@tianhai/pi-workflow-kit 2.4.0 → 2.6.0

package/docs/workflow-phases.md

@@ -1,5 +1,14 @@
 # Workflow Phases
 
+Phase skills keep detailed contracts local to their skill directories:
+`skills/pwk-brainstorming/references/umbrella.md`,
+`skills/pwk-brainstorming/references/design-format.md`, and
+`skills/pwk-brainstorming/scripts/validate-design.py`; plus
+`skills/pwk-executing-tasks/references/progress-format.md`,
+`skills/pwk-executing-tasks/references/resume.md`,
+`skills/pwk-executing-tasks/references/review.md`, and
+`skills/pwk-executing-tasks/scripts/build-review-packet.py`.
+
 The kit enforces a design → execute → finalize workflow. Each phase below names the skill that drives it:
 
 `pi-workflow-kit` has 4 pipeline skills plus 2 utility skills. You invoke each one explicitly with `/skill:`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianhai/pi-workflow-kit",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "Enforce structured design→execute→finalize workflow with TDD discipline in AI coding agents",
   "keywords": [
     "pi-package",

package/skills/pwk-brainstorming/SKILL.md

@@ -11,50 +11,25 @@ Read-only exploration of source code; every file you create or edit goes under `
 
 Classify the change at the start.
 
-- **Trivial** — typo or obvious bugfix with no open design questions, config/version bump, single-function change, or anything the human flags as trivial. Skip steps 3–6; write a **minimal** design doc in one turn (an `In short:` one-liner — what + why + approach in plain words, plus a single `### R1:` requirement block with its criteria and tags, and an optional `## Production-risk areas` line — and deliberately **no `## Feature acceptance`**: a trivial slice's ship gate is the full existing suite, no E2E is manufactured for it), and hand off to `/skill:pwk-executing-tasks`. The guard still enforces read-only — trivial compresses the phase to one turn, it doesn't skip it.
+- **Trivial** — typo or obvious bugfix with no open design questions, config/version bump, single-function change, or anything the human flags as trivial. Skip steps 3–6; read the design-format reference and run the validator in step 7, writing a **minimal** design doc in one turn (an `In short:` one-liner — what + why + approach in plain words, plus a single `### R1:` requirement block with its criteria and tags, and an optional `## Production-risk areas` line — and deliberately **no `## Feature acceptance`**: a trivial slice's ship gate is the full existing suite, no E2E is manufactured for it), and hand off to `/skill:pwk-executing-tasks`. The guard still enforces read-only — trivial compresses the phase to one turn, it doesn't skip it.
 - **Non-trivial** — open design questions, multiple approaches, cross-module impact, or new behavior. Run the full process below.
 
 When unsure, ask: "This looks trivial — fast-path it, or full brainstorm?" Default to full.
 
-## Granularity
+## Scope and granularity
 
-**One design doc = one PR; one requirement = one testable slice within it.** Most work is a single design doc.
+**One design doc = one PR; one requirement = one testable slice within it.** Most work is a single design doc; several requirements serving one cohesive outcome do not force an umbrella.
 
-**One folder per topic.** Every topic — a single-part design doc or an umbrella — lives in its own folder `docs/plans/<date>-<topic>/`, and that folder is the unit of creation, discovery, and disposal. The topic's docs are leaves inside it: `<leaf>-design.md`, `<leaf>-progress.md`, `<leaf>-review-packet*.md`, where `<leaf>` is the part slug (`<topic>` itself for a single-part topic — the everyday case). A folder holding more than one leaf also carries an `overview.md`, and that is all "umbrella" means: a topic whose requirement was split into several design docs that still ship as one PR.
+Before drafting, assess whether a large request has distinct testable outcomes that need separate design/execute cycles. If so, propose an **umbrella** of vertical slices with one-line scopes and a build order, and get human approval before writing an overview or design. A layers-only split (database, API, UI) is not a vertical split: each slice delivers testable behavior. Design only the current slice; ground later designs in implemented code, not speculative sibling designs. The umbrella still ships as one PR on one branch, finalized once.
 
-- Within a doc, decompose into **requirements** — one `### R<n>: <name>` block per requirement, each one testable behavior carrying its own acceptance criteria and tags.
-- A requirement too big for one design doc but shipping as a single PR is an **umbrella** — multiple design docs decomposed under one overview, on one branch, finalized once. See [Umbrella](#umbrella) below.
+**One folder per topic:** `docs/plans/<date>-<topic>/`, containing `<leaf>-design.md`, `<leaf>-progress.md`, and `<leaf>-review-packet*.md`; `<leaf>` is `<topic>` for a single-part topic. More than one leaf adds `overview.md`. The whole folder is the creation/discovery/disposal unit.
 
-## Umbrella
-
-An umbrella splits one large requirement into multiple design docs that ship together as **one PR**. It is the single-topic folder above with more than one leaf: one branch, one `pwk-finalizing` at the end, which disposes the folder as one unit. The split is intra-PR decomposition — a way to keep each design/execute cycle small and focused, not a multi-PR strategy.
-
-**First brainstorm** (the requirement is too big for one design doc):
-
-1. **Propose the split** — the parts, a one-line scope each, and build order. Get human approval before writing anything beyond discovery.
-2. **Write the overview** — `docs/plans/<date>-<topic>/overview.md`, in the topic's own folder (every leaf lives beside it: `<leaf>-design.md`, `<leaf>-progress.md`, `<leaf>-review-packet*.md`), a **status-free roster**:
-
-   ```markdown
-   # Overview: <topic>
-
-   Goal: <one line — what the whole requirement delivers>
-
-   ## Parts (build order)
-   1. <leaf> — <one-line scope>
-   2. <leaf> — <one-line scope>
-   ```
-
-   The `## Parts (build order)` heading and the `N. <leaf> — <one-line scope>` item shape together are the **roster contract**: `pwk-finalizing` and `pwk-status` both read them, and both are lint-pinned so a drifted heading fails loudly instead of reading an empty roster. Goal, parts with one-line scopes, build order — **no status column**. No skill mutates the overview between this write and `pwk-finalizing` (which disposes it); part-completion is inferred from each leaf's own `*-progress.md`.
-3. **Write the first part's design doc** — `docs/plans/<date>-<topic>/<leaf>-design.md` in the same folder, then hand off to `/skill:pwk-executing-tasks`.
-
-**Later parts** — re-run `/skill:pwk-brainstorming` for the next part. Read the overview for big-picture/roster context (which slice is yours, which siblings exist), then report each prior leaf's `Feature phase:` line (matched header-only — `grep -m1 '^Feature phase:' <leaf>-progress.md` beside the overview — no body ingest; a leaf with no progress file yet reports `not started`) before designing the slice, then explore the codebase to design your slice **as brainstorm always does** — prior parts are just implemented code in the repo by then. Predecessor phases are visibility, not enforcement: design the slice regardless; cross-slice decisions that must persist go in an ADR, not the overview.
-
-The whole umbrella is one branch and one PR: `pwk-executing-tasks` creates the branch in its pre-flight and reuses it for later parts, and suggests the next part (or finalize after the last); `pwk-finalizing` disposes the whole folder — overview + every leaf — and ships one PR.
+**Umbrella trigger:** before proposing or writing a new umbrella, or when discovery finds an existing `overview.md` beside this design, read [references/umbrella.md](references/umbrella.md). It defines the status-free roster, first/later-slice procedures, and header-only predecessor reporting. Build order is advisory, not an enforcement gate. An existing roster means the split is already decided; design the current slice against it.
 
 ## Process
 
 1. **Check git state** — `git status` + `git log --oneline -5`. Uncommitted work? Ask the user what to do first.
-2. **Discovery** *(skip in a brand-new repo with no `docs/plans/`)* — first verify the repo root: run `pwd` (or your shell's equivalent) and `git rev-parse --show-toplevel`; mismatch → report both paths and stop; never `cd` (a worktree root counts). Then list `docs/plans` recursively, excluding docs/plans/completed/, for `*-design.md`, `*-progress.md`, and `overview.md` (topic docs live in `docs/plans/<date>-<topic>/` folders — archived work is not in flight). Use whatever recurses in your harness; one example: `find docs/plans -name '<suffix>' -not -path '*/completed/*'`; report in-flight topics and any active umbrella. For each in-flight topic with a progress file, report its `Feature phase:` line (matched header-only — `grep -m1 '^Feature phase:' <file>` — no body ingest); design-only topics report `design`. If the new idea continues an existing topic, ask whether to extend it or start fresh. Part of an umbrella? An existing `overview.md` **beside the design doc** means the split is already decided — read it for the roster and design this part's `<leaf>-design.md` against it (see [Umbrella](#umbrella)).
+2. **Discovery** *(skip in a brand-new repo with no `docs/plans/`)* — first verify the repo root: run `pwd` (or your shell's equivalent) and `git rev-parse --show-toplevel`; mismatch → report both paths and stop; never `cd` (a worktree root counts). Then list `docs/plans` recursively, excluding docs/plans/completed/, for `*-design.md`, `*-progress.md`, and `overview.md` (topic docs live in `docs/plans/<date>-<topic>/` folders — archived work is not in flight). Use whatever recurses in your harness; one example: `find docs/plans -name '<suffix>' -not -path '*/completed/*'`; report in-flight topics and any active umbrella. For each in-flight topic with a progress file, report its `Feature phase:` line (matched header-only — `grep -m1 '^Feature phase:' <file>` — no body ingest); design-only topics report `design`. If the new idea continues an existing topic, ask whether to extend it or start fresh. Part of an umbrella? An existing `overview.md` **beside the design doc** means the split is already decided — read it for the roster and design this part's `<leaf>-design.md` against it (read [references/umbrella.md](references/umbrella.md) before proceeding).
 3. **Understand the idea** — read only enough code/docs/commits to ground the design. **Check `docs/lessons.md`** — known constraints may shape it. Ask questions in **frontier rounds**: build a question tree seeded by the dimension checklist, then ask in rounds. The **frontier** is every question whose prerequisites are already settled — ask the whole frontier in one round; a question whose answer depends on another still-open question waits for a later round. Number each question (`Q1`, `Q2`, …) and attach your recommended answer (`➡️ <recommendation>`) — the recommendation is your assumption surfaced up front; the human confirms, strikes, or corrects each in one reply. Recompute the frontier after each round of answers. Seed the tree by walking every checklist dimension — *Goal & scope · Data & state · Behavior & edge cases · Errors & failure · Integration · Non-functional* — printing `— nothing to ask` for groups with no questions (never skip silently). **Facts vs. decisions**: anything answerable from the codebase, docs, or tools is looked up — recon scout or inline — never asked of the human; a pending lookup is an unsettled prerequisite that holds only its downstream questions, while the rest of the frontier is asked now. Only decisions are asked. Major approvals stay single-decision — one question each, never batched: approach selection (step 5), umbrella split, design approval, ADR offer. The interview ends when the frontier is empty — every branch visited, nothing left silently assumed — not when you feel you understand. Then present a short summary and ask: "Should I proceed, or is there more?" The human decides when to move on.
 4. **(skipped on trivial changes)** **Codebase recon** — for non-trivial topics with prior art, request the host’s `codebase-recon` capability using the logical `pwk-recon-scout` role. Require a fresh-context, read-only, bounded worker and pass the topic, one-line intent, and repo root. Use the returned 5-section codebase map (Relevant files, Existing patterns, Call sites, Test layout, Gotchas) as the grounding context for the next two steps instead of reading those files inline. The scout is observations only — no design recommendations. Skip this step on trivial changes (typo, version bump, single-function edit per the proportionality rule). If no compatible capability is available or the provider cannot enforce the requested constraints, report `Scout: unavailable` and do the same recon inline, preserving the five-section map and `file:line` citations; do not silently omit recon.
 5. **Explore approaches** — propose 2–3, leading with your recommendation. Sketch the concrete interface (types, signatures, example caller) for each so the comparison is grounded in code, not abstractions.
@@ -63,60 +38,19 @@ The whole umbrella is one branch and one PR: `pwk-executing-tasks` creates the b
    **Assumptions to confirm first** — before presenting, sweep the drafted design: every assumption it would bake in unconfirmed (business rules, defaults, edge-case resolutions) re-opens as a numbered question carrying your recommended answer; the human confirms, strikes, or corrects each in one reply. An honest empty gate ("no unconfirmed assumptions") when the draft is clean — never invent items. Hard rule: no business behavior enters the design doc on the agent's assumption. Confirmed facts are woven into the doc's existing sections — no new template section.
 
    Identified a significant architectural decision? Offer an ADR in `docs/adr/`. Only when all three hold: **hard to reverse**, **surprising without context**, **a real trade-off**. Format: title + 1–3 sentences of context/decision/why. ADRs are permanent institutional memory — they stay out of archive/rotation forever. (Guard note: `docs/adr/` is outside the writable `docs/plans/`; the human writes the approved ADR themselves or briefly runs `/pwk-guard off` — the agent never writes it while the design phase is gated.)
-7. **Write the design doc** — `docs/plans/<date>-<topic>/<leaf>-design.md`, creating the topic folder when absent (`<leaf>` is `<topic>` for a single-part topic — the everyday case), descriptive (not a task list). This is the single artifact the executor builds from.
-
-   **Open with `## At a glance`** — the human's two-minute digest, immediately before `## Requirements`. It contains (1) a 2–4 sentence plain-language summary: what is wrong or needed, what will be built, the key approach in plain words; (2) **Key decisions** — one line each: decision + why, with a `(rejected: <alternative> — <reason>)` clause only when the fork was real and load-bearing (never manufactured — no fork, no clause); (3) a table `| R# | Requirement in one line | Risk |` with exactly one row per requirement, where **R# = the requirement's block number in the `## Requirements` section below** — this ID is what every later digest keys on (progress rows, execution summary, reviewer coverage table). Plain language only: short sentences, no jargon, no Given/When/Then — those live in the requirement blocks for the executor. An umbrella overview gains no at-a-glance section; its roster already serves that role.
-
-   Then **`## Requirements`** — one block per requirement, each one testable behavior:
-
-   ```markdown
-   ## Requirements
+7. **Write the design doc** — validate its structure before handing off; before writing either a trivial or non-trivial doc, read [references/design-format.md](references/design-format.md) for the exact format, tag defaults, risk/Setup rules, and audit. Requirement blocks carry acceptance criteria plus `### Checkpoints` / `### Review` tags. Missing tags default to `none` / `skip`. Write `docs/plans/<date>-<topic>/<leaf>-design.md`, creating the topic folder when absent. It is descriptive, not a task list; the executor builds directly from it.
 
-   ### R1: <name>
-   <one-line testable behavior — what the feature produces or changes, through its public interface>
+   **Completion gate:** Test observable behavior through the public interface. Audit every requirement's criteria, tags, and risk notes; confirm each appears exactly once. For non-trivial work, finish with end-to-end `## Feature acceptance` as the primary enforced spec. If writing a scenario step would require inventing behavior, that invention goes back through the assumption gate — an unwritable step means an unspecified requirement, not permission to guess. Risk notes never set the tag — the written `### Review` value stays `skip` unless the human sets it, and only the human tags a slice for review. Keep designing until the requirements compose into a coherent feature and the human approves the design, including feature acceptance. Trivial work retains the compressed one-turn path above, not another recurring approval stop.
 
-   **Acceptance criteria** — Given/When/Then criteria defining "done". Test observable behavior — what the feature produces or changes through its public interface; not implementation steps. Cover edge and error cases.
-   - Given … When … Then …
-   - Given … When … Then … (edge case)
+   **Python prerequisite:** structural validation requires Python 3.9+ where commands execute, using only its standard library (no pip or project Node configuration). Confirm a compatible `python3` exists before invoking the helper. If Python is missing, unavailable, or too old, report the blocker and request a suitable runtime; stop at this gate. Do not auto-install Python, use a fallback implementation, or claim validation succeeded.
 
-   ### Checkpoints: none | full
-   ### Review: skip | parallel | inline
+   Resolve the helper from this installed skill's directory; pass explicit paths and quote paths with spaces. Relative input paths resolve from the caller's working directory, not the skill directory:
 
-   ### Production-risk notes
-   - <only when the requirement touches a risk area>
-
-   ### R2: <name>
-   …
+   ```sh
+   python3 "<brainstorming-skill-dir>/scripts/validate-design.py" "<design-path>"
    ```
 
-   Block rules:
-
-   - **No test-name lists.** The criteria are the test spec — the executor writes and names the actual tests red-green from them, so the doc contains no test-name lists and no R#-to-section mapping tables: the block structure is the map.
-   - **Tag every requirement** — `### Checkpoints` (how many human stops: `none` = no per-requirement stop, the default — the feature gate covers it; `full` = tests + complete stops) and `### Review` (per-requirement review: `skip` = none, the default; `parallel` = four delegated reviewers; `inline` = one `pwk-code-review` pass). Missing tags default to `none` / `skip`. Flag `full` only where complex logic or the main part of the feature makes a human look at the slice worth the stop.
-   - **Nothing is tagged silently here; only the human tags a slice for review.** A requirement that touches a production-risk area carries its `### Production-risk notes` in the block and is flagged `⚠ production-risk` in the At-a-glance Risk column (the column is derived, **display-only**: `⚠ production-risk` if and only if the block carries non-empty `### Production-risk notes`, else `—` — never normative, never an input; `auto` reads the underlying risk content — the `## Production-risk areas` section and the notes — never the display column), but its written `### Review` value stays `skip` unless the human sets it — propose the tag in prose, leave the field at `skip`. An explicit human tag always wins, in both directions.
-   - **No per-requirement spec stop, by design** — the acceptance criteria are approved right here, at design time; re-checking them mid-execution asks a question the human already answered.
-   - **Production-risk notes** — a requirement touching a production-risk area carries its notes inside the block. Risks involving schema migrations, new dependencies, external APIs, or seed data also get a `## Setup` section (dependencies, migrations, seed data, and how to verify setup worked) between `## Requirements` and `## Feature acceptance`.
-   - **Ordering** — dependencies come earlier in the list; the executor runs blocks in listed order with no dependency graph. Aim for vertical slices that merge cleanly on their own.
-
-   Then the narrative sections the executor reads as context — problem, approaches considered, architecture, components, data flow, error handling. Head the approaches section exactly `## Approaches considered` — finalizing's learning sweep reads it by that name. **`## Approaches considered` records every real fork and why each loser lost** — the executor needs the reasoning, and the finalize learning sweep harvests it for ADRs.
-
-   Touches a production-risk area (DB schema/migrations, auth, external APIs, concurrency/batch, uploads/large data flows, Redis/caching/queues)? Add a brief `## Production-risk areas` **immediately after the last requirement block** — inside the `### R1 → ## Feature acceptance` span, so the review packet carries it to reviewers verbatim — and mirror the risks into each touched block's `### Production-risk notes`. `pwk-code-review` audits it, per requirement when the slice is reviewed and at the feature review always; finalize's learning sweep reads it.
-
-   **End with `## Feature acceptance`** — one or more end-to-end `Given/When/Then` scenarios proving the requirements *compose* into the feature. This is the feature's definition-of-done; the human approves it as what "the feature works" means. `pwk-executing-tasks` writes it as the E2E test first and runs it as the **primary enforced spec** (the test it gates on first). The section carries the feature-level `### Feature review: auto | parallel | inline` tag — the one whole-feature review; default `auto`, which resolves on the design's own production-risk content to `parallel` (all four reviewers) when the design has any — a non-empty `## Production-risk areas` section, or a non-empty `### Production-risk notes` on any requirement — and to `inline` (one pass) otherwise. An explicit `parallel` or `inline` is written as-is, never resolved, so the human always overrides `auto`. Treat "I can write this scenario" as the green light to finish designing — if you can't, keep designing because the requirements don't yet compose into a coherent feature. If writing a scenario step would require inventing behavior, that invention goes back through the assumption gate — it may never be silently written into the scenario; an unwritable step means an unspecified requirement, so keep designing.
-
-   ```markdown
-   ## Feature acceptance
-
-   - Given <starting state>, When <trigger>, Then <end-to-end outcome the feature promises>.
-
-   ### Feature review: auto | parallel | inline — the one whole-feature review; leave `auto` unless the human says otherwise.
-   ```
-
-   Example (rate limiting): "Given a new API consumer with no prior usage, When they exceed 100 requests/minute for 3 consecutive minutes, Then they're throttled, a `rate_limited` event is emitted, and further requests return 429."
-
-   **Audit before finishing:** every requirement block has acceptance criteria and both tags, and each requirement appears **exactly once** — none dropped, none duplicated. A `## Feature acceptance` section exists as the primary enforced spec — on every non-trivial doc; a trivial doc ends after its `### R1:` block and ships on the full suite instead. Production-risk areas are reflected in the requirement blocks that touch them.
-
-   **Splitting large issues:** if the requirement needs more than one design doc, propose an umbrella split (one `<topic>` per part) and get human approval first — see [Umbrella](#umbrella). On approval, write the status-free overview (`docs/plans/<date>-<topic>/overview.md`) and the **first part's** `-design.md` beside it, then hand off to `/skill:pwk-executing-tasks`. Later parts are brainstormed one by one (each re-reading the overview) — do not write every part's design doc up front.
+   Nonzero means validation did not succeed: report file-specific diagnostics, correct structural errors, and rerun. A missing local reference or helper is a blocker before its dependent action; do not silently skip it. Success verifies structure only, never semantic correctness, sound slicing, confirmed assumptions, or human approval.
 
 The session stays read-only and uncommitted through brainstorm: branch creation and the design-doc commit happen at the start of `pwk-executing-tasks` (its pre-flight creates the feature branch).
 
@@ -131,3 +65,23 @@ The session stays read-only and uncommitted through brainstorm: branch creation
 ## After the design
 
 Ask: "Ready to execute? Run `/skill:pwk-executing-tasks`"
+
+## Contract index
+
+The detailed design contract is in `references/design-format.md`; this compact index keeps
+the pipeline markers visible to tools that inspect only the entrypoint:
+`## At a glance` → **Key decisions** → `| R# | Requirement in one line | Risk |`;
+`### R<n>: <name>` blocks contain Given/When/Then criteria, no test-name lists, and both
+tags. The feature section ends with `### Feature review: auto | parallel | inline`.
+Production-risk display is `⚠ production-risk` if and only if notes exist; alternatives
+are never manufactured. The umbrella roster uses `## Parts (build order)` and
+`N. <leaf> — <one-line scope>`.
+The design format carries `Given/When/Then criteria`, `no test-name lists`, and tags;
+the full contract also states `written \`### Review\` value stays \`skip\`` and records
+architectural deviations `at deviation time`.
+
+```markdown
+## Feature acceptance
+- Given <starting state>, When <trigger>, Then <outcome>.
+### Feature review: auto | parallel | inline
+```

package/skills/pwk-brainstorming/references/design-format.md

@@ -0,0 +1,83 @@
+# Design format
+
+Read before writing any design doc. Keep the design descriptive, not a task list. It is the single buildable artifact; no separate implementation plan.
+
+## Trivial format
+
+A trivial design has an `In short:` one-liner (what + why + approach in plain words), a single `### R1:` block with acceptance criteria and tags, and optional `## Production-risk areas`. It has no `## At a glance`, `## Requirements`, or `## Feature acceptance`; its ship gate is the full existing suite, not a manufactured E2E. Use the block rules below for its criteria, tags, and risk notes.
+
+```markdown
+# Design: <topic>
+
+In short: <what + why + approach>
+
+### R1: <name>
+<observable behavior>
+
+**Acceptance criteria**
+- Given <state>, When <action>, Then <observable outcome>.
+
+### Checkpoints: none
+### Review: skip
+```
+
+## Non-trivial format
+
+**Open with `## At a glance`** — the human's two-minute digest, immediately before `## Requirements`. It contains (1) a 2–4 sentence plain-language summary: what is wrong or needed, what will be built, the key approach in plain words; (2) **Key decisions** — one line each: decision + why, with a `(rejected: <alternative> — <reason>)` clause only when the fork was real and load-bearing (never manufactured — no fork, no clause); (3) a table `| R# | Requirement in one line | Risk |` with exactly one row per requirement, where **R# = the requirement's block number in the `## Requirements` section below** — this ID is what every later digest keys on (progress rows, execution summary, reviewer coverage table). Plain language only: short sentences, no jargon, no Given/When/Then — those live in the requirement blocks for the executor. An umbrella overview gains no at-a-glance section; its roster already serves that role.
+
+Then **`## Requirements`** — one `### R<n>: <name>` block per requirement, each one testable behavior:
+
+```markdown
+## Requirements
+
+### R1: <name>
+<one-line testable behavior — what the feature produces or changes, through its public interface>
+
+**Acceptance criteria** — Given/When/Then criteria defining "done". Test observable behavior — what the feature produces or changes through its public interface; not implementation steps. Cover edge and error cases.
+- Given … When … Then …
+- Given … When … Then … (edge case)
+
+### Checkpoints: none | full
+### Review: skip | parallel | inline
+
+### Production-risk notes
+- <only when the requirement touches a risk area>
+
+### R2: <name>
+…
+```
+
+Block rules:
+
+- **No test-name lists.** The criteria are the test spec — the executor writes and names the actual tests red-green from them, so the doc contains no test-name lists and no R#-to-section mapping tables: the block structure is the map.
+- **Tag every requirement** — `### Checkpoints` (how many human stops: `none` = no per-requirement stop, the default — the feature gate covers it; `full` = tests + complete stops) and `### Review` (per-requirement review: `skip` = none, the default; `parallel` = four delegated reviewers; `inline` = one `pwk-code-review` pass). Missing tags default to `none` / `skip`. Flag `full` only where complex logic or the main part of the feature makes a human look at the slice worth the stop.
+- **Nothing is tagged silently here; only the human tags a slice for review.** A requirement that touches a production-risk area carries its `### Production-risk notes` in the block and is flagged `⚠ production-risk` in the At-a-glance Risk column (the column is derived, **display-only**: `⚠ production-risk` if and only if the block carries non-empty `### Production-risk notes`, else `—` — never normative, never an input; `auto` reads the underlying risk content — the `## Production-risk areas` section and the notes — never the display column), but its written `### Review` value stays `skip` unless the human sets it — propose the tag in prose, leave the field at `skip`. An explicit human tag always wins, in both directions.
+- **No per-requirement spec stop, by design** — the acceptance criteria are approved right here, at design time; re-checking them mid-execution asks a question the human already answered.
+- **Production-risk notes** — a requirement touching a production-risk area carries its notes inside the block. Risks involving schema migrations, new dependencies, external APIs, or seed data also get a `## Setup` section (dependencies, migrations, seed data, and how to verify setup worked) between `## Requirements` and `## Feature acceptance`.
+- **Ordering** — dependencies come earlier in the list; the executor runs blocks in listed order with no dependency graph. Aim for vertical slices that merge cleanly on their own.
+
+Then the narrative sections the executor reads as context — problem, approaches considered, architecture, components, data flow, error handling. Head the approaches section exactly `## Approaches considered` — finalizing's learning sweep reads it by that name. **`## Approaches considered` records every real fork and why each loser lost** — the executor needs the reasoning, and the finalize learning sweep harvests it for ADRs.
+
+Touches a production-risk area (DB schema/migrations, auth, external APIs, concurrency/batch, uploads/large data flows, Redis/caching/queues)? Add a brief `## Production-risk areas` **immediately after the last requirement block** — inside the `### R1 → ## Feature acceptance` span, so the review packet carries it to reviewers verbatim — and mirror the risks into each touched block's `### Production-risk notes`. `pwk-code-review` audits it, per requirement when the slice is reviewed and at the feature review always; finalize's learning sweep reads it.
+
+**End with `## Feature acceptance`** — one or more end-to-end `Given/When/Then` scenarios proving the requirements *compose* into the feature. This is the feature's definition-of-done; the human approves it as what "the feature works" means. `pwk-executing-tasks` writes it as the E2E test first and runs it as the **primary enforced spec** (the test it gates on first). The section carries the feature-level `### Feature review: auto | parallel | inline` tag — the one whole-feature review; default `auto`, which resolves on the design's own production-risk content to `parallel` (all four reviewers) when the design has any — a non-empty `## Production-risk areas` section, or a non-empty `### Production-risk notes` on any requirement — and to `inline` (one pass) otherwise. An explicit `parallel` or `inline` is written as-is, never resolved, so the human always overrides `auto`. Treat "I can write this scenario" as the green light to finish designing — if you can't, keep designing because the requirements don't yet compose into a coherent feature. If writing a scenario step would require inventing behavior, that invention goes back through the assumption gate — it may never be silently written into the scenario; an unwritable step means an unspecified requirement, so keep designing.
+
+```markdown
+## Feature acceptance
+
+- Given <starting state>, When <trigger>, Then <end-to-end outcome the feature promises>.
+
+### Feature review: auto | parallel | inline — the one whole-feature review; leave `auto` unless the human says otherwise.
+```
+
+Example (rate limiting): "Given a new API consumer with no prior usage, When they exceed 100 requests/minute for 3 consecutive minutes, Then they're throttled, a `rate_limited` event is emitted, and further requests return 429."
+
+**Audit before finishing:** every requirement block has acceptance criteria and both tags, and each requirement appears **exactly once** — none dropped, none duplicated. A `## Feature acceptance` section exists as the primary enforced spec — on every non-trivial doc; a trivial doc ends after its `### R1:` block and ships on the full suite instead. Production-risk areas are reflected in the requirement blocks that touch them.
+
+## Structural validator contract
+
+Run `scripts/validate-design.py` as directed in the main skill. It reads UTF-8 Markdown without modifying it. Headings, tags, and labels inside backtick or tilde fenced examples do not count; close every fence. Real requirements use unique sequential `### R1: <name>`, `### R2: <name>`, … headings with nonempty names. Each block needs a standalone `**Acceptance criteria**` label in its main body, before any tag or risk-note heading (an explanatory suffix after an em dash, dash, or colon is allowed) and nonempty criteria before the next heading or bold section label. A bare bullet or content borrowed from risk notes is not a criterion section.
+
+Write each selected tag as one value, not the template's pipe-separated alternatives. Missing optional tags retain `Checkpoints: none`, `Review: skip`, and `Feature review: auto`. Non-trivial designs require nonempty `## Feature acceptance` scenarios before their feature-review tag. Only the minimal trivial shape above receives the no-Feature-acceptance exception.
+
+The helper checks structure, not meaning: it does not prove Given/When/Then quality, testability, complete edge/error coverage, good slicing, risk classification, confirmed assumptions, or human approval. Those remain the agent's audit and the human's judgment. Structural success does not complete the design gate by itself.

package/skills/pwk-brainstorming/references/umbrella.md

@@ -0,0 +1,26 @@
+# Umbrella mechanics
+
+An umbrella splits one large requirement into multiple design docs that ship together as **one PR**. It is a single-topic folder with more than one leaf: one branch, one `pwk-finalizing` at the end, which disposes the folder as one unit. Design only the current slice; ground later slices in implemented predecessor code. The split is intra-PR decomposition — a way to keep each design/execute cycle small and focused, not a multi-PR strategy.
+
+**First brainstorm** (the requirement is too big for one design doc):
+
+1. **Propose the split** — the parts, a one-line scope each, and build order. Get human approval before writing anything beyond discovery.
+2. **Write the overview** — `docs/plans/<date>-<topic>/overview.md`, in the topic's own folder (every leaf lives beside it: `<leaf>-design.md`, `<leaf>-progress.md`, `<leaf>-review-packet*.md`), a **status-free roster**:
+
+   ```markdown
+   # Overview: <topic>
+
+   Goal: <one line — what the whole requirement delivers>
+
+   ## Parts (build order)
+   1. <leaf> — <one-line scope>
+   2. <leaf> — <one-line scope>
+   ```
+
+   The `## Parts (build order)` heading and the `N. <leaf> — <one-line scope>` item shape together are the **roster contract**: `pwk-finalizing` and `pwk-status` both read them, and both are lint-pinned so a drifted heading fails loudly instead of reading an empty roster. Goal, parts with one-line scopes, build order — **no status column**. No skill mutates the overview between this write and `pwk-finalizing` (which disposes it); part-completion is inferred from each leaf's own `*-progress.md`.
+3. **Write the first part's design doc** — `docs/plans/<date>-<topic>/<leaf>-design.md` in the same folder, then hand off to `/skill:pwk-executing-tasks`.
+
+**Later parts** — re-run `/skill:pwk-brainstorming` for the next part. Read the overview for big-picture/roster context (which slice is yours, which siblings exist), then report each prior leaf's `Feature phase:` line (matched header-only — `grep -m1 '^Feature phase:' <leaf>-progress.md` beside the overview — no body ingest; a leaf with no progress file yet reports `not started`) before designing the slice, then explore the codebase to design your slice **as brainstorm always does** — prior parts are just implemented code in the repo by then. Predecessor phases are visibility, not enforcement: design the slice regardless; cross-slice decisions that must persist go in an ADR, not the overview.
+
+The whole umbrella is one branch and one PR: `pwk-executing-tasks` creates the branch in its pre-flight and reuses it for later parts, and suggests the next part (or finalize after the last); `pwk-finalizing` disposes the whole folder — overview + every leaf — and ships one PR.
+

package/skills/pwk-brainstorming/scripts/validate-design.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""Read-only validation of the workflow's Markdown design structure (Python 3.9+)."""
+
+import argparse
+from dataclasses import dataclass
+from pathlib import Path
+import re
+import sys
+from typing import List, Optional, Tuple
+
+
+TAG_VALUES = {
+    "Checkpoints": ("none", "full"),
+    "Review": ("skip", "parallel", "inline"),
+    "Feature review": ("auto", "parallel", "inline"),
+}
+HEADING = re.compile(r"^ {0,3}(#{1,6})[ \t]+(.+?)\s*#*\s*$")
+REQUIREMENT = re.compile(r"^R([1-9][0-9]*):\s*(.*)$")
+REQUIREMENT_LIKE = re.compile(r"^R(?:[0-9]|\s*:)")
+CRITERIA = re.compile(r"^\*\*Acceptance criteria\*\*(?:\s*(?:—|–|-|:).*)?$")
+
+
+@dataclass
+class Heading:
+    level: int
+    title: str
+    index: int
+
+
+def visible_lines(text: str) -> Tuple[List[str], List[str]]:
+    """Blank fenced examples, retaining indexes for diagnostics. Not a Markdown renderer."""
+    lines = []
+    errors = []
+    fence = ""
+    fence_line = 0
+    for number, line in enumerate(text.splitlines(), 1):
+        if fence:
+            if re.fullmatch(r" {0,3}" + re.escape(fence[0]) + "{" + str(len(fence)) + r",}[ \t]*", line):
+                fence = ""
+            lines.append("")
+            continue
+        opening = re.match(r"^ {0,3}(`{3,}|~{3,})(.*)$", line)
+        if opening and not (opening[1][0] == "`" and "`" in opening[2]):
+            fence = opening[1]
+            fence_line = number
+            lines.append("")
+        else:
+            lines.append(line)
+    if fence:
+        errors.append(f"line {fence_line}: unclosed code fence; close it before validating")
+    return lines, errors
+
+
+def has_content(lines: List[str]) -> bool:
+    # Check presence, not whether the assertion is true, testable, or sufficiently specific.
+    for line in lines:
+        text = re.sub(r"^\s*(?:[-+*]|[0-9]+[.)])\s*", "", line).strip()
+        if text and re.search(r"\w", text):
+            return True
+    return False
+
+
+def criteria_body(lines: List[str], start: int, end: int) -> List[str]:
+    """A heading or another bold section label terminates criteria, not just the next R ID."""
+    result = []
+    for line in lines[start:end]:
+        if HEADING.match(line) or re.match(r"^\s*\*\*[^*]+\*\*", line):
+            break
+        result.append(line)
+    return result
+
+
+def validate(text: str) -> Tuple[List[str], List[str]]:
+    lines, errors = visible_lines(text)
+    headings = []
+    for index, line in enumerate(lines):
+        match = HEADING.match(line)
+        if match:
+            headings.append(Heading(len(match[1]), match[2], index))
+    for heading in headings:
+        if REQUIREMENT_LIKE.match(heading.title) and heading.level != 3:
+            errors.append(f"line {heading.index + 1}: {heading.title} must use a ### requirement heading")
+    requirements = [h for h in headings if h.level == 3 and REQUIREMENT_LIKE.match(h.title)]
+    features = [h for h in headings if h.level == 2 and h.title == "Feature acceptance"]
+    summaries = []
+
+    if not requirements:
+        errors.append("required requirement block missing; add ### R1: <name> with Acceptance criteria")
+    seen = set()
+    for expected, heading in enumerate(requirements, 1):
+        match = REQUIREMENT.fullmatch(heading.title)
+        if not match:
+            errors.append(f"line {heading.index + 1}: malformed requirement '{heading.title}'; use ### R{expected}: <name>")
+            continue
+        number = int(match[1])
+        if number in seen:
+            errors.append(f"line {heading.index + 1}: duplicate requirement R{number}")
+        elif number != expected:
+            errors.append(f"line {heading.index + 1}: expected R{expected}, found R{number}; IDs must be sequential in document order")
+        seen.add(number)
+        if not match[2].strip():
+            errors.append(f"line {heading.index + 1}: R{number} requires a nonempty name")
+
+    intro_end = requirements[0].index if requirements else len(lines)
+    short = any(re.match(r"^In short:\s*\S.*$", line) for line in lines[:intro_end])
+    full_format = any(h.level == 2 and h.title in ("At a glance", "Requirements") for h in headings)
+    trivial = short and not full_format and len(requirements) == 1 and requirements[0].title.startswith("R1:") and not features
+    if not trivial and not features:
+        errors.append("## Feature acceptance is required for non-trivial designs; the trivial exception needs an In short: one-liner and a single R1 block without full-format sections")
+    if len(features) > 1:
+        errors.append("duplicate ## Feature acceptance section; keep exactly one")
+
+    # Record ownership so a valid-looking tag cannot silently land outside its section.
+    owned_tags = set()
+
+    def tags(start: int, end: int, names: Tuple[str, ...], owner: str) -> dict:
+        values = {name: TAG_VALUES[name][0] for name in names}
+        found = set()
+        for heading in headings:
+            if not start <= heading.index < end:
+                continue
+            for name in names:
+                if heading.level != 3 or not re.match(re.escape(name) + r"\b", heading.title):
+                    continue
+                owned_tags.add(heading.index)
+                if name in found:
+                    errors.append(f"line {heading.index + 1}: duplicate {name} tag in {owner}")
+                found.add(name)
+                value = heading.title[len(name):].strip()
+                value = value[1:].strip() if value.startswith(":") else ""
+                if value not in TAG_VALUES[name]:
+                    allowed = " | ".join(TAG_VALUES[name])
+                    errors.append(f"line {heading.index + 1}: invalid {name} tag in {owner}; expected {allowed}")
+                else:
+                    values[name] = value
+        return values
+
+    for heading in requirements:
+        end = next((h.index for h in headings if h.index > heading.index and (h.level <= 2 or h in requirements)), len(lines))
+        criteria_end = next((h.index for h in headings if heading.index < h.index < end), end)
+        labels = [i for i in range(heading.index + 1, criteria_end) if CRITERIA.fullmatch(lines[i].strip())]
+        owner = heading.title.split(":", 1)[0]
+        if not labels:
+            errors.append(f"line {heading.index + 1}: {owner} needs a standalone **Acceptance criteria** section")
+        elif len(labels) > 1:
+            errors.append(f"line {labels[1] + 1}: {owner} has duplicate Acceptance criteria sections")
+        elif not has_content(criteria_body(lines, labels[0] + 1, end)):
+            errors.append(f"line {labels[0] + 1}: {owner} Acceptance criteria is empty; add a criterion before the next section")
+        values = tags(heading.index + 1, end, ("Checkpoints", "Review"), owner)
+        summaries.append(f"{owner}: Checkpoints={values['Checkpoints']}, Review={values['Review']}")
+
+    for heading in features:
+        end = next((h.index for h in headings if h.index > heading.index and h.level <= 2), len(lines))
+        if not has_content(criteria_body(lines, heading.index + 1, end)):
+            errors.append(f"line {heading.index + 1}: Feature acceptance is empty; add an end-to-end criterion before its review tag")
+        values = tags(heading.index + 1, end, ("Feature review",), "Feature acceptance")
+        summaries.append(f"Feature review={values['Feature review']}")
+
+    for heading in headings:
+        for name in TAG_VALUES:
+            if re.match(re.escape(name) + r"\b", heading.title) and heading.index not in owned_tags:
+                owner = "## Feature acceptance" if name == "Feature review" else "a ### R<n>: requirement block"
+                errors.append(f"line {heading.index + 1}: {name} must be a ### tag inside {owner}")
+    return errors, summaries
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Read-only structural design validation. Requires Python 3.9+; standard library only. Semantic correctness is not verified.",
+        epilog="Pass an explicit design path. Absolute paths are used directly; relative paths resolve from the caller's working directory (cwd), not the installed skill directory.",
+    )
+    parser.add_argument("design", type=Path, help="UTF-8 Markdown design file (quote paths containing spaces)")
+    args = parser.parse_args(argv)
+    if sys.version_info < (3, 9):
+        print("Python 3.9+ is required; supply a compatible runtime before validation.", file=sys.stderr)
+        return 2
+    try:
+        text = args.design.read_text(encoding="utf-8")
+    except (OSError, UnicodeError, ValueError) as error:
+        print(f"{args.design}: cannot read UTF-8 design: {error}", file=sys.stderr)
+        return 2
+    errors, summaries = validate(text)
+    if errors:
+        for error in errors:
+            print(f"{args.design}: {error}", file=sys.stderr)
+        return 1
+    print(f"{args.design}: structural checks passed. Semantic correctness is not verified.")
+    for summary in summaries:
+        print(f"  {summary}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())