@tianhai/pi-workflow-kit 1.2.0 → 1.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 (11) hide show
  1. package/README.md +27 -25
  2. package/agents/pwk-recon-scout.md +68 -0
  3. package/docs/developer-usage-guide.md +7 -7
  4. package/docs/oversight-model.md +2 -2
  5. package/docs/workflow-phases.md +13 -12
  6. package/package.json +1 -2
  7. package/skills/pwk-brainstorming/SKILL.md +6 -5
  8. package/skills/pwk-code-review/SKILL.md +2 -2
  9. package/skills/pwk-executing-tasks/SKILL.md +92 -76
  10. package/skills/pwk-writing-plans/SKILL.md +16 -7
  11. package/docs/lessons.md +0 -15
package/README.md CHANGED
@@ -1,6 +1,6 @@
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 per-requirement code review.
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.
4
4
 
5
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.
6
6
 
@@ -20,7 +20,7 @@ No setup needed — skills and guards activate automatically after install.
20
20
  pi -e npm:@tianhai/pi-workflow-kit
21
21
  ```
22
22
 
23
- **Optional — parallel code review.** Per-requirement review can run four specialized reviewers in parallel via the `subagent` tool. Install [`pi-subagents`](https://pi.dev/packages/pi-subagents) to enable it:
23
+ **Optional — parallel code review.** The feature-level review can run four specialized reviewers in parallel over the whole feature diff via the `subagent` tool. Install [`pi-subagents`](https://pi.dev/packages/pi-subagents) to enable it:
24
24
 
25
25
  ```bash
26
26
  pi install npm:pi-subagents
@@ -49,7 +49,7 @@ Guide the agent through a disciplined development process:
49
49
 
50
50
  ```
51
51
  brainstorm → writing-plans → executing-tasks → finalizing
52
- (per requirement: tests → checkpoint → implement → checkpoint → code-review)
52
+ (feature-gate: write feature E2E → feature-spec → implement → feature-complete → review)
53
53
  ↕
54
54
  diagnose (anytime) · status (anytime)
55
55
  ```
@@ -58,10 +58,10 @@ A **design doc is one PR**; a **requirement is one testable slice within it**. A
58
58
 
59
59
  | Phase | Trigger | What Happens |
60
60
  |-------|---------|--------------|
61
- | **Brainstorm** | `/skill:pwk-brainstorming` | Explore approaches, produce a design doc with a `## Requirements` list |
61
+ | **Brainstorm** | `/skill:pwk-brainstorming` | Explore approaches, produce a design doc with a `## Requirements` list. On non-trivial topics, dispatches the `pwk-recon-scout` agent (read-only) to map the codebase before design. |
62
62
  | **Plan** | `/skill:pwk-writing-plans` | Turn each requirement into **acceptance criteria + integration tests** — a behavioral spec (no implementation code) |
63
- | **Execute** | `/skill:pwk-executing-tasks` | Per requirement: write tests (red) → **checkpoint: tests** → implement (green) → **checkpoint: complete** → code-review |
64
- | **Code review** | `/skill:pwk-code-review` | Per requirement: code tracing, spec alignment, code smells (applies fixes), production hazard check |
63
+ | **Execute** | `/skill:pwk-executing-tasks` | Write the feature E2E (red) → **checkpoint: feature-spec** → implement requirements → **checkpoint: feature-complete** → feature review |
64
+ | **Code review** | `/skill:pwk-code-review` | Feature-level (default) or per-requirement: code tracing, spec alignment, code smells (applies fixes), production hazard check |
65
65
  | **Finalize** | `/skill:pwk-finalizing` | Delete consumed plan docs, update README/CHANGELOG, create PR |
66
66
  | **Diagnose** | `/skill:pwk-diagnose` | Debugging loop: reproduce → hypothesise → instrument → fix → cleanup. **Exits the gated phase** (debugging writes tests/instrumentation) |
67
67
  | **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**. |
@@ -75,8 +75,8 @@ You control each phase — the agent never advances on its own. Invoke a skill t
75
75
  ```
76
76
  /skill:pwk-brainstorming → discuss and design (lists Requirements)
77
77
  /skill:pwk-writing-plans → turn each Requirement into acceptance criteria + integration tests
78
- /skill:pwk-executing-tasks → implement per requirement with two mandatory checkpoints
79
- /skill:pwk-code-review → auto-runs per-requirement inside executing-tasks; also invocable manually for ad-hoc reviews
78
+ /skill:pwk-executing-tasks → feature-gate flow: E2E-first, implement, feature review (two checkpoints)
79
+ /skill:pwk-code-review → auto-runs at the feature level inside executing-tasks; also invocable manually for ad-hoc reviews
80
80
  /skill:pwk-finalizing → ship it
81
81
  ```
82
82
 
@@ -84,15 +84,17 @@ You control each phase — the agent never advances on its own. Invoke a skill t
84
84
 
85
85
  Plans specify *what*, not *how*. For each requirement, the plan gives **acceptance criteria + integration-test cases** — no implementation code, no file-by-file recipe. The executor has full autonomy to choose structure, signatures, and internals. A fine-grained implementation plan invalidates the moment a detail shifts; acceptance criteria + integration tests survive implementation changes.
86
86
 
87
- ### Test-First per Requirement
87
+ ### Feature-Gate Execution
88
88
 
89
- Each requirement is implemented test-first:
89
+ The feature is implemented via the feature-gate flow:
90
90
 
91
- 1. Write the integration tests (red)
92
- 2. ⏸ **checkpoint: tests** — you review the test design
93
- 3. Implement to green (full autonomy)
94
- 4. ⏸ **checkpoint: complete** — you review the implementation
95
- 5. Commit → code review
91
+ 1. Write the feature-acceptance E2E test (red)
92
+ 2. ⏸ **checkpoint: feature-spec** — you confirm the E2E proves the feature
93
+ 3. Implement the requirements back-to-back (TDD: meaningful test → red → green per slice; full autonomy)
94
+ 4. ⏸ **checkpoint: feature-complete** — full suite + feature E2E green, you review the whole diff
95
+ 5. Feature review → commit
96
+
97
+ Per-requirement checkpoints/reviews are opt-in (default off); the feature-level review covers everything.
96
98
 
97
99
  ### Lessons Learned
98
100
 
@@ -111,22 +113,22 @@ Rules are simple imperative bullets:
111
113
  - Never import `testify` in this project
112
114
  - Always check for existing test helpers before writing new ones
113
115
 
114
- No configuration needed — the file ships with starter rules and grows as the agent learns.
116
+ No configuration needed — the agent creates `docs/lessons.md` on first use and it grows as the agent learns.
115
117
 
