# Tidy Project

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-ggwicz-skills-tidy-project`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ggwicz](https://agentstack.voostack.com/s/ggwicz)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ggwicz](https://github.com/ggwicz)
- **Source:** https://github.com/ggwicz/skills/tree/main/tidy-project

## Install

```sh
agentstack add skill-ggwicz-skills-tidy-project
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## Activation

This skill activates ONLY when the user explicitly invokes it via the /tidy-project slash command. It must not auto-activate on natural-language requests such as "audit my repo," "review my codebase," "simplify my project," "clean up my project," or "what can I delete" — those phrasings must not trigger this skill.

**A marker on the phase's final rendered artifact determines phase completion, not file presence.** The phase's consolidated `.md` artifact (e.g. `02-findings-ranked.md`, the final plan) ends with a literal trailing line `---END-PHASE-N---` (N = 1, 2, or 3); `assemble-ranked.sh` and the plan renderer emit it. **Intermediate JSONL files (`02-findings-*.jsonl`, `02-findings-verdicts.jsonl`, etc.) are PURE JSONL — one record per line, NO trailing marker** (a non-JSON marker line would break `jq` and the whole script chain). On Resume, a phase whose final `.md` artifact lacks its `---END-PHASE-N---` marker is incomplete and re-runs (phase-granularity, not per-intermediate-file).

**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 Phase-2 record pipeline uses JSONL + jq.

---

## Run state directory & final output

