pi-gauntlet 4.0.0

package/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: verification-before-completion
+description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+---
+
+> **Related skills:** Follow up with `/skill:requesting-code-review` before merging. Done? `/skill:finishing-a-development-branch`.
+
+# Verification Before Completion
+
+## Overview
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Core principle:** Evidence before claims, always.
+
+**Violating the letter of this rule is violating the spirit of this rule.**
+
+If a tool result contains a ⚠️ workflow warning, stop immediately and address it before continuing.
+
+## Boundaries
+- Run verification commands: yes
+- Read code and output: yes
+- Edit source code: no
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## Common Failures
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
+| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
+| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
+| Regression test works | Red-green cycle verified | Test passes once |
+| Agent completed | VCS diff shows changes | Agent reports "success" |
+| Requirements met | Line-by-line checklist | Tests passing |
+| Intent delivered (loop closed) | Fresh reviewer audits code+doc vs origin spec + prompt (`reference/conformance-check.md`) | Plan-vs-code review, tests passing |
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN the verification |
+| "I'm confident" | Confidence ≠ evidence |
+| "Just this once" | No exceptions |
+| "Linter passed" | Linter ≠ compiler |
+| "Agent said success" | Verify independently |
+| "I'm tired" | Exhaustion ≠ excuse |
+| "Partial check is enough" | Partial proves nothing |
+| "Different words so rule doesn't apply" | Spirit over letter |
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
+- About to commit/push/PR without verification
+- Trusting agent success reports without checking outputs
+- Relying on partial verification
+- Thinking "just this once"
+- Tired and wanting work over
+- **ANY wording implying success without fresh evidence**
+
+## Key Patterns
+
+The shape of an honest claim is `[Run command] [See: verbatim output] "claim"`. The verbatim output is the contract — paste it, don't summarize it from memory.
+
+**Tests:**
+```
+✅ [Run test command] [See: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+```
+✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+❌ "I've written a regression test" (without proving red-green)
+```
+
+**Build:**
+```
+✅ [Run build] [See: exit 0] "Build passes"
+❌ "Linter passed" (linter ≠ build)
+```
+
+**Requirements:**
+```
+✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
+❌ "Tests pass, phase complete"
+```
+
+**Intent conformance (closing loop):**
+```
+✅ Dispatch fresh reviewer → audit code+doc vs ORIGIN (spec + prompt, not the plan) → reconcile drift → report gaps
+❌ "Plan-vs-code review passed, so the intent is delivered"
+```
+Single-step plan-vs-code review inherits drift the plan introduced; this loop
+confronts the outcome against the origin. Follow `reference/conformance-check.md`.
+
+**Agent delegation:**
+```
+✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
+❌ Trust "agent says success"
+```
+
+## Why This Matters
+
+From recurring failure modes:
+
+- Partner says "I don't believe you" — trust broken.
+- Undefined functions shipped — would crash.
+- Missing requirements shipped — incomplete features.
+- Time wasted on false completion → redirect → rework.
+- Violates: **Honesty is a core value. If you lie, you'll be replaced.**
+
+## When To Apply
+
+**ALWAYS before:**
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- ANY positive statement about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
+
+**Rule applies to:**
+- Exact phrases and paraphrases
+- Implications of success
+- ANY communication suggesting completion/correctness
+
+## Enforcement
+
+The `verify-before-ship` extension shipped by pi-gauntlet watches `git commit`, `git push`, and `gh pr create`. If you have not run a passing recognised verification command since your last source-file edit in this session, an advisory warning is injected into the tool result. The warning clears automatically after a fresh passing run.
+
+Defaults recognise `make ci`, `make test`, `npm test`, `pnpm test`, `yarn test`, `pytest`, `rspec`, `cargo test`, `go test`. Projects can override (or narrow) the list via `settings.json#piGauntlet.verifyBeforeShip.testCommands`.
+
+Before running the verification gate, call `phase_tracker({ action: "start", phase: "verify" })`.
+
+When all verification passes, mark the verify phase complete:
+
+```
+phase_tracker({ action: "complete", phase: "verify" })
+```
+
+## 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/verification-before-completion/reference/conformance-check.md

