Tidy Code

Activation

This skill activates only when the user explicitly invokes it via the /tidy-code slash command. It must not auto-activate on natural-language requests such as "review my code," "audit the code," "clean this up," "find code smells," "make this more maintainable," or "reduce complexity" — those phrasings must not trigger this skill.

Dependency preflight (startup, before any dispatch). Run command -v jq. If jq (≥ 1.6) is absent, abort immediately with an install hint (brew install jq / apt-get install jq) — and must not create the state dir or dispatch any subagent. The finding pipeline uses JSONL records + jq.

---

Hard Constraints

• MUST NOT modify source files. The only writable paths are under `` (the per-run scratch directory — see § Run state directory) and the final consolidated plan path (see § Final Plan Format).
• MUST NOT auto-activate without /tidy-code.
• MUST NOT retry the adversarial review more than once (depth=1).
• MUST NOT re-run the file-review pass from inside the reviewer subagent.

---

Run state directory & final output

Intermediate scratch artifacts (per-wave findings, dedup output, review verdict) are NEVER user-facing. They live under a per-run scratch directory and exist only to support Resume and debugging.

• State directory (scratch): .agents/local/state/tidy-code-/ at the repo root. The orchestrator creates this directory at startup. ` is a **UUIDv7** generated once via Bash: scripts/uuidv7.sh — NEVER a date timestamp — so two runs started in the same wall-clock second can never share a state dir or clobber each other (see repo-root STANDARDS.md` § Run-ID scoping). The orchestrator generates the runid once and threads it into every subagent dispatch; subagents never generate their own. Every subagent writes into this directory; nothing else writes outside it.
• Resume detection: On entry, the orchestrator runs ls -1d .agents/local/state/tidy-code-* 2>/dev/null. If any prior-run directories exist, ask the user Fresh run (new runid, prior dirs untouched), Resume (reuse most recent runid; the phase is complete when the rendered findings.md ends with ---END-REPORT--- — intermediate .jsonl files carry no marker), or Discard prior (delete prior tidy-code-* dirs, then Fresh). Never silently overwrite.
• Final consolidated plan (the only user-facing file): After step 8 completes PASS or PASSWITHCORRECTIONS, the orchestrator generates a single self-contained markdown file optimized for downstream LLM execution. Path resolution:

1. If docs/ exists at the repo root → write to docs/YYYY-MM-DD-tidy-code-plan.md.
2. Else → write to YYYY-MM-DD-tidy-code-plan.md at the repo root.

YYYY-MM-DD uses date +%Y-%m-%d (date only, distinct from the state-dir runid).

• User-facing response rule (load-bearing). The orchestrator's reply to the user at end-of-run MUST mention only the consolidated plan path. Do NOT print the state directory, the per-wave findings files, the review file, or the runid. The state dir is implementation detail. Disclose .agents/local/state/tidy-code-/ only if the user explicitly asks where intermediates live.

§ Final Plan Format below summarizes the format and links the full template in references/final-plan-format.md.

---

Task List Protocol

At command startup, before any subagent dispatch, the orchestrator MUST create a visible progress checklist covering all nine workflow steps and update it as each step starts and completes. The exact mechanism depends on the agent host (Claude Code, Gemini CLI, Codex, etc.) — see references/progress-tracking.md for the canonical step list and per-host adapter rules.

The reference is small and self-contained; load it once at command start, follow the adapter for the current host, and re-consult only when a parallel wave needs an activeForm update.

Free-text "Phase N starting" annotations in the conversation are NOT a substitute — the user must see structured, tickable progress.

---

Subagent Return Contract

Every subagent spawned by this skill MUST end its reply with a Summary block under 150 words. The literal first line MUST be a machine-parseable status token: STATUS: PASS | PASS_WITH_CORRECTIONS | FAIL. The remainder lists output file path(s) and key counts (files reviewed, findings by severity). Subagents MUST NOT restate the contents of files they wrote — those are on disk for the orchestrator to read on demand. The orchestrator gates step transitions on the STATUS token, not on prose interpretation.

Generic Summary shape (each role extends with its own counts — File Discovery emits two list paths; Findings Reviewer adds KEEP/REVISE/DROP):

STATUS: PASS
- Output: /findings.md
- Files reviewed: N
- Findings: N (H: N, M: N, L: N)
- Unverified rewrites: N

` is .agents/local/state/tidy-code-/ — the orchestrator passes its absolute path to every subagent in the dispatch prompt. Subagents NEVER hardcode .agents/tidy/code/` or any other path.

---

Review Workflow

Intermediate filenames (pinned — use these literal names; do NOT improvise per-run names). All under ``:

| File | Written by | Contents | |------|-----------|----------| | findings-wave{N}.jsonl | each File-Review Subagent (step 3) | that wave's raw analyst records | | findings.jsonl | orchestrator (step 4) | the validated waves concatenated — the combined analyst record set | | findings-deduped.jsonl | dedup-findings.sh (step 4) | deduplicated records, the source of truth for steps 5–8; severity + rewrite-verification are merged back into it at the step 5–6 re-join | | findings-severity.jsonl | Severity Classifier (step 5) | per-finding severity verdicts (PURE JSONL, no marker); merged into findings-deduped.jsonl at the re-join | | findings-verified.jsonl | Rewrite Verifier (step 6) | per-finding rewrite-verification verdicts, sentinel on failure (PURE JSONL, no marker); merged into findings-deduped.jsonl at the re-join | | findings-review.jsonl | Findings Reviewer (step 8) | one verdict record per finding (PURE JSONL, no marker) | | findings.md | render-findings.sh (step 7) | the rendered report; ends with ---END-REPORT---; Resume gates on this marker |

The rendered findings.md is the single artifact guaranteed present across runs; every other name above is fixed so a harness or Resume can find records deterministically.

1. File Discovery — If the user listed files, use them. Otherwise dispatch the File Discovery Subagent (fast cheap) to run Bash: scripts/enumerate.sh and parse the JSONL output — each line is {"path": , "kind": "app"|"test"} — splitting on .kind into the app/test lists (read each record's .path with jq, not by column-splitting prose). The script already excludes dotfiles, dot-directories, and common build/vendor/cache dirs (node_modules, vendor, dist, build, coverage, __pycache__, target, venv). Non-source extensions (.json, .yaml, .md, .lock, images, fonts, .d.ts, etc.) are filtered downstream by the File-Review Subagents per § Scope Rules. Do nothing else.

• Abort conditions: app-files empty → user-facing error. >1000 app files (50/wave × 20 waves ceiling — 5 concurrent subagents × ≤10 files each per wave) → ask the user to scope the review (e.g., a subdirectory).

1. Sub-agents load rules — Each File-Review Subagent reads references/principles-quick-ref.md at the start of its pass. The orchestrator does NOT load it.
2. Review files in parallel — Spawn up to 5 concurrent File-Review Subagents (fast cheap; batches of 8–12 files per subagent — see Batching rule below). Dispatch each wave in a single assistant turn — emit all of that wave's subagent dispatches in one message so the host runs them concurrently; subagents dispatched across separate messages run sequentially. Keep each turn within the 5-concurrent cap (with more batches than the cap, run successive waves). Each loads reference files on demand and emits findings as JSONL records (one object per line, schema in § Output Format) to its pinned per-wave file /findings-wave{N}.jsonl. Internal parallelism (mandatory): within its assigned batch, the subagent must issue Read / Grep calls in parallel — one assistant turn, many tool calls — not sequentially file-by-file. Falsifiability gate (mandatory): before emitting any finding, the subagent classifies it FALSIFIABLE (cites a specific snippet/identifier on a specific line that Grep can confirm) or OPINION (a judgment where the evidence is interpretation). For FALSIFIABLE findings the subagent runs Grep with an exact pattern against the cited path before emission, sets "falsifiable": true and "grep": "" on the record, and DROPs the finding if Grep returns no match or matches at a different line — log drops as dropped_hallucinations: N in the Summary. For OPINION findings the subagent sets "falsifiable": false and "grep": null. On subagent failure, log and continue.
3. Dedup and collect — Orchestrator runs Bash: scripts/validate-records.sh on each per-wave file (a malformed record or bad enum fails that wave and triggers a re-dispatch), concatenates the validated waves into /findings.jsonl, then Bash: scripts/dedup-findings.sh /findings.jsonl → /findings-deduped.jsonl (no subagent dispatch). Both consume JSONL finding records (one object per line). Stdout is the deduplicated record stream (key: (cat, file, line)), sorted by (file, line, cat); stderr lists every dropped duplicate as @ : DROPPED_DUP_OF @ :. Then the orchestrator reconciles cross-file violations missed across batches. When the same evidence supports multiple findings (e.g., UserManager triggering both tc-04 god class and tc-09 uncommunicative name), keep the higher-severity finding and reference the others in its rationale; do not emit duplicates for the same evidence. Malformed Summary → treat findings as partial, add Unverified suggestions: [N].

Batching rule (referenced from step 3)

Default: 8–12 files per File-Review Subagent, 5 concurrent subagents per wave. This favors fewer-larger over more-smaller: each subagent dispatch carries fixed init overhead to reload references and context, which dominates when the actual review work per file is small. Larger batches amortize that overhead — the LLM reads the batch in parallel internally.

Deviations:

• **Tiny repo ( review work). Never exceed 20 (context window pressure within the subagent + diminishing-returns on parallel reads).

1. Classify severity (order-free with step 6 — dispatched concurrently; see the re-join clause below) — Severity Classifier Subagent (fast cheap) applies references/severity-rubric.md to assign high/medium/low; rubric is a deterministic lookup, no reasoning required. Reads /findings-deduped.jsonl; writes its per-finding severity verdicts to /findings-severity.jsonl. Does not modify the deduped file.
2. Verify suggestions (order-free with step 5 — dispatched concurrently; see the re-join clause below) — Rewrite Verifier Subagent (mid-tier reasoning) confirms each rewrite resolves the flagged violation without introducing a new one; returns a one-line rationale per finding (e.g., "OK — guard clause eliminates the nested if; no new branch introduced"). On failure after one revision pass (depth=1), emit the sentinel string defined below. Do not retry further. Reads /findings-deduped.jsonl; writes its per-finding verification verdicts (the sentinel in suggested on failure) to /findings-verified.jsonl; does not modify the deduped file. Verification is scoped to each already-cited finding — the finding set is fixed before this step, so this is judgment about existing citations, never re-detection. Accordingly the subagent issues its per-finding Read/Grep calls in parallel (one assistant turn, many calls) and, for a large cited file (wc -l first), reads a bounded window around the cited line rather than the whole file.

Steps 5–6 concurrent dispatch & re-join (mandatory). Steps 5 and 6 both read the same immutable findings-deduped.jsonl and write to disjoint fields (step 5 → sev; step 6 → suggested/verification), so they are order-free. Dispatch both subagents in a single assistant turn so the host runs them concurrently — two subagents, well within the 5-concurrent cap; their differing tiers do not change this. Re-join before advancing: the orchestrator MUST confirm BOTH subagents have returned (parse both STATUS first-line tokens) and then merge both outputs back onto /findings-deduped.jsonl via jq — the classifier's sev overriding each record's severity, the verifier's sentinel/verification applied to suggested — producing the finalized record set. The orchestrator MUST NOT render (step 7) or let the Findings Reviewer evaluate the debate gate (step 8, which keys on sev:high AND the rewrite-verifier sentinel) until both merges are confirmed complete. A missing STATUS token from either subagent blocks the re-join; re-dispatch the missing one before continuing. The merge is deterministic jq field application by the orchestrator (the same apply-verdicts pattern step 8 uses), not LLM prose.

1. Assemble report — The orchestrator renders the human-readable report from the validated/deduped records: Bash: scripts/render-findings.sh /findings-deduped.jsonl > /findings.md. The script groups by file (records sorted by (file, line)), emits one ### Finding N block per record, and appends the ## Summary block + ---END-REPORT--- marker. No subagent hand-writes findings.md.
2. Adversarial review — Dispatch the Findings Reviewer Subagent (mid-tier) with references/adversarial-review-prompt.md. Output: /findings-review.jsonl ending in PASS / PASSWITHCORRECTIONS / FAIL. On FAIL, re-run the affected file-review subagents once (depth=1) before finalizing. On PASSWITHCORRECTIONS, the orchestrator applies the reviewer's REVISE/DROP decisions to the report in place.
3. Generate final consolidated plan — Once step 8 is PASS or PASSWITHCORRECTIONS, the orchestrator transforms the validated /findings.md into a single self-contained file at docs/YYYY-MM-DD-tidy-code-plan.md (or repo root if docs/ doesn't exist) using the template in references/final-plan-format.md (load it at this step). Per the § User-facing response rule, this consolidated plan is the only path named to the user.

Sentinel strings. [Suggested rewrite could not be verified — manual rewrite required] — emitted verbatim in the Suggested: field when rewrite verification (step 6) fails after one retry. The Summary's Unverified rewrites: N line MUST always appear (use 0 when none).

---

Multi-agent debate protocol

The Findings Reviewer marks severity: high findings as DEBATE_PENDING when the file-review pass emitted the rewrite-verifier sentinel [Suggested rewrite could not be verified — manual rewrite required]. For each pending finding the orchestrator runs a 2-agent × 2-round debate in this exact shape (per Du et al. 2024, scoped down for solo-dev budget):

1. Spawn two mid-tier reviewer subagents in parallel, fresh contexts. Each receives: the full finding record (cat, file, line, sev, falsifiable, grep, smell, principle, refactoring, suggested), the file-review subagent's reasoning, and the Findings Reviewer's tentative verdict and reason. Neither subagent sees the other's response or the original Findings Reviewer prompt.
2. Round 1 — independent verdict. Each subagent returns KEEP / REVISE / DROP with a ≤40-word reason.
3. Round 2 — exchange and rebut. The orchestrator passes each subagent the other's Round 1 reason (verbatim) and asks for a refined verdict + ≤40-word rebuttal. The subagents now know each other's position but did not see each other's deliberation.
4. **Orchestrator reso

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ggwicz
• Source: ggwicz/skills
• License: MIT

Install and usage instructions live in the source repository linked above.