task-pipeline-skill 0.12.0 → 1.0.0

package/cursor/rules/task-pipeline.mdc

@@ -1,15 +1,19 @@
 ---
-description: "task-pipeline: run a substantial task through a disciplined, gated delivery cycle — an intake grill that expands the request, then docs→brainstorm→spec→plan→build→tests→lint/deploy→post-deploy→docs. Apply when the user asks to run a task through the pipeline, the full cycle / полный цикл / прогони по конвейеру, or starts any substantial feature/fix/build."
+description: "task-pipeline: run a substantial task through a disciplined, gated delivery cycle — an intake grill that expands the request into a checkable requirement list, then docs→brainstorm→spec→plan→build→tests→lint/deploy→post-deploy→docs/wiki→acceptance. Apply when the user asks to 'run this through the pipeline' / 'прогони по конвейеру', asks for 'the full cycle' / 'полный цикл', or starts any substantial feature/fix/build."
 alwaysApply: false
 ---
 
 # task-pipeline — gated delivery cycle (Cursor)
 
 Self-contained rule (Cursor copies this file into projects — no external links).
-Run a substantial task through an up-front **intake grill + 9 gated stages**. No
+Run a substantial task through an up-front **intake grill + 10 gated stages**. No
 stage advances until its **gate** passes. Each gate is `auto` (verify it yourself,
 pass/fail) or `manual` (wait for the user's explicit go).
 
+**No companion skill is required.** Every rule below is the doctrine itself — the
+grill, the design gate, the plan format, the build loop and TDD. Nothing to
+install, nothing to resolve, nothing that breaks when a plugin is missing.
+
 ## Model — decide once, before you start
 
 Recommended: **the most capable reasoning model the environment offers** (at time
@@ -24,16 +28,42 @@ recommended tier isn't available, say which one you're using and continue.
 
 Never skipped, and nothing to install — the grill is part of this rule. No "the
 task was already clear" exemption, no starting stage 1 while the user thinks. A
-one-line task ("build feature X") is not enough to finish autonomously. Grill the
-user up front, then run the rest without mid-flight questions:
+one-line task ("build feature X") is not enough to finish autonomously.
+
+**Phase 1 — harvest the sources BEFORE the first question.** Find what the project
+already knows about this task and read it: the code; `CLAUDE.md` / `AGENTS.md`;
+`CONTEXT.md` (or `CONTEXT-MAP.md`) and `docs/adr/`; `docs/` and `docs/ux/`; past
+briefs/plans and their carry-over ledgers; **the knowledge wiki if one is
+installed** — [obsidian-wiki](https://github.com/ar9av/obsidian-wiki), detect
+`~/.obsidian-wiki/config` or a resolving `wiki-query`; and **any other repository
+or hosted doc system the project names as its docs** (read-only, and never a source
+you invented — it counts because the project names it). Query each by *this task's*
+nouns; it is retrieval, not a full read; stop when the terms return nothing new.
+Write a short **source ledger** into the brief — source, what it says about this
+task, how fresh, and whether this run makes it stale. `none found` is a valid row.
+If no wiki is installed, recommend it once and continue:
+`pip install obsidian-wiki` → `obsidian-wiki setup --vault <path>`. It is never a
+gate.
+
+**Phase 2 — grill the user against that harvest**, then run the rest without
+mid-flight questions:
 1. One question per turn — never bundle.
 2. Give a recommended answer with every question (+ one-line rationale).
 3. Explore the codebase before asking — if a search/read answers it, do that.
-4. Walk the decision tree depth-first; ask prerequisite decisions first.
-5. Reconcile contradictions; chase dodges ("decide later" → "latest you can decide
+4. **Validate every answer against the harvest.** When what the user says
+   contradicts a doc you read, quote the doc and ask which governs: *"the March ADR
+   says X, you just described Y — has it changed?"* The user **outranks every
+   document, but only out loud** — an override quoted against its source is a
+   recorded decision; an unquoted one is an undetected divergence that every later
+   gate will pass over. When two sources disagree: code > host docs/ADRs > wiki >
+   memory. Whichever side loses, if it's written down somewhere, log it for the
+   stage-9 doc update.
+5. Walk the decision tree depth-first; ask prerequisite decisions first.
+6. Reconcile contradictions; chase dodges ("decide later" → "latest you can decide
    and still ship?").
-6. Run the **autonomy sweep** — resolve now whatever would stop stages 1→9 later:
-   external libs and where their docs live; UI verdict; base branch, branch policy,
+7. Run the **autonomy sweep** — resolve now whatever would stop stages 1→10 later:
+   external libs and where their docs live; **which doc sources beyond this repo are
+   in play and whether stage 9 may write to them**; UI verdict; base branch, branch policy,
    commit convention, task tracker; the test command and what "green" means; the
    lint command; the deploy target, release toggle and **deploy authorization**;
    where logs/health live; which docs and runbooks this change updates. Each item
@@ -55,6 +85,19 @@ Offer an ADR (`docs/adr/NNNN-slug.md`, 1–3 sentences is a complete ADR) only w
 all three hold: hard to reverse, surprising without context, and the result of a
 real trade-off. Any one missing → skip it.
 
+**Write the REQ spine before the brief is confirmed.** Turn the request into an
+addressable list — one row per independently verifiable deliverable (not one per
+sentence), each naming **how it is verified**: a test name, a `file:line`, a command
+and its expected output, or a scenario id. *A requirement you can't say how to
+verify is a badly-stated requirement* — split it here. Then freeze the list:
+adding later is free, **removing or narrowing needs the user's explicit
+agreement**. Quietly restating the task in smaller terms is the subtlest way to
+lose it — every later gate then passes honestly on a task that shrank.
+
+Seed a **carry-over ledger** next to the brief, append-only. Anything deferred,
+dropped, or left half-done goes in the moment it's said — including implementer
+concerns and non-blocking review findings. **Deferred out loud is forgotten.**
+
 Stop when shared understanding is reached (every branch answered or explicitly
 deferred) and lock the answers into a short brief the user confirms. Only then
 start. Later stages read that brief instead of asking again.
@@ -63,31 +106,93 @@ start. Later stages read that brief instead of asking again.
 specific (named target + named preconditions). A vague "just do everything" does
 not authorize an outward, irreversible action — stage 7 stops and asks.
 
-## Stages 1→9
+## Stages 1→10
 
 1. **Docs study** (auto) — ground every external lib/API on current docs, not recall.
-2. **Brainstorm** (manual) — 2–3 approaches + a recommendation; design approved.
-   Record whether the task touches a user-facing surface (UI verdict).
-3. **Spec** (manual) — write and commit the design; lock shared contracts. For UI
-   tasks, run the UX chain FIRST (see super-ux below) and embed it.
-4. **Plan** (auto) — zero-context tasks, exact paths, TDD steps, DoD each,
-   dependency graph + parallel groups, non-overlapping file ownership.
-5. **Dev** (auto) — isolate (worktree), TDD per task (failing test → minimal impl →
-   green → commit); two-stage review (spec compliance, then code quality).
+2. **Brainstorm + decompose** (manual) — read the brief, explore the code, then 2–3
+   approaches with a recommendation, YAGNI applied, design presented in sections and
+   approved. **Hard gate: no code, no scaffolding before that approval** — including
+   on "obviously simple" tasks. Record whether the task touches a user-facing surface
+   (UI verdict). **If the brief is a platform, not a change** — several independent
+   capabilities or separately shippable surfaces — cut it into modules before any
+   spec: modules by capability, never by layer; a module qualifies as a brick only if
+   it is independently specifiable, buildable and testable, owns its own entities,
+   talks to others through declared contracts only, and can land while leaving the
+   system working. Commit a module map (module, delivers, entities owned, depends on,
+   contracts exposed, UI?, REQs, status) in build order — the **walking skeleton
+   first**, then topologically, no cycles (a cycle means the cut is wrong). Every REQ
+   maps to exactly one module. Then stages 3→10 run **per module**, one brick at a
+   time; stages 0–2 run once, and the map's status column is the resume point. Single
+   module → record "single module: <name>" and move on.
+3. **Spec** (manual) — write and commit the design; lock every shared contract
+   (types, schemas, signatures, file layout) plus a **Global Constraints** block of
+   exact values every later task inherits. Self-review it for placeholders,
+   contradictions, ambiguity and scope before showing it. For UI tasks, run the UX
+   chain FIRST (see super-ux below) and embed it.
+4. **Plan** (auto) — every task names the REQ ids it `Implements:`, and the set of those ids must **equal** the brief's REQ set — a difference is scope lost, print it and fix it. Zero-context tasks: exact paths, complete code in every step,
+   the exact command and its expected output, TDD steps, DoD each, dependency graph
+   + parallel groups, non-overlapping file ownership. **No placeholders** — no TBD,
+   no "add error handling", no "similar to Task N", no undefined types.
+5. **Dev** (auto) — isolate first (existing worktree? native worktree tool? else
+   `git worktree` into an ignored dir), baseline tests green, then one task at a
+   time: TDD (failing test → watch it fail → minimal impl → watch it pass →
+   commit), then a review with **all three** verdicts — spec compliance, **REQ
+   satisfied** (judged against the requirement's own statement, not the task's
+   instructions), and code quality. Findings loop back to the implementer (max 5
+   rounds, then adjudicate in writing); minor findings are recorded, never blocking. Keep a progress ledger in
+   a file so a lost context can resume instead of redoing finished work. Tasks in
+   the same parallel group run concurrently **only** if each worker has its own
+   worktree — otherwise sequential. Close the stage by integrating: sync with the
+   base branch, re-run the full suite on the result, merge (or open a PR — that's
+   outward, so ask first), remove the worktree.
 6. **Tests** (auto) — full suite green (not just new tests); new/changed code
-   covered; no skip/xfail hiding red.
+   covered including failure paths; no skip/xfail hiding red. Tests assert real
+   behavior, never mock behavior.
 7. **Lint + deploy** (manual) — lint clean AND suite green before deploy; deploy is
    outward → explicit user go, or the specific standing authorization recorded in
    the stage-0 brief.
 8. **Post-deploy** (auto) — tail logs / health-check; clean boot or an honest
    degradation report (never silent success).
-9. **Docs** (auto) — update module docs/runbooks in the SAME change.
+9. **Docs + wiki** (auto) — **the phase-1 source ledger is the work list**: every
+    source the harvest read gets updated if this run changed or disproved it. Module
+    docs and runbooks in the SAME change; the knowledge wiki via `wiki-update` when
+    [obsidian-wiki](https://github.com/ar9av/obsidian-wiki) is installed (absent →
+    recommend once, never block). Docs in **another repository** are outward:
+    propose the edit and get an explicit go, or carry it over with the exact change
+    written down. A doc that was worth reading at stage 0 and is wrong now is the
+    next run's false premise.
+10. **Acceptance** (manual) — the closing stage: go back to the brief and account
+    for **every** REQ. One row each, status `verified` / `partial` / `deferred` /
+    `dropped`, and every `verified` carries **evidence** — a passing test name, a
+    `file:line`, a command and its output. "Done" without evidence is downgraded to
+    `partial`, never upgraded. Then ask out loud, list in hand: *here's what you
+    asked for, here's what shipped, here's what's deferred and where it lives —
+    what's missing?* Ask it even when the table is green. Gate: no REQ `unknown`,
+    no ledger row without a home, user signs off.
 
-Cross-cutting: answer from the brief's autonomy section rather than re-asking, track
+Cross-cutting: answer from the brief's autonomy section rather than re-asking, log every deferral in the ledger, never narrow the task silently, track
 tasks, conventional commits, honest degradation (never claim a failed/skipped step
 succeeded), and get explicit go before any outward/irreversible action (deploy,
 publish, repo create).
 
+**Loop guard — break churn instead of iterating.** Every repeating pass (a fix
+round, a re-entered stage, the next module) logs one line per touched file: the
+file, the pass, and the reason that forced it — a finding id or a failed gate item.
+"Cleanup" is not a reason. **Stop immediately** when: an edit undoes what an earlier
+pass in this run deliberately did (A→B→A); the same file is edited twice for the
+same reason; a finding already fixed or parked comes back; a stage is entered a
+third time for one artifact; two loops edit one file. Hard caps: 5 fix rounds per
+task, 2 re-entries per stage, 3 passes per module. On a stop: name shape A and shape
+B with their evidence and who asks for each; escalate to the layer that owns the
+conflict (two findings → the review rubric; finding vs plan → the user; plan vs spec
+→ back to planning; ambiguous spec → back to spec; two modules claiming one file →
+back to the module map) — **never settle a higher-layer conflict inside a lower
+loop**; then re-plan the check as an ordered checklist, one owner and one
+verification command per item, and go through it one at a time, one commit per item,
+no opportunistic edits. Re-check the list once in the same order at the end. If it
+trips again after a re-planned pass, stop and hand back with both shapes, the
+evidence and your recommendation.
+
 ## super-ux for user-facing tasks (recommended)
 
 If the task touches any UI (web/mobile/CLI/TUI), the WHY→UI→scenario chain comes

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "task-pipeline-skill",
-  "version": "0.12.0",
-  "description": "Full-cycle task delivery pipeline orchestrator skill for Claude Code \u2014 a mandatory built-in intake grill + 9 gated stages (docs, brainstorm, spec, plan, build, tests, deploy, post-deploy, docs/wiki) built on the superpowers skills, with a super-ux UX track for user-facing tasks and toggleable release automation. This package is the installer CLI.",
+  "version": "1.0.0",
+  "description": "Full-cycle delivery pipeline for coding agents: a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine ships inside the skill — no companion plugin required. This package is the installer CLI.",
   "bin": {
     "task-pipeline": "bin/task-pipeline.js"
   },
+  "scripts": {
+    "test": "python3 test/validate.py"
+  },
   "files": [
     "bin",
     "plugins",
@@ -14,7 +17,8 @@
     "CHANGELOG.md"
   ],
   "repository": "github:ssheleg/task-pipeline",
-  "homepage": "https://github.com/ssheleg/task-pipeline",
+  "homepage": "https://github.com/ssheleg/task-pipeline#readme",
+  "bugs": "https://github.com/ssheleg/task-pipeline/issues",
   "license": "MIT",
   "author": "ssheleg",
   "engines": {
@@ -23,11 +27,11 @@
   "keywords": [
     "pipeline",
     "workflow",
-    "superpowers",
     "orchestrator",
     "tdd",
     "deploy",
     "spec-driven",
+    "self-contained",
     "claude-code",
     "skill"
   ]

package/plugins/task-pipeline/.claude-plugin/plugin.json

@@ -1,10 +1,21 @@
 {
   "name": "task-pipeline",
-  "description": "Thin orchestrator: a mandatory built-in intake grill expands the task, sharpens its domain language and pre-resolves what would stop later stages, then docs study, brainstorm, spec, plan, subagent build, tests, lint/deploy, post-deploy log check, docs/wiki sync — typed auto/manual gates, one provider-agnostic model confirmed up front, a super-ux UX track for user-facing tasks, and toggleable project-configurable release automation. Built on the superpowers skills; generic-portable.",
-  "version": "0.12.0",
-  "author": { "name": "ssheleg" },
+  "description": "Runs a substantial task through a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine is built into the skill — no companion plugin required — with typed auto/manual gates, a frozen requirement spine that must close with evidence, a loop guard that breaks churn, one provider-agnostic model confirmed up front, and an optional super-ux UX track for user-facing work.",
+  "version": "1.0.0",
+  "author": {
+    "name": "ssheleg"
+  },
   "homepage": "https://github.com/ssheleg/task-pipeline",
   "repository": "https://github.com/ssheleg/task-pipeline",
   "license": "MIT",
-  "keywords": ["pipeline", "workflow", "superpowers", "orchestrator", "tdd", "deploy", "spec-driven", "claude-code"]
+  "keywords": [
+    "pipeline",
+    "workflow",
+    "orchestrator",
+    "tdd",
+    "deploy",
+    "spec-driven",
+    "self-contained",
+    "claude-code"
+  ]
 }

package/plugins/task-pipeline/commands/task-pipeline.md

@@ -1,19 +1,31 @@
 ---
-description: Run a task through task-pipeline — an intake grill that expands the request, then docs → brainstorm → spec → plan → build → tests → deploy → post-deploy → docs/wiki.
+description: Run a task through task-pipeline — an intake grill that expands the request, then docs → brainstorm → spec → plan → build → tests → deploy → post-deploy → docs/wiki → acceptance.
 argument-hint: <one-line task description>
 ---
 Use the `task-pipeline` skill to run the task below through all gated stages —
 **stage 0 intake grill** → docs study → brainstorm → spec → plan → subagent
-build → tests → lint/deploy → post-deploy → docs/wiki. The **intake grill is
-mandatory and built in** (`references/grill.md` — nothing to install): interview the
+build → tests → lint/deploy → post-deploy → docs/wiki → **acceptance**. **Every stage's doctrine is
+built into the skill** (`references/{knowledge-sources,grill,brainstorm,decomposition,spec,planning,build,review,tdd,acceptance,loop-guard}.md`)
+— no companion plugin is required for any of them. **Stage 0 opens with the
+knowledge harvest, before the first question** (`references/knowledge-sources.md`):
+pull what the project already knows about this task from the code, `CLAUDE.md`,
+`CONTEXT.md`/ADRs, `docs/` + `docs/ux/`, past pipeline briefs, the **knowledge wiki**
+if one is installed ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki) —
+recommended, never required; detect `~/.obsidian-wiki/config`) and any **other repo
+or hosted doc system the project names as its docs**, then write the **source
+ledger** into the brief. The **intake grill is
+mandatory** (`references/grill.md`): interview the
 operator one question at a time (with a recommended answer each, exploring the
-codebase before asking) until every decision branch is resolved, applying the
+codebase before asking) until every decision branch is resolved, **validating every
+answer against the harvested sources** — the operator outranks any document, but
+only out loud, and a doc the run proves stale is logged for the stage-9 update —
+applying the
 grill's **domain awareness** (challenge terms against `CONTEXT.md`, sharpen fuzzy
 language, ADRs for hard-to-reverse calls) and covering the **autonomy sweep** (what
-would otherwise stop stages 1→9: docs sources, branch/tracker policy, test and lint
-commands, deploy target and authorization, log locations, docs/wiki targets) —
-until the brief is locked, so the rest runs autonomously. For any user-facing task, recommend/use
-**super-ux**. Honor every stage gate by its type (`auto` = verify yourself;
+would otherwise stop stages 1→10: docs sources incl. doc repos and the wiki, branch/tracker
+policy, test and lint commands, deploy target and authorization, log locations, docs/wiki targets) —
+until the brief is locked — including the **REQ table**, the request as an addressable list where every row names how it is verified — so the rest runs autonomously and the final stage can account for all of it. The list is frozen: adding is free, removing needs the operator's agreement. Anything deferred goes into the carry-over ledger the moment it's said. For any user-facing task, recommend/use
+**super-ux**. **If the brief describes a platform rather than a change**, stage 2 also cuts it into modules (`references/decomposition.md`) — module map committed, walking skeleton first, every REQ in exactly one module — and stages 3→10 then run per module, one brick at a time. **If any loop starts undoing an earlier pass** (same file edited twice for the same reason, a closed finding returning, a third entry into one stage), stop and run the loop guard (`references/loop-guard.md`): name both shapes, escalate to the layer that owns the conflict, re-plan the check as an ordered list, then go item by item. Honor every stage gate by its type (`auto` = verify yourself;
 `manual` = wait for explicit go). Confirm the **model once at preflight** —
 recommend the most capable one the environment offers, never a hardcoded id — then
 run the whole pipeline on it without re-asking.

package/plugins/task-pipeline/skills/task-pipeline/SKILL.md

@@ -1,18 +1,19 @@
 ---
 name: task-pipeline
-description: "Use when running a substantial task through the full end-to-end delivery pipeline — an up-front intake grill that expands the request into a complete brief, then docs study, brainstorm, spec, plan, subagent-driven build, test suite, lint/deploy, post-deploy log check, and docs/wiki sync — as gated stages built on the superpowers skills. Use when the user wants to run a task through the pipeline, asks for the full cycle / полный цикл / прогони по конвейеру, invokes /task-pipeline, or starts any substantial feature, fix, or build that should follow the disciplined cycle rather than ad-hoc coding. The intake grill is mandatory — it front-loads every decision, including the per-stage autonomy sweep, so stages 1→9 run without mid-flight questions; recommends super-ux for any user-facing task; confirms one model up front (most capable available, never a hardcoded id); reads host-project conventions for deploy/docs/wiki so it stays project-agnostic."
+description: "Use when running a substantial task through the full end-to-end delivery pipeline — an up-front intake grill that expands the request into a complete brief, then docs study, brainstorm, spec, plan, subagent-driven build, tests, lint/deploy, post-deploy log check, docs/wiki sync and acceptance — as gated stages whose doctrine is built entirely into this skill (no required companion skills). Triggers - 'run this through the pipeline' / 'прогони по конвейеру', 'the full cycle' / 'полный цикл', /task-pipeline, or any substantial feature, fix, or build that should follow the disciplined cycle rather than ad-hoc coding. The intake grill is mandatory - it front-loads every decision, including the per-stage autonomy sweep, so stages 1→10 run without mid-flight questions; recommends super-ux for user-facing work; confirms one model up front (most capable available, never a hardcoded id); reads host-project conventions for deploy/docs/wiki so it stays project-agnostic."
 ---
 
 # task-pipeline
 
-Thin orchestrator. Runs a task through **gated stages**, each built on an
-existing skill. Keeps the main thread disciplined: no stage advances until its
-gate passes; the whole run uses one model, confirmed before it starts.
+Self-contained orchestrator. Runs a task through **gated stages**, each carrying its
+own built-in doctrine — no companion plugin required. Keeps the main thread
+disciplined: no stage advances until its gate passes; the whole run uses one model,
+confirmed before it starts.
 
 **Grill first, then run autonomously.** A one-line task ("make me feature X") is
 never enough to finish without a human in the loop. Stage 0 is **mandatory**: a
 relentless, one-question-at-a-time interview that resolves every decision branch
-*and* sweeps stages 1→9 for anything that would stop the run later — then locks
+*and* sweeps stages 1→10 for anything that would stop the run later — then locks
 the answers into a brief. Autonomy is bought there or not at all; every question
 skipped at stage 0 comes back as an interruption at stage 6.
 
@@ -21,21 +22,43 @@ a machine-readable config — an ordered list of stages, each with `skills[]` (t
 skills/agents that run it) and a `gate {type, check}`. The schema is the universal
 contract; it imposes **no** specific stages, skills, or gate assignments.
 [`pipeline.example.json`](pipeline.example.json) is a **copy-and-rewrite example**
-that encodes this plugin's own default flow (stage 0 intake + the 1→9 stages
+that encodes this plugin's own default flow (stage 0 intake + the 1→10 stages
 tabled below) and an optional, toggleable `release` block. Any project replaces it
 wholesale — any number of stages, run by its own skills/agents, with its own gate
 types (see *Bring your own skills*). Each gate has a **type**: `auto` (the
 orchestrator verifies the `check` itself, pass/fail) or `manual` (wait for an
-explicit operator go); which stages are manual is the operator's call.
-
-## Prerequisite
-
-Requires the **superpowers** skills. Preflight: confirm `superpowers:brainstorming`,
-`superpowers:writing-plans`, `superpowers:subagent-driven-development`,
-`superpowers:using-git-worktrees`, `superpowers:test-driven-development` resolve.
-If missing → tell the operator to install from **https://github.com/obra/superpowers**
-(`/plugin marketplace add obra/superpowers` → `/plugin install superpowers@superpowers`)
-and stop.
+explicit operator go); which stages are manual is the operator's call. In the
+example's `skills[]`, `task-pipeline:<name>` denotes this skill's own built-in
+doctrine (`references/<name>.md`) and `host:<name>` denotes the host project's own
+command for that job (`references/conventions.md`); everything else is a real skill
+the environment resolves.
+
+## Prerequisites — none required
+
+**Every stage's doctrine ships inside this skill.** There is no required companion
+plugin, nothing to resolve at preflight, no version skew with someone else's repo,
+and no stage that can fail because a dependency is missing:
+
+| Stage | Built-in doctrine |
+|---|---|
+| 0 Knowledge harvest (pre-grill) | [`references/knowledge-sources.md`](references/knowledge-sources.md) |
+| 0 Intake grill | [`references/grill.md`](references/grill.md) |
+| 2 Brainstorm | [`references/brainstorm.md`](references/brainstorm.md) |
+| 2 Decompose (platforms only) | [`references/decomposition.md`](references/decomposition.md) |
+| 3 Spec | [`references/spec.md`](references/spec.md) |
+| 4 Plan | [`references/planning.md`](references/planning.md) |
+| 5 Build (worktree, subagents, fix loop) | [`references/build.md`](references/build.md) + [`references/review.md`](references/review.md) |
+| 5–6 TDD + suite gate | [`references/tdd.md`](references/tdd.md) |
+| 10 Acceptance (REQ close-out) | [`references/acceptance.md`](references/acceptance.md) |
+| any repeating loop | [`references/loop-guard.md`](references/loop-guard.md) |
+
+**Optional bridge.** If the operator already runs an equivalent skill set (e.g.
+`superpowers:brainstorming` / `writing-plans` / `subagent-driven-development` /
+`using-git-worktrees` / `test-driven-development`), it can be mapped onto stages
+2/4/5/6 in `pipeline.json` → `skills[]`. That is a **substitution, never a
+requirement**: the built-in doctrine is normative, the gates in
+`references/stages.md` still govern, and nothing detects, recommends or waits for
+an external provider.
 
 **super-ux — recommended for ANY user-facing task.** The moment a task implies a
 user interface (web / mobile / CLI / TUI — a screen, a command, a visible
@@ -63,14 +86,31 @@ no "clear enough task" exemption, no starting stage 1 without a committed,
 operator-confirmed brief. The one sanctioned bypass is the entry-from-super-ux
 short-circuit, and even that demands a scope confirmation.
 
-Two things the grill does beyond clarifying the request:
+It also produces the **REQ spine**: the request as an addressable list of
+requirements, each naming how it will be verified. Stages 3–5 trace to those ids,
+stage 4's gate is a mechanical set-comparison against them, and **stage 10 accounts
+for every one** — which is what turns the pipeline from a funnel into a circle.
+
+**Harvest before you ask.** Stage 0 opens with a **knowledge harvest**
+([`references/knowledge-sources.md`](references/knowledge-sources.md)), not a
+question: pull what the project already knows about this task from the code,
+`CLAUDE.md`, `CONTEXT.md`/ADRs, `docs/` + `docs/ux/`, past pipeline briefs, the
+**knowledge wiki** if one is installed
+([obsidian-wiki](https://github.com/ar9av/obsidian-wiki) — recommended, never
+required) and any **other repo or hosted doc system the project names as its
+docs**. Write the source ledger into the brief, then interview *against* it: every
+answer that touches a source is checked against that source, and the operator
+outranks any document — but only out loud, so an override is a recorded decision
+instead of an undetected divergence. The same ledger is stage 9's work list.
+
+Three things the grill does beyond clarifying the request:
 - **Domain awareness.** It reads the project's own `CONTEXT.md` / `docs/adr/` and
   holds the operator to them — challenging terms that conflict with the glossary,
   sharpening overloaded words, stress-testing with concrete scenarios, and
   flagging where the code contradicts what was just said. Resolved terms are
   written to `CONTEXT.md` as they land; genuinely hard-to-reverse decisions get an
   ADR.
-- **The autonomy sweep.** It pre-resolves what would otherwise stop stages 1→9
+- **The autonomy sweep.** It pre-resolves what would otherwise stop stages 1→10
   mid-flight (test/lint/deploy commands, branch policy, log locations, docs
   targets, the model decision, deploy authorization). Autonomy is bought here or
   not at all — an unasked question is a scheduled interruption.
@@ -79,33 +119,54 @@ Two things the grill does beyond clarifying the request:
 
 1. Restate the task in one line. Create a **TaskList: one task per stage, starting
    with stage 0** (survives context loss; lets you resume). Then run the
-   **companion preflight** (`references/companion-skills.md`): detect which
-   companion skills resolve and emit ONE block covering both the companions —
-   install the required/recommended ones (superpowers always; super-ux for UI
-   tasks) — **and the model decision** (`references/model-tiering.md`): recommend
+   **companion preflight** (`references/companion-skills.md`): the stage doctrine
+   is built in, so this only checks the *optional* companions (super-ux for UI
+   tasks, context7, wiki-update) and emits ONE block covering them
+   **and the model decision** (`references/model-tiering.md`): recommend
    the most capable model available, let the operator confirm or override, record
    it. Ask once, here.
-2. **Run stage 0 (Intake grill) — always, no exceptions.** Grill until shared
-   understanding is reached, the autonomy sweep is covered and the brief is locked
+2. **Run stage 0 — always, no exceptions.** It opens with the **knowledge harvest**
+   (`references/knowledge-sources.md`): query the project's own sources — repo docs,
+   ADRs, `docs/ux/`, past briefs, the wiki if installed, any doc repo the project
+   names — for this task's terms, and write the **source ledger** into the brief
+   before question one. Then grill until shared
+   understanding is reached, **each answer checked against the harvest**, the
+   autonomy sweep is covered, **the REQ table is
+   written (one row per independently verifiable deliverable, each naming its
+   check)** and the brief is locked
    (`references/stages.md` → 0). Do not touch stage 1 before the brief is
    committed and confirmed. **Entered from super-ux?**
    (a validated `docs/ux/` chain and/or a `docs/ux/plans/…` fix plan already
    exists — super-ux's `/ux` hands off here) → don't re-grill or rebuild the UX
    chain: just check it's OK (`/ux-lint` green), confirm scope in one line, and
    skip ahead to the first stage with real work (see `references/stages.md` → 0).
-3. Walk stages 1→9 on the model confirmed at preflight. **Don't re-ask about the
+3. Walk stages 1→10 on the model confirmed at preflight. **Don't re-ask about the
    model at every boundary** — only when the operator recorded a per-stage override
    map and the next stage's entry differs (`references/model-tiering.md`).
+   **Is the brief a platform rather than a change?** Then stage 2 also cuts it into
+   modules (`references/decomposition.md`) and stages 3→10 run **per module** in
+   build order, one brick at a time — stages 0–2 run once, and the module map's
+   status column is the resume point (`references/stages.md` → *The program loop*).
 4. Do **not** advance until the stage **gate** passes (`references/stages.md`).
    Honor the gate **type**: for `auto`, verify the gate's `check` yourself and
    stop/return on fail; for `manual`, present the result and **wait for the
    operator's explicit "continue"/go** — an auto gate never substitutes for a
    required manual approval.
 5. Cross-cutting, every stage: **answer from the brief's autonomy section rather
-   than asking again** — it was grilled precisely so you wouldn't have to; task
+   than asking again** — it was grilled precisely so you wouldn't have to;
+   **anything deferred, dropped or left half-done goes into the carry-over ledger
+   the moment it's said** — deferred out loud is forgotten; **never narrow the task
+   silently** — the REQ list is frozen, adding is free, removing needs the
+   operator's explicit agreement; **when a loop starts undoing an earlier pass —
+   the same file edited twice for the same reason, a closed finding coming back, a
+   third entry into one stage — stop and run the loop guard**
+   (`references/loop-guard.md`): name the two shapes, escalate to the layer that
+   owns the conflict, re-plan the check as an ordered list, then go through it one
+   item at a time; task
    tracker + conventional commits per host conventions; worktree isolation for the
-   build; honest degradation (never claim a failed/skipped step succeeded);
-   outward/irreversible actions (deploy, publish, repo create) need explicit
+   build, integrated back per the brief's branch policy before stage 7; honest
+   degradation (never claim a failed/skipped step succeeded);
+   outward/irreversible actions (deploy, publish, repo create, opening a PR) need explicit
    operator go — or a **specific** standing authorization recorded in the brief
    (named target + preconditions; a vague "do everything" is not one).
 
@@ -116,16 +177,17 @@ capable available — see `references/model-tiering.md`).
 
 | # | Stage | Invoke | Gate | Type |
 |---|---|---|---|---|
-| 0 | Intake grill — **mandatory** | built in: [`references/grill.md`](references/grill.md) | shared understanding reached; autonomy sweep covered; brief locked + confirmed | manual |
+| 0 | Intake grill — **mandatory** | built in: [`references/knowledge-sources.md`](references/knowledge-sources.md) (harvest) → [`references/grill.md`](references/grill.md) (interview) | source ledger written; shared understanding reached; autonomy sweep covered; brief locked + confirmed | manual |
 | 1 | Docs study | `context7` (resolve-library-id → get-library-docs) / `context7-docs` | contracts grounded on fetched docs | auto |
-| 2 | Brainstorm | `superpowers:brainstorming` + **UI detection** | design approved; UI verdict recorded | manual |
-| 3 | Spec | **UI → super-ux chain first** (`/ux` → `ux-foundation` CJM → `ux-flows` screens → `ux-scenarios` → `/ux-lint`), then spec `docs/superpowers/specs/…-design.md` | committed + reviewed; UI: chain validated, linter green, scenarios/`SCR-` traced | manual |
-| 4 | Plan | `superpowers:writing-plans` → `docs/superpowers/plans/…md` | parallel-ready, DoD per task | auto |
-| 5 | Dev | `superpowers:using-git-worktrees` + `superpowers:subagent-driven-development` (TDD) | tasks DONE, TDD green per task | auto |
-| 6 | Tests | host test runner + `superpowers:test-driven-development` | full suite green; new/changed code covered | auto |
+| 2 | Brainstorm + decompose | built in: [`references/brainstorm.md`](references/brainstorm.md) + **UI detection** + [`references/decomposition.md`](references/decomposition.md) for platforms | design approved; UI verdict recorded; every REQ answered; platform: module map approved | manual |
+| 3 | Spec | built in: [`references/spec.md`](references/spec.md) — **UI → super-ux chain first** (`/ux` → `ux-foundation` CJM → `ux-flows` screens → `ux-scenarios` → `/ux-lint`), then spec `docs/superpowers/specs/…-design.md` | committed + reviewed; UI: chain validated, linter green, scenarios/`SCR-` traced | manual |
+| 4 | Plan | built in: [`references/planning.md`](references/planning.md) → `docs/superpowers/plans/…md` | parallel-ready, DoD per task | auto |
+| 5 | Dev | built in: [`references/build.md`](references/build.md) (worktree → subagent per task → review loop → integrate) + [`references/tdd.md`](references/tdd.md) | tasks DONE, TDD green per task, branch integrated per the brief | auto |
+| 6 | Tests | host test runner + built-in [`references/tdd.md`](references/tdd.md) | full suite green; new/changed code covered | auto |
 | 7 | Lint + deploy | host lint → deploy per host convention | lint clean + suite green before deploy; deploy needs a go (or the brief's specific standing authorization) | manual |
 | 8 | Post-deploy | tail deploy logs / health-check | clean boot or honest degradation report | auto |
-| 9 | Docs + wiki | host module docs/runbook rules → `wiki-update` | docs synced, wiki synced | auto |
+| 9 | Docs + wiki | host module docs/runbook rules → `wiki-update` ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki), recommended) | every stale row of the stage-0 source ledger updated; docs synced; wiki synced | auto |
+| 10 | **Acceptance** | built in: [`references/acceptance.md`](references/acceptance.md) | every REQ accounted for with evidence; ledger has no unresolved row; operator signs off | manual |
 
 ## Model — ask once, at preflight
 
@@ -145,8 +207,8 @@ pinned to the confirmed model automatically. Detail: `references/model-tiering.m
 
 ## Bring your own skills
 
-The stages above (stage 0 intake + 1→9) are the **example** flow (grill +
-superpowers + a super-ux UX track for user-facing tasks + host conventions). A
+The stages above (stage 0 intake + 1→10) are the **example** flow (this skill's
+built-in doctrine + a super-ux UX track for user-facing tasks + host conventions). A
 host project owns its pipeline: copy `pipeline.example.json` → `pipeline.json`,
 then define its **own** stages (any count), point each stage's `skills[]` at the
 skills/agents its environment resolves, set each `gate.type` (`auto`/`manual`) to
@@ -157,10 +219,21 @@ automation is on — `pipeline.schema.json` is the only contract.
 ## References
 
 - `pipeline.schema.json` — the universal pipeline config contract (stages + release)
-- `pipeline.example.json` — this plugin's default flow (stage 0 + 1→9) + release, as config
+- `pipeline.example.json` — this plugin's default flow (stage 0 + 1→10) + release, as config
+- `references/knowledge-sources.md` — stage-0 phase 1: the source list, the wiki, the ledger, the stage-9 loop-back
 - `references/grill.md` — the built-in stage-0 grill: loop, domain awareness, autonomy sweep
+- `references/acceptance.md` — the built-in stage-10 close-out: REQ coverage, evidence, sign-off
+- `references/brainstorm.md` — stage 2: design dialogue, approaches, UI detection, hard gate
+- `references/spec.md` — stage 3: UX track order, the spec contract, self-review, review gate
+- `references/planning.md` — stage 4: zero-context plan format, parallel groups, no placeholders
+- `references/build.md` — stage 5: isolation, ledger, subagent task loop, fix loop, final review
+- `references/review.md` — the review rubric, diff packages and the three reviewer prompts
+- `references/tdd.md` — stages 5–6: the iron law, red/green/refactor, the suite gate
 - `references/stages.md` — per-stage detail + exact gate criteria + gate types
 - `references/model-tiering.md` — model map, ids, the `/model` reminder mechanic, override
-- `references/conventions.md` — how stages 6–9 read the host project's CLAUDE.md
+- `references/conventions.md` — how stages 6–10 read the host project's CLAUDE.md
 - `references/companion-skills.md` — companion skills, install lines, preflight recommendation
 - `references/artifacts.md` — the canonical document/artifact layout per stage
+- `templates/` — skeletons seeded into the host project: `brief.md` (stage 0),
+  `carryover.md` (seeded at 0, appended by every stage, read in full at 10),
+  `context.md` and `adr.md` (format references the grill writes lazily)