@tianhai/pi-workflow-kit 1.0.0 → 1.2.0

package/README.md

@@ -41,7 +41,7 @@ Enforces phase-appropriate tool access — not just guidelines, but hard blocks:
 
 The agent can read code and discuss design with you during brainstorm/plan, but it physically cannot modify source files. Bash during gated phases is governed by a simple common-blacklist (a command is allowed unless it matches a destructive pattern), and a short phase reminder is shown once when the gated phase begins so the model self-restricts.
 
-Phases transition only when you invoke a skill (`/skill:pwk-brainstorming` → read-only; `/skill:pwk-executing-tasks` → unrestricted) — no message keyword unlocks the guard. Need to override it? `/pwk-guard on` forces a read-only lock, `off` disables the guard entirely, `auto` (default) returns to skill-driven phases. The subcommands autocomplete after the command.
+Phases transition only when you invoke a skill (`/skill:pwk-brainstorming` → read-only; `/skill:pwk-executing-tasks` → unrestricted) — no message keyword unlocks the guard. Unlocking skills: `pwk-executing-tasks`, `pwk-finalizing`, `pwk-code-review`, `pwk-diagnose` (all need source writes); `pwk-status` deliberately stays gated (read-only orientation). The canonical list is the exported `UNLOCK_SKILLS` in `extensions/workflow-guard.ts`, lint-asserted against the skills by `npm run check`. Need to override it? `/pwk-guard on` forces a read-only lock, `off` disables the guard entirely, `auto` (default) returns to skill-driven phases. The subcommands autocomplete after the command.
 
 ### 🧠 7 Workflow Skills
 
@@ -54,7 +54,7 @@ brainstorm → writing-plans → executing-tasks → finalizing
                    diagnose (anytime)   ·   status (anytime)
 ```
 
-A **design doc is one PR**; a **requirement is one testable slice within it**. For multi-design work (a large issue split into several design docs — each its own PR), run the pipeline once per design doc.
+A **design doc is one PR**; a **requirement is one testable slice within it**. A requirement too big for one design doc but shipping as one PR is an **umbrella** — multiple design docs under one status-free overview, on one branch, finalized once.
 
 | Phase | Trigger | What Happens |
 |-------|---------|--------------|
@@ -63,8 +63,8 @@ A **design doc is one PR**; a **requirement is one testable slice within it**. F
 | **Execute** | `/skill:pwk-executing-tasks` | Per requirement: write tests (red) → **checkpoint: tests** → implement (green) → **checkpoint: complete** → code-review |
 | **Code review** | `/skill:pwk-code-review` | Per requirement: code tracing, spec alignment, code smells (applies fixes), production hazard check |
 | **Finalize** | `/skill:pwk-finalizing` | Delete consumed plan docs, update README/CHANGELOG, create PR |
-| **Diagnose** | `/skill:pwk-diagnose` | Debugging loop: reproduce → hypothesise → instrument → fix → cleanup |
-| **Status** | `/skill:pwk-status` | Read-only overview of all active design topics — phase + progress. Use when resuming or juggling several designs in parallel worktrees. Not a pipeline phase. |
+| **Diagnose** | `/skill:pwk-diagnose` | Debugging loop: reproduce → hypothesise → instrument → fix → cleanup. **Exits the gated phase** (debugging writes tests/instrumentation) |
+| **Status** | `/skill:pwk-status` | Read-only overview of all active design topics — phase + progress. Use when resuming or juggling several designs in parallel worktrees. Not a pipeline phase; **does not exit the gated phase**. |
 
 ## The Workflow in Detail
 

package/docs/developer-usage-guide.md

@@ -32,7 +32,7 @@ Or in `.pi/settings.json` / `~/.pi/agent/config.json`:
 
 ## The workflow
 
-You control each phase by invoking the skill. A design doc is one PR; a requirement is one testable slice within it. For multi-design work (a large issue split), run the pipeline once per design doc:
+You control each phase by invoking the skill. A design doc is one PR; a requirement is one testable slice within it. A requirement too big for one design doc but shipping as one PR is an **umbrella** — multiple design docs under one status-free overview, on one branch, finalized once:
 
 ```
 /skill:pwk-brainstorming  →  /skill:pwk-writing-plans  →  /skill:pwk-executing-tasks  →  /skill:pwk-finalizing
@@ -46,7 +46,7 @@ You control each phase by invoking the skill. A design doc is one PR; a requirem
 
 Explore the idea through collaborative dialogue. The agent reads code, asks questions, proposes approaches, and presents the design for your review.
 