116
- ### Two Mandatory Checkpoints per Requirement
118
+ ### Two Feature-Level Checkpoints
117
119
 
118
- Each requirement has **two hard human-review gates** (not optional):
120
+ The feature-gate flow has **two hard human-review gates** (not optional):
119
121
 
120
122
  | Checkpoint | What's done | What you review |
121
123
  |---|---|---|
122
- | **tests** | Integration tests written, confirmed failing | Are the right behaviors being specified? |
123
- | **complete** | Implemented, tests green, refactored | Is the implementation correct before committing? |
124
+ | **feature-spec** | Feature-acceptance E2E written, confirmed failing | Does the E2E actually prove the feature? |
125
+ | **feature-complete** | All requirements implemented; full suite + E2E green | Is the whole feature correct before review? |
124
126
 
125
127
  The agent stops and waits at each — approve, request changes, or send it back.
126
128
 
127
- ### Before You Ship: the Integration Gate
129
+ ### Before You Ship: the Feature-Complete Gate
128
130
 
129
- Per-requirement review checks each diff in isolation. Before finalizing, the agent runs an **integration gate**: the **full test suite** (not just the last requirement's) must pass, and it confirms the requirements compose into the feature the design described. Finalize re-runs the full suite too — it never ships a red suite, even across resumed sessions.
131
+ 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.
130
132
 
131
133
  ## Quick Start
132
134
 
@@ -147,7 +149,7 @@ pi install npm:@tianhai/pi-workflow-kit
147
149
 
148
150
  > /skill:pwk-executing-tasks
149
151
 
150
- # (per requirement: writes tests → checkpoint → implements → checkpoint → code-review)
152
+ # (feature-gate: writes feature E2E → checkpoint → implements requirements → checkpoint → feature review)
151
153
 
152
154
  > /skill:pwk-finalizing
153
155
 
@@ -158,7 +160,7 @@ pi install npm:@tianhai/pi-workflow-kit
158
160
 
159
161
  - **AI agents skip design.** Left unchecked, they jump to code and over-engineer. This forces a think-first workflow.
160
162
  - **Specs beat recipes.** Plans are behavioral specs (acceptance criteria + tests), not implementation recipes — they don't invalidate when details change.
161
- - **You stay in control.** Two mandatory checkpoints per requirement let you approve test design and implementation before the agent commits.
163
+ - **You stay in control.** Two feature-level checkpoints let you approve the feature spec (E2E) and the finished implementation before the agent ships.
162
164
  - **Enforced, not suggested.** Hard blocks mean the agent can't ignore the rules — not even accidentally.
163
165
 
164
166
  ## Project
@@ -175,7 +177,7 @@ pi-workflow-kit/
175
177
  │ ├── pwk-finalizing/SKILL.md
176
178
  │ ├── pwk-status/SKILL.md
177
179
  │ └── pwk-diagnose/SKILL.md
178
- ├── agents/ # package agents for parallel code-review (discovered by pi-subagents)
180
+ ├── agents/ # package agents for parallel code-review + recon scout (discovered by pi-subagents)
179
181
  ├── docs/
180
182
  │ ├── developer-usage-guide.md
181
183
  │ ├── workflow-phases.md
package/agents/pwk-recon-scout.md ADDED
@@ -0,0 +1,68 @@
1
+ ---
2
+ name: pwk-recon-scout
3
+ description: Codebase recon scout — maps how a repo handles a topic before design. Produces a 5-section observation report (no recommendations, no design opinion). Read-only reporter.
4
+ tools: read, grep, find, ls, bash
5
+ systemPromptMode: replace
6
+ ---
7
+
8
+ # PWK Recon Scout
9
+
10
+ You are a codebase recon scout dispatched by `pwk-brainstorming` before design work. Your job is to map how a repository handles a topic today so the main agent can design against prior art instead of loading the relevant files into its own context.
11
+
12
+ **You are observations only.** No design recommendations, no preferred-approach opinion, no code beyond one-line excerpts. Every claim must cite a `file:line` so the main agent can drill in if it needs to.
13
+
14
+ ## Tools
15
+
16
+ You inherit the read-only set the workflow-guard already enforces on the brainstorm session: `read, grep, find, ls, bash`. Do not attempt writes or edits — they will be blocked.
17
+
18
+ ## Inputs
19
+
20
+ The main agent dispatches you with three things in the task string:
21
+
22
+ - a `<topic>` (one short phrase, the new feature or change)
23
+ - a one-line `<intent>` (what the new thing does, in plain words)
24
+ - the repo root
25
+
26
+ If any of these is missing, ask for it before proceeding.
27
+
28
+ ## Output — the 5-section codebase map
29
+
30
+ Return a single markdown report with these five sections, in this order. Each section is a short bulleted list (5-10 bullets is the sweet spot; fewer is fine, more is a smell that you did not stay narrow).
31
+
32
+ ### Relevant files
33
+
34
+ Paths that matter for the topic, each with a one-line role. Group by subdirectory if the repo has clear layering; otherwise a flat list is fine.
35
+
36
+ ### Existing patterns
37
+
38
+ How the codebase does similar work today. Cite the file:line for the pattern. Include 2-4 patterns — the new design will compose with these, so the main agent needs to know what conventions are non-negotiable.
39
+
40
+ ### Call sites
41
+
42
+ Where the new behavior would plug in, or which existing wiring it would change. Distinguish **read-side call sites** (consumers of the current behavior) from **write-side call sites** (the functions or entry points that would need updating).
43
+
44
+ ### Test layout
45
+
46
+ Where similar tests live, what harness they use (vitest, jest, go test, etc.), and one or two example test names to mimic. If the codebase has a custom fixture that is painful to build, call it out here so the main agent does not discover it during the planning phase.
47
+
48
+ ### Gotchas
49
+
50
+ Anything that bit a previous change, in this layer of the code or in the topic area specifically. A migrations folder that must run in order, a feature flag that gates the new path, a known deadlock with another subsystem, an environment variable that has to be set, a CI hook that runs before tests. The point is to surface landmines before the main agent commits to a design.
51
+
52
+ ## Hard rules
53
+
54
+ - **Cite a file:line per claim.** No assertions without a citation. The main agent treats your report as a map, not a summary.
55
+ - **Observations only.** No `I recommend`, no `the right approach is`, no `consider doing X`. If you have an opinion, surface it as a neutral fact: e.g. `the codebase has three different error formats` is fine; `the codebase should standardize on one` is not.
56
+ - **Stay narrow.** If the topic is `add OAuth2 login`, do not also report on the entire auth subsystem. Cover the call sites and patterns the new feature will actually touch.
57
+ - **Do not paste code blocks longer than five lines.** One-line excerpts are fine for context. Anything longer means the main agent should read the file itself.
58
+ - **Time-box.** If after 10 tool calls the topic has no prior art in the repo, report that and stop. An empty codebase map is a useful signal: the topic is greenfield.
59
+
60
+ ## When you finish
61
+
62
+ Return the report as your final message. The main agent reads it into its context and uses it as the grounding for the next two brainstorm steps (Explore approaches, Present the design).
63
+
64
+ ## Failure modes
65
+
66
+ - Subagent tool unavailable: the main agent will fall back to inline recon and you will not be invoked. You do not need to handle this case.
67
+ - You return empty: the main agent will treat it as greenfield and proceed with no-prior-art assumptions. Returning a short, honest report is better than padding it.
68
+ - You return a wrong-shaped report: the main agent will downweight the findings but still proceed. Better to ship the 5-section shape than to improvise.
package/docs/developer-usage-guide.md CHANGED
@@ -4,7 +4,7 @@ How to install and use `pi-workflow-kit` with the Pi coding agent.
4
4
 
5
5
  ## What you get
6
6
 
7
- - **5 pipeline skills** — brainstorm → writing-plans → executing-tasks → finalizing, with code-review running per requirement during execution.
7
+ - **5 pipeline skills** — brainstorm → writing-plans → executing-tasks → finalizing, with code-review running at the feature level during execution.
8
8
  - **2 utility skills** — diagnose (debugging) and status (multi-topic overview), both on demand.
9
9
  - **1 extension** — hard-blocks source writes during brainstorm and writing-plans, and blocks destructive bash via a simple common-blacklist.
10
10
 
@@ -44,7 +44,7 @@ You control each phase by invoking the skill. A design doc is one PR; a requirem
44
44
  /skill:pwk-brainstorming
45
45
  ```
46
46
 
47
- Explore the idea through collaborative dialogue. The agent reads code, asks questions, proposes approaches, and presents the design for your review.
47
+ 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 agent dispatches the `pwk-recon-scout` package agent (read-only, fresh context) to map the codebase before design, so the main agent can design against prior art instead of loading files into its own context.
48
48
 
49
49
  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).
50
50
 
@@ -64,11 +64,11 @@ Outcome: `docs/plans/YYYY-MM-DD-<topic>-implementation.md`.
64
64
  /skill:pwk-executing-tasks
65
65
  ```
66
66
 
67
- Implement requirement-by-requirement with **full autonomy**: write the integration tests (red) → **checkpoint: tests** → implement to green → **checkpoint: complete** → commit → code-review. Two mandatory human checkpoints per requirement. After all requirements, an **integration gate** runs the full suite and confirms the requirements compose into the feature before finalize.
67
+ 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).
68
68
 
