task-pipeline-skill 0.5.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,129 @@
 # Changelog
 
+## v0.9.0 — 2026-07-23
+
+Full structural parity with the sibling `super-ux` per the ssheleg skill canon
+(make-skill): the Cursor channel and a templates dir were the last gaps.
+
+- **Cursor channel.** New `cursor/rules/task-pipeline.mdc` — a self-contained,
+  agent-requested rule (`alwaysApply: false` + a trigger `description`, no external
+  links so it survives being copied into any project) that carries the full
+  intake-grill + 9-stage discipline and the super-ux recommendation. Install
+  globally via `npx skills add ssheleg/task-pipeline --agent cursor --global`, or
+  copy per project into `.cursor/rules/`.
+- **Templates dir.** New `templates/brief.md` — the stage-0 intake-brief skeleton
+  this plugin seeds into `docs/superpowers/specs/…-brief.md` (create-if-absent,
+  never overwrite), plus `templates/README.md` mapping template → destination →
+  stage. Spec/plan and `docs/ux/*` skeletons remain owned by superpowers / super-ux.
+- **Validator + packaging.** The validator now checks every `cursor/rules/*.mdc`
+  has `description` + `alwaysApply` frontmatter and that `templates/brief.md`
+  exists; `package.json` `files` ships `cursor` and `templates`. All prior gates
+  (four-way version sync, config conformance, gate types, release shape, links)
+  retained.
+- **Docs.** README gains a Cursor install block and an "Updating everywhere" table
+  (one channel per agent — the plugin+plain duplicate caveat spelled out);
+  `references/artifacts.md` and stage 0 reference the brief template.
+
+## v0.8.1 — 2026-07-23
+
+- Docs consistency: the SKILL.md super-ux intro now lists the full current chain
+  (`/ux`, `ux-foundation`, `ux-flows`, `ux-scenarios`, `/ux-lint`) instead of the
+  pre-flows subset, matching the stage-3 table and `companion-skills.md`. Wiki
+  synced to the current architecture.
+
+## v0.8.0 — 2026-07-23
+
+Project-configurable release automation, super-ux embedding refreshed to its
+current chain, a locked artifact structure, a companion-skills preflight, and a
+full contradiction sweep.
+
+- **Release automation — project-configurable & individually toggleable.** New
+  optional `release` block in `pipeline.schema.json` (master `enabled` toggle,
+  `trigger`, project-defined `steps`, `verify` smoke-checks) with the repo's own
+  config in `pipeline.example.json`. Reference implementation
+  `.github/workflows/release.yml` is **off unless armed** per repo via the
+  `RELEASE_ENABLED` variable; when on it validates the tag ↔ manifest version,
+  cuts a GitHub release from the CHANGELOG, and smoke-tests `npx` from a clean
+  checkout — closing the previously-manual post-deploy gap. Validator shape-checks
+  the block and enforces that `enabled:true` ships the workflow.
+- **super-ux embedding updated to super-ux's current chain.** The stage-3 UX
+  track now walks `/ux` → `ux-foundation` (WHY) → `ux-flows` (flows + `screens.md`,
+  Figma frames) → `ux-scenarios` (WHAT) → **`/ux-lint`** (`docs/ux/lint.py`, must
+  pass), reflecting super-ux ≥0.17 (flows/screens layers, linter, Figma). The
+  linter is wired into stage 7 (lint) and stage 9 (same-change), and stage-4 DoD
+  now carries `SCR-` screens alongside scenario IDs.
+- **Entry-from-super-ux short-circuit.** When launched *from* super-ux (its `/ux`
+  hand-off, UX chain already built), stage 0 detects the existing validated
+  chain/plan and **skips the grill + UX rebuild** — it verifies (`/ux-lint`
+  green), confirms scope in one line, and resumes at the first stage with real
+  work. super-ux skills are treated as idempotent (reuse, never rebuild).
+- **Companion-skills preflight.** New `references/companion-skills.md`: a matrix
+  of what powers each stage (superpowers, super-ux, grill-me, context7,
+  wiki-update) with install lines and a preflight recommendation block emitted
+  before stage 0, so the operator can arm the full flow up front. super-ux install
+  lines are surfaced the moment a UI task is detected.
+- **Locked artifact structure.** New `references/artifacts.md` fixes the canonical
+  `docs/superpowers/{specs,plans}` + `docs/ux/*` layout, the stage→artifact map,
+  and this repo's own structure — so every stage writes to the same place.
+- **Contradiction sweep.** Manifest descriptions (marketplace/plugin/package) and
+  the "9 stages" wording in README + SKILL.md now account for stage 0; the v0.1.0
+  spec/plan carry *historical snapshot* banners; model tiering marks 0–4 Fable;
+  `conventions.md` covers the super-ux linter and the release block.
+
+## v0.7.0 — 2026-07-23
+
+Front-loaded **intake grill** (stage 0) + super-ux promoted to a recommended,
+auto-detected workflow for any user-facing task.
+
+- **New stage 0 — Intake grill (Fable, manual gate).** Before any technical work,
+  the pipeline interviews the operator relentlessly — one question per turn, a
+  recommended answer with each, exploring the codebase/docs before asking — until
+  every decision branch is resolved and locked into a committed **task brief**
+  (`docs/superpowers/specs/…-brief.md`). This expands a one-line request into a
+  complete input so stages 1→9 run autonomously (only the built-in gates pause).
+  Inspired by [Matt Pocock's grill-me](https://github.com/mattpocock/skills);
+  uses the `grill-me` / `grilling` skill if it resolves, else a built-in grill
+  loop (no hard dependency). The 5 grill rules + stopping condition are embedded
+  in `references/stages.md`.
+- **super-ux recommended for ANY user-facing task.** The stage-0 grill detects a
+  UI surface (web/mobile/CLI/TUI) early and surfaces super-ux immediately: **use
+  it if installed**, otherwise print the install line on the spot
+  (`/plugin marketplace add ssheleg/super-ux` → `/plugin install super-ux@super-ux`,
+  or `npx skills add ssheleg/super-ux`). The stage-3 UX track (`/ux` →
+  `ux-foundation` CJM → `ux-scenarios`) is unchanged; the spec gate still requires
+  it for UI tasks.
+- **Docs synced:** SKILL.md gains the intake overview, a strengthened super-ux
+  block (recommended / use-if-installed / install-now) and an optional grill-me
+  note; stages table + `pipeline.example.json` gain stage 0; model tiering marks
+  0–4 as Fable; the `/task-pipeline` command and README (EN + RU) describe the
+  grill-first flow.
+
+## v0.6.0 — 2026-07-23
+
+Typed gates + generic pipeline contract (merged the good ideas from the `os`
+branch onto main, **keeping** the v0.5.0 UX track, the npm installer, and CI).
+
+- **Typed gates:** every gate is now tagged `auto` (the orchestrator verifies the
+  check itself, pass/fail) or `manual` (wait for the operator's explicit go).
+  SKILL.md gained a **Type** column; `stages.md` tags each gate; SKILL.md's
+  *How to run* spells out honoring the type (an auto gate never substitutes for a
+  required manual approval). Default assignment: 2/3/7 manual, the rest auto.
+- **Generic config contract:** new **`pipeline.schema.json`** (universal contract —
+  ordered `stages[]`, each with `skills[]` + `gate{type,check}`; no fixed stage
+  count, no baked-in skills) and **`pipeline.example.json`** (this plugin's own
+  9-stage flow as config, UX track included). New *Bring your own skills* section:
+  a host project copies the example to `pipeline.json` and rewrites it with its
+  own stages/agents/gate-types.
+- **Validator:** checks the schema is well-formed and the example conforms — a
+  dependency-free shape check (states unique, `skills[]` non-empty, `gate.type` in
+  {auto,manual}, `gate.check` present) plus a full `jsonschema` pass when the
+  library is available. All prior checks (four-way version sync, command
+  frontmatter, relative links, npm bin) retained.
+- **Retained from main (not regressed by the merge):** the super-ux UX track
+  (stage-2 UI detection, stage-3 `/ux`→`ux-foundation` CJM→`ux-scenarios`,
+  scenario IDs in stage-4 DoD), `bin/task-pipeline.js` + `package.json`, and the
+  CI workflow with its negative self-test.
+
 ## v0.5.0 — 2026-07-20
 
 UX track: scenario-first design for user-facing tasks, built on

package/README.md

@@ -1,37 +1,63 @@
 # task-pipeline
 
 Full-cycle task delivery pipeline orchestrator for **Claude Code**. One skill that
-runs any substantial task through **9 gated stages** — built on the
-[superpowers](https://github.com/obra/superpowers) skills.
+runs any substantial task through an up-front **intake grill** + **9 gated stages** —
+built on the [superpowers](https://github.com/obra/superpowers) skills.
 
 ## What it does
 
-`docs study → brainstorm → spec → plan → subagent build → tests → lint/deploy →
-post-deploy log check → docs/wiki sync`
-
-Each stage gates the next; each names the model to use.
-
-| # | Stage | Model | Gate |
-|---|---|---|---|
-| 1 | Docs study | Fable | contracts grounded on current docs |
-| 2 | Brainstorm | Fable | design approved; UI verdict recorded |
-| 3 | Spec | Fable | committed + reviewed; UI: scenarios + CJM traced |
-| 4 | Plan | Fable | parallel-ready, DoD per task |
-| 5 | Dev | Opus | tasks DONE, TDD green per task |
-| 6 | Tests | Opus | full suite green, new code covered |
-| 7 | Lint + deploy | host | lint clean + suite green before deploy |
-| 8 | Post-deploy | host | clean boot / honest degradation |
-| 9 | Docs + wiki | host | docs + wiki synced |
-
-## UX track (user-facing tasks)
-
-When a task touches any user-facing surface (web / mobile / CLI / TUI), the spec
-stage runs the [super-ux](https://github.com/ssheleg/super-ux) skills **before any
-plan is written**: `/ux` (setup check) → `ux-foundation` (personas, JTBD,
-**customer journey maps**, user stories) → `ux-scenarios` (usage scenarios
-validated against the base, ux-contract v2). 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.
+`intake grill → docs study → brainstorm → spec → plan → subagent build → tests →
+lint/deploy → post-deploy log check → docs/wiki sync`
+
+It **grills you first**: a one-line task ("make me feature X") is expanded, one
+question at a time, into a locked brief — so the remaining stages run to the end
+without mid-flight questions. Each stage gates the next; each names the model to
+use. Every gate is typed — **auto** (the orchestrator verifies it, pass/fail) or
+**manual** (waits for your go).
+
+| # | Stage | Model | Gate | Type |
+|---|---|---|---|---|
+| 0 | Intake grill | Fable | shared understanding reached; brief locked | manual |
+| 1 | Docs study | Fable | contracts grounded on current docs | auto |
+| 2 | Brainstorm | Fable | design approved; UI verdict recorded | manual |
+| 3 | Spec | Fable | committed + reviewed; UI: scenarios + CJM traced | manual |
+| 4 | Plan | Fable | parallel-ready, DoD per task | auto |
+| 5 | Dev | Opus | tasks DONE, TDD green per task | auto |
+| 6 | Tests | Opus | full suite green, new code covered | auto |
+| 7 | Lint + deploy | host | lint clean + suite green before deploy | manual |
+| 8 | Post-deploy | host | clean boot / honest degradation | auto |
+| 9 | Docs + wiki | host | docs + wiki synced | auto |
+
+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.
+
+## Intake grill (stage 0)
+
+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**. That front-loads
+all the human input so stages 1→9 run autonomously (only the built-in gates pause).
+Uses the `grill-me` / `grilling` skill if installed; otherwise runs a built-in grill
+loop (no hard dependency).
+
+## 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)
+is the **recommended** workflow, detected early in the stage-0 grill. If it's
+installed, task-pipeline uses it; if not, it gives you the install line on the spot.
+The spec stage runs it **before any plan is written**: `/ux` (setup check) →
+`ux-foundation` (personas, JTBD, **customer journey maps**, user stories) →
+`ux-scenarios` (usage scenarios validated against the base, ux-contract v2). 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
 
@@ -71,6 +97,15 @@ 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/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:**
 ```
 git clone https://github.com/ssheleg/task-pipeline
@@ -80,6 +115,19 @@ cd task-pipeline && ./install.sh
 command into `~/.claude/commands/`; idempotent — rerun skips existing installs,
 `./install.sh --force` overwrites)
 
+## Updating everywhere
+
+Pick **one** channel per agent (running the plugin and the plain/skills-CLI copy
+on the same Claude Code install yields a duplicate skill).
+
+| Agent / channel | Update |
+|---|---|
+| Claude Code (plugin) | `claude plugin marketplace update task-pipeline` → `claude plugin update task-pipeline@task-pipeline` → restart |
+| Any agent (skills CLI) | `npx skills add ssheleg/task-pipeline --agent <name> --global` (re-run overwrites); `--agent '*'` for all |
+| Cursor | skills CLI (above) with `--agent cursor`, or re-copy the `.mdc` per project |
+| 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"* / *"полный цикл"* / *"прогони по конвейеру"*,
@@ -87,31 +135,62 @@ or `/task-pipeline`. The skill creates a per-stage TaskList and walks the gates.
 
 ## Model tiering
 
-Stages 1–4 → Fable, stages 5–6 → Opus, 7–9 → inherit. **Reminders only** — a skill
+Stages 0–4 → Fable, stages 5–6 → Opus, 7–9 → inherit. **Reminders only** — a skill
 can't switch the main-loop model; `/model` is the operator's. Stage-5 subagents are
 pinned to Opus automatically.
 
+## 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), **grill-me** (optional, enhances the stage-0
+grill), **context7** (docs stage), **wiki-update** (stage 9). A preflight prints
+which are ready and which to install so you can arm the full flow before work.
+
 ## 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.
+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).
-
+один скилл проводит любую существенную задачу через **интейк-грил + 9 гейтованных
+стадий** (изучение доков → брейншторм → спека → план → сборка сабагентами →
+тесты → линт/деплой → пост-деплой проверка логов → синк доков/вики), построенных
+на скиллах [superpowers](https://github.com/obra/superpowers).
+
+- **Грил на входе (стадия 0):** одна строка задачи («сделай фичу X») недостаточна
+  для автономной работы. Пайплайн сначала «допрашивает» оператора — по одному
+  вопросу за ход, с рекомендованным ответом, изучив код до вопроса — пока все
+  ветки решений не закрыты и не зафиксированы в брифе. Это выносит весь ввод
+  человека вперёд, дальше стадии 1→9 идут автономно. Идея взята из
+  [grill-me Мэтта Покока](https://github.com/mattpocock/skills); использует скилл
+  `grill-me`/`grilling` если установлен, иначе — встроенный грил-цикл.
 - Ни одна стадия не стартует, пока не пройден гейт предыдущей; деплой требует
   зелёного полного прогона тестов и явного «go» оператора.
-- **UX-трек:** для user-facing задач стадия спеки сначала гоняет скиллы
-  [super-ux](https://github.com/ssheleg/super-ux) (`/ux` → `ux-foundation`:
-  персоны, JTBD, CJM → `ux-scenarios`: сценарии использования по контракту
-  ux-contract v2) — до написания плана; спека включает ID сценариев, стадии
-  CJM и применённые UX-паттерны. Сценарии — до интерфейса.
-- Каждая стадия напоминает, какую модель включить (`/model`): 1–4 — Fable,
+- **UX-трек (super-ux рекомендуется):** как только задача трогает интерфейс
+  (web/mobile/CLI/TUI), [super-ux](https://github.com/ssheleg/super-ux) —
+  рекомендуемый воркфлоу, детектится ещё на гриле; если установлен — используется,
+  если нет — сразу даётся строка установки. Стадия спеки гоняет `/ux` →
+  `ux-foundation` (персоны, JTBD, CJM) → `ux-scenarios` (сценарии по ux-contract
+  v2) до написания плана; спека включает ID сценариев, стадии CJM и UX-паттерны.
+  Сценарии — до интерфейса.
+- Каждая стадия напоминает, какую модель включить (`/model`): 0–4 — Fable,
   5–6 — Opus, 7–9 — наследуется. Это только напоминание — модель переключает
   оператор.
 - Стадии 6–9 читают конвенции хост-проекта из `CLAUDE.md` (тесты / линт /

package/cursor/rules/task-pipeline.mdc

@@ -0,0 +1,56 @@
+---
+description: "task-pipeline: run a substantial task through a disciplined, gated delivery cycle — an intake grill that expands the request, then docs→brainstorm→spec→plan→build→tests→lint/deploy→post-deploy→docs. Apply when the user asks to run a task through the pipeline, the full cycle / полный цикл / прогони по конвейеру, or starts any substantial feature/fix/build."
+alwaysApply: false
+---
+
+# task-pipeline — gated delivery cycle (Cursor)
+
+Self-contained rule (Cursor copies this file into projects — no external links).
+Run a substantial task through an up-front **intake grill + 9 gated stages**. No
+stage advances until its **gate** passes. Each gate is `auto` (verify it yourself,
+pass/fail) or `manual` (wait for the user's explicit go).
+
+## Stage 0 — intake grill (do this FIRST)
+
+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:
+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
+   and still ship?").
+Stop when shared understanding is reached (every branch answered or explicitly
+deferred) and lock the answers into a short brief the user confirms. Only then start.
+
+## Stages 1→9
+
+1. **Docs study** (auto) — ground every external lib/API on current docs, not recall.
+2. **Brainstorm** (manual) — 2–3 approaches + a recommendation; design approved.
+   Record whether the task touches a user-facing surface (UI verdict).
+3. **Spec** (manual) — write and commit the design; lock shared contracts. For UI
+   tasks, run the UX chain FIRST (see super-ux below) and embed it.
+4. **Plan** (auto) — zero-context tasks, exact paths, TDD steps, DoD each,
+   dependency graph + parallel groups, non-overlapping file ownership.
+5. **Dev** (auto) — isolate (worktree), TDD per task (failing test → minimal impl →
+   green → commit); two-stage review (spec compliance, then code quality).
+6. **Tests** (auto) — full suite green (not just new tests); new/changed code
+   covered; no skip/xfail hiding red.
+7. **Lint + deploy** (manual) — lint clean AND suite green before deploy; deploy is
+   outward → explicit user go.
+8. **Post-deploy** (auto) — tail logs / health-check; clean boot or an honest
+   degradation report (never silent success).
+9. **Docs** (auto) — update module docs/runbooks in the SAME change.
+
+Cross-cutting: track tasks, conventional commits, honest degradation (never claim a
+failed/skipped step succeeded), and get explicit go before any outward/irreversible
+action (deploy, publish, repo create).
+
+## super-ux for user-facing tasks (recommended)
+
+If the task touches any UI (web/mobile/CLI/TUI), the WHY→UI→scenario chain comes
+BEFORE interface code. If super-ux is available, use it: foundation (personas,
+JTBD, customer journey maps, user stories) → flows + screens → scenarios (the
+source of truth) → run its linter. Otherwise still design that chain, get it
+approved, and trace every user-facing requirement to a scenario before building.
+Install (Cursor/Claude/others): `npx skills add ssheleg/super-ux`.

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "task-pipeline-skill",
-  "version": "0.5.0",
-  "description": "Full-cycle task delivery pipeline orchestrator skill for Claude Code — 9 gated stages (docs, brainstorm, spec, plan, build, tests, deploy, post-deploy, docs/wiki) built on the superpowers skills. This package is the installer CLI.",
+  "version": "0.9.0",
+  "description": "Full-cycle task delivery pipeline orchestrator skill for Claude Code — an intake grill + 9 gated stages (docs, brainstorm, spec, plan, build, tests, deploy, post-deploy, docs/wiki) built on the superpowers skills, with a super-ux UX track for user-facing tasks and toggleable release automation. This package is the installer CLI.",
   "bin": {
     "task-pipeline": "bin/task-pipeline.js"
   },
   "files": [
     "bin",
     "plugins",
+    "cursor",
+    "templates",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"

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

@@ -1,7 +1,7 @@
 {
   "name": "task-pipeline",
-  "description": "Thin orchestrator that runs a task through the full delivery pipeline: docs study, brainstorm, spec, plan, subagent build, test suite, lint/deploy, post-deploy log check, docs/wiki sync. Built on the superpowers skills; per-stage model reminders; generic-portable.",
-  "version": "0.5.0",
+  "description": "Thin orchestrator: an intake grill expands the task, then docs study, brainstorm, spec, plan, subagent build, tests, lint/deploy, post-deploy log check, docs/wiki sync — typed auto/manual gates, per-stage model reminders, a super-ux UX track for user-facing tasks, and toggleable project-configurable release automation. Built on the superpowers skills; generic-portable.",
+  "version": "0.9.0",
   "author": { "name": "ssheleg" },
   "homepage": "https://github.com/ssheleg/task-pipeline",
   "repository": "https://github.com/ssheleg/task-pipeline",

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

@@ -1,17 +1,21 @@
 ---
-description: Run a task through the full 9-stage task-pipeline (docs → brainstorm → spec → plan → build → tests → deploy → post-deploy → docs/wiki).
+description: Run a task through task-pipeline — an intake grill that expands the request, then docs → brainstorm → spec → plan → build → tests → deploy → post-deploy → docs/wiki.
 argument-hint: <one-line task description>
 ---
-Use the `task-pipeline` skill to run the task below through all **nine gated
-stages** — docs study → brainstorm → spec → plan → subagent build → tests →
-lint/deploy → post-deploy → docs/wiki. Honor every stage gate (never advance a
-red gate) and emit the per-stage model reminder when the recommended model
-differs from the current one.
+Use the `task-pipeline` skill to run the task below through all gated stages —
+**stage 0 intake grill** → docs study → brainstorm → spec → plan → subagent
+build → tests → lint/deploy → post-deploy → docs/wiki. Start with the **intake
+grill**: interview the operator one question at a time (with a recommended answer
+each, exploring the codebase before asking) until every decision branch is
+resolved and the brief is locked — so the rest runs autonomously. For any
+user-facing task, recommend/use **super-ux**. Honor every stage gate by its type
+(`auto` = verify yourself; `manual` = wait for explicit go) and emit the
+per-stage model reminder when the recommended model differs from the current one.
 
 Task: $ARGUMENTS
 
 Idempotent entry — inspect state first, never restart blindly:
 - If a pipeline TaskList from a previous run already exists for this task,
   **resume** from the first incomplete stage instead of starting over.
-- Otherwise, if no task is given above, ask the operator for the task in one
-  line before starting stage 1.
+- Otherwise, begin at stage 0 (intake grill). If no task is given above, the
+  grill's first question asks the operator for the task in one line.

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

@@ -1,14 +1,33 @@
 ---
 name: task-pipeline
-description: "Orchestrates a task through the full end-to-end delivery pipeline — docs study, brainstorm, spec, plan, subagent-driven build, test suite, lint/deploy, post-deploy log check, and docs/wiki sync — as nine gated stages built on the superpowers skills. Use when the user wants to run a task through the pipeline, asks for the full cycle / полный цикл / прогони по конвейеру, invokes /task-pipeline, or starts any substantial feature, fix, or build that should follow the disciplined cycle rather than ad-hoc coding. Reminds which model to switch to per stage; reads host-project conventions for deploy/docs/wiki so it stays project-agnostic."
+description: "Orchestrates a task through the full end-to-end delivery pipeline — an up-front intake grill that expands the request into a complete brief, then docs study, brainstorm, spec, plan, subagent-driven build, test suite, lint/deploy, post-deploy log check, and docs/wiki sync — as gated stages built on the superpowers skills. Use when the user wants to run a task through the pipeline, asks for the full cycle / полный цикл / прогони по конвейеру, invokes /task-pipeline, or starts any substantial feature, fix, or build that should follow the disciplined cycle rather than ad-hoc coding. Grills the operator first so the rest runs autonomously; recommends super-ux for any user-facing task; reminds which model to switch to per stage; reads host-project conventions for deploy/docs/wiki so it stays project-agnostic."
 ---
 
 # task-pipeline
 
-Thin orchestrator. Runs a task through **9 gated stages**, each built on an
+Thin orchestrator. Runs a task through **gated stages**, each built on an
 existing skill. Keeps the main thread disciplined: no stage advances until its
 gate passes; each stage names the model to use.
 
+**Grill first, then run autonomously.** A one-line task ("make me feature X") is
+never enough to finish without a human in the loop. Stage 0 **grills the operator
+up front** — a relentless, one-question-at-a-time interview that resolves every
+decision branch — and locks the answers into a brief. That front-loads all the
+human input so stages 1→9 can run to the end with only the built-in gate
+approvals, not mid-flight discovery.
+
+**Config contract: [`pipeline.schema.json`](pipeline.schema.json).** A pipeline is
+a machine-readable config — an ordered list of stages, each with `skills[]` (the
+skills/agents that run it) and a `gate {type, check}`. The schema is the universal
+contract; it imposes **no** specific stages, skills, or gate assignments.
+[`pipeline.example.json`](pipeline.example.json) is a **copy-and-rewrite example**
+that encodes this plugin's own default flow (stage 0 intake + the 1→9 stages
+tabled below) and an optional, toggleable `release` block. Any project replaces it
+wholesale — any number of stages, run by its own skills/agents, with its own gate
+types (see *Bring your own skills*). Each gate has a **type**: `auto` (the
+orchestrator verifies the `check` itself, pass/fail) or `manual` (wait for an
+explicit operator go); which stages are manual is the operator's call.
+
 ## Prerequisite
 
 Requires the **superpowers** skills. Preflight: confirm `superpowers:brainstorming`,
@@ -18,36 +37,71 @@ If missing → tell the operator to install from **https://github.com/obra/super
 (`/plugin marketplace add obra/superpowers` → `/plugin install superpowers@superpowers`)
 and stop.
 
-For **user-facing tasks** (web/mobile/CLI/TUI) the spec stage additionally requires
-the **super-ux** skills (`ux-foundation`, `ux-scenarios`, `/ux`) —
-**https://github.com/ssheleg/super-ux**. Check only when stage 2 flags UI; if
-missing then → tell the operator to install and stop.
+**super-ux — recommended for ANY user-facing task.** The moment a task implies a
+user interface (web / mobile / CLI / TUI — a screen, a command, a visible
+behavior; the stage-0 grill detects this early), super-ux is the recommended
+workflow for the WHY→UI→scenario chain (`/ux`, `ux-foundation`, `ux-flows`,
+`ux-scenarios`, `/ux-lint`).
+- **Already installed?** (does `/ux` or `super-ux:ux-foundation` resolve) → **use
+  it**: `/ux` at intake, then the stage-3 UX track walks its traced chain —
+  `ux-foundation` (personas, JTBD, CJM, stories) → `ux-flows` (user flows +
+  `screens.md`, Figma frames when on) → `ux-scenarios` (traced scenarios) → the
+  `/ux-lint` linter (`docs/ux/lint.py`) must pass. Wire that linter into the host
+  CI/pre-commit so UX drift can't merge.
+- **Not installed?** → recommend it and give the install line right away:
+  ```
+  /plugin marketplace add ssheleg/super-ux
+  /plugin install super-ux@super-ux
+  ```
+  (or `npx skills add ssheleg/super-ux`). For UI tasks the spec gate **requires**
+  it — install before stage 3, otherwise stop and ask the operator to install.
+
+**grill-me (optional, enhances stage 0).** If the `grill-me` / `grilling` skill
+resolves, stage 0 uses it; otherwise stage 0 runs its own built-in grill loop —
+no hard dependency. Install (optional): `npx skills add mattpocock/skills` or the
+engineering-advanced-skills marketplace.
 
 ## How to run
 
-1. Restate the task in one line. Create a **TaskList: one task per stage** (survives
-   context loss; lets you resume).
-2. Walk stages 1→9. Before each: **model check** (see `references/model-tiering.md`) —
+1. Restate the task in one line. Create a **TaskList: one task per stage, starting
+   with stage 0** (survives context loss; lets you resume). Then run the
+   **companion preflight** (`references/companion-skills.md`): detect which
+   companion skills resolve and emit the recommendation block — install the
+   required/recommended ones (superpowers always; super-ux for UI tasks) before
+   proceeding.
+2. **Run stage 0 (Intake grill) first** — grill the operator until shared
+   understanding is reached and the brief is locked (`references/stages.md` → 0).
+   Do not touch stage 1 before the brief is confirmed. **Entered from super-ux?**
+   (a validated `docs/ux/` chain and/or a `docs/ux/plans/…` fix plan already
+   exists — super-ux's `/ux` hands off here) → don't re-grill or rebuild the UX
+   chain: just check it's OK (`/ux-lint` green), confirm scope in one line, and
+   skip ahead to the first stage with real work (see `references/stages.md` → 0).
+3. Walk stages 1→9. Before each: **model check** (see `references/model-tiering.md`) —
    if recommended ≠ current, emit the reminder block and wait for the operator to `/model`.
-3. Do **not** advance until the stage **gate** passes (`references/stages.md`).
-4. Cross-cutting, every stage: task tracker + conventional commits per host
+4. Do **not** advance until the stage **gate** passes (`references/stages.md`).
+   Honor the gate **type**: for `auto`, verify the gate's `check` yourself and
+   stop/return on fail; for `manual`, present the result and **wait for the
+   operator's explicit "continue"/go** — an auto gate never substitutes for a
+   required manual approval.
+5. Cross-cutting, every stage: task tracker + conventional commits per host
    conventions; worktree isolation for the build; honest degradation (never claim a
    failed/skipped step succeeded); outward/irreversible actions (deploy, publish,
    repo create) need explicit operator go.
 
 ## Stages (detail in `references/stages.md`)
 
-| # | Stage | Model | Invoke | Gate |
-|---|---|---|---|---|
-| 1 | Docs study | Fable | `context7` (resolve-library-id → get-library-docs) / `context7-docs` | contracts grounded on fetched docs |
-| 2 | Brainstorm | Fable | `superpowers:brainstorming` + **UI detection** | design approved; UI verdict recorded |
-| 3 | Spec | Fable | **UI → super-ux first** (`/ux` → `ux-foundation` CJM → `ux-scenarios`), then spec `docs/superpowers/specs/…-design.md` | committed + reviewed; UI: scenarios validated + CJM traced |
-| 4 | Plan | Fable | `superpowers:writing-plans` → `docs/superpowers/plans/…md` | parallel-ready, DoD per task |
-| 5 | Dev | **Opus** | `superpowers:using-git-worktrees` + `superpowers:subagent-driven-development` (TDD) | tasks DONE, TDD green per task |
-| 6 | Tests | **Opus** | host test runner + `superpowers:test-driven-development` | full suite green; new/changed code covered |
-| 7 | Lint + deploy | host | host lint → deploy per host convention | lint clean + suite green before deploy; deploy needs go |
-| 8 | Post-deploy | host | tail deploy logs / health-check | clean boot or honest degradation report |
-| 9 | Docs + wiki | host | host module docs/runbook rules → `wiki-update` | docs synced, wiki synced |
+| # | Stage | Model | Invoke | Gate | Type |
+|---|---|---|---|---|---|
+| 0 | Intake grill | Fable | `grill-me` / `grilling` if present, else built-in grill loop | shared understanding reached; brief locked + confirmed | manual |
+| 1 | Docs study | Fable | `context7` (resolve-library-id → get-library-docs) / `context7-docs` | contracts grounded on fetched docs | auto |
+| 2 | Brainstorm | Fable | `superpowers:brainstorming` + **UI detection** | design approved; UI verdict recorded | manual |
+| 3 | Spec | Fable | **UI → super-ux chain first** (`/ux` → `ux-foundation` CJM → `ux-flows` screens → `ux-scenarios` → `/ux-lint`), then spec `docs/superpowers/specs/…-design.md` | committed + reviewed; UI: chain validated, linter green, scenarios/`SCR-` traced | manual |
+| 4 | Plan | Fable | `superpowers:writing-plans` → `docs/superpowers/plans/…md` | parallel-ready, DoD per task | auto |
+| 5 | Dev | **Opus** | `superpowers:using-git-worktrees` + `superpowers:subagent-driven-development` (TDD) | tasks DONE, TDD green per task | auto |
+| 6 | Tests | **Opus** | host test runner + `superpowers:test-driven-development` | full suite green; new/changed code covered | auto |
+| 7 | Lint + deploy | host | host lint → deploy per host convention | lint clean + suite green before deploy; deploy needs go | manual |
+| 8 | Post-deploy | host | tail deploy logs / health-check | clean boot or honest degradation report | auto |
+| 9 | Docs + wiki | host | host module docs/runbook rules → `wiki-update` | docs synced, wiki synced | auto |
 
 ## Model reminder (emit at a boundary when recommended ≠ current)
 
@@ -55,8 +109,23 @@ missing then → tell the operator to install and stop.
 > Switch: `/model <id>` — then say "continue". *(Reminder only — override if you
 > don't have that model.)*
 
+## Bring your own skills
+
+The stages above (stage 0 intake + 1→9) are the **example** flow (grill +
+superpowers + a super-ux UX track for user-facing tasks + host conventions). A
+host project owns its pipeline: copy `pipeline.example.json` → `pipeline.json`,
+then define its **own** stages (any count), point each stage's `skills[]` at the
+skills/agents its environment resolves, set each `gate.type` (`auto`/`manual`) to
+fit its process, and configure/toggle its own `release` block. The framework ships
+no fixed stage count and no opinion on which gates are manual or whether release
+automation is on — `pipeline.schema.json` is the only contract.
+
 ## References
 
-- `references/stages.md` — per-stage detail + exact gate criteria
+- `pipeline.schema.json` — the universal pipeline config contract (stages + release)
+- `pipeline.example.json` — this plugin's default flow (stage 0 + 1→9) + release, as config
+- `references/stages.md` — per-stage detail + exact gate criteria + gate types
 - `references/model-tiering.md` — model map, ids, the `/model` reminder mechanic, override
 - `references/conventions.md` — how stages 6–9 read the host project's CLAUDE.md
+- `references/companion-skills.md` — companion skills, install lines, preflight recommendation
+- `references/artifacts.md` — the canonical document/artifact layout per stage

package/plugins/task-pipeline/skills/task-pipeline/pipeline.example.json

@@ -0,0 +1,130 @@
+{
+  "$schema": "./pipeline.schema.json",
+  "version": 1,
+  "_note": "EXAMPLE ONLY — copy this file, rename to pipeline.json in your project, and rewrite it. This particular example encodes the plugin's own default flow (an up-front intake grill + superpowers + a super-ux UX track for user-facing tasks); it is NOT a fixed contract. Your project defines its own stages (any count), each executed by your own skills/agents, with your own gate types. The universal contract is pipeline.schema.json; test/validate.py checks this example against it. gate.type: auto = orchestrator verifies the check itself (pass/fail); manual = wait for an explicit operator go. Which stages are manual vs auto is the operator's decision, not the plugin's.",
+  "stages": [
+    {
+      "id": 0,
+      "state": "intake",
+      "name": "Intake grill",
+      "model": "claude-fable-5",
+      "skills": ["grill-me", "grilling"],
+      "gate": {
+        "type": "manual",
+        "check": "grill the operator one question at a time (recommended answer per question; explore codebase/docs before asking) until shared understanding is reached — every decision branch has a recorded answer or explicit deferral, no open contradictions; UI verdict recorded (arms super-ux); decisions locked into a committed task brief the operator confirms before stage 1"
+      }
+    },
+    {
+      "id": 1,
+      "state": "docs-study",
+      "name": "Docs study",
+      "model": "claude-fable-5",
+      "skills": ["context7", "context7-docs"],
+      "gate": {
+        "type": "auto",
+        "check": "every contract the design will lock is grounded in fetched docs, not recall; unresolvable libraries are flagged in the spec"
+      }
+    },
+    {
+      "id": 2,
+      "state": "brainstorm",
+      "name": "Brainstorm",
+      "model": "claude-fable-5",
+      "skills": ["superpowers:brainstorming"],
+      "gate": {
+        "type": "manual",
+        "check": "the user approves the design AND the UI verdict is recorded (does the task touch a user-facing surface — web/mobile/CLI/TUI? this arms the stage-3 UX track)"
+      }
+    },
+    {
+      "id": 3,
+      "state": "spec",
+      "name": "Spec",
+      "model": "claude-fable-5",
+      "skills": ["super-ux:ux-foundation", "super-ux:ux-scenarios", "superpowers:brainstorming"],
+      "gate": {
+        "type": "manual",
+        "check": "spec committed and user-reviewed with all shared contracts locked; for UI tasks additionally: UX track ran FIRST (/ux -> ux-foundation CJM -> ux-scenarios), scenarios validated in docs/ux/scenarios.md, CJM/foundation coverage present, and every user-facing spec requirement traces to a scenario ID — scenarios come BEFORE interface"
+      }
+    },
+    {
+      "id": 4,
+      "state": "plan",
+      "name": "Plan",
+      "model": "claude-fable-5",
+      "skills": ["superpowers:writing-plans"],
+      "gate": {
+        "type": "auto",
+        "check": "every spec requirement maps to a task; no placeholders; parallel-group tasks share no files; for UI tasks each user-facing task names the scenario ID(s) it implements and its DoD includes satisfying them"
+      }
+    },
+    {
+      "id": 5,
+      "state": "dev",
+      "name": "Dev",
+      "model": "claude-opus-4-8",
+      "skills": ["superpowers:using-git-worktrees", "superpowers:subagent-driven-development"],
+      "gate": {
+        "type": "auto",
+        "check": "all plan tasks DONE (two-stage review: spec compliance, then code quality); full test suite green"
+      }
+    },
+    {
+      "id": 6,
+      "state": "tests",
+      "name": "Tests",
+      "model": "claude-opus-4-8",
+      "skills": ["superpowers:test-driven-development"],
+      "gate": {
+        "type": "auto",
+        "check": "full suite green (not just new tests); new/changed code covered; no skip/xfail smuggling a red suite past the gate"
+      }
+    },
+    {
+      "id": 7,
+      "state": "lint-deploy",
+      "name": "Lint + deploy",
+      "model": "inherit",
+      "skills": ["host:lint", "host:deploy"],
+      "gate": {
+        "type": "manual",
+        "check": "lint clean and full suite green before deploy; deploy is outward and needs explicit operator go"
+      }
+    },
+    {
+      "id": 8,
+      "state": "post-deploy",
+      "name": "Post-deploy",
+      "model": "inherit",
+      "skills": ["host:health-check"],
+      "gate": {
+        "type": "auto",
+        "check": "clean boot confirmed (no error spike, live subsystems healthy), or an honest degradation report with next steps"
+      }
+    },
+    {
+      "id": 9,
+      "state": "docs-wiki",
+      "name": "Docs + wiki",
+      "model": "inherit",
+      "skills": ["host:module-docs", "wiki-update"],
+      "gate": {
+        "type": "auto",
+        "check": "docs in sync with code in the same change; wiki synced; dangling links fixed"
+      }
+    }
+  ],
+  "release": {
+    "enabled": true,
+    "trigger": "tag",
+    "steps": [
+      "create a GitHub release from the matching CHANGELOG section",
+      "npm publish (task-pipeline-skill) — human 2FA step, not automated"
+    ],
+    "verify": [
+      "CI green on the tagged commit",
+      "npx github:ssheleg/task-pipeline#<tag> from a clean cwd installs the skill + command",
+      "after npm publish: npm view task-pipeline-skill version == <tag>"
+    ]
+  }
+}

package/plugins/task-pipeline/skills/task-pipeline/pipeline.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/ssheleg/task-pipeline/pipeline.schema.json",
+  "title": "task-pipeline config",
+  "description": "Generic contract for a pipeline config. An ordered list of stages; each stage is run by the host project's own skills/agents and guarded by a typed gate. The framework imposes no specific stages, skills, or gate assignments — those are entirely the host project's config. Copy pipeline.example.json and rewrite it to match your project.",
+  "type": "object",
+  "required": ["stages"],
+  "additionalProperties": true,
+  "properties": {
+    "version": { "type": "integer", "minimum": 1 },
+    "stages": {
+      "type": "array",
+      "minItems": 1,
+      "description": "The pipeline stages, in order. Any number, any names — your project's real stages.",
+      "items": { "$ref": "#/definitions/stage" }
+    },
+    "release": { "$ref": "#/definitions/release" }
+  },
+  "definitions": {
+    "release": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Optional release automation, entirely project-defined and INDIVIDUALLY TOGGLEABLE. Omit the whole object, or set enabled:false, to turn release automation off for this project. The framework ships an example workflow (.github/workflows/release.yml) whose job is gated on a repo variable so each project arms it on its own; this block is the declarative counterpart the orchestrator reads.",
+      "required": ["enabled"],
+      "properties": {
+        "enabled": { "type": "boolean", "description": "Master on/off toggle. false (or the object omitted) = no release automation for this project." },
+        "trigger": { "enum": ["tag", "manual", "push", "none"], "description": "What kicks off a release (e.g. a pushed vX.Y.Z tag, manual dispatch)." },
+        "steps": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "description": "Ordered release actions, in prose — project-specific (e.g. create a GitHub release, npm publish). Human-only steps (2FA publish) are named as such."
+        },
+        "verify": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "description": "Post-release smoke checks that must pass after a release — this is the release's own post-deploy gate (stage 8 applied to shipping the package itself)."
+        }
+      }
+    },
+    "stage": {
+      "type": "object",
+      "required": ["state", "skills", "gate"],
+      "additionalProperties": true,
+      "properties": {
+        "id": { "type": "integer", "description": "Optional ordinal." },
+        "state": { "type": "string", "minLength": 1, "description": "Unique stable key for the stage." },
+        "name": { "type": "string", "description": "Optional human label." },
+        "model": { "type": "string", "description": "Optional recommended model id for the stage." },
+        "skills": {
+          "type": "array",
+          "minItems": 1,
+          "description": "The skill(s)/agent(s) that execute this stage. Any names your environment resolves — this is where you plug in your OWN skills.",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "gate": {
+          "type": "object",
+          "required": ["type", "check"],
+          "additionalProperties": true,
+          "description": "Condition that must pass before advancing to the next stage.",
+          "properties": {
+            "type": {
+              "enum": ["auto", "manual"],
+              "description": "auto = the orchestrator verifies `check` itself (pass/fail); manual = wait for the operator's explicit go."
+            },
+            "check": { "type": "string", "minLength": 1, "description": "The gate condition, in prose." }
+          }
+        }
+      }
+    }
+  }
+}

package/plugins/task-pipeline/skills/task-pipeline/references/artifacts.md

@@ -0,0 +1,64 @@
+# Artifact structure — the canonical layout
+
+Every stage that produces a durable artifact writes it to the **same** place, so
+a resumed or handed-off run always knows where to look. This is the recommended
+structure; a host project may relocate roots via its `CLAUDE.md`, but keep the
+shape.
+
+## In the host project
+
+```
+docs/
+  superpowers/
+    specs/
+      YYYY-MM-DD-<topic>-brief.md     # stage 0 — locked intake brief (grill output)
+      YYYY-MM-DD-<topic>-design.md    # stage 3 — the spec (locks shared contracts)
+    plans/
+      YYYY-MM-DD-<topic>.md           # stage 4 — the implementation plan
+  ux/                                 # super-ux, UI tasks only (see companion-skills.md)
+    foundation.md                     # WHY: personas, JTBD, CJM, stories
+    flows.md                          # HOW: task analysis + user-flow diagrams
+    screens.md                        # UI map: screens + states, wireframes, Figma frames
+    scenarios.md                      # WHAT: scenarios (source of truth for behavior)
+    audits/YYYY-MM-DD-<scope>.md       # ux-audit reports
+    plans/YYYY-MM-DD-<scope>.md        # super-ux fix plans (may hand off to this pipeline)
+    lint.py, README.md                 # seeded by super-ux
+```
+
+Naming: date-prefixed `YYYY-MM-DD-<topic>` slugs, one topic per file, kebab-case.
+The three superpowers artifacts share the **same `<topic>` slug** so brief →
+design → plan is traceable at a glance.
+
+## Stage → artifact map
+
+| Stage | Writes | Consumed by |
+|---|---|---|
+| 0 Intake | `specs/<topic>-brief.md` (seed from `templates/brief.md`) | stages 2–4 |
+| 3 Spec | `specs/<topic>-design.md` (+ links `docs/ux/*` for UI) | stage 4 |
+| 4 Plan | `plans/<topic>.md` | stage 5 |
+| 3 UX track | `docs/ux/{foundation,flows,screens,scenarios}.md` | stages 4–9 + `/ux-lint` |
+| 8 Post-deploy | log/health notes (in the run, not a committed file) | stage 9 |
+| 9 Docs+wiki | host module docs + wiki pages | — |
+
+## This repo (task-pipeline itself), for reference
+
+```
+.claude-plugin/marketplace.json              # marketplace manifest
+plugins/task-pipeline/
+  .claude-plugin/plugin.json
+  commands/task-pipeline.md                   # /task-pipeline
+  skills/task-pipeline/
+    SKILL.md
+    pipeline.schema.json                      # generic pipeline contract
+    pipeline.example.json                     # this plugin's own flow, as config
+    references/{stages,model-tiering,conventions,artifacts,companion-skills}.md
+cursor/rules/task-pipeline.mdc                # Cursor channel (self-contained rule)
+templates/brief.md                            # skeleton seeded at stage 0
+bin/task-pipeline.js                          # npx installer (package task-pipeline-skill)
+package.json
+install.sh                                    # POSIX installer
+test/validate.py                              # structural validator
+.github/workflows/{validate,release}.yml      # CI + toggleable release
+README.md  CHANGELOG.md  LICENSE
+docs/superpowers/{specs,plans}/               # this repo's own design history
+```

package/plugins/task-pipeline/skills/task-pipeline/references/companion-skills.md

@@ -0,0 +1,46 @@
+# Companion skills — what powers each stage, how to install, what to run
+
+task-pipeline is a thin orchestrator; the actual work is done by companion
+skills. Preflight-detect each one; if a needed skill doesn't resolve, **give the
+operator the install line immediately** and (for required ones) stop until it's
+installed. Never silently degrade a required capability.
+
+## The matrix
+
+| Skill / tool | Needed for | Required? | Install |
+|---|---|---|---|
+| **superpowers** (`brainstorming`, `writing-plans`, `subagent-driven-development`, `using-git-worktrees`, `test-driven-development`) | stages 2, 4, 5, 6 | **Required** (always) | `/plugin marketplace add obra/superpowers` → `/plugin install superpowers@superpowers` |
+| **super-ux** (`ux-foundation`, `ux-flows`, `ux-scenarios`, `ux-audit`, `/ux`, `/ux-lint`) | stage 3 UX track | **Required for any user-facing task** | `/plugin marketplace add ssheleg/super-ux` → `/plugin install super-ux@super-ux` (or `npx skills add ssheleg/super-ux`) |
+| **grill-me** / **grilling** | stage 0 intake grill | Optional (built-in grill loop is the fallback) | `npx skills add mattpocock/skills`, or the engineering-advanced-skills marketplace |
+| **context7** (MCP) | stage 1 docs study | Recommended (web-search fallback) | connect the context7 MCP server |
+| **wiki-update** | stage 9 wiki sync | Optional (skip wiki if absent) | user's wiki skill set |
+
+## Preflight recommendation (emit before stage 0)
+
+At the very start, detect which of the above resolve and print ONE recommendation
+block so the operator can arm the full flow before work begins. Example:
+
+```
+Pipeline companions:
+  ✓ superpowers        — ready
+  ✗ super-ux           — this task looks user-facing; recommended. Install:
+                           /plugin marketplace add ssheleg/super-ux
+                           /plugin install super-ux@super-ux
+  ✓ context7           — ready
+  ✗ grill-me           — optional; falling back to the built-in grill loop
+  ✓ wiki-update        — ready
+Recommend installing the ✗ items marked recommended, then say "continue".
+```
+
+Rules:
+- Only flag **super-ux** as recommended when the task implies a UI (the stage-0
+  grill decides this; when unsure, flag it — a false positive costs one install).
+- **superpowers** missing → stop; it's required for the core stages.
+- Optional tools missing → state the fallback, don't block.
+- Re-detect after the operator installs; don't assume.
+
+## Hand-off the other direction
+
+super-ux's `/ux` menu can hand off *to* this pipeline (its "execute
+autonomously" action). When entered that way the UX chain already exists — see
+`stages.md` → 0 *Entry-from-super-ux short-circuit*: verify, don't rebuild.

package/plugins/task-pipeline/skills/task-pipeline/references/conventions.md

@@ -9,12 +9,21 @@ found, surface it and **ask** rather than guessing.
 - `CLAUDE.md` usually names the commands. Else detect: `package.json` scripts
   (`npm test` / `npm run lint`), `pyproject.toml` / `ruff` (`ruff check`), `pytest`,
   `Makefile` targets, `.golangci.yml`, `cargo test`.
+- **UI projects:** the super-ux linter (`python3 docs/ux/lint.py` / `/ux-lint`) is
+  part of lint — run it too; it must pass (no UX drift).
 
-## Deploy
+## Deploy / release
 - `CLAUDE.md` deploy section (e.g. deploy-from-main rule, Heroku auto-deploy on
   push, `Procfile`). Else detect: `Procfile` / heroku remote, `Dockerfile`,
   `.github/workflows/*.yml`, Vercel / Netlify config. **Never invent a deploy
   path** — if none is discoverable, ask.
+- **Release automation is project-configurable and individually toggleable.** If
+  the project declares a `release` block (see `pipeline.schema.json`; this repo's
+  own is in `pipeline.example.json`) with `enabled: true`, that block's `steps`
+  are the deploy, and its `verify` list is the stage-8 post-deploy check. Off (or
+  omitted) → no release automation; deploy by the host convention above. This
+  repo's reference implementation is `.github/workflows/release.yml`, armed per
+  repo via the `RELEASE_ENABLED` variable — copy and adapt it, don't assume it.
 
 ## Post-deploy logs
 - Heroku: `heroku logs -a <app>`. Docker / k8s: `docker logs` / `kubectl logs`.

package/plugins/task-pipeline/skills/task-pipeline/references/model-tiering.md

@@ -5,7 +5,7 @@ lack one, keep your current model; the pipeline still runs.
 
 | Stages | Recommended | id |
 |---|---|---|
-| 1–4 (docs, brainstorm, spec, plan) | Fable 5 | `claude-fable-5` |
+| 0–4 (intake grill, docs, brainstorm, spec, plan) | Fable 5 | `claude-fable-5` |
 | 5–6 (subagent dev, tests) | Opus 4.8 | `claude-opus-4-8` |
 | 7–9 (lint/deploy, logs, docs) | inherit current | — |
 
@@ -20,7 +20,8 @@ At each stage boundary compare recommended vs current. If they differ, emit:
 
 A skill runs inside the current context; it **cannot change the main-loop model**.
 Only the operator can, via `/model` (or `/fast`). The stages that most benefit from
-Fable (1–4) are interactive anyway, so the operator is present to switch.
+Fable (0–4) are interactive anyway (stage 0 is a live grill), so the operator is
+present to switch.
 
 Stage 5 spawns subagents; those **are** pinned to Opus by the orchestrator via the
 `Agent` / `Workflow` model override — no operator action needed for subagents.

package/plugins/task-pipeline/skills/task-pipeline/references/stages.md

@@ -1,7 +1,58 @@
 # Stages — detail & gates
 
 For each stage: what it does, what to invoke, artifacts, and the **GATE** that
-must pass before advancing.
+must pass before advancing. Each gate is tagged with its **type** — `auto` (the
+orchestrator verifies the check itself, pass/fail) or `manual` (wait for the
+operator's explicit go). These stages (0 intake + 1→9) are the plugin's
+**example** flow, encoded in `pipeline.example.json` against the universal contract
+`pipeline.schema.json`; a host project replaces it with its own
+stages/agents/types (see SKILL.md → *Bring your own skills*).
+
+## 0 — Intake grill (Fable)
+- **Entry-from-super-ux short-circuit (check FIRST).** task-pipeline is often
+  launched *from* super-ux — its `/ux` action menu offers "execute autonomously
+  via the task-pipeline plugin" once the UX chain (and often a
+  `docs/ux/plans/…` fix plan) is already built. Before grilling, detect that:
+  if `docs/ux/` already holds a validated chain (foundation → flows → screens →
+  scenarios) and/or a fresh fix plan, **do not re-run the grill or the stage-3
+  UX track from scratch.** Instead: (1) run a quick check — `/ux-lint`
+  (`docs/ux/lint.py`) green, chain present, plan (if any) readable; (2) confirm
+  the scope with the operator in ONE line; (3) skip to the first stage that
+  still has real work (usually stage 4 Plan if a UX fix plan already exists, or
+  stage 3 Spec to formalize it). Record what was adopted vs skipped. If the
+  check finds drift/gaps, fall back to the normal flow for the missing parts
+  only.
+- **What (normal entry):** the operator's one-line task is almost never enough to
+  run autonomously. Before anything else, **grill the operator** to expand that
+  one line into a complete, unambiguous brief — resolve every decision branch
+  up front so stages 1→9 need no further human input beyond the manual gates.
+  This is input expansion, not design: turn "make me feature X" into locked
+  answers for scope, users, constraints, data, edge cases, done-criteria.
+- **Invoke:** prefer the `grill-me` / `grilling` skill if it resolves; otherwise
+  run the built-in grill loop:
+  1. **One question per turn** — never bundle.
+  2. **Give a recommended answer with every question** (+ 1-line rationale);
+     "what do you think?" is lazy.
+  3. **Explore the codebase/docs before asking** — if `grep`/`Read`/context7
+     answers it, do that instead of spending a turn.
+  4. **Walk the decision tree depth-first**; finish a branch before opening
+     another; ask prerequisite decisions first.
+  5. **Reconcile contradictions** immediately; chase dodges ("we'll decide
+     later" → "what's the latest you can decide and still ship?").
+- **UI early-detect:** one branch of the grill is always "does this touch a
+  user-facing surface (web/mobile/CLI/TUI)?". If yes → surface **super-ux**
+  now (use it if installed; otherwise give the install line — see SKILL.md
+  *Prerequisites*); this arms the stage-3 UX track.
+- **Artifact:** lock the resolved decisions into a **task brief** committed at
+  `docs/superpowers/specs/YYYY-MM-DD-<topic>-brief.md` (scope, users/UI verdict,
+  constraints, assumptions, explicitly-deferred items, done-criteria). Seed it from
+  the plugin's `templates/brief.md` skeleton — but only when absent, never
+  overwrite an existing brief. Stages 2–4 build on this brief.
+- **GATE (manual):** shared understanding reached — every detected branch has a
+  recorded answer or an explicit deferral, no open contradictions, and the
+  operator confirms the brief. Stop when a re-scan surfaces no new branches
+  (don't grill past diminishing returns; reversible calls can be deferred with a
+  note). Only then start stage 1.
 
 ## 1 — Docs study (Fable)
 - **What:** ground every external library / API / SDK the task touches on the
@@ -9,8 +60,8 @@ must pass before advancing.
 - **Invoke:** `context7` MCP (`resolve-library-id` → `get-library-docs`, scope by
   `topic`) or the `context7-docs` skill. Web-search fallback for libs context7
   can't resolve.
-- **GATE:** every contract the design will lock is grounded in fetched docs, not
-  recall. Unresolvable libraries are flagged in the spec.
+- **GATE (auto):** every contract the design will lock is grounded in fetched docs,
+  not recall. Unresolvable libraries are flagged in the spec.
 
 ## 2 — Brainstorm (Fable)
 - **Invoke:** `superpowers:brainstorming`. One question at a time; 2–3 approaches +
@@ -19,47 +70,63 @@ must pass before advancing.
   user-facing surface (web, mobile, CLI, TUI — new feature, new screen/command,
   or a change to user-visible behavior). Record the verdict; it arms the UX
   track in stage 3.
-- **GATE:** the user approves the design **and** the UI verdict is recorded.
+- **GATE (manual):** the user approves the design **and** the UI verdict is recorded.
 
 ## 3 — Spec (Fable) — with UX track for user-facing tasks
 - **UX track (runs FIRST when stage 2 flagged UI; skip entirely otherwise).**
-  Requires the **super-ux** skills (`/plugin marketplace add ssheleg/super-ux` →
-  `/plugin install super-ux@super-ux`, or `npx skills add ssheleg/super-ux`);
-  if missing on a UI task → tell the operator to install and stop.
-  1. `/ux` (super-ux entry) — inspects/repairs `docs/ux/` setup in the host project.
-  2. `ux-foundation` — the WHY layer: personas, Jobs to Be Done, **customer
-     journey maps (CJM)**, user stories with Given/When/Then acceptance
-     criteria. Create if missing; update if the feature shifts who/why.
-  3. `ux-scenarios` — draft the feature's usage scenarios and validate them
-     against the existing base per the super-ux format contract
-     (`scenario-format.md`, ux-contract v2): IDs, statuses, `Traces:` to
-     foundation stories/journey stages, edge/error states enumerated.
+  Requires the **super-ux** skills. If missing on a UI task → give the install
+  line and stop (see SKILL.md *Prerequisites*: `/plugin marketplace add
+  ssheleg/super-ux` → `/plugin install super-ux@super-ux`, or `npx skills add
+  ssheleg/super-ux`). super-ux builds a traced chain — walk it top-down (see its
+  `system-map.md`):
+  1. `/ux` (the only super-ux entry) — reports which `docs/ux/` layers exist,
+     repairs the skeleton, records the Figma on/off choice, recommends the next
+     action. Never make the operator pick skills.
+  2. `ux-foundation` → `docs/ux/foundation.md` — the **WHY**: personas, Jobs to
+     Be Done, **customer journey maps (CJM)**, user stories (Given/When/Then).
+  3. `ux-flows` → `docs/ux/flows.md` + `docs/ux/screens.md` — the **HOW + UI
+     map**: task analysis, user-flow diagrams (branches, error paths), every
+     screen + state with wireframe and (Figma on) a Figma frame link.
+  4. `ux-scenarios` → `docs/ux/scenarios.md` — the **WHAT** (source of truth for
+     behavior): scenarios validated per the format contract (`scenario-format.md`,
+     ux-contract v2) — IDs, statuses, `Traces:` to stories/journey stages/flows,
+     edge/error states enumerated.
+  5. **Run the super-ux linter** (`/ux-lint` or `python3 docs/ux/lint.py`) — it
+     must pass: no drift, no orphans, no broken traces or stale Figma links.
+  These skills are **idempotent** — reuse and extend existing `docs/ux/` layers,
+  never rebuild from scratch. If the chain already exists and is validated (e.g.
+  the task entered from super-ux), just verify (linter green) and embed it into
+  the spec; only build the parts that are missing.
 - **Spec:** brainstorming writes the design to
   `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commits it. Lock all
   shared contracts (types, schemas, signatures, file layout). For UI tasks the
-  spec **embeds the UX layer**: links the validated scenario IDs and the CJM
-  stages the feature serves, and states which UX patterns/guides from super-ux
-  apply (per-scenario quality bars, error/empty/loading states, traceability).
-- **GATE:** spec committed **and** user-reviewed; for UI tasks additionally:
-  scenarios validated in `docs/ux/scenarios.md`, CJM/foundation coverage in
-  `docs/ux/foundation.md` (or explicit v1-mode/tiny-project waiver by the
-  operator), and every user-facing spec requirement traces to a scenario ID.
-  No plan (stage 4) starts before this — scenarios come BEFORE interface.
+  spec **embeds the UX layer**: links the validated scenario IDs, the flows and
+  `SCR-` screens, the CJM stages the feature serves, and the UX
+  patterns/principles from super-ux that apply (`best-practices.md`,
+  `ux-design-principles.md`, `component-guidelines.md`).
+- **GATE (manual):** spec committed **and** user-reviewed; for UI tasks
+  additionally: the super-ux chain (foundation → flows → screens → scenarios) is
+  designed, validated and approved; scenarios validated in `docs/ux/scenarios.md`;
+  the linter passes; every user-facing spec requirement traces to a scenario ID
+  (or an explicit v1-mode/tiny-project waiver by the operator). No plan (stage 4)
+  starts before this — the chain comes BEFORE interface.
 
 ## 4 — Plan (Fable)
 - **Invoke:** `superpowers:writing-plans` →
   `docs/superpowers/plans/YYYY-MM-DD-<feature>.md`. Zero-context tasks, exact
   paths, TDD steps, DoD each, dependency graph + parallel groups, non-overlapping
   file ownership.
-- **GATE:** every spec requirement maps to a task; no placeholders; parallel-group
+- **GATE (auto):** every spec requirement maps to a task; no placeholders; parallel-group
   tasks share no files. For UI tasks: every task building user-facing behavior
-  names the scenario ID(s) it implements, and its DoD includes satisfying them.
+  names the scenario ID(s) and `SCR-` screen(s) it implements, and its DoD
+  includes satisfying them **and** updating the affected super-ux layers in the
+  same change (super-ux *same-change* rule).
 
 ## 5 — Dev (Opus)
 - **Invoke:** `superpowers:using-git-worktrees` (isolate) →
   `superpowers:subagent-driven-development` (or `superpowers:executing-plans`).
   TDD per task (failing test → minimal impl → green → commit). Pin subagents to Opus.
-- **GATE:** all plan tasks DONE (two-stage review: spec compliance, then code
+- **GATE (auto):** all plan tasks DONE (two-stage review: spec compliance, then code
   quality); full test suite green.
 
 ## 6 — Tests (Opus)
@@ -68,24 +135,31 @@ must pass before advancing.
   change touched, and add edge-case + failure-path tests per DoD.
 - **Invoke:** the host test runner (see `conventions.md` → *Lint + test*);
   `superpowers:test-driven-development` for any uncovered gap.
-- **GATE:** the **full** suite is green (not just the new tests); new/changed code
+- **GATE (auto):** the **full** suite is green (not just the new tests); new/changed code
   is covered; no `skip`/`xfail` smuggling a red suite past the gate. Never advance
   to deploy on a red or partial run.
 
 ## 7 — Lint + deploy (host model)
 - Read host conventions (`conventions.md`): run the linter; fix failures. The suite
-  is already green from stage 6 — re-run it if code changed since. Then deploy per
-  the project's convention.
-- **GATE:** lint clean **and** suite green **before** deploy. Deploy is outward →
-  explicit operator go. Respect deploy-from-main rules if the project mandates them.
+  is already green from stage 6 — re-run it if code changed since. For UI projects,
+  the **super-ux linter** (`python3 docs/ux/lint.py` / `/ux-lint`) is part of lint —
+  it must pass too (no UX drift merges). Then deploy per the project's convention;
+  if the project defines release automation (`pipeline.json` → `release`, toggle
+  on), that is what "deploy" runs here.
+- **GATE (manual):** lint clean (host linter **and**, for UI projects, the super-ux
+  linter) **and** suite green **before** deploy. Deploy is outward → explicit
+  operator go. Respect deploy-from-main rules if the project mandates them.
 
 ## 8 — Post-deploy (host model)
 - Tail deploy logs / health-check per conventions. Confirm clean boot, no error
   spike, live subsystems healthy.
-- **GATE:** clean boot confirmed, or an **honest degradation report** with next
+- **GATE (auto):** clean boot confirmed, or an **honest degradation report** with next
   steps — never silent success.
 
 ## 9 — Docs + wiki (host model)
 - Update host module docs / runbooks per the project's self-update rules, in the
-  **same change**. Then sync knowledge to the wiki (`wiki-update` skill).
-- **GATE:** docs in sync with code; wiki synced; dangling links fixed.
+  **same change**. For UI tasks, confirm the super-ux layers were updated in this
+  change and the linter is green (super-ux *same-change* + *no-drift* rules). Then
+  sync knowledge to the wiki (`wiki-update` skill).
+- **GATE (auto):** docs in sync with code; UI: super-ux layers current + linter
+  green; wiki synced; dangling links fixed.

package/templates/README.md

@@ -0,0 +1,12 @@
+# templates
+
+Skeletons task-pipeline seeds into a host project. Only the **brief** is owned by
+this plugin (it is the stage-0 intake artifact); the spec and plan skeletons come
+from the `superpowers` skills, and the `docs/ux/*` skeletons from `super-ux`.
+
+| Template | Seeded to | Stage |
+|---|---|---|
+| `brief.md` | `docs/superpowers/specs/YYYY-MM-DD-<topic>-brief.md` | 0 — intake grill |
+
+Seeding rule (per the ssheleg canon): create a template copy **only when the
+target is absent**; never overwrite an existing brief.

package/templates/brief.md

@@ -0,0 +1,35 @@
+# Task brief — <topic>
+
+> Stage-0 intake artifact. The grill fills this in and the operator confirms it
+> before stage 1. Copy to `docs/superpowers/specs/YYYY-MM-DD-<topic>-brief.md`.
+> Every field is a resolved decision or an explicit deferral — no open unknowns.
+
+- **Date:** YYYY-MM-DD
+- **Task (one line):** <what the operator asked for, restated>
+- **UI verdict:** yes / no — does this touch a user-facing surface (web/mobile/CLI/TUI)?
+  If yes, the stage-3 super-ux UX track is armed.
+
+## Scope
+
+- **In scope:** …
+- **Out of scope / explicitly deferred:** … (with the reason and, for deferrals,
+  the latest moment the decision can still be made)
+
+## Users & context
+
+- **Who / for what:** … (personas, the job being done)
+- **Where it runs / constraints:** platform, runtime, data, integrations, limits
+
+## Decisions locked (the grill's output)
+
+| # | Decision | Chosen | Rationale |
+|---|---|---|---|
+| 1 | … | … | … |
+
+## Done-criteria
+
+- Observable, verifiable conditions that mean "this task is finished".
+
+## Open assumptions / risks
+
+- Assumption → how it's validated (or flagged risky-untested).