@tianhai/pi-workflow-kit 2.2.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (16) hide show
  1. package/README.md +14 -15
  2. package/agents/pwk-spec-reviewer.md +1 -1
  3. package/agents/pwk-tracing-reviewer.md +1 -1
  4. package/docs/developer-usage-guide.md +11 -17
  5. package/docs/oversight-model.md +12 -10
  6. package/docs/provider-delegation-contract.md +1 -1
  7. package/docs/workflow-phases.md +14 -14
  8. package/extensions/workflow-guard.ts +4 -10
  9. package/package.json +1 -1
  10. package/skills/pwk-brainstorming/SKILL.md +25 -21
  11. package/skills/pwk-code-review/SKILL.md +25 -17
  12. package/skills/pwk-executing-tasks/SKILL.md +80 -60
  13. package/skills/pwk-finalizing/SKILL.md +27 -29
  14. package/skills/pwk-status/SKILL.md +9 -12
  15. package/skills/pwk-walkthrough/SKILL.md +2 -2
  16. package/skills/pwk-diagnose/SKILL.md +0 -59
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # pi-workflow-kit
2
2
 
3
- > Stop AI agents from rushing to code. Enforce a structured brainstorm→plan→execute→finalize workflow with test-first discipline and a feature-gate execution model.
3
+ > Stop AI agents from rushing to code. Enforce a structured design → execute → finalize workflow with test-first discipline and a feature-gate execution model.
4
4
 
5
- AI coding agents tend to skip design and jump straight into implementation, producing over-engineered or misaligned code. **pi-workflow-kit** solves this by hard-blocking write operations during brainstorm and planning phases — the agent *literally cannot modify your source files* until you approve the design.
5
+ AI coding agents tend to skip design and jump straight into implementation, producing over-engineered or misaligned code. **pi-workflow-kit** solves this by hard-blocking write operations during the design phase — the agent *literally cannot modify your source files* until you approve the design.
6
6
 
