task-pipeline-skill 0.12.0 → 1.0.0

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

@@ -0,0 +1,195 @@
+# Plan — stage 4, built in
+
+Turning the spec into an implementation plan a **zero-context implementer** can
+execute task by task without reading the spec, the chat, or the rest of the plan.
+Built into this skill; nothing to install.
+
+> Ported from the `writing-plans` skill in
+> [obra/superpowers](https://github.com/obra/superpowers) (MIT — see `LICENSE` →
+> *Third-party*), extended with the dependency graph, parallel groups and
+> file-ownership rules this pipeline's stage-5 subagent build depends on.
+
+## Audience
+
+Assume a skilled developer who knows nothing about this codebase, this domain or
+this toolset, has questionable taste, and will read **only their own task**.
+Everything they need is in that task: exact paths, complete code, exact commands,
+expected output. DRY. YAGNI. TDD. Frequent commits.
+
+Path: `docs/superpowers/plans/YYYY-MM-DD-<topic>.md` — same `<topic>` slug as the
+brief and the spec.
+
+## Before writing tasks
+
+**Scope check.** A plan covers exactly **one** spec — for a decomposed platform,
+one module's dossier ([`decomposition.md`](decomposition.md)). If the spec in front
+of you covers several independent subsystems, the decomposition was missed at stage
+2: say so and go back there for a module map, rather than inventing the split here.
+Whatever this plan covers must produce working, testable software on its own.
+
+**Map the file structure.** List every file that will be created or modified and
+what each one owns. This is where decomposition gets locked in:
+
+- One clear responsibility per file; clear boundaries, defined interfaces.
+- Files that change together live together. Split by responsibility, not by
+  technical layer.
+- Follow the existing codebase's patterns. Don't unilaterally restructure — but if
+  a file you're modifying has grown unwieldy, planning its split is fair.
+
+**Draw the dependency graph.** Which task needs what from which. Then group tasks
+into **parallel groups** in topological order, and tag each task
+`depends: [task ids]`.
+
+**File ownership is exclusive within a group.** No two tasks in the same parallel
+group write the same file — that is the rule that makes stage-5 fan-out safe.
+Sequential integration/glue tasks sit *between* groups.
+
+## Task right-sizing
+
+A task is the smallest unit that carries its own test cycle and is worth a fresh
+reviewer's gate. Fold setup, configuration, scaffolding and docs into the task
+whose deliverable needs them. Split only where a reviewer could meaningfully reject
+one task while approving its neighbor. Every task ends with an independently
+testable deliverable.
+
+Each **step** inside a task is one action, 2–5 minutes: write the failing test →
+run it and watch it fail → minimal implementation → run it and watch it pass →
+commit.
+
+## Plan header — required
+
+```markdown
+# <Feature> — implementation plan
+
+> **For agentic workers:** execute this plan task-by-task under the task-pipeline
+> stage-5 build doctrine — isolated workspace, one implementer per task, a review
+> with all three verdicts after each (spec compliance, REQ satisfied, code
+> quality). Steps use `- [ ]` checkboxes.
+
+**Goal:** <one sentence>
+
+**Architecture:** <2–3 sentences>
+
+**Tech stack:** <key technologies>
+
+**Spec:** docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
+
+## Global constraints
+
+<the spec's project-wide requirements — version floors, dependency limits, naming
+and copy rules, platform requirements — one line each, exact values copied
+verbatim from the spec. Every task's requirements implicitly include this section.>
+
+## Execution order
+
+| Group | Tasks | Runs after |
+|---|---|---|
+| A | 1, 2 | — |
+| B | 3 | A |
+
+---
+```
+
+## Task structure — required
+
+````markdown
+### Task N: <component>
+
+**Depends:** [task ids, or —]
+
+**Implements:** REQ-003, REQ-007 — *(the brief's requirement ids this task
+delivers, or `—` for pure glue/infrastructure tasks. Quote each REQ's one-line
+statement under the DoD so the zero-context implementer sees the intent, not just
+the instruction.)*
+
+**Files:**
+- Create: `exact/path/to/file.py`
+- Modify: `exact/path/to/existing.py:123-145`
+- Test: `tests/exact/path/to/test_file.py`
+
+**Interfaces:**
+- Consumes: <what this task uses from earlier tasks — exact signatures>
+- Produces: <what later tasks rely on — exact names, parameter and return types.
+  The implementer sees only this task; this block is how they learn the names
+  neighboring tasks use.>
+
+**Definition of done:** <observable, verifiable conditions — tests green, behavior
+demonstrated, docs updated in this same change>
+
+- [ ] **Step 1: write the failing test**
+
+```python
+def test_specific_behavior():
+    assert function(input) == expected
+```
+
+- [ ] **Step 2: run it and confirm it fails**
+
+Run: `pytest tests/path/test_file.py::test_specific_behavior -v`
+Expected: FAIL — `NameError: name 'function' is not defined`
+
+- [ ] **Step 3: minimal implementation**
+
+```python
+def function(value):
+    return expected
+```
+
+- [ ] **Step 4: run it and confirm it passes**
+
+Run: `pytest tests/path/test_file.py::test_specific_behavior -v`
+Expected: PASS
+
+- [ ] **Step 5: commit**
+
+```bash
+git add tests/path/test_file.py src/path/file.py
+git commit -m "feat: <what changed>"
+```
+````
+
+For UI tasks, every task that builds user-facing behavior 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.
+
+## No placeholders
+
+These are plan failures. Never write them:
+
+- "TBD", "TODO", "implement later", "fill in details"
+- "Add appropriate error handling" / "add validation" / "handle edge cases"
+- "Write tests for the above" without the actual test code
+- "Similar to Task N" — repeat the code; tasks get read out of order
+- A step that says what to do without showing how (code steps need code blocks)
+- References to types, functions or methods no task defines
+
+## Self-review — before handing off
+
+A checklist you run yourself, inline. No subagent:
+
+1. **REQ coverage — set equality, not a feeling.** Collect every `Implements:` id
+   across all tasks and compare it to the brief's REQ table. The two sets must be
+   **equal**: a REQ with no task is scope silently lost; an `Implements:` id that
+   isn't in the brief is either a typo or work nobody asked for. Print the
+   difference and fix it before anything else — this seam is where scope leaks.
+2. **Spec coverage:** walk each spec requirement. Point at the task that implements
+   it. A requirement with no task → add the task.
+3. **Placeholder scan:** search the plan for every pattern above. Fix.
+4. **Name and type consistency:** signatures, property names and types used in
+   later tasks match what earlier tasks defined. `clearLayers()` in Task 3 and
+   `clearFullLayers()` in Task 7 is a bug, not a style difference.
+5. **Parallel safety:** no two tasks in the same group write the same file; every
+   `depends:` points at a task that really produces what's consumed.
+6. **DoD present and verifiable** on every task.
+
+## GATE (auto)
+
+**Set equality first:** the REQ ids in the brief equal the union of `Implements:`
+across the plan's tasks. A non-empty difference fails the gate and is reported as
+the explicit list of dropped (or invented) requirements — this seam is where scope
+leaks, so the check is mechanical, never a judgement call.
+
+Then: every spec requirement maps to a task; no placeholders; names and types
+consistent across tasks; parallel-group tasks share no files; each task has a
+verifiable DoD. UI tasks carry their scenario IDs and `SCR-` screens. Verify all of
+it yourself and stop on failure — this gate has no operator in it.

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

