Dispatch up to 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, tsconfig.json, Cargo.toml, pyproject.toml, go.mod, etc.).
- Based on detected languages, determine which subagents apply (see language applicability below).
- 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.
Subagents
Each subagent is spawned using the Agent tool with mode: "auto". Give each subagent a clear prompt including: the task description below, the project root path, detected language(s), and a reminder to commit its own changes with the prefix cleanup(<task>):.
| # | Subagent | Applies to | Description |
|---|---|---|---|
| 1 | Deduplication | All languages | Find duplicated logic across the codebase. Apply DRY only where it reduces complexity; do not abstract three similar lines into a helper. |
| 2 | Type consolidation | JS/TS, Java, C#, Go (typed languages) | Find all type/interface definitions. Merge duplicates into shared locations. Update imports. |
| 3 | Dead code removal | All languages | JS/TS: use knip to find unused exports, files, and dependencies. Other languages: use grep-based analysis to find unreferenced exports and files. Verify each removal with grep across the full repo before deleting. |
| 4 | Circular dependency resolution | All languages | JS/TS: use madge --circular to identify cycles. Other languages: trace import graphs with grep/find. Refactor to break cycles; do not paper over with lazy imports. |
| 5 | Weak type elimination | JS/TS (primary), Python (type hints) | Replace any, unknown (TS) or missing type annotations (Python) with concrete types. Research correct types from call sites and upstream packages. No casts to suppress errors. |
| 6 | Defensive code pruning | All languages | Remove try/catch blocks that hide errors or return silent fallbacks. Keep only those guarding genuinely untrusted input (user input, external APIs, filesystem boundaries). |
| 7 | Deprecated/legacy removal | All languages | Find code marked deprecated, behind always-on feature flags, or labeled legacy. Remove the dead path; keep one canonical implementation. |
| 8 | AI slop removal | All languages | 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. |
Skip subagents that don't apply to the detected language. For a Python-only project, skip subagent 4 (madge) unless circular imports are suspected, and scope subagent 2 to dataclass/TypedDict consolidation.
Execution order
Run in two phases because dead-code removal and circular-dep work produce better results after dedup and type consolidation have landed.
Phase 1 (parallel): 1, 2, 5, 6, 7, 8 Phase 2 (parallel, after Phase 1 commits): 3, 4
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. - For repositories over ~200 files, consider scoping to the most active packages/directories rather than sweeping everything. Use
git log --format='%H' --since='3 months ago' -- <path>to prioritize high-churn areas.
Reporting
After all subagents complete, produce a single summary with:
- Per-subagent: files changed, lines added/removed, key findings.
- Subagents skipped (with reason — language not applicable).
- 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.