@tianhai/pi-workflow-kit 1.1.0 → 1.2.0

package/README.md

@@ -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 |
 |-------|---------|--------------|

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)
 

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:
 

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
 
@@ -17,7 +17,7 @@ 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, 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 split a large issue into multiple design docs (human-approved).
+- 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,7 @@ 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`.
 
@@ -77,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.
@@ -88,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 — 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).
+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
 

package/package.json

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

package/skills/pwk-brainstorming/SKILL.md

@@ -18,15 +18,41 @@ When unsure, ask: "This looks trivial — fast-path it, or full brainstorm?" Def
 
 ## Granularity
 
-**One design doc = one PR; one requirement = one testable slice within it.**
+**One design doc = one PR; one requirement = one testable slice within it.** Most work is a single design doc.
 
-- Split into **multiple design docs** only when each part could ship as its own PR (independently reviewable and mergeable). Each runs its own plan → execute → finalize pipeline.
-- Within a doc, decompose into **requirements**, each one testable behavior. Decision rule: could this part be reviewed and merged on its own? Yes → separate design doc. No → one doc, multiple requirements. Most work is a single doc; splitting is opt-in.
+- 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.
+
+## Umbrella
+
+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.
+
+**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/YYYY-MM-DD-<umbrella>-overview.md`, a **status-free roster**:
+
+   ```markdown
+   # Overview: <umbrella>
+
+   Goal: <one line — what the whole requirement delivers>
+
+   ## Parts (build order)
+   1. <topic> — <one-line scope>
+   2. <topic> — <one-line scope>
+   ```
+
+   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.
+
+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`; report in-flight topics. If the new idea continues an existing topic, ask whether to extend it or start fresh.
+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.
@@ -46,7 +72,7 @@ When unsure, ask: "This looks trivial — fast-path it, or full brainstorm?" Def
 
    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:** propose multiple design docs (one `<topic>` per sub-issue) and get human approval first — see [Granularity](#granularity). Each 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.
 
 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`.
 

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

@@ -19,7 +19,7 @@ The plan is a **behavioral spec** (acceptance criteria + integration tests) —
 
 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/<plan-name>-progress.md`:
+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>
@@ -123,7 +123,12 @@ When no `⬜ pending` or `🔄 in-progress` requirements remain, run the **integ
 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 present:
+Then determine the next step from the artifacts (the human drives every transition — this is a suggestion, not a gate):
+
+- **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).
+
+Present:
 
 ```
 ✅ All requirements complete — integration verified!
@@ -133,7 +138,8 @@ Then present:
 | 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

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
@@ -10,20 +10,43 @@ Ship the completed work.
 ## Pre-finalization checks
 
 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 the progress file (`docs/plans/*-progress.md`):
-   - **Any `❌ failed`** → **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.
+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** — progress file → `Plan:` ref → plan's `Design:` ref → design-doc filename → `<topic>`. Ambiguous with several designs in flight? Ask.
-2. **Delete consumed plan docs** — only this design's three artifacts, matched by the exact topic slug (with the `YYYY-MM-DD-` prefix) so similarly-named plans for other topics survive:
+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 docs/plans/????-??-??-<topic>-implementation.md 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:
 
-   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` handles missing files. `docs/adr/`, `docs/lessons.md`, `CHANGELOG.md`, and `README.md` are permanent — leave them entirely out of the delete set.
+   - **Delete (default)** — code + tests are the source of truth; removing the scaffold prevents stale plan docs from misleading future sessions:
+
+     ```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>"
+     ```
+
+   - **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>"
+     ```
+
+   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:
@@ -38,6 +61,6 @@ Ship the completed work.
 
 ## Principles
 
-- Delete **only** the active design's artifacts — un-started designs (from a split) stay in `docs/plans/`.
+- 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. 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).
+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

@@ -13,8 +13,8 @@ Your writes go into `docs/plans/` and nowhere else. Source code and configuratio
 
 ## Process
 
-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.
-2. **Create the feature branch** — `git checkout -b <topic>` (branch creation is allowed in the plan phase). Design + plan docs live on this branch, committed at the start of `pwk-executing-tasks`.
+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.
@@ -33,6 +33,7 @@ Your writes go into `docs/plans/` and nowhere else. Source code and configuratio
 
    ## 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>