@@ -0,0 +1,174 @@
+# Review — the rubric and the prompts, built in
+
+Used by stage 5's per-task reviews, its scoped re-reviews and its final
+whole-branch review ([`build.md`](build.md)). Built into this skill; nothing to
+install.
+
+> Ported from the `requesting-code-review` skill and the reviewer prompts in
+> [obra/superpowers](https://github.com/obra/superpowers) (MIT — see `LICENSE` →
+> *Third-party*), condensed into one rubric plus three copy-paste prompts, with the
+> external helper scripts replaced by plain git commands so the doctrine works on
+> any agent.
+
+## The diff package
+
+A reviewer never re-derives the diff with a dozen git calls, and the diff never
+enters **your** context. Write it to one file and pass the path (`$WORKSPACE` is
+this plan's git-ignored directory, `.task-pipeline/build/<plan-basename>/` — see
+[`build.md`](build.md)):
+
+```bash
+{ git log --oneline "$BASE..$HEAD"
+  echo
+  git diff --stat "$BASE..$HEAD"
+  echo
+  git diff -U10 "$BASE..$HEAD"
+} > "$WORKSPACE/review-task-$N-$(git rev-parse --short "$HEAD").md"
+```
+
+`BASE` is the commit you recorded **before** dispatching the implementer — never
+`HEAD~1`, which silently drops every commit but the last of a multi-commit task.
+For a scoped re-review, `BASE` is the head the previous review saw. For the final
+review, `BASE` is `git merge-base "$BASE_BRANCH" HEAD` — the base branch recorded
+in the stage-0 brief, which is not always `main`.
+
+Never dispatch a reviewer without a diff file.
+
+## Reviewer inputs
+
+Four things, three of them paths:
+
+1. The **task brief** file — what was required.
+2. The **implementer report** file — what was done, with the test evidence.
+3. The **diff package** path.
+4. The **Global Constraints** that bind this task — copied **verbatim** from the
+   plan: exact values, exact formats, stated relationships ("same layout as X",
+   "matches Y"). This block is the reviewer's attention lens.
+
+## Controller rules
+
+- **Never pre-judge.** Don't tell a reviewer to ignore something, don't cap a
+  severity, don't explain why a finding would be a false positive. If your prompt
+  contains "don't flag", "at most Minor", or "the plan chose this" — stop: you're
+  buying yourself a shorter loop with an unreviewed defect. Let the finding come and
+  adjudicate it in the loop.
+- **Don't ask a reviewer to re-run tests** the implementer already ran on the same
+  code; the report carries the evidence.
+- **No open-ended directives** ("check all uses", "run race tests if useful")
+  without a concrete, task-specific reason.
+
+## The rubric
+
+Review in this order; stop reading the diff only when you've covered all of it.
+
+1. **Spec compliance.** Every requirement in the brief: met, partially met, or
+   missing. Anything built that the brief did *not* ask for is scope creep — flag
+   it, even when it's nice.
+2. **REQ satisfaction.** Read the task's `Implements:` requirement statements, not
+   just its instructions, and judge the diff against **those**. A task can satisfy
+   every line of its brief and still miss the requirement it exists to deliver —
+   that gap is invisible one level down, which is why it is asked for here.
+3. **Correctness.** Logic errors, off-by-one, wrong operator, unhandled `None`/nil,
+   race conditions, resource leaks, wrong error propagation. State the concrete
+   input or state that produces the wrong output — a finding without a failure
+   scenario is an opinion.
+4. **Global constraints.** Exact values, formats and relationships from the
+   constraints block. Approximations are failures.
+5. **Test honesty.** Tests assert on real behavior, not on mocks. No test that
+   passes regardless of the production code. No `skip`/`xfail`/commented assertion
+   smuggling a red suite past a gate. New behavior has a covering test; the failure
+   path has one too.
+6. **Error handling and degradation.** Every external call (network, DB, file, MCP,
+   API) handles failure, and the failure is reported honestly rather than swallowed.
+7. **Boundaries and clarity.** One responsibility per unit; names that say what the
+   thing is; no duplication of a logic block that should be shared; nothing left
+   dead.
+8. **Security.** No secrets in code, logs or fixtures; input validated at the
+   boundary; no new injection or path-traversal surface.
+9. **Docs in the same change.** Module docs, runbooks and (for UI work) the
+   super-ux layers updated alongside the code, not deferred.
+
+**Severities:**
+
+- **Critical** — wrong behavior, data loss, security hole, a red or dishonest test
+  suite. Blocks.
+- **Important** — a real defect or spec gap that will bite: missing requirement,
+  unhandled failure path, a magic value the constraints named. Blocks.
+- **Minor** — style, naming, a nit with no behavioral consequence. Never blocks;
+  goes to the ledger.
+- **⚠️ Cannot verify from diff** — the requirement lives in unchanged code or spans
+  tasks. Not a blocker for the reviewer; the controller resolves it.
+
+Formatting nits that don't change meaning are not findings. Praise is not a
+finding either.
+
+## Prompt — task review
+
+> You are reviewing one task of an implementation plan. Read, in order:
+> `<brief path>` (the requirements), `<report path>` (what the implementer did and
+> the test evidence), `<diff package path>` (commits, stat, full diff).
+>
+> Global constraints binding this task:
+> ```
+> <verbatim block>
+> ```
+>
+> Produce three verdicts, all required:
+> 1. **Spec compliance:** ✅ or ❌. List every requirement as met / partial /
+>    missing, and list anything implemented that was not asked for.
+> 2. **REQ satisfied:** ✅ or ❌ per `Implements:` id. The brief quotes each
+>    requirement's statement — judge the diff against **that statement**, not
+>    against the task's instructions. A task can follow every instruction and still
+>    miss the requirement it exists to deliver; say so when it does.
+> 3. **Code quality:** approved or not. Findings only, each as
+>    `severity — file:line — the defect — the failure scenario (concrete input or
+>    state → wrong result)`. Severities: Critical, Important, Minor. Use
+>    `⚠️ cannot verify from diff` for anything you can't judge from the diff alone.
+>
+> Review against the rubric: correctness, global constraints, test honesty (tests
+> assert real behavior, not mocks; no skipped/empty assertions), error handling and
+> honest degradation, boundaries and naming, security and secrets, docs updated in
+> the same change. No praise, no formatting nits that don't change meaning. Do not
+> re-run the tests the report already covers. Return the verdicts and findings as
+> your final message — nothing else.
+
+## Prompt — scoped re-review
+
+> A previous review of this task raised the findings below. The implementer has
+> since pushed fixes. Read `<brief path>`, `<report path>` (its fix report is
+> appended at the end) and `<fix diff package path>` — the fix diff **only**.
+>
+> Open findings:
+> ```
+> 1. <finding>
+> 2. <finding>
+> ```
+>
+> For each finding return `ADDRESSED` (with the `file:line` that resolves it) or
+> `NOT ADDRESSED` (with what's still wrong). Then flag any **new** Critical or
+> Important breakage introduced by this fix diff. Out-of-scope observations about
+> code this diff didn't touch: list them separately as deferred minors — they are
+> not part of this verdict. End with: all findings addressed / N still open.
+
+## Prompt — final whole-branch review
+
+> Review this entire branch before merge. Read `<diff package path>` (merge-base to
+> HEAD) and `<spec path>`.
+>
+> Findings deferred or parked during implementation:
+> ```
+> <the ledger's minor + parked lines>
+> ```
+>
+> Judge the branch as a whole: does it deliver the spec; do the pieces fit; is
+> anything half-migrated, duplicated across tasks, or left dead; are the tests
+> honest and the suite genuinely green; is error handling consistent; are docs in
+> sync. Triage the deferred/parked list: which of those must be fixed before merge,
+> which can stand and why. Findings only, with severity and a concrete failure
+> scenario each. Return the findings as your final message.
+
+Run the final review on the **run's confirmed model** like everything else
+([`model-tiering.md`](model-tiering.md)). It is the one review that sees the whole
+change, so if the run is on a tier below the most capable one available, say so and
+offer to escalate just this dispatch — a recommendation stated out loud, never a
+silent switch (`build.md` → *Models*).

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

@@ -0,0 +1,144 @@
+# Spec — stage 3, built in
+
+Writing the approved design down so a zero-context implementer — human or subagent
+— can build from it without asking. Built into this skill; nothing to install.
+
+> The spec write-up, its self-review pass and the operator-review gate are ported
+> from the tail of the `brainstorming` skill in
+> [obra/superpowers](https://github.com/obra/superpowers) (MIT — see `LICENSE` →
+> *Third-party*), extended here with the UX track and the Global Constraints block
+> that stages 4–5 depend on.
+
+## Order of operations
+
+For a **user-facing task** (stage-2 UI verdict = yes) the UX chain runs **first** —
+scenarios before interface, always. For everything else, go straight to *Write the
+spec*.
+
+## UX track (user-facing tasks only)
+
+Runs on **super-ux** — the one companion this pipeline recommends by name
+([`companion-skills.md`](companion-skills.md)). If it isn't installed on a UI task,
+give the install line and stop; don't improvise a half-chain.
+
+1. `/ux` — the single 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, 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 and
+   state with a wireframe and, when Figma is on, a frame link.
+4. `ux-scenarios` → `docs/ux/scenarios.md` — the **WHAT**, the source of truth for
+   user-facing behavior: scenarios validated against super-ux's format contract —
+   IDs, statuses, `Traces:` to stories / journey stages / flows, edge and error
+   states enumerated.
+5. **Run the linter** (`/ux-lint`, i.e. `python3 docs/ux/lint.py`). It must pass:
+   no drift, no orphans, no broken traces, no stale Figma links.
+
+These skills are **idempotent** — extend the existing `docs/ux/` layers, never
+rebuild them. If the chain already exists and is validated (typically when the run
+entered from super-ux), verify it and embed it; build only what's missing.
+
+## Write the spec
+
+Path: `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`, committed, **same
+`<topic>` slug as the brief** so brief → design → plan is traceable at a glance.
+(The directory name is this pipeline's historical convention, not a dependency on
+anything; a host project may relocate the root via its `CLAUDE.md` — keep the
+shape. See [`artifacts.md`](artifacts.md).)
+
+**Every section carries `covers: REQ-…`** — the brief's requirement ids it serves.
+This is what makes the brief→spec seam checkable instead of a re-telling: at the
+gate, every REQ must appear in at least one section, and a section that covers no
+REQ is either scope creep or a missing REQ. Say which.
+
+The spec **locks every shared contract**, because from here on people and subagents
+work from it in parallel and can't renegotiate:
+
+- **Types, schemas, signatures** — exact names, exact parameter and return types.
+- **File layout** — which files exist, what each one owns.
+- **Global Constraints** — the project-wide requirements every task inherits:
+  version floors, dependency limits, naming and copy rules, platform requirements,
+  exact values. Stage 4 copies this block verbatim into the plan and stage 5 hands
+  it to every reviewer, so write it as literal values, never as prose.
+- **Error handling and degradation** — what fails how, what the user sees, what
+  gets logged.
+- **Testing approach** — what proves this works.
+
+For UI tasks the spec **embeds the UX layer**: the validated scenario IDs, the
+flows and `SCR-` screens, the CJM stages the feature serves, and the applicable
+super-ux patterns and principles. Every user-facing requirement traces to a
+scenario ID.
+
+## Module dossier — when the run is one brick of a platform
+
+If stage 2 produced a module map ([`decomposition.md`](decomposition.md)), this
+spec is that module's **dossier**, and it is the only document the module's build
+gets. Cover all of it, in this order, each section carrying its `covers: REQ-…`:
+
+1. **Purpose and boundary** — what this module delivers, and what it explicitly
+   does not (naming the module that does).
+2. **Architecture** — the module's internal shape: units, responsibilities, the
+   flow of a request or event through it, and where it sits in the platform.
+3. **Entities and data** — the entities this module **owns** (it is their source of
+   truth), their fields and invariants, their lifecycle/state transitions, storage
+   and migrations. Entities owned elsewhere are referenced by id, never copied into
+   a second source of truth.
+4. **Contracts — in and out.** For every inbound API/event this module serves and
+   every outbound one it consumes: exact signature or schema, auth, idempotency,
+   versioning, and **the behavior when the other side is unavailable or wrong**.
+   These are the seams the map named; here they get their shapes.
+5. **Business logic and rules** — the rules in the domain's language, each with the
+   condition that triggers it and the outcome. Rules that only exist as code are
+   rules nobody can review.
+6. **Edge and failure cases** — the boundaries (empty, first, last, maximum,
+   concurrent), the failure modes (timeout, partial write, duplicate delivery,
+   downstream down) and the honest degradation for each. This is the section that
+   decides whether the module survives contact with production, so it is not a
+   bullet list of "handle errors".
+7. **UI / Figma** — for a module with a surface: the super-ux chain (foundation →
+   flows → screens → scenarios), the `SCR-` screens and their Figma frame links,
+   and the states each screen has (loading, empty, error, partial).
+8. **Non-functional** — limits, expected volumes, latency budget, security and
+   privacy constraints that bind this module specifically.
+9. **Open questions** — anything still undecided, with the latest moment it can be
+   decided and who decides. An open question that reaches the plan becomes an
+   implementer's guess.
+
+A dossier that skips a section says why in one line (`no UI surface`, `owns no
+entities`). Silence is not a skip.
+
+Anything the stage-1 docs study could not ground (a library context7 can't resolve,
+a private API) is **flagged in the spec** as an assumption, not silently assumed.
+
+## Self-review — before showing it
+
+Read what you wrote with fresh eyes and fix inline. No subagent, no second pass:
+
+1. **REQ coverage:** does every REQ in the brief appear in at least one section's
+   `covers:` line, and does every section cover at least one REQ? A missing REQ is
+   scope lost here; a section covering none is scope creep or a missing REQ.
+2. **Placeholders:** any TBD / TODO / "handle edge cases" / unfinished section? Fix.
+3. **Internal consistency:** do sections contradict each other? Does the
+   architecture match the feature descriptions and the locked signatures?
+4. **Scope:** is this one implementable plan, or does it need decomposition?
+5. **Ambiguity:** can any requirement be read two ways? Pick one and say it.
+6. **Traceability (UI):** does every user-facing requirement name its scenario ID?
+
+## GATE (manual)
+
+> "Spec written and committed to `<path>`. Review it and tell me if anything should
+> change before I write the implementation plan."
+
+Wait for the operator. Changes requested → apply, re-run the self-review, ask
+again.
+
+The gate is not only the operator's word: **every section carries `covers: REQ-…`
+and every REQ in the brief appears in at least one section.** For UI tasks it
+additionally requires: the chain (foundation → flows → screens → scenarios)
+designed, validated and approved; `/ux-lint` green; every user-facing requirement
+traced to a scenario ID — or an explicit waiver from the operator recorded in the
+spec.
+
+No plan starts before this gate passes.