task-pipeline-skill 0.17.1 → 1.1.0

package/README.md

@@ -4,24 +4,61 @@
 [![validate](https://github.com/ssheleg/task-pipeline/actions/workflows/validate.yml/badge.svg)](https://github.com/ssheleg/task-pipeline/actions/workflows/validate.yml)
 [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
-Full-cycle task delivery pipeline orchestrator for **Claude Code**. One skill that
-runs any substantial task through an up-front **intake grill** + **10 gated stages** —
-with every stage's doctrine **built in**: no companion plugin required.
+**A full-cycle delivery pipeline for coding agents.** One skill takes a substantial
+task, interrogates it into a complete brief, then walks it through ten gated stages
+— and refuses to advance until each gate passes.
 
-## What it does
+Agents write code well and judge *when to stop asking you things* badly. A
+substantial task becomes twenty interruptions, or a confident build that skipped
+the tests and quietly delivered two thirds of what you asked for. `task-pipeline`
+front-loads every decision into one intake conversation, then runs to the end
+without checking in — and closes by accounting for every requirement, from a list
+rather than from memory.
+
+Built for **Claude Code**, and installable into any agent that reads skills
+(Cursor, Codex, OpenCode, …). Every stage's doctrine ships **inside the skill** —
+no companion plugin, nothing to resolve, nothing that breaks when a dependency is
+missing.
+
+---
+
+## The flow
+
+```
+intake grill → docs study → brainstorm + decompose → spec → plan → subagent build
+→ tests → lint/deploy → post-deploy log check → docs/wiki sync → acceptance
+```
 
-`intake grill → docs study → brainstorm + decompose → spec → plan → subagent build →
-tests → lint/deploy → post-deploy log check → docs/wiki sync → acceptance`
+```mermaid
+flowchart TD
+    S0["0 · Harvest + intake grill<br/>brief · REQ table · source ledger"]
+    S1["1 · Docs study"]
+    S2["2 · Brainstorm + decompose"]
+    S3["3 · Spec — UX track first, if UI"]
+    S4["4 · Plan"]
+    S5["5 · Dev — worktree, subagents, TDD"]
+    S6["6 · Tests"]
+    S7["7 · Lint + deploy"]
+    S8["8 · Post-deploy"]
+    S9["9 · Docs + wiki"]
+    S10["10 · Acceptance"]
+
+    S0 --> S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8 --> S9 --> S10
+    S10 -. "platform: next module" .-> S3
+    S10 -. "accounts for every REQ in the brief" .-> S0
+
+    classDef manual fill:#fde68a,stroke:#b45309,color:#111827
+    classDef auto fill:#dbeafe,stroke:#1d4ed8,color:#111827
+    class S0,S2,S3,S7,S10 manual
+    class S1,S4,S5,S6,S8,S9 auto
+```
 
-It **grills you first, always**: stage 0 is mandatory — a one-line task ("make me
-feature X") is expanded, one question at a time, into a locked brief, and the grill
-also sweeps stages 1→10 for anything that would stop the run later. Each stage gates
-the next. Every gate is typed — **auto** (the orchestrator verifies it, pass/fail)
-or **manual** (waits for your go). One model, confirmed before the run starts.
+Every gate is **typed**: `auto` — the orchestrator verifies it itself, pass/fail
+(blue); `manual` — it waits for your explicit go (amber).
 
 | # | Stage | Gate | Type |
 |---|---|---|---|
-| 0 | Intake grill — **mandatory** | shared understanding + autonomy sweep; brief locked | manual |
+| 0 | Harvest + intake grill — **mandatory** | source ledger written; shared understanding + autonomy sweep; brief locked | manual |
 | 1 | Docs study | contracts grounded on current docs | auto |
 | 2 | Brainstorm + decompose | design approved; UI verdict recorded; every REQ answered; platform: module map approved | manual |
 | 3 | Spec | committed + reviewed; UI: super-ux chain validated, linter green | manual |
@@ -30,18 +67,41 @@ or **manual** (waits for your go). One model, confirmed before the run starts.
 | 6 | Tests | full suite green, new code covered | auto |
 | 7 | Lint + deploy | lint clean + suite green before deploy | manual |
 | 8 | Post-deploy | clean boot / honest degradation | auto |
-| 9 | Docs + wiki | docs + wiki synced | auto |
+| 9 | Docs + wiki | every stale source-ledger row updated; docs + wiki synced | auto |
 | 10 | **Acceptance** | every REQ accounted for with evidence; operator signs off | manual |
 
-These stages (0 intake + 1→10) are the plugin's **example** flow. It's a machine-readable config
-([`pipeline.example.json`](plugins/task-pipeline/skills/task-pipeline/pipeline.example.json))
-against a universal contract
-([`pipeline.schema.json`](plugins/task-pipeline/skills/task-pipeline/pipeline.schema.json)):
-a host project copies the example to `pipeline.json` and rewrites it with its own
-stages (any count), its own `skills[]`, and its own `auto`/`manual` gate types —
-"bring your own skills". The framework bakes in no fixed stages.
+## What you get
+
+- **The intake grill asks what a senior engineer would ask** before anything is
+  touched — scope, edge cases, failure modes, rollback, who the user is — so the
+  build does not stall halfway through.
+- **Every stage has a gate.** No code before a spec. No deploy before tests. No
+  "done" before the post-deploy logs have been read.
+- **Nothing falls out the back.** The request becomes a frozen, addressable list of
+  requirements, and the last stage accounts for every one with evidence — then
+  walks the ladder for what should have been on the list and never was.
+- **Team discipline without a team.** ADRs, a written plan, a real test suite, a
+  wiki entry — produced as part of the work, not promised for later.
+- **It adapts to your repo, not the reverse.** Deploy, docs and wiki conventions
+  are read from the host project, so nothing is imposed.
 
-## Everything is built in — zero required dependencies
+## Quickstart
+
+```
+/plugin marketplace add ssheleg/task-pipeline
+/plugin install task-pipeline@task-pipeline
+```
+
+Then say *"run this through the pipeline"*, *"the full cycle"*, or invoke
+`/task-pipeline <one-line task>`. Russian phrasings (*"полный цикл"*, *"прогони по
+конвейеру"*) route the same way. The skill creates a TaskList with one entry per
+stage and walks the gates. See [Install](#install) for the other channels.
+
+---
+
+## What makes it different
+
+### Everything is built in — zero required dependencies
 
 The doctrine each stage runs on ships inside the skill. Nothing to install for it,
 nothing to resolve at preflight, no version skew with someone else's repo, and no
@@ -49,15 +109,17 @@ stage that can fail because a plugin is missing:
 
 | Stage | Built-in doctrine |
 |---|---|
-| 0 Intake grill | [`references/grill.md`](plugins/task-pipeline/skills/task-pipeline/references/grill.md) — interview loop, domain awareness, autonomy sweep |
-| 2 Brainstorm | [`references/brainstorm.md`](plugins/task-pipeline/skills/task-pipeline/references/brainstorm.md) — approaches, YAGNI, the no-code-before-approval gate |
-| 2 Decompose | [`references/decomposition.md`](plugins/task-pipeline/skills/task-pipeline/references/decomposition.md) — platforms only: brick criteria, module map, build order |
-| 3 Spec | [`references/spec.md`](plugins/task-pipeline/skills/task-pipeline/references/spec.md) — UX-track order, locked contracts, global constraints, self-review |
-| 4 Plan | [`references/planning.md`](plugins/task-pipeline/skills/task-pipeline/references/planning.md) — zero-context tasks, parallel groups, no placeholders |
-| 5 Build | [`references/build.md`](plugins/task-pipeline/skills/task-pipeline/references/build.md) + [`review.md`](plugins/task-pipeline/skills/task-pipeline/references/review.md) — isolation, ledger, subagent loop, review rubric, fix loop |
-| 5–6 TDD | [`references/tdd.md`](plugins/task-pipeline/skills/task-pipeline/references/tdd.md) — the iron law, red/green/refactor, the suite gate |
-| 10 Acceptance | [`references/acceptance.md`](plugins/task-pipeline/skills/task-pipeline/references/acceptance.md) — REQ coverage table, evidence rules, the closing question |
-| any loop | [`references/loop-guard.md`](plugins/task-pipeline/skills/task-pipeline/references/loop-guard.md) — churn detection, caps, the break protocol |
+| 0 Knowledge harvest | [`knowledge-sources.md`](plugins/task-pipeline/skills/task-pipeline/references/knowledge-sources.md) — source list, the wiki, the ledger, the stage-9 loop-back |
+| 0 Intake grill | [`grill.md`](plugins/task-pipeline/skills/task-pipeline/references/grill.md) — interview loop, domain awareness, autonomy sweep |
+| 2 Brainstorm | [`brainstorm.md`](plugins/task-pipeline/skills/task-pipeline/references/brainstorm.md) — approaches, YAGNI, the no-code-before-approval gate |
+| 2 Decompose | [`decomposition.md`](plugins/task-pipeline/skills/task-pipeline/references/decomposition.md) — platforms only: brick criteria, module map, build order |
+| 3 Spec | [`spec.md`](plugins/task-pipeline/skills/task-pipeline/references/spec.md) — UX-track order, locked contracts, global constraints, self-review |
+| 4 Plan | [`planning.md`](plugins/task-pipeline/skills/task-pipeline/references/planning.md) — zero-context tasks, parallel groups, no placeholders |
+| 5 Build | [`build.md`](plugins/task-pipeline/skills/task-pipeline/references/build.md) + [`review.md`](plugins/task-pipeline/skills/task-pipeline/references/review.md) — isolation, ledger, subagent loop, review rubric, fix loop |
+| 5–6 TDD | [`tdd.md`](plugins/task-pipeline/skills/task-pipeline/references/tdd.md) — the iron law, red/green/refactor, the suite gate |
+| 10 Acceptance | [`acceptance.md`](plugins/task-pipeline/skills/task-pipeline/references/acceptance.md) — REQ coverage table, evidence rules, the closing question |
+| 10 + any audit | [`audit.md`](plugins/task-pipeline/skills/task-pipeline/references/audit.md) — the L0→L7 ladder and its seams, axis rotation, ratchets, proven checks |
+| any loop | [`loop-guard.md`](plugins/task-pipeline/skills/task-pipeline/references/loop-guard.md) — churn detection, caps, the break protocol |
 
 **Ported, not depended on.** Stage 0 is adapted from
 [Matt Pocock's `grilling` / `grill-with-docs`](https://github.com/mattpocock/skills)
@@ -70,21 +132,14 @@ and stages 2–6 from the corresponding skills in
 requirement — the gates still govern, and nothing detects, recommends or waits for
 an external provider.
 
-## Intake grill (stage 0) — mandatory
+### The intake grill (stage 0) — mandatory
 
-Inspired by [Matt Pocock's grill-me](https://github.com/mattpocock/skills). Before
-any technical work, task-pipeline interviews you relentlessly — one question per
-turn, each with a recommended answer, exploring the codebase before asking — until
-every decision branch is resolved and locked into a **task brief**. There is no
-"clear enough task" exemption: no stage-1 work starts without a committed,
+Before any technical work, task-pipeline interviews you relentlessly — one question
+per turn, each with a recommended answer, exploring the codebase before asking —
+until every decision branch is resolved and locked into a **task brief**. There is
+no "clear enough task" exemption: no stage-1 work starts without a committed,
 confirmed brief.
 
-**Built in — nothing to install.** The full doctrine ships inside the skill
-([`references/grill.md`](plugins/task-pipeline/skills/task-pipeline/references/grill.md)):
-no companion skill, no resolution step, no fallback path, no version skew. Adapted
-from [Matt Pocock's grill-with-docs](https://github.com/mattpocock/skills) (MIT —
-see [LICENSE](LICENSE) → *Third-party*).
-
 **Domain awareness.** While exploring, the grill reads the project's own
 `CONTEXT.md` / `docs/adr/` and holds you to them — calling out terms that conflict
 with the glossary, replacing overloaded words with a canonical one, stress-testing
@@ -94,15 +149,57 @@ decisions that are hard to reverse, surprising without context **and** the resul
 a real trade-off get an ADR. Both files are created lazily.
 
 **Autonomy comes from the sweep.** Beyond the task itself, the grill pre-resolves
-everything that would otherwise interrupt stages 1→10: which external libs need docs,
-branch and task-tracker policy, the test command and what "green" means, the lint
-command, the deploy target and its **authorization**, where logs and health live,
-which docs and runbooks to update, and the model. Each gets an answer or an explicit
-"stop and ask me here" — an unasked question is a scheduled interruption. Deploy
-authorization has a hard floor: a standing go counts only if it names the target and
-the preconditions.
+everything that would otherwise interrupt stages 1→10: which external libs need
+docs, branch and task-tracker policy, the test command and what "green" means, the
+lint command, the deploy target and its **authorization**, where logs and health
+live, which docs and runbooks to update, and the model. Each gets an answer or an
+explicit "stop and ask me here" — an unasked question is a scheduled interruption.
+Deploy authorization has a hard floor: a standing go counts only if it names the
+target and the preconditions.
+
+### Knowledge harvest — read the project before asking the person
+
+Stage 0 doesn't open with a question. It opens by finding what the project already
+knows about this task
+([`knowledge-sources.md`](plugins/task-pipeline/skills/task-pipeline/references/knowledge-sources.md)):
+the code, `CLAUDE.md`, `CONTEXT.md` and the ADRs, `docs/` and `docs/ux/`, previous
+pipeline briefs and their carry-over ledgers, **the knowledge wiki if you have one**,
+and **any other repository or hosted doc system your project names as its docs**. It's
+retrieval scoped by the task's own nouns, not a read of everything, and it ends with a
+**source ledger** written into the brief — one row per source, what it says, how
+fresh, and whether this run makes it stale.
+
+That buys two things. The cheap one: you don't get asked what an ADR already
+answers. The one that matters: **an answer nobody can check is a recollection.**
+People answer from memory about systems they wrote a year ago, and without the
+document in hand there is no way to tell a decision from a misremembering — so the
+run builds on it and every later gate passes honestly on a false premise. With the
+harvest in hand the grill quotes the source instead: *"the March ADR says orders go
+through the command handler, you just described a direct write — has that changed?"*
+You outrank every document, but **only out loud**: an override quoted against its
+source is a recorded decision, an unquoted one is an undetected divergence. When two
+sources disagree, precedence is code > host docs/ADRs > wiki > memory.
+
+Then the loop closes: **stage 9 updates exactly what stage 0 read.** Every doc the
+run proved stale is already in the ledger with what's wrong, so "docs updated" means
+the sources the next run will trust — not just the files this change happened to
+touch.
+
+**The wiki is [obsidian-wiki](https://github.com/ar9av/obsidian-wiki)** (Karpathy's
+LLM-wiki pattern), and it's the one source that carries *why* across projects and
+across months. Detected via `~/.obsidian-wiki/config` or a resolving `wiki-query`.
+Installed → queried at stage 0, synced with `wiki-update` at stage 9. Not installed →
+recommended once, with the line, and the run continues:
 
-## The REQ spine — why nothing falls out the back
+```bash
+pip install obsidian-wiki
+obsidian-wiki setup --vault /path/to/your/vault
+```
+
+It is a **recommendation, never a gate** — no stage blocks on a missing wiki, and
+nothing asks twice in one run.
+
+### The REQ spine — why nothing falls out the back
 
 Every gate before the last one asks *"is this artifact good?"* — none asks *"does
 this still contain everything that was asked for?"* Scope doesn't leak inside a
@@ -136,12 +233,12 @@ Stage 10 closes the circle with the question the pipeline exists to be able to
 answer from a list rather than from memory: *here's what you asked for, here's what
 shipped, here's what's deferred and where it lives — what's missing?*
 
-## Platforms — decomposed into bricks, built one at a time
+### Platforms — decomposed into bricks, built one at a time
 
 A one-feature task runs the pipeline once. A **platform** — several independent
 capabilities, several separately shippable surfaces, requirements no single
 deliverable satisfies — gets cut into modules at stage 2, before any spec is
-written ([`references/decomposition.md`](plugins/task-pipeline/skills/task-pipeline/references/decomposition.md)).
+written ([`decomposition.md`](plugins/task-pipeline/skills/task-pipeline/references/decomposition.md)).
 
 Modules are cut **by capability, never by layer** ("Ordering", "Billing" — not
 "Controllers", "Services"), and a candidate is only a brick when it is
@@ -158,7 +255,7 @@ stopped. Each module's spec is a full dossier: architecture, entities and
 ownership, contracts in and out with their failure behavior, business rules, edge
 and failure cases, UI/Figma chain, limits, open questions.
 
-## Loop guard — churn is detected, not endured
+### Loop guard — churn is detected, not endured
 
 Any repeating pass can start undoing the previous one: two shapes alternating, the
 same file rewritten round after round, a finding that was closed coming back. That
@@ -176,7 +273,58 @@ module map), re-plans the check as an ordered checklist with one verification
 command per item, and goes through it one at a time. A higher-layer conflict is
 never settled inside a lower loop.
 
-## UX track (user-facing tasks) — super-ux recommended
+### The audit ladder — finding what was never written
+
+The REQ spine catches a requirement that was **named and lost**. It cannot catch
+one that was never named — because **a comparison needs two sides, and an absence
+has one.** Nothing in a diff between spec and plan reveals the error path nobody
+specified, the entity nobody gave an owner, the failure mode nobody thought of.
+
+So stage 10 opens with a **ladder walk**
+([`audit.md`](plugins/task-pipeline/skills/task-pipeline/references/audit.md)), not
+with the coverage table. Each requirement is walked **bottom-up** through its rungs
+— recorded decision → spec section → contract *and its failure behavior* → plan
+task → the change in the tree → an **executed** named assertion → the surface a
+user reaches and its docs — and the work is the **seam between each pair**: did the
+decision reach the spec, does every contract have a task, did the DoD land in the
+diff, would that test still pass with the production code deleted, does what
+shipped satisfy the requirement's own *statement* rather than the task's
+instructions. Findings are ordered **by seam, never by file** — the seam names
+which layer of your process leaks. Every absence becomes a new REQ row with its
+check *before* the table is written.
+
+Bottom-up is not taste: a missing artefact low on the ladder makes everything above
+it meaningless, so top-down you spend the pass polishing a surface for a contract
+that does not exist.
+
+Three rules keep the audit from becoming another loop:
+
+- **Every pass changes the axis, not the effort.** A searching pass doesn't
+  oscillate, it *converges*: each pass edits the corpus the next one reads, so the
+  newest edits are always the least-reviewed text and are what the next pass finds.
+  Measured over seven passes on a production repository, by pass six the audit was
+  mostly repairing its own previous pass — while the finding count still looked
+  healthy. So count both numbers every pass (new findings vs. self-inflicted ones);
+  when the second overtakes the first, **rotate the axis** — seams down one
+  deliverable, then invariants across deliverables, then one class swept end to end.
+- **A class that repeats twice becomes a gate, not a note.** Once is an incident;
+  twice is a category, and a category belongs in lint or CI where nobody has to
+  remember it. The third instance in a ledger is how a mechanical defect becomes
+  permanent.
+- **What can't be fixed now becomes a ratchet, never a TODO** — a named, counted
+  set that may only shrink, printed *beside every gate verdict*
+  (`carry-over: 4 open (was 6) · unresolved: 0`). A TODO is invisible until someone
+  opens the file; a ratchet makes **"green" never read as "verified"** — it reads
+  as *"green, and here is exactly what was not looked at"*.
+
+And the exit criterion that is usually skipped: a deliverable is audited when every
+rung has its artefact **and every check you are relying on has been seen failing
+once against a planted defect.** That is the TDD iron law — *if you didn't watch it
+fail, you don't know it tests the right thing* — raised from one test to every
+gate, linter and script in the run. **A green result from an unproven check is
+worth nothing.**
+
+### UX track (user-facing tasks) — super-ux recommended
 
 The moment a task touches any user-facing surface (web / mobile / CLI / TUI — a
 screen, command, or visible behavior), [super-ux](https://github.com/ssheleg/super-ux)
@@ -185,26 +333,82 @@ installed, task-pipeline uses it; if not, it gives you the install line on the s
 The spec stage runs it **before any plan is written**: `/ux` (setup check) →
 `ux-foundation` (personas, JTBD, **customer journey maps**, user stories) →
 `ux-flows` (user flows + `screens.md` UI map, Figma frames) → `ux-scenarios`
-(usage scenarios validated against the base, ux-contract v4) → `/ux-lint` (must pass). The
-spec then embeds the UX layer — scenario IDs, CJM stages served, applicable UX
-patterns — and the plan's UI tasks carry scenario IDs in their DoD. Scenarios come
-before interface.
-
-## Prerequisites
-
-**None for the pipeline itself** — the doctrine for every stage ships inside the
-skill (see *Everything is built in* above).
-
-**super-ux** (only for user-facing tasks) — https://github.com/ssheleg/super-ux
+(usage scenarios validated against super-ux's own scenario-format contract) →
+`/ux-lint` (must pass). The spec then embeds the UX layer — scenario IDs, CJM
+stages served, applicable UX patterns — and the plan's UI tasks carry scenario IDs
+in their DoD. Scenarios come before interface.
 
 ```
 /plugin marketplace add ssheleg/super-ux
 /plugin install super-ux@super-ux
 ```
 
+### Model policy — one model, confirmed once
+
+The default recommendation is *the most capable reasoning model the environment
+offers* — currently the latest Opus generation, but that's a **tier, not a string**.
+Model ids go stale as generations ship, and you may be on another provider entirely,
+so nothing is hardcoded: the pipeline resolves the top tier available at runtime and
+stage configs use provider-agnostic tokens (`default` / `inherit`).
+
+You confirm or override it (per-stage overrides welcome) before stage 0 — then it
+**stops asking**. A skill can't switch the main-loop model; `/model` is yours.
+Stage-5 subagents are pinned to the confirmed model automatically. If the
+recommended tier isn't available, the pipeline says which one it's using and
+continues — a reminder, never a block.
+
+---
+
+## Configure it for your project
+
+### Bring your own skills
+
+Stages 0→10 above are the plugin's **example** flow. It is a machine-readable config
+([`pipeline.example.json`](plugins/task-pipeline/skills/task-pipeline/pipeline.example.json))
+written against a universal contract
+([`pipeline.schema.json`](plugins/task-pipeline/skills/task-pipeline/pipeline.schema.json)):
+copy the example to `pipeline.json` in your repo and rewrite it with your own stages
+(any count), your own `skills[]`, and your own `auto`/`manual` gate types. The
+framework bakes in no fixed stage count and no opinion on which gates are manual.
+
+```jsonc
+{
+  "version": 1,
+  "stages": [
+    {
+      "id": 1,
+      "state": "spec",
+      "name": "Spec",
+      "model": "default",              // 'default' = the run's confirmed model
+      "skills": ["your-team:spec"],    // whatever your environment resolves
+      "gate": { "type": "manual", "check": "spec committed and reviewed" }
+    }
+  ]
+}
+```
+
+### Release automation (optional, toggleable)
+
+A pipeline config may declare an optional `release` block: a master `enabled`
+toggle, a `trigger`, project-defined `steps`, and `verify` smoke-checks. It's **off
+unless a project turns it on**, and every project configures its own. This repo's
+own instance is [`.github/workflows/release.yml`](.github/workflows/release.yml) —
+armed per repo by the `RELEASE_ENABLED` variable (unset = off), it validates the tag
+against the manifests, cuts a GitHub release from the CHANGELOG, and smoke-tests
+`npx` from a clean checkout. Copy and adapt it; nothing is hardcoded.
+
+### Portability
+
+Stages 6–10 read the host project's `CLAUDE.md` conventions (tests / lint / deploy /
+docs / wiki) with detection fallbacks, so the skill works in any repo. The canonical
+artifact layout each stage writes to is fixed in
+[`artifacts.md`](plugins/task-pipeline/skills/task-pipeline/references/artifacts.md).
+
+---
+
 ## Install
 
-**Plugin (recommended):**
+**Claude Code plugin (recommended):**
 ```
 /plugin marketplace add ssheleg/task-pipeline
 /plugin install task-pipeline@task-pipeline
@@ -212,14 +416,14 @@ skill (see *Everything is built in* above).
 
 **Any agent via the skills CLI (Cursor, Codex, OpenCode, 70+ — not Claude Code,
 use the plugin above):**
-```
+```bash
 npx skills add ssheleg/task-pipeline --agent cursor --agent codex --global
 ```
 (one repeated `--agent` per agent; never include `claude-code` while the plugin is
 installed — the plain copy shadows it)
 
 **npm installer (no clone needed):**
-```
+```bash
 npx github:ssheleg/task-pipeline          # straight from GitHub
 npx task-pipeline-skill                   # from the npm registry
 ```
@@ -227,17 +431,14 @@ npx task-pipeline-skill                   # from the npm registry
 on npm; installs the same skill + `/task-pipeline` command into `~/.claude`,
 idempotent, `--force` to overwrite)
 
-**Cursor:**
-```
-npx skills add ssheleg/task-pipeline --agent cursor --global   # global, or…
-```
-…or per project, copy `cursor/rules/task-pipeline.mdc` into the repo's
+**Cursor:** the skills CLI above with `--agent cursor`, or per project copy
+[`cursor/rules/task-pipeline.mdc`](cursor/rules/task-pipeline.mdc) into the repo's
 `.cursor/rules/`. Cursor has no global rules directory — use the skills CLI for a
 global install, the `.mdc` for per-project, or paste it into Cursor Settings →
 Rules. The rule is self-contained (no external links), so it works copied anywhere.
 
 **Plain skill:**
-```
+```bash
 git clone https://github.com/ssheleg/task-pipeline
 cd task-pipeline && ./install.sh
 ```
@@ -245,10 +446,10 @@ cd task-pipeline && ./install.sh
 command into `~/.claude/commands/`; idempotent — rerun skips existing installs,
 `./install.sh --force` overwrites)
 
-## Updating everywhere
+### Updating
 
-Pick **one** channel per agent (running the plugin and the plain/skills-CLI copy
-on the same Claude Code install yields a duplicate skill).
+Pick **one** channel per agent — running the plugin and the plain/skills-CLI copy on
+the same Claude Code install yields a duplicate, shadowing skill.
 
 | Agent / channel | Update |
 |---|---|
@@ -258,70 +459,47 @@ on the same Claude Code install yields a duplicate skill).
 | npm | `npx task-pipeline-skill@latest` / `npx github:ssheleg/task-pipeline` (ephemeral — always latest) |
 | Plain skill | `git pull && ./install.sh --force` |
 
-## Use
-
-Say *"run this through the pipeline"* or *"the full cycle"*, or invoke
-`/task-pipeline`. The skill creates a per-stage TaskList and walks the gates.
-Russian phrasings (*"полный цикл"*, *"прогони по конвейеру"*) route the same way.
-
-## Model policy
-
-**One model, confirmed once, at preflight.** The default recommendation is *the most
-capable reasoning model the environment offers* — currently the latest Opus
-generation, but that's a **tier, not a string**. Model ids go stale as generations
-ship, and you may be on another provider entirely, so nothing is hardcoded: the
-pipeline resolves the top tier available at runtime and stage configs use
-provider-agnostic tokens (`default` / `inherit`).
+### Prerequisites
 
-You confirm or override it (per-stage overrides welcome) before stage 0 — then it
-**stops asking**. A skill can't switch the main-loop model; `/model` is yours.
-Stage-5 subagents are pinned to the confirmed model automatically. If the
-recommended tier isn't available, the pipeline says which one it's using and
-continues — a reminder, never a block.
-
-## Release automation (project-configurable, toggleable)
-
-A pipeline config may declare an optional `release` block (see
-[`pipeline.schema.json`](plugins/task-pipeline/skills/task-pipeline/pipeline.schema.json)):
-a master `enabled` toggle, a `trigger`, project-defined `steps`, and `verify`
-smoke-checks. It's **off unless a project turns it on**, and every project
-configures its own. This repo's own instance is
-[`.github/workflows/release.yml`](.github/workflows/release.yml) — armed per repo
-by the `RELEASE_ENABLED` variable (unset = off), it validates the tag against the
-manifests, cuts a GitHub release from the CHANGELOG, and smoke-tests `npx` from a
-clean checkout. Copy and adapt it per project; nothing is hardcoded.
-
-## Companion skills
+**None for the pipeline itself** — the doctrine for every stage ships inside the
+skill. Three optional companions make individual stages better:
 
-`references/companion-skills.md` separates what's built in (stages 0, 2, 3, 4, 5, 6
-and 10 — nothing to install) from the short optional list: **super-ux** (required only for
-user-facing tasks — install line surfaced on the spot), **context7** (docs stage),
-**wiki-update** (stage 9). A single preflight block prints which are ready, which to
-install, and the model recommendation, so you arm the whole run in one exchange.
+| Companion | For | Required? |
+|---|---|---|
+| [super-ux](https://github.com/ssheleg/super-ux) | the stage-3 UX track | only for user-facing tasks |
+| context7 (MCP) | stage-1 docs study | recommended — web-search fallback |
+| [obsidian-wiki](https://github.com/ar9av/obsidian-wiki) | stage-0 harvest + stage-9 sync | recommended — never a gate |
 
-## Portability
+A single preflight block prints which are ready, which to install, and the model
+recommendation, so you arm the whole run in one exchange. Detail:
+[`companion-skills.md`](plugins/task-pipeline/skills/task-pipeline/references/companion-skills.md).
 
-Stages 6–10 read the host project's `CLAUDE.md` conventions (tests / lint / deploy /
-docs / wiki) with detection fallbacks, so the skill works in any repo. The
-canonical artifact layout each stage writes to is fixed in
-[`references/artifacts.md`](plugins/task-pipeline/skills/task-pipeline/references/artifacts.md).
+---
 
-## What this gives you
+## Documentation map
 
-Agents write code well and judge *when to stop asking you things* badly. A
-substantial task turns into twenty interruptions, or into a confident build that
-skipped the tests. `task-pipeline` front-loads every decision into one intake
-conversation, then runs ten gated stages without stopping to check in.
+| File | What's in it |
+|---|---|
+| [`SKILL.md`](plugins/task-pipeline/skills/task-pipeline/SKILL.md) | the orchestrator: how to run, the stage table, the model decision |
+| [`references/stages.md`](plugins/task-pipeline/skills/task-pipeline/references/stages.md) | per-stage detail and the exact gate criteria |
+| [`references/artifacts.md`](plugins/task-pipeline/skills/task-pipeline/references/artifacts.md) | the canonical document layout each stage writes to |
+| [`references/conventions.md`](plugins/task-pipeline/skills/task-pipeline/references/conventions.md) | how stages 6–10 read the host project's `CLAUDE.md` |
+| [`references/model-tiering.md`](plugins/task-pipeline/skills/task-pipeline/references/model-tiering.md) | model policy, the `/model` reminder, overrides |
+| [`templates/`](plugins/task-pipeline/skills/task-pipeline/templates/README.md) | brief, carry-over ledger, `CONTEXT.md` and ADR skeletons |
+| [`CHANGELOG.md`](CHANGELOG.md) | every release, with the reasoning behind it |
+| [`CONTRIBUTING.md`](CONTRIBUTING.md) | dev setup, the validator, the version-sync rule, release flow |
+
+## Contributing
+
+Issues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for
+the repo's invariants (the structural validator, four-way version sync, and the
+surfaces that must never drift apart). Security reports:
+[SECURITY.md](SECURITY.md). Everyone participating is expected to follow the
+[Code of Conduct](CODE_OF_CONDUCT.md).
 
-- **The intake grill asks what a senior engineer would ask** before anything is
-  touched — scope, edge cases, failure modes, rollback, who the user is — so the
-  build does not stall halfway through.
-- **Every stage has a gate.** No code before a spec. No deploy before tests. No
-  "done" before the post-deploy logs have been read.
-- **Team discipline without a team.** ADRs, a written plan, a real test suite, a
-  wiki entry — produced as part of the work, not promised for later.
-- **It adapts to your repo, not the reverse.** Deploy, docs and wiki conventions
-  are read from the host project, so nothing is imposed.
+```bash
+npm test        # python3 test/validate.py — the structural validator
+```
 
 ## Author
 
@@ -340,4 +518,5 @@ npx sshlg-skills install
 
 ## License
 
-MIT © 2026 ssheleg.
+MIT © 2026 ssheleg. Third-party portions (the ported stage doctrine) are credited
+and licensed in [LICENSE](LICENSE) → *Third-party*.