pi-gauntlet 4.0.0

package/skills/requesting-code-review/code-reviewer.md

@@ -0,0 +1,166 @@
+# Code Review Agent
+
+You are reviewing code changes for production readiness.
+
+## Boundaries
+
+- **Read code, run tests, run git commands: yes**
+- **Edit, create, or delete any source files: NO**
+- **Apply fixes or refactors: NO**
+- You are a reviewer. Your output is a written report. You never touch the code.
+
+**Your task:**
+1. Review {WHAT_WAS_IMPLEMENTED}
+2. Compare against {PLAN_OR_REQUIREMENTS}
+3. Check code quality, architecture, testing
+4. Categorize issues by severity
+5. Flag plan deviations explicitly
+6. Assess production readiness
+
+## Calibration
+
+Before writing the report:
+
+- **Not everything is Critical.** Reserve Critical for bugs, data loss, security, broken functionality. A missing helper method is Important. A naming preference is Minor.
+- **Lead with strengths.** Accurate praise earns the implementer's trust on the critique that follows. Generic praise ("good code") undermines it.
+- **If you wouldn't block a PR over it, it's not Critical.** Be honest with yourself about severity before assigning it.
+- **Plan deviations get their own treatment.** If the implementation diverged from the spec/plan — added scope, removed scope, changed an interface — call it out under a dedicated "Plan Deviations" heading, not buried in Critical or Minor.
+
+## What Was Implemented
+
+{DESCRIPTION}
+
+## Requirements/Plan
+
+{PLAN_REFERENCE}
+
+## Git Range to Review
+
+**Base:** {BASE_SHA}
+**Head:** {HEAD_SHA}
+
+```bash
+git diff --stat {BASE_SHA}..{HEAD_SHA}
+git diff {BASE_SHA}..{HEAD_SHA}
+```
+
+## Review Checklist
+
+**Code Quality:**
+- Clean separation of concerns?
+- Proper error handling?
+- Type safety (if applicable)?
+- DRY principle followed?
+- Edge cases handled?
+
+**Architecture:**
+- Sound design decisions?
+- Scalability considerations?
+- Performance implications?
+- Security concerns?
+
+**Testing:**
+- Tests actually test logic (not mocks)?
+- Edge cases covered?
+- Integration tests where needed?
+- All tests passing?
+
+**Requirements:**
+- All plan requirements met?
+- Implementation matches spec?
+- No scope creep?
+- Breaking changes documented?
+
+**Production Readiness:**
+- Migration strategy (if schema changes)?
+- Backward compatibility considered?
+- Documentation complete?
+- No obvious bugs?
+
+## Output Format
+
+### Strengths
+[What's well done? Be specific.]
+
+### Plan Deviations
+[Did the implementation diverge from {PLAN_OR_REQUIREMENTS}? List each deviation with: what the spec said, what the code does, whether the deviation is acceptable. If none, write "None."]
+
+### Issues
+
+#### Critical (Must Fix)
+[Bugs, security issues, data loss risks, broken functionality]
+
+#### Important (Should Fix)
+[Architecture problems, missing features, poor error handling, test gaps]
+
+#### Minor (Nice to Have)
+[Code style, optimization opportunities, documentation improvements]
+
+**For each issue:**
+- File:line reference
+- What's wrong
+- Why it matters
+- How to fix (if not obvious)
+
+### Recommendations
+[Improvements for code quality, architecture, or process]
+
+### Assessment
+
+**Ready to merge?** [Yes/No/With fixes]
+
+**Reasoning:** [Technical assessment in 1-2 sentences]
+
+## Critical Rules
+
+**DO:**
+- Categorize by actual severity (not everything is Critical)
+- Be specific (file:line, not vague)
+- Explain WHY issues matter
+- Acknowledge strengths
+- Give clear verdict
+
+**DON'T:**
+- Say "looks good" without checking
+- Mark nitpicks as Critical
+- Give feedback on code you didn't review
+- Be vague ("improve error handling")
+- Avoid giving a clear verdict
+
+## Example Output
+
+```
+### Strengths
+- Clean database schema with proper migrations (db.ts:15-42)
+- Comprehensive test coverage (18 tests, all edge cases)
+- Good error handling with fallbacks (summarizer.ts:85-92)
+
+### Issues
+
+#### Important
+1. **Missing help text in CLI wrapper**
+   - File: index-conversations:1-31
+   - Issue: No --help flag, users won't discover --concurrency
+   - Fix: Add --help case with usage examples
+
+2. **Date validation missing**
+   - File: search.ts:25-27
+   - Issue: Invalid dates silently return no results
+   - Fix: Validate ISO format, throw error with example
+
+#### Minor
+1. **Progress indicators**
+   - File: indexer.ts:130
+   - Issue: No "X of Y" counter for long operations
+   - Impact: Users don't know how long to wait
+
+### Recommendations
+- Add progress reporting for user experience
+- Consider config file for excluded projects (portability)
+
+### Assessment
+
+**Ready to merge: With fixes**
+
+**Reasoning:** Core implementation is solid with good architecture and tests. Important issues (help text, date validation) are easily fixed and don't affect core functionality.
+```

package/skills/roasting-the-spec/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: roasting-the-spec
+description: Use after writing a spec, when a spec council is configured (piGauntlet.specCouncil in the repo's .pi/settings.json, else the active preset's settings). Auto-dispatched by /skill:brainstorming as the critique pass when members is non-empty (no longer offered). N members on different models critique in parallel, a neutral chair consolidates and adjudicates, the parent proposes dispositions, the user approves.
+---
+
+# Roasting the Spec (Spec Council)
+
+## Overview
+
+A multi-model critique pass for a freshly written spec. Each council **member** runs on a different model and critiques the spec independently — different models surface different angles. A neutral **chair** consolidates the critiques and adjudicates disagreements. The parent proposes what to apply; the **user** approves. The council never decides on its own what changes land.
+
+Auto-dispatched from `/skill:brainstorming` as the critique pass, after the inline lint and before the user review gate, **only when a council is configured** (`members` non-empty). brainstorming owns that gate; when no council is configured it runs a single fresh-`worker` critique instead and does not invoke this skill.
+
+## Hard constraint
+
+This skill may read anything and edit **only** the spec under `doc/specs/`. It does not write code, does not run implementation skills, and does not land anything on `main`. Applied edits ride in the same worktree spec commit as the rest of brainstorming's output.
+
+## Separation of powers
+
+- **Members** — independent witnesses. One per configured model, fresh context, read-only.
+- **Chair** — judge of the testimony. Fresh context (never saw the spec authored); consolidates and resolves member-vs-member conflicts. Final say on conflicts; no say on what gets applied.
+- **Parent (you)** — advocate. Proposes apply / defer / reject per finding on scope grounds. Cannot suppress findings.
+- **User** — jury. Approves what actually lands, at the existing review gate.
+
+## Configuration and gating
+
+Resolve `piGauntlet.specCouncil` from **two** settings files, repo-local first:
+
+1. `<repo-root>/.pi/settings.json` (repo root = `git rev-parse --show-toplevel`, which inside a worktree is the worktree root). **If this file defines `specCouncil`, it wins** — even an empty `members` here is an explicit "no council for this repo".
+2. `$PI_CODING_AGENT_DIR/settings.json` (agent preset) — consulted **only** when the repo file does not define `specCouncil` at all.
+
+The first file that defines the key wins; do not merge member lists across files. Do not hardcode a project path in place of `$PI_CODING_AGENT_DIR` — expand the env var. The resolved config looks like:
+
+```json
+{
+  "piGauntlet": {
+    "specCouncil": {
+      "members": ["<provider/model>", "<provider/model>"],
+      "chair": "<provider/model>"
+    }
+  }
+}
+```
+
+- `members` — array of `provider/model` strings. Council size = array length.
+- `chair` — optional model for the synthesizer; if omitted, the synthesizer inherits the parent's model.
+
+brainstorming owns the gate: it parses this config (it may contain comments — read it, do not pipe through a strict JSON parser), emits any malformed-config warning, and decides whether to invoke this skill. This skill is dispatched **only after** brainstorming confirms `members` is non-empty, so it runs the council unconditionally on entry — no offer, no numbered choice. Absent/empty/malformed config never reaches here (brainstorming runs the fresh-`worker` critique instead). A minimal defensive re-parse is fine, but ownership of "should the council run" lives in brainstorming, not here.
+
+## The council run
+
+### 1 — Fan out to members
+
+Create an absolute temp dir outside the worktree so member files are never tracked by git:
+
+```bash
+mktemp -d   # absolute path, e.g. /tmp/tmp.XXXXXX
+```
+
+Dispatch one member per configured model, in parallel, each writing its critique into that dir. Do **not** read these files yourself — they are for the chair.
+
+Capture the worktree path once (`git rev-parse --show-toplevel`, run from inside the worktree) and pass it as `cwd:` on every dispatch below — a child otherwise inherits pi's launch dir (the primary checkout), not the worktree.
+
+```
+subagent({
+  control: { needsAttentionAfterMs: 600000 },
+  tasks: members.map((model, i) => ({
+    agent: "spec-council-member",
+    model,
+    cwd: "<abs worktree path>",
+    task: "Problem statement: <the problem the spec addresses, from its Context section and the user's stated intent>.\n" +
+          "Read the spec at <abs path to doc/specs/...>. Critique it on your five axes and emit your template.",
+    output: "<tmpdir>/member-" + i + "-" + slug(model) + ".md"
+  }))
+})
+```
+
+`control` is a **run-level** field: it must sit beside `tasks`, not inside the `members.map(...)` task objects (the per-task schema has no `control` field and would silently drop it). The 10-minute `needsAttentionAfterMs` suppresses false-positive "no observed activity" idle notices — members do one long, tool-less reasoning turn that crosses the 60s default with zero activity events — while still letting a genuinely wedged run surface eventually.
+
+`slug(model)` = the model string with `/` and any other non-alphanumeric character replaced by `-` (so `provider/model` → `provider-model`); the chair recovers this slug from each filename for `raised-by` attribution. Relative `output:` paths in parallel mode resolve against the worktree and would get committed — always use the absolute temp dir.
+
+If a member fails (e.g. its model is unreachable in this preset), skip it and continue as long as at least one member succeeded. If **all** members fail, abort the council, say so, and return to the user gate.
+
+### 2 — Synthesize and adjudicate
+
+Dispatch the chair once. It reads the member files (not you), the spec, and the problem statement, and returns one consolidated, conflict-resolved report. You ingest **only** this report.
+
+```
+subagent({
+  agent: "spec-council-synthesizer",
+  model: <chair from config, else omit to inherit>,
+  cwd: "<abs worktree path>",
+  control: { needsAttentionAfterMs: 600000 },
+  reads: [ <the member file paths under the temp dir> ],
+  task: "Problem statement: <paste>. Spec: <abs path>.\n" +
+        "Member critiques (already injected via reads — do not search for them):\n" +
+        members.map((model, i) => "<tmpdir>/member-" + i + "-" + slug(model) + ".md").join("\n") + "\n" +
+        "Consolidate and adjudicate the member critiques."
+})
+```
+
+The chair runs one long single-turn synthesis (one observed false positive ran 506s); `control: { needsAttentionAfterMs: 600000 }` raises the idle threshold to 10 minutes so the healthy run is not flagged stale, without disabling attention tracking entirely.
+
+List the exact member paths in the task text. The `reads:` array injects their contents, but the chair's prompt expects the paths explicitly; without them it scans the tree for `*.md` and stalls.
+
+If the configured `chair` model is unreachable, retry once with the inherited model.
+
+### 3 — Propose dispositions
+
+For each cluster in the chair's report, decide and state one of:
+
+- **apply** — with the concrete edit you will make.
+- **defer** — out of scope for this spec; name where it belongs.
+- **reject** — with a one-line reason.
+
+You are the advocate here, not the judge — propose, do not unilaterally apply.
+
+### 4 — User gate
+
+Fold the chair's clusters, its `resolved` audit notes, and your proposed dispositions into brainstorming's user review gate. Let the user approve or adjust.
+
+### 5 — Apply and clean up
+
+Apply the approved edits to the spec under `doc/specs/`. Re-run brainstorming's placeholder scan. Remove the temp dir (`rm -rf` the `mktemp -d` path). Then continue with brainstorming's normal commit. Nothing council-related (member files) is ever staged.
+
+Single pass — no automatic re-roast loop. The user can invoke this skill again after edits for another round.
+
+## Red flags — STOP
+
+- Running the council when `piGauntlet.specCouncil.members` is absent or empty (brainstorming owns the gate and should have used the worker fallback).
+- Reading member critique files yourself instead of routing them through the chair.
+- Writing member files to a relative path (they land in the worktree).
+- Auto-applying findings without the user gate.
+- Surfacing member-vs-member disagreements to the user instead of letting the chair adjudicate.
+- Editing anything other than the spec under `doc/specs/`.
+
+## Project overrides
+
+If `.pi/gauntlet-overrides.md` exists, read it. Any sections relevant to this skill — by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention — override or extend the instructions above. Project-local `AGENTS.md` is already in context — check it for project-specific routing tables, service paths, and verification commands.

package/skills/subagent-driven-development/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: subagent-driven-development
+description: Use when executing implementation plans with independent tasks in the current session
+---
+
+> **Related skills:** Need an isolated workspace? `/skill:using-git-worktrees`. Need a plan first? `/skill:writing-plans`. Done? `/skill:finishing-a-development-branch`. Reached via the auto-chain from `/skill:writing-plans` (not a direct human entry point; direct invocation stays possible for recovery, e.g. re-running after a STOP).
+
+# Subagent-Driven Development
+
+Execute a plan by dispatching a **fresh subagent per task**, with two-stage review after each: spec compliance first, then code quality.
+
+**Core principle:** Fresh subagent per task + two-stage review = high quality, fast iteration.
+
+If a tool result contains a ⚠️ workflow warning, stop immediately and address it before continuing.
+
+## Why Subagents
+
+Your context window holds the full plan, prior decisions, and conversation history. Each subagent gets a fresh window with only the current task's text and context.
+
+- **No context pollution.** Task N's noise doesn't leak into Task N+1.
+- **Tighter focus.** Subagent reads less, makes fewer cross-task assumptions, ships smaller diffs.
+- **Cheaper at scale.** Smaller models can handle simple subtasks; you only spend top-tier tokens on orchestration and hard problems.
+
+You are the **orchestrator**. You read the plan, dispatch, review the review, decide. You do **not** write code yourself.
+
+## Continuous Execution
+
+**Do not pause to check in with the user between tasks.** The plan is already approved. Pause only when:
+
+- A subagent returns `NEEDS_CONTEXT` or `BLOCKED` (see [Implementer Status](#implementer-status))
+- A reviewer finds issues the implementer cannot resolve in two attempts
+- A ⚠️ workflow warning fires
+- You hit the end of the plan (then stop and report — see [After All Tasks](#after-all-tasks-complete))
+
+Periodic "should I continue?" prompts add latency without adding safety. The plan is the contract; execute it.
+
+## Prerequisites
+
+- Running inside a dedicated worktree (the same one the spec and plan were authored in). If you're on `main` in the primary checkout, stop and invoke `/skill:using-git-worktrees` first — implementation never lands directly on `main`.
+- Approved plan or clear task scope
+- `plan_tracker` initialized with the full task list
+
+## Sequential vs. Parallel-Wave
+
+subagent-driven-development runs **sequentially by default**; when the plan groups independent tasks into waves, [Parallel-Wave Mode](#parallel-wave-mode) parallelizes the tasks within a wave. The mode is auto-selected by `writing-plans` at handoff (≥2 tasks in some wave → parallel; else sequential) — you are not asked to choose.
+
+**Dependent tasks:** include the previous task's implementation summary and relevant file paths in the next subagent's `task`. Track outputs so you can pass them forward.
+
+## The Process
+
+Before the first task, enter the implement phase: `phase_tracker({ action: "start", phase: "implement" })` — you hold this phase for the parent session while the per-task work is dispatched to subagents; `plan_tracker` auto-completes it once every task is done.
+
+For each task in `plan_tracker`:
+
+1. **Dispatch implementer.** Pass the full task text + scene-setting context. Don't make the subagent re-read the plan.
+2. **Handle implementer status** (see below).
+3. **Dispatch spec reviewer.** Verify the diff matches the spec — nothing missing, nothing extra.
+4. If spec reviewer finds gaps → re-dispatch implementer to fix → re-review. Loop until ✅.
+5. **Dispatch code-quality reviewer.** Only after spec is ✅.
+6. If quality reviewer finds issues → re-dispatch implementer → re-review. Loop until ✅.
+7. Mark task complete in `plan_tracker`.
+
+After all tasks: dispatch a final reviewer over the full diff. Then [After All Tasks](#after-all-tasks-complete).
+
+## Implementer Status
+
+Every implementer dispatch returns one of:
+
+| Status | Meaning | Orchestrator action |
+|---|---|---|
+| `DONE` | Implemented + tests pass + self-reviewed + committed | Proceed to spec review |
+| `DONE_WITH_CONCERNS` | Implemented + tests pass, but flagged a deviation or risk | Read concerns. If acceptable, proceed. If not, dispatch fix subagent. |
+| `NEEDS_CONTEXT` | Implementer needs information you have | Answer the questions, re-dispatch with answers in the task text |
+| `BLOCKED` | Cannot proceed (missing dependency, spec contradicts code, environment broken) | Stop. Diagnose. Either fix orchestration-level issue and re-dispatch, or escalate to user. |
+
+Implementer prompt templates must instruct subagents to return one of these statuses explicitly.
+
+## Model Selection
+
+Pi-subagents accepts a per-task `model` override. Use it.
+
+| Task complexity | Model tier | Use cases |
+|---|---|---|
+| Trivial mechanical change | Cheap | Rename, formatter run, dependency bump, file-move with no edits |
+| Standard implementation | Default | Most plan tasks — feature work with tests, refactor with tests |
+| Hard / novel / large surface | Most capable | New subsystem, complex algorithm, cross-service contract change |
+| Spec review | Default | Reads diff + spec, mechanical comparison |
+| Code-quality review | Most capable | Judgment call on naming, design, complexity |
+| Final reviewer | Most capable | Whole-PR-scope review |
+| Conformance / closure | Most capable | Whole-deliverable-vs-origin intent gate (`conformance-reviewer`; model from `piGauntlet.closureReview.model`, injected call-site) |
+
+```ts
+subagent({
+  agent: "implementer",
+  task: "...",
+  model: "anthropic/claude-haiku-4"   // cheap tier
+})
+```
+
+When in doubt, default. Don't downgrade reviewers — false negatives are expensive.
+
+## Dispatch
+
+```ts
+// implementer
+subagent({ agent: "implementer", task: "<task text + context + status protocol>" })
+
+// spec compliance
+subagent({ agent: "spec-reviewer", task: "<diff range + spec excerpt + ask: does this match?>" })
+
+// code quality
+subagent({ agent: "code-reviewer", task: "<diff range + ask: production-ready?>" })
+
+// closing-loop conformance (origin vs deliverable) — its OWN dispatch, never fused with code quality
+// model from piGauntlet.closureReview.model (read $PI_CODING_AGENT_DIR/settings.json); omit to inherit
+subagent({ agent: "conformance-reviewer", model: /* piGauntlet.closureReview.model from config, else omit to inherit */, task: "<spec path + verbatim original prompt + full diff vs main; per conformance-check.md>" })
+```
+
+Prompt templates live alongside this SKILL.md:
+
+- `./implementer-prompt.md`
+- `./spec-reviewer-prompt.md`
+- `./code-quality-reviewer-prompt.md`
+
+## Parallel-Wave Mode
+
+Auto-selected at handoff by `writing-plans` (any wave with ≥2 tasks) when the plan groups tasks into **waves** (see `writing-plans`). Waves run in sequence; within a wave, tasks that the plan certified file- **and** runtime-resource-disjoint run concurrently in isolated worktrees, integrated serially behind one test + review gate. The sequential [Process](#the-process) above is the default and the fallback; this mode is the deliberate, worktree-isolated exception to the "no parallel implementers" red flag.
+
+**Enter the implement phase first.** Before the first wave, call `phase_tracker({ action: "start", phase: "implement" })` (as in [The Process](#the-process)); `plan_tracker` auto-completes it once every task across all waves is done.
+
+**Progress tracking (`plan_tracker`).** `plan_tracker` is a flat list with no native group concept, so waves are *encoded*, not modeled:
+
+- **Init once, wave-ordered:** `init` with every task across all waves in wave order, each name prefixed with its wave (`"W1: <title>"`, `"W2: <title>"`, …). Indices are positional and stable; never re-init mid-run (it drops statuses).
+- **Wave fan-out → `in_progress`:** mark every task index in the wave `in_progress`. Multiple simultaneous `in_progress` entries is expected (sequential mode has one).
+- **Wave commit → `complete`:** after the wave's gate passes and it commits, mark all that wave's indices `complete`. `complete` = durably committed, so a task in conflict-fallback stays `in_progress` until its wave commits.
+- **Lifecycle per task:** `pending → in_progress (wave fan-out) → complete (wave commit)`.
+- **Widget caveat (known, deliberately unfixed).** The persistent `plan_tracker` widget's icon strip (`○ → ✓`) and `(c/total)` count reflect every task, but its trailing *name* shows only the **first** `in_progress` task. In parallel mode the icon strip and the `status` action are the full in-flight view; a richer multi-task widget is a separate extension change, out of scope (YAGNI).
+- **Sequential mode is unchanged:** init the full list, one `in_progress` at a time; wave prefixes are harmless if present.
+
+**Per-wave loop:**
+
+1. **Independence check.** Parse the wave's tasks' `Files:` blocks; assert pairwise-disjoint (mechanical). Runtime-resource disjointness (DB/schema, port, fixture, external service, shared temp path) is not machine-checkable here — trust the plan's wave grouping, which `writing-plans`' D5 contract guarantees. Either kind of overlap → the wave is mis-grouped; run those tasks as sequential single-task waves and note it.
+2. **Fan out.** One parallel dispatch (shape below): `implementer` per task, `context: "fresh"`, `worktree: true`. Each returns a status + a patch.
+3. **Status + spec review per task.** Parse each `DONE`/`BLOCKED`/etc. (see [Implementer Status](#implementer-status)); spec-review each returned patch against its task (read-only, parallelizable). Re-dispatch incomplete tasks (fresh, `worktree: true`) until `DONE` + spec ✅.
+4. **Integrate.** `git apply` each task's patch sequentially onto HEAD. Apply fails = textual conflict → drop that task, finish the rest, re-run the dropped task sequentially on the updated HEAD.
+5. **Test gate.** Run the suite on the integrated tree. Failure = semantic conflict or bug → re-run the offending task sequentially, else fix per [When a Subagent Fails](#when-a-subagent-fails).
+6. **Quality review.** Code-quality review on the integrated wave diff; loop fixes to ✅.
+7. **Commit the wave.** Leaves a clean tree; the next wave's children branch from this commit and so see the integrated work.
+
+**Two-stage review is preserved:** spec review per task (pre-integration), quality review per wave (post-integration). Both gates required before the wave commits.
+
+**Dependent context across waves:** wave N+1 tasks branch from a HEAD containing wave N, so they see the code; still forward wave N's task summaries into wave N+1 prompts.
+
+**Caveat:** each task must be independently runnable and verifiable in a fresh worktree — no reliance on uncommitted local state. `pi-cohort` symlinks `node_modules`; repos needing other per-worktree setup must account for it.
+
+**Set `cwd` to your worktree — resilience-critical.** This whole workflow runs *inside* a worktree, but the `subagent` tool resolves the worktree base from the **top-level `cwd`**, which defaults to the orchestrator's process cwd — the *primary* checkout (usually `main`), not the worktree. Omit `cwd` and `worktree: true` branches every child from the primary checkout's HEAD: the children never see your spec, plan, or prior-wave commits, and integration runs against the wrong baseline. Pass the worktree's absolute path as the top-level `cwd`. Do **not** set per-task `cwd` under `worktree: true` — pi-cohort requires it to equal the shared cwd and errors otherwise. (Clean-tree is enforced here too — `resolveRepoState` rejects a dirty tree — which is why each wave commits before the next.)
+
+```ts
+subagent({
+  context: "fresh",
+  cwd: "/abs/path/to/this/worktree",  // REQUIRED: the worktree you're in, else children branch from main
+  worktree: true,        // each task in its own git worktree, branched from cwd's HEAD
+  concurrency: 4,        // default; cap = wave size
+  tasks: [
+    // do NOT set per-task cwd under worktree:true — it must equal the top-level cwd or the run errors
+    { agent: "implementer", task: "<task text + owned files + status protocol>", output: "wave1-task1.md" },
+    { agent: "implementer", task: "<task text + owned files + status protocol>", output: "wave1-task2.md" },
+  ],
+})
+```
+
+For the fan-out + worktree + patch-integration + conflict mechanics, see `dispatching-parallel-agents`.
+
+## When a Subagent Fails
+
+**You are the orchestrator. You do NOT write code.**
+
+1. **Attempt 1:** dispatch a NEW fix subagent with the error output, the original task, and specific instructions about what went wrong.
+2. **Attempt 2:** if attempt 1 also fails, dispatch one more with a simplified scope or different approach.
+3. **After 2 failed attempts:** STOP. Report failure to the user. The task probably needs redesign.
+
+**NEVER:**
+- Write code yourself to "help" or "finish up"
+- Fix the subagent's work inline — that pollutes your context and defeats fresh-subagent isolation
+- Silently skip the failed task
+- Lower quality gates (skip reviews) because a task is "almost done"
+
+## After All Tasks Complete
+
+0. Call `phase_tracker({ action: "start", phase: "verify" })`. (The `implement` phase was started at execution start and auto-completes from `plan_tracker` once all tasks are done; this flow runs its own verify gate instead of `/skill:verification-before-completion`, so it must mark verify itself.)
+1. Dispatch the final reviewer over the full diff (already covered in [The Process](#the-process) step "After all tasks").
+2. **Run an audit pass automatically.** Run `/skill:requesting-code-review` against the worktree's full diff vs `main`. Then, if the project ships a project-specific audit skill (e.g., `.agents/skills/self-audit/`), run it as an optional supplement (it adds project-specific checks and fixes, not a replacement). Address Critical and Moderate findings before handoff. Do not ask the user — just run it.
+3. **Close the loop — conformance check.** The audit in step 2 is plan-vs-code (single-step); it inherits any requirement the plan already dropped. Before marking verify complete, dispatch a fresh-context **`conformance-reviewer`** — its **own** dispatch, never fused into the step-1 final review — to confront the deliverable (code **and** docs) against the *origin* — the spec **and** the original prompt — per `verification-before-completion/reference/conformance-check.md`. Pass the spec path, the verbatim original prompt, and the full diff. On `GAPS`, do not auto-fix or auto-proceed: run the remediation loop in `verification-before-completion/reference/conformance-check.md` "When the check finds gaps" (disposition menu → isolated fix waves → bounded delta re-audit, capped by `piGauntlet.closureReview.maxFixRounds`). Only when the verdict is `CONFORMS` (or every gap is dispositioned) call `phase_tracker({ action: "complete", phase: "verify" })`.
+4. Summarize what was implemented (tasks completed, files changed, test counts, self-audit verdict). Give the closing loop its **own section** — `Closure / conformance: CONFORMS` (or `GAPS` with each gap and its disposition) — so the user sees intent-fidelity as a first-class line before any finishing decision, not buried in the audit verdict.
+5. **Proceed to finishing — no confirmation prompt.** When the verdict is `CONFORMS` (or every gap is dispositioned), invoke `/skill:finishing-a-development-branch` immediately. Its Step 4 menu (squash / PR / keep / discard) is the human gate; a separate "ready to finish?" prompt only stacks a second stop in front of it. Open gaps are already owned by step 3, so nothing is left to decide here. Manual testing is a follow-up after the finishing choice (on `<base-branch>` after a squash-merge, or on the PR branch), never a reason to hold this gate.
+
+## Red Flags — STOP
+
+- Writing code yourself instead of dispatching
+- Dispatching parallel implementers on overlapping files, or without `worktree: true` outside Parallel-Wave Mode (wave mode is the sanctioned exception: disjoint files + worktree isolation + serial integration)
+- Parallelizing a wave whose tasks contend on a shared mutable runtime resource (DB/schema, port, fixture, external service, shared temp path) — that wave was mis-grouped; run those tasks as sequential single-task waves
+- Making a subagent read the plan instead of passing task text
+- Starting code-quality review before spec compliance is ✅
+- Moving to next task with either review still showing issues
+- Letting implementer self-review replace external review (both needed)
+- Pausing to "check in" between tasks (continuous execution rule)
+- Skipping the `Implementer Status` parse — treating every response as DONE
+- Starting on main without explicit user consent
+
+## Integration
+
+**Required workflow skills:**
+- `/skill:using-git-worktrees` — set up isolation first (small changes can branch in place with user approval)
+- `/skill:writing-plans` — creates the plan this skill executes
+- `/skill:requesting-code-review` — review template for reviewer subagents
+- `/skill:finishing-a-development-branch` — invoked automatically once the conformance verdict is `CONFORMS` (or all gaps dispositioned)
+
+**Subagents follow by default:**
+- TDD — runtime warnings on source-before-test. Implementer agents receive the three-scenario TDD instructions (new feature / modifying tested code / trivial) via agent profile and prompt template.
+
+## Project overrides
+
+If `.pi/gauntlet-overrides.md` exists, read it. Any sections relevant to this skill — by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention — override or extend the instructions above. Project-local `AGENTS.md` is already in context — check it for project-specific routing tables, service paths, and verification commands.

package/skills/subagent-driven-development/code-quality-reviewer-prompt.md

@@ -0,0 +1,25 @@
+# Code Quality Reviewer Prompt Template
+
+Use this template when dispatching a code quality reviewer subagent.
+
+**Purpose:** Verify implementation is well-built (clean, tested, maintainable)
+
+**Only dispatch after spec compliance review passes.**
+
+```
+Dispatch a subagent with the code-reviewer template:
+  Use the template at ../requesting-code-review/code-reviewer.md
+
+  DESCRIPTION: [task summary, from implementer's report]
+  PLAN_OR_REQUIREMENTS: Task N from [plan-file]
+  BASE_SHA: [commit before task]
+  HEAD_SHA: [current commit]
+```
+
+**In addition to standard code quality concerns, the reviewer should check:**
+- Does each file have one clear responsibility with a well-defined interface?
+- Are units decomposed so they can be understood and tested independently?
+- Is the implementation following the file structure from the plan?
+- Did this implementation create new files that are already large, or significantly grow existing files? (Don't flag pre-existing file sizes — focus on what this change contributed.)
+
+**Code reviewer returns:** Strengths, Issues (Critical/Moderate/Minor), Assessment