7
7
  [pi](https://github.com/badlogic/pi-mono) package. Skills are portable; the workflow guard and `/pwk-setup` command are Pi integrations.
8
8
 
@@ -18,7 +18,7 @@ For Pi delegation providers that discover project agents, install the canonical
18
18
  /pwk-setup
19
19
  ```
20
20
 
21
- This creates the five role definitions under `.agents/agents/`. It does not install or configure a provider. Existing customized files are preserved; use `/pwk-setup --force` only when you explicitly want to replace differing role files. Run setup before `/skill:pwk-brainstorming`; the command is refused during brainstorm and plan phases.
21
+ This creates the five role definitions under `.agents/agents/`. It does not install or configure a provider. Existing customized files are preserved; use `/pwk-setup --force` only when you explicitly want to replace differing role files. Run setup before `/skill:pwk-brainstorming`; the command is refused during the design phase.
22
22
 
23
23
  Optionally set a fast-tier model for the smell/hazard reviewers (they carry `thinking: low` and a turn budget by default): `/pwk-setup --fast-model <model>` — or pick one interactively when setup offers — and `--all-roles` to apply it to all four reviewers. The hint is advisory; hosts that cannot honor it keep the default model. Bare re-runs keep the recorded choice; only `--force` replaces local edits beyond the model line.
24
24
 
@@ -51,13 +51,14 @@ Enforces phase-appropriate tool access — not just guidelines, but hard blocks:
51
51
  | Phase | `write` / `edit` | `bash` |
52
52
  |-------|:-:|:-:|
53
53
  | **Design** | 🔒 Blocked outside `docs/plans/` | 🔒 Destructive commands blocked (simple blacklist) |
54
- | **Execute** / **Code-review** / **Finalize** / **Diagnose** / **Status** | ✅ Full access | ✅ Full access |
54
+ | **Execute** / **Code-review** / **Finalize** / **Walkthrough** | ✅ Full access | ✅ Full access |
55
+ | **Status** | Unchanged — status never exits the gate (read-only orientation) | Unchanged — the active phase's bash rules still apply |
55
56
 
56
57
  The agent can read code and discuss design with you during the design phase, 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.
57
58
 
58
- 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.
59
+ 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-walkthrough` (all write beyond `docs/plans/`, so all exit the gate); `pwk-status` stays read-only and runs inside the gate. 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.
59
60
 
60
- ### 🧠 7 Workflow Skills
61
+ ### 🧠 6 Workflow Skills
61
62
 
62
63
  Guide the agent through a disciplined development process:
63
64
 
@@ -65,10 +66,10 @@ Guide the agent through a disciplined development process:
65
66
  brainstorm → executing-tasks → finalizing
66
67
  (feature-gate: write feature E2E → report it → implement → review → ⏸ ship checkpoint)
67
68
  ↕
68
- diagnose (anytime) · status (anytime)
69
+ status (anytime)
69
70
  ```
70
71
 
71
- 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.
72
+ A **design doc is one PR**; a **requirement is one testable slice within it**. **One folder per topic** — `docs/plans/<date>-<topic>/` holds the topic's design doc, progress file, and review packet, and is the unit disposed at finalize. A requirement too big for one design doc but shipping as one PR is an **umbrella** — more than one leaf in that same folder, under one status-free overview, on one branch, finalized once.
72
73
 
73
74
  | Phase | Trigger | What Happens |
74
75
  |-------|---------|--------------|
@@ -76,7 +77,6 @@ A **design doc is one PR**; a **requirement is one testable slice within it**. A
76
77
  | **Execute** | `/skill:pwk-executing-tasks` | Create the feature branch, then: write the feature E2E (red) → **report it, no stop** → implement the design doc's `### R<n>` requirement blocks → feature review (risk-scaled: four roles or one inline pass) → **ship checkpoint** (execution summary + code digest + coverage table; full diff on request) |
77
78
  | **Code review** | `/skill:pwk-code-review` | Feature-level (default) or per-requirement: code tracing, spec alignment, code smells (applies fixes), production hazard check. Delegated review uses four tiered logical roles (smell/hazard on a fast model via `/pwk-setup --fast-model`) over a script-assembled review packet when a safe provider is available; otherwise it runs inline. |
78
79
  | **Finalize** | `/skill:pwk-finalizing` | Delete consumed plan docs or archive them under `docs/plans/completed/` (discovery always runs excluding docs/plans/completed/, so archived work never resurfaces as in flight — single source: the `pwk-executing-tasks` glob wording), update README/CHANGELOG, create PR |
79
- | **Diagnose** | `/skill:pwk-diagnose` | Debugging loop: reproduce → hypothesise → instrument → fix → cleanup. **Exits the gated phase** (debugging writes tests/instrumentation) |
80
80
  | **Walkthrough** | `/skill:pwk-walkthrough` | On demand: generate a detailed, file:line-anchored walkthrough of a shipped feature into `docs/walkthroughs/<topic>.md` (Summary / How it works / Key flows / Gotchas & invariants / Change map); stamped with the commit range, regenerated wholesale, never disposed. **Exits the gated phase** |
81
81
  | **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**. |
82
82
 
@@ -115,7 +115,6 @@ A persistent rules file (`docs/lessons.md`) helps the agent learn from repeat mi
115
115
 
116
116
  ```
117
117
  brainstorm → reads lessons (design context)
118
- plan → reads lessons (acceptance criteria / tests)
119
118
  execute → reads lessons per requirement, writes new ones on repeat mistakes
120
119
  finalize → reviews, generalizes, and retires stale rules
121
120
  ```
@@ -128,12 +127,13 @@ Rules are simple imperative bullets:
128
127
 
129
128
  No configuration needed — the agent creates `docs/lessons.md` on first use and it grows as the agent learns.
130
129
 
131
- ### One Feature-Level Checkpoint
130
+ ### Feature-Level Checkpoints
132
131
 
133
- The feature-gate flow has **one hard human-review gate** (not optional):
132
+ The feature-gate flow's hard human-review gates (not optional) — **two hard stops when the design carries `## Setup`** (setup + ship), otherwise one (ship):
134
133
 
135
134
  | Checkpoint | What's done | What you review |
136
135
  |---|---|---|
136
+ | **setup** *(only when the design has a `## Setup` section)* | Dependencies installed, migrations applied, existing suite run | Setup results — approve before implementation starts |
137
137
  | **ship** | All requirements implemented; full suite + E2E green; feature review collected | Execution summary + code digest + per-requirement coverage table — built as promised? (full diff on request) |
138
138
 
139
139
  The agent stops and waits there — approve, request changes, or send it back. The feature-acceptance E2E is still written first and still gated at the ship checkpoint; it is reported before implementation without pausing, because its text was approved as `## Feature acceptance` during brainstorm.
@@ -158,7 +158,7 @@ pi install npm:@tianhai/pi-workflow-kit
158
158
 
159
159
  > /skill:pwk-executing-tasks
160
160
 
161
- # (feature-gate: creates the branch, writes feature E2E → checkpoint → implements the blocks → checkpoint → feature review)
161
+ # (feature-gate: creates the branch → setup stop when the design carries `## Setup` → writes feature E2E → notice → implements the blocks → feature review → ship checkpoint)
162
162
 
163
163
  > /skill:pwk-finalizing
164
164
 
@@ -169,7 +169,7 @@ pi install npm:@tianhai/pi-workflow-kit
169
169
 
170
170
  - **AI agents skip design.** Left unchecked, they jump to code and over-engineer. This forces a think-first workflow.
171
171
  - **Specs beat recipes.** Plans are behavioral specs (acceptance criteria + tests), not implementation recipes — they don't invalidate when details change.
172
- - **You stay in control.** One feature-level checkpoint (ship) lets you sign off the finished implementation — execution summary, code digest, and coverage table — before the agent ships; the E2E is reported before implementation so you can object early.
172
+ - **You stay in control.** One or two feature-level stops (setup when the design carries `## Setup`, then ship) let you sign off the finished implementation — execution summary, code digest, and coverage table — before the agent ships; the E2E is reported before implementation so you can object early.
173
173
  - **Enforced, not suggested.** Hard blocks mean the agent can't ignore the rules — not even accidentally.
174
174
 
175
175
  ## Project
@@ -184,7 +184,6 @@ pi-workflow-kit/
184
184
  │ ├── pwk-code-review/SKILL.md
185
185
  │ ├── pwk-finalizing/SKILL.md
186
186
  │ ├── pwk-status/SKILL.md
187
- │ ├── pwk-diagnose/SKILL.md
188
187
  │ └── pwk-walkthrough/SKILL.md # on-demand explainer; docs/walkthroughs/ output
189
188
  ├── agents/ # canonical role contracts; /pwk-setup copies them to .agents/agents/
190
189
  ├── docs/
package/agents/pwk-spec-reviewer.md CHANGED
@@ -28,7 +28,7 @@ The task provides a review packet: the diff under review plus the acceptance cri
28
28
 
29
29
  For each acceptance criterion, point to the code and the test that satisfy it. A criterion with no covering code or no test is a **gap**. Code that does more than the criteria specify is **scope creep** — flag it.
30
30
 
31
- **Open the report with a coverage table** — one row per requirement, keyed by the packet's `## Requirement N` headings (R# = N):
31
+ **Open the report with a coverage table** — one row per requirement, keyed by the design doc's `### R<n>:` headings as carried verbatim in the packet's `## Acceptance criteria` section (R# = n):
32
32
 
33
33
  | R# | Verdict | Evidence |
34
34
  |----|---------|----------|
package/agents/pwk-tracing-reviewer.md CHANGED
@@ -26,4 +26,4 @@ The task provides a review packet: the diff under review plus the acceptance cri
26
26
 
27
27
  ### Code tracing
28
28
 
29
- Trace the new or changed code paths end-to-end against the integration tests. For each path, determine whether data flows correctly from entry to the asserted outcome. Note any branch the tests do not exercise, any dead branch, or any path where the trace breaks.
29
+ Trace the new or changed code paths end-to-end against the acceptance criteria and the feature-acceptance E2E scenarios in the packet. For each path, determine whether data flows correctly from entry to the asserted outcome. Note any branch the tests do not exercise, any dead branch, or any path where the trace breaks.
package/docs/developer-usage-guide.md CHANGED
@@ -2,10 +2,12 @@
2
2
 
3
3
  How to install and use `pi-workflow-kit` with Pi, and how its workflow roles map to other agent hosts.
4
4
 
5
+ The kit enforces a design → execute → finalize workflow: one buildable design doc per feature, executed through the feature gate, shipped once.
6
+
5
7
  ## What you get
6
8
 
7
9
  - **4 pipeline skills** — brainstorm → executing-tasks → finalizing, with code-review running at the feature level during execution.
8
- - **2 utility skills** — diagnose (debugging) and status (multi-topic overview), both on demand.
10
+ - **2 utility skills** — status (multi-topic overview) and walkthrough (on-demand explainer), both invoked on demand.
9
11
  - **1 extension** — hard-blocks source writes during the design phase, and blocks destructive bash via a simple common-blacklist.
10
12
 
11
13
  ## Installation
@@ -32,7 +34,7 @@ Or in `.pi/settings.json` / `~/.pi/agent/config.json`:
32
34
 
33
35
  ## The workflow
34
36
 
35
- 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:
37
+ You control each phase by invoking the skill. One folder per topic: `docs/plans/<date>-<topic>/` holds the topic's design doc, progress file, and review packet, and is the unit disposed at finalize. 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** — more than one leaf in that same folder, under one status-free overview, on one branch, finalized once:
36
38
 
37
39
  ```
38
40
  /skill:pwk-brainstorming → /skill:pwk-executing-tasks → /skill:pwk-finalizing
@@ -46,7 +48,7 @@ Before entering the gated phase in Pi, optionally install the canonical role def
46
48
  /pwk-setup
47
49
  ```
48
50
 
49
- The command creates `.agents/agents/` and installs the five PWK roles. It preserves differing files unless `--force` is supplied and is refused during brainstorm and plan phases. It does not install a delegation provider.
51
+ The command creates `.agents/agents/` and installs the five PWK roles. It preserves differing files unless `--force` is supplied and is refused during the design phase. It does not install a delegation provider.
50
52
 
51
53
  ```
52
54
  /skill:pwk-brainstorming
@@ -54,7 +56,7 @@ The command creates `.agents/agents/` and installs the five PWK roles. It preser
54
56
 
55
57
  Explore the idea through collaborative dialogue. The agent reads code, asks questions, proposes approaches, and presents the design for your review. Questioning runs in **frontier rounds**: numbered questions each carrying a recommended answer, facts looked up rather than asked, an assumption gate before the design is presented, and a frontier-empty stop rule (nothing left silently assumed). On non-trivial topics with prior art, the skill requests the logical `codebase-recon` capability using the `pwk-recon-scout` role. A compatible host may dispatch that role in a fresh, bounded, read-only worker; otherwise the skill reports `Scout: unavailable` and performs the same five-section recon inline.
56
58
 
57
- Outcome: `docs/plans/YYYY-MM-DD-<topic>-design.md` — descriptive, opening with a `## At a glance` digest for the human (plain-language summary → **Key decisions** — `(rejected: …)` clauses only for real forks — → `| R# | Requirement in one line | Risk |` table) immediately before the `## Requirements` blocks. 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).
59
+ Outcome: `docs/plans/<date>-<topic>/<leaf>-design.md` — descriptive, opening with a `## At a glance` digest for the human (plain-language summary → **Key decisions** — `(rejected: …)` clauses only for real forks — → `| R# | Requirement in one line | Risk |` table) immediately before the `## Requirements` blocks. For a too-big requirement, may start an **umbrella** (writes a status-free `overview.md` + the first leaf's design doc in the same folder). ADRs go to `docs/adr/` (permanent).
58
60
 
59
61
  ### 2. Execute
60
62
 
@@ -62,7 +64,7 @@ Outcome: `docs/plans/YYYY-MM-DD-<topic>-design.md` — descriptive, opening with
62
64
  /skill:pwk-executing-tasks
63
65
  ```
64
66
 
65
- Implement via the **feature-gate flow** with full autonomy: write the feature-acceptance E2E test (red) → **report it (no stop)** → implement the requirements back-to-back → feature review → **ship checkpoint** (full suite + E2E green; you review the execution summary + code digest + coverage table — full diff on request). After the review passes, the executor writes the code digest into the progress file from the review packet. One mandatory checkpoint (ship) at the feature level. Per-requirement checkpoints/reviews are opt-in (default off).
67
+ Implement via the **feature-gate flow** with full autonomy: write the feature-acceptance E2E test (red) → **report it (no stop)** → implement the requirements back-to-back → feature review → **ship checkpoint** (full suite + E2E green; you review the execution summary + code digest + coverage table — full diff on request). After the review passes, the executor writes the code digest into the progress file from the review packet. Two hard stops when the design carries `## Setup` (setup + ship); otherwise one (ship) at the feature level. Per-requirement checkpoints/reviews are opt-in (default off).
66
68
 
67
69
  ### 3. Code review (feature level)
68
70
 
@@ -80,12 +82,6 @@ In Pi, `/pwk-setup` installs the canonical role definitions into `.agents/agents
80
82
 
81
83
  **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; archived docs land in `docs/plans/completed/`, and every discovery glob runs excluding docs/plans/completed/ so archived work never resurfaces as in flight — single source: the `pwk-executing-tasks` glob wording), curate lessons, update CHANGELOG/README, create PR or merge.
82
84
 
83
- ### Diagnose (on demand)
84
-
85
- ```
86
- /skill:pwk-diagnose
87
- ```
88
-
89
85
  ### Walkthrough (on demand)
90
86
 
91
87
  ```
@@ -94,8 +90,6 @@ In Pi, `/pwk-setup` installs the canonical role definitions into `.agents/agents
94
90
 
95
91
  Generate a detailed, file:line-anchored walkthrough of a shipped feature or branch into `docs/walkthroughs/<topic>.md` — Summary / How it works / Key flows / Gotchas & invariants / Change map — stamped with the commit range, regenerated wholesale on re-run, never disposed. Exits the gated design phase.
96
92
 
97
- A debugging loop you invoke when something is broken. Not a pipeline phase. **Invoking it exits the gated design 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`.
98
-
99
93
  ### Status (on demand)
100
94
 
101
95
  ```
@@ -109,8 +103,8 @@ A read-only overview of all active design topics — which phase each is in and
109
103
  The `workflow-guard` extension registers `/pwk-setup` and watches `write`/`edit` and `bash` tool calls:
110
104
 
111
105
  - **During the design phase**: 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.
112
- - **During executing-tasks, code-review, finalizing, diagnose**: no restrictions.
113
- - **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.
106
+ - **During executing-tasks, code-review, finalizing, walkthrough**: no restrictions.
107
+ - **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-walkthrough` (walkthrough writes explainer output under `docs/walkthroughs/`); `pwk-status` stays read-only and runs inside the gate. To override, run `/pwk-guard on` (force read-only), `off` (disable), or `auto` (default; skill-driven). Subcommands autocomplete.
114
108
 
115
109
  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.
116
110
 
@@ -118,12 +112,12 @@ No configuration needed. It activates automatically after install.
118
112
 
119
113
  ## Test-first discipline
120
114
 
121
- Plans specify *what* (acceptance criteria + integration tests); the executor writes the tests first (red), then implements to green. This keeps the spec stable — implementation details can change without invalidating the plan.
115
+ Design docs specify *what* (acceptance criteria + end-to-end scenarios); the executor writes the feature-acceptance E2E first (red), then implements to green. This keeps the spec stable — implementation details can change without invalidating the design.
122
116
 
123
117
  ## Tips
124
118
 
125
119
  - Start with brainstorming for anything non-trivial.
126
120
  - The design doc is a behavioral spec, not an implementation recipe — let the executor choose how.
127
- - The feature-gate flow has **one** mandatory checkpoint (ship): the E2E is written and reported before implementation without pausing (its content was approved as `## Feature acceptance` during brainstorm), and the ship checkpoint signs off the finished implementation (digest + coverage, diff on request).
121
+ - The feature-gate flow has two hard stops when the design carries `## Setup` (setup + ship), otherwise one (ship): the E2E is written and reported before implementation without pausing (its content was approved as `## Feature acceptance` during brainstorm), and the ship checkpoint signs off the finished implementation (digest + coverage, diff on request).
128
122
  - **Right-size each requirement at design time** with the `### Checkpoints` (`none`/`full`, default `none` — the acceptance criteria were approved at design time, so there is no per-requirement correctness stop) and `### Review` (`skip`/`parallel`/`inline`, default `skip`) tags — per-requirement ceremony is opt-in. The risk-scaled feature-level `### Feature review` covers the whole diff. A trivial fix can also use the brainstorming trivial fast-path (one-turn brainstorm, minimal design doc). Nothing is tagged silently: **only the human tags** a requirement for a per-requirement review, and the always-on feature-level `### Feature review` covers what is left.
129
123
  - Put all design artifacts under `docs/plans/`; ADRs under `docs/adr/`.
package/docs/oversight-model.md CHANGED
@@ -2,19 +2,21 @@
2
2
 
3
3
  `pi-workflow-kit` combines **skills** and **one extension**.
4
4
 
5
+ The kit enforces a design → execute → finalize workflow: one buildable design doc per feature, executed through the feature gate, shipped once.
6
+
5
7
  ## Skills
6
8
 
7
- Skills teach the agent the workflow. There are 5 pipeline skills:
9
+ Skills teach the agent the workflow. There are 4 pipeline skills plus 2 utility skills:
8
10
 
9
- - **pwk-brainstorming** — explore ideas, produce the single buildable design doc (each `### R<n>:` block carries its acceptance criteria + review tags) that opens with a `## At a glance` digest for the human (plain-language summary → **Key decisions** with rejected-alternative clauses only for real forks → `| R# | Requirement in one line | Risk |` table) immediately before the `## Requirements` blocks. 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). On non-trivial topics, requests the logical `codebase-recon` capability and falls back to the `pwk-recon-scout` role inline when unavailable or unsafe.
10
- - **pwk-executing-tasks** — feature-gate flow: write the feature E2E first, report it (no stop), implement the design doc's `### R<n>` requirement blocks, then one risk-scaled feature-level review before the **ship checkpoint** (execution summary + code digest + coverage table presented for approval; full diff on request); one mandatory checkpoint (ship), per-requirement ceremony opt-in
11
- - **pwk-code-review** — the inline reviewer (code tracing, spec alignment, code smells, production hazards). During `pwk-executing-tasks`, the feature-level review resolves the design's `### Feature review` tag (`auto` by default): four logical fresh-context, read-only roles when the design carries production-risk content, otherwise one inline pass. successful reports are retained and missing roles are retried or completed inline. It falls back to inline review when no safe compatible provider exists. The canonical provider contract is documented in `docs/provider-delegation-contract.md`.
12
- - **pwk-finalizing** — dispose consumed plan docs (archive or delete; for an umbrella, the overview + every part), curate lessons, update docs, create PR or merge
11
+ - **pwk-brainstorming** — explore ideas, produce the single buildable design doc (each `### R<n>:` block carries its acceptance criteria + review tags) that opens with a `## At a glance` digest for the human (plain-language summary → **Key decisions** with rejected-alternative clauses only for real forks → `| R# | Requirement in one line | Risk |` table) immediately before the `## Requirements` blocks. 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). On non-trivial topics, requests the logical `codebase-recon` capability using the `pwk-recon-scout` role and falls back to the same five-section recon inline when unavailable or unsafe.
12
+ - **pwk-executing-tasks** — feature-gate flow: write the feature E2E first, report it (no stop), implement the design doc's `### R<n>` requirement blocks, then one risk-scaled feature-level review before the **ship checkpoint** (execution summary + code digest + coverage table presented for approval; full diff on request); two hard stops when the design carries `## Setup` (setup + ship), otherwise one (ship), per-requirement ceremony opt-in
13
+ - **pwk-code-review** — the inline reviewer (code tracing, spec alignment, code smells, production hazards). During `pwk-executing-tasks`, the feature-level review resolves the design's `### Feature review` tag (`auto` by default): four logical fresh-context, read-only roles when the design carries production-risk content, otherwise one inline pass. Successful reports are retained and missing roles are retried or completed inline. It falls back to inline review when no safe compatible provider exists. The canonical provider contract is documented in `docs/provider-delegation-contract.md`.
14
+ - **pwk-finalizing** — dispose the consumed topic folder `docs/plans/<date>-<topic>/` as one unit (archive or delete; a single-leaf topic and an umbrella alike), curate lessons, update docs, create PR or merge
13
15
 
14
- Plus 2 on-demand skills:
16
+ Plus 2 on-demand utility skills:
15
17
 
16
18
  - **pwk-status** — read-only overview of all active design topics (phase + progress), for resuming or juggling parallel designs
17
- - **pwk-diagnose** — 6-phase debugging loop, invoked anytime something is broken
19
+ - **pwk-walkthrough** — on-demand explainer; renders a file:line-anchored walkthrough of a shipped feature into `docs/walkthroughs/<topic>.md`, regenerated wholesale, never disposed
18
20
 
19
21
  They explain *what* to do and *when* to do it. Phase control is manual — you invoke each skill with `/skill:`; the agent never advances on its own.
20
22
 
@@ -22,15 +24,15 @@ They explain *what* to do and *when* to do it. Phase control is manual — you i
22
24
 
23
25
  The `workflow-guard` extension registers the Pi-only `/pwk-setup` command and enforces one workflow rule:
24
26
 
25
- > During brainstorm and plan phases, `write` and `edit` are **hard-blocked** outside `docs/plans/`.
27
+ > During the design phase, `write` and `edit` are **hard-blocked** outside `docs/plans/`.
26
28
 
27
29
  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.
28
30
 
29
- 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.
31
+ During executing-tasks, code-review, finalizing, and walkthrough, nothing is restricted. `pwk-status` stays inside the gate.
30
32
 
31
33
  Canonical role contracts live in `agents/pwk-*.md` (single source of truth) and can be installed into `.agents/agents/` with `/pwk-setup`. `pwk-executing-tasks` requests logical review roles through the host’s delegation capabilities and passes each role a one-liner pointer to a script-assembled review packet — the packet defines the scope per review level (feature review: the whole feature diff; per-requirement: just that slice).
32
34
 
33
- 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.
35
+ Phases follow the skill you invoke — there is no message-keyword unlock. Invoking `/skill:pwk-executing-tasks`, `pwk-finalizing`, `pwk-code-review`, or `pwk-walkthrough` exits the gated phase (those skills write — walkthrough writes its explainer output under `docs/walkthroughs/`); `pwk-status` deliberately does **not** (read-only orientation). `/pwk-guard on|off|auto` manually overrides the guard.
34
36
 
35
37
  ## Enforcement style
36
38
 
package/docs/provider-delegation-contract.md CHANGED
@@ -115,6 +115,6 @@ Providers may cache role definitions. Hosts should tell the user when `/reload`
115
115
 
116
116
  ## Safety boundary
117
117
 
118
- The provider is responsible for enforcing any capability it advertises. The role prompt is defense in depth, not a security boundary. The Pi workflow guard protects the main Pi session’s brainstorm and plan phases; it does not automatically protect Claude Code or another host, and it does not replace delegated-worker tool restrictions.
118
+ The provider is responsible for enforcing any capability it advertises. The role prompt is defense in depth, not a security boundary. The Pi workflow guard protects the main Pi session's design phase; it does not automatically protect Claude Code or another host, and it does not replace delegated-worker tool restrictions.
119
119
 
120
120
  The `/pwk-setup` installer itself is hardened in depth: it opens the target with `O_NOFOLLOW` and does every subsequent check, read, and write through that one descriptor (`fstat` regular-file check, content comparison, and post-write verification), so nothing swapped in on the path afterward can affect what is read or written. On platforms where `O_NOFOLLOW` is unavailable, a symlink swapped in before the initial open remains a narrow advisory window; setup is a user-invoked development command, not a security boundary.
package/docs/workflow-phases.md CHANGED
@@ -1,13 +1,15 @@
1
1
  # Workflow Phases
2
2
 
3
- `pi-workflow-kit` has 4 pipeline skills plus 3 utility skills. You invoke each one explicitly with `/skill:`.
3
+ The kit enforces a design → execute → finalize workflow. Each phase below names the skill that drives it:
4
+
5
+ `pi-workflow-kit` has 4 pipeline skills plus 2 utility skills. You invoke each one explicitly with `/skill:`.
4
6
 
5
7
  ```
6
8
  brainstorm → executing-tasks → finalizing
7
9
  (feature-gate: write feature E2E → report it → implement requirements → feature review → ⏸ ship)
8
10
  ```
9
11
 
10
- 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 → execute) × N → finalize`).
12
+ **One folder per topic.** Every topic — a single-part design doc or an umbrella — lives in its own folder `docs/plans/<date>-<topic>/`, and that folder is the unit of creation, discovery, and disposal. Its docs are leaves inside it: `<leaf>-design.md`, `<leaf>-progress.md`, `<leaf>-review-packet*.md`, where `<leaf>` is the part slug (`<topic>` for a single-part topic). A folder holding more than one leaf also carries an `overview.md`. 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 (leaves) under one status-free overview, on one branch, finalized once (`(brainstorm → execute) × N → finalize`).
11
13
 
12
14
  ## brainstorm
13
15
 
@@ -16,8 +18,8 @@ A design doc is one PR; a requirement is one testable slice within it. A require
16
18
  ```
