pi-gauntlet 4.1.0 → 4.2.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## v4.2.0 - 2026-07-04
+
+Documents become first-class origin requirements, the post-execution review stack
+is deduplicated, and this repo now dogfoods its own workflow (GitHub #1 + folded-in B/C/D/E).
+
+- **Part A - docs as first-class origin.** New shared reference
+  `skills/brainstorming/reference/documentation-impact.md` defines a materiality
+  bar (seven inclusion categories + a litmus test, an anti-flooding exclusion list,
+  and amend-over-create) so only meaningful docs earn a place. `brainstorming` gets
+  a required `## Documentation impact` spec section (three classes: introduced /
+  materially amended / derived-memory invalidated); `writing-plans` turns doc updates
+  into real tasks + a trailing doc-only wave; `conformance-check.md` names spec docs
+  as origin requirements the existing pass already verifies. No new pass or agent.
+- **Part B - review-stack dedup.** `subagent-driven-development`'s post-execution
+  stack collapses from a duplicated whole-diff review to one `requesting-code-review`
+  plus the separate `conformance-reviewer`; the auto-fired project-audit supplement
+  is removed (consumers re-wire via `.pi/gauntlet-overrides.md` or run it manually).
+  `agents/code-reviewer.md` severity and `README.md` are decoupled from the example
+  self-audit skill. Execution-phase per-task/per-wave reviews are untouched.
+- **Part C - ephemeral-plan parity.** `finishing-a-development-branch` now strips the
+  plan doc before the PR push (guarded `git ls-files --error-unmatch`), symmetric with
+  the squash-merge path; the plan never lands on base.
+- **Part D - self-hosting mandate.** `AGENTS.md` mandates the full gauntlet for this
+  repo's own non-trivial changes and reframes the direct-edit recipes as implement-phase
+  mechanics.
+- **Part E - file-placement convention.** `writing-skills` codifies dispatch-payload
+  templates as `SKILL.md` siblings vs deep guidance in `reference/` (destination, not format).
+
 ## v4.1.0 - 2026-07-02
 
 - **`closureReview` now resolves repo-local first.** The verify-step skills

package/README.md

@@ -15,10 +15,10 @@ brainstorm → plan → implement → verify → ship
 1. **`brainstorming`** — every change starts here. Sets up an isolated worktree, explores the codebase, and turns the idea into a written spec under `doc/specs/`. A multi-model critique runs automatically before you read it (`roasting-the-spec` when a council is configured, else one fresh `worker`). **Hard gate:** no implementation code is written until you approve the spec.
 2. **`writing-plans`** — derives an implementation plan from the approved spec, decomposed into atomic, independently-verifiable tasks (grouped into parallel waves when they're file- and resource-disjoint). Auto-chains into execution.
 3. **`subagent-driven-development`** — executes the plan one atomic task at a time, each in a **fresh subagent**, behind a **two-stage review**: spec compliance first (`spec-reviewer`), then code quality (`code-reviewer`). The `implementer` persona is TDD-locked (RED→GREEN→REFACTOR). You orchestrate; you never hand-write the code.
-4. **verify** — after the last task: a whole-diff review (`requesting-code-review`, plus any project-specific `self-audit` supplement), then the `conformance-reviewer` closing-loop gate that confronts the delivered code **and** docs against the *origin* (spec + your verbatim original prompt), not the plan. The phase-tracker **blocks `complete verify`** until a conformance dispatch has run, and on a successful `complete verify` (ship still pending) injects an advisory to invoke `finishing-a-development-branch` immediately without a redundant "ready to finish?" prompt - or to reopen verify if a requirement decision is still open.
+4. **verify** — after the last task: a whole-diff review (`requesting-code-review`), then the `conformance-reviewer` closing-loop gate that confronts the delivered code **and** docs against the *origin* (spec + your verbatim original prompt), not the plan. The phase-tracker **blocks `complete verify`** until a conformance dispatch has run, and on a successful `complete verify` (ship still pending) injects an advisory to invoke `finishing-a-development-branch` immediately without a redundant "ready to finish?" prompt - or to reopen verify if a requirement decision is still open.
 5. **`finishing-a-development-branch`** — squash / PR / keep / discard. This menu is the single human decision gate at the end, mirroring spec approval at the start.
 
-Spec, plan, and implementation all live in the **same worktree** and ship as **one squash commit**.
+Spec, plan, and implementation are all developed in the **same worktree**. The squash commit ships spec and implementation; the plan is ephemeral and is stripped before any landing path.
 
 **Supporting skills** slot in as the pipeline needs them: `using-git-worktrees` (isolation, before the spec), `test-driven-development` (inside every implementer), `dispatching-parallel-agents` (wave fan-out), `systematic-debugging` (when something breaks), `receiving-code-review` (when you get feedback), `writing-skills` (authoring more of these).
 

package/agents/code-reviewer.md

@@ -40,7 +40,8 @@ Findings:
 Complexity: net -<N> lines   (omit if nothing to cut)
 ```
 
-Severity (aligned with the `self-audit` skill):
+Severity:
+
 - **Critical** — must fix before merge (data loss, security, broken correctness on a common path, broken contract).
 - **Moderate** — should fix; open for discussion (significant but not strictly blocking).
 - **Minor** — nit, style, preference, suggestion.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "type": "module",
   "license": "MIT",

package/skills/brainstorming/SKILL.md

@@ -78,7 +78,7 @@ The spec is the **first commit in a dedicated worktree**, not a separate commit
 2. Switch into the worktree.
 3. From there, write the spec, run self-review, commit, hand off.
 
-Spec doc, plan doc, and implementation all live in the same worktree and ship together as a single squash commit (see `/skill:finishing-a-development-branch`).
+Spec doc, plan doc, and implementation are all developed in the same worktree; the squash ships the spec and the implementation, with the ephemeral plan stripped before landing (see `/skill:finishing-a-development-branch`).
 
 **Exception:** trivial one-off edits the user explicitly asks for outside this skill flow (e.g. "fix this typo") do not require a worktree.
 
@@ -140,7 +140,16 @@ Cover at minimum:
 - Data flow (or request flow)
 - Error handling and edge cases
 - Testing approach
-- Documentation impact — name each doc that changes (README, AGENTS.md, CHANGELOG, API contracts, inline docs), or write "none". Doc updates ship in the same commit and are verified against the spec by the conformance gate.
+- Documentation impact — a required `## Documentation impact` section. Cite the materiality bar in `reference/documentation-impact.md` by relative path rather than restating its categories, and reproduce its template block verbatim:
+
+  ```markdown
+  ## Documentation impact
+  - Feature / user-facing docs introduced: <list, or "none">
+  - Materially amended existing docs: <list, or "none">
+  - Derived / memory docs invalidated: <routers / AGENTS.md sections / topic guides / indexes, or "none">
+  ```
+
+  Each entry answers with a doc name, "none", or "deferred: <trigger>". A new standalone `.md` appears only where no existing doc already owns the topic. Project-specific doc taxonomy goes in a `## documentation` block in `.pi/gauntlet-overrides.md` (no new settings key; guidance only). Doc updates ship in the same commit and are verified against the spec by the conformance gate.
 
 Be ready to go back and clarify when something doesn't make sense.
 
@@ -188,7 +197,7 @@ After writing the spec to `<project>/doc/specs/<filename>.md` (per [Filename Con
 
 - **Placeholder scan.** Any `TODO`, `TBD`, `<fill in>`, `[example]`, `xxx`? Either resolve them or convert to explicit "Open Questions" with names.
 - **Internal consistency.** Does Section 4 contradict Section 2? Are component names and field names consistent throughout?
-- **Documentation named.** Does the spec state which docs change (or an explicit "none")?
+- **Documentation named.** Does the spec name all three classes (feature/user-facing introduced; materially amended; derived/memory invalidated), or an explicit "none" for each? Enforce the materiality bar in `reference/documentation-impact.md` without restating it: each listed doc names the category it clears, none is a code-mirror, amend-over-create was applied, and skill/agent bodies are implementation surface, not doc-impact entries here.
 - **Scope check.** Does every paragraph serve the goal? Cut filler. If something is out of scope, say it's out of scope.
 - **Ambiguity check.** Is every "we should…" backed by a concrete decision? Replace "we could probably" with "we will" or "we won't".
 

package/skills/brainstorming/reference/documentation-impact.md

@@ -0,0 +1,134 @@
+# Documentation Impact: the Materiality Bar
+
+The shared materiality bar for a spec's "Documentation impact" section. Several
+skills cite this doc by relative path rather than restating its rules.
+
+## Governing principle
+
+The governing principle: document what the code cannot tell you.
+
+The "Documentation impact" section is a **filter with a default of "none,"** not
+a prompt to produce documentation. A doc earns a line in that section only when
+it clears one of the categories below. Absence is the expected outcome for most
+changes - most changes touch no product-facing doc at all.
+
+## Scope + the three doc classes
+
+The section tracks **product-facing docs**: README, `AGENTS.md`, CHANGELOG,
+external / API contracts, and genuinely-new standalone guidance docs.
+
+Skill and agent bodies, and their `reference/` sub-docs, are **implementation
+surface** - the deliverable itself, tracked in the plan's file list - **not**
+doc-impact entries. Listing them here would just restate the diff.
+
+Within that scope, a spec's Documentation impact section enumerates three
+classes:
+
+- **Feature / user-facing docs introduced** - a new doc the change adds.
+- **Materially amended existing docs** - an existing product doc that gains a
+  new section or a changed contract.
+- **Derived / memory docs invalidated** - router entries (`AGENTS.md` sections),
+  topic guides, taxonomy indexes that go stale because of this change.
+
+## The seven inclusion categories
+
+These seven categories gate classes 1 and 2 (feature/user-facing introduced;
+materially amended) - selection by importance. Class 3 (derived/memory
+invalidated) uses a different, lighter test; see "Gating class 3" below.
+
+A doc earns its place in classes 1-2 only by clearing at least one of these.
+Categories are not mutually exclusive; one match is sufficient.
+
+**Litmus test for every category:** would a competent teammate need this
+written down to safely operate or extend the system without reading the diff
+or the code? If the code (or its tests) already answers it, it fails the bar.
+
+- **Major procedures / conventions** - how work is done here (workflow, review,
+  release discipline).
+- **Operations / tunable parameters** - env vars, thresholds, feature flags,
+  runbook / recovery steps. PASS: a new `PI_LENS_MAX_FILES` threshold, its
+  default, and when to change it. FAIL: restating that a function reads an
+  env var - the code already says that.
+- **Communication contracts / integrations** - API / wire / queue contracts,
+  cross-component boundaries.
+- **Architecture** - module boundaries, data flow, structural decisions.
+- **Major definitions** - the canonical definition of a load-bearing domain
+  term, concept, or invariant that multiple components depend on and no single
+  code location fully owns. PASS: the canonical meaning of a domain term
+  several components rely on. FAIL: a one-line type alias the code already
+  names in full.
+- **Non-obvious rationale / decisions that outlive the PR** - the "why," and
+  why not the obvious alternative. PASS: why a simpler, obvious approach was
+  rejected, recorded so it is not re-litigated later. FAIL: a restatement of
+  what the chosen code does.
+- **Security, data-access & permissions** - trust boundaries, who can access
+  what, data-handling and permission decisions.
+
+## Gating class 3
+
+Class 3 ("Derived / memory docs invalidated") is not gated by the seven
+categories above. A router entry, topic guide, or taxonomy index is
+invalidated by drift, not selected by topical weight. The test is: an
+existing doc's content is now wrong or misleading because of this change.
+If so, it belongs in class 3 regardless of whether it would clear any of the
+seven categories. A citing skill (for example `writing-plans`, which sources
+doc-update tasks from this section) must not apply the seven-category filter
+to class 3 entries.
+
+## Exclusion / anti-pattern list
+
+None of the following clears the bar, no matter how it is framed:
+
+- Per-symbol or per-module narration.
+- Restating signatures, types, or schemas the code already owns.
+- "How it works" prose that reading the code answers directly.
+- Anything that would need an edit on every code change - the code-mirror
+  tell: if a doc rots the moment the function it describes changes, it was
+  never documentation, it was a copy.
+
+In-code doc comments such as RDoc/JSDoc are out of scope for this bar; it
+governs standalone `.md` docs only, and the same "no code-mirror" rule
+applies to both: a narrow markdown file that mirrors one function or one
+module fails the bar the same way an inline doc comment would.
+
+## Amend over create
+
+Clearing the bar does not default to a new file. **Extend the canonical
+existing doc that owns the topic.** When ownership is ambiguous, extend the
+most specific existing doc that already discusses the surrounding topic; a
+new standalone `.md` is justified only when zero existing docs mention the
+topic at all - this is the anti-proliferation rule, and it is why most
+changes that clear the bar still show up under "materially amended," not
+"introduced."
+
+## The section template
+
+Reproduce this block exactly in a spec's "Documentation impact" section:
+
+```markdown
+## Documentation impact
+- Feature / user-facing docs introduced: <list, or "none">
+- Materially amended existing docs: <list, or "none">
+- Derived / memory docs invalidated: <routers / AGENTS.md sections / topic guides / indexes, or "none">
+```
+
+Each entry answers with a doc name, `"none"`, or `"deferred: <trigger>"` (for
+example, `CHANGELOG.md - deferred: release`, when a doc changes on a known
+later event and should not be flagged as missing before that event fires).
+
+## Referenced by
+
+Keep this list in sync with the skills that cite this doc:
+
+- `brainstorming` section 6 and its Spec Self-Review check.
+- `writing-plans` - sources doc-update tasks from the spec's Documentation
+  impact section.
+- `verification-before-completion/reference/conformance-check.md` - docs named
+  here are origin requirements the conformance pass verifies.
+- `finishing-a-development-branch` Step 1's doc-impact pointer.
+
+## Project-specific taxonomy
+
+This doc is generic. Project-specific doc taxonomy (which docs a given
+project treats as canonical for which topic) lives in a project's
+`.pi/gauntlet-overrides.md`, in a `## documentation` section - not here.

package/skills/finishing-a-development-branch/SKILL.md

@@ -42,7 +42,7 @@ Stop. Don't proceed to Step 2.
 
 **If tests pass:** Continue to Step 2.
 
-No documentation prompt here: doc impact is decided at spec time (`/skill:brainstorming` section 6) and has already shipped in the diff by the time you reach finishing.
+No documentation prompt here: Documentation impact is decided at spec time (`/skill:brainstorming` section 6, gated by `brainstorming/reference/documentation-impact.md`) and has already shipped in the diff by the time you reach finishing.
 
 ### Step 2: Detect Environment
 
@@ -154,6 +154,12 @@ git branch -d <feature-branch>
 #### Option 2: Push and Create PR
 
 ```bash
+# Plans are ephemeral - if one was committed on this branch, remove it before the PR diff is opened.
+PLAN_PATH=doc/plans/<plan-file>.md   # or <service>/doc/plans/<plan-file>.md
+if git ls-files --error-unmatch "$PLAN_PATH" >/dev/null 2>&1; then
+  git rm "$PLAN_PATH" && git commit -m "Remove ephemeral plan doc"
+fi
+
 # Push branch
 git push -u origin <feature-branch>
 
@@ -235,12 +241,12 @@ git worktree prune  # Self-healing: clean up any stale registrations
 
 ## Quick Reference
 
-| Option | Merge | Push | Keep Worktree | Cleanup Branch |
-|--------|-------|------|---------------|----------------|
-| 1. Squash-merge locally | yes (squash) | - | - | yes |
-| 2. Create PR | - | yes | yes | - |
-| 3. Keep as-is | - | - | yes | - |
-| 4. Discard | - | - | - | yes (force) |
+| Option | Merge | Push | Keep Worktree | Cleanup Branch | Plan-doc removal |
+|---|---|---|---|---|---|
+| 1. Squash-merge locally | yes (squash) | - | - | yes | yes (unconditional) |
+| 2. Create PR | - | yes | yes | - | yes (guarded, before push) |
+| 3. Keep as-is | - | - | yes | - | - |
+| 4. Discard | - | - | - | yes (force) | - |
 
 ## Common Mistakes
 
@@ -272,7 +278,7 @@ git worktree prune  # Self-healing: clean up any stale registrations
 - **Problem:** Accidentally delete work
 - **Fix:** Require typed "discard" confirmation
 
-**Skipping the plan-doc deletion in Option 1**
+**Skipping the plan-doc deletion in Options 1 and 2 (any path that lands on base)**
 - **Problem:** Plan docs are ephemeral and shouldn't land on `<base-branch>`. Forgetting `git rm doc/plans/<plan-file>.md` ships scaffolding to main.
 - **Fix:** The plan stays in the deleted branch's git history (`git log --all -- doc/plans/...`). Spec stays on `<base-branch>`; plan does not.
 
@@ -295,6 +301,7 @@ phase_tracker({ action: "complete", phase: "ship" })
 - Clean up worktrees you didn't create (provenance check)
 - Run `git worktree remove` from inside the worktree
 - Present finish options while a conformance gap is open and undispositioned
+- Skip the guarded plan-doc removal before push on Option 2 when a plan doc was committed
 
 **Always:**
 - Verify tests before offering options

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

@@ -60,7 +60,7 @@ For each task in `plan_tracker`:
 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).
+After all tasks: run the whole-diff code review (`requesting-code-review`). Then [After All Tasks](#after-all-tasks-complete).
 
 ## Implementer Status
 
@@ -86,7 +86,6 @@ Pi-subagents accepts a per-task `model` override. Use it.
 | 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`, resolved repo-first whole-object, injected call-site) |
 
 ```ts
@@ -188,11 +187,10 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
 ## 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.
+1. **Run the whole-diff code review.** Dispatch `/skill:requesting-code-review` against the worktree's full diff vs `main` (already covered in [The Process](#the-process) step "After all tasks"). Address Critical and Moderate findings before handoff. (Consumers wanting an in-flow project-specific audit re-add it as an explicit step in `.pi/gauntlet-overrides.md`, or run `/self-audit` manually.)
+2. **Close the loop — conformance check.** The review in step 1 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 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" })`.
+3. Summarize what was implemented (tasks completed, files changed, test counts, code-review 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 review verdict.
+4. **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 2, 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
 

package/skills/verification-before-completion/reference/conformance-check.md

@@ -2,7 +2,12 @@
 
 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.
+requirements. Docs named in a spec's "Documentation impact" section - any of
+the three classes (introduced, materially amended, derived/memory invalidated) -
+are origin requirements the same as code: a missing or drifted doc from that
+section is a conformance gap, not a code-review nit. See
+`../../brainstorming/reference/documentation-impact.md` for what that section
+contains and how its entries are scoped.
 
 ## Why this is distinct from code review
 

package/skills/writing-plans/SKILL.md

@@ -85,6 +85,10 @@ Group tasks into **waves** so the executor can parallelize independent work (see
 
 **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.
 
+**Doc tasks.** Doc updates are real plan tasks, not an afterthought. Task-local docs (a doc that only describes the file(s) a task already touches) ride with that task. Cross-cutting or index docs (README, `AGENTS.md`, topic guides, taxonomy indexes) sequence into a dedicated trailing doc-only wave — last wave by convention, file-disjoint from every code task so the pairwise-disjoint wave contract holds.
+
+**Doc-wave collision rule.** Amend-over-create (see `brainstorming/reference/documentation-impact.md`) concentrates edits into hub docs like README and `AGENTS.md`. A doc wave with ≥2 tasks auto-selects Parallel-Wave Mode, which requires pairwise-disjoint files — so doc tasks that land on the *same* file merge into one task rather than splitting. A single-task trailing doc wave is the expected shape, not a smell.
+
 ```markdown
 ## Wave 1 — Foundations
 
@@ -189,7 +193,7 @@ Every plan failure mode:
 - ❌ "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.
+- ❌ "Probably also need to update the docs" — either yes (which doc) or no. Docs are named plan tasks, sourced from the spec's Documentation impact section (materiality bar in `brainstorming/reference/documentation-impact.md`).
 
 If a decision is genuinely open, put it in an explicit **Open Questions** section at the top and resolve before execution starts.
 
@@ -197,7 +201,7 @@ If a decision is genuinely open, put it in an explicit **Open Questions** sectio
 
 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.
+- **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. Each Documentation impact entry maps to a plan task (or explicit "none").
 - **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.

package/skills/writing-skills/SKILL.md

@@ -36,11 +36,14 @@ Each skill directory contains:
 SKILL.md              # required entry point
 reference/            # optional progressive-disclosure files
   <topic>.md          # read directly when SKILL.md points at it
-<supporting>.md       # prompt templates, examples
+  examples.md         # read directly when SKILL.md points at it
+<supporting>.md       # prompt templates (dispatch payloads)
 ```
 
 `reference/` is the pi pattern for keeping SKILL.md tight while still shipping deep guidance. See `.pi/skills/test-driven-development/reference/` and `.pi/skills/systematic-debugging/reference/` for working examples.
 
+Prompt templates and other dispatch payloads - files filled in and passed wholesale into a subagent `task` - live as siblings of SKILL.md, not under `reference/`. See `requesting-code-review/code-reviewer.md` and the three `subagent-driven-development/*-prompt.md` files. The decision criterion is destination, not format: a file passed wholesale into a subagent's `task` is a sibling; a file read at a decision point for deep guidance, examples, or rationale is `reference/`. Some older skills (`systematic-debugging`, `test-driven-development`) keep deep-guidance `*.md` files flat as siblings, predating the `reference/` convention (obra/superpowers lineage) - that is descriptive history, not a mandate to move them.
+
 ### Reference Files Bundled With This Skill
 
 Read directly when SKILL.md tells you to (path is given inline). The progressive-disclosure pattern is *which file to read when*, not a special tool: