@tianhai/pi-workflow-kit 1.6.1 → 1.8.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 (11) hide show
  1. package/README.md +11 -11
  2. package/agents/pwk-spec-reviewer.md +9 -1
  3. package/docs/developer-usage-guide.md +7 -7
  4. package/docs/oversight-model.md +3 -3
  5. package/docs/workflow-phases.md +10 -9
  6. package/package.json +1 -1
  7. package/skills/pwk-brainstorming/SKILL.md +14 -9
  8. package/skills/pwk-executing-tasks/SKILL.md +52 -21
  9. package/skills/pwk-finalizing/SKILL.md +14 -7
  10. package/skills/pwk-status/SKILL.md +2 -2
  11. package/skills/pwk-writing-plans/SKILL.md +13 -5
package/README.md CHANGED
@@ -63,7 +63,7 @@ Guide the agent through a disciplined development process:
63
63
 
64
64
  ```
65
65
  brainstorm → writing-plans → executing-tasks → finalizing
66
- (feature-gate: write feature E2E → feature-spec → implement → feature-complete → review)
66
+ (feature-gate: write feature E2E → feature-spec → implement → review → ship checkpoint)
67
67
  ↕
68
68
  diagnose (anytime) · status (anytime)
69
69
  ```
@@ -72,11 +72,11 @@ A **design doc is one PR**; a **requirement is one testable slice within it**. A
72
72
 
73
73
  | Phase | Trigger | What Happens |
74
74
  |-------|---------|--------------|
75
- | **Brainstorm** | `/skill:pwk-brainstorming` | Explore approaches, produce a design doc with a `## Requirements` list. On non-trivial topics, requests the logical `codebase-recon` capability; if unavailable or unsafe, performs the `pwk-recon-scout` role inline. |
76
- | **Plan** | `/skill:pwk-writing-plans` | Turn each requirement into **acceptance criteria + integration tests** — a behavioral spec (no implementation code) |
77
- | **Execute** | `/skill:pwk-executing-tasks` | Write the feature E2E (red) → **checkpoint: feature-spec** → implement requirements → **checkpoint: feature-complete** → feature review |
75
+ | **Brainstorm** | `/skill:pwk-brainstorming` | Explore approaches, produce a design doc opening with a `## At a glance` digest (plain summary + `| R# | Requirement in one line | Risk |` table) before the `## Requirements` list. Interviews in **frontier rounds**: numbered questions each with a recommended answer, facts looked up rather than asked, an assumption gate before the design is presented. On non-trivial topics, requests the logical `codebase-recon` capability; if unavailable or unsafe, performs the `pwk-recon-scout` role inline. |
76
+ | **Plan** | `/skill:pwk-writing-plans` | Turn each requirement into **acceptance criteria + integration tests** — a behavioral spec (no implementation code), with a `## Crosswalk` proving every R# is covered; you review a one-line confirmation, not the full plan |
77
+ | **Execute** | `/skill:pwk-executing-tasks` | Write the feature E2E (red) → **checkpoint: feature-spec** → implement requirements → feature review → **ship checkpoint** (execution summary + code digest + coverage table; full diff on request) |
78
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. |
79
- | **Finalize** | `/skill:pwk-finalizing` | Delete consumed plan docs, update README/CHANGELOG, create PR |
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 |
80
80
  | **Diagnose** | `/skill:pwk-diagnose` | Debugging loop: reproduce → hypothesise → instrument → fix → cleanup. **Exits the gated phase** (debugging writes tests/instrumentation) |
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
 
@@ -89,7 +89,7 @@ You control each phase — the agent never advances on its own. Invoke a skill t
89
89
  ```
90
90
  /skill:pwk-brainstorming → discuss and design (lists Requirements)
91
91
  /skill:pwk-writing-plans → turn each Requirement into acceptance criteria + integration tests
92
- /skill:pwk-executing-tasks → feature-gate flow: E2E-first, implement, feature review (two checkpoints)
92
+ /skill:pwk-executing-tasks → feature-gate flow: E2E-first, implement, review, ship checkpoint
93
93
  /skill:pwk-code-review → auto-runs at the feature level inside executing-tasks; also invocable manually for ad-hoc reviews
94
94
  /skill:pwk-finalizing → ship it
95
95
  ```
@@ -105,8 +105,8 @@ The feature is implemented via the feature-gate flow:
105
105
  1. Write the feature-acceptance E2E test (red)
106
106
  2. ⏸ **checkpoint: feature-spec** — you confirm the E2E proves the feature
107
107
  3. Implement the requirements back-to-back (TDD: meaningful test → red → green per slice; full autonomy)
108
- 4. ⏸ **checkpoint: feature-complete** — full suite + feature E2E green, you review the whole diff
109
- 5. Feature review → commit
108
+ 4. Feature review (four fresh-context roles over a script-assembled review packet)
109
+ 5. ⏸ **ship checkpoint** — full suite + feature E2E green; you review the execution summary + coverage table (full diff on request)
110
110
 
111
111
  Per-requirement checkpoints/reviews are opt-in (default off); the feature-level review covers everything.
112
112
 
@@ -136,13 +136,13 @@ The feature-gate flow has **two hard human-review gates** (not optional):
136
136
  | Checkpoint | What's done | What you review |
137
137
  |---|---|---|
138
138
  | **feature-spec** | Feature-acceptance E2E written, confirmed failing | Does the E2E actually prove the feature? |
139
- | **feature-complete** | All requirements implemented; full suite + E2E green | Is the whole feature correct before review? |
139
+ | **ship** | All requirements implemented; full suite + E2E green; feature review collected | Execution summary + per-requirement coverage table — built as promised? (full diff on request) |
140
140
 
141
141
  The agent stops and waits at each — approve, request changes, or send it back.
142
142
 
143
- ### Before You Ship: the Feature-Complete Gate
143
+ ### Before You Ship: the Ship Gate
144
144
 
145
- The feature-level review checks the whole diff composed. The **feature-complete** checkpoint already ran the full suite + the feature-acceptance E2E green — that *is* the integration check (there is no separate end pass). Finalize re-runs the full suite too — it never ships a red suite, even across resumed sessions.
145
+ The feature-level review checks the whole diff composed and runs **before** the **ship checkpoint** — so your one final approval is fully informed (execution summary + coverage table; the raw diff stays one command away). The ship checkpoint already ran the full suite + the feature-acceptance E2E green — that *is* the integration check (there is no separate end pass). Finalize re-runs the full suite too — it never ships a red suite, even across resumed sessions.
146
146
 
147
147
  ## Quick Start
148
148
 