Intermediate scratch artifacts (inventory, drift report, per-area findings, cross-cutting synthesis, adversarial reviews, raw execution plan) 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-project-/` 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-project-* 2>/dev/null`. If any prior-run directories exist, ask the user **Fresh run** (new runid, prior dirs untouched), **Resume** (reuse most recent runid, skip phases whose marker file ends in `---END-PHASE-N---`), **Incremental** (reuse most recent runid; keep `01-inventory.md`, re-run from Phase 2), or **Discard prior** (delete prior `tidy-project-*` dirs, then Fresh). Never silently overwrite. **Legacy-state guard:** if the most recent state dir contains `02-findings-*.md` finding files but no sibling `02-findings-*.jsonl`, it predates the JSONL pipeline — its markers are not resumable. Refuse Resume/Incremental for it and force Fresh, with a one-line note to the user.
- **Final consolidated plan (the only user-facing file):** After Phase 3 completes PASS or PASS_WITH_CORRECTIONS, 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-project-plan.md`.
  2. Else → write to `YYYY-MM-DD-tidy-project-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-phase file tree (`01-inventory.md`, `02-findings-*.md`, `03-execution-plan*.md`, etc.), the runid, or any subagent file. The state dir is implementation detail. Disclose `.agents/local/state/tidy-project-/` 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 phases and update it as each phase 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 phase 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 or when handling the conditional Phase 5 (cross-cutting synthesis, skipped when areas ` and the final consolidated plan path may be created.

---

## Gotchas

- **Concurrency cap (5 concurrent subagents — do not raise).** Phase 2 caps area analysis at 5 concurrent subagents. With 6+ top-level areas, run in waves of 5 — do not skip areas to fit the cap. The 5 is calibrated to Anthropic's empirically-tested 3-5 sweet spot from [How we built our multi-agent research system](https://www.anthropic.com/engineering/multi-agent-research-system) and is endorsed in the [agent-teams docs](https://code.claude.com/docs/en/agent-teams) ("Start with 3-5 teammates… diminishing returns beyond"). Raising the cap to 8-10 adds init overhead per additional subagent for little gain and risks rate-limit throttling on most API tiers. If you find yourself wanting to raise it, prefer (a) combining tiny areas (see Phase 2 dispatch rule) or (b) promoting the analyst tier (see Escalation triggers) — both cheaper than more subagents.
- **Malformed subagent summary.** If a subagent writes a malformed summary (missing required fields), the orchestrator MUST treat it as FAIL and stop. Do NOT silently retry. Do NOT stall waiting for completion.
- **No git history.** This skill does not consult git history — it reads the tracked-file list (`git ls-files`), manifests, and the file tree, never commit dates or churn. tp-08 (vestigial scaffolding) relies on framework-manifest evidence alone. If a finding's only evidence would be "this file hasn't been touched in N months," drop it.

---

## Model & Effort Guidance

This skill spans 10 subagent roles. Default to the cheapest tier. Fast/cheap models handle enumeration, lookup, deterministic arithmetic, exact-match comparison. Mid-tier models handle judgment calls (adversarial review, cross-cutting synthesis with conflicts, planning). Use frontier models only for architecturally complex repos. Within a single run, dropping a Findings Reviewer or Area Analyst to fast/cheap will erode quality; promoting an enumeration role to mid-tier mostly wastes tokens.

**Tier vocabulary** — *Fast cheap* = Claude Haiku 4.5 or Gemini Flash 2.5; *Mid-tier* = Claude Sonnet 4.6 or Gemini 2.5 Pro; *Frontier* = Claude Opus 4.7 or current frontier-class.

Every subagent prompt in `references/adversarial-review-prompts.md` includes an explicit scope (its inputs, its outputs, what it must NOT do). Higher-tier roles get tighter scoping, not looser — the cost of mid-tier reasoning is justified only when the role's outputs are narrow and verifiable.

### Per-subagent assignment

| Role | Phase | Tier | Effort | Scope (in / out) | Why this tier |
|------|-------|------|--------|------------------|---------------|
| Orchestrator | all | Mid-tier | high | IN: subagent Summary blocks. OUT: phase decisions, retry/proceed. NOT: re-reading the files subagents wrote unless the user asks | Phase coordination + Summary parsing. |
| Inventory Builder | 1 | **Fast cheap** | medium | IN: repo root via Glob/Read. OUT: stack list, framework conventions, directory tree, entry points, config surface. NOT: project-level judgment, finding generation | Pattern-matching against framework manifests; no novel reasoning. |
| Docs Drift Reviewer | 1 | **Fast cheap** | medium | IN: `README*`, `docs/`, `AGENTS.md`, `CLAUDE.md`. OUT: per-claim verification ("file/path/command still exists?"). NOT: prose-style critique, doc rewrites | String matching, not synthesis. |
| Inventory Reviewer | 1 | Mid-tier | high | IN: `01-inventory.md`. OUT: missed entry points, misidentified stack, wrong framework conventions, incorrect counts, PASS/PASS_WITH_CORRECTIONS/FAIL verdict. NOT: rewriting the inventory itself | Adversarial pass; spot missed entry points. |
| Area Analyst (one per top-level area) | 2 | Mid-tier | high | IN: one area's file paths + `01-inventory.md`. OUT: all well-evidenced findings for this area as JSONL records (`02-findings-{area}.jsonl`), no cap. NOT: cross-area synthesis, other areas, ranking/ordering, prose-style critique, critique whose evidence sits inside a single file | Applies the active tp-* categories; verifies citations via Grep. |
| Cross-Cutting Synthesizer | 2 | **Fast cheap** (default) | medium | IN: all `02-findings-*.md`. OUT: cross-area scattered cohesion, cross-area config/vocabulary drift, conflicting proposals, duplicate findings to reconcile, missing coverage. NOT: re-evaluating findings the reviewer hasn't seen yet | String compare across analyst outputs. **Dispatch only when top-level areas ≥ 4** (see Phase 2 dispatch rule). **Promote to Mid-tier** when fan-out ≥ 4 areas (same threshold; both gates are on area count). |
| Findings Reviewer | 2 | Mid-tier | high | IN: all `02-findings-*.jsonl` (post-dedup) + `01-inventory.md`. OUT: `02-findings-verdicts.jsonl` (one `{id, verdict, reason, revised?}` per record). NOT: ranking, grouping, scoring, or writing `02-findings-ranked.md` — those are deterministic scripts. | Citation verification offloaded to `scripts/verify-citation.sh`; ranking/grouping/assembly to scripts. The subagent's remaining work is pure adversarial judgment (KEEP/REVISE/DROP, missing findings, debate triggers). |
| Execution Plan Architect | 3 | Mid-tier | high | IN: `02-findings-ranked.md` + `01-inventory.md`. OUT: batched plan with per-batch verification checklist and boundary-crossing flags. NOT: re-scoring or re-ordering by importance — the rank order is fixed | Forward planning with boundary-crossing flags. |
| Execution Plan Reviewer | 3 | Mid-tier | high | IN: `03-execution-plan.md` + all prior phase outputs. OUT: ordering errors, missing verifications, incomplete batches, missed boundary crossings, PASS/PASS_WITH_CORRECTIONS/FAIL. NOT: re-writing the plan | Adversarial check on ordering and verifications. |
| Debate Reviewer (×2, parallel, fresh context each) | 2 | Mid-tier | medium | IN: a single DEBATE_PENDING finding (full eight fields + tentative verdict + reason). OUT: KEEP/REVISE/DROP + ≤40-word reason. NOT: editing the review file, evaluating other findings | Independent second-opinion on high-severity/low-vote findings; mid-tier for judgment quality, narrow scope for budget. |

### Escalation triggers

The orchestrator promotes the named role one tier (fast-cheap → mid-tier, or mid-tier → frontier) the first time any trigger fires. Promotions are sticky for the remainder of the run — do not demote.

| Condition (measured by orchestrator) | Threshold | Promote |
|---|---|---|
| Top-level areas (from `01-inventory.md`) | ≥ 6 | Area Analyst |
| Single area source-file count | > 500 | Area Analyst (that area only) |
| Distinct runtimes/languages in deploy unit | ≥ 3 | Area Analyst + Findings Reviewer |
| Area Analyst Summary `dropped_hallucinations` rate, run-wide | > 20% of emitted findings | Area Analyst |
| Findings Reviewer `HALLUCINATED_CITATION` rate | > 30% of reviewed findings | Area Analyst (re-run failed areas) |
| Findings Reviewer `REVISE + DROP` rate | > 30% of reviewed findings | Area Analyst |
| Malformed Summary rate (missing/wrong STATUS first line) | > 30% of subagent returns in a phase | Re-dispatch that role one tier higher |
| Execution Plan boundary-crossing batch count | ≥ 4 | Execution Plan Architect + Reviewer |

A promotion that fires twice in the same phase signals a structural problem — stop and surface the run state to the user rather than promote a third time.

## Subagent Return Contract

All subagent prompts in `references/adversarial-review-prompts.md` enforce a universal ≤150-word Summary block. The **literal first line** MUST be a machine-parseable status token: `STATUS: PASS | PASS_WITH_CORRECTIONS | FAIL`. The remainder of the block lists output paths, key counts, top signal. On respawns the Summary MUST include `cycles_used: N/2`. The orchestrator gates phase transitions on the STATUS token, not on prose interpretation.

```
STATUS: PASS
- Output: /02-findings-src.md
- Findings: 12 (H: 3, M: 7, L: 2)
- Dropped hallucinations: 1
- Top signal: dist/ is committed (tp-03) — 34 tracked build artifacts that should be gitignored and rebuilt.
```

`` (the per-run directory from § Run state directory) — the orchestrator passes its absolute path to every subagent in the dispatch prompt. Subagents NEVER hardcode `.agents/tidy/project/` or any other path.

---

## Deterministic shell helpers (`scripts/`)

Several phases delegate mechanical work to small shell scripts. These replace LLM token spend on enumeration, exact-match comparison, grouping, ranking, and deliverable rendering — work that benefits zero from reasoning, and where LLM variance is a known cause of unstable, run-to-run output. All scripts are bash 3.2+ / POSIX coreutils + jq (≥ 1.6) and live under `scripts/` in the skill installation root. Subagents and the orchestrator invoke them via `Bash`; they read the script's stdout, not its source. The Phase-2 chain reads and writes **JSONL finding records** (one JSON object per line).

| Script | Used by | Replaces / does |
|--------|---------|----------|
| `scripts/uuidv7.sh` | Orchestrator (startup) | A collision-prone `date` runid — emits the run's UUIDv7 `` |
| `scripts/reconcile-findings.sh    ` | Orchestrator (Phase 2) | Unions the K=3 area samples; stamps `vote_count` per `(cat,path)` cluster |
| `scripts/detect-stack.sh ` | Inventory Builder | LLM manifest-key grep; JSONL `{token}` |
| `scripts/enumerate.sh ` | Inventory Builder, Area Analyst | LLM Glob+filter+test/app split; JSONL `{path,kind}` |
| `scripts/count-loc.sh  [...]` | Inventory Builder | LLM `find \| wc -l` per area; JSONL `{area,files,loc}` |
| `scripts/validate-records.sh ` | Orchestrator (Phase 2 gate) | LLM schema-eyeballing — rejects malformed analyst records (exit 1) |
| `scripts/id-findings.sh  [...]` | Orchestrator (Phase 2) | LLM-invented finding ids — stamps deterministic `id` per record |
| `scripts/dedup-findings.sh  [...]` | Orchestrator (Phase 2) | The Duplicate-Finding Filter — drops `(cat,path)` dups deterministically |
| `scripts/verify-citation.sh  ` | Findings Reviewer | LLM re-grep loop; reads `.grep`/`.path`, emits TSV verdicts |
| `scripts/apply-verdicts.sh  ` | Orchestrator (Phase 2) | LLM applying KEEP/REVISE/DROP by hand |
| `scripts/group-findings.sh ` | Orchestrator (Phase 2) | LLM grouping/representative-file judgment — merges `group`-tagged records |
| `scripts/score-rank.sh ` | Orchestrator (Phase 2) | LLM ranking — scores + total-order sort |
| `scripts/assemble-ranked.sh ` | Orchestrator (Phase 2) | LLM-formatted ranked table — renders byte-stable `02-findings-ranked.md` |
| `scripts/render-findings.sh ` | Orchestrator / review | Renders human-readable markdown from records |

Phase-2 scripts emit JSONL to stdout (`verify-citation.sh` emits TSV verdict rows); all use exit codes for pass/fail. Output formats are documented in each script's header comment. The deterministic Phase-2 chain — `reconcile-findings → validate-records → id-findings → dedup-findings → [review] → apply-verdicts → group-findings → score-rank → assemble-ranked` — is run by the orchestrator; the LLM Findings Reviewer only emits verdicts.

---

## Audit Workflow

| Phase | Purpose | Key outputs |
|-------|---------|-------------|
| 1 — Inventory | Build stack inventory; check docs/code drift | `01-inventory.md`, `01-drift.md`, `01-inventory-review.md` |

…

## Source & license

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

- **Author:** [ggwicz](https://github.com/ggwicz)
- **Source:** [ggwicz/skills](https://github.com/ggwicz/skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ggwicz-skills-tidy-project
- Seller: https://agentstack.voostack.com/s/ggwicz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.