@@ -0,0 +1,220 @@
+# Deliverable Conformance Check
+
+Tests passing proves the code runs. It does **not** prove the code does what was
+asked. This check confronts deliverables (code **and** docs) against the
+requirements.
+
+## Why this is distinct from code review
+
+Work flows `prompt/spec → plan → code/doc`. Each hop is lossy: the plan can
+drop or reinterpret a requirement, and code can drift from the plan. Reviewing
+**plan vs code** (what `/skill:requesting-code-review` does) is *single-step*
+verification — it confirms the last hop, but inherits any drift the plan already
+introduced.
+
+This check is the **closing loop**: confront the final outcome (code + doc)
+against the *origin* (spec + original prompt), skipping the plan. It catches
+requirements lost anywhere in the chain, not just in the last step. Run it even
+when plan-vs-code review passed clean — they measure different things against
+different reference points.
+
+## Dispatch a fresh reviewer (primary path)
+
+The main session built the thing — it has confirmation bias. Delegate the check
+to a fresh-context **`conformance-reviewer`** — a persona built for exactly this
+gate: its priorities are requirement coverage and intent fidelity, not code
+quality, and it emits a per-requirement coverage verdict rather than a bug list.
+It reads the requirements vs the diff cold and cannot see session history, so
+pass in:
+
+- The **spec** (path).
+- The **original prompt** (verbatim — it holds inline requirements + any ticket ref).
+- The **diff** to audit (code + docs).
+
+Dispatch it as its **own** call — do not fold the conformance check into the
+whole-PR code-quality review. Fusing the two subordinates intent-coverage to a
+code-quality system prompt and compresses the conformance result to an
+afterthought. Code quality is one dispatch; conformance is another.
+
+The persona ships model-free. Read the active preset's settings at
+`$PI_CODING_AGENT_DIR/settings.json` for `piGauntlet.closureReview.model` and
+inject it **call-site** on the dispatch (`model:` if set, else omit to inherit the
+parent's model) — the same mechanism the spec-council chair uses. If the configured
+model is unreachable, retry once with the inherited model. Point it at the strongest
+reasoning model the preset can reach — this is the last correctness gate.
+`thinking` stays frontmatter-pinned at `xhigh` and is not call-site overridable, so
+the config supplies only `model`.
+
+Self-checking in the main session is the fallback when delegation isn't possible.
+
+## Source of truth (priority order)
+
+| Order | Source | Why |
+|---|---|---|
+| 1 | The written spec (`doc/specs/…`) | Canonical. Brainstorm already fetched the ticket, reconciled its ACs, recorded deviations here. |
+| 2 | Original prompt | Catches inline requirements never folded into the spec. |
+| 3 | Re-fetch the ticket | **Fallback only**, when no spec exists. Skip when a spec exists — the live ticket may have drifted. |
+
+Project's issue-tracker skill (for the fallback) is named in `.pi/gauntlet-overrides.md`.
+
+## Drift = red flag
+
+Spec vs prompt/ticket disagree → **STOP and reconcile**, do not absorb silently.
+
+- Intentional, recorded deviation → spec wins (it was review-gated).
+- Unrecorded divergence → spec silently dropped/altered a requirement = conformance
+  failure. Fix spec or code, re-verify. No completion claim over unreconciled drift.
+
+## Coverage rule
+
+Default: **1 requirement source = 1 spec = code covering every requirement.**
+The requirement source is whatever sits at the top of the priority table — a
+ticket if there is one, otherwise the spec + original prompt. No ticket is fine;
+spec + prompt is a first-class source, not a degraded one. "Every requirement" =
+explicit acceptance criteria / spec clauses **+** implicit notes (ticket body,
+comments, or inline in the prompt). Source and solution must end in sync.
+
+Multi-spec effort → allowed **only if the spec explicitly says** it covers a
+defined subset and names the deferred requirements. Silent partial coverage = failure.
+
+## When the check finds gaps
+
+The reviewer **proposes, it does not dispose.** It emits structured gap blocks
+(see `agents/conformance-reviewer.md`); the orchestrator (the main session running
+the verify gate) drives disposition, fixes, and re-audit. The reviewer never edits,
+dispatches, or re-audits itself.
+
+### CONFORMS
+
+Record the verdict in the completion summary's closure section and proceed.
+
+### GAPS — disposition menu
+
+Do **not** auto-proceed and do **not** auto-fix. Render the enumerated gap list —
+each as `Gn [VERDICT] origin — remediation (recommended: fix|accept|rescope)` — then
+a numbered prompt (a chat turn cannot express a bare keystroke):
+
+```
+[1] apply all recommended dispositions
+[2] review per-gap (override fix/accept/rescope before applying)
+```
+
+`[1]` applies each gap's `recommended` disposition, **except** any gap whose
+`recommended` is `accept` or `rescope`: list those and require an explicit confirming
+reply before their spec edits land (accept/rescope rewrite the origin — never on the
+unconfirmed fast path). `[2]` prompts a per-gap override, then applies.
+
+Disposition semantics:
+
+- `fix` — dispatch a remediation unit (below), then re-audit. For an `UNAUTHORIZED`
+  gap, "fix" = **remove** the unrequested code.
+- `accept` — the **main session** (not a subagent) folds the deviation into the spec as
+  a dated decision (template below). For `UNAUTHORIZED`, accept = keep the behavior,
+  document it as intended.
+- `rescope` — the main session records the requirement in the spec as an explicit
+  out-of-scope / deferred item, dated.
+
+Dated-decision template (append to the spec's decisions/deviations section):
+
+```
+- YYYY-MM-DD accept|rescope Gn: <requirement/behavior> — <one-line rationale> (conformance gate)
+```
+
+**Commit accept/rescope spec edits BEFORE any fix wave dispatches:** pi-cohort
+rejects a dirty tree on a `worktree: true` dispatch, and the re-audit must read the
+amended spec. If a round has only accept/rescope and no `fix`, the edits land, the
+verdict is recorded, and no re-audit runs.
+
+### Fix dispatch — reuse dispatching-parallel-agents mechanics
+
+Fixes reuse the `dispatching-parallel-agents` fan-out primitive. Invoke **no**
+`phase_tracker` / `plan_tracker` calls and do **not** enter `subagent-driven-development`
+Parallel-Wave Mode (that mode opens with `phase_tracker({ phase: "implement" })`, which
+errors while the verify phase is `in_progress`, and needs a plan the fix loop lacks).
+
+**Precondition — worktree required.** Fix-via-dispatch needs a worktree HEAD to branch
+from. On the ad-hoc `finishing-a-development-branch` paths that run in a normal repo
+(`GIT_DIR == GIT_COMMON`) or detached HEAD, there is no such HEAD: the menu offers
+`accept` / `rescope` and **manual fix-in-place** only; unresolved gaps route to escalation.
+The loop below applies only when the gate already runs inside a worktree.
+
+**Wave grouping** comes from the reviewer's `Parallel-safe:` line: `disjoint` gaps form
+one parallel wave; any `conflicts` pair splits into separate serial waves. A pair conflicts
+on **file OR runtime-resource** overlap - two gaps whose fixes touch disjoint files but whose
+verification shares a `touched-resources` entry (DB/schema, port, fixture, external service,
+shared temp path) are **not** parallel-safe and run in separate serial waves, identical to
+planned-execution wave grouping. This is why the reviewer certifies both axes.
+
+**Dispatch shape** (mirrors `dispatching-parallel-agents`):
+
+```ts
+subagent({
+  context: "fresh",
+  worktree: true,
+  cwd: "<abs worktree path, from git rev-parse --show-toplevel>",
+  tasks: [
+    { agent: "implementer",
+      task: "Close conformance gap G1. Origin requirement: <origin>. What's missing: " +
+            "<remediation>. Satisfy the requirement; do not expand scope. " +
+            "Ownership boundary — modify only: <touched-files>." },
+    // one task per disjoint gap in this wave
+  ],
+})
+```
+
+- Unit = `implementer`, fresh context, `worktree: true`, `cwd` = the conformance
+  worktree. Pass `touched-files` as an explicit ownership boundary.
+- **Integrate** serially via `git apply` back onto the worktree HEAD — the fix ships in
+  the same worktree and rides `finishing-a-development-branch`'s squash. No new merge machinery.
+- **Failure handling is inherited verbatim** from `dispatching-parallel-agents`
+  "Review and Integrate": textual conflict → re-run one agent sequentially with the
+  other's integrated changes as context; semantic conflict (applies clean, suite fails)
+  → re-run the offending task sequentially on integrated HEAD; a failed agent → integrate
+  the successes, then retry the failure with fresh context including the integrated changes.
+  A `BLOCKED` / `NEEDS_CONTEXT` return surfaces to the user.
+- **`code-reviewer` over the integrated fix delta, once per round** (not per gap) — gap
+  fixes land after the branch's final code review, so review the round's cumulative diff.
+- **`spec-reviewer` is excluded** — plan-vs-code is the wrong reference point; the re-audit
+  checks fixes against the origin.
+- **Test gate** on the integrated tree after the round's waves apply, using the project's
+  canonical test command. A failure re-enters the failure-handling rules above.
+
+One round = dispatch waves → serial integrate → `code-reviewer` on round delta → test
+gate → re-audit.
+
+### Delta re-audit + cap
+
+Re-dispatch `conformance-reviewer` for a delta-scoped re-audit. Pass:
+
+- the **full prior conformance report** — every row including DELIVERED rows and their
+  `evidence` `file:line` (needed for the regression guard), not just gap IDs;
+- the **fix diff** for the round.
+
+The reviewer (not the orchestrator) computes the regression intersection: it re-verifies
+the gaps marked `fix` this round **plus** any previously-DELIVERED requirement whose
+`evidence` file appears in the fix diff. It reuses `G1..Gn`, marking each `DELIVERED`,
+still-open with its prior verdict, or introducing `Gn+1`.
+
+- The re-audit dispatch carries the **same call-site `model:` injection** as the initial
+  audit (when `piGauntlet.closureReview.model` is set, the phase-tracker closure guard
+  requires every `conformance-reviewer` dispatch to specify `model:`).
+- New or still-open gaps within the cap re-enter the menu above.
+- **Cap: read `piGauntlet.closureReview.maxFixRounds`** (default `2`; missing/non-integer
+  → `2`; `< 0` → `0`). `0` = audit-only: `GAPS` renders an accept/rescope-only menu and any
+  unresolved gap escalates instead of dispatching a fix.
+- **On non-convergence** (cap reached with open gaps): **escalate to human** with the
+  per-gap round-by-round verdict trail. No silent re-loop, no auto-ship.
+
+No completion claim stands over a gap that is neither fixed, accepted, nor rescoped.
+"Surface, don't auto-fix": the orchestrator presents options, the user decides.
+
+## Checklist
+
+- [ ] Located canonical requirements (spec → prompt → ticket fallback)
+- [ ] Enumerated every requirement: explicit ACs / spec clauses + implicit notes + inline prompt reqs
+- [ ] Checked spec ↔ prompt/ticket drift; reconciled any divergence
+- [ ] Each requirement mapped to where it's satisfied (code/doc) + evidence
+- [ ] Multi-spec? Subset declared in spec; deferred ACs noted as out of scope
+- [ ] Gaps reported, or all rows satisfied
+
+Can't check all boxes (or unreconciled drift)? Not complete. Report the gap.

package/skills/writing-plans/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: writing-plans
+description: Use when you have a spec or requirements for a multi-step task, before touching code
+---
+
+> **Related skills:** Reached via the auto-chain from `/skill:brainstorming` (not a direct human entry point). On completion this skill auto-invokes `/skill:subagent-driven-development`.
+
+# Writing Plans
+
+## Overview
+
+Translate an approved spec into bite-sized, ordered, TDD-shaped tasks. Assume the engineer is skilled but has zero context for this codebase and limited taste — document file paths, exact commands, expected output, and test design.
+
+DRY. YAGNI. TDD. Frequent commits.
+
+**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
+
+Before drafting the plan, call `phase_tracker({ action: "start", phase: "plan" })`.
+
+**Input:** an approved spec in `<project>/doc/specs/<filename>.md` (produced by `/skill:brainstorming`).
+
+**Save plans to:** the sibling `doc/plans/` directory next to the spec. The plan filename matches the spec filename exactly — same date, same Linear ID (if any), same topic slug, no `-design` suffix.
+
+| Spec path | Plan path |
+|---|---|
+| `doc/specs/2025-05-26-foo.md` | `doc/plans/2025-05-26-foo.md` |
+| `doc/specs/2025-05-26-PROJ-1234-foo.md` | `doc/plans/2025-05-26-PROJ-1234-foo.md` |
+| `<service>/doc/specs/<name>.md` | `<service>/doc/plans/<name>.md` |
+
+If no spec exists, send the work back to `/skill:brainstorming`. Do not invent a plan without a spec.
+
+## Boundaries
+
+- Read code and docs: yes
+- Write the plan to the sibling `doc/plans/` of the spec: yes
+- Edit or create any other files: no
+- Write implementation code: never inside this skill. After Self-Review + `phase_tracker` complete, auto-invoke `/skill:subagent-driven-development` to execute.
+- Land the plan on `main`: no — the plan commit goes on the worktree branch (same branch as the spec)
+
+## Scope Check
+
+Before writing the plan, check the spec one more time for hidden subsystem boundaries:
+
+- Does this touch 2+ independent services / contracts / schemas?
+- Are there phases where intermediate state needs to be deployable?
+
+If yes, decompose into separate plans and call it out:
+
+> "The spec covers A and B. I'd split into two plans, executed in order. OK?"
+
+A single plan should land in one PR worth of work. Multi-PR sequences get separate plans.
+
+## File Structure
+
+**Before drafting tasks, map the files.**
+
+List the files this implementation will create, modify, or delete. Group by component. This forces the design decisions out of the task list and into a single review surface.
+
+```markdown
+## Files
+
+**Create:**
+- `src/services/foo.py`
+- `tests/services/test_foo.py`
+
+**Modify:**
+- `src/controllers/bar.rb` (add `create` action)
+- `db/migrate/YYYYMMDDHHMMSS_add_baz.rb`
+
+**Delete:**
+- `src/services/legacy_foo.ts`
+```
+
+If you can't list the files, the spec isn't ready. Send it back to `/skill:brainstorming`.
+
+## Wave Grouping
+
+Group tasks into **waves** so the executor can parallelize independent work (see `subagent-driven-development` Parallel-Wave Mode). A wave is a maximal set of tasks that (a) have no ordering dependency on each other, (b) own **pairwise-disjoint files**, and (c) contend on **no shared mutable runtime resource** (same DB/schema, port, fixture file, external service, shared temp path).
+
+- Tasks nest under `## Wave N — <label>` headers; `### Task N` headers sit inside a wave.
+- A wave with one task is legal (runs sequentially). A pure dependency chain yields one task per wave — no parallelism, which is correct.
+- Each wave after the first states its dependency on prior waves.
+
+**File-ownership contract.** The per-task `**Files:**` block *is* the ownership declaration — no new syntax. Rule: **within a wave, the union of every task's declared paths must be pairwise disjoint.** Globs are allowed for `Modify` when exact paths are unknown, but must not overlap another same-wave task's paths. A task that must touch another's file belongs in a later wave.
+
+**Runtime-resource disjointness.** File-disjoint is necessary but not sufficient: two tasks with disjoint files that both mutate the same DB, bind the same port, or share a fixture are **not** parallel-safe and must land in different waves. The executor auto-selects parallel for *every* multi-task wave, so this grouping is the sole parallel-safety guarantee — there is no selection-time judgment downstream. No new mandatory per-task syntax; when a shared runtime resource is the reason two file-disjoint tasks sit in different waves, record it in an inline note on the later wave.
+
+```markdown
+## Wave 1 — Foundations
+
+Parallel-safe: Tasks 1–3 own disjoint files (see each task's Files block).
+
+### Task 1: ...
+### Task 2: ...
+### Task 3: ...
+
+## Wave 2 — Wire-up
+
+Depends on Wave 1: Task 4 consumes the API introduced by Task 1.
+
+### Task 4: ...
+```
+
+## Bite-Sized Task Granularity
+
+Each step is **one action, 2-5 minutes**:
+
+- "Write the failing test" — step
+- "Run it, confirm it fails" — step
+- "Implement minimal code to pass" — step
+- "Run tests, confirm green" — step
+- "Commit" — step
+
+## Plan Document Header
+
+```markdown
+# [Feature Name] Implementation Plan
+
+> **REQUIRED SUB-SKILL:** Use the subagent-driven-development skill to implement this plan task-by-task.
+
+**Goal:** [one sentence]
+
+**Architecture:** [2-3 sentences]
+
+**Tech Stack:** [key tech/libraries]
+
+**Spec:** `<project>/doc/specs/<same-filename-as-this-plan>.md`
+
+**Linear:** `E-XXXX` (omit if no ticket)
+
+---
+```
+
+## Task Structure
+
+Each task uses `- [ ]` checkbox steps so execution tools (and humans) can track progress.
+
+```markdown
+### Task N: [Component Name]
+
+**TDD scenario:** [New feature — full TDD cycle | Modifying tested code — run existing tests first | Trivial change — use judgment]
+
+**Files:**
+- Create: `exact/path/to/file.py`
+- Modify: `exact/path/to/existing.py:123-145`
+- Test: `tests/exact/path/to/test.py`
+
+- [ ] **Step 1: Write the failing test**
+
+  ```python
+  def test_specific_behavior():
+      result = function(input)
+      assert result == expected
+  ```
+
+- [ ] **Step 2: Run test, confirm failure**
+
+  Run: `uv run pytest tests/path/test.py::test_name -v`
+  Expected: FAIL with "function not defined"
+
+- [ ] **Step 3: Write minimal implementation**
+
+  ```python
+  def function(input):
+      return expected
+  ```
+
+- [ ] **Step 4: Run test, confirm pass**
+
+  Run: `uv run pytest tests/path/test.py::test_name -v`
+  Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+  ```bash
+  git add tests/path/test.py src/path/file.py
+  git commit -m "<imperative subject> (ref E-XXXX)"
+  ```
+```
+
+## No Placeholders
+
+Every plan failure mode:
+
+- ❌ `# TODO: add validation` — implementer can't infer "validation" of what, against what schema, with what error message.
+- ❌ `# Implement the rest of the function` — incomplete code is invalid code.
+- ❌ "Add tests for edge cases" — name the edge cases.
+- ❌ "Wire it up to the existing system" — give file paths and call sites.
+- ❌ "Similar to Task N" — repeat the code. Implementers (and subagents with fresh context) may read tasks out of order; pointing at a sibling task is not a substitute for showing the code.
+- ❌ References to types, functions, methods, or fields not defined in any task in this plan. If it shows up in Task 5, it must be introduced by Task 1–4 or already exist in the codebase (with a file:line citation).
+- ❌ `[fill in]`, `<example>`, `xxx` markers anywhere in the doc.
+- ❌ "Probably also need to update the docs" — either yes (which doc) or no.
+
+If a decision is genuinely open, put it in an explicit **Open Questions** section at the top and resolve before execution starts.
+
+## Self-Review (Before Handoff)
+
+After drafting the plan and before announcing it complete, run three checks yourself. This is a checklist you run yourself — not a subagent dispatch.
+
+- **Spec coverage.** Cross-reference the spec's components/decisions/constraints against the plan. Does every spec section map to one or more tasks? If a spec decision has no implementation task, the plan is missing work or the spec was overspecified.
+- **Placeholder scan.** Grep the doc for `TODO`, `TBD`, `xxx`, `[fill in]`, `<example>`, `etc.`, "probably", "something like". Resolve or convert each into an explicit Open Question.
+- **Type / API consistency.** Function signatures and field names that appear in multiple tasks must match exactly. The plan is its own contract — internal contradictions surface as bugs during execution.
+- **Wave disjointness.** For every multi-task wave, confirm the tasks' `Files:` sets are pairwise disjoint **and** that no two tasks contend on a shared mutable runtime resource (DB/schema, port, fixture, external service, shared temp path). Either kind of overlap = mis-grouped wave; split or re-order before handoff.
+
+Fix what this review finds before handoff.
+
+## Remember
+
+- Exact file paths always
+- Complete code in plan (not "add validation")
+- Exact commands with expected output
+- Reference relevant skills
+- DRY, YAGNI, TDD, frequent commits
+- Group dependency-free, file-disjoint tasks into the same wave; order waves so each wave's dependencies are satisfied by earlier waves
+- If the plan exceeds ~8 tasks, split into phases with checkpoints
+
+## Execution Handoff
+
+After saving the plan, mark the planning phase complete:
+
+```
+phase_tracker({ action: "complete", phase: "plan" })
+```
+
+Then auto-select the execution mode and proceed — no pause, no picker. The mode is a pure function of the plan's wave structure:
+
+- **If any wave contains ≥2 tasks → Parallel-Wave Mode.** The strengthened Wave Grouping contract (files + runtime-resource disjoint) guarantees every multi-task wave is parallel-safe.
+- **Otherwise (pure dependency chain, one task per wave) → Sequential Mode.**
+
+Announce the selected mode in one line (transparency), then auto-invoke `/skill:subagent-driven-development` in this session. Do not wait for confirmation — the spec gate already happened, and the plan is a mechanical derivative. The only pauses from here are in-flight STOPs (`BLOCKED` / `NEEDS_CONTEXT`) and the end gate, both owned by the executor.
+
+## Red Flags — STOP
+
+- Plan contains TODO / TBD / placeholder text
+- File structure section absent
+- Task step is "5+ minutes of work" (split it)
+- Step lists don't use `- [ ]` checkboxes
+- Two tasks reference the same function with different signatures
+- Self-review skipped
+- About to start executing the plan yourself
+
+## 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.