package/agents/pwk-spec-reviewer.md CHANGED
@@ -26,4 +26,12 @@ The task provides a review packet: the diff under review plus the acceptance cri
26
26
 
27
27
  ### Spec alignment
28
28
 
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.
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
+
31
+ **Open the report with a coverage table** — one row per requirement, keyed by the packet's `## Requirement N` headings (R# = N):
32
+
33
+ | R# | Verdict | Evidence |
34
+ |----|---------|----------|
35
+ | 1 | <verdict> | file:line (code), file:line (test) |
36
+
37
+ Verdict per requirement: `covered | gap | scope-creep` — `covered` = every criterion has covering code and a test; `gap` = a criterion lacks code or a test; `scope-creep` = the code does more than the criteria specify. Findings elaborate on every non-`covered` row; an all-`covered` table still ends with the explicit `No findings` line.
package/docs/developer-usage-guide.md CHANGED
@@ -52,9 +52,9 @@ The command creates `.agents/agents/` and installs the five PWK roles. It preser
52
52
  /skill:pwk-brainstorming
53
53
  ```
54
54
 
55
- Explore the idea through collaborative dialogue. The agent reads code, asks questions, proposes approaches, and presents the design for your review. 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.
55
+ 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
56
 
57
- 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).
57
+ Outcome: `docs/plans/YYYY-MM-DD-<topic>-design.md` — descriptive, opening with a `## At a glance` digest for the human (plain-language summary + `| R# | Requirement in one line | Risk |` table) immediately before the `## 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).
58
58
 
59
59
  ### 2. Plan
60
60
 
@@ -62,7 +62,7 @@ Outcome: `docs/plans/YYYY-MM-DD-<topic>-design.md` — descriptive, opening with
62
62
  /skill:pwk-writing-plans
63
63
  ```
64
64
 
65
- Read the design doc's Requirements and turn each into **acceptance criteria + integration-test cases** — a behavioral spec (no implementation code).
65
+ Read the design doc's Requirements and turn each into **acceptance criteria + integration-test cases** — a behavioral spec (no implementation code). The plan carries a `## Crosswalk` (one row per design requirement); you review a **one-line confirmation** ("Plan covers R1–R<N>; tags: …") — the full plan is available on request.
66
66
 
67
67
  Outcome: `docs/plans/YYYY-MM-DD-<topic>-implementation.md`.
68
68
 
@@ -72,11 +72,11 @@ Outcome: `docs/plans/YYYY-MM-DD-<topic>-implementation.md`.
72
72
  /skill:pwk-executing-tasks
73
73
  ```
74
74
 
75
- Implement via the **feature-gate flow** with full autonomy: write the feature-acceptance E2E test (red) → **checkpoint: feature-spec** → implement the requirements back-to-back → **checkpoint: feature-complete** (full suite + E2E green) → feature review. Two mandatory checkpoints at the feature level. Per-requirement checkpoints/reviews are opt-in (default off).
75
+ Implement via the **feature-gate flow** with full autonomy: write the feature-acceptance E2E test (red) → **checkpoint: feature-spec** → 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 mandatory checkpoints at the feature level. Per-requirement checkpoints/reviews are opt-in (default off).
76
76
 
77
77
  ### 4. Code review (feature level)
78
78
 
79
- The `pwk-executing-tasks` skill requests the `parallel-review` capability for four logical roles over the whole feature diff: spec alignment, code tracing, code smells, and production hazards. The scope is a script-assembled review packet (diff + acceptance criteria verbatim) handed to every role via a one-liner pointer — the packet never rides in spawn arguments. The roles are independent, fresh-context, read-only reporters; the main agent collects their results, applies smell fixes itself, runs the tests, and flags other findings for the human.
79
+ The `pwk-executing-tasks` skill requests the `parallel-review` capability for four logical roles over the whole feature diff: spec alignment, code tracing, code smells, and production hazards. The scope is a script-assembled review packet (diff + acceptance criteria verbatim) handed to every role via a one-liner pointer — the packet never rides in spawn arguments. The roles are independent, fresh-context, read-only reporters; the main agent collects their results, applies smell fixes itself, runs the tests, and flags other findings for the human. The review runs before the ship checkpoint, so your final approval is fully informed: execution summary, per-requirement coverage table, findings status, full diff on request.
80
80
 
81
81
  In Pi, `/pwk-setup` installs the canonical role definitions into `.agents/agents/`, where compatible providers such as `@tintinweb/pi-subagents` can discover them. `/pwk-setup --fast-model <model>` (or the interactive picker) sets the fast-tier model for the smell/hazard reviewers — an advisory hint hosts may honor. Tintinweb may run the roles through its native `Agent` mechanism or map recon to its built-in read-only `Explore` type. The core kit does not require Tintinweb or any other provider.
82
82
 
@@ -88,7 +88,7 @@ In Pi, `/pwk-setup` installs the canonical role definitions into `.agents/agents
88
88
  /skill:pwk-finalizing
89
89
  ```
90
90
 
91
- **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.
91
+ **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.
92
92
 
93
93
  ### Diagnose (on demand)
94
94
 
@@ -126,6 +126,6 @@ Plans specify *what* (acceptance criteria + integration tests); the executor wri
126
126
 
127
127
  - Start with brainstorming for anything non-trivial.
128
128
  - The plan is a behavioral spec, not an implementation recipe — let the executor choose how.
129
- - The feature-gate flow has two checkpoints by default (feature-spec + feature-complete): use them to steer the E2E spec and the finished implementation.
129
+ - The feature-gate flow has two checkpoints by default (feature-spec + ship): use them to steer the E2E spec and to sign off the finished implementation (digest + coverage, diff on request).
130
130
  - **Right-size each requirement at plan time** with the `### Checkpoints` (`none`/`full`/`spec`, default `none`) and `### Review` (`skip`/`parallel`/`inline`, default `skip`) tags — per-requirement ceremony is opt-in. The always-on feature-level `### Feature review` covers the whole diff. `spec` keeps the cheap spec-correctness gate and drops the complete checkpoint (covered by review), so it requires at least `inline` review. A trivial fix can also use the brainstorming trivial fast-path (one-turn brainstorm, minimal design doc). Production-risk requirements are auto-tagged `### Review: parallel` by `pwk-writing-plans`; the human can override or downgrade before plan approval.
131
131
  - Put all plan artifacts under `docs/plans/`; ADRs under `docs/adr/`.
package/docs/oversight-model.md CHANGED
@@ -6,9 +6,9 @@
6
6
 
7
7
  Skills teach the agent the workflow. There are 5 pipeline skills:
8
8
 