69
- ### 4. Code review (per requirement)
69
+ ### 4. Code review (feature level)
70
70
 
71
- The `pwk-executing-tasks` skill invokes the `subagent` tool automatically (programmatic, not user-driven). Four specialized reviewers launch in parallel — each reviewing from a different dimension (spec gaps & scope creep, end-to-end code tracing, code smells, production hazards). The reviewers ship as **package agents** (`agents/pwk-*.md`, declared via the `pi-subagents.agents` manifest key) and are discovered natively by the optional **`pi-subagents`** package — no copy step. All report findings only; no agent edits files or produces commits. The main agent collects results, applies smell fixes itself, runs integration tests after each fix, then updates progress to `✅ done`.
71
+ The `pwk-executing-tasks` skill invokes the `subagent` tool automatically at the feature-level review (programmatic, not user-driven). Four specialized reviewers launch in parallel over the whole feature diff — each from a different dimension (spec gaps & scope creep, end-to-end code tracing, code smells, production hazards). A per-requirement review runs the same way for a tagged requirement. The reviewers ship as **package agents** (`agents/pwk-*.md`, declared via the `pi-subagents.agents` manifest key) and are discovered natively by the optional **`pi-subagents`** package — no copy step. All report findings only; no agent edits files or produces commits. The main agent collects results, applies smell fixes itself, runs integration tests after each fix, then updates progress to `✅ done`.
72
72
 
73
73
  *Fallback:* if `pi-subagents` is not installed (so the `subagent` tool is unavailable), the skill falls back to inline `/skill:pwk-code-review` as before. Install it to enable parallel review:
74
74
 
@@ -120,6 +120,6 @@ Plans specify *what* (acceptance criteria + integration tests); the executor wri
120
120
 
121
121
  - Start with brainstorming for anything non-trivial.
122
122
  - The plan is a behavioral spec, not an implementation recipe — let the executor choose how.
123
- - Each requirement has two mandatory checkpoints by default: use them to steer test design and implementation.
124
- - **Right-size each requirement at plan time** with the `### Checkpoints` (`full`/`spec`/`none`) and `### Review` (`parallel`/`inline`/`skip`) tags — defaults are conservative (`full` + `parallel`), so behavior is unchanged unless you opt in. `spec` keeps the cheap spec-correctness gate and drops the complete checkpoint (covered by review), so it's the lowest-iteration option that doesn't sacrifice quality — but it requires at least `inline` review. A trivial fix can also use the brainstorming trivial fast-path (one-turn brainstorm, minimal design doc).
123
+ - The feature-gate flow has two checkpoints by default (feature-spec + feature-complete): use them to steer the E2E spec and the finished implementation.
124
+ - **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.
125
125
  - Put all plan artifacts under `docs/plans/`; ADRs under `docs/adr/`.
package/docs/oversight-model.md CHANGED
@@ -8,8 +8,8 @@ Skills teach the agent the workflow. There are 5 pipeline skills:
8
8
 
9
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)
10
10
  - **pwk-writing-plans** — turn each requirement into acceptance criteria + integration-test cases (a behavioral spec, no implementation code)
11
- - **pwk-executing-tasks** — implement requirement-by-requirement, test-first, with two mandatory human checkpoints per requirement
12
- - **pwk-code-review** — the inline reviewer (code tracing, spec alignment, code smells, production hazards). During `pwk-executing-tasks`, per-requirement review instead runs **four specialized reviewers in parallel** via the `subagent` tool, each from a fresh context (spec gaps & scope creep, tracing, smells, hazards). These ship as package agents (`agents/pwk-*.md`) discovered natively by the optional **`pi-subagents`** package; all report findings only — fixes are applied by the executing-tasks main agent. Falls back to inline `/skill:pwk-code-review` when `pi-subagents` is not installed.
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
12
+ - **pwk-code-review** — the inline reviewer (code tracing, spec alignment, code smells, production hazards). During `pwk-executing-tasks`, the **feature-level review** (the default) runs **four specialized reviewers in parallel** over the whole feature diff via the `subagent` tool, each from a fresh context (spec gaps & scope creep, tracing, smells, hazards); a per-requirement review runs the same way for a tagged requirement. These ship as package agents (`agents/pwk-*.md`) discovered natively by the optional **`pi-subagents`** package; all report findings only — fixes are applied by the executing-tasks main agent. Falls back to inline `/skill:pwk-code-review` when `pi-subagents` is not installed.
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
 
