task-pipeline-skill 0.12.0 → 1.0.0

package/README.md

@@ -4,56 +4,139 @@
 [![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** + **9 gated stages** —
-built on the [superpowers](https://github.com/obra/superpowers) skills.
+**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.
 
-`intake grill → docs study → brainstorm → spec → plan → subagent build → tests →
-lint/deploy → post-deploy log check → docs/wiki sync`
+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.
 
-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→9 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.
+---
+
+## The flow
+
+```
+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
+```
+
+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 | design approved; UI verdict recorded | manual |
+| 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 |
 | 4 | Plan | parallel-ready, DoD per task | auto |
-| 5 | Dev | tasks DONE, TDD green per task | auto |
+| 5 | Dev | tasks DONE (three review verdicts each), TDD green per task | auto |
 | 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→9) 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
 
-## Intake grill (stage 0) — mandatory
+- **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 of them with evidence.
+- **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.
 
-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,
-confirmed brief.
+## 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
 
-**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*).
+### 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
+stage that can fail because a plugin is missing:
+
+| Stage | Built-in doctrine |
+|---|---|
+| 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 |
+| 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)
+and stages 2–6 from the corresponding skills in
+[obra/superpowers](https://github.com/obra/superpowers) — both MIT, both credited in
+[LICENSE](LICENSE) → *Third-party*. Nothing at runtime reaches for either.
+
+**Optional bridge:** if you already run an equivalent skill set, map it onto stages
+2/4/5/6 in your `pipeline.json` → `skills[]`. That's a substitution, never a
+requirement — the gates still govern, and nothing detects, recommends or waits for
+an external provider.
+
+### The intake grill (stage 0) — mandatory
+
+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.
 
 **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
@@ -64,15 +147,131 @@ 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→9: 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:
+
+```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
+stage; it leaks on the **seams**, because brief → spec → plan → task briefs is four
+rewrites and nothing compares the lists.
+
+So the grill's second hard output is an addressable **requirement table**: one row
+per independently verifiable deliverable, each naming how it will be verified. A
+requirement you can't say how to verify is a badly-stated requirement — it gets
+split during the grill, not discovered at the end.
 
-## UX track (user-facing tasks) — super-ux recommended
+From there the ids thread through everything:
+
+| Where | What it does |
+|---|---|
+| Spec | every section carries `covers: REQ-…` |
+| Plan | every task carries `Implements: REQ-…`; **the gate is set equality** against the brief — a difference is printed as the explicit list of dropped requirements |
+| Build | the implementer's brief quotes the REQ statement verbatim, so it optimises the requirement and not just the instruction |
+| Review | a third verdict beside spec-compliance and code-quality: **does this satisfy its REQ?** |
+| Deploy | no REQ may still be `open`; a `partial` ships only with explicit acceptance |
+| **Acceptance** | every REQ gets `verified` / `partial` / `deferred` / `dropped` — and `verified` requires **evidence**: a passing test name, a `file:line`, a command and its output |
+
+Two rules keep it honest. **The list is frozen** — adding mid-run is free, removing
+or narrowing needs your explicit agreement, because silently restating the task
+smaller makes every later gate pass honestly on a shrunken task. And **deferred out
+loud is forgotten** — anything postponed, dropped or half-done goes into an
+append-only carry-over ledger the moment it's said, including implementer concerns
+and non-blocking review findings.
+
+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
+
+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 ([`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
+independently specifiable, buildable and testable, owns its own entities, talks to
+its neighbours through declared contracts only, and can land while leaving the
+system working. The committed module map fixes the build order — **walking skeleton
+first**, then topological, no cycles — and every requirement maps to exactly one
+module.
+
+Then stages 3→10 run **per module**: dossier → plan → build → tests → deploy →
+post-deploy → docs → acceptance → next brick. Stages 0–2 run once for the platform,
+and the map's status column is what a resumed session reads to know where it
+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
+
+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
+looks like progress and consumes a run, so it is
+[detected mechanically](plugins/task-pipeline/skills/task-pipeline/references/loop-guard.md):
+every repeat pass logs one line per touched file with **the reason that forced it**
+— a finding id, a failed gate item. "Cleanup" is not a reason.
+
+It trips on revert-oscillation, a file edited twice for the same reason, a
+resurrected finding, a third entry into one stage, or two loops editing one file —
+plus hard caps (5 fix rounds per task, 2 re-entries per stage, 3 passes per module).
+On a trip the run **stops editing**, names shape A and shape B with their evidence,
+escalates to the layer that owns the conflict (rubric → operator → plan → spec →
+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 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)
@@ -81,30 +280,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
-
-**superpowers** — https://github.com/obra/superpowers
+(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 obra/superpowers
-/plugin install superpowers@superpowers
+/plugin marketplace add ssheleg/super-ux
+/plugin install super-ux@super-ux
 ```
 
-**super-ux** (only for user-facing tasks) — https://github.com/ssheleg/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" }
+    }
+  ]
+}
 ```
-/plugin marketplace add ssheleg/super-ux
-/plugin install super-ux@super-ux
-```
+
+### 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
@@ -112,14 +363,14 @@ before interface.
 
 **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
 ```
@@ -127,17 +378,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
 ```
@@ -145,10 +393,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 |
 |---|---|
@@ -158,114 +406,64 @@ 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
+### Prerequisites
 
-Say *"run this through the pipeline"* / *"полный цикл"* / *"прогони по конвейеру"*,
-or `/task-pipeline`. The skill creates a per-stage TaskList and walks the gates.
+**None for the pipeline itself** — the doctrine for every stage ships inside the
+skill. Three optional companions make individual stages better:
 
-## Model policy
+| 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 |
 
-**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`).
+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).
 