9
- - **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). 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-writing-plans** — turn each requirement into acceptance criteria + integration-test cases (a behavioral spec, no implementation code)
11
- - **pwk-executing-tasks** — feature-gate flow: write the feature E2E first, implement the requirements, then one feature-level review; two mandatory checkpoints at the feature level, per-requirement ceremony opt-in
9
+ - **pwk-brainstorming** — explore ideas, produce a descriptive design doc that opens with a `## At a glance` digest for the human (plain-language summary + a `| R# | Requirement in one line | Risk |` table) immediately before the `## 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). 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-writing-plans** — turn each requirement into acceptance criteria + integration-test cases (a behavioral spec, no implementation code); carries a `## Crosswalk` (R# → section → tests) and presents a one-line coverage confirmation instead of the full plan
11
+ - **pwk-executing-tasks** — feature-gate flow: write the feature E2E first, implement the requirements, then one feature-level review before the **ship checkpoint** (execution summary + coverage table presented for approval; full diff on request); two mandatory checkpoints (feature-spec + ship), per-requirement ceremony opt-in
12
12
  - **pwk-code-review** — the inline reviewer (code tracing, spec alignment, code smells, production hazards). During `pwk-executing-tasks`, the feature-level review requests the `parallel-review` capability for four logical fresh-context, read-only roles; 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`.
13
13
  - **pwk-finalizing** — dispose consumed plan docs (archive or delete; for an umbrella, the overview + every part), curate lessons, update docs, create PR or merge
14
14
 
package/docs/workflow-phases.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  ```
6
6
  brainstorm → writing-plans → executing-tasks → finalizing
7
- (feature-gate: write feature E2E → ⏸ feature-spec → implement requirements → ⏸ feature-complete → feature review)
7
+ (feature-gate: write feature E2E → ⏸ feature-spec → implement requirements → feature review → ⏸ ship)
8
8
  ```
9
9
 
10
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 → plan → execute) × N → finalize`).
@@ -15,9 +15,9 @@ A design doc is one PR; a requirement is one testable slice within it. A require
15
15
  /skill:pwk-brainstorming
16
16
  ```
17
17
 
18
- - Explore requirements and shape the design.
19
- - 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).
20
- - 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.
18
+ - 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, opening with a `## At a glance` digest for the human (2–4 sentence plain-language summary + a `| R# | Requirement in one line | Risk |` table, one row per requirement) immediately before the `## 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).
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
21
  - ADRs go to `docs/adr/` (permanent, never archived).
22
22
 
23
23
  Write boundary: only `docs/plans/` is writable. Source files are hard-blocked.
@@ -29,8 +29,8 @@ Write boundary: only `docs/plans/` is writable. Source files are hard-blocked.
29
29
  ```
30
30
 
31
31
  - Creates the feature branch first (`git checkout -b <topic>`), so design + plan docs live on the branch, not `main`.
32
- - 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.
33
- - 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.
32
+ - 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. Emits a `## Crosswalk` (R# → plan section → tests) after `## Overview` — the audit checks every design R# appears exactly once, and the human is shown a **one-line confirmation** ("Plan covers R1–R<N>; tags: …"), not the full plan.
33
+ - For an umbrella part, reads the umbrella folder's `overview.md` to plan one slice (composing with earlier parts' code) and reuses the existing feature branch instead of creating a new one.
34
34
  - Derives a **`## Feature acceptance` section** in the plan from the design's Feature acceptance — the **primary enforced spec**, an end-to-end test the executor gates on first. If the design has none, stops and asks the human to brainstorm one.
35
35
  - Tags the plan: per-requirement `### Checkpoints`/`### Review` default to `none`/`skip` (opt-in), plus an always-on feature-level `### Feature review`. Flags only requirements with complex logic, the main part of the feature, or production-risk. Requirements with `### Production-risk notes` are auto-tagged `### Review: parallel` (see `pwk-writing-plans` for the rule).
36
36
  - Produce `docs/plans/YYYY-MM-DD-<topic>-implementation.md`.
@@ -43,9 +43,10 @@ Write boundary: only `docs/plans/` is writable.
43
43
  /skill:pwk-executing-tasks
44
44
  ```
45
45
 
46
- - **Feature-gate flow:** write the feature-acceptance E2E test (red) → **⏸ checkpoint: feature-spec** (human confirms the E2E proves the feature) → implement the requirements back-to-back with full autonomy (the executor chooses structure/signatures/internals) → **⏸ checkpoint: feature-complete** (full suite + feature E2E green) → **feature review** (request the `parallel-review` capability for four logical read-only roles when the host supports it; otherwise run `/skill:pwk-code-review` inline — see [code-review](#code-review)).
46
+ - **Feature-gate flow:** write the feature-acceptance E2E test (red) → **⏸ checkpoint: feature-spec** (human confirms the E2E proves the feature) → implement the requirements back-to-back with full autonomy (the executor chooses structure/signatures/internals) → **feature review** (request the `parallel-review` capability for four logical read-only roles when the host supports it; otherwise run `/skill:pwk-code-review` inline — see [code-review](#code-review)) → **⏸ checkpoint: ship** (full suite + feature E2E green; present the execution summary + code digest + reviewer coverage table; full diff on request).
47
+ - 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.
47
48
  - Per-requirement checkpoints/reviews are **opt-in** — they fire only for requirements the plan tags (default off); see [Proportionality](#proportionality).
48
- - **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 `feature-complete` (the old integration gate folds into it).
49
+ - **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).
49
50
  - Progress tracked in `docs/plans/*-progress.md` (feature phase + requirement checklist).
50
51
 
51
52
  No write restrictions. All tools available.
@@ -79,7 +80,7 @@ No write restrictions.
79
80
  ```
80
81
 
81
82
  - **Pre-check: run the full test suite** — don't ship a red suite (resume spans sessions; don't trust the last execute session).
82
- - 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**.
83
+ - 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**.
83
84
  - Curate `docs/lessons.md`, update README/CHANGELOG, create PR or merge.
84
85
 
85
86
  No write restrictions.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tianhai/pi-workflow-kit",
3
- "version": "1.6.1",
3
+ "version": "1.8.0",
4
4
  "description": "Enforce structured brainstorm→plan→execute→finalize workflow with TDD discipline in AI coding agents",
5
5
  "keywords": [
6
6
  "pi-package",
package/skills/pwk-brainstorming/SKILL.md CHANGED
@@ -11,7 +11,7 @@ Read-only exploration of source code; every file you create or edit goes under `
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 (one-line context, a `## Requirements` list with the single requirement, optional `## Production-risk areas` line), and hand off to `/skill:pwk-writing-plans`. The guard still enforces read-only — trivial compresses the phase to one turn, it doesn't skip it.
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, a `## Requirements` list with the single requirement, optional `## Production-risk areas` line), and hand off to `/skill:pwk-writing-plans`. The guard still enforces read-only — trivial compresses the phase to one turn, it doesn't skip it.
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.
@@ -30,7 +30,7 @@ An umbrella splits one large requirement into multiple design docs that ship tog
30
30
  **First brainstorm** (the requirement is too big for one design doc):
31
31
 
32
32
  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/YYYY-MM-DD-<umbrella>-overview.md`, a **status-free roster**:
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>-implementation.md`, `<part>-progress.md`, `*-review-packet.md`), a **status-free roster**:
34
34
 
35
35
  ```markdown
36
36
  # Overview: <umbrella>
@@ -43,7 +43,7 @@ An umbrella splits one large requirement into multiple design docs that ship tog
43
43
  ```
44
44
 
45
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** `YYYY-MM-DD-<part>-design.md`, then hand off to `/skill:pwk-writing-plans`.
46
+ 3. **Write the first part's** `<part>-design.md` in the same umbrella folder, then hand off to `/skill:pwk-writing-plans`.
47
47
 
48
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.
49
49
 
@@ -52,18 +52,22 @@ The whole umbrella is one branch and one PR: `pwk-writing-plans` creates the bra
52
52
  ## Process
53
53
 
54
54
  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/`)* — 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)).
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 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.
55
+ 2. **Discovery** *(skip in a brand-new repo with no `docs/plans/`)* — glob `docs/plans/**/*-design.md` and `docs/plans/**/overview.md` (recursive — each umbrella lives in its own `docs/plans/<date>-<umbrella>/` folder, excluding docs/plans/completed/ — archived work is not in flight); 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
57
  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
58
  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
59
  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
60
 
61
+ **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
+
61
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.)
62
- 7. **Write the design doc** — `docs/plans/YYYY-MM-DD-<topic>-design.md`, descriptive (not a task list). **Open with `## Requirements`** — one testable behavior each; `pwk-writing-plans` derives acceptance criteria and tests from these. Then: problem, approaches considered, architecture, components, data flow, error handling, testing.
64
+ 7. **Write the design doc** — `docs/plans/YYYY-MM-DD-<topic>-design.md`, descriptive (not a task list). **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) a table `| R# | Requirement in one line | Risk |` with exactly one row per requirement, where **R# = the requirement's number in the `## Requirements` list below** — this ID is what every later digest keys on (plan crosswalk, progress rows, reviewer coverage table). Plain language only: short sentences, no jargon, no Given/When/Then — those live in the body sections for the executor. An umbrella overview gains no at-a-glance section; its roster already serves that role.
65
+
66
+ Then **`## Requirements`** — one testable behavior each; `pwk-writing-plans` derives acceptance criteria and tests from these. Then: problem, approaches considered, architecture, components, data flow, error handling, testing.
63
67
 
64
68
  Touches a production-risk area (DB schema/migrations, auth, external APIs, concurrency/batch, uploads/large data flows, Redis/caching/queues)? Add a brief `## Production-risk areas` — `pwk-writing-plans` carries it into the plan and `pwk-code-review` audits it per requirement.
65
69
 
66
- **End with `## Feature acceptance`** — one or more end-to-end `Given/When/Then` scenarios proving the requirements *compose* into the feature. This is the feature's definition-of-done; the human approves it as what "the feature works" means. `pwk-writing-plans` derives a feature-level test from it; `pwk-executing-tasks` runs it as the **primary enforced spec** (the test it gates on first). 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.
70
+ **End with `## Feature acceptance`** — one or more end-to-end `Given/When/Then` scenarios proving the requirements *compose* into the feature. This is the feature's definition-of-done; the human approves it as what "the feature works" means. `pwk-writing-plans` derives a feature-level test from it; `pwk-executing-tasks` runs it as the **primary enforced spec** (the test it gates on first). 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.
67
71
 
68
72
  ```markdown
69
73
  ## Feature acceptance
@@ -73,13 +77,14 @@ The whole umbrella is one branch and one PR: `pwk-writing-plans` creates the bra
73
77
 
74
78
  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."
75
79
 
76
- **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.
80
+ **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-writing-plans`. Later parts are brainstormed one by one (each re-reading the overview) — do not write every part's design doc up front.
77
81
 
78
82
  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`.
79
83
 
80
84
  ## Principles
81
85
 
82
- - One question at a time
86
+ - Detail-gathering asks in frontier rounds; approvals ask one decision at a time
87
+ - No silent assumptions — ask, gate, or look it up
83
88
  - YAGNI — remove unnecessary features
84
89
  - Design for testability
85
90
  - Explore alternatives before settling
package/skills/pwk-executing-tasks/SKILL.md CHANGED
@@ -7,19 +7,19 @@ description: "Implement a plan via the feature-gate flow: write the feature-acce
7
7
 
8
8
  Implement the plan from `docs/plans/*-implementation.md` via the **feature-gate flow**. The plan is a behavioral spec (acceptance criteria + integration tests) — you choose structure, signatures, internals; the criteria define *what*, you decide *how*.
9
9
 
10
- The feature-acceptance E2E test is the primary enforced gate and the primary enforced spec for the feature. The flow is always on: write the E2E first (red), implement the requirements back-to-back, then run one feature-level review over the whole diff. Per-requirement checkpoints and reviews are **opt-in** — they fire only for requirements the plan tags (default off); the feature gate covers everything else.
10
+ The feature-acceptance E2E test is the primary enforced gate and the primary enforced spec for the feature. The flow is always on: write the E2E first (red), implement the requirements back-to-back, then run the feature review and pause at the **ship checkpoint** — one fully-informed stop where you present the execution summary and the reviewer coverage table, with the full diff on request. Per-requirement checkpoints and reviews are **opt-in** — they fire only for requirements the plan tags (default off); the feature gate covers everything else.
11
11
 
12
12
  ## Before you start
13
13
 
14
14
  1. **Git state** — `git status` + `git log --oneline -5`; note uncommitted changes.
15
- 2. **Find the plan** — glob `docs/plans/*-implementation.md`; if several, ask which. Report one line, e.g. `Found: design "auth" — feature-gate execute (feature-spec done, implementing 2/5)`. A matching `*-progress.md` means this is a **resume** (see [Resume](#resume)).
15
+ 2. **Find the plan** — glob `docs/plans/**/*-implementation.md` (recursive — umbrella parts live in `docs/plans/<date>-<umbrella>/` folders, excluding docs/plans/completed/ — archived plans are not pending work); if several, ask which. Report one line, e.g. `Found: design "auth" — feature-gate execute (feature-spec done, implementing 2/5)`. A matching `*-progress.md` means this is a **resume** (see [Resume](#resume)).
16
16
  3. **Workspace** — `pwk-writing-plans` already created the branch/worktree. If you're still on `main`, tell the user the workspace wasn't set up and suggest fixing that before executing.
17
17
 
18
18
  ## First run
19
19
 
20
20
  1. **Parse the plan** — read every `## Requirement N:` heading and its `### Checkpoints` / `### Review` tags (defaults `none` / `skip`), plus the feature-level `### Feature review` tag. Requirements run in **listed order** (build order); do not reorder. Read the `## Feature acceptance` section — it is the E2E you gate on first.
