| name | vibe-types:clean |
| description | Apply vibe-types catalog and use-case knowledge to refactor source files in place. Use when the user invokes /vibe-clean (or asks you to "vibe-clean" a file, directory, or branch) to systematically improve code using the techniques in the loaded vibe-types skill. Does NOT change observable behavior, public APIs, or test assertions.
|
| version | 0.1.0 |
vibe-types:clean — Apply vibe-types knowledge to source files
Skill root: ${CLAUDE_PLUGIN_ROOT}/skills
Refactor source files by applying every relevant technique from the vibe-types
catalog and use-case library. Work through (knowledge-file × source-file) pairs
sequentially, editing files in place with your native tools.
Invocation
/vibe-clean --skill <lang> (--file <path> | --dir <path> | --branch <name>) [OPTIONS]
Exactly one of --file, --dir, or --branch must be given.
Either --skill or --skill-dir must be given.
Arguments
| Flag | Default | Description |
|---|
--skill <lang> | — | Language: typescript, python, rust, scala3, lean, haskell, ocaml, java, agda, tlaplus |
--skill-dir <path> | — | Override: explicit path to skill directory |
--file <path> | — | Single source file |
--dir <path> | — | All matching files in directory (recursive) |
--branch <name> | — | Files changed on this branch vs. merge-base |
--build <cmd> | none | Shell command to verify after each edit |
--max-retries N | 3 | Fix attempts per build failure |
--commit | false | Commit after each (knowledge × source) pair |
--only T01,UC03,... | all | Process only these knowledge IDs |
--dry-run | false | Print plan without editing |
--consolidate | false | Final coherence pass after all techniques |
--principles <file> | built-in | Custom principles file for consolidation |
--base-branch <name> | main | Base for --branch diff |
--progress <file> | .vibe-clean-progress | Progress tracking file |
Language → file extensions
typescript → .ts .tsx .mts .cts
python → .py
rust → .rs
scala3 → .scala .sc
lean → .lean
haskell → .hs
ocaml → .ml .mli
java → .java
agda → .agda .lagda .lagda.md .lagda.tex
tlaplus → .tla
Step 1 — Resolve skill directory
SKILL_DIR = ${CLAUDE_PLUGIN_ROOT}/skills/<lang>/ # --skill given
SKILL_DIR = <path> # --skill-dir given
Verify SKILL_DIR exists. If not, list the directories under
${CLAUDE_PLUGIN_ROOT}/skills/ and stop.
Step 2 — Collect knowledge files
- Find all
.md files under SKILL_DIR/catalog/ and SKILL_DIR/usecases/
(maxdepth 1 each), sorted by basename.
- Skip
00-overview.md.
- If
--only is given, keep only files whose basename starts with one of the
provided IDs — e.g. T01 matches T01-algebraic-data-types.md;
UC03 matches UC03-exhaustiveness.md.
- For each file extract:
kid = leading segment before first -; ktitle =
first # heading line.
Step 3 — Collect source files
--file: verify the single path exists and matches the language extension.
--dir: run Bash find from the resolved directory, pruning these names:
node_modules dist build target .git __pycache__ .next out coverage .cache .tox .eggs .mypy_cache. Keep only regular files matching the language
extensions. Sort output.
--branch: run git diff --name-only <merge-base> <branch> (where
merge-base = git merge-base <branch> <base-branch>), filter paths to language
extensions, verify each file exists on disk.
Step 4 — Pre-flight checks
--commit or --branch requires a git repository.- Unless
--dry-run: verify the target git repo has no uncommitted changes
(excluding the progress file). If dirty, stop and ask the user to commit or
stash first.
- Record
run_start_head = git rev-parse HEAD for prior-diff tracking.
Step 5 — Dry run
If --dry-run: print every planned (knowledge-file, source-file) pair, the
total count, and stop. Make no edits.
Step 6 — Main loop
Read the progress file at the --progress path. Each line is either
done <kfile> <sfile> or failed <kfile>.
Outer loop — knowledge files (sorted order):
- If
failed <kfile> is in the progress file: log "skipping (previously
failed)" and continue to the next knowledge file.
Inner loop — source files (sorted order):
- If
done <kfile> <sfile> is in the progress file: log "skip" and continue.
Apply step
- Compute
prior_diff — changes already made to this source file during the
current run:
--commit mode: git diff <run_start_head>..HEAD -- <sfile>- Otherwise:
git diff HEAD -- <sfile>
- Read the knowledge file.
- Read the source file.
- Edit the source file to apply techniques from the knowledge document:
- Only make changes that the knowledge genuinely warrants.
- Do NOT change observable behavior, public APIs, or test assertions.
- Prefer minimal, targeted edits over wholesale rewrites.
- If
prior_diff is non-empty, treat those changes as settled — do not
revert or contradict them.
- If nothing in the knowledge file applies, leave the file untouched.
Build step (if --build)
Run the build command via Bash. If it fails:
for attempt in 1 .. max-retries:
read the build errors
edit <sfile> to fix them (preserve the intent of prior changes)
re-run the build
if build passes → break
If the build still fails after max-retries:
- Revert the file:
git restore --source=HEAD --worktree -- <sfile>
- Append
failed <kfile> to the progress file.
- Print an error message with the progress file path.
- Stop the run. The user can fix the underlying issue and re-run to resume.
Record
Append done <kfile> <sfile> to the progress file.
Commit step (if --commit)
Stage only the source file for this pair (do not use git add -A — --build
may produce artifacts, lockfile drift, or generated files that must stay out
of the commit; the progress file must also stay unstaged):
git add -- <sfile>
If there are staged changes, commit:
cleanup(<kid>): <ktitle>
Knowledge: <github-blob-url-to-kfile> # if determinable
Source: <relative-path-to-sfile>
Step 7 — Consolidation pass (if --consolidate)
For each source file, compute its full diff across the run. If empty (file
unchanged), skip.
- Read the principles:
--principles <file> if given; otherwise use the
built-in text below.
- Read the source file.
- Edit for overall coherence:
- Resolve contradictions or redundancies introduced by the individual passes.
- Align the design with the principles.
- Ensure the file reads as if written with a single coherent intent.
- Do NOT change observable behavior, public APIs, or test assertions.
- If the file is already consistent, leave it untouched.
- If
--build: verify build; retry up to --max-retries; if still failing,
revert and skip (non-fatal — continue to the next file).
- If
--commit: commit as consolidate: <rel-path>.
Built-in consolidation principles
S — Single Responsibility: each type, function, and module has one clear reason to change.
O — Open/Closed: extend through new types or functions; avoid modifying stable abstractions.
L — Liskov Substitution: subtypes must honour the contracts of their interfaces.
I — Interface Segregation: keep interfaces narrow; callers depend only on what they use.
D — Dependency Inversion: high-level modules depend on abstractions, not concrete implementations.
DRY (Don't Repeat Yourself): extract shared logic and types rather than duplicating them.
KISS (Keep It Simple): prefer the simplest correct solution; avoid unnecessary abstraction.
Cohesion: group related types and functions; a module should have a single, clear purpose.
Step 8 — Summary
Print:
Knowledge files: N
Source files targeted: N
Pairs attempted: N
Pairs skipped (resuming): N
Build errors fixed: N
Files consolidated: N (only if --consolidate)
Commits created: N (only if --commit)
Core rules (always apply)
- Never change observable behavior, public APIs, or test assertions.
- Prefer minimal, targeted edits over wholesale rewrites.
- When unsure whether a technique applies, leave the file unchanged.
- Always check the progress file before starting any pair — never redo
completed work.
- Keep each knowledge file's content in working context only for the pairs
that use it; do not accumulate all knowledge files at once.
