| name | spring-cleaning |
| description | Internal crew primitive, dispatched by /crew:run — do not invoke directly or select it for a user request; route cleanup/dead-code requests to /crew:run, which decides the full workflow. (Function: propose bounded, evidence-backed cleanups validated against the test suite; never touches protected paths, never merges.) |
spring-cleaning
Internal crew primitive — dispatched by /crew:run. You are running because the
orchestrator selected this as one step of a larger workflow; carry out the work below. This
skill is not meant to be invoked on its own — user requests go to /crew:run.
You perform bounded, evidence-backed cleanup. You never make sweeping rewrites — each
cleanup is small, justified, and validated. Your ceiling is a review-ready PR — never
merge.
Optional argument is the scope: dead-code, unused-deps, stale-todos, orphaned, or
all (default: ask the user, or dead-code if unattended).
0. Load config
python3 "${CLAUDE_PLUGIN_ROOT}/lib/load_config.py"
Obey guardrails.protected_paths (never touch these), commands.* (to validate), and
labels.{agent_pr,cleanup}.
Then read ${CLAUDE_PLUGIN_ROOT}/reference/work-model.md and resolve the mode before any
gh call. Detection and validation are identical in both modes; only the output differs
(step 4).
1. Detect (read-only first)
Pick detectors by language — use what the repo already has before installing anything:
- dead code / unused exports:
knip or ts-prune (JS/TS), ruff check --select F401
vulture (Python), go vet / deadcode (Go), cargo +nightly udeps (Rust).
- unused dependencies:
depcheck (JS/TS), comparing manifest vs imports otherwise.
- stale TODOs:
grep -rn "TODO\|FIXME\|XXX" and cross-reference with git blame age.
- orphaned files: files with no inbound references / not in any build graph.
Gather evidence for each candidate (e.g. "no inbound references", "import removed in
PR #X"). Do not act on anything you can't justify.
2. Propose a bounded set
For the chosen scope, select the high-confidence, evidence-backed changes. Exclude
anything matching protected_paths. When unsure, leave it and note it in the PR description
as a candidate for human judgment.
If the cleanup is huge. If detection turns up far more justified cleanup than fits a single
bounded PR — it naturally breaks down module by module or across many categories — don't
silently truncate to the cap and don't sprawl. Add a decomposition plan to your report back
to the orchestrator: a numbered list of independent units (e.g. one per module or category),
each with description, target (the files/module it owns), primitive: spring-cleaning, and
any depends_on. Flag the report scale-out-recommended. The orchestrator decides whether
to fan it out, always confirming with the user first (see
${CLAUDE_PLUGIN_ROOT}/reference/scale-out.md for the unit shape). You only recommend — you
never spawn anything.
3. Validate
Apply the removals on a branch, then run commands.install and commands.test (and
lint/typecheck if present). If anything breaks, revert that item — a cleanup that
breaks the build is not a cleanup.
4. One change set per category
Work on branch crew/cleanup-<scope> (local mode: in an isolated worktree per
local.isolation, work-model.md §4). List each removal with its evidence and the test
result.
- GitHub mode: open a PR labeled
labels.agent_pr + labels.cleanup, titled
chore(cleanup): <scope>, with that list in the body.
- Local mode: commit to the branch (no push, no PR); record the removal list + evidence
in
<ledger.dir>/cleanup-<scope>/decision.md.
Never merge.
Constraints
- Never touch
protected_paths.
- Evidence required for every change; scoped to high-confidence removals.
- Validated — tests must pass.
- Never merge.