21
21
  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.
22
- 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):
22
+ 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; an umbrella part creates `<part>-progress.md` inside its `docs/plans/<date>-<umbrella>/` folder):
23
23
 
24
24
  ```markdown
25
25
  # Progress: <topic>
@@ -34,13 +34,29 @@ The feature-acceptance E2E test is the primary enforced gate and the primary enf
34
34
  | # | Done | Requirement | Per-req ceremony | Commit |
35
35
  |---|------|-------------|-----------------|--------|
36
36
  | 1 | ⬜ | <requirement name> | — | — |
37
+
38
+ ## Execution summary
39
+ | R# | Requirement | How it was built | Deviated? |
40
+ |----|-------------|------------------|-----------|
41
+ | 1 | <requirement name> | | |
42
+
43
+ ## Code digest
44
+
45
+ <!-- Written once, after the feature review passes; never back-filled per requirement. -->
46
+
47
+ ### Summary — 2–3 sentences: what the code now does differently, and why.
48
+ ### Flow — execution/data movement through the changed code, as arrow chains.
49
+ ### Gotchas — edge cases, implicit assumptions; [ALERT]-prefixed real risks.
50
+ ### Key files — 3–5 pivotal files, one line each: what shifted inside them.
37
51
  ```
38
52
 
39
- `Feature phase` is one of: `e2e-written`, `feature-spec-paused`, `implementing (k/N)`, `feature-complete-paused`, `reviewing`, `done`.
53
+ The `## Code digest` is filled once, at the write point in the ship checkpoint — never per requirement. Fill rules: plain language, R# anchors where natural, no test names (the execution-summary rule). `### Flow` uses `A -> B -> C` arrow chains. `### Gotchas` lifts real risks from the review findings — `[ALERT]` only for reviewer-confirmed issues, never invented; with no findings, write `none beyond review findings` and mean it. `### Key files` is capped at 5 pivotal files, one line each: what shifted inside them.
54
+
55
+ `Feature phase` is one of: `e2e-written`, `feature-spec-paused`, `implementing (k/N)`, `reviewing`, `ship-paused`, `done`.
40
56
 
41
57
  4. **Commit the plan docs** — `git add docs/plans/ && git commit -m "docs: add implementation plan"`.
42
58
  5. **Write the feature-acceptance E2E test (red).** Read the plan's `## Feature acceptance` section and encode it as a real test file; run it; confirm it **fails** (it must — little or none of the feature exists yet). If it passes immediately, the behavior may already exist or the test is wrong — investigate before proceeding.
43
- 6. **⏸ CHECKPOINT: feature-spec** — set `Feature phase: feature-spec-paused`, present the E2E test + failing output, and wait. This is where the human confirms the E2E actually proves the feature (the definition of done). **request changes** → revise, re-run, re-present.
59
+ 6. **⏸ CHECKPOINT: feature-spec** — set `Feature phase: feature-spec-paused`, lead with 1–2 plain-language lines stating **what the E2E proves** ("this test proves that …"), then present the E2E test + failing output, and wait. This is where the human confirms the E2E actually proves the feature (the definition of done). **request changes** → revise, re-run, re-present.
44
60
 
45
61
  ## Resume
46
62
 
@@ -48,13 +64,16 @@ Read the progress file's `Feature phase`:
48
64
  - `e2e-written` → write the E2E if not yet present, then present the **feature-spec** checkpoint.
49
65
  - `feature-spec-paused` → re-present the feature-spec checkpoint and wait.
50
66
  - `implementing (k/N)` → continue the next not-yet-✅ requirement.
51
- - `feature-complete-paused` → re-present the feature-complete checkpoint and wait.
52
- - `reviewing` → continue/finish the feature review.
67
+ - `reviewing` → continue/finish the feature review, then assemble the **ship** checkpoint.
68
+ - `ship-paused` → re-present the ship checkpoint and wait.
69
+ - legacy `feature-complete-paused` (a progress file from before the ship gate) → treat as `reviewing`: finish the feature review, then present the ship checkpoint.
53
70
 
54
71
  ## Progress file
55
72
 
56
73
  Update the matching requirement row directly (not via pattern matching that could corrupt the table). Update `Last updated` and `Feature phase` on every change. The `Per-req ceremony` column records a requirement's tagged checkpoint/review status when it has one (e.g. `⏸ tests`, `🔎 inline`); leave `—` for default (`none`/`skip`) requirements.
57
74
 
75
+ **Execution summary rows are written in the same step as marking a requirement ✅** — never retrofitted at the end. "How it was built" = one or two plain sentences: what it does now + the approach actually taken; file names sparingly; **no test names, no code** (the human reads this at the ship checkpoint — big picture only). If the implementation departs from the plan, fill the Deviated? column when the departure happens, with a one-line why — it is a log, not a stop.
76
+
58
77
  ## Implement phase (after feature-spec is approved)
59
78
 
60
79
  Set `Feature phase: implementing (0/N)` and work the requirements in listed order. For each:
@@ -62,9 +81,9 @@ Set `Feature phase: implementing (0/N)` and work the requirements in listed orde
62
81
  1. **Mark the requirement 🔄** (Done column) and read its `### Checkpoints` / `### Review` tags.
63
82
  2. **Write a meaningful test (red), then implement (green)** — TDD discipline. Encode the requirement's acceptance criteria as a real test through the public interface; run it; confirm it fails; implement to green. Skip the per-slice test only when the slice has no independent observable behavior (the feature E2E covers it). Follow the meaningful-test rules: (1) **Test observable behavior** — assert on what the feature produces or changes (a return value, persisted/updated data, an emitted event, an HTTP response) through its public interface; these assertions keep passing as the implementation changes. (2) **Write a per-slice test when the slice has its own observable behavior** — when a slice is pure config or a trivial extraction, the feature E2E covers it and a per-slice test is unnecessary. (Mirrored in `pwk-writing-plans` and `docs/lessons.md`.)