-Outcome: `docs/plans/YYYY-MM-DD-<topic>-design.md` — descriptive, opening with a `## Requirements` list. May split a large issue into multiple design docs. ADRs go to `docs/adr/` (permanent).
+Outcome: `docs/plans/YYYY-MM-DD-<topic>-design.md` — descriptive, opening with a `## Requirements` list. For a too-big requirement, may start an **umbrella** (writes a status-free overview + the first part's design doc). ADRs go to `docs/adr/` (permanent).
 
 ### 2. Plan
 
@@ -82,7 +82,7 @@ pi install npm:pi-subagents
 /skill:pwk-finalizing
 ```
 
-**Pre-check: run the full test suite** — never ship a red suite (resume spans sessions). Then delete consumed plan docs (code + tests are the source of truth), curate lessons, update CHANGELOG/README, create PR or merge.
+**Pre-check: run the full test suite** — never ship a red suite (resume spans sessions). Then archive or delete consumed plan docs (the human's choice), curate lessons, update CHANGELOG/README, create PR or merge.
 
 ### Diagnose (on demand)
 
@@ -90,7 +90,7 @@ pi install npm:pi-subagents
 /skill:pwk-diagnose
 ```
 
-A debugging loop you invoke when something is broken. Not a pipeline phase.
+A debugging loop you invoke when something is broken. Not a pipeline phase. **Invoking it exits the gated brainstorm/plan phase** — diagnosis needs to write failing tests and debug instrumentation. If you only want read-only investigation mid-design, use `pwk-status` or re-lock with `/pwk-guard on`.
 
 ### Status (on demand)
 
@@ -98,15 +98,15 @@ A debugging loop you invoke when something is broken. Not a pipeline phase.
 /skill:pwk-status
 ```
 
-A read-only overview of all active design topics — which phase each is in and how far along. Use when resuming work or juggling several designs in parallel (e.g. across worktrees) and you're unsure which topic to continue. Not a pipeline phase.
+A read-only overview of all active design topics — which phase each is in and how far along. Use when resuming work or juggling several designs in parallel (e.g. across worktrees) and you're unsure which topic to continue. Not a pipeline phase, and **it does not exit the gated phase** — it needs no writes, so the brainstorm/plan write boundary stays up.
 
 ## What the extension does
 
 The `workflow-guard` extension watches `write`/`edit` and `bash` tool calls:
 
 - **During brainstorm and writing-plans**: blocks writes outside `docs/plans/`, and blocks destructive bash via a simple common-blacklist (a command is allowed unless it matches a destructive pattern). A short phase reminder is shown once when the gated phase begins so the model self-restricts.
-- **During executing-tasks, code-review, finalizing**: no restrictions.
-- **Phases are skill-driven**: the guard follows the skill you invoke — it never unlocks on message keywords. To override, run `/pwk-guard on` (force read-only), `off` (disable), or `auto` (default; skill-driven). Subcommands autocomplete.
+- **During executing-tasks, code-review, finalizing, diagnose**: no restrictions.
+- **Phases are skill-driven**: the guard follows the skill you invoke — it never unlocks on message keywords. The exact unlock set is `pwk-executing-tasks`, `pwk-finalizing`, `pwk-code-review`, `pwk-diagnose`; `pwk-status` stays gated. To override, run `/pwk-guard on` (force read-only), `off` (disable), or `auto` (default; skill-driven). Subcommands autocomplete.
 
 The destructive blacklist covers common file-mutating vectors (redirects, `tee`, `cp`/`mv`/`touch`/`rm`, `git commit`/`apply`, `npm install`, in-place editors like `sed -i`/`perl -i`, `patch`, `find -delete`). Exotic vectors (interpreter escapes like `node -e`, `python -c`, `| bash`) rely on the phase reminder — the guard is advisory, not a security boundary.
 
@@ -120,5 +120,6 @@ Plans specify *what* (acceptance criteria + integration tests); the executor wri
 
 - Start with brainstorming for anything non-trivial.
 - The plan is a behavioral spec, not an implementation recipe — let the executor choose how.
-- Each requirement has two mandatory checkpoints: use them to steer test design and implementation.
-- Put all plan artifacts under `docs/plans/`; ADRs under `docs/adr/`.
+- Each requirement has two mandatory checkpoints by default: use them to steer test design and implementation.
+- **Right-size each requirement at plan time** with the `### Checkpoints` (`full`/`spec`/`none`) and `### Review` (`parallel`/`inline`/`skip`) tags — defaults are conservative (`full` + `parallel`), so behavior is unchanged unless you opt in. `spec` keeps the cheap spec-correctness gate and drops the complete checkpoint (covered by review), so it's the lowest-iteration option that doesn't sacrifice quality — but it requires at least `inline` review. A trivial fix can also use the brainstorming trivial fast-path (one-turn brainstorm, minimal design doc).
+- Put all plan artifacts under `docs/plans/`; ADRs under `docs/adr/`.

package/docs/lessons.md

@@ -9,5 +9,7 @@ Retire rules that no longer apply during finalizing.
 
 ## Cross-Skill Consistency
 
+- **skill-lint assertions for new behavior need a marker that distinguishes new from old.** A token present in both models gives a false green — e.g. `/umbrella/` matched the old `<umbrella>-overview.md` filename placeholder before the new behavior landed; switched to `/status-free/`, a property only the new model has.
+- **Test-first for skill/doc content:** add the skill-lint assertion first (red — the skill doesn't yet claim the behavior), then edit the skill markdown to satisfy it (green). After edits run biome — it collapses short `if (cond) ok();` to one line and rejects array holes like `[, ""]` (restructure instead).
 
 ## Documentation

package/docs/oversight-model.md

@@ -6,11 +6,11 @@
 
 Skills teach the agent the workflow. There are 5 pipeline skills:
 
-- **pwk-brainstorming** — explore ideas, produce a descriptive design doc that opens with a `## Requirements` list
+- **pwk-brainstorming** — explore ideas, produce a descriptive design doc that opens with a `## Requirements` list. For a requirement too big for one design doc, may start an **umbrella** (multiple design docs under one status-free overview, shipping as one PR)
 - **pwk-writing-plans** — turn each requirement into acceptance criteria + integration-test cases (a behavioral spec, no implementation code)
 - **pwk-executing-tasks** — implement requirement-by-requirement, test-first, with two mandatory human checkpoints per requirement
 - **pwk-code-review** — the inline reviewer (code tracing, spec alignment, code smells, production hazards). During `pwk-executing-tasks`, per-requirement review instead runs **four specialized reviewers in parallel** via the `subagent` tool, each from a fresh context (spec gaps & scope creep, tracing, smells, hazards). These ship as package agents (`agents/pwk-*.md`) discovered natively by the optional **`pi-subagents`** package; all report findings only — fixes are applied by the executing-tasks main agent. Falls back to inline `/skill:pwk-code-review` when `pi-subagents` is not installed.
-- **pwk-finalizing** — delete consumed plan docs, curate lessons, update docs, create PR or merge
+- **pwk-finalizing** — dispose consumed plan docs (archive or delete; for an umbrella, the overview + every part), curate lessons, update docs, create PR or merge
 
 Plus 2 on-demand skills:
 
@@ -27,12 +27,14 @@ The `workflow-guard` extension enforces one rule:
 
 The agent can still use `read` and `bash` for investigation. During those gated phases, `bash` is governed by a simple destructive-command blacklist (`rm`, `>`, `git commit`, `npm install`, in-place editors, etc.) — a command is allowed unless it matches a destructive pattern. A short phase reminder is shown once when the gated phase begins so the model self-restricts.
 
-During executing-tasks, code-review, and finalizing, nothing is restricted.
+During executing-tasks, code-review, finalizing, **and diagnose**, nothing is restricted (diagnosis needs to write failing tests and debug instrumentation, so it exits the gate). `pwk-status` stays inside the gate.
 
-Phases follow the skill you invoke — there is no message-keyword unlock. `/pwk-guard on|off|auto` manually overrides the guard (`on` = force read-only lock, `off` = disabled, `auto` = skill-driven, the default); subcommands autocomplete.
+Reviewer-agent checklists live only in `agents/pwk-*-reviewer.md` (single source of truth); `pwk-executing-tasks` passes each reviewer just the requirement scope + diff and names the agent.
+
+Phases follow the skill you invoke — there is no message-keyword unlock. Invoking `/skill:pwk-executing-tasks`, `pwk-finalizing`, `pwk-code-review`, or `pwk-diagnose` exits the gated phase (those skills write source); `pwk-status` deliberately does **not** (read-only orientation). `/pwk-guard on|off|auto` manually overrides the guard.
 
 ## Enforcement style
 
-Hard block for write boundaries during gated phases. No warnings, no escalation, no prompts. Either the tool call is allowed or it's blocked.
+Hard block for write boundaries during gated phases. No warnings, no escalation, no prompts. Either the tool call is allowed or it's blocked. The unlock list is hard-coded in the extension and verified by `tests/skill-lint.mjs` against the skills' claims, so a skill that promises "read-only" can't silently unlock.
 
 TDD, checkpoints, debugging, and code review are guidance in the skill instructions, not runtime-enforced. The bash blacklist covers common destructive vectors only; exotic escapes (interpreter one-liners, piped shells) rely on the phase reminder — the guard is advisory, not a security boundary.

package/docs/workflow-phases.md

@@ -7,7 +7,7 @@ brainstorm → writing-plans → executing-tasks → finalizing
                           (per requirement: tests → ⏸ checkpoint → implement → ⏸ checkpoint → code-review)
 ```
 
-A design doc is one PR; a requirement is one testable slice within it. For multi-design work (a large issue split into several design docs — each its own PR), run the pipeline once per design doc.
+A design doc is one PR; a requirement is one testable slice within it. A requirement too big for one design doc but shipping as one PR is an **umbrella**: multiple design docs under one status-free overview, on one branch, finalized once (`(brainstorm → plan → execute) × N → finalize`).
 
 ## brainstorm
 
@@ -16,8 +16,8 @@ A design doc is one PR; a requirement is one testable slice within it. For multi
 ```
 
 - Explore requirements and shape the design.
-- Produce `docs/plans/YYYY-MM-DD-<topic>-design.md` — descriptive, opening with a `## Requirements` list.
-- May split a large issue into multiple design docs (human-approved).
+- Produce `docs/plans/YYYY-MM-DD-<topic>-design.md` — descriptive, opening with a `## Requirements` list, ending with a `## Feature acceptance` section (end-to-end scenarios that prove the requirements compose into the PRD's behavior — the feature's definition-of-done).
+- May start an **umbrella** for a requirement too big for one design doc (human-approved): writes the status-free `docs/plans/YYYY-MM-DD-<umbrella>-overview.md` (roster of parts + build order) and the **first** part's `-design.md`. Later parts are brainstormed one by one against the overview + implemented predecessors.
 - ADRs go to `docs/adr/` (permanent, never archived).
 
 Write boundary: only `docs/plans/` is writable. Source files are hard-blocked.
@@ -30,6 +30,8 @@ Write boundary: only `docs/plans/` is writable. Source files are hard-blocked.
 
 - Creates the feature branch first (`git checkout -b <topic>`), so design + plan docs live on the branch, not `main`.
 - Reads the design doc's `## Requirements`; for each, derives **acceptance criteria + integration-test cases** (a behavioral spec, no implementation code), lists requirements in build order (dependencies positioned earlier), and challenges the design when `## Production-risk areas` is present.
+- For an umbrella part, reads the `*-overview.md` to plan one slice (composing with earlier parts' code) and reuses the existing feature branch instead of creating a new one.
+- Derives a **`## Feature acceptance` section** in the plan from the design's Feature acceptance — an end-to-end integration test that exercises the requirements together (distinct from per-requirement tests). If the design has none, stops and asks the human to brainstorm one.
 - Produce `docs/plans/YYYY-MM-DD-<topic>-implementation.md`.
 
 Write boundary: only `docs/plans/` is writable.
@@ -41,12 +43,22 @@ Write boundary: only `docs/plans/` is writable.
 ```
 
 - Per requirement: write the integration tests (red) → **⏸ checkpoint: tests** → implement to green (full autonomy — the executor chooses structure/signatures/internals) → **⏸ checkpoint: complete** → commit → **per-requirement review** (four parallel reviewers via the `subagent` tool; falls back to inline `/skill:pwk-code-review` when `pi-subagents` is absent — see [code-review](#code-review)).
-- Two **mandatory** human checkpoints per requirement.
+- Two **mandatory** human checkpoints per requirement — unless the plan tags a requirement lighter (see [Proportionality](#proportionality)).
+- **Composition check after each commit** — if a requirement touched shared code, the executor runs the full suite now and fixes cross-requirement regressions immediately, rather than discovering them only at the integration gate.
 - Progress tracked in `docs/plans/*-progress.md`.
-- After all requirements: **integration gate** — run the full suite and confirm the requirements compose into the feature before `/skill:pwk-finalizing`.
+- After all requirements: **integration gate** — run the full suite, **run the feature-acceptance test** (the end-to-end check from the plan's `## Feature acceptance` section), and confirm the requirements compose into the feature before `/skill:pwk-finalizing`.
 
 No write restrictions. All tools available.
 
+## Proportionality
+
+The defaults preserve the 1.0.0 behavior (two checkpoints + parallel review per requirement). At plan time the human can tag each requirement lighter to right-size the workflow:
+
+- **Checkpoints** — `full` (both stops, default) | `spec` (tests stop only — cheap spec-correctness gate, implementation covered by review) | `none` (no stops, trivial only). Test-first is preserved either way: even `none` writes tests first (red) and implements to green; only the human *stops* are optional. `spec` requires at least `inline` review (never combine with `skip`).
+- **Review** — `parallel` (four fresh-context reviewers, default) | `inline` (single `pwk-code-review` pass) | `skip` (trivial diffs with no behavioral surface only).
+
+A trivial fix can also skip the multi-turn brainstorm dialogue via the brainstorming trivial fast-path (compress to one turn, minimal design doc) — the guard still enforces read-only. Tags default conservatively, so nothing changes unless the human opts in.
+
 ## code-review
 
 ```
@@ -66,7 +78,7 @@ No write restrictions.
 ```
 
 - **Pre-check: run the full test suite** — don't ship a red suite (resume spans sessions; don't trust the last execute session).
-- Delete consumed plan docs (per-`<topic>`) — code + tests are the source of truth; ADRs stay at `docs/adr/`.
+- Dispose of consumed plan docs (per-`<topic>`) — the human picks **delete** (default — code + tests are the source of truth) or **archive** to `docs/plans/completed/` (keep planning history). ADRs stay at `docs/adr/`. For an umbrella (an `*-overview.md` exists), disposes the overview **and every part's** docs in one pass and ships **one PR**.
 - Curate `docs/lessons.md`, update README/CHANGELOG, create PR or merge.
 
 No write restrictions.
@@ -77,7 +89,7 @@ No write restrictions.
 /skill:pwk-status
 ```
 
-Read-only overview of all active pipeline topics (phase + progress) when several designs are in flight. Not a pipeline phase.
+Read-only overview of all active pipeline topics (phase + progress) when several designs are in flight; an umbrella rolls up under its overview (shipped / in-flight / not-started). Not a pipeline phase — and it **does not exit the gated phase** (`pwk-status` is read-only; it runs fine under the brainstorm/plan write block, so the boundary stays up).
 
 ## diagnose
 
@@ -85,7 +97,7 @@ Read-only overview of all active pipeline topics (phase + progress) when several
 /skill:pwk-diagnose
 ```
 
-Not a pipeline phase. A utility skill invoked on demand when debugging is needed.
+Not a pipeline phase. A utility skill invoked on demand when debugging is needed. Invoking it **exits the gated phase** — diagnosis needs to write failing tests and `[DEBUG-…]` instrumentation. To stay read-only mid-brainstorm, use `/skill:pwk-status` instead, or re-lock with `/pwk-guard on`.
 
 No write restrictions.
 

package/extensions/workflow-guard.ts

@@ -128,6 +128,10 @@ const SKILL_TO_PHASE: Record<string, Phase> = {
   "pwk-writing-plans": "plan",
 };
 
+/** Skills whose invocation exits a gated phase (used by the input handler; exported for tests/
+ *  skill-lint). Deliberately excludes pwk-status (read-only by design; stays gated). */
+export const UNLOCK_SKILLS = ["pwk-executing-tasks", "pwk-finalizing", "pwk-code-review", "pwk-diagnose"] as const;
+
 /** Phase-aware reminder appended after the user's message each turn while a gated phase is active.
  *  Returned as a message (not a system-prompt change) so it sits at the tail of the request and
  *  never invalidates the cached prefix. */
@@ -247,14 +251,14 @@ export default function (pi: ExtensionAPI) {
       }
     }
     // Phase transitions happen only via skills — no message keyword unlocks the plan phase.
-    // Run /skill:pwk-executing-tasks (or any non-gated skill) to leave a gated phase.
-    if (
-      text.startsWith("/skill:pwk-executing-tasks") ||
-      text.startsWith("/skill:pwk-finalizing") ||
-      text.startsWith("/skill:pwk-code-review") ||
-      text.startsWith("/skill:pwk-diagnose") ||
-      text.startsWith("/skill:pwk-status")
-    ) {
+    // Run /skill:pwk-executing-tasks (or another write-needing skill) to leave a gated phase.
+    //
+    // Unlock list rationale: execute/finalize/code-review/diagnose all need to write source
+    // (implement, edit review fixes, add [DEBUG-] instrumentation), so they exit the gate.
+    // pwk-status is NOT here on purpose: it is read-only orientation, so it stays inside the
+    // gated phase and never drops the write boundary the user is relying on.
+    // (Orientation never needs write access; see skills/pwk-status.)
+    if (UNLOCK_SKILLS.some((s) => text.startsWith(`/skill:${s}`))) {
       phase = null;
     }
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianhai/pi-workflow-kit",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Enforce structured brainstorm→plan→execute→finalize workflow with TDD discipline in AI coding agents",
   "keywords": [
     "pi-package",
@@ -16,7 +16,8 @@
   "scripts": {
     "test": "vitest run",
     "lint": "biome check .",
-    "check": "biome check . && vitest run"
+    "skill-lint": "node tests/skill-lint.mjs",
+    "check": "biome check . && vitest run && node tests/skill-lint.mjs"
   },
   "license": "MIT",
   "author": "yinloo-ola",

package/skills/pwk-brainstorming/SKILL.md

@@ -5,56 +5,84 @@ description: "Use this before any creative work — creating features, building
 
 # Brainstorming
 
-Read-only exploration. You may **not** edit or create any files except under `docs/plans/`.
+Read-only exploration of source code; every file you create or edit goes under `docs/plans/`. (Once an ADR is approved by the human, `docs/adr/` becomes writable too — ask the user to unlock or run the write.) Planning produces the document the executor builds from; source-writing happens in later phases.
 
-## Granularity
+## Proportionality: trivial vs non-trivial
 
-**A design doc is one pull request; a requirement is one testable slice within it.** Two decomposition levels answer two different questions:
+Classify the change at the start.
 
-- **How many PRs?** — split a large issue into **multiple design docs** only when each part could ship as its own PR (independently reviewable and mergeable). Each design doc runs its own plan → execute → finalize pipeline → its own PR. Example: "add OAuth" and "add dark mode" are unrelated → two design docs.
-- **How to build one PR incrementally?** — within a design doc, decompose the work into **requirements**, each "one testable behavior." The plan covers all of them; the executor builds them one at a time. Example: "add OAuth" = R1 redirect flow, R2 token refresh, R3 error states → one design doc, three requirements, one PR.
+- **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–5; write a **minimal** design doc in one turn (one-line context, a `## Requirements` list with the single requirement, optional `## Production-risk areas` line), and hand off to `/skill:pwk-writing-plans`. 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.
 
-Requirements are the leaf unit — never split further. Decision rule: **could this part be reviewed and merged on its own?** Yes → separate design doc. No → one design doc, multiple requirements. Most work is a single design doc; splitting is opt-in.
+When unsure, ask: "This looks trivial — fast-path it, or full brainstorm?" Default to full.
 
-## Process
+## Granularity
+
+**One design doc = one PR; one requirement = one testable slice within it.** Most work is a single design doc.
+
+- Within a doc, decompose into **requirements**, each one testable behavior.
+- 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.
 
-1. **Check git state** — run `git status` and `git log --oneline -5`. If there's uncommitted work, ask the user what to do with it first.
-2. **Discovery** *(skip if this is a brand-new repo with no `docs/plans/`)* — glob `docs/plans/*-design.md`. Report active topics found (e.g. `In-flight: auth (plan), billing (brainstorm)`). Multiple designs may run in parallel. If the new idea continues an existing topic, ask the human whether to extend it or start fresh before designing.
-3. **Understand the idea** — read existing code, docs, and recent commits. Grep for related functionality, check package.json/dependencies and module structure. **Check `docs/lessons.md`** if it exists — known constraints and patterns may affect the design. Read only what's necessary to ground the design — don't read the entire codebase. Ask questions to refine the idea. Prefer multiple choice when possible. After each question, check: can you clearly articulate (a) what the user wants to build, (b) why, and (c) key constraints? If yes, present your understanding as a short summary and ask: "Should I proceed with this, or is there more to add?" The human decides when to move on.
-4. **Explore approaches** — propose 2-3 approaches. For each approach, sketch the concrete interface (types, method signatures, example caller code) so the comparison is grounded in actual code, not abstract descriptions. Lead with your recommendation.
-5. **Present the design** — break it into focused sections. Each section should be one screen of reading. Present each section to the human and wait for approval before continuing. Cover: architecture, components, data flow, error handling, testing. On feedback, incorporate it and re-present the revised section.
+## Umbrella
 
-   When a significant architectural decision is identified, offer to write a lightweight ADR to `docs/adr/`. Only write an ADR when all three are true:
+An umbrella splits one large requirement into multiple design docs that ship together as **one PR**. One branch; one `pwk-finalizing` at the end. The split is intra-PR decomposition — a way to keep each design/plan/execute cycle small and focused, not a multi-PR strategy.
 
-   1. **Hard to reverse** — changing your mind later has meaningful cost
-   2. **Surprising without context** — a future reader will wonder "why?"
-   3. **A real trade-off** — there were genuine alternatives
+**First brainstorm** (the requirement is too big for one design doc):
 
-   ADR format — a title and 1-3 sentences covering context, decision, and why:
+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/YYYY-MM-DD-<umbrella>-overview.md`, a **status-free roster**:
 
    ```markdown
-   # <Short title of the decision>
+   # Overview: <umbrella>
 
-   <1-3 sentences: context, decision, and why.>
+   Goal: <one line — what the whole requirement delivers>
+
+   ## Parts (build order)
+   1. <topic> — <one-line scope>
+   2. <topic> — <one-line scope>
    ```
 
-   ADRs live under `docs/adr/` permanently — they are institutional memory, never archived.
+   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 part's own `*-progress.md`.
+3. **Write the first part's** `YYYY-MM-DD-<part>-design.md`, then hand off to `/skill:pwk-writing-plans`.
+
+**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 explore the codebase to design your slice **as brainstorm always does** — prior parts are just implemented code in the repo by then. There is no special "read your predecessors" step; cross-slice decisions that must persist go in an ADR, not the overview.
 
-6. **Write the design doc** — save it to `docs/plans/YYYY-MM-DD-<topic>-design.md` as a descriptive document (not a task list). **Open with a `## Requirements` list** — each requirement one testable behavior the user will get (`pwk-writing-plans` derives acceptance criteria + integration tests per requirement). Then cover: problem, approaches considered, architecture, components, data flow, error handling, and testing.
+The whole umbrella is one branch and one PR: `pwk-writing-plans` creates the branch on the first part and reuses it for later parts; `pwk-executing-tasks` suggests the next part (or finalize after the last); `pwk-finalizing` disposes the overview + every part's docs and ships one PR.
+
+## 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/`)* — glob `docs/plans/*-design.md` and `*-overview.md`; report in-flight topics and any active umbrella. If the new idea continues an existing topic, ask whether to extend it or start fresh. Part of an umbrella? An existing `*-overview.md` means the split is already decided — read it for the roster and design this part's `-design.md` against it (see [Umbrella](#umbrella)).
+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 one at a time, prefer multiple choice. Once you can articulate what/why/constraints, present a short summary and ask: "Should I proceed, or is there more?" The human decides when to move on.
+4. **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.
+5. **Present the design** in one pass, organized into sections (architecture, components, data flow, error handling, testing) — the human comments on any section; re-present only revised sections.
+
+   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/`; write it only after the user approves and unlocks.)
+6. **Write the design doc** — `docs/plans/YYYY-MM-DD-<topic>-design.md`, descriptive (not a task list). **Open with `## Requirements`** — one testable behavior each; `pwk-writing-plans` derives acceptance criteria and tests from these. Then: problem, approaches considered, architecture, components, data flow, error handling, testing.
+
+   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` — `pwk-writing-plans` carries it into the plan and `pwk-code-review` audits it per requirement.
+
+   **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-writing-plans` derives a feature-level test from it; `pwk-executing-tasks` runs it at the integration gate. 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.
+
+   ```markdown
+   ## Feature acceptance
+
+   - Given <starting state>, When <trigger>, Then <end-to-end outcome the feature promises>.
+   ```
 
-   If the design touches any production-risk area — database schema changes or migrations, authentication or authorization, external API or service integrations, concurrency or batch processing, file uploads or large data flows, Redis/caching/message queues — add a short `## Production-risk areas` section noting them. `pwk-writing-plans` carries these notes into the plan, and `pwk-code-review` audits them after each requirement.
+   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."
 
-   **Splitting large issues:** if the work is large enough to be multiple PRs, propose splitting it into multiple design docs (one per sub-issue, each with its own `<topic>`) and get the human's approval first — see [Granularity](#granularity) for the decision rule. Each design doc then runs its own pipeline.
+   **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.md` and the **first part's** `-design.md`, then hand off to `/skill:pwk-writing-plans`. Later parts are brainstormed one by one (each re-reading the overview) — do not write every part's design doc up front.
 
-   Branch creation and workspace setup happen at the end of `/skill:pwk-writing-plans` (after the plan is approved); the design + plan docs are committed at the start of `pwk-executing-tasks`. Until then the session is read-only and uncommitted.
+The session stays read-only and uncommitted through brainstorm and plan: branch creation happens at the end of `/skill:pwk-writing-plans`; plan docs are committed at the start of `pwk-executing-tasks`.
 
 ## Principles
 
 - One question at a time
 - YAGNI — remove unnecessary features
 - Design for testability
-- Always explore alternatives before settling
+- Explore alternatives before settling
 
 ## After the design
 
-Ask: "Ready to plan? Run `/skill:pwk-writing-plans`"
+Ask: "Ready to plan? Run `/skill:pwk-writing-plans`"

package/skills/pwk-code-review/SKILL.md

@@ -38,8 +38,8 @@ Review the code just implemented for a requirement. **Unlocked** — you may edi
 ## Principles
 
 - **Tracing and spec alignment are the core** — they catch what tests miss: untested branches, missing criteria, scope creep.
-- **Fix smells in place; flag everything else.** Don't redesign.
-- **Be proportional** — a one-function change doesn't need the depth of a batch pipeline.
+- **Fix smells in place; flag everything else.** Keep the review scoped — the goal is polish on the requirement that just landed, not a redesign pass.
+- **Be proportional** — a one-function change doesn't need the depth of a batch pipeline. When this skill runs as the inline path because the plan tagged the requirement `Review: inline`, that was a deliberate call at plan time — keep the review focused and don't second-guess the tag.
 
 ## After the review
 

package/skills/pwk-diagnose/SKILL.md

@@ -7,6 +7,8 @@ description: "Disciplined debugging loop for hard bugs and performance regressio
 
 A 6-phase debugging discipline. Phase 1 is the skill — spend disproportionate effort here.
 
+Invoking `/skill:pwk-diagnose` **exits the gated brainstorm/plan phase** (the workflow guard unlocks) — diagnosis needs to write failing tests and `[DEBUG-…]` instrumentation. If you only wanted read-only investigation, use `/skill:pwk-status` (stays gated) or reinstate the lock with `/pwk-guard on`.
+
 ## Phase 1 — Build a feedback loop
 
 Create a fast, deterministic, agent-runnable pass/fail signal for the bug before doing anything else. Try in this order: failing test, curl script, CLI invocation, headless browser script.
@@ -19,7 +21,7 @@ The loop must produce the failure mode the **user** described — not a nearby b
 
 If you genuinely cannot build a loop, stop and say so. List what you tried. Ask for access to a reproducing environment or a captured artifact.
 
-Do not proceed until you have a loop you believe in.
+Hold at Phase 1 until you have a loop you believe in. Everything downstream — hypotheses, instrumentation, the fix — depends on that loop actually reproducing the user's symptom.
 
 ## Phase 2 — Reproduce
 

package/skills/pwk-executing-tasks/SKILL.md

@@ -5,24 +5,21 @@ description: "Implement a plan requirement-by-requirement with test-first discip
 
 # Executing Tasks
 
-Implement the plan from `docs/plans/*-implementation.md` requirement-by-requirement, with file-based progress tracking.
+Implement the plan from `docs/plans/*-implementation.md` requirement by requirement, tracking progress in a file.
 
-The plan is a **behavioral spec** (acceptance criteria + integration tests). You have **full autonomy** to choose structure, signatures, and internals — the acceptance criteria and integration tests define *what*; you decide *how*. Do not ask the plan for implementation steps; it deliberately doesn't contain them.
+The plan is a **behavioral spec** (acceptance criteria + integration tests) — it deliberately contains no implementation steps. You choose structure, signatures, and internals; the criteria define *what*, you decide *how*.
 
 ## Before you start
 
-1. **Check git state** — `git status` and `git log --oneline -5`. Note uncommitted changes.
-2. **Find the plan + report** — look for `docs/plans/*-implementation.md`. If several, list them and ask which. Print a one-line discovery report, e.g. `Found: design "auth" — execute phase (1/3 requirements done)`. If a matching `*-progress.md` exists, this is a **resume** (see [Resume](#resume)).
-3. **Workspace isolation should already be done** — `pwk-writing-plans` set up the branch/worktree before handoff. If you land here still on `main`, tell the user the workspace wasn't set up and suggest doing it before executing.
+1. **Git state** — `git status` + `git log --oneline -5`; note uncommitted changes.
+2. **Find the plan** — glob `docs/plans/*-implementation.md`; if several, ask which. Report one line, e.g. `Found: design "auth" — execute phase (1/3 done)`. A matching `*-progress.md` means this is a **resume** (see [Resume](#resume)).
+3. **Workspace** — `pwk-writing-plans` already created the branch/worktree. If you're still on `main`, tell the user the workspace wasn't set up and suggest fixing that before executing.
 
 ## First run
 
-1. **Parse the plan** — read all `## Requirement N:` headings. Build the progress table with all requirements as `⬜ pending`. Process them in **listed order** — the plan is already in build order; do not reorder.
-2. **Setup pre-flight** — if the plan has a `## Setup` section, follow it: install dependencies, apply migrations, and seed data. Run the existing test suite to confirm nothing broke. **⏸ CHECKPOINT: setup** — present the migration/output to the human and wait for approval.
-   - **approve** → continue.
-   - **request changes** → revise and re-present.
-   (Only runs on the first `First run` — the progress file is created after this step, so a resumed session skips setup.)
-3. **Create the progress file** at `docs/plans/<plan-name>-progress.md`:
+1. **Parse the plan** — read every `## Requirement N:` heading and its `### Checkpoints` / `### Review` tags (defaults `full` / `parallel`). Requirements run in **listed order** — the plan is already in build order; do not reorder.
+2. **Setup pre-flight** *(only if the plan has a `## Setup` section)* — install dependencies, apply migrations, seed data, then run the existing test suite. **⏸ CHECKPOINT: setup** — present results and wait for approval. Record `setup: done` in the progress-file header so a resume can confirm it rather than assume it.
+3. **Create the progress file** `docs/plans/YYYY-MM-DD-<topic>-progress.md` (same dated stem as the implementation doc, so `pwk-finalizing`'s glob matches):
 
    ```markdown
    # Progress: <topic>
@@ -37,97 +34,101 @@ The plan is a **behavioral spec** (acceptance criteria + integration tests). You
    | 1 | ⬜ pending | <requirement name> | — |
    ```
 4. **Commit the plan docs** — `git add docs/plans/ && git commit -m "docs: add implementation plan"`.
-5. Begin requirement 1 (see [Per-requirement execution](#per-requirement-execution)).
+5. Start requirement 1.
 
 ## Resume
 
-1. Read the progress file. Find the first requirement that is `⬜ pending`, `🔄 in-progress`, `⏸ tests-review`, or `⏸ complete-review`.
-2. Resume from the recorded state:
-   - `⏸ tests-review` / `⏸ complete-review` → re-present that checkpoint and wait.
-   - `🔄 in-progress` mid-write → continue the requirement.
-   - `⬜ pending` → start it.
+Find the first row that is `⬜ pending`, `🔄 in-progress`, `⏸ tests-review`, or `⏸ complete-review`:
+- `⏸ *-review` → re-present that checkpoint and wait.
+- `🔄 in-progress` → continue the requirement.
+- `⬜ pending` → start it.
 
 ## Progress file
 
-Path: `docs/plans/<plan-name>-progress.md`. Update the matching row directly (not via pattern matching that could corrupt the table). Update `Last updated` on every change.
+Update the matching row directly (not via pattern matching that could corrupt the table). Update `Last updated` on every change.
 
 | Status | Meaning |
 |--------|---------|
 | `⬜ pending` | Not started |
 | `🔄 in-progress` | Writing tests or implementing |
-| `⏸ tests-review` | Paused at checkpoint: tests, awaiting human approval |
-| `⏸ complete-review` | Paused at checkpoint: complete, awaiting human approval |
-| `🔎 review` | Committed; `pwk-code-review` in progress |
-| `✅ done` | `pwk-code-review` complete (smells fixed, hazards noted), all green |
-| `❌ failed` | Could not complete; partial work discarded/reverted (append `Failed: <reason>`) |
+| `⏸ tests-review` | Paused at tests checkpoint, awaiting approval |
+| `⏸ complete-review` | Paused at complete checkpoint, awaiting approval |
+| `🔎 review` | Committed; code review in progress |
+| `✅ done` | Reviewed (smells fixed, hazards noted), all green |
+| `❌ failed` | Abandoned; partial work discarded/reverted (append `Failed: <reason>`) |
 | `⏭ skipped` | User chose to skip |
 
 ## Per-requirement execution
 
-For each requirement:
-
-1. **Mark in-progress** — `🔄 in-progress`.
-2. **Write the integration tests (red).** Read the requirement's acceptance criteria + integration-test cases from the plan and write the actual test files. Run them — confirm they **fail** (red). If they pass immediately, the behavior may already exist or the tests are wrong; investigate before proceeding.
-3. **⏸ CHECKPOINT: tests.** Stop. Do not implement yet. Mark `⏸ tests-review`. Present the integration tests and the failing output to the human, and wait for approval. The human reviews whether the right behaviors are being specified.
-   - **approve** → return to `🔄 in-progress` and continue.
-   - **request changes** → revise the tests, re-run, re-present.
-4. **Implement (green).** With full autonomy, implement whatever is needed to make the integration tests pass and satisfy the acceptance criteria — you choose the structure, modules, signatures, and internals. Run the tests after each meaningful change. Refactor for clarity (shallow modules, no duplication, seam discipline) while tests stay green.
-5. **Learn.** If you caught a repeat mistake, append a **generic** rule to `docs/lessons.md` (strip domain specifics).
-6. **⏸ CHECKPOINT: complete.** Stop. Do **not** commit yet. Mark `⏸ complete-review`. Run the tests (show passing output) and `git diff`, present the implementation to the human, and wait for approval.
-   - **approve** → return to `🔄 in-progress` and continue.
-   - **request changes** → revise, re-run, re-present at this same checkpoint.
-7. **Commit.** `git add` the relevant files and commit with a clear message. (Status stays `🔄 in-progress` — not done yet.)
-8. **Code review.** Mark `🔎 review`. Attempt isolated code-review via the `subagent` tool — four agents review the same diff in parallel, each from a different dimension (each gets a fresh context window, zero pollution from previous requirements):
-
-   Gather the requirement's scope: acceptance criteria, integration test cases, and git diff (`git log --oneline -5 && git diff HEAD~N..HEAD`).
-
-   **If the `subagent` tool is available**, invoke it with parallel tasks:
+1. **Mark 🔄 in-progress** and read this requirement's `### Checkpoints` / `### Review` tags.
+2. **Write the integration tests (red).** Encode the acceptance criteria + test cases from the plan as real test files; run them; confirm they **fail**. If they pass immediately, the behavior may already exist or the tests are wrong — investigate before proceeding.
+3. **⏸ CHECKPOINT: tests** *(fires for `full` and `spec`)* — mark `⏸ tests-review`, present the tests + failing output, wait. **request changes** → revise, re-run, re-present. With `none`, show the red output inline and proceed.
+4. **Implement (green)** with full autonomy. Run tests after each meaningful change; refactor for clarity (deep modules, no duplication, seam discipline) while tests stay green.
+5. **Learn.** Caught a repeat mistake? Append a **generic** rule to `docs/lessons.md` (strip domain specifics).
+6. **⏸ CHECKPOINT: complete** *(fires for `full` only)* — mark `⏸ complete-review`, show passing tests + `git diff`, wait. With `spec`/`none`, show them inline and proceed (**review** covers implementation quality; `spec` requires at least `inline` review).
+7. **Commit** the relevant files with a clear message. Status stays `🔄 in-progress` — not done yet.
+8. **Composition check** — if this diff touched code shared with other requirements in the plan, run the **full test suite** now and fix any cross-requirement regression while the context is fresh. Otherwise keep running just this requirement's tests.
+9. **Code review** — mark `🔎 review`; drive review by the `### Review` tag (`parallel | inline | skip`):
+   - **`parallel`** — four fresh-context reviewers via the `subagent` tool (see below).
+   - **`inline`** — run `/skill:pwk-code-review` as a single pass.
+   - **`skip`** — mark `✅ done` and move to the next requirement.
+
+   **Parallel path** — gather scope (acceptance criteria, test cases, `git log --oneline -5 && git diff HEAD~N..HEAD`) and invoke:
    ```json
    {
      "tasks": [
-       {"agent": "pwk-spec-reviewer", "task": "<scope + diff here>\n\n## Spec Review\nFor each acceptance criterion, point to the code and test that satisfy it. Flag gaps (criterion with no covering code or test) and scope creep (code beyond criteria). Report only — do not modify files. Your findings are collected by the parent agent which applies fixes and commits changes."},
-       {"agent": "pwk-tracing-reviewer", "task": "<scope + diff here>\n\n## Trace Review\nTrace every new/changed code path end-to-end against tests. Note untested branches, dead branches, paths where the trace breaks. Report only — do not modify files. Your findings are collected by the parent agent which applies fixes and commits changes."},
-       {"agent": "pwk-smell-reviewer", "task": "<scope + diff here>\n\n## Smell Review\nReport: shallow modules (interface ≈ implementation complexity), duplication, missing seams / premature abstraction, poor naming, magic values, dead code. Flag only: smells requiring risky large refactors. Report only — do not modify files. Your findings are collected by the parent agent which applies fixes and commits changes."},
-       {"agent": "pwk-hazard-reviewer", "task": "<scope + diff here>\n\n## Hazard Review\nAudit changed code against these hazards: unbounded ops (KEYS/SCAN/full-table loads), missing indexes, unbounded concurrency (Promise.all without limits), long-running transactions, query/command interpolation (injection), unrestricted uploads/temp flooding, silent swallowing loops. Write [SAFE] (1-line reason) or [TRIGGERED] (mitigation). Report only — do not modify files. Your findings are collected by the parent agent which applies fixes and commits changes."}
+       {"agent": "pwk-spec-reviewer", "task": "<scope + diff here>"},
+       {"agent": "pwk-tracing-reviewer", "task": "<scope + diff here>"},
+       {"agent": "pwk-smell-reviewer", "task": "<scope + diff here>"},
+       {"agent": "pwk-hazard-reviewer", "task": "<scope + diff here>"}
      ],
      "agentScope": "both",
      "cwd": "<repo-root>"
    }
    ```
+   The reviewer checklists live only in `agents/pwk-*-reviewer.md` — don't restate them in the task strings (duplication guarantees drift). Reviewers are read-only reporters; the executing agent applies fixes and commits.
 
-   **On success:** collect all findings. For smell-review findings: identify the smells, apply the fixes yourself (re-run integration tests after changes — must stay green, commit). For trace/spec/hazard findings: flag as follow-ups for human decision or later fix. Update the progress-file row to `✅ done`. Flag non-trivial issues as follow-ups.
+   **On success** — apply smell fixes yourself (re-run integration tests, must stay green, commit), flag trace/spec/hazard findings as follow-ups for the human, mark `✅ done`.
 
-   **Fallback** (subagent unavailable or returns error): revert to inline review — run `/skill:pwk-code-review` for this requirement as before.
-9. **Loop** — go to step 1 for the next `⬜ pending` requirement, or see [After all requirements](#after-all-requirements).
+   **Fallback** — subagent tool unavailable or errors → run `/skill:pwk-code-review` inline instead.
+10. **Loop** to step 1 for the next `⬜ pending` requirement, or see [After all requirements](#after-all-requirements).
 
-### Checkpoint gates are mandatory
+### Checkpoint gates are mandatory (when the tag says so)
 
-Both checkpoints are **hard stops, not optional**. When you reach one:
-- Stop executing immediately. Do not pass it without explicit human approval.
-- **Never** `git add` or `git commit` before the human approves at a checkpoint.
+`### Checkpoints` accepted values: `full | spec | none` → both stops / tests stop only / no stops. When a checkpoint fires it is a **hard stop**:
+- Stop immediately; never proceed without explicit human approval.
+- **Never** `git add` or `git commit` before approval at a checkpoint.
 - Mark the progress file to the review status **before** pausing.
 
+`Checkpoints: spec` with `Review: skip` is invalid (nothing would cover implementation quality) — stop and ask the human to fix the tags; use `Checkpoints: none` for truly trivial diffs.
+
 ## User override commands
 
 | User says | Agent does |
 |-----------|-----------|
 | `skip` | Mark current requirement `⏭ skipped`, move to next |
 | `status` | Show the progress table |
-| `stop` | Restore current requirement to its pre-in-progress state, suggest `/new` to resume later |
+| `stop` | Restore current requirement to its pre-in-progress state, suggest `/new` |
 | `retry` | Re-read the requirement, start over |
 
 ## Receiving feedback (outside a checkpoint)
 
-When the user shares review feedback outside a checkpoint: verify the criticism against the code, evaluate the suggestion, then implement (with tests) or push back with evidence. Don't blindly apply.
+Verify the criticism against the code, evaluate the suggestion, then implement (with tests) or push back with evidence. Don't blindly apply.
 
 ## After all requirements
 
-When no `⬜ pending` or `❌ failed` requirements remain, run the **integration gate** before suggesting finalize. Per-requirement code-review only saw each requirement's diff in isolation — this is where you prove the requirements *compose* into the feature:
+When no `⬜ pending` or `🔄 in-progress` requirements remain, run the **integration gate** before suggesting finalize — per-requirement review only saw each diff in isolation; this proves the requirements *compose* into the feature:
+
+1. **Run the FULL test suite.** A failure here means one requirement regressed another — fix it now, in execute context.
+2. **Run the feature-acceptance test.** The plan's `## Feature acceptance` section specifies one end-to-end test exercising the requirements *together* against the design's claim. Write it if missing; run it; it must pass. If the plan has no such section, stop and tell the human — the gate has nothing concrete to verify.
+3. **Confirm composition.** Do the requirements together deliver the end-to-end behavior the design doc described? Fix gaps here, with tests, before shipping.
+
+Then determine the next step from the artifacts (the human drives every transition — this is a suggestion, not a gate):
 
-1. **Run the FULL test suite** (not just the last requirement's tests). Every test must pass. A failure here means one requirement regressed another — fix it now, in execute context, while the progress file and fix autonomy are at hand.
-2. **Confirm the requirements compose** into the feature the design doc described. Each requirement passed alone; do they deliver the intended end-to-end behavior *together*? If integration exposes a gap, fix it here (with tests) before shipping.
+- **Standalone design doc** (no `docs/plans/*-overview.md`) → suggest `/skill:pwk-finalizing`.
+- **Umbrella part** (an `*-overview.md` exists) → read the overview roster and find this part's `<topic>`. If it's the **last** in build order, the umbrella is complete → suggest `/skill:pwk-finalizing` (one PR for the whole umbrella). If **more parts remain**, suggest `/skill:pwk-brainstorming` for the next part (the next `<topic>` in the roster).
 
-Only when the full suite is green and the feature works end-to-end:
+Present:
 
 ```
 ✅ All requirements complete — integration verified!
@@ -137,18 +138,13 @@ Only when the full suite is green and the feature works end-to-end:
 | 1 | ✅ done | <name> |
 | … | … | … |
 
-   - Ship: /skill:pwk-finalizing
+   - Next part: /skill:pwk-brainstorming (<next topic>)   ← umbrella, more parts remain
+   - Ship: /skill:pwk-finalizing                          ← standalone, or last umbrella part
 ```
 
 ## If you're stuck
 
 1. Re-read the requirement's acceptance criteria — you may have drifted.
-2. Check `git log` for context.
-3. Ask the user — clarify beats guessing.
-4. If still stuck:
-   - Discard uncommitted changes (`git restore .`).
-   - If the requirement has already been committed (step 7 completed), also revert its commit(s) so partial work leaves no trace on the shipped branch (`git revert HEAD --no-edit` if only the requirement commit; `git revert HEAD~N..HEAD --no-edit` if multiple commits including code-review smell fixes).
-
-   **Never leave a failed requirement's partial work on the shipped branch.** Dead code from incomplete requirements must be cleaned up before moving on.
-5. Mark `❌ failed` with the reason and move on.
-6. Check `docs/lessons.md` — a prior lesson may apply.
+2. Check `git log` for context. Ask the user — clarify beats guessing.
+3. Still stuck → discard uncommitted changes (`git restore .`); if already committed, also `git revert` the requirement's commit(s). **Never leave a failed requirement's partial work on the shipped branch.**
+4. Mark `❌ failed` with the reason and move on. Check `docs/lessons.md` — a prior lesson may apply.

package/skills/pwk-finalizing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pwk-finalizing
-description: "Use after all requirements are complete to delete consumed plan docs, curate lessons, update documentation, and ship the work."
+description: "Use after all requirements are complete to archive or delete consumed plan docs, curate lessons, update documentation, and ship the work."
 ---
 
 # Finalizing
@@ -9,70 +9,58 @@ Ship the completed work.
 
 ## Pre-finalization checks
 
-1. **Run the FULL test suite.** Every test must pass. Resume spans sessions — don't assume the last execute session left the suite green. If anything fails, stop and send the user back to `/skill:pwk-executing-tasks` to fix; never archive or open a PR against a red suite.
-
-2. Read the progress file (`docs/plans/*-progress.md`). Check for failed or skipped rows:
-
-   - **Any `❌ failed`** → **block**. Present the count and reasons to the user. Do not continue until one of:
-     - The user sends the task back to `/skill:pwk-executing-tasks` to fix the failures, or
-     - The user explicitly types `--force-failed` to acknowledge shipping with known incomplete requirements.
-
-     Never merge a branch that carries incomplete requirements without explicit acknowledgment.
-
-   - **Only `⏭ skipped`** (no `❌ failed`) → present a warning and confirm:
-
-     ```
-     ⚠️ Requirement 4 was skipped. Continue with finalizing, or go back?
-     ```
-
-     Continue on confirmation; abort otherwise.
+1. **Run the FULL test suite** — every test must pass, and only a green suite ships. Resume spans sessions; re-run the suite yourself rather than trust the previous session's ending state. Anything failing → send the user back to `/skill:pwk-executing-tasks`.
+2. Read **every** relevant progress file — for an umbrella that's each part's `docs/plans/*-progress.md`; for a standalone design doc, the one:
+   - **Any `❌ failed`** (in any part) → **block**. Present counts and reasons; continue only when the user sends the task back to executing-tasks, or explicitly types `--force-failed` to acknowledge shipping with incomplete requirements.
+   - **Only `⏭ skipped`** → warn and confirm ("Requirement N was skipped. Continue, or go back?").
 
 ## Process
 
-1. **Derive the topic** — from the progress file → its `Plan:` ref → the plan's `Design:` ref → the design-doc filename → `<topic>`. If several designs are in flight and it's ambiguous, ask which is being shipped.
-
-2. **Delete consumed plan docs** — only this design's artifacts; leave other (un-started) design docs in place:
+1. **Derive the topic set** —
+   - **Umbrella** (a `docs/plans/*-overview.md` exists): read its roster; the set is every part's `<topic>`. The overview is disposed too.
+   - **Standalone**: progress file → `Plan:` ref → plan's `Design:` ref → design-doc filename → `<topic>`. One topic.
 
-   ```bash
-   rm -f docs/plans/*<topic>*-design.md
-   rm -f docs/plans/*<topic>*-implementation.md
-   rm -f docs/plans/*<topic>*-progress.md
-   ```
+   Ambiguous with several designs in flight? Ask.
+2. **Dispose of consumed plan docs — ask archive or delete** — for **every topic** in the set, dispose its `-design.md`, `-implementation.md`, `-progress.md` (matched by the exact dated topic slug so similarly-named plans for other topics survive); for an umbrella, also dispose the `-overview.md`. Each path is matched with the `????-??-??-` prefix. Present both options and let the human choose:
 
-   Each `rm -f` gracefully handles a missing file. **Do not touch `docs/adr/`**, `docs/lessons.md`, `CHANGELOG.md`, or `README.md` — those are permanent.
+   - **Delete (default)** — code + tests are the source of truth; removing the scaffold prevents stale plan docs from misleading future sessions:
 
-3. **Review & polish lessons (Agile Scrum Master Hat)** — if `docs/lessons.md` exists, curate it for future sprints: add missed lessons, generalize domain-specific rules into generic patterns, de-duplicate, categorize under clear headers, retire stale rules. If it doesn't exist but lessons were learned, create it with the standard format.
-
-4. **Update documentation** — if the API or surface changed: update `README.md`, `CHANGELOG.md`, and any inline docs.
+     ```bash
+     # for each <topic> in the set:
+     rm -f docs/plans/????-??-??-<topic>-design.md docs/plans/????-??-??-<topic>-implementation.md docs/plans/????-??-??-<topic>-progress.md
+     # umbrella only:
+     rm -f docs/plans/????-??-??-<umbrella>-overview.md
+     git add -A docs/plans/ && git commit -m "chore: delete planning docs for <topic-or-umbrella>"
+     ```
 
-5. **Choose a merge strategy** — ask the human which they prefer:
+   - **Archive** — keep the planning history for future readers (e.g. a complex design worth preserving) by moving the artifacts into `docs/plans/completed/`:
+
+     ```bash
+     mkdir -p docs/plans/completed
+     # for each <topic> in the set:
+     mv docs/plans/????-??-??-<topic>-design.md          docs/plans/completed/ 2>/dev/null || true
+     mv docs/plans/????-??-??-<topic>-implementation.md  docs/plans/completed/ 2>/dev/null || true
+     mv docs/plans/????-??-??-<topic>-progress.md        docs/plans/completed/ 2>/dev/null || true
+     # umbrella only:
+     mv docs/plans/????-??-??-<umbrella>-overview.md     docs/plans/completed/ 2>/dev/null || true
+     git add docs/plans/ && git commit -m "chore: archive planning docs for <topic-or-umbrella>"
+     ```
 
-   1. **Create PR** — push and open a PR for external review:
-      ```
-      git push origin <branch>
-      gh pr create --title "feat: <summary>" --body "<summary>"
-      ```
-   2. **Rebase & merge** *(recommended)* — rebase onto parent, fast-forward merge, push parent, delete branch:
-      ```
-      parent=$(git show-branch -a 2>/dev/null | grep '\*' | grep -v "$(git branch --show-current)" | head -1 | sed 's/.*\[\(.*\)\].*/\1/' | sed 's/[\^~].*//')
-      git checkout "$parent" && git pull
-      git checkout - && git rebase "$parent"
-      git checkout "$parent" && git merge --ff-only -
-      git push origin "$parent"
-      git branch -d - && git push origin --delete -
-      ```
-   3. **Squash & merge** — squash all commits into one on parent, push, delete branch.
-   4. **Merge commit** — merge with `--no-ff`, push parent, delete branch.
+   The `????-??-??-` glob enforces the dated filename; a bare `*<topic>*` would over-match unrelated docs (e.g. topic `auth` would also hit `feature-auth-redesign-design.md`). Verify with `ls docs/plans/` before and after. `rm -f` and each `mv … || true` handle missing files. Both paths commit the disposal so the shipped branch is clean. Neither path touches `docs/adr/`, `docs/lessons.md`, `CHANGELOG.md`, or `README.md` — those are permanent.
+3. **Curate lessons (Agile Scrum Master hat)** — if `docs/lessons.md` exists: add missed lessons, generalize domain-specific rules into generic patterns, de-duplicate, categorize, retire stale rules. None exists but lessons were learned? Create it.
+4. **Update documentation** — if the API or surface changed: `README.md`, `CHANGELOG.md`, any inline docs.
+5. **Choose a merge strategy** — ask the human:
 
-   For options 2–4, confirm the detected parent branch before proceeding.
+   1. **Create PR** — `git push origin <branch>` then `gh pr create`.
+   2. **Rebase & merge** *(recommended)* — rebase onto parent, `--ff-only` merge, push parent, delete branch.
+   3. **Squash & merge** — squash onto parent, push, delete branch.
+   4. **Merge commit** — `--no-ff` merge, push parent, delete branch.
 
-6. **Clean up** — if a worktree was used, remove it:
-   ```
-   git worktree remove ../<repo>-<topic>
-   ```
+   For 2–4, confirm the detected parent branch before proceeding.
+6. **Clean up** — remove the worktree if one was used: `git worktree remove ../<repo>-<topic>`.
 
 ## Principles
 
-- Delete **only** the active design's artifacts — un-started designs (from a split) stay in `docs/plans/`.
-- ADRs are never archived.
-- Bump the package version if this is a published change (major bump for breaking changes).
+- Dispose of the active work's artifacts only (archive or delete, the human's choice) — for a standalone design doc its three docs; for an umbrella its overview plus every part's docs. Unrelated topics stay in `docs/plans/`.
+- ADRs are permanent institutional memory — they stay out of archive/rotation forever.
+- Bump the package version if this is a published change (major for breaking changes).

package/skills/pwk-status/SKILL.md

@@ -5,24 +5,23 @@ description: "Show all active pipeline topics and their phase/progress. Use when
 
 # Status
 
-Report on all in-flight pipelines (split designs may run in parallel across worktrees). Read-only.
+Report on in-flight pipelines in this working tree (a worktree has its own `docs/plans/`, so run status in each). Read-only. This skill **does not unlock the guard** — it needs no writes, so it runs fine inside the brainstorm/plan read-only phase. If you want source edits after a status check, invoke the skill for the next phase yourself (the guard follows the skill).
 
 ## Process
 
-1. Glob `docs/plans/*-design.md`, `*-implementation.md`, `*-progress.md`.
-2. For each `<topic>`, infer the furthest artifact present:
-   - only `*-design.md` → brainstorm done, plan next
-   - `*-implementation.md` but no progress → plan done, execute next
-   - `*-progress.md` → execute phase — show `done/total` requirement count
-3. Print a one-line table, e.g.:
+1. Glob `docs/plans/*-overview.md`, `*-design.md`, `*-implementation.md`, `*-progress.md` — this working tree only.
+2. For each topic, infer the furthest artifact: only `*-design.md` → plan next; `*-implementation.md` no progress → execute next; `*-progress.md` → execute, show `done/total`.
+3. **Group by umbrella** — for each `*-overview.md`, take its **parts** roster and roll up each part by state, inferred from artifacts (the overview is **status-free** — read no status from it): **in-flight** if it has an active `*-implementation.md`/`*-progress.md` (show `done/total`); else **not-started**. Print one roll-up line (`<umbrella> (umbrella): n in-flight · n not-started`), then nest the parts under it with their phase. Once the umbrella finalizes, its docs — overview included — are disposed, so it no longer appears here. Topics not part of an overview print flat.
+4. Print a compact table, grouped under any umbrellas, e.g.:
 
    ```
-   | Topic   | Phase   | Progress | Branch           |
-   |---------|---------|----------|------------------|
-   | auth    | execute | 2/3 done | auth             |
-   | billing | plan    | —        | ../repo-billing  |
+   payments-revamp (umbrella): 2 in-flight · 1 not-started
+     payments-core      execute  2/3 done
+     payments-ui        plan     —
+     payments-webhooks  not started
+   auth                execute  1/2 done
    ```
 
-4. If none, say so and suggest `/skill:pwk-brainstorming`.
+   If nothing, suggest `/skill:pwk-brainstorming`.
 
 Keep it short — this is orientation, not analysis. No writes; the `<topic>` slug is the identity.

package/skills/pwk-writing-plans/SKILL.md

@@ -7,22 +7,24 @@ description: "Turn a design doc's requirements into a behavioral spec — accept
 
 Turn the design doc's requirements into a **behavioral spec** the executor implements against.
 
-One design doc = one plan = one PR. The plan lists **all** the design's requirements; the executor builds them one at a time, in the order you list them (see **Ordering** below).
+One design doc = one plan = one PR. The plan lists **all** the design's requirements in build order; the executor builds them one at a time.
 
-You may only create or edit files under `docs/plans/`. Do not modify source code or configuration.
+Your writes go into `docs/plans/` and nowhere else. Source code and configuration get written later, in `pwk-executing-tasks` — this phase produces the document the executor builds from.
 
 ## Process
 
-1. **Find the design doc** — look for `docs/plans/*-design.md`. (For a full multi-topic overview when several are in flight, use `/skill:pwk-status`.) If none, ask the user to run `/skill:pwk-brainstorming` first. If several exist (a large issue was split), list them and ask which to plan. **Read `docs/lessons.md`** if it exists — incorporate known patterns into the acceptance criteria and tests.
-2. **Create the feature branch first** — `git checkout -b <topic>` (branch creation is allowed in the plan phase). The design + plan docs are written on this branch (committed at the start of `pwk-executing-tasks`), not `main`.
-3. **Read the Requirements** — the design doc opens with a `## Requirements` list; each requirement is one testable behavior the user will get. This plan covers **all** requirements in the design doc (one pipeline per design doc). If the design has no Requirements list, derive the requirements from its described behaviors and confirm them with the human before proceeding.
-
-4. **Write the plan — acceptance criteria + integration tests per requirement.** For each requirement specify:
-   - **Acceptance criteria** — `Given/When/Then` behavioral statements that define "done" for that requirement.
-   - **Integration tests** — the concrete test cases that encode the acceptance criteria: a test name and what each asserts. This is the spec the executor writes and implements against.
-   - **Challenge the design first** *(if `## Production-risk areas` exists)* — before writing acceptance criteria, stress-test the design against the flagged risks: ask the uncomfortable "what breaks under load / on failure / on bad input" questions and confirm the approach holds. If a risk invalidates a design choice, stop and return to `/skill:pwk-brainstorming` rather than planning around a flawed design.
-   - **Ordering** — list requirements in the order they should be built. If a requirement depends on another, the dependency must come **earlier in the list**; the executor runs requirements in listed order and does not reorder. Aim for each requirement to be a vertical slice that merges cleanly on its own — if a dependency can't be sliced away, position resolves it (there is no parsed dependency graph).
-   - **Production-risk notes** *(if the design flagged any in `## Production-risk areas`)* — carried forward so the executor and `pwk-code-review` account for them.
+1. **Find the design doc** — glob `docs/plans/*-design.md`. If none, ask the user to run `/skill:pwk-brainstorming` first; if several, ask which. **Read `docs/lessons.md`** if it exists — known patterns belong in the acceptance criteria. **Umbrella part?** If `docs/plans/*-overview.md` exists and this design is one of its roster parts, read the overview for the umbrella goal + roster — plan this part as one slice, composing with what earlier parts already established in the code. Note the umbrella in the plan's Overview so the executor inherits the context.
+2. **Create or reuse the feature branch** — if you're already on a feature branch (not `main`), **reuse** it: a later umbrella part continues on the same umbrella branch. Otherwise `git checkout -b <topic>` — the umbrella's `<topic>` if this is part of an overview, else the design doc's `<topic>` (branch creation is allowed in the plan phase). Design + plan docs live on this branch, committed at the start of `pwk-executing-tasks`.
+3. **Read the `## Requirements` list** — the plan covers **all** of them. If the design has none, derive requirements from its described behaviors and confirm with the human before proceeding.
+4. **Write the plan** — for each requirement:
+   - **Acceptance criteria** — `Given/When/Then` behavioral statements defining "done". Write observable behaviors, not implementation steps; cover edge and error cases.
+   - **Integration tests** — test name + what each asserts. This is the spec the executor writes tests from.
+   - **`### Checkpoints: full | spec | none`** — how many human stops. `full` = tests + complete (default); `spec` = tests stop only (clear spec, low implementation risk — the complete checkpoint is dropped); `none` = trivial only (config line, typo).
+   - **`### Review: parallel | inline | skip`** — `parallel` = four reviewers via subagent (default, non-trivial diffs); `inline` = one `pwk-code-review` pass (small/medium diffs); `skip` = trivial diffs with no behavioral surface.
+   - Tag every requirement — missing tags default to `full` / `parallel`. **`spec` requires at least `inline` review** — dropping the complete checkpoint is only safe when review covers implementation quality; never combine `spec` with `Review: skip` (use `Checkpoints: none` instead).
+   - **Production-risk notes** — carry forward the design's `## Production-risk areas`, if any.
+   - **Challenge the design first** *(if production-risk areas exist)* — stress-test the design against the flagged risks before writing criteria. If a risk invalidates a design choice, stop and return to `/skill:pwk-brainstorming` rather than planning around a flawed design.
+   - **Ordering** — dependencies come **earlier** in the list; the executor runs in listed order with no dependency graph. Aim for vertical slices that merge cleanly on their own.
 
    Save to `docs/plans/YYYY-MM-DD-<topic>-implementation.md`:
 
@@ -31,6 +33,7 @@ You may only create or edit files under `docs/plans/`. Do not modify source code
 
    ## Overview
    Design: docs/plans/YYYY-MM-DD-<topic>-design.md
+   Umbrella: docs/plans/YYYY-MM-DD-<umbrella>-overview.md   *(umbrella part only — else omit)*
 
    ## Requirement 1: <name>
 
@@ -42,41 +45,35 @@ You may only create or edit files under `docs/plans/`. Do not modify source code
    - `should <behavior>` — asserts <observable outcome>
    - `should <error case>` — asserts <failure outcome>
 
+   ### Checkpoints: full | spec | none
+   ### Review: parallel | inline | skip
+
    ### Production-risk notes
    - <from the design's Production-risk areas, if any>
 
    ## Requirement 2: <name>
    …
-   ```
-
-   **If the design has `## Production-risk areas`** that flag schema migrations, new dependencies, external API integrations, or seed data, emit a `## Setup` section between `## Overview` and `## Requirement 1`:
 
-   ```markdown
-   ## Setup
-
-   - **Dependencies:** what to install (and how)
-   - **Migrations:** each migration with a brief description
-   - **Seed / test data:** what data to prepare
-   - **Verify:** how to confirm setup worked (e.g. `npm test` still passes)
+   ## Feature acceptance
+   Derived from the design doc. One end-to-end test exercising the requirements *together*:
+   - `should <the PRD's end-to-end claim>` — Given <starting state>, When <trigger>, Then <composed outcome across requirements>.
    ```
 
-5. **Before presenting — audit the spec:**
-   - Every requirement has acceptance criteria **and** matching integration tests.
-   - Acceptance criteria are observable behaviors, not implementation steps.
-   - Edge/error cases are covered.
-   - Production-risk areas from the design are reflected.
-   Fix gaps before presenting.
+   **If the design has no `## Feature acceptance` section**, stop and ask the human to run `/skill:pwk-brainstorming` to add one — the feature's definition-of-done is missing. (A trivial single-requirement design may fold the scenario into that requirement's criteria; note it and skip the separate section.)
 
-6. **Set up workspace isolation** *(before approving)* — you're already on the `<topic>` feature branch (step 2); the design + plan docs live here, not on `main` (committed at the start of `pwk-executing-tasks`). For larger work, offer a worktree (`git worktree add ../<repo>-<topic> <topic>`) and hand off to a new session there so `pwd` is the worktree. Wait for the user's choice.
-7. **Present the plan** — show the complete plan and wait for approval. On approval, hand off to `/skill:pwk-executing-tasks` — running it is what transitions out of the gated plan phase (the guard unlocks on the skill, not on the word "approve").
+   **If `## Production-risk areas` flagged** schema migrations, new dependencies, external APIs, or seed data, emit a `## Setup` section between `## Overview` and `## Requirement 1` (dependencies, migrations, seed data, and how to verify setup worked).
 
-## What the plan is NOT
+5. **Audit before presenting:**
+   - Every requirement has criteria **and** matching tests, a checkpoint tag, a review tag.
+   - No `spec` + `skip` combination.
+   - A `## Feature acceptance` section exists (or the trivial-fold note).
+   - Production-risk areas from the design are reflected.
+6. **Workspace isolation** — you're on the `<topic>` branch. For larger work, offer a worktree (`git worktree add ../<repo>-<topic> <topic>`) and hand off to a new session there so `pwd` is the worktree. Wait for the user's choice.
+7. **Present the plan** and wait for approval. On approval, hand off: "Ready to execute? Run `/skill:pwk-executing-tasks`" (running it is what exits the gated plan phase).
 
-- **Not an implementation recipe** — no exact code, no file-by-file breakdowns, no signatures, no stubs. (A fine-grained implementation plan invalidates the moment a detail shifts; acceptance criteria + integration tests survive implementation changes.)
-- **Not micro-tasks** — one coarse block per requirement. The executor decides how to structure and slice the implementation.
-- **Not the tests themselves** — the plan specifies *what* the tests prove (names + assertions); `pwk-executing-tasks` writes the actual test files first (red), then implements to green.
+## What belongs in the plan — and what stays out
 
-The executor has **full autonomy** to choose structure, signatures, and internals — bounded only by the acceptance criteria and the two mandatory checkpoints per requirement (after integration tests are written, and after the requirement is complete), enforced by `pwk-executing-tasks`.
+The plan carries: observable behavior (acceptance criteria), the test names + assertions that prove it, and per-requirement tags. Everything about implementation *how* — code, signatures, file-by-file breakdowns, micro-task decomposition — stays with the executor, which picks structure against the spec. That's the division that keeps the plan stable when a detail shifts mid-implementation.
 
 ## After the plan