-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
-
-`references/companion-skills.md` lists what powers each stage and how to install
-it: **superpowers** (required), **super-ux** (required for user-facing tasks —
-install line surfaced on the spot), **context7** (docs stage), **wiki-update**
-(stage 9). The stage-0 grill is **not** on that list — it's built into the skill. A
-single preflight
-block prints which are ready, which to install, and the model recommendation, so you
-arm the whole run in one exchange.
-
-## Portability
-
-Stages 6–9 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).
-
-## По-русски
-
-**task-pipeline** — оркестратор полного цикла доставки задачи для Claude Code:
-один скилл проводит любую существенную задачу через **интейк-грил + 9 гейтованных
-стадий** (изучение доков → брейншторм → спека → план → сборка сабагентами →
-тесты → линт/деплой → пост-деплой проверка логов → синк доков/вики), построенных
-на скиллах [superpowers](https://github.com/obra/superpowers).
-
-- **Грил на входе (стадия 0) — обязателен.** Одна строка задачи («сделай фичу X»)
-  недостаточна для автономной работы, поэтому стадию нельзя пропустить: пайплайн
-  «допрашивает» оператора — по одному вопросу за ход, с рекомендованным ответом,
-  изучив код до вопроса — пока все ветки решений не закрыты и не зафиксированы в
-  брифе. Ни одна стадия 1+ не стартует без закоммиченного подтверждённого брифа.
-  **Грил встроен в скилл** — ставить нечего: вся доктрина лежит в
-  `references/grill.md`, без компаньонов, резолва и фолбэков. Портировано из
-  [grill-with-docs Мэтта Покока](https://github.com/mattpocock/skills) (MIT, см.
-  `LICENSE` → *Third-party*).
-- **Доменная осознанность на гриле.** Пайплайн читает `CONTEXT.md` / `docs/adr/`
-  проекта и держит оператора в рамках его же языка: ловит термины, конфликтующие с
-  глоссарием, заменяет размытые слова каноничными, проверяет отношения конкретными
-  краевыми сценариями, вскрывает расхождения между кодом и только что сказанным.
-  Разрешённый термин сразу пишется в `CONTEXT.md`; решение, которое трудно
-  откатить, неочевидно без контекста и стало результатом реального компромисса,
-  получает ADR. Файлы создаются лениво.
-- **Автономию даёт свип по стадиям.** Помимо самой задачи грил заранее закрывает
-  всё, что иначе остановит стадии 1→9: внешние библиотеки и где их доки, политику
-  веток и трекер задач, команду тестов и что значит «зелено», команду линта, цель
-  деплоя и **авторизацию на него**, где живут логи/health, какие доки и раннбуки
-  обновлять, и модель. По каждому пункту — либо ответ, либо явное «здесь
-  остановись и спроси»; незаданный вопрос = запланированное прерывание. У
-  авторизации деплоя жёсткий пол: постоянное «go» засчитывается, только если
-  названы цель и предусловия.
-- Ни одна стадия не стартует, пока не пройден гейт предыдущей; деплой требует
-  зелёного полного прогона тестов и явного «go» оператора.
-- **UX-трек (super-ux рекомендуется):** как только задача трогает интерфейс
-  (web/mobile/CLI/TUI), [super-ux](https://github.com/ssheleg/super-ux) —
-  рекомендуемый воркфлоу, детектится ещё на гриле; если установлен — используется,
-  если нет — сразу даётся строка установки. Стадия спеки гоняет `/ux` →
-  `ux-foundation` (персоны, JTBD, CJM) → `ux-flows` (флоу + `screens.md` — карта
-  экранов) → `ux-scenarios` (сценарии, ux-contract v4) → `/ux-lint` (линтер должен
-  быть зелёным) до написания плана; спека включает ID сценариев, `SCR-` экраны,
-  стадии CJM и UX-паттерны.
-  Сценарии — до интерфейса.
-- **Модель — одна на прогон, подтверждается один раз до старта.** Рекомендация по
-  умолчанию — *самая мощная reasoning-модель, доступная в окружении* (сейчас это
-  последнее поколение Opus, но это **тир, а не строка**). Идентификаторы моделей
-  устаревают, и провайдер может быть другой, поэтому ничего не захардкожено:
-  актуальный топ-тир определяется в рантайме, а в конфиге стадий стоят
-  провайдер-агностичные токены (`default` / `inherit`). Оператор подтверждает или
-  переопределяет (можно по стадиям) — дальше пайплайн больше не переспрашивает.
-  Сабагенты стадии 5 пинятся на подтверждённую модель автоматически.
-- Стадии 6–9 читают конвенции хост-проекта из `CLAUDE.md` (тесты / линт /
-  деплой / доки / вики), поэтому скилл работает в любом репозитории.
-
-Запуск: скажите *«полный цикл»* / *«прогони по конвейеру»* или `/task-pipeline
-<задача>`. Установка — см. раздел Install выше (плагин, `npx skills add
-ssheleg/task-pipeline`, `npx task-pipeline-skill` / `npx
-github:ssheleg/task-pipeline` или `./install.sh`).
+## Documentation map
+
+| 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).
+
+```bash
+npm test        # python3 test/validate.py — the structural validator
+```
+
+## Author
+
+Built by ssheleg — [sshlg.me](https://sshlg.me)
+
+- X / Twitter — [@fuck_this_year](https://x.com/fuck_this_year)
+- Telegram — [@sshlg](https://t.me/sshlg)
+
+Part of the [ssheleg skill family](https://github.com/ssheleg/sshlg-skills):
+`super-ux`, `task-pipeline`, `make-skill`, `sheleg-design`, `seo-aeo-audit`.
+One command installs all five for every agent you use:
+
+```bash
+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*.