| name | clean |
| description | Scope-locked codebase cleanup with 8 focused assessment lanes — deduplication, type consolidation, dead code removal, circular dependencies, type strengthening, defensive code removal, legacy cleanup, and AI slop removal. Use when the user wants to clean up the codebase or improve code quality at scale. |
| argument-hint | [--dry-run] [--scope package-name] [--agents 1,3,5] [--no-codex] |
| context | fork |
| effort | very-high |
Clean Skill
Codebase cleanup in two explicit phases: 8 focused lanes assess the code read-only, then the human locks a numbered fix scope before any implementation begins. Unlike /audit and /principles, /clean may transform code, but only inside that approved scope.
References: CLAUDE.md and .claude/context/*.md for invariants. /audit for prior findings.
Activation
| Trigger | Action |
|---|
/clean | Full assessment -> numbered scope lock -> approved implementation -> Codex final review |
/clean --dry-run | Research + assessment only; stop before scope lock or implementation |
/clean --scope shared | Limit all agents (and Codex review) to one package |
/clean --agents 1,3,5 | Run only specific agents by number; Codex review still runs |
/clean --no-codex | Skip the Codex final review pass |
Pre-Flight
Before assessment:
- Inspect repository state:
git status --short --branch. If unrelated or unknown changes overlap the requested scope, stop and surface them; do not format, stash, branch, or edit around them.
- Run a non-mutating baseline:
bun format:check, bun lint, and bun run test — capture pass/fail counts without rewriting files.
- Load prior accepted findings when requested: query current Linear issues in the approved scope; do not treat old repo-local reports as a registry.
- Stay on the current branch: never create or switch branches during pre-flight.
- Record the assessment base:
CHECKPOINT_SHA="$(git rev-parse HEAD)".
No source, report, branch, worktree, lockfile, or plan mutation is allowed before the human approves the numbered scope lock.
The 8 Agents
Dispatch assessment lanes in parallel only when the user or active agent policy permits subagents. Assessment lanes are read-only and return findings to the lead; they do not create worktrees or report files. After scope lock, implement sequentially on the current branch by default. Isolated worktrees and their branches require separate, explicit human approval; when approved, base them on the checkpoint SHA, never main, origin/main, or the tool's default branch.
Worktree Base Invariant
When worktrees were explicitly approved, verify each implementation worktree base from the orchestrator:
test "$(git -C "$WORKTREE" merge-base "$CHECKPOINT_SHA" HEAD)" = "$CHECKPOINT_SHA"
If any agent worktree fails this check, stop and re-dispatch that agent from the checkpoint. Do not continue a stale-base run by default.
Salvage is allowed only when the human explicitly approves a stale-base salvage after seeing:
- checkpoint SHA and stale worktree SHA
- commit gap (
git rev-list --count "$STALE_BASE..$CHECKPOINT_SHA")
- affected file list
- planned validation and conflict audit steps
When stale-base salvage is approved, record every conflict and every dropped/ported
agent insight in the conversation or, for plan-backed work, in the existing feature
hub's reports/merge-audit.md.
Agent Protocol (all agents)
Phase 1: RESEARCH — Scan the approved repository scope for instances of the problem
Phase 2: ASSESS — Return findings categorized as HIGH / MEDIUM / LOW confidence.
The lead deduplicates them into a numbered scope-lock proposal.
SCOPE LOCK — Wait for the human to approve exact finding numbers.
Phase 3: IMPLEMENT — Fix only approved findings. Do not pull in adjacent cleanup.
Assessment results stay in the conversation until scope lock. After approval, each
implementation lane returns its approved finding IDs and provenance to the lead. For
plan-backed work, the lead may add a compact result to the existing feature hub's
handoff or report; do not create a generic cleanup-report directory. In --dry-run
mode, lanes stop after Phase 2 and do not write files.
Every report must include a provenance block:
## Provenance
- execution_mode: current-branch | authorized-worktree
- checkpoint_sha:
- implementation_base_sha:
- implementation_head_sha:
- merge_base_with_checkpoint: (authorized worktree only)
- stale_base: yes/no/not-applicable
Agent missions are short by design — the agents are strong models; give them the lane and the repo-specific rules, not a tutorial. Every agent: respect CLAUDE.md + .claude/context/*.md invariants, run bun run test in affected packages after implementing.
Agent 1: Deduplication & DRY
Find and consolidate real duplication (components, logic, utilities, near-identical types). Rules: consolidate only at 3+ duplicates (or 2 nearly identical); consolidated hooks go in @green-goods/shared; new shared APIs must be added to a declared root or subpath export in packages/shared/package.json#exports; no premature abstractions; preserve existing tests.
Agent 2: Type Consolidation
Consolidate domain types into shared. Rules: domain types (Garden, Work, Action, Address) MUST live in @green-goods/shared; Address (not string) for Ethereum addresses; update all import sites when moving; confirm the intended path is declared in packages/shared/package.json#exports.
Agent 3: Dead Code Removal (knip)
Remove unused files/exports/types/deps found by bunx knip --reporter compact. Rules: trust knip over grep (~80% grep false-positive rate here); verify each finding against dynamic imports, test-only usage, config references, and Envio runtime-imported handlers; never touch packages/contracts/lib/ (Foundry submodules) or packages/indexer/generated/; remove the import AND the file/export together.
Agent 4: Circular Dependency Resolution (madge)
Zero out cycles from npx madge --circular --extensions ts,tsx packages/. Resolution preference: import type → extract shared interface → dependency inversion → merge modules. Rules: respect build order contracts -> shared -> indexer -> client/admin/agent; never create upward dependencies; hooks stay in shared; bun build must pass after.
Agent 5: Type Strengthening
Replace weak types (any, escape-hatch unknown, as assertions, @ts-ignore, compiler-silencing !) with real types researched from call sites and library defs (wagmi/viem/EAS). Rules: unknown is CORRECT at system boundaries (user input, external APIs, JSON.parse); any acceptable in complex test mocks; wrap weak library types locally instead of spreading any; no new tsc errors.
Agent 6: Defensive Code Removal
Remove error handling that hides failures (empty catches, log-only catches, catch-and-return-default, fake-success paths). KEEP: parseContractError() + USER_FRIENDLY_ERRORS, createMutationErrorHandler() in shared mutation hooks, error boundaries with user feedback, genuine boundary input handling. Rules: never swallow errors in mutation/transaction paths; logger from shared, not console.log.
Agent 7: Legacy & Deprecated Code
Remove obsolete paths: @deprecated tags, stale TODO/FIXME/HACK, dead feature flags, commented-out blocks, migration shims, long-past version gates. Rules: git blame first — understand why it was added; if a TODO references a Linear issue, check whether it's still open; never remove offline-first fallback paths (job queue, IndexedDB persistence, service worker are intentional complexity).
Agent 8: AI Slop & Comment Cleanup
Remove AI residue: what-comments and code-history comments (keep WHY comments), stub implementations, verbose no-information JSDoc, leftover console.log debugging, dead imports, over-engineered single-use wrappers. Edited comments are written for the next developer, not the reviewer. Judge over-engineering against values.md § Implementation Quality Contract rather than restating principles.
Orchestration
digraph clean_flow {
rankdir=TB;
preflight [label="Non-mutating pre-flight\n(state, baseline, checkpoint SHA)" shape=box];
dispatch [label="Run assessment lanes\n(read-only)" shape=box];
reports [label="Present numbered findings\n(no file writes)" shape=box];
scope [label="Human scope lock\n(approved finding IDs)" shape=diamond];
implement [label="Implement approved findings\n(current branch by default)" shape=box];
merge [label="Merge approved worktrees\n(if separately authorized)" shape=box];
validate [label="Validate\nShip Gate\n(validation-pipeline.md)" shape=box];
codex [label="Codex final review\n(regression + miss hunt,\nparallel lanes)" shape=box];
triage [label="Triage Codex findings\n(auto-revert regressions,\nuser-confirm misses)" shape=box];
summary [label="Summary to user\n(changes, findings, skipped,\nCodex callouts)" shape=box];
preflight -> dispatch;
dispatch -> reports;
reports -> scope [label="--dry-run stops here"];
scope -> implement [label="approved IDs"];
implement -> merge;
merge -> validate;
validate -> codex [label="--no-codex skips"];
codex -> triage;
triage -> summary;
}
After assessment:
- Deduplicate findings and validate each against current source.
- Present numbered findings with evidence, risk, smallest fix, and explicit out-of-scope boundaries.
- Wait for scope lock. The human must approve exact finding IDs before implementation.
- Stop in dry-run mode without writing reports or changing repository state.
After approved implementation:
- Collect implementation results from the lanes/session, each tied to approved finding IDs.
- Verify provenance when worktrees were authorized — each report must show
stale_base: no; if not, stop for re-dispatch or explicit stale-base salvage approval.
- Merge authorized worktrees only without blanket "take ours" / "take theirs" conflict resolution; skip this step for current-branch execution.
- Write merge audit if any conflict, stale-base salvage, dropped stash, or no-op cherry-pick occurred.
- Run the non-mutating Review Readiness Gate from
.claude/context/validation-pipeline.md. Run the mutating Ship Gate only when the user separately requests ship, PR, commit, merge, or release readiness and its pre-flight passes.
- Run residue checks:
git diff --check, targeted removed-symbol scans, package TypeScript checks, and locally installed knip for unused export/dependency drift.
- Revert only the specific approved change if it caused a regression; do not fix unrelated failures.
- Run the Codex final review unless
--no-codex; never auto-apply miss-hunt findings.
- Summarize files changed, approved finding IDs, validation, skipped findings, and merge-audit or review callouts.
Merge Audit Format
Use this format in the conversation, or in the existing feature hub's
reports/merge-audit.md, whenever a merge is not a clean
fast-forward/cherry-pick with no conflicts:
# Clean Merge Audit
## Base Provenance
- checkpoint_sha:
- expected_base:
- stale_agent_worktrees:
## Conflict Resolutions
| Agent | File | Agent intent | Resolution | Develop already covered it? | Follow-up needed |
|-------|------|--------------|------------|-----------------------------|------------------|
## Auto-Merge / Stash Events
| Event | Files | Action | Residual risk |
|-------|-------|--------|---------------|
## Validation
- command:
- result:
For each conflict, inspect the agent diff before resolving. "Ours" is valid only when the checkpoint/develop side already contains the same improvement or the agent hunk is obsolete. If it drops a real cleanup, either port the cleanup immediately or record it as a follow-up in the audit.
Commit Hygiene
Use source-change subjects only when source changes landed. A report-only or no-op
lane is summarized to the user and does not earn a repository commit.
Avoid --no-verify. If a hook is broken or irrelevant for a docs-only commit, run the equivalent manual checks first (git diff --check at minimum), record the reason in the commit body, and prefer a normal verified commit whenever possible.
Codex Final Review
A second-opinion pass after Claude's 8 agents merge and validation passes. Codex sees the merged result, not partial agent worktrees, so it can catch regressions and cross-cutting misses that no single agent's lane covered. Skipped in --dry-run and --no-codex.
Why Codex (not a 9th Claude agent)
- Codex's structural-review and "promptability" lens is independently validated for cleanup-style work (taxonomy, dead code, naming, file/route alignment).
- Two reviewers with different model biases catch different misses; the merged diff is the natural handoff point.
- Codex is weak at visual/UX judgment — that's why it's the reviewer, not an implementer of new style.
Lanes
Both lanes dispatch via .claude/scripts/dispatch-codex-lane.sh against the approved implementation head, with --phase regression and --phase gap. Use worktree-backed lanes only when branch/worktree creation was explicitly approved.
Lane R — Regression hunt (diff-scoped):
You are reviewing the merged diff between $BASE_BRANCH and the approved implementation
head. Cleanup implementation just modified this codebase. Your job is to find any change
that alters runtime behavior, NOT to find new cleanup opportunities.
Scan every hunk and classify:
REGRESSION-HIGH — Behavior change disguised as a refactor. Examples: removed catch block
that was actually load-bearing, changed default arg, narrowed a type
that callers relied on, dead-code removal that wasn't actually dead.
REGRESSION-MED — Plausible behavior change but unclear; needs human eye.
REGRESSION-LOW — Likely safe but worth flagging (e.g., reordered arguments, renamed
public symbol without checking external consumers).
SAFE — Pure refactor / dedup / type tightening with equivalent semantics.
For each non-SAFE finding, output: file:line, the agent's likely intent, why it might
break, and the smallest revert (specific lines).
Honor these invariants from CLAUDE.md — flag if any agent broke them:
- Hook boundary (all hooks live in @green-goods/shared)
- Shared imports use only declared package export paths; no `shared/src` internals
- Address type for Ethereum addresses
- parseContractError() + USER_FRIENDLY_ERRORS for contract errors
- Offline-first fallbacks are intentional, not legacy
- Single root .env (no per-package .env)
Lane G — Miss hunt (codebase-wide):
The 8 cleanup lanes have just finished. Their integrated summaries are included in
this review context. Your job is to find cleanup opportunities they MISSED,
especially issues that don't fit neatly into a single lane.
Read each lane summary first to understand what was already covered. Then scan for:
CROSS-CUTTING — Issues spanning two or more agent domains (e.g., a duplicated type that
is also dead, a defensive catch around legacy code).
TAXONOMY — Inconsistent naming, ambiguous file/folder placement, types/components
whose names lie about what they do. Use the "promptability" lens: would
an AI agent looking at this codebase confidently know where to put a new
feature?
PLACEMENT — Files in the wrong package (e.g., a hook in client/ that should be in
shared/, a domain type in admin/ that should be in shared/).
SEAM DRIFT — Public APIs that have grown asymmetric (one helper does X+Y, its sibling
only does X), declared exports that don't match what consumers import.
DOC/CODE DRIFT — Comments, JSDoc, or .claude/context/*.md that contradict the current code.
For each finding, output: location, category, concrete fix, and confidence
(HIGH/MED/LOW). Do NOT modify files. Output is a report only.
Outputs
Each lane writes its codex-result.md (per .codex/output-schema.json) inside its
temporary worktree. Read those results into the session after dispatch; do not copy
them into the repository. Remove the temporary worktrees after the result has been
integrated, unless the user asked to preserve them for debugging.
Linear follow-up routing
All routing (team, .plans/source:plans, projects, labels, privacy, prompt-before-create)
follows the shared core: .claude/context/linear-routing-rules.md.
Cleanup-specific delta: accepted findings are tracked in Linear after user approval;
Git/PR history is the implementation record. Do not create a parallel cleanup registry
under .plans/.
Triage rules (Claude reads, decides, acts)
- REGRESSION-HIGH → revert only the cited approved lines at the implementation head, then re-run validation. If validation now fails, escalate to user.
- REGRESSION-MED / -LOW → list in summary, do not auto-revert.
- Miss-hunt findings (any confidence) → never auto-apply. Surface in summary, let user pick which to feed into a follow-up
/clean --agents N or a manual edit.
- If Codex flags an "agent removed dead code that was actually used" and the test suite still passes, trust the test suite first; surface the finding as REGRESSION-LOW for human review.
When to skip
Use --no-codex when:
- Codex binary is unavailable (no
/Applications/Codex.app/... or CODEX env)
- Network/auth is broken on the codex side
- The user already plans to run a full
/review on the branch
- Time pressure (Codex review adds ~3-5 min sequential after the parallel agent phase)
Post-Clean Validation
git diff --check
bun format:check && bun lint
bun run test
bun build
madge --circular --extensions ts,tsx packages/
bunx knip --reporter compact
Required checks must pass or be explicitly documented as a pre-existing failure before reporting completion. Optional tooling that is not installed is UNAVAILABLE, not permission to install it. If an approved change causes a failure, fix or revert that change. Codex regression-revert (above) runs before this final validation, so the post-clean numbers reflect the corrected state.
For symbol-removal agents (dead code, legacy, type consolidation), add targeted scans for every removed public symbol across packages/, docs/, .plans/, and active agent guidance. Source references must be fixed; docs references must either be updated or recorded as intentionally historical.
Safety Rules
- Current branch safety — never create or switch branches unless the human explicitly requests it
- Scope lock — no source/report/worktree mutation before exact finding IDs are approved
- Checkpoint base — every agent worktree must use the checkpoint SHA as its merge base
- Worktree authorization — use isolated worktrees only after explicit human approval; otherwise implement sequentially on the current branch
- No stale-base default — re-dispatch stale worktrees unless the human explicitly approves stale-base salvage
- Test after implement — each agent runs
bun run test in affected packages
- No cross-agent dependencies — agents don't depend on each other's output
- HIGH-confidence only — agents only implement findings they're confident about
- Preserve invariants — all CLAUDE.md rules apply (hook boundary, declared public imports, Address types, single .env)
- Conflict audit — every conflict resolution records agent intent, chosen side, and whether any cleanup insight was dropped
- Never remove offline-first code — the job queue, IndexedDB persistence, and service worker are intentional complexity
- Codex reviews the integrated result — dispatch only after implementation + validation, so Codex sees the same code the user will ship
- Codex is read-only by default — only auto-applies regression-reverts (HIGH); miss-hunt findings always go to the user
Scope Limiting
With --scope, all agents restrict their scan to the named package:
/clean --scope shared # Only clean packages/shared
/clean --scope client # Only clean packages/client
With --agents, only specified agents run:
/clean --agents 3,4,5 # Dead code + circular deps + type strengthening
/clean --agents 8 # Just AI slop cleanup
Combine both: /clean --scope shared --agents 1,2,5
Anti-Patterns
| Don't | Why |
|---|
| Create or switch branches before explicit approval | Violates shared-tree safety and mutates state before scope lock |
| Write assessment reports before scope lock | Read-only assessment must not mutate the repository |
| Install missing audit tools implicitly | Supply-chain changes require explicit approval |
| Let agent worktrees branch from main/origin/main | Stale diffs can silently drop or obsolete cleanup on develop |
| Resolve conflicts with blanket "take ours" | Can discard the agent's real cleanup insight without audit |
Skip bun run test validation | Silent regressions |
Skip git diff --check after docs/report commits | Plan-file whitespace and conflict-marker residue can bypass source validation |
| Remove offline-first fallbacks | They're intentional, not legacy |
| Consolidate 2 slightly-different things | Premature abstraction; need 3+ duplicates |
| Use grep to find dead code | ~80% false-positive rate; use knip |
| Remove contracts/lib/ files | Foundry git submodules |
| Remove indexer/generated/ files | Envio generated code |
| Remove catch blocks in contract interactions | They use parseContractError() intentionally |
| Strengthen types in test mocks to exact shapes | Test mocks are intentionally partial |
| Run all 8 agents on a tiny change | Use --agents to pick relevant ones |
| Use source-change commit subjects for report-only/no-op merges | Misleads reviewers about what actually landed |
| Auto-apply Codex miss-hunt findings | Need human judgment; surface them, don't merge them |
| Run Codex review before merge/validation | Codex needs to see the merged result, not partial worktrees |
| Use Codex review to vet visual/UX cleanup | Codex is weak at visual judgment — that's a Claude job |
Related Skills
audit — Find problems (read-only). Use when you want a report, not fixes.review — Review specific changes. Use when reviewing a PR or recent commits.plan (teams.md § Part 11) — canonical reference for the dispatch-codex-lane.sh pattern that the Codex final review reuses.
Recommended flow: clean assessment -> approve numbered finding IDs -> targeted implementation -> Codex final review -> review the changes.