17
19
 
18
20
  - Explore requirements and shape the design. Interviews in **frontier rounds**: questions form a dependency tree seeded by a six-dimension checklist; each round asks the full frontier as numbered questions, each with a recommended answer; facts are looked up, only decisions asked; the interview ends when the frontier is empty — nothing left silently assumed — and an assumption gate sweeps the draft before the design is presented.
19
- - Produce `docs/plans/YYYY-MM-DD-<topic>-design.md` — descriptive, the **single buildable artifact**: a `## At a glance` digest for the human (2–4 sentence plain-language summary → **Key decisions**, one line each: decision + why, a `(rejected: …)` clause only when the fork was real → a `| R# | Requirement in one line | Risk |` table, one row per requirement) immediately before the `## Requirements` blocks — one `### R<n>:` block per requirement carrying its one-line behavior, **acceptance criteria** (Given/When/Then incl. edge/error cases) and Checkpoints/Review tags (no test-name lists, no separate plan doc) — 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).
20
- - May start an **umbrella** for a requirement too big for one design doc (human-approved): writes the status-free `docs/plans/<date>-<umbrella>/overview.md` (each umbrella in its own folder; roster of parts + build order) and the **first** part's `-design.md` beside it. Later parts are brainstormed one by one against the overview + implemented predecessors.
21
+ - Produce `docs/plans/<date>-<topic>/<leaf>-design.md` — descriptive, the **single buildable artifact**: a `## At a glance` digest for the human (2–4 sentence plain-language summary → **Key decisions**, one line each: decision + why, a `(rejected: …)` clause only when the fork was real → a `| R# | Requirement in one line | Risk |` table, one row per requirement) immediately before the `## Requirements` blocks — one `### R<n>:` block per requirement carrying its one-line behavior, **acceptance criteria** (Given/When/Then incl. edge/error cases) and Checkpoints/Review tags (no test-name lists, no separate plan doc) — ending with a `## Feature acceptance` section (end-to-end scenarios that prove the requirements compose into the feature — the feature's definition-of-done).
22
+ - May start an **umbrella** for a requirement too big for one design doc (human-approved): writes the status-free `docs/plans/<date>-<topic>/overview.md` (the same topic folder, now with more than one leaf; a `## Parts (build order)` roster of leaves + build order) and the **first** leaf's `<leaf>-design.md` beside it. Later leaves are brainstormed one by one against the overview + implemented predecessors.
21
23
  - ADRs go to `docs/adr/` (permanent, never archived).
22
24
 
23
25
  Write boundary: only `docs/plans/` is writable. Source files are hard-blocked.
@@ -32,7 +34,7 @@ Write boundary: only `docs/plans/` is writable. Source files are hard-blocked.
32
34
  - After the review passes, the executor writes a **code digest** into the progress file — plain-language summary, execution flow, gotchas, key files — derived from the review packet; it rides the existing disposal globs.
33
35
  - Per-requirement checkpoints/reviews are **opt-in** — they fire only for requirements the design doc tags (default off); see [Proportionality](#proportionality).
34
36
  - **Regression check after each commit** — run the full existing suite to catch cross-requirement regressions immediately. The feature E2E stays red until the last requirement and is gated only at the ship checkpoint (the old integration gate folds into it).
35
- - Progress tracked in `docs/plans/*-progress.md` (feature phase + requirement checklist).
37
+ - Progress tracked in `docs/plans/<date>-<topic>/<leaf>-progress.md` (feature phase + requirement checklist).
36
38
 
37
39
  No write restrictions. All tools available.
38
40
 
@@ -64,8 +66,8 @@ No write restrictions.
64
66
  /skill:pwk-finalizing
65
67
  ```
66
68
 
67
- - **Pre-check: run the full test suite** — don't ship a red suite (resume spans sessions; don't trust the last execute session).
68
- - 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; every discovery glob runs excluding docs/plans/completed/, so archived work never resurfaces as in flight — single source: the `pwk-executing-tasks` glob wording). ADRs stay at `docs/adr/`. For an umbrella (a `docs/plans/**/overview.md` exists), disposes the whole `docs/plans/<date>-<umbrella>/` folder — overview **and every part's** docs — in one pass and ships **one PR**.
69
+ - **Pre-check: verify the repo root, then run the full test suite** — don't ship a red suite (resume spans sessions; don't trust the last execute session).
70
+ - Dispose of consumed plan docs — the unit is the **topic folder** `docs/plans/<date>-<topic>/`, so a single-leaf topic and an umbrella dispose identically as one folder. The human picks **delete** (default — code + tests are the source of truth) or **archive** to `docs/plans/completed/` (keep planning history; every discovery glob runs excluding docs/plans/completed/, so archived work never resurfaces as in flight — single source: the `pwk-executing-tasks` glob wording). ADRs stay at `docs/adr/`. Ships **one PR** per topic.
69
71
  - Curate `docs/lessons.md`, update README/CHANGELOG, create PR or merge.
70
72
 
71
73
  No write restrictions.
@@ -76,17 +78,15 @@ No write restrictions.
76
78
  /skill:pwk-status
77
79
  ```
78
80
 
79
- 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 design-phase write block, so the boundary stays up).
81
+ Read-only overview of all active pipeline topics (phase + progress) when several designs are in flight; an umbrella rolls up under its overview (done / 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 design-phase write block, so the boundary stays up).
80
82
 
81
- ## diagnose
83
+ ## walkthrough
82
84
 
83
85
  ```
84
- /skill:pwk-diagnose
86
+ /skill:pwk-walkthrough
85
87
  ```
86
88
 
87
- 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`.
88
-
89
- No write restrictions.
89
+ Not a pipeline phase. An on-demand utility skill that generates a detailed, file:line-anchored walkthrough of a shipped feature into `docs/walkthroughs/<topic>.md` — Summary / How it works / Key flows / Gotchas & invariants / Change map — stamped with the commit range, regenerated wholesale on re-run, never disposed. Invoking it **exits the gated phase** (it writes its explainer output under `docs/walkthroughs/`).
90
90
 
91
91
  ## Manual override
92
92
 
@@ -94,4 +94,4 @@ No write restrictions.
94
94
 
95
95
  ## Continuity across sessions
96
96
 
97
- A new session resumes by invoking the skill for the phase to continue. The skill globs `docs/plans/` for its artifact (progress file / plan doc), resumes the single match, or asks if several. Each resumption skill reports what it found on entry — no registry file needed; the `<topic>` slug in the filenames is the identity.
97
+ A new session resumes by invoking the skill for the phase to continue. The skill globs `docs/plans/` for its artifact (progress file / design doc), resumes the single match, or asks if several. Each resumption skill reports what it found on entry — no registry file needed; the `<topic>` slug in the filenames is the identity.
package/extensions/workflow-guard.ts CHANGED
@@ -477,13 +477,7 @@ const SKILL_TO_PHASE: Record<string, Phase> = {
477
477
 
478
478
  /** Skills whose invocation exits a gated phase (used by the input handler; exported for tests/
479
479
  * skill-lint). Deliberately excludes pwk-status (read-only by design; stays gated). */
480
- export const UNLOCK_SKILLS = [
481
- "pwk-executing-tasks",
482
- "pwk-finalizing",
483
- "pwk-code-review",
484
- "pwk-diagnose",
485
- "pwk-walkthrough",
486
- ] as const;
480
+ export const UNLOCK_SKILLS = ["pwk-executing-tasks", "pwk-finalizing", "pwk-code-review", "pwk-walkthrough"] as const;
487
481
 
488
482
  /** Phase-aware reminder appended after the user's message each turn while a gated phase is active.
489
483
  * Returned as a message (not a system-prompt change) so it sits at the tail of the request and
@@ -660,9 +654,9 @@ export default function (pi: ExtensionAPI) {
660
654
  // Phase transitions happen only via skills — no message keyword unlocks the design phase.
661
655
  // Run /skill:pwk-executing-tasks (or another write-needing skill) to leave a gated phase.
662
656
  //
663
- // Unlock list rationale: execute/finalize/code-review/diagnose/walkthrough all need to write
664
- // source or docs outside docs/plans/ (implement, edit review fixes, add [DEBUG-] instrumentation,
665
- // generate docs/walkthroughs/), so they exit the gate.
657
+ // Unlock list rationale: execute/finalize/code-review/walkthrough all need to write
658
+ // source or docs outside docs/plans/ (implement, edit review fixes, generate
659
+ // docs/walkthroughs/), so they exit the gate.
666
660
  // pwk-status is NOT here on purpose: it is read-only orientation, so it stays inside the
667
661
  // gated phase and never drops the write boundary the user is relying on.
668
662
  // (Orientation never needs write access; see skills/pwk-status.)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tianhai/pi-workflow-kit",
3
- "version": "2.2.0",
3
+ "version": "2.4.0",
4
4
  "description": "Enforce structured design→execute→finalize workflow with TDD discipline in AI coding agents",
5
5
  "keywords": [
6
6
  "pi-package",
package/skills/pwk-brainstorming/SKILL.md CHANGED
@@ -5,13 +5,13 @@ description: "Use this before any creative work — creating features, building
5
5
 
6
6
  # Brainstorming
7
7
 
8
- 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.) The design doc is the **single buildable artifact** — each requirement carries its own acceptance criteria and review tags, and the executor builds straight from it; nothing is re-derived into a second document later. Source-writing happens in `pwk-executing-tasks`.
8
+ Read-only exploration of source code; every file you create or edit goes under `docs/plans/`. (An approved ADR goes to `docs/adr/`, which sits outside the writable boundary — the human writes it themselves or briefly runs `/pwk-guard off`; the design phase never unlocks it.) The design doc is the **single buildable artifact** — each requirement carries its own acceptance criteria and review tags, and the executor builds straight from it; nothing is re-derived into a second document later. Source-writing happens in `pwk-executing-tasks`.
9
9
 
10
10
  ## Proportionality: trivial vs non-trivial
11
11
 
12
12
  Classify the change at the start.
13
13
 
14
- - **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–7; write a **minimal** design doc in one turn (an `In short:` one-liner — what + why + approach in plain words, plus a single `### R1:` requirement block with its criteria and tags, and an optional `## Production-risk areas` line), and hand off to `/skill:pwk-executing-tasks`. The guard still enforces read-only — trivial compresses the phase to one turn, it doesn't skip it.
14
+ - **Trivial** — typo or obvious bugfix with no open design questions, config/version bump, single-function change, or anything the human flags as trivial. Skip steps 3–6; write a **minimal** design doc in one turn (an `In short:` one-liner — what + why + approach in plain words, plus a single `### R1:` requirement block with its criteria and tags, and an optional `## Production-risk areas` line — and deliberately **no `## Feature acceptance`**: a trivial slice's ship gate is the full existing suite, no E2E is manufactured for it), and hand off to `/skill:pwk-executing-tasks`. The guard still enforces read-only — trivial compresses the phase to one turn, it doesn't skip it.
15
15
  - **Non-trivial** — open design questions, multiple approaches, cross-module impact, or new behavior. Run the full process below.
16
16
 
17
17
  When unsure, ask: "This looks trivial — fast-path it, or full brainstorm?" Default to full.
@@ -20,48 +20,50 @@ When unsure, ask: "This looks trivial — fast-path it, or full brainstorm?" Def
20
20
 
21
21
  **One design doc = one PR; one requirement = one testable slice within it.** Most work is a single design doc.
22
22
 
23
+ **One folder per topic.** Every topic — a single-part design doc or an umbrella — lives in its own folder `docs/plans/<date>-<topic>/`, and that folder is the unit of creation, discovery, and disposal. The topic's docs are leaves inside it: `<leaf>-design.md`, `<leaf>-progress.md`, `<leaf>-review-packet*.md`, where `<leaf>` is the part slug (`<topic>` itself for a single-part topic — the everyday case). A folder holding more than one leaf also carries an `overview.md`, and that is all "umbrella" means: a topic whose requirement was split into several design docs that still ship as one PR.
24
+
23
25
  - Within a doc, decompose into **requirements** — one `### R<n>: <name>` block per requirement, each one testable behavior carrying its own acceptance criteria and tags.
24
26
  - 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.
25
27
 
26
28
  ## Umbrella
27
29
 
28
- 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/execute cycle small and focused, not a multi-PR strategy.
30
+ An umbrella splits one large requirement into multiple design docs that ship together as **one PR**. It is the single-topic folder above with more than one leaf: one branch, one `pwk-finalizing` at the end, which disposes the folder as one unit. The split is intra-PR decomposition — a way to keep each design/execute cycle small and focused, not a multi-PR strategy.
29
31
 
30
32
  **First brainstorm** (the requirement is too big for one design doc):
31
33
 
32
34
  1. **Propose the split** — the parts, a one-line scope each, and build order. Get human approval before writing anything beyond discovery.
33
- 2. **Write the overview** — `docs/plans/<date>-<umbrella>/overview.md`, in the umbrella's own folder (every part doc lives beside it: `<part>-design.md`, `<part>-progress.md`, `*-review-packet.md`), a **status-free roster**:
35
+ 2. **Write the overview** — `docs/plans/<date>-<topic>/overview.md`, in the topic's own folder (every leaf lives beside it: `<leaf>-design.md`, `<leaf>-progress.md`, `<leaf>-review-packet*.md`), a **status-free roster**:
34
36
 
35
37
  ```markdown
36
- # Overview: <umbrella>
38
+ # Overview: <topic>
37
39
 
38
40
  Goal: <one line — what the whole requirement delivers>
39
41
 
40
42
  ## Parts (build order)
41
- 1. <topic> — <one-line scope>
42
- 2. <topic> — <one-line scope>
43
+ 1. <leaf> — <one-line scope>
44
+ 2. <leaf> — <one-line scope>
43
45
  ```
44
46
 
45
- 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`.
46
- 3. **Write the first part's** `<part>-design.md` in the same umbrella folder, then hand off to `/skill:pwk-executing-tasks`.
47
+ The `## Parts (build order)` heading and the `N. <leaf> — <one-line scope>` item shape together are the **roster contract**: `pwk-finalizing` and `pwk-status` both read them, and both are lint-pinned so a drifted heading fails loudly instead of reading an empty roster. Goal, parts with one-line scopes, build order — **no status column**. No skill mutates the overview between this write and `pwk-finalizing` (which disposes it); part-completion is inferred from each leaf's own `*-progress.md`.
48
+ 3. **Write the first part's design doc** — `docs/plans/<date>-<topic>/<leaf>-design.md` in the same folder, then hand off to `/skill:pwk-executing-tasks`.
47
49
 
48
- **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.
50
+ **Later parts** — re-run `/skill:pwk-brainstorming` for the next part. Read the overview for big-picture/roster context (which slice is yours, which siblings exist), then report each prior leaf's `Feature phase:` line (matched header-only — `grep -m1 '^Feature phase:' <leaf>-progress.md` beside the overview — no body ingest; a leaf with no progress file yet reports `not started`) before designing the slice, then explore the codebase to design your slice **as brainstorm always does** — prior parts are just implemented code in the repo by then. Predecessor phases are visibility, not enforcement: design the slice regardless; cross-slice decisions that must persist go in an ADR, not the overview.
49
51
 
50
- The whole umbrella is one branch and one PR: `pwk-executing-tasks` creates the branch in its pre-flight and reuses it for later parts, and suggests the next part (or finalize after the last); `pwk-finalizing` disposes the overview + every part's docs and ships one PR.
52
+ The whole umbrella is one branch and one PR: `pwk-executing-tasks` creates the branch in its pre-flight and reuses it for later parts, and suggests the next part (or finalize after the last); `pwk-finalizing` disposes the whole folder — overview + every leaf — and ships one PR.
51
53
 
52
54
  ## Process
53
55
 
54
56
  1. **Check git state** — `git status` + `git log --oneline -5`. Uncommitted work? Ask the user what to do first.
55
- 2. **Discovery** *(skip in a brand-new repo with no `docs/plans/`)* — first verify the repo root: run `pwd` (or your shell's equivalent) and `git rev-parse --show-toplevel`; mismatch → report both paths and stop; never `cd` (a worktree root counts). Then list `docs/plans` recursively, excluding docs/plans/completed/, for `*-design.md` and `overview.md` (each umbrella lives in its own `docs/plans/<date>-<umbrella>/` folder — archived work is not in flight). Use whatever recurses in your harness; one example: `find docs/plans -name '<suffix>' -not -path '*/completed/*'`; report in-flight topics and any active umbrella. 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)).
56
- 3. **Understand the idea** — read only enough code/docs/commits to ground the design. **Check `docs/lessons.md`** — known constraints may shape it. Ask questions in **frontier rounds**: build a question tree seeded by the dimension checklist, then ask in rounds. The **frontier** is every question whose prerequisites are already settled — ask the whole frontier in one round; a question whose answer depends on another still-open question waits for a later round. Number each question (`Q1`, `Q2`, …) and attach your recommended answer (`➡️ <recommendation>`) — the recommendation is your assumption surfaced up front; the human confirms, strikes, or corrects each in one reply. Recompute the frontier after each round of answers. Seed the tree by walking every checklist dimension — *Goal & scope · Data & state · Behavior & edge cases · Errors & failure · Integration · Non-functional* — printing `— nothing to ask` for groups with no questions (never skip silently). **Facts vs. decisions**: anything answerable from the codebase, docs, or tools is looked up — recon scout or inline — never asked of the human; a pending lookup is an unsettled prerequisite that holds only its downstream questions, while the rest of the frontier is asked now. Only decisions are asked. Major approvals stay single-decision — one question each, never batched: approach selection (step 5), umbrella split, design approval, ADR unlock. The interview ends when the frontier is empty — every branch visited, nothing left silently assumed — not when you feel you understand. Then present a short summary and ask: "Should I proceed, or is there more?" The human decides when to move on.
57
+ 2. **Discovery** *(skip in a brand-new repo with no `docs/plans/`)* — first verify the repo root: run `pwd` (or your shell's equivalent) and `git rev-parse --show-toplevel`; mismatch → report both paths and stop; never `cd` (a worktree root counts). Then list `docs/plans` recursively, excluding docs/plans/completed/, for `*-design.md`, `*-progress.md`, and `overview.md` (topic docs live in `docs/plans/<date>-<topic>/` folders — archived work is not in flight). Use whatever recurses in your harness; one example: `find docs/plans -name '<suffix>' -not -path '*/completed/*'`; report in-flight topics and any active umbrella. For each in-flight topic with a progress file, report its `Feature phase:` line (matched header-only — `grep -m1 '^Feature phase:' <file>` — no body ingest); design-only topics report `design`. If the new idea continues an existing topic, ask whether to extend it or start fresh. Part of an umbrella? An existing `overview.md` **beside the design doc** means the split is already decided — read it for the roster and design this part's `<leaf>-design.md` against it (see [Umbrella](#umbrella)).
58
+ 3. **Understand the idea** — read only enough code/docs/commits to ground the design. **Check `docs/lessons.md`** — known constraints may shape it. Ask questions in **frontier rounds**: build a question tree seeded by the dimension checklist, then ask in rounds. The **frontier** is every question whose prerequisites are already settled — ask the whole frontier in one round; a question whose answer depends on another still-open question waits for a later round. Number each question (`Q1`, `Q2`, …) and attach your recommended answer (`➡️ <recommendation>`) — the recommendation is your assumption surfaced up front; the human confirms, strikes, or corrects each in one reply. Recompute the frontier after each round of answers. Seed the tree by walking every checklist dimension — *Goal & scope · Data & state · Behavior & edge cases · Errors & failure · Integration · Non-functional* — printing `— nothing to ask` for groups with no questions (never skip silently). **Facts vs. decisions**: anything answerable from the codebase, docs, or tools is looked up — recon scout or inline — never asked of the human; a pending lookup is an unsettled prerequisite that holds only its downstream questions, while the rest of the frontier is asked now. Only decisions are asked. Major approvals stay single-decision — one question each, never batched: approach selection (step 5), umbrella split, design approval, ADR offer. The interview ends when the frontier is empty — every branch visited, nothing left silently assumed — not when you feel you understand. Then present a short summary and ask: "Should I proceed, or is there more?" The human decides when to move on.
57
59
  4. **(skipped on trivial changes)** **Codebase recon** — for non-trivial topics with prior art, request the host’s `codebase-recon` capability using the logical `pwk-recon-scout` role. Require a fresh-context, read-only, bounded worker and pass the topic, one-line intent, and repo root. Use the returned 5-section codebase map (Relevant files, Existing patterns, Call sites, Test layout, Gotchas) as the grounding context for the next two steps instead of reading those files inline. The scout is observations only — no design recommendations. Skip this step on trivial changes (typo, version bump, single-function edit per the proportionality rule). If no compatible capability is available or the provider cannot enforce the requested constraints, report `Scout: unavailable` and do the same recon inline, preserving the five-section map and `file:line` citations; do not silently omit recon.
58
60
  5. **Explore approaches** — propose 2–3, leading with your recommendation. Sketch the concrete interface (types, signatures, example caller) for each so the comparison is grounded in code, not abstractions.
59
61
  6. **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.
60
62
 
61
63
  **Assumptions to confirm first** — before presenting, sweep the drafted design: every assumption it would bake in unconfirmed (business rules, defaults, edge-case resolutions) re-opens as a numbered question carrying your recommended answer; the human confirms, strikes, or corrects each in one reply. An honest empty gate ("no unconfirmed assumptions") when the draft is clean — never invent items. Hard rule: no business behavior enters the design doc on the agent's assumption. Confirmed facts are woven into the doc's existing sections — no new template section.
62
64
 
63
- 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.)
64
- 7. **Write the design doc** — `docs/plans/YYYY-MM-DD-<topic>-design.md`, descriptive (not a task list). This is the single artifact the executor builds from.
65
+ Identified a significant architectural decision? Offer an ADR in `docs/adr/`. Only when all three hold: **hard to reverse**, **surprising without context**, **a real trade-off**. Format: title + 1–3 sentences of context/decision/why. ADRs are permanent institutional memory — they stay out of archive/rotation forever. (Guard note: `docs/adr/` is outside the writable `docs/plans/`; the human writes the approved ADR themselves or briefly runs `/pwk-guard off` — the agent never writes it while the design phase is gated.)
66
+ 7. **Write the design doc** — `docs/plans/<date>-<topic>/<leaf>-design.md`, creating the topic folder when absent (`<leaf>` is `<topic>` for a single-part topic — the everyday case), descriptive (not a task list). This is the single artifact the executor builds from.
65
67
 
66
68
  **Open with `## At a glance`** — the human's two-minute digest, immediately before `## Requirements`. It contains (1) a 2–4 sentence plain-language summary: what is wrong or needed, what will be built, the key approach in plain words; (2) **Key decisions** — one line each: decision + why, with a `(rejected: <alternative> — <reason>)` clause only when the fork was real and load-bearing (never manufactured — no fork, no clause); (3) a table `| R# | Requirement in one line | Risk |` with exactly one row per requirement, where **R# = the requirement's block number in the `## Requirements` section below** — this ID is what every later digest keys on (progress rows, execution summary, reviewer coverage table). Plain language only: short sentences, no jargon, no Given/When/Then — those live in the requirement blocks for the executor. An umbrella overview gains no at-a-glance section; its roster already serves that role.
67
69
 
@@ -91,14 +93,14 @@ The whole umbrella is one branch and one PR: `pwk-executing-tasks` creates the b
91
93
 
92
94
  - **No test-name lists.** The criteria are the test spec — the executor writes and names the actual tests red-green from them, so the doc contains no test-name lists and no R#-to-section mapping tables: the block structure is the map.
93
95
  - **Tag every requirement** — `### Checkpoints` (how many human stops: `none` = no per-requirement stop, the default — the feature gate covers it; `full` = tests + complete stops) and `### Review` (per-requirement review: `skip` = none, the default; `parallel` = four delegated reviewers; `inline` = one `pwk-code-review` pass). Missing tags default to `none` / `skip`. Flag `full` only where complex logic or the main part of the feature makes a human look at the slice worth the stop.
94
- - **Nothing is tagged silently here; only the human tags a slice for review.** A requirement that touches a production-risk area is flagged in the At-a-glance risk column and carries its `### Production-risk notes`, but its written `### Review` value stays `skip` unless the human sets it — propose the tag in prose, leave the field at `skip`. An explicit human tag always wins, in both directions.
95
- - **No per-requirement spec stop, by design** — the acceptance criteria are approved right here, at design time; re-checking them mid-execution asks a question the human already answered. A legacy `spec` tag in an in-flight design doc resolves to `none`.
96
+ - **Nothing is tagged silently here; only the human tags a slice for review.** A requirement that touches a production-risk area carries its `### Production-risk notes` in the block and is flagged `⚠ production-risk` in the At-a-glance Risk column (the column is derived, **display-only**: `⚠ production-risk` if and only if the block carries non-empty `### Production-risk notes`, else `—` — never normative, never an input; `auto` reads the underlying risk content — the `## Production-risk areas` section and the notes — never the display column), but its written `### Review` value stays `skip` unless the human sets it — propose the tag in prose, leave the field at `skip`. An explicit human tag always wins, in both directions.
97
+ - **No per-requirement spec stop, by design** — the acceptance criteria are approved right here, at design time; re-checking them mid-execution asks a question the human already answered.
96
98
  - **Production-risk notes** — a requirement touching a production-risk area carries its notes inside the block. Risks involving schema migrations, new dependencies, external APIs, or seed data also get a `## Setup` section (dependencies, migrations, seed data, and how to verify setup worked) between `## Requirements` and `## Feature acceptance`.
97
99
  - **Ordering** — dependencies come earlier in the list; the executor runs blocks in listed order with no dependency graph. Aim for vertical slices that merge cleanly on their own.
98
100
 
99
- Then the narrative sections the executor reads as context — problem, approaches considered, architecture, components, data flow, error handling. **Approaches considered records every real fork and why each loser lost** — the executor needs the reasoning, and the finalize learning sweep harvests it for ADRs.
101
+ Then the narrative sections the executor reads as context — problem, approaches considered, architecture, components, data flow, error handling. Head the approaches section exactly `## Approaches considered` — finalizing's learning sweep reads it by that name. **`## Approaches considered` records every real fork and why each loser lost** — the executor needs the reasoning, and the finalize learning sweep harvests it for ADRs.
100
102
 
101
- Touches a production-risk area (DB schema/migrations, auth, external APIs, concurrency/batch, uploads/large data flows, Redis/caching/queues)? Add a brief `## Production-risk areas` **immediately after the last requirement block** — inside the `### R1 → ## Feature acceptance` span, so the review packet carries it to reviewers verbatim — and mirror the risks into each touched block's `### Production-risk notes`. `pwk-code-review` audits it per requirement, and finalize's learning sweep reads it.
103
+ Touches a production-risk area (DB schema/migrations, auth, external APIs, concurrency/batch, uploads/large data flows, Redis/caching/queues)? Add a brief `## Production-risk areas` **immediately after the last requirement block** — inside the `### R1 → ## Feature acceptance` span, so the review packet carries it to reviewers verbatim — and mirror the risks into each touched block's `### Production-risk notes`. `pwk-code-review` audits it, per requirement when the slice is reviewed and at the feature review always; finalize's learning sweep reads it.
102
104
 
103
105
  **End with `## Feature acceptance`** — one or more end-to-end `Given/When/Then` scenarios proving the requirements *compose* into the feature. This is the feature's definition-of-done; the human approves it as what "the feature works" means. `pwk-executing-tasks` writes it as the E2E test first and runs it as the **primary enforced spec** (the test it gates on first). The section carries the feature-level `### Feature review: auto | parallel | inline` tag — the one whole-feature review; default `auto`, which resolves on the design's own production-risk content to `parallel` (all four reviewers) when the design has any — a non-empty `## Production-risk areas` section, or a non-empty `### Production-risk notes` on any requirement — and to `inline` (one pass) otherwise. An explicit `parallel` or `inline` is written as-is, never resolved, so the human always overrides `auto`. Treat "I can write this scenario" as the green light to finish designing — if you can't, keep designing because the requirements don't yet compose into a coherent feature. If writing a scenario step would require inventing behavior, that invention goes back through the assumption gate — it may never be silently written into the scenario; an unwritable step means an unspecified requirement, so keep designing.
104
106
 
@@ -106,13 +108,15 @@ The whole umbrella is one branch and one PR: `pwk-executing-tasks` creates the b
106
108
  ## Feature acceptance
107
109
 
108
110
  - Given <starting state>, When <trigger>, Then <end-to-end outcome the feature promises>.
111
+
112
+ ### Feature review: auto | parallel | inline — the one whole-feature review; leave `auto` unless the human says otherwise.
109
113
  ```
110
114
 
111
115
  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."
112
116
 
113
- **Audit before finishing:** every requirement block has acceptance criteria and both tags, and each requirement appears **exactly once** — none dropped, none duplicated. A `## Feature acceptance` section exists as the primary enforced spec. Production-risk areas are reflected in the requirement blocks that touch them.
117
+ **Audit before finishing:** every requirement block has acceptance criteria and both tags, and each requirement appears **exactly once** — none dropped, none duplicated. A `## Feature acceptance` section exists as the primary enforced spec — on every non-trivial doc; a trivial doc ends after its `### R1:` block and ships on the full suite instead. Production-risk areas are reflected in the requirement blocks that touch them.
114
118
 
115
- **Splitting large issues:** if the requirement needs more than one design doc, propose an umbrella split (one `<topic>` per part) and get human approval first — see [Umbrella](#umbrella). On approval, write the status-free overview (`docs/plans/<date>-<umbrella>/overview.md`) and the **first part's** `-design.md` beside it, then hand off to `/skill:pwk-executing-tasks`. Later parts are brainstormed one by one (each re-reading the overview) — do not write every part's design doc up front.
119
+ **Splitting large issues:** if the requirement needs more than one design doc, propose an umbrella split (one `<topic>` per part) and get human approval first — see [Umbrella](#umbrella). On approval, write the status-free overview (`docs/plans/<date>-<topic>/overview.md`) and the **first part's** `-design.md` beside it, then hand off to `/skill:pwk-executing-tasks`. Later parts are brainstormed one by one (each re-reading the overview) — do not write every part's design doc up front.
116
120
 
117
121
  The session stays read-only and uncommitted through brainstorm: branch creation and the design-doc commit happen at the start of `pwk-executing-tasks` (its pre-flight creates the feature branch).
118
122