64
83
  3. **⏸ per-requirement checkpoint** *(fires only when the tag says so — opt-in)* — if `### Checkpoints: full` or `spec`, stop and present per the tag (`full` = after tests and after complete; `spec` = after tests only). With the default `none`, show the red→green inline and proceed.
65
- 4. **Regression check after each commit** — run the **full existing suite**. This is what catches cross-requirement regressions (a later requirement breaking an earlier one's test). The **feature E2E stays red until the last requirement lands**; you may run it to watch the failure point advance, but it is gated only at `feature-complete` — never expect it green per-commit.
84
+ 4. **Regression check after each commit** — run the **full existing suite**. This is what catches cross-requirement regressions (a later requirement breaking an earlier one's test). The **feature E2E stays red until the last requirement lands**; you may run it to watch the failure point advance, but it is gated only at the ship checkpoint — never expect it green per-commit.
66
85
  5. **Learn.** Caught a repeat mistake? Append a **generic** rule to `docs/lessons.md` (strip domain specifics).
67
- 6. **Commit** the requirement with a clear message; mark its row ✅; advance `Feature phase: implementing (k/N)`.
86
+ 6. **Commit** the requirement with a clear message; mark its row ✅ and write its execution-summary row in the same step; advance `Feature phase: implementing (k/N)`.
68
87
 
69
88
  ### Per-requirement review (opt-in)
70
89
 
@@ -79,24 +98,36 @@ When a per-requirement checkpoint fires it is a **hard stop**:
79
98
  - **Never** `git add` or `git commit` before approval at a checkpoint.
80
99
  - Set the progress phase/status **before** pausing.
81
100
 
82
- ## Feature-complete checkpoint
101
+ ## Ship checkpoint (feature-complete + review, merged)
83
102
 
84
103
  When every requirement's Done column is ✅:
85
104
 
86
105
  1. **Run the FULL test suite** — a failure means one requirement regressed another; fix it now, in execute context.
87
106
  2. **Run the feature-acceptance E2E** — the test you wrote at the start. It must be **green** now that all requirements have landed. If it is still red, a requirement is missing or wrong — fix it before proceeding. (If the plan declared no feature E2E — a pure refactor — gate on the full suite staying green instead.)
88
- 3. **Set `Feature phase: feature-complete-paused`** and **⏸ CHECKPOINT: feature-complete** — present the green full suite + green feature E2E + the whole diff (`git diff <merge-base>...HEAD`), and wait for approval.
107
+ 3. **Run the feature review** (below) per the plan's `### Feature review` tag — set `Feature phase: reviewing` first, so a mid-review resume routes into this step instead of the implement loop. The review runs **before** your final approval, so the pause is fully informed. Apply smell fixes yourself and re-green (full suite + E2E) before pausing.
108
+ 4. **Write the code digest** into the progress file — the review has succeeded, findings are fixed, and the code is final: read the packet's `## Commits`, `## Changed files`, and `## Diff` sections and fill the progress file's `## Code digest` (template above) per the fill rules. If the packet is stale or missing, re-run the recipe before writing. A resumed `Feature phase: reviewing` that completes lands on this same write point before the checkpoint is assembled. Written once — never rewritten per requirement, never a gate: it explains the change, it does not block shipping.
109
+ 5. **Set `Feature phase: ship-paused`** and **⏸ CHECKPOINT: ship** — present, in this order:
110
+ - a green-gates line: full suite green, feature E2E green;
111
+ - the **execution summary** — what each requirement became, deviations included;
112
+ - the **code digest** — the plain-language change explanation from the progress file (summary, flow, gotchas, key files);
113
+ - the **coverage table** from the spec-reviewer report (one verdict row per R#);
114
+ - findings status: fixed / open for the human;
115
+ - "full diff on request" — the raw diff is one command away; show a hunk only where a verdict or finding makes the human ask.
116
+
117
+ Wait for approval. **request changes** → fix, re-run the gates (and the review if the change is substantive), re-present.
118
+
119
+ A reviewer report without a per-requirement coverage table is invalid — retry the role or complete it inline before pausing; the ship checkpoint is never presented without coverage.
89
120
 
90
- The old "integration gate" is gone — the feature E2E at `feature-complete` *is* the gate; there is no separate end pass.
121
+ The old "integration gate" is gone — the feature E2E at the ship checkpoint *is* the gate; there is no separate end pass.
91
122
 
92
123
  ## Feature review
93
124
 
94
- After `feature-complete` is approved, run **one** review over the **whole feature diff**, driven by the plan's feature-level `### Feature review` tag. This is the single thorough review — per-requirement reviews, if any, only saw slices in isolation.
125
+ This is step 3 of the [ship checkpoint](#ship-checkpoint-feature-complete--review-merged): it runs **before** the final human approval, so the pause is fully informed. Run **one** review over the **whole feature diff**, driven by the plan's feature-level `### Feature review` tag. This is the single thorough review — per-requirement reviews, if any, only saw slices in isolation.
95
126
 
96
127
  **Assemble the review packet first** — once, by script, so that no packet byte passes through model output (spawn arguments are model output; file reads are not). If commits land while the review is in flight, re-run the recipe before spawning any replacement role so the packet matches HEAD:
97
128
 
98
129
  ```bash
99
- PACKET="docs/plans/<dated-stem>-review-packet.md" # same dated stem as the plan docs
130
+ PACKET="<plan doc's directory>/<plan doc's stem>-review-packet.md" # beside the plan doc — flat topic: docs/plans/<dated-stem>-review-packet.md; umbrella part: inside the docs/plans/<date>-<umbrella>/ folder
100
131
  {
101
132
  echo "# Review packet: <topic> — feature review"
102
133
  echo
@@ -107,13 +138,13 @@ PACKET="docs/plans/<dated-stem>-review-packet.md" # same dated stem as the pla
107
138
  git diff --stat <merge-base>...HEAD
108
139
  echo
109
140
  echo "## Acceptance criteria (verbatim from the plan)"
110
- sed -n '/^## Requirement 1/,/^## Feature acceptance/p' docs/plans/<dated-stem>-implementation.md | sed '/^## Feature acceptance/,$d'
141
+ sed -n '/^## Requirement 1/,/^## Feature acceptance/p' <plan-doc path> | sed '/^## Feature acceptance/,$d'
111
142
  echo
112
143
  echo "## Feature acceptance (verbatim)"
113
- sed -n '/^## Feature acceptance/,/^### Feature review/p' docs/plans/<dated-stem>-implementation.md | sed '/^### Feature review/,$d'
144
+ sed -n '/^## Feature acceptance/,/^### Feature review/p' <plan-doc path> | sed '/^### Feature review/,$d'
114
145
  echo
115
146
  echo "## Production-risk notes (verbatim, if any)"
116
- sed -n '/^### Production-risk notes/,/^## /p' docs/plans/<dated-stem>-implementation.md | sed '/^## /d'
147
+ sed -n '/^### Production-risk notes/,/^## /p' <plan-doc path> | sed '/^## /d'
117
148
  echo
118
149
  echo "## Diff"
119
150
  git diff <merge-base>...HEAD
@@ -125,7 +156,7 @@ PACKET="docs/plans/<dated-stem>-review-packet.md" # same dated stem as the pla
125
156
  - **`inline`** — perform `/skill:pwk-code-review` over the whole diff as a single pass.
126
157
  - **Fallback** — if the host has no compatible parallel-review capability, cannot prove the requested read-only/fresh-context/bounded constraints, or delegation fails, perform the missing review work inline. Retain successful delegated reports and do not mark the feature fully reviewed while a required role is missing.
127
158
 
128
- On success, set `Feature phase: done`.
159
+ On success, continue assembling the ship checkpoint; once the human approves it, set `Feature phase: done`.
129
160
 
130
161
  ## Tags reference
131
162
 
@@ -150,10 +181,10 @@ Verify the criticism against the code, evaluate the suggestion, then implement (
150
181
 
151
182
  ## After the feature review
152
183
 
153
- The feature is implemented and reviewed. Determine the next step from the artifacts (the human drives every transition — this is a suggestion, not a gate):
184
+ The feature is implemented, reviewed, and approved at the ship checkpoint. Determine the next step from the artifacts (the human drives every transition — this is a suggestion, not a gate; both overview checks below run excluding docs/plans/completed/ — an archived umbrella never routes):
154
185
 
155
- - **Standalone design doc** (no `docs/plans/*-overview.md`) → suggest `/skill:pwk-finalizing`.
156
- - **Umbrella part** (an `*-overview.md` exists) → read the overview roster and find this part's `<topic>`. If it is 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).
186
+ - **Standalone design doc** (no `docs/plans/**/overview.md` exists) → suggest `/skill:pwk-finalizing`.
187
+ - **Umbrella part** (a `docs/plans/**/overview.md` exists) → read the overview roster and find this part's `<topic>`. If it is 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).
157
188
 
158
189
  Present:
159
190
 
package/skills/pwk-finalizing/SKILL.md CHANGED
@@ -10,26 +10,29 @@ Ship the completed work.
10
10
  ## Pre-finalization checks
11
11
 
12
12
  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`.
13
- 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:
13
+ 2. Read **every** relevant progress file — for an umbrella that's each part's `docs/plans/**/*-progress.md` (recursive — umbrella docs live in `docs/plans/<date>-<umbrella>/` folders, excluding docs/plans/completed/ — archived parts are already shipped); for a standalone design doc, the one:
14
14
  - **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.
15
15
  - **Only `⏭ skipped`** → warn and confirm ("Requirement N was skipped. Continue, or go back?").
16
+ - **`Feature phase` must be `done`** in every progress file — any other value (`e2e-written`, `feature-spec-paused`, `implementing (k/N)`, `reviewing`, `ship-paused`, or a legacy `feature-complete-paused` from before the ship gate) means the feature is still in flight: the ship checkpoint has not been approved. Send the user back to `/skill:pwk-executing-tasks` instead of finalizing.
16
17
 
17
18
  ## Process
18
19
 
19
20
  1. **Derive the topic set** —
20
- - **Umbrella** (a `docs/plans/*-overview.md` exists): read its roster; the set is every part's `<topic>`. The overview is disposed too.
21
+ - **Umbrella** (a `docs/plans/**/overview.md` exists — excluding docs/plans/completed/, so an archived umbrella is never the one being finalized): read its roster; the set is every part's `<topic>`. The umbrella folder is disposed too.
21
22
  - **Standalone**: progress file → `Plan:` ref → plan's `Design:` ref → design-doc filename → `<topic>`. One topic.
22
23
 
23
24
  Ambiguous with several designs in flight? Ask.
24
- 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:
25
+ 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, dispose the whole `docs/plans/<date>-<umbrella>/` folder — overview + every part — as one unit. Standalone topics keep the per-file paths. The digest sections (`## At a glance`, `## Crosswalk`, `## Execution summary`) live inside their host docs and ride the same globs — no separate disposal. Each path is matched with the `????-??-??-` prefix. Present both options and let the human choose:
25
26
 
26
27
  - **Delete (default)** — code + tests are the source of truth; removing the scaffold prevents stale plan docs from misleading future sessions:
27
28
 
28
29
  ```bash
29
30
  # for each <topic> in the set:
30
31
  rm -f docs/plans/????-??-??-<topic>-design.md docs/plans/????-??-??-<topic>-implementation.md docs/plans/????-??-??-<topic>-progress.md docs/plans/????-??-??-<topic>-review-packet*.md
31
- # umbrella only:
32
- rm -f docs/plans/????-??-??-<umbrella>-overview.md
32
+ # umbrella only — the whole folder goes as one unit (overview + every part).
33
+ # The folder path is taken verbatim from the discovered docs/plans/**/overview.md
34
+ # result — never typed or reconstructed (rm -rf has no dated-glob guard):
35
+ rm -rf docs/plans/<date>-<umbrella>/
33
36
  git add -A docs/plans/ && git commit -m "chore: delete planning docs for <topic-or-umbrella>"
34
37
  ```
35
38
 
@@ -42,8 +45,12 @@ Ship the completed work.
42
45
  mv docs/plans/????-??-??-<topic>-implementation.md docs/plans/completed/ 2>/dev/null || true
43
46
  mv docs/plans/????-??-??-<topic>-progress.md docs/plans/completed/ 2>/dev/null || true
44
47
  mv docs/plans/????-??-??-<topic>-review-packet*.md docs/plans/completed/ 2>/dev/null || true
45
- # umbrella only:
46
- mv docs/plans/????-??-??-<umbrella>-overview.md docs/plans/completed/ 2>/dev/null || true
48
+ # umbrella only — the whole folder goes as one unit (overview + every part).
49
+ # No error suppression on the folder move: verify the archive landed before
50
+ # committing, or a silently failed move would commit the deletion and destroy
51
+ # the history the human chose to keep:
52
+ mv docs/plans/<date>-<umbrella>/ docs/plans/completed/
53
+ ls docs/plans/completed/<date>-<umbrella>/ >/dev/null
47
54
  git add docs/plans/ && git commit -m "chore: archive planning docs for <topic-or-umbrella>"
48
55
  ```
49
56
 
package/skills/pwk-status/SKILL.md CHANGED
@@ -9,9 +9,9 @@ Report on in-flight pipelines in this working tree (a worktree has its own `docs
9
9
 
10
10
  ## Process
11
11
 
12
- 1. Glob `docs/plans/*-overview.md`, `*-design.md`, `*-implementation.md`, `*-progress.md` — this working tree only.
12
+ 1. Glob `docs/plans/**/*-design.md`, `docs/plans/**/*-implementation.md`, `docs/plans/**/*-progress.md`, and `docs/plans/**/overview.md` (recursive — umbrella docs live in `docs/plans/<date>-<umbrella>/` folders, excluding docs/plans/completed/ — archived topics are not in flight) — this working tree only.
13
13
  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`.
14
- 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.
14
+ 3. **Group by umbrella** — for each umbrella `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 folder — overview included — is disposed, so it no longer appears here. Topics not part of an overview print flat.
15
15
  4. Print a compact table, grouped under any umbrellas, e.g.:
16
16
 
17
17
  ```
package/skills/pwk-writing-plans/SKILL.md CHANGED
@@ -15,10 +15,11 @@ Your writes go into `docs/plans/` and nowhere else. Source code and configuratio
15
15
 
16
16
  ## Process
17
17
 
18
- 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.
18
+ 1. **Find the design doc** — glob `docs/plans/**/*-design.md` (recursive — umbrella docs live in `docs/plans/<date>-<umbrella>/` folders, excluding docs/plans/completed/ — archived designs are not plannable). 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 a `docs/plans/**/overview.md` exists (excluding docs/plans/completed/ — an archived umbrella is never the umbrella being planned) 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.
19
19
  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`.
20
- 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.
20
+ 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. A requirement whose testable acceptance criteria cannot be derived without inventing behavior is bounced back to `/skill:pwk-brainstorming` naming the specific gap — never plan on an assumption.
21
21
  4. **Write the plan** — for each requirement:
22
+ - **Crosswalk** — immediately after `## Overview`, emit `## Crosswalk`: a table `| R# | Plan section | Tests |` with one row per design requirement (R# = the design's numbering from its at-a-glance `## Requirements` list; Tests = that requirement's test names from the plan). Placement is load-bearing: the crosswalk sits strictly before `## Requirement 1` (between `## Overview` and `## Setup`, if present) so the review-packet sed spans (`## Requirement 1` → `## Feature acceptance` → `### Feature review`) stay untouched.
22
23
  - **Acceptance criteria** — `Given/When/Then` behavioral statements defining "done". Write observable behaviors, not implementation steps; cover edge and error cases.
23
24
  - **Integration tests** — test name + what each asserts. This is the spec the executor writes tests from.
24
25
  - **Meaningful tests** — write acceptance criteria and tests as observable behavior: (1) **Test observable behavior** — assert on what the feature produces or changes (a return value, persisted/updated data, an emitted event, an HTTP response) through its public interface; these assertions keep passing as the implementation changes. (2) **Write a per-slice test when the slice has its own observable behavior** — when a slice is pure config or a trivial extraction, the feature E2E covers it and a per-slice test is unnecessary.
@@ -31,14 +32,20 @@ Your writes go into `docs/plans/` and nowhere else. Source code and configuratio
31
32
  - **Challenge the design first** *(if production-risk areas exist)* — stress-test the design against the flagged risks before writing criteria. If a risk invalidates a design choice, stop and return to `/skill:pwk-brainstorming` rather than planning around a flawed design.
32
33
  - **Ordering** — dependencies come **earlier** in the list; the executor runs in listed order with no dependency graph. Aim for vertical slices that merge cleanly on their own.
33
34
 
34
- Save to `docs/plans/YYYY-MM-DD-<topic>-implementation.md`:
35
+ Save to `docs/plans/YYYY-MM-DD-<topic>-implementation.md` (an umbrella part saves into its umbrella folder as `<part>-implementation.md`):
35
36
 
36
37
  ```markdown
37
38
  # Implementation Plan: <topic>
38
39
 
39
40
  ## Overview
40
41
  Design: docs/plans/YYYY-MM-DD-<topic>-design.md
41
- Umbrella: docs/plans/YYYY-MM-DD-<umbrella>-overview.md *(umbrella part only — else omit)*
42
+ Umbrella: docs/plans/<date>-<umbrella>/overview.md *(umbrella part only — else omit)*
43
+
44
+ ## Crosswalk
45
+
46
+ | R# | Plan section | Tests |
47
+ |----|--------------|-------|
48
+ | 1 | Requirement 1: <name> | `<test name> …` |
42
49
 
43
50
  ## Requirement 1: <name>
44
51
 
@@ -72,13 +79,14 @@ Your writes go into `docs/plans/` and nowhere else. Source code and configuratio
72
79
 
73
80
  5. **Audit before presenting:**
74
81
  - Every requirement has criteria **and** matching tests, a checkpoint tag, a review tag.
82
+ - The `## Crosswalk` covers every design requirement R# exactly once — none dropped, none duplicated.
75
83
  - No `spec` + `skip` combination.
76
84
  - A `## Feature acceptance` section exists as the primary enforced spec (or the trivial-fold note).
77
85
  - A feature-level `### Feature review` tag is present.
78
86
  - Per-requirement tags default to `none` / `skip`; only requirements with complex logic, the main part of the feature, or production-risk are flagged heavier.
79
87
  - Production-risk areas from the design are reflected.
80
88
  6. **Workspace isolation** — you're on the `<topic>` branch. For larger work, offer a worktree (`git worktree add ../<repo>-<topic> <topic>`) and hand off to a new session there so `pwd` is the worktree. Wait for the user's choice.
81
- 7. **Present the plan** and wait for approval. On approval, hand off: "Ready to execute? Run `/skill:pwk-executing-tasks`" (running it is what exits the gated plan phase).
89
+ 7. **Present the plan** — the human reads a **one-line confirmation**, not the full plan: `Plan covers R1–R<N>; tags: <non-default tags>` plus the feature-acceptance test name. The full plan is available on request. Wait for approval. On approval, hand off: "Ready to execute? Run `/skill:pwk-executing-tasks`" (running it is what exits the gated plan phase).
82
90
 
83
91
  ## What belongs in the plan — and what stays out
84
92