15
15
  Plus 2 on-demand skills:
package/docs/workflow-phases.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  ```
6
6
  brainstorm → writing-plans → executing-tasks → finalizing
7
- (per requirement: tests → ⏸ checkpoint → implement → ⏸ checkpoint → code-review)
7
+ (feature-gate: write feature E2E → ⏸ feature-spec → implement requirements → ⏸ feature-complete → feature review)
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`).
@@ -31,7 +31,8 @@ Write boundary: only `docs/plans/` is writable. Source files are hard-blocked.
31
31
  - Creates the feature branch first (`git checkout -b <topic>`), so design + plan docs live on the branch, not `main`.
32
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
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.
34
- - Derives a **`## Feature acceptance` section** in the plan from the design's Feature acceptance — an end-to-end integration test that exercises the requirements together (distinct from per-requirement tests). If the design has none, stops and asks the human to brainstorm one.
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
+ - 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).
35
36
  - Produce `docs/plans/YYYY-MM-DD-<topic>-implementation.md`.
36
37
 
37
38
  Write boundary: only `docs/plans/` is writable.
@@ -42,22 +43,22 @@ Write boundary: only `docs/plans/` is writable.
42
43
  /skill:pwk-executing-tasks
43
44
  ```
44
45
 
45
- - Per requirement: write the integration tests (red) → **⏸ checkpoint: tests** → implement to green (full autonomy — the executor chooses structure/signatures/internals) → **⏸ checkpoint: complete** → commit → **per-requirement review** (four parallel reviewers via the `subagent` tool; falls back to inline `/skill:pwk-code-review` when `pi-subagents` is absent — see [code-review](#code-review)).
46
- - Two **mandatory** human checkpoints per requirement — unless the plan tags a requirement lighter (see [Proportionality](#proportionality)).
47
- - **Composition check after each commit** — if a requirement touched shared code, the executor runs the full suite now and fixes cross-requirement regressions immediately, rather than discovering them only at the integration gate.
48
- - Progress tracked in `docs/plans/*-progress.md`.
49
- - After all requirements: **integration gate** — run the full suite, **run the feature-acceptance test** (the end-to-end check from the plan's `## Feature acceptance` section), and confirm the requirements compose into the feature before `/skill:pwk-finalizing`.
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** (four parallel reviewers over the whole feature diff via the `subagent` tool; falls back to inline `/skill:pwk-code-review` when `pi-subagents` is absent — see [code-review](#code-review)).
47
+ - 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
+ - Progress tracked in `docs/plans/*-progress.md` (feature phase + requirement checklist).
50
50
 
51
51
  No write restrictions. All tools available.
52
52
 
53
53
  ## Proportionality
54
54
 
55
- The defaults preserve the 1.0.0 behavior (two checkpoints + parallel review per requirement). At plan time the human can tag each requirement lighter to right-size the workflow:
55
+ The **feature-gate flow** is the default: write the feature E2E first, implement the requirements, then one feature-level review. Per-requirement ceremony is opt-in — at plan time the human (or planner) tags only the requirements that need it:
56
56
 
57
- - **Checkpoints** — `full` (both stops, default) | `spec` (tests stop only — cheap spec-correctness gate, implementation covered by review) | `none` (no stops, trivial only). Test-first is preserved either way: even `none` writes tests first (red) and implements to green; only the human *stops* are optional. `spec` requires at least `inline` review (never combine with `skip`).
58
- - **Review** — `parallel` (four fresh-context reviewers, default) | `inline` (single `pwk-code-review` pass) | `skip` (trivial diffs with no behavioral surface only).
57
+ - **Checkpoints** — `none` (no per-requirement stop, **default**) | `full` (both stops) | `spec` (tests stop only — cheap spec-correctness gate, implementation covered by review). Test-first is preserved either way: even `none` writes a meaningful test first (red) and implements to green; only the human *stops* are optional. `spec` requires at least `inline` review (never combine with `skip`).
58
+ - **Review** — `skip` (no per-requirement review, **default**) | `parallel` (four fresh-context reviewers) | `inline` (single `pwk-code-review` pass).
59
+ - **Feature review** — `parallel` (four reviewers over the whole feature diff, **default**) | `inline` (one pass, small features). Always on.
59
60
 
60
- A trivial fix can also skip the multi-turn brainstorm dialogue via the brainstorming trivial fast-path (compress to one turn, minimal design doc) — the guard still enforces read-only. Tags default conservatively, so nothing changes unless the human opts in.
61
+ Flag a requirement for a checkpoint when it has complex logic or is the main part of the feature; for a review when it touches production-risk. A trivial fix can also skip the multi-turn brainstorm dialogue via the brainstorming trivial fast-path (compress to one turn, minimal design doc) — the guard still enforces read-only.
61
62
 
62
63
  ## code-review
63
64
 
@@ -67,7 +68,7 @@ A trivial fix can also skip the multi-turn brainstorm dialogue via the brainstor
67
68
 
68
69
  The **inline reviewer**: code tracing, spec alignment (vs acceptance criteria), code smells (applies fixes), production hazard check. Unlocked — may modify code to fix smells.
69
70
 
70
- **Not a phase you drive manually.** During `pwk-executing-tasks`, per-requirement review runs **four specialized reviewers in parallel** via the `subagent` tool (spec, tracing, smell, hazard — each fresh-context, read-only reporters); this skill is the **fallback** when [`pi-subagents`](https://pi.dev/packages/pi-subagents) is not installed. You can also invoke `/skill:pwk-code-review` standalone for an ad-hoc review of any diff.
71
+ **Not a phase you drive manually.** During `pwk-executing-tasks`, the **feature-level review** (the default) runs **four specialized reviewers in parallel** over the whole feature diff via the `subagent` tool (spec, tracing, smell, hazard — each fresh-context, read-only reporters); a per-requirement review runs the same way for a tagged requirement. This skill is the **fallback** when [`pi-subagents`](https://pi.dev/packages/pi-subagents) is not installed. You can also invoke `/skill:pwk-code-review` standalone for an ad-hoc review of any diff.
71
72
 
72
73
  No write restrictions.
73
74
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tianhai/pi-workflow-kit",
3
- "version": "1.2.0",
3
+ "version": "1.4.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",
@@ -32,7 +32,6 @@
32
32
  "docs/developer-usage-guide.md",
33
33
  "docs/workflow-phases.md",
34
34
  "docs/oversight-model.md",
35
- "docs/lessons.md",
36
35
  "LICENSE",
37
36
  "README.md"
38
37
  ],
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–5; write a **minimal** design doc in one turn (one-line context, a `## Requirements` list with the single requirement, optional `## Production-risk areas` line), and hand off to `/skill:pwk-writing-plans`. The guard still enforces read-only — trivial compresses the phase to one turn, it doesn't skip it.
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.
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.
@@ -54,15 +54,16 @@ The whole umbrella is one branch and one PR: `pwk-writing-plans` creates the bra
54
54
  1. **Check git state** — `git status` + `git log --oneline -5`. Uncommitted work? Ask the user what to do first.
55
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
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.
57
- 4. **Explore approaches** — propose 2–3, leading with your recommendation. Sketch the concrete interface (types, signatures, example caller) for each so the comparison is grounded in code, not abstractions.
58
- 5. **Present the design** in one pass, organized into sections (architecture, components, data flow, error handling, testing) — the human comments on any section; re-present only revised sections.
57
+ 4. **(skipped on trivial changes)** **Codebase recon** — for non-trivial topics with prior art, dispatch the `pwk-recon-scout` package agent (a fresh-context, read-only worker) with the topic, a one-line intent, and the 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 — and stays within the read-only tool set the guard already enforces. Skip this step on trivial changes (typo, version bump, single-function edit per the proportionality rule). If the `subagent` tool is unavailable (e.g. `pi-subagents` is not installed), skip the dispatch, do the recon inline as today, and append the literal line `Scout: unavailable (pi-subagents not installed) — inline recon used.` to the design doc at step 7.
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
+ 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.
59
60
 
60
61
  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.)
61
- 6. **Write the design doc** — `docs/plans/YYYY-MM-DD-<topic>-design.md`, descriptive (not a task list). **Open with `## Requirements`** — one testable behavior each; `pwk-writing-plans` derives acceptance criteria and tests from these. Then: problem, approaches considered, architecture, components, data flow, error handling, testing.
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.
62
63
 
63
64
  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.
64
65
 
65
- **End with `## Feature acceptance`** — one or more end-to-end `Given/When/Then` scenarios proving the requirements *compose* into the feature. This is the feature's definition-of-done; the human approves it as what "the feature works" means. `pwk-writing-plans` derives a feature-level test from it; `pwk-executing-tasks` runs it at the integration gate. Treat "I can write this scenario" as the green light to finish designing — if you can't, keep designing because the requirements don't yet compose into a coherent feature.
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.
66
67
 
67
68
  ```markdown
68
69
  ## Feature acceptance
package/skills/pwk-code-review/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: pwk-code-review
3
- description: "Review a completed requirement's code — trace the logic, check spec alignment against the acceptance criteria, fix code smells, and run a production hazard check. Runs after each requirement in pwk-executing-tasks. Unlocked: may edit code to apply smell fixes."
3
+ description: "Review a completed requirement's code — trace the logic, check spec alignment against the acceptance criteria, fix code smells, and run a production hazard check. Runs as the feature-level review in pwk-executing-tasks (whole feature diff), or per-requirement when tagged. Unlocked: may edit code to apply smell fixes."
4
4
  ---
5
5
 
6
6
  # Code Review
@@ -9,7 +9,7 @@ Review the code just implemented for a requirement. **Unlocked** — you may edi
9
9
 
10
10
  ## Process
11
11
 
12
- 1. **Identify the scope** — the requirement just completed (from the progress file / most recent commit). Read its acceptance criteria and integration tests from the plan doc. Run `git log --oneline -5` and `git diff` to see exactly what changed for this requirement.
12
+ 1. **Identify the scope** — in the feature-gate flow (the default), you review the **whole feature diff** at the feature-level review (`git diff <merge-base>...HEAD`); all acceptance criteria in the plan and the `## Feature acceptance` E2E are in scope. When invoked per-requirement (`Review: inline`/`parallel` on a tagged requirement), scope is just that requirement — read its acceptance criteria and integration tests from the plan doc, run `git log --oneline -5` and `git diff` to see what changed for it.
13
13
 
14
14
  2. **🔍 Code tracing** — trace the new/changed code paths end-to-end against the integration tests. For each path: does data flow correctly from entry to the asserted outcome? Note any branch the tests don't exercise, any dead branch, any path where the trace breaks.
15
15
 
package/skills/pwk-executing-tasks/SKILL.md CHANGED
@@ -1,23 +1,23 @@
1
1
  ---
2
2
  name: pwk-executing-tasks
3
- description: "Implement a plan requirement-by-requirement with test-first discipline and full autonomy. Run after pwk-writing-plans. Each requirement: write integration tests (red) → checkpoint → implement to green → checkpoint → pwk-code-review."
3
+ description: "Implement a plan via the feature-gate flow: write the feature-acceptance E2E first, implement requirements back-to-back, then one feature-level review. Run after pwk-writing-plans. Per-requirement checkpoints/reviews are opt-in (default off)."
4
4
  ---
5
5
 
6
6
  # Executing Tasks
7
7
 
8
- Implement the plan from `docs/plans/*-implementation.md` requirement by requirement, tracking progress in a file.
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 plan is a **behavioral spec** (acceptance criteria + integration tests) — it deliberately contains no implementation steps. You choose structure, signatures, and internals; the criteria define *what*, you decide *how*.
10
+ The feature-acceptance E2E test is the primary enforced gate. 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.
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" — execute phase (1/3 done)`. A matching `*-progress.md` means this is a **resume** (see [Resume](#resume)).
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)).
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
- 1. **Parse the plan** — read every `## Requirement N:` heading and its `### Checkpoints` / `### Review` tags (defaults `full` / `parallel`). Requirements run in **listed order** — the plan is already in build order; do not reorder.
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
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):
23
23
 
@@ -28,86 +28,107 @@ The plan is a **behavioral spec** (acceptance criteria + integration tests) —
28
28
  Branch: <branch>
29
29
  Started: <ISO timestamp>
30
30
  Last updated: <ISO timestamp>
31
+ Feature phase: e2e-written
31
32
 
32
- | # | Status | Requirement | Commit |
33
- |---|--------|-------------|--------|
34
- | 1 | ⬜ pending | <requirement name> | — |
33
+ ## Requirements
34
+ | # | Done | Requirement | Per-req ceremony | Commit |
35
+ |---|------|-------------|-----------------|--------|
36
+ | 1 | ⬜ | <requirement name> | — | — |
35
37
  ```
38
+
39
+ `Feature phase` is one of: `e2e-written`, `feature-spec-paused`, `implementing (k/N)`, `feature-complete-paused`, `reviewing`, `done`.
40
+
36
41
  4. **Commit the plan docs** — `git add docs/plans/ && git commit -m "docs: add implementation plan"`.
37
- 5. Start requirement 1.
42
+ 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.
38
44
 
39
45
  ## Resume
40
46
 
41
- Find the first row that is `⬜ pending`, `🔄 in-progress`, `⏸ tests-review`, or `⏸ complete-review`:
42
- - `⏸ *-review` → re-present that checkpoint and wait.
43
- - `🔄 in-progress` → continue the requirement.
44
- - `⬜ pending` → start it.
47
+ Read the progress file's `Feature phase`:
48
+ - `e2e-written` → write the E2E if not yet present, then present the **feature-spec** checkpoint.
49
+ - `feature-spec-paused` → re-present the feature-spec checkpoint and wait.
50
+ - `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.
45
53
 
46
54
  ## Progress file
47
55
 
48
- Update the matching row directly (not via pattern matching that could corrupt the table). Update `Last updated` on every change.
49
-
50
- | Status | Meaning |
51
- |--------|---------|
52
- | `⬜ pending` | Not started |
53
- | `🔄 in-progress` | Writing tests or implementing |
54
- | `⏸ tests-review` | Paused at tests checkpoint, awaiting approval |
55
- | `⏸ complete-review` | Paused at complete checkpoint, awaiting approval |
56
- | `🔎 review` | Committed; code review in progress |
57
- | `✅ done` | Reviewed (smells fixed, hazards noted), all green |
58
- | `❌ failed` | Abandoned; partial work discarded/reverted (append `Failed: <reason>`) |
59
- | `⏭ skipped` | User chose to skip |
60
-
61
- ## Per-requirement execution
62
-
63
- 1. **Mark 🔄 in-progress** and read this requirement's `### Checkpoints` / `### Review` tags.
64
- 2. **Write the integration tests (red).** Encode the acceptance criteria + test cases from the plan as real test files; run them; confirm they **fail**. If they pass immediately, the behavior may already exist or the tests are wrong — investigate before proceeding.
65
- 3. **⏸ CHECKPOINT: tests** *(fires for `full` and `spec`)* — mark `⏸ tests-review`, present the tests + failing output, wait. **request changes** → revise, re-run, re-present. With `none`, show the red output inline and proceed.
66
- 4. **Implement (green)** with full autonomy. Run tests after each meaningful change; refactor for clarity (deep modules, no duplication, seam discipline) while tests stay green.
56
+ 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
+
58
+ ## Implement phase (after feature-spec is approved)
59
+
60
+ Set `Feature phase: implementing (0/N)` and work the requirements in listed order. For each:
61
+
62
+ 1. **Mark the requirement 🔄** (Done column) and read its `### Checkpoints` / `### Review` tags.
63
+ 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
+ 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.
67
66
  5. **Learn.** Caught a repeat mistake? Append a **generic** rule to `docs/lessons.md` (strip domain specifics).
68
- 6. **⏸ CHECKPOINT: complete** *(fires for `full` only)* — mark `⏸ complete-review`, show passing tests + `git diff`, wait. With `spec`/`none`, show them inline and proceed (**review** covers implementation quality; `spec` requires at least `inline` review).
69
- 7. **Commit** the relevant files with a clear message. Status stays `🔄 in-progress` — not done yet.
70
- 8. **Composition check** — if this diff touched code shared with other requirements in the plan, run the **full test suite** now and fix any cross-requirement regression while the context is fresh. Otherwise keep running just this requirement's tests.
71
- 9. **Code review** — mark `🔎 review`; drive review by the `### Review` tag (`parallel | inline | skip`):
72
- - **`parallel`** — four fresh-context reviewers via the `subagent` tool (see below).
73
- - **`inline`** — run `/skill:pwk-code-review` as a single pass.
74
- - **`skip`** — mark `✅ done` and move to the next requirement.
75
-
76
- **Parallel path** — gather scope (acceptance criteria, test cases, `git log --oneline -5 && git diff HEAD~N..HEAD`) and invoke:
77
- ```json
78
- {
79
- "tasks": [
80
- {"agent": "pwk-spec-reviewer", "task": "<scope + diff here>"},
81
- {"agent": "pwk-tracing-reviewer", "task": "<scope + diff here>"},
82
- {"agent": "pwk-smell-reviewer", "task": "<scope + diff here>"},
83
- {"agent": "pwk-hazard-reviewer", "task": "<scope + diff here>"}
84
- ],
85
- "agentScope": "both",
86
- "cwd": "<repo-root>"
87
- }
88
- ```
89
- The reviewer checklists live only in `agents/pwk-*-reviewer.md` — don't restate them in the task strings (duplication guarantees drift). Reviewers are read-only reporters; the executing agent applies fixes and commits.
67
+ 6. **Commit** the requirement with a clear message; mark its row ✅; advance `Feature phase: implementing (k/N)`.
90
68
 
91
- **On success** — apply smell fixes yourself (re-run integration tests, must stay green, commit), flag trace/spec/hazard findings as follow-ups for the human, mark `✅ done`.
69
+ ### Per-requirement review (opt-in)
92
70
 
93
- **Fallback** — subagent tool unavailable or errors → run `/skill:pwk-code-review` inline instead.
94
- 10. **Loop** to step 1 for the next `⬜ pending` requirement, or see [After all requirements](#after-all-requirements).
71
+ If the requirement's `### Review` tag is `parallel` or `inline` (default `skip`), review that slice now — same mechanics as the [feature review](#feature-review), scoped to the requirement's diff. With `skip`, no per-requirement review; the feature-level review covers it.
72
+
73
+ `Checkpoints: spec` requires at least `inline` review — dropping the complete checkpoint is only safe when review covers implementation quality; never combine `spec` with `Review: skip` (use `Checkpoints: none` instead).
95
74
 
96
75
  ### Checkpoint gates are mandatory (when the tag says so)
97
76
 
98
- `### Checkpoints` accepted values: `full | spec | none` → both stops / tests stop only / no stops. When a checkpoint fires it is a **hard stop**:
77
+ When a per-requirement checkpoint fires it is a **hard stop**:
99
78
  - Stop immediately; never proceed without explicit human approval.
100
79
  - **Never** `git add` or `git commit` before approval at a checkpoint.
101
- - Mark the progress file to the review status **before** pausing.
80
+ - Set the progress phase/status **before** pausing.
81
+
82
+ ## Feature-complete checkpoint
83
+
84
+ When every requirement's Done column is ✅:
85
+
86
+ 1. **Run the FULL test suite** — a failure means one requirement regressed another; fix it now, in execute context.
87
+ 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.
89
+
90
+ The old "integration gate" is gone — the feature E2E at `feature-complete` *is* the gate; there is no separate end pass.
102
91
 
103
- `Checkpoints: spec` with `Review: skip` is invalid (nothing would cover implementation quality) — stop and ask the human to fix the tags; use `Checkpoints: none` for truly trivial diffs.
92
+ ## Feature review
93
+
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.
95
+
96
+ - **`parallel`** (default) — four fresh-context reviewers via the `subagent` tool. Gather scope (the plan's acceptance criteria + Feature acceptance, `git log --oneline && git diff <merge-base>...HEAD`) and invoke:
97
+
98
+ ```json
99
+ {
100
+ "tasks": [
101
+ {"agent": "pwk-spec-reviewer", "task": "<scope + whole diff here>"},
102
+ {"agent": "pwk-tracing-reviewer", "task": "<scope + whole diff here>"},
103
+ {"agent": "pwk-smell-reviewer", "task": "<scope + whole diff here>"},
104
+ {"agent": "pwk-hazard-reviewer", "task": "<scope + whole diff here>"}
105
+ ],
106
+ "agentScope": "both",
107
+ "cwd": "<repo-root>"
108
+ }
109
+ ```
110
+
111
+ The reviewer checklists live only in `agents/pwk-*-reviewer.md` — don't restate them in the task strings (duplication guarantees drift). Reviewers are read-only reporters; you apply smell fixes yourself (full suite + E2E must stay green, commit) and flag trace/spec/hazard findings as follow-ups for the human.
112
+
113
+ - **`inline`** — run `/skill:pwk-code-review` over the whole diff as a single pass.
114
+ - **Fallback** — subagent tool unavailable or errors → run `/skill:pwk-code-review` inline instead.
115
+
116
+ On success, set `Feature phase: done`.
117
+
118
+ ## Tags reference
119
+
120
+ The plan tags each requirement and the feature level:
121
+
122
+ - **`### Checkpoints: none | full | spec`** — per-requirement human stops. `none` (default) = no per-requirement stop; `full` = tests + complete; `spec` = tests only.
123
+ - **`### Review: skip | parallel | inline`** — per-requirement review. `skip` (default) = none; `parallel` = four reviewers; `inline` = one `pwk-code-review` pass. The auto-tag default for requirements with non-empty `### Production-risk notes` is `parallel` (see `pwk-writing-plans` for the rule).
124
+ - **`### Feature review: parallel | inline`** — the one whole-feature review (always present). Default `parallel`; `inline` for small features.
104
125
 
105
126
  ## User override commands
106
127
 
107
128
  | User says | Agent does |
108
129
  |-----------|-----------|
109
- | `skip` | Mark current requirement `⏭ skipped`, move to next |
110
- | `status` | Show the progress table |
130
+ | `skip` | Mark current requirement skipped, move to next |
131
+ | `status` | Show the progress file (feature phase + requirement table) |
111
132
  | `stop` | Restore current requirement to its pre-in-progress state, suggest `/new` |
112
133
  | `retry` | Re-read the requirement, start over |
113
134
 
@@ -115,27 +136,22 @@ Update the matching row directly (not via pattern matching that could corrupt th
115
136
 
116
137
  Verify the criticism against the code, evaluate the suggestion, then implement (with tests) or push back with evidence. Don't blindly apply.
117
138
 
118
- ## After all requirements
119
-
120
- When no `⬜ pending` or `🔄 in-progress` requirements remain, run the **integration gate** before suggesting finalize — per-requirement review only saw each diff in isolation; this proves the requirements *compose* into the feature:
121
-
122
- 1. **Run the FULL test suite.** A failure here means one requirement regressed another — fix it now, in execute context.
123
- 2. **Run the feature-acceptance test.** The plan's `## Feature acceptance` section specifies one end-to-end test exercising the requirements *together* against the design's claim. Write it if missing; run it; it must pass. If the plan has no such section, stop and tell the human — the gate has nothing concrete to verify.
124
- 3. **Confirm composition.** Do the requirements together deliver the end-to-end behavior the design doc described? Fix gaps here, with tests, before shipping.
139
+ ## After the feature review
125
140
 
126
- Then determine the next step from the artifacts (the human drives every transition — this is a suggestion, not a gate):
141
+ 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):
127
142
 
128
143
  - **Standalone design doc** (no `docs/plans/*-overview.md`) → suggest `/skill:pwk-finalizing`.
129
- - **Umbrella part** (an `*-overview.md` exists) → read the overview roster and find this part's `<topic>`. If it's the **last** in build order, the umbrella is complete → suggest `/skill:pwk-finalizing` (one PR for the whole umbrella). If **more parts remain**, suggest `/skill:pwk-brainstorming` for the next part (the next `<topic>` in the roster).
144
+ - **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).
130
145
 
131
146
  Present:
132
147
 
133
148
  ```
134
- ✅ All requirements complete — integration verified!
149
+ ✅ Feature complete — feature E2E green, feature review done!
135
150
 
136
- | # | Status | Requirement |
137
- |---|--------|-------------|
138
- | 1 | ✅ done | <name> |
151
+ Feature phase: done
152
+ | # | Done | Requirement |
153
+ |---|------|-------------|
154
+ | 1 | ✅ | <name> |
139
155
  | … | … | … |
140
156
 
141
157
  - Next part: /skill:pwk-brainstorming (<next topic>) ← umbrella, more parts remain
@@ -147,4 +163,4 @@ Present:
147
163
  1. Re-read the requirement's acceptance criteria — you may have drifted.
148
164
  2. Check `git log` for context. Ask the user — clarify beats guessing.
149
165
  3. Still stuck → discard uncommitted changes (`git restore .`); if already committed, also `git revert` the requirement's commit(s). **Never leave a failed requirement's partial work on the shipped branch.**
150
- 4. Mark `❌ failed` with the reason and move on. Check `docs/lessons.md` — a prior lesson may apply.
166
+ 4. Mark the requirement failed with the reason and move on. Check `docs/lessons.md` — a prior lesson may apply.
package/skills/pwk-writing-plans/SKILL.md CHANGED
@@ -9,6 +9,8 @@ Turn the design doc's requirements into a **behavioral spec** the executor imple
9
9
 
10
10
  One design doc = one plan = one PR. The plan lists **all** the design's requirements in build order; the executor builds them one at a time.
11
11
 
12
+ The executor runs the **feature-gate flow**: it writes the feature-acceptance E2E first, implements the requirements back-to-back, then runs one feature-level review. Per-requirement checkpoints/reviews happen only for requirements you tag (default off) — so tag only the slices that genuinely need a human stop or a focused review.
13
+
12
14
  Your writes go into `docs/plans/` and nowhere else. Source code and configuration get written later, in `pwk-executing-tasks` — this phase produces the document the executor builds from.
13
15
 
14
16
  ## Process
@@ -19,10 +21,13 @@ Your writes go into `docs/plans/` and nowhere else. Source code and configuratio
19
21
  4. **Write the plan** — for each requirement:
20
22
  - **Acceptance criteria** — `Given/When/Then` behavioral statements defining "done". Write observable behaviors, not implementation steps; cover edge and error cases.
21
23
  - **Integration tests** — test name + what each asserts. This is the spec the executor writes tests from.
22
- - **`### Checkpoints: full | spec | none`** — how many human stops. `full` = tests + complete (default); `spec` = tests stop only (clear spec, low implementation risk — the complete checkpoint is dropped); `none` = trivial only (config line, typo).
23
- - **`### Review: parallel | inline | skip`** — `parallel` = four reviewers via subagent (default, non-trivial diffs); `inline` = one `pwk-code-review` pass (small/medium diffs); `skip` = trivial diffs with no behavioral surface.
24
- - Tag every requirement — missing tags default to `full` / `parallel`. **`spec` requires at least `inline` review** — dropping the complete checkpoint is only safe when review covers implementation quality; never combine `spec` with `Review: skip` (use `Checkpoints: none` instead).
24
+ - **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.
25
+ - **`### Checkpoints: none | full | spec`** — how many human stops. `none` = no per-requirement stop (default — the feature gate covers it); `full` = tests + complete stops; `spec` = tests stop only. Flag a requirement `full` or `spec` when it contains complex logic or is the main part of the feature — where a human look at the slice is worth the stop.
26
+ - **`### Review: skip | parallel | inline`** — `skip` = no per-requirement review (default — the feature-level review covers it); `parallel` = four reviewers via subagent; `inline` = one `pwk-code-review` pass. The auto-tag bullet below is the single source of truth for risky-requirement tagging.
27
+ - **`### Feature review: parallel | inline`** — one review over the **whole feature diff**, always present (the single thorough pass). `parallel` (default — thoroughness lives here, since it is the only review in the common case); `inline` for small features.
28
+ - Tag every requirement — missing tags default to `none` / `skip`. **`spec` requires at least `inline` review** — dropping the complete checkpoint is only safe when review covers implementation quality; never combine `spec` with `Review: skip` (use `Checkpoints: none` instead).
25
29
  - **Production-risk notes** — carry forward the design's `## Production-risk areas`, if any.
30
+ - **Auto-tag risky requirements with `### Review: parallel`** — when a requirement has a non-empty `### Production-risk notes` section, emit `### Review: parallel` as the default. Requirements without risk notes keep the existing default (`### Review: skip`). The tag is silently applied; the human can override or downgrade it to `inline` or `skip` during plan review before approval, and `pwk-executing-tasks` honors the edited value. This is the one source of truth for the auto-tag rule — `pwk-executing-tasks` and the docs link to it here, they do not restate the rule.
26
31
  - **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.
27
32
  - **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.
28
33
 
@@ -45,8 +50,8 @@ Your writes go into `docs/plans/` and nowhere else. Source code and configuratio
45
50
  - `should <behavior>` — asserts <observable outcome>
46
51
  - `should <error case>` — asserts <failure outcome>
47
52
 
48
- ### Checkpoints: full | spec | none
49
- ### Review: parallel | inline | skip
53
+ ### Checkpoints: none | full | spec
54
+ ### Review: skip | parallel | inline
50
55
 
51
56
  ### Production-risk notes
52
57
  - <from the design's Production-risk areas, if any>
@@ -55,8 +60,10 @@ Your writes go into `docs/plans/` and nowhere else. Source code and configuratio
55
60
  …
56
61
 
57
62
  ## Feature acceptance
58
- Derived from the design doc. One end-to-end test exercising the requirements *together*:
63
+ The **primary enforced spec** — the definition of done for the feature, and the test the executor gates on first. Derived from the design doc: one end-to-end test exercising the requirements *together*. Make it concrete — a named test + the assertion that proves the composed behavior:
59
64
  - `should <the PRD's end-to-end claim>` — Given <starting state>, When <trigger>, Then <composed outcome across requirements>.
65
+ ### Feature review: parallel | inline
66
+ One review over the whole feature diff (always). Default `parallel`; `inline` for small features.
60
67
  ```
61
68
 
62
69
  **If the design has no `## Feature acceptance` section**, stop and ask the human to run `/skill:pwk-brainstorming` to add one — the feature's definition-of-done is missing. (A trivial single-requirement design may fold the scenario into that requirement's criteria; note it and skip the separate section.)
@@ -66,7 +73,9 @@ Your writes go into `docs/plans/` and nowhere else. Source code and configuratio
66
73
  5. **Audit before presenting:**
67
74
  - Every requirement has criteria **and** matching tests, a checkpoint tag, a review tag.
68
75
  - No `spec` + `skip` combination.
69
- - A `## Feature acceptance` section exists (or the trivial-fold note).
76
+ - A `## Feature acceptance` section exists as the primary enforced spec (or the trivial-fold note).
77
+ - A feature-level `### Feature review` tag is present.
78
+ - Per-requirement tags default to `none` / `skip`; only requirements with complex logic, the main part of the feature, or production-risk are flagged heavier.
70
79
  - Production-risk areas from the design are reflected.
71
80
  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.
72
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).
package/docs/lessons.md DELETED
@@ -1,15 +0,0 @@
1
- # Lessons Learned
2
-
3
- <!--
4
- Agent: read this during brainstorm (design), writing-plans (acceptance criteria + tests), executing-tasks (per requirement), and finalizing (curation).
5
- Follow every rule. Add new rules when you catch yourself making repeat mistakes.
6
- Rules must be generic patterns applicable to any domain or feature — not specific to one service, entity, or use case.
7
- Retire rules that no longer apply during finalizing.
8
- -->
9
-
10
- ## Cross-Skill Consistency
11
-
12
- - **skill-lint assertions for new behavior need a marker that distinguishes new from old.** A token present in both models gives a false green — e.g. `/umbrella/` matched the old `<umbrella>-overview.md` filename placeholder before the new behavior landed; switched to `/status-free/`, a property only the new model has.
13
- - **Test-first for skill/doc content:** add the skill-lint assertion first (red — the skill doesn't yet claim the behavior), then edit the skill markdown to satisfy it (green). After edits run biome — it collapses short `if (cond) ok();` to one line and rejects array holes like `[, ""]` (restructure instead).
14
-
15
- ## Documentation