task-pipeline-skill 0.9.0 → 0.12.0

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

@@ -1,32 +1,65 @@
-# Model tiering
+# Model policy
 
-A **reminder**, not a hard block. Not every environment has every model — if you
-lack one, keep your current model; the pipeline still runs.
+**One model, confirmed once, before the run starts.** Not a per-stage tier list,
+not a hardcoded vendor id — a single decision the operator makes at preflight and
+the pipeline then honors without nagging.
 
-| Stages | Recommended | id |
-|---|---|---|
-| 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 | — |
+## The default
 
-## Mechanic
+> **Use the most capable reasoning model the environment offers** — at the time of
+> writing that is the **latest Opus generation**, but read that as *"the top tier
+> of whatever you're on"*, not as a specific string.
 
-At each stage boundary compare recommended vs current. If they differ, emit:
+Every stage runs on that model by default. The pipeline is a full delivery cycle:
+the grill has to hear what the operator didn't say, the spec has to lock contracts
+a zero-context implementer will follow, and the build has to hold a plan in its
+head. Downgrading any of those to save tokens costs more in rework than it saves.
 
-> ⏸ **Stage N (`<name>`) recommends `<model>` (`<id>`).** You're on `<current>`.
-> Switch: `/model <id>` — then say "continue". *(Reminder only.)*
+## Never hardcode a model id
 
-## Why manual
+Model ids go stale — generations ship, tiers get renamed, and the operator may not
+even be on the same provider. So:
 
-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 (0–4) are interactive anyway (stage 0 is a live grill), so the operator is
-present to switch.
+- **Resolve at runtime.** Look at what the environment actually offers (`/model`,
+  the harness's model list) and pick the top reasoning tier available there.
+- **Treat any id in this repo as an example**, including in `pipeline.example.json`.
+  Stage configs use provider-agnostic tokens:
+  - `default` — the model confirmed for this run (the recommendation above)
+  - `inherit` — whatever the operator is currently on; no recommendation
+- **Another provider is fine.** "Top tier available" is the contract. If the
+  environment has no Opus-class model, the best available one is the right answer —
+  say which one you settled on and keep going.
 
-Stage 5 spawns subagents; those **are** pinned to Opus by the orchestrator via the
-`Agent` / `Workflow` model override — no operator action needed for subagents.
+## Mechanic — confirm at preflight, then stop asking
 
-## Override
+Once, as part of the preflight (before stage 0):
 
-Set your own map if your task warrants it (e.g. a heavy design needs Opus at
-stage 2). The recommendations are defaults, not rules.
+> 🧠 **Model for this run:** recommended **`<top tier available>`**. You're on
+> `<current>`.
+> Switch with `/model <id>`, or say "keep current" / name another. Per-stage
+> overrides welcome (e.g. a cheaper model for mechanical stages) — say so now and
+> I'll record the map.
+
+Record the answer in the stage-0 brief (`Model` row of the autonomy sweep). After
+that:
+
+- **Do not re-prompt at every stage boundary.** The decision is made; nagging is
+  the thing this replaces.
+- **Re-prompt only** when the operator recorded a *per-stage override map* and the
+  next stage's entry differs from the current model — then emit the same block
+  scoped to that stage.
+- A skill runs inside the current context and **cannot change the main-loop
+  model**; only the operator can, via `/model` (or `/fast`). Preflight is
+  interactive anyway, so this costs one exchange.
+
+## Subagents
+
+Stage 5 spawns subagents; the orchestrator pins them to the **run's confirmed
+model** via the `Agent` / `Workflow` model override. No operator action needed —
+and no silent downgrade to a cheaper tier.
+
+## Degradation
+
+The recommendation is a **reminder, not a block**. If the recommended tier isn't
+available, keep the current model, state plainly which one is in use, and run. The
+pipeline never stalls on a model it can't get.

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

@@ -8,7 +8,14 @@ operator's explicit go). These stages (0 intake + 1→9) are the plugin's
 `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)
+## 0 — Intake grill — MANDATORY
+- **Stage 0 is not optional and not skippable.** There is no "small enough task"
+  exemption, no "the request was already clear" exemption, no starting stage 1
+  "while the operator thinks". The only sanctioned bypass is the
+  entry-from-super-ux short-circuit below, and even that still requires a scope
+  confirmation and a record of what was adopted vs skipped. A run that reaches
+  stage 1 without a committed, operator-confirmed brief is a **failed run** —
+  stop and go back.
 - **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
@@ -28,33 +35,36 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   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?").
+- **How it runs: [`grill.md`](grill.md)** — the full doctrine, built into this
+  skill (nothing to install). In short: one question per turn, a recommended
+  answer with each, explore the codebase before asking, depth-first through the
+  decision tree, contradictions reconciled on the spot; plus **domain awareness**
+  (challenge terms against `CONTEXT.md`, sharpen fuzzy language, stress-test with
+  concrete scenarios, cross-reference the code, record ADRs for hard-to-reverse
+  calls) and the **autonomy sweep** that pre-resolves every stage-1→9 blocker.
+  Deploy authorization has a hard floor there: a standing go counts only when it
+  names the target and the preconditions.
 - **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.
+  constraints, assumptions, explicitly-deferred items, done-criteria) **plus the
+  autonomy sweep's per-stage answers and the model decision**. Seed it from
+  the skill's `templates/brief.md` skeleton — but only when absent, never
+  overwrite an existing brief. Stages 2–4 build on this brief; stages 5–9 read
+  its autonomy section instead of asking. Where the session produced them, also:
+  an updated `CONTEXT.md` (terms written as they resolved) and any ADRs under
+  `docs/adr/` — see `grill.md` → *Domain awareness*.
 - **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.
+  recorded answer or an explicit deferral, no open contradictions, **every
+  autonomy-sweep row is answered or explicitly marked "stop and ask here"**, the
+  model decision is recorded, 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)
+## 1 — Docs study
 - **What:** ground every external library / API / SDK the task touches on the
   *current* docs, before locking any contract.
 - **Invoke:** `context7` MCP (`resolve-library-id` → `get-library-docs`, scope by
@@ -63,7 +73,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
 - **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)
+## 2 — Brainstorm
 - **Invoke:** `superpowers:brainstorming`. One question at a time; 2–3 approaches +
   a recommendation; design presented in sections.
 - **UI detection (mandatory check):** decide whether the task touches any
@@ -72,7 +82,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   track in stage 3.
 - **GATE (manual):** the user approves the design **and** the UI verdict is recorded.
 
-## 3 — Spec (Fable) — with UX track for user-facing tasks
+## 3 — Spec — with UX track for user-facing tasks
 - **UX track (runs FIRST when stage 2 flagged UI; skip entirely otherwise).**
   Requires the **super-ux** skills. If missing on a UI task → give the install
   line and stop (see SKILL.md *Prerequisites*: `/plugin marketplace add
@@ -89,7 +99,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
      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,
+     ux-contract v4) — 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.
@@ -111,7 +121,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   (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)
+## 4 — Plan
 - **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
@@ -122,14 +132,15 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   includes satisfying them **and** updating the affected super-ux layers in the
   same change (super-ux *same-change* rule).
 
-## 5 — Dev (Opus)
+## 5 — Dev
 - **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.
+  TDD per task (failing test → minimal impl → green → commit). Pin subagents to the
+  run's confirmed model (`model-tiering.md`).
 - **GATE (auto):** all plan tasks DONE (two-stage review: spec compliance, then code
   quality); full test suite green.
 
-## 6 — Tests (Opus)
+## 6 — Tests
 - **What:** consolidate test coverage for the change: confirm new functionality
   has tests (written test-first in stage 5), update/repair existing tests the
   change touched, and add edge-case + failure-path tests per DoD.
@@ -139,7 +150,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   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)
+## 7 — Lint + deploy
 - 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. For UI projects,
   the **super-ux linter** (`python3 docs/ux/lint.py` / `/ux-lint`) is part of lint —
@@ -150,13 +161,13 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   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)
+## 8 — Post-deploy
 - Tail deploy logs / health-check per conventions. Confirm clean boot, no error
   spike, live subsystems healthy.
 - **GATE (auto):** clean boot confirmed, or an **honest degradation report** with next
   steps — never silent success.
 
-## 9 — Docs + wiki (host model)
+## 9 — Docs + wiki
 - Update host module docs / runbooks per the project's self-update rules, in the
   **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

package/{templates → plugins/task-pipeline/skills/task-pipeline/templates}/README.md

@@ -7,6 +7,12 @@ 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 |
+| `context.md` | `CONTEXT.md` at the repo root (or per context) | 0 — grill, domain awareness |
+| `adr.md` | `docs/adr/NNNN-<slug>.md` | 0 — grill, hard-to-reverse decisions |
+
+`context.md` and `adr.md` are **format references**, not files to copy wholesale:
+the grill writes `CONTEXT.md` entries and ADRs in their shape, lazily — only once
+there is a resolved term or a decision worth recording.
 
 Seeding rule (per the ssheleg canon): create a template copy **only when the
 target is absent**; never overwrite an existing brief.

package/plugins/task-pipeline/skills/task-pipeline/templates/adr.md

@@ -0,0 +1,64 @@
+# ADR — format
+
+Architecture Decision Records live in `docs/adr/` with sequential numbering
+(`0001-slug.md`, `0002-slug.md`, …). Scan for the highest existing number and
+increment. Create the directory **lazily** — only when the first ADR is needed.
+
+> Adapted from Matt Pocock's `grill-with-docs` (MIT — see the repo LICENSE →
+> *Third-party*).
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1–3 sentences: what the context was, what was decided, and why.}
+```
+
+That's it. An ADR can be a single paragraph. The value is recording *that* a
+decision was made and *why* — not filling out sections.
+
+## Optional sections
+
+Only when they add genuine value; most ADRs need none.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by
+  ADR-NNNN`) — useful once decisions start getting revisited.
+- **Considered options** — only when the rejected alternatives are worth
+  remembering.
+- **Consequences** — only when non-obvious downstream effects need calling out.
+
+## When to write one
+
+All three must hold:
+
+1. **Hard to reverse** — changing your mind later carries real cost.
+2. **Surprising without context** — a future reader will look at the code and
+   wonder "why on earth did they do it this way?"
+3. **A real trade-off** — genuine alternatives existed and one was picked for
+   specific reasons.
+
+Easy to reverse → skip it, you'll just reverse it. Not surprising → nobody will
+wonder. No real alternative → there's nothing to record beyond "we did the obvious
+thing."
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "The write model is
+  event-sourced; the read model projects into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate via
+  domain events, not synchronous HTTP."
+- **Technology choices carrying lock-in.** Database, message bus, auth provider,
+  deployment target — not every library, just the ones that would take a quarter to
+  swap out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer
+  context; others reference it by ID only." The explicit no's are as valuable as
+  the yes's.
+- **Deliberate deviations from the obvious path.** "Manual SQL instead of an ORM
+  because X." Anything a reasonable reader would assume the opposite of — this is
+  what stops the next engineer from "fixing" something deliberate.
+- **Constraints invisible in the code.** "No AWS, for compliance." "Sub-200ms
+  responses, per the partner API contract."
+- **Rejected alternatives whose rejection is non-obvious.** Considered GraphQL,
+  picked REST for subtle reasons → record it, or someone re-proposes GraphQL in six
+  months.

package/plugins/task-pipeline/skills/task-pipeline/templates/brief.md

@@ -0,0 +1,59 @@
+# 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 | … | … | … |
+
+## Autonomy (the sweep — stages 1→9 read this instead of asking)
+
+Every row is either a resolved answer or an explicit **STOP AND ASK**. A blank row
+is not neutral — it is a scheduled interruption.
+
+| Stage | Question | Answer |
+|---|---|---|
+| run-wide | Model for this run | … (most capable available unless overridden; per-stage overrides here) |
+| run-wide | Decide autonomously vs escalate to me | … |
+| 1 Docs | External libs/APIs/SDKs in play; any context7 can't resolve → where their docs live | … |
+| 2–3 Spec | UI verdict (arms super-ux); scenario-tracing waiver, if any | … |
+| 4–5 Dev | Base branch; worktree/branch policy; is `main` off-limits; commit convention; task tracker | … |
+| 6 Tests | Test command; what "green" means; known-red baseline; coverage expectation | … |
+| 7 Lint | Lint command (incl. `docs/ux/lint.py` for UI projects) | … |
+| 7 Deploy | Target + path; release automation on/off; deploy-from-main rule | … |
+| 7 Deploy | **Authorization** — standing go, or ask every time? | … |
+| 8 Post-deploy | Where logs / health live (app name, endpoint, workflow) | … |
+| 9 Docs+wiki | Which module docs / runbooks this change updates; wiki sync yes/no | … |
+
+> **Deploy authorization has a hard floor.** A standing go counts only if it is
+> **specific** — named target and named preconditions ("staging, once lint and the
+> full suite are green; production always asks"). Vague blanket permission does not
+> authorize an outward, irreversible action; stage 7 stops and asks.
+
+## Done-criteria
+
+- Observable, verifiable conditions that mean "this task is finished".
+
+## Open assumptions / risks
+
+- Assumption → how it's validated (or flagged risky-untested).

package/plugins/task-pipeline/skills/task-pipeline/templates/context.md

@@ -0,0 +1,87 @@
+# CONTEXT.md — format
+
+The project's living glossary. The stage-0 grill writes to it **inline**, as each
+term is resolved. Seeded at the repo root (`CONTEXT.md`) for a single-context repo.
+
+> Adapted from Matt Pocock's `grill-with-docs` (MIT — see the repo LICENSE →
+> *Third-party*).
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentences: what this context is and why it exists.}
+
+## Language
+
+**Order**:
+A confirmed request from a Customer for goods or services.
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+
+## Relationships
+
+- An **Order** produces one or more **Invoices**
+- An **Invoice** belongs to exactly one **Customer**
+
+## Example dialogue
+
+> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"
+> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed."
+
+## Flagged ambiguities
+
+- "account" was used to mean both **Customer** and **User** — resolved: these are
+  distinct concepts.
+```
+
+## Rules
+
+- **Be opinionated.** Several words for one concept → pick the best, list the rest
+  as aliases to avoid.
+- **Flag conflicts explicitly.** An ambiguous term goes under *Flagged ambiguities*
+  with its resolution.
+- **Keep definitions tight.** One sentence. Define what it IS, not what it does.
+- **Show relationships.** Bold the term names; express cardinality where obvious.
+- **Only project-specific terms.** General programming concepts (timeouts, error
+  types, utility patterns) don't belong, however heavily the project uses them.
+  Before adding: is this unique to this context, or just programming?
+- **Group under subheadings** when natural clusters emerge; a flat list is fine
+  when the terms are one cohesive area.
+- **Write an example dialogue** — a dev and a domain expert using the terms
+  naturally, which is what exposes the boundaries between related concepts.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** one `CONTEXT.md` at the root.
+
+**Multiple contexts:** a `CONTEXT-MAP.md` at the root lists them, where they live,
+and how they relate:
+
+```md
+# Context Map
+
+## Contexts
+
+- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
+- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced`; Fulfillment consumes it to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched`; Billing consumes it to invoice
+- **Ordering ↔ Billing**: shared types for `CustomerId` and `Money`
+```
+
+Which structure applies is inferred: `CONTEXT-MAP.md` exists → read it to find the
+contexts; only a root `CONTEXT.md` → single context; neither → create the root file
+lazily, when the first term is resolved.

package/templates/brief.md

@@ -1,35 +0,0 @@
-# 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).