task-pipeline-skill 0.17.1 → 1.0.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,40 @@ 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 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.
 
-## 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 +108,16 @@ 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 |
+| 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 +130,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 +147,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 +231,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 +253,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 +271,7 @@ 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
+### 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 +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
-
-**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 +363,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 +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
 ```
@@ -245,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 |
 |---|---|
@@ -258,70 +406,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 +465,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*.

package/cursor/rules/task-pipeline.mdc

@@ -28,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→10 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
@@ -127,8 +153,14 @@ not authorize an outward, irreversible action — stage 7 stops and asks.
    the stage-0 brief.
 8. **Post-deploy** (auto) — tail logs / health-check; clean boot or an honest
    degradation report (never silent success).
-9. **Docs + wiki** (auto) — update module docs/runbooks in the SAME change, and
-    sync the project's knowledge base/wiki if it has one.
+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

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "task-pipeline-skill",
-  "version": "0.17.1",
-  "description": "Full-cycle task delivery pipeline orchestrator skill for Claude Code — a mandatory built-in intake grill + 10 gated stages (docs, brainstorm+decompose, spec, plan, build, tests, lint/deploy, post-deploy, docs/wiki, acceptance) whose doctrine ships inside the skill with no required companion plugin, plus 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": {