Dispatch 8 subagents to audit and clean the codebase. Each subagent must: (1) research its domain, (2) write a critical assessment with findings, (3) implement all high-confidence fixes.
Pre-flight
- Detect project language(s) from config files (package.json, Cargo.toml, pyproject.toml, go.mod, etc.) and tailor subagent instructions accordingly.
- Identify the test runner and verify tests pass before starting. Abort if tests are already broken.
- Create a working branch:
cleanup/<YYYY-MM-DD>. - Exclude generated files,
node_modules,dist,vendor, lock files, and any paths listed in.gitignore.
Execution order
Some subagents have dependencies. Run in two phases:
Phase 1 (parallel): 1, 2, 5, 6, 7, 8 Phase 2 (parallel, after Phase 1 commits): 3, 4
Dead-code removal (3) runs after dedup (1) and type consolidation (2) to avoid deleting code that is about to be reused. Circular-dep work (4) benefits from type consolidation first.
Subagents
- Deduplication — Find duplicated logic across the codebase. Apply DRY only where it reduces complexity; do not abstract three similar lines into a helper.
- Type consolidation — Find all type definitions. Merge duplicates into shared locations. Update imports.
- Dead code removal — Use
knip(or language equivalent) to find unused exports, files, and dependencies. Verify each removal with grep across the full repo before deleting. - Circular dependency resolution — Use
madge --circular(or equivalent) to identify cycles. Refactor to break them; do not paper over with lazy imports. - Weak type elimination — Replace
any,unknown, and language equivalents with concrete types. Research correct types from call sites and upstream packages. No casts to suppress errors. - Defensive code pruning — Remove try/catch blocks that hide errors or return silent fallbacks. Keep only those guarding genuinely untrusted input (user input, external APIs, filesystem boundaries).
- Deprecated/legacy removal — Find code marked deprecated, behind always-on feature flags, or labeled legacy. Remove the dead path; keep one canonical implementation.
- AI slop removal — Strip stubs, placeholder code, in-motion-work comments ("now replacing X with Y"), and over-commenting. Replace only where a new contributor genuinely needs the context. Be concise.
Constraints
- Each subagent commits independently with a descriptive message (
cleanup(<task>): <summary>). - Run the test suite after each subagent commits. If tests fail, revert that subagent's commit and include the failure in the final report — do not auto-fix.
- Subagents that touch the same file must serialize: later subagents rebase on earlier commits.
- No subagent may skip hooks (
--no-verify) or force-push.
Reporting
After all subagents complete, produce a single summary with:
- Per-subagent: files changed, lines added/removed, key findings.
- Any subagents that failed or were reverted, with the failing test output.
- Remaining issues flagged but not auto-fixed (low confidence) — list for human review.