tidy-project

Audit the repo's project structure — layout, placement, and naming of files and directories, plus config, dependency, and build hygiene — and produce one consolidated, batched execution plan. Run to completion without user interaction: no pauses between phases, no confirmation prompts, no intermediate reports. The plan file is the deliverable; the state file is for your own resumability, not human review. Mirror the four phases in the host's todo tool.

Non-negotiables (read first)

• Read-only against source. Create nothing outside the state file and the final plan path.
• Behavior-preserving proposals only. Every proposed change must preserve functionality.
• Preserve infrastructure. Languages, frameworks, hosting, databases, and runtime environments identified in Phase 1 are held fixed for the whole audit.
• No dependency swaps unless the dependency is demonstrably unused or replaceable by ~10 lines of stdlib code.
• No rewrites — only consolidations, deletions, flattenings, renames, and extractions (literal → environment lookup).
• No git history. Evidence is the tracked-file list (git ls-files), manifests, and the file tree — never commit dates or churn. If a finding's only evidence would be "untouched for N months," drop it.
• Falsifiability gate. Classify every finding FALSIFIABLE (cites a path, tracked-file entry, or string that Grep or git ls-files can confirm) or OPINION (a structural judgment). Verify every falsifiable citation with a fresh Grep or git ls-files call before it enters the draft; no match means hallucinated citation — drop it.
• Framework-required structure is off-limits. Never flag files or dirs a Phase-1-identified framework requires (src/pages/, app/, settings.py, .github/workflows/, Dockerfile, package.json, tsconfig.json, Makefile, and kin) as findings.

Scope boundary

Every tp-* category (tp-01..tp-11, defined in references/categories-quick-ref.md) is decidable from the file tree, git ls-files, manifests, and targeted greps. This skill does NOT own:

• Code semantics — dead code, cross-file logic duplication, premature abstraction, coupling, import cycles. Never read code for meaning.
• Single-file concerns — identifier naming, function length, magic numbers, in-file duplication. A finding whose evidence sits entirely inside one file is out of scope.
• Test internals — test files are audited at the structural level only (existence, placement, organization, vestigial scaffolding); logic inside test functions is out of scope.

Excluded paths

Skip traversing: any dot-directory (.git/, .venv/, .next/, .cache/, .turbo/, .agents/, .claude/, .vscode/, .idea/, .github/, and kin), node_modules/, vendor/, dist/, build/, __pycache__/, target/, coverage/, generated code, binary assets.

Nuance: skipping traversal does not mean skipping evidence — tp-02/tp-03 may still flag the tracked presence of a committed dist/ or vendored library via git ls-files; that check is cheap and in scope. Lockfiles are never read, but their presence or absence next to each manifest is the tp-02 signal.

State file

.agents/local/state/tidy-project-YYYY-MM-DD.md (create the directory if missing). If today's file exists and is complete, append -2, -3. On start: glob .agents/local/state/tidy-project-*.md; if the newest has unchecked items, resume against it; otherwise create a new file. Delete the file to force a fresh run. Format — a markdown checklist grouped by phase, one item per area, plus the findings draft appended below it:

# Tidy Project — 2026-07-17
- [ ] Phase 1 — inventory
- [ ] src/
- [ ] docs (drift)
- [ ] Phase 3 — adversarial review
- [ ] Phase 4 — plan written

You alone write the state file. Workers return findings in their reply; they never touch it.

Phase 1 — Inventory (mechanical, no subagents)

Build the inventory inline — do not dispatch subagents for this:

1. Stack. Glob for manifests (package.json, pyproject.toml, requirements.txt, go.mod, Cargo.toml, composer.json, Gemfile) and read them for frameworks. Record the framework-required (off-limits) paths, entry points, and config surface.
2. Tree and areas. git ls-files plus a two-level tree walk. List top-level areas with source-file counts; note any folder whose purpose is unclear.
3. Hygiene greps — these checks are grep-shaped by nature; run them now and hand hits to the matching area's worker as candidates: git ls-files '*.env' | grep -v example (tracked env files), lockfile adjacent to each manifest, git ls-files dist build out and git ls-files '*.min.*' (committed build artifacts), git ls-files '*.log' (log artifacts), find . -name .git -mindepth 2 -not -path './.git/*' (nested codebase).

Write the inventory summary and the area checklist to the state file, then proceed directly to Phase 2 — do not stop or summarize.

Phase 2 — Area analysis (parallel)

Dispatch workers using the Area Analyst prompt in references/adversarial-review-prompts.md — one worker per top-level area, plus one docs worker assigned the docs area (README, docs/, agent instruction files) that also loads references/docs-code-drift.md and returns drift findings in the same one-line format. Combine areas with fewer than 10 source files into a single worker. Cap at 5 concurrent workers, all of a wave's Agent calls in one message; with more areas, run waves of 5 — never skip an area to fit the cap.

Workers run on the host's cheap-model alias (model: haiku-style — never a pinned version). Pass each worker its file list and the inventory summary (stack, off-limits paths, entry points, relevant hygiene hits). Workers run from the user's project root, so expand every references/… path in their briefs to its absolute path under this skill's directory before dispatching. Workers load references/solo-dev-lens.md, references/categories-quick-ref.md, and references/severity-and-difficulty.md, plus references/hardcoded-environment.md for tp-10 candidates and references/convention-drift.md for tp-11 candidates, apply the falsifiability gate with their own Grep/git ls-files calls, and return one-line findings.

Cross-Cutting Synthesizer — only when top-level areas ≥ 4; skip below that. After all area workers return, dispatch one synthesizer (same reference, its own prompt) with the combined findings plus repo read access to surface cross-area duplicates, scattered cohesion spanning areas, conflicting proposals, and vocabulary drift. Cap: 10 findings.

As each worker returns, append its findings to the draft in the state file and tick its checkbox.

Finding format

One line per finding. OPINION findings omit the evidence field; everything else is mandatory — the Phase 4 formula consumes sev, diff, risk, and blast.

- [tp-10] Hardcoded environment — src/config/db.ts:4 — sev:high diff:easy risk:MEDIUM blast:1 — grep:`postgres://[^ ]*@db\.internal` — committed connection string, not deploy-portable → replace with process.env.DATABASE_URL and add a .env.example entry

sev low|medium|high · diff easy|medium|hard · risk LOW|MEDIUM|HIGH · blast = count of files affected (min 1). Evidence is grep: or git-ls-files: with the exact re-runnable pattern. Findings that must land together carry a shared group:tag token before the evidence field. Line-anchor the path (:line) only when the finding is line-specific.

Phase 3 — Adversarial review (one round)

Dispatch one Findings Reviewer (default model, prompt in references/adversarial-review-prompts.md) with the full findings draft and repo read access. It re-runs every cited grep and git ls-files itself, drops hallucinated citations, challenges false vestigials, false hardcoded-environment calls, and risky renames, enforces the security-path severity floor, flags missing findings, and returns a KEEP/REVISE/DROP verdict per finding. Apply the verdicts to the draft. Depth = 1 — never dispatch a second round.

Phase 4 — Rank and write the plan (no subagents)

Load references/ranking-formula.md; score every surviving finding, merge group-tagged findings per its grouping rules, and sort. Sequence the ranked findings into atomic batches — the smallest sets that leave the repo working between batches, each independently committable, dependency-ordered, with a concrete runnable Verification: command per batch. Flag any batch touching env vars, CLI flags, DB schema, deployed URLs, cron/webhook/queue handlers, or auth as boundary_crossing: true. Then load references/final-plan-format.md and write the plan:

• docs/ exists at the repo root → docs/YYYY-MM-DD-tidy-project-plan.md
• else → YYYY-MM-DD-tidy-project-plan.md at the repo root

Surface only the plan path. Your closing reply names the consolidated plan path and nothing else — never the state file, worker output, or intermediate drafts. Disclose the state-file location only if the user explicitly asks.

Failure modes to avoid

• Flagging framework-required structure as over-engineering.
• Accepting "hasn't been touched in months" as evidence — structure evidence only, never git history.
• Treating a required checked-in file (lockfile, fixture, generated file the build consumes as input) as a tp-03 committed artifact.
• Treating a skipped directory as unreviewable — its tracked presence is still evidence via git ls-files.
• Letting a worker return prose paragraphs instead of one-line findings — re-dispatch that area with the format restated.
• Pausing between phases for confirmation, or printing per-phase summaries. Run through.

Done

Every checkbox ticked and the plan written. Report the plan path — nothing else. Do not commit, do not delete the state file, do not run build or test commands.