@tianhai/pi-workflow-kit 1.1.0 → 1.3.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.
- package/README.md +26 -24
- package/docs/developer-usage-guide.md +9 -9
- package/docs/oversight-model.md +4 -4
- package/docs/workflow-phases.md +18 -16
- package/package.json +1 -2
- package/skills/pwk-brainstorming/SKILL.md +32 -6
- package/skills/pwk-code-review/SKILL.md +2 -2
- package/skills/pwk-executing-tasks/SKILL.md +97 -75
- package/skills/pwk-finalizing/SKILL.md +33 -10
- package/skills/pwk-status/SKILL.md +11 -12
- package/skills/pwk-writing-plans/SKILL.md +18 -9
- package/docs/lessons.md +0 -13
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
|
|
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.**
|
|
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,19 +49,19 @@ Guide the agent through a disciplined development process:
|
|
|
49
49
|
|
|
50
50
|
```
|
|
51
51
|
brainstorm → writing-plans → executing-tasks → finalizing
|
|
52
|
-
(
|
|
52
|
+
(feature-gate: write feature E2E → feature-spec → implement → feature-complete → review)
|
|
53
53
|
↕
|
|
54
54
|
diagnose (anytime) · status (anytime)
|
|
55
55
|
```
|
|
56
56
|
|
|
57
|
-
A **design doc is one PR**; a **requirement is one testable slice within it**.
|
|
57
|
+
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.
|
|
58
58
|
|
|
59
59
|
| Phase | Trigger | What Happens |
|
|
60
60
|
|-------|---------|--------------|
|
|
61
61
|
| **Brainstorm** | `/skill:pwk-brainstorming` | Explore approaches, produce a design doc with a `## Requirements` list |
|
|
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` |
|
|
64
|
-
| **Code review** | `/skill:pwk-code-review` |
|
|
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
|
|
79
|
-
/skill:pwk-code-review → auto-runs
|
|
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
|
-
###
|
|
87
|
+
### Feature-Gate Execution
|
|
88
88
|
|
|
89
|
-
|
|
89
|
+
The feature is implemented via the feature-gate flow:
|
|
90
90
|
|
|
91
|
-
1. Write the
|
|
92
|
-
2. ⏸ **checkpoint:
|
|
93
|
-
3. Implement to green
|
|
94
|
-
4. ⏸ **checkpoint: complete** — you review the
|
|
95
|
-
5.
|
|
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
|
|
116
|
+
No configuration needed — the agent creates `docs/lessons.md` on first use and it grows as the agent learns.
|
|
115
117
|
|
|
116
|
-
### Two
|
|
118
|
+
### Two Feature-Level Checkpoints
|
|
117
119
|
|
|
118
|
-
|
|
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
|
-
| **
|
|
123
|
-
| **complete** |
|
|
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
|
|
129
|
+
### Before You Ship: the Feature-Complete Gate
|
|
128
130
|
|
|
129
|
-
|
|
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
|
-
# (
|
|
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
|
|
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
|
|
@@ -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
|
|
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
|
|
|
@@ -32,7 +32,7 @@ Or in `.pi/settings.json` / `~/.pi/agent/config.json`:
|
|
|
32
32
|
|
|
33
33
|
## The workflow
|
|
34
34
|
|
|
35
|
-
You control each phase by invoking the skill. A design doc is one PR; a requirement is one testable slice within it.
|
|
35
|
+
You control each phase by invoking the skill. A design doc is one PR; a requirement is one testable slice within it. A requirement too big for one design doc but shipping as one PR is an **umbrella** — multiple design docs under one status-free overview, on one branch, finalized once:
|
|
36
36
|
|
|
37
37
|
```
|
|
38
38
|
/skill:pwk-brainstorming → /skill:pwk-writing-plans → /skill:pwk-executing-tasks → /skill:pwk-finalizing
|
|
@@ -46,7 +46,7 @@ You control each phase by invoking the skill. A design doc is one PR; a requirem
|
|
|
46
46
|
|
|
47
47
|
Explore the idea through collaborative dialogue. The agent reads code, asks questions, proposes approaches, and presents the design for your review.
|
|
48
48
|
|
|
49
|
-
Outcome: `docs/plans/YYYY-MM-DD-<topic>-design.md` — descriptive, opening with a `## Requirements` list.
|
|
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
|
|
|
51
51
|
### 2. Plan
|
|
52
52
|
|
|
@@ -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
|
|
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 (
|
|
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
|
|
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
|
|
|
@@ -82,7 +82,7 @@ pi install npm:pi-subagents
|
|
|
82
82
|
/skill:pwk-finalizing
|
|
83
83
|
```
|
|
84
84
|
|
|
85
|
-
**Pre-check: run the full test suite** — never ship a red suite (resume spans sessions). Then delete consumed plan docs (
|
|
85
|
+
**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.
|
|
86
86
|
|
|
87
87
|
### Diagnose (on demand)
|
|
88
88
|
|
|
@@ -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
|
-
-
|
|
124
|
-
- **Right-size each requirement at plan time** with the `### Checkpoints` (`full`/`spec
|
|
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).
|
|
125
125
|
- Put all plan artifacts under `docs/plans/`; ADRs under `docs/adr/`.
|
package/docs/oversight-model.md
CHANGED
|
@@ -6,11 +6,11 @@
|
|
|
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
|
|
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
|
|
12
|
-
- **pwk-code-review** — the inline reviewer (code tracing, spec alignment, code smells, production hazards). During `pwk-executing-tasks`,
|
|
13
|
-
- **pwk-finalizing** —
|
|
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
|
+
- **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:
|
|
16
16
|
|
package/docs/workflow-phases.md
CHANGED
|
@@ -4,10 +4,10 @@
|
|
|
4
4
|
|
|
5
5
|
```
|
|
6
6
|
brainstorm → writing-plans → executing-tasks → finalizing
|
|
7
|
-
(
|
|
7
|
+
(feature-gate: write feature E2E → ⏸ feature-spec → implement requirements → ⏸ feature-complete → feature review)
|
|
8
8
|
```
|
|
9
9
|
|
|
10
|
-
A design doc is one PR; a requirement is one testable slice within it.
|
|
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`).
|
|
11
11
|
|
|
12
12
|
## brainstorm
|
|
13
13
|
|
|
@@ -17,7 +17,7 @@ A design doc is one PR; a requirement is one testable slice within it. For multi
|
|
|
17
17
|
|
|
18
18
|
- Explore requirements and shape the design.
|
|
19
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
|
|
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.
|
|
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.
|
|
@@ -30,7 +30,9 @@ Write boundary: only `docs/plans/` is writable. Source files are hard-blocked.
|
|
|
30
30
|
|
|
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 — 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.
|
|
34
36
|
- Produce `docs/plans/YYYY-MM-DD-<topic>-implementation.md`.
|
|
35
37
|
|
|
36
38
|
Write boundary: only `docs/plans/` is writable.
|
|
@@ -41,22 +43,22 @@ Write boundary: only `docs/plans/` is writable.
|
|
|
41
43
|
/skill:pwk-executing-tasks
|
|
42
44
|
```
|
|
43
45
|
|
|
44
|
-
-
|
|
45
|
-
-
|
|
46
|
-
- **
|
|
47
|
-
- Progress tracked in `docs/plans/*-progress.md
|
|
48
|
-
- 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).
|
|
49
50
|
|
|
50
51
|
No write restrictions. All tools available.
|
|
51
52
|
|
|
52
53
|
## Proportionality
|
|
53
54
|
|
|
54
|
-
The
|
|
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:
|
|
55
56
|
|
|
56
|
-
- **Checkpoints** — `
|
|
57
|
-
- **Review** — `parallel` (four fresh-context reviewers
|
|
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.
|
|
58
60
|
|
|
59
|
-
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
|
+
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.
|
|
60
62
|
|
|
61
63
|
## code-review
|
|
62
64
|
|
|
@@ -66,7 +68,7 @@ A trivial fix can also skip the multi-turn brainstorm dialogue via the brainstor
|
|
|
66
68
|
|
|
67
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.
|
|
68
70
|
|
|
69
|
-
**Not a phase you drive manually.** During `pwk-executing-tasks`,
|
|
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.
|
|
70
72
|
|
|
71
73
|
No write restrictions.
|
|
72
74
|
|
|
@@ -77,7 +79,7 @@ No write restrictions.
|
|
|
77
79
|
```
|
|
78
80
|
|
|
79
81
|
- **Pre-check: run the full test suite** — don't ship a red suite (resume spans sessions; don't trust the last execute session).
|
|
80
|
-
-
|
|
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**.
|
|
81
83
|
- Curate `docs/lessons.md`, update README/CHANGELOG, create PR or merge.
|
|
82
84
|
|
|
83
85
|
No write restrictions.
|
|
@@ -88,7 +90,7 @@ No write restrictions.
|
|
|
88
90
|
/skill:pwk-status
|
|
89
91
|
```
|
|
90
92
|
|
|
91
|
-
Read-only overview of all active pipeline topics (phase + progress) when several designs are in flight. Not a pipeline phase — and it **does not exit the gated phase** (`pwk-status` is read-only; it runs fine under the brainstorm/plan write block, so the boundary stays up).
|
|
93
|
+
Read-only overview of all active pipeline topics (phase + progress) when several designs are in flight; an umbrella rolls up under its overview (shipped / in-flight / not-started). Not a pipeline phase — and it **does not exit the gated phase** (`pwk-status` is read-only; it runs fine under the brainstorm/plan write block, so the boundary stays up).
|
|
92
94
|
|
|
93
95
|
## diagnose
|
|
94
96
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tianhai/pi-workflow-kit",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.3.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
|
],
|
|
@@ -18,15 +18,41 @@ When unsure, ask: "This looks trivial — fast-path it, or full brainstorm?" Def
|
|
|
18
18
|
|
|
19
19
|
## Granularity
|
|
20
20
|
|
|
21
|
-
**One design doc = one PR; one requirement = one testable slice within it.**
|
|
21
|
+
**One design doc = one PR; one requirement = one testable slice within it.** Most work is a single design doc.
|
|
22
22
|
|
|
23
|
-
-
|
|
24
|
-
-
|
|
23
|
+
- Within a doc, decompose into **requirements**, each one testable behavior.
|
|
24
|
+
- A requirement too big for one design doc but shipping as a single PR is an **umbrella** — multiple design docs decomposed under one overview, on one branch, finalized once. See [Umbrella](#umbrella) below.
|
|
25
|
+
|
|
26
|
+
## Umbrella
|
|
27
|
+
|
|
28
|
+
An umbrella splits one large requirement into multiple design docs that ship together as **one PR**. One branch; one `pwk-finalizing` at the end. The split is intra-PR decomposition — a way to keep each design/plan/execute cycle small and focused, not a multi-PR strategy.
|
|
29
|
+
|
|
30
|
+
**First brainstorm** (the requirement is too big for one design doc):
|
|
31
|
+
|
|
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**:
|
|
34
|
+
|
|
35
|
+
```markdown
|
|
36
|
+
# Overview: <umbrella>
|
|
37
|
+
|
|
38
|
+
Goal: <one line — what the whole requirement delivers>
|
|
39
|
+
|
|
40
|
+
## Parts (build order)
|
|
41
|
+
1. <topic> — <one-line scope>
|
|
42
|
+
2. <topic> — <one-line scope>
|
|
43
|
+
```
|
|
44
|
+
|
|
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`.
|
|
47
|
+
|
|
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
|
+
|
|
50
|
+
The whole umbrella is one branch and one PR: `pwk-writing-plans` creates the branch on the first part and reuses it for later parts; `pwk-executing-tasks` suggests the next part (or finalize after the last); `pwk-finalizing` disposes the overview + every part's docs and ships one PR.
|
|
25
51
|
|
|
26
52
|
## Process
|
|
27
53
|
|
|
28
54
|
1. **Check git state** — `git status` + `git log --oneline -5`. Uncommitted work? Ask the user what to do first.
|
|
29
|
-
2. **Discovery** *(skip in a brand-new repo with no `docs/plans/`)* — glob `docs/plans/*-design.md`; report in-flight topics. If the new idea continues an existing topic, ask whether to extend it or start fresh.
|
|
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)).
|
|
30
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.
|
|
31
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.
|
|
32
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.
|
|
@@ -36,7 +62,7 @@ When unsure, ask: "This looks trivial — fast-path it, or full brainstorm?" Def
|
|
|
36
62
|
|
|
37
63
|
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.
|
|
38
64
|
|
|
39
|
-
**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
|
|
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 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.
|
|
40
66
|
|
|
41
67
|
```markdown
|
|
42
68
|
## Feature acceptance
|
|
@@ -46,7 +72,7 @@ When unsure, ask: "This looks trivial — fast-path it, or full brainstorm?" Def
|
|
|
46
72
|
|
|
47
73
|
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."
|
|
48
74
|
|
|
49
|
-
**Splitting large issues:**
|
|
75
|
+
**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.
|
|
50
76
|
|
|
51
77
|
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`.
|
|
52
78
|
|
|
@@ -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
|
|
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
|
|
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
|
|
|
@@ -1,25 +1,25 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: pwk-executing-tasks
|
|
3
|
-
description: "Implement a plan
|
|
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`
|
|
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
|
|
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
|
|
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 `
|
|
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
|
|
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
|
|
|
24
24
|
```markdown
|
|
25
25
|
# Progress: <topic>
|
|
@@ -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
|
-
|
|
33
|
-
|
|
34
|
-
|
|
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.
|
|
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
|
-
|
|
42
|
-
-
|
|
43
|
-
-
|
|
44
|
-
-
|
|
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
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
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.
|
|
69
|
-
|
|
70
|
-
|
|
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)`.
|
|
68
|
+
|
|
69
|
+
### Per-requirement review (opt-in)
|
|
90
70
|
|
|
91
|
-
|
|
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.
|
|
92
72
|
|
|
93
|
-
|
|
94
|
-
10. **Loop** to step 1 for the next `⬜ pending` requirement, or see [After all requirements](#after-all-requirements).
|
|
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
|
-
|
|
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
|
-
-
|
|
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.
|
|
91
|
+
|
|
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:
|
|
102
121
|
|
|
103
|
-
|
|
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.
|
|
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
|
|
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,25 +136,26 @@ 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
|
|
139
|
+
## After the feature review
|
|
119
140
|
|
|
120
|
-
|
|
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):
|
|
121
142
|
|
|
122
|
-
|
|
123
|
-
|
|
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.
|
|
143
|
+
- **Standalone design doc** (no `docs/plans/*-overview.md`) → suggest `/skill:pwk-finalizing`.
|
|
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).
|
|
125
145
|
|
|
126
|
-
|
|
146
|
+
Present:
|
|
127
147
|
|
|
128
148
|
```
|
|
129
|
-
✅
|
|
149
|
+
✅ Feature complete — feature E2E green, feature review done!
|
|
130
150
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
151
|
+
Feature phase: done
|
|
152
|
+
| # | Done | Requirement |
|
|
153
|
+
|---|------|-------------|
|
|
154
|
+
| 1 | ✅ | <name> |
|
|
134
155
|
| … | … | … |
|
|
135
156
|
|
|
136
|
-
-
|
|
157
|
+
- Next part: /skill:pwk-brainstorming (<next topic>) ← umbrella, more parts remain
|
|
158
|
+
- Ship: /skill:pwk-finalizing ← standalone, or last umbrella part
|
|
137
159
|
```
|
|
138
160
|
|
|
139
161
|
## If you're stuck
|
|
@@ -141,4 +163,4 @@ Then present:
|
|
|
141
163
|
1. Re-read the requirement's acceptance criteria — you may have drifted.
|
|
142
164
|
2. Check `git log` for context. Ask the user — clarify beats guessing.
|
|
143
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.**
|
|
144
|
-
4. Mark
|
|
166
|
+
4. Mark the requirement failed with the reason and move on. Check `docs/lessons.md` — a prior lesson may apply.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: pwk-finalizing
|
|
3
|
-
description: "Use after all requirements are complete to delete consumed plan docs, curate lessons, update documentation, and ship the work."
|
|
3
|
+
description: "Use after all requirements are complete to archive or delete consumed plan docs, curate lessons, update documentation, and ship the work."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Finalizing
|
|
@@ -10,20 +10,43 @@ 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
|
|
14
|
-
- **Any `❌ failed`** → **block**. Present counts and reasons; continue only when the user sends the task back to executing-tasks, or explicitly types `--force-failed` to acknowledge shipping with incomplete requirements.
|
|
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:
|
|
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
16
|
|
|
17
17
|
## Process
|
|
18
18
|
|
|
19
|
-
1. **Derive the topic** —
|
|
20
|
-
|
|
19
|
+
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
|
+
- **Standalone**: progress file → `Plan:` ref → plan's `Design:` ref → design-doc filename → `<topic>`. One topic.
|
|
21
22
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
```
|
|
23
|
+
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
25
|
|
|
26
|
-
|
|
26
|
+
- **Delete (default)** — code + tests are the source of truth; removing the scaffold prevents stale plan docs from misleading future sessions:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
# for each <topic> in the set:
|
|
30
|
+
rm -f docs/plans/????-??-??-<topic>-design.md docs/plans/????-??-??-<topic>-implementation.md docs/plans/????-??-??-<topic>-progress.md
|
|
31
|
+
# umbrella only:
|
|
32
|
+
rm -f docs/plans/????-??-??-<umbrella>-overview.md
|
|
33
|
+
git add -A docs/plans/ && git commit -m "chore: delete planning docs for <topic-or-umbrella>"
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
- **Archive** — keep the planning history for future readers (e.g. a complex design worth preserving) by moving the artifacts into `docs/plans/completed/`:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
mkdir -p docs/plans/completed
|
|
40
|
+
# for each <topic> in the set:
|
|
41
|
+
mv docs/plans/????-??-??-<topic>-design.md docs/plans/completed/ 2>/dev/null || true
|
|
42
|
+
mv docs/plans/????-??-??-<topic>-implementation.md docs/plans/completed/ 2>/dev/null || true
|
|
43
|
+
mv docs/plans/????-??-??-<topic>-progress.md docs/plans/completed/ 2>/dev/null || true
|
|
44
|
+
# umbrella only:
|
|
45
|
+
mv docs/plans/????-??-??-<umbrella>-overview.md docs/plans/completed/ 2>/dev/null || true
|
|
46
|
+
git add docs/plans/ && git commit -m "chore: archive planning docs for <topic-or-umbrella>"
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
The `????-??-??-` glob enforces the dated filename; a bare `*<topic>*` would over-match unrelated docs (e.g. topic `auth` would also hit `feature-auth-redesign-design.md`). Verify with `ls docs/plans/` before and after. `rm -f` and each `mv … || true` handle missing files. Both paths commit the disposal so the shipped branch is clean. Neither path touches `docs/adr/`, `docs/lessons.md`, `CHANGELOG.md`, or `README.md` — those are permanent.
|
|
27
50
|
3. **Curate lessons (Agile Scrum Master hat)** — if `docs/lessons.md` exists: add missed lessons, generalize domain-specific rules into generic patterns, de-duplicate, categorize, retire stale rules. None exists but lessons were learned? Create it.
|
|
28
51
|
4. **Update documentation** — if the API or surface changed: `README.md`, `CHANGELOG.md`, any inline docs.
|
|
29
52
|
5. **Choose a merge strategy** — ask the human:
|
|
@@ -38,6 +61,6 @@ Ship the completed work.
|
|
|
38
61
|
|
|
39
62
|
## Principles
|
|
40
63
|
|
|
41
|
-
-
|
|
64
|
+
- Dispose of the active work's artifacts only (archive or delete, the human's choice) — for a standalone design doc its three docs; for an umbrella its overview plus every part's docs. Unrelated topics stay in `docs/plans/`.
|
|
42
65
|
- ADRs are permanent institutional memory — they stay out of archive/rotation forever.
|
|
43
66
|
- Bump the package version if this is a published change (major for breaking changes).
|
|
@@ -5,24 +5,23 @@ description: "Show all active pipeline topics and their phase/progress. Use when
|
|
|
5
5
|
|
|
6
6
|
# Status
|
|
7
7
|
|
|
8
|
-
Report on
|
|
8
|
+
Report on in-flight pipelines in this working tree (a worktree has its own `docs/plans/`, so run status in each). Read-only. This skill **does not unlock the guard** — it needs no writes, so it runs fine inside the brainstorm/plan read-only phase. If you want source edits after a status check, invoke the skill for the next phase yourself (the guard follows the skill).
|
|
9
9
|
|
|
10
10
|
## Process
|
|
11
11
|
|
|
12
|
-
1. Glob `docs/plans/*-design.md`, `*-implementation.md`, `*-progress.md
|
|
13
|
-
2. For each
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
- `*-progress.md` → execute phase — show `done/total` requirement count
|
|
17
|
-
3. Print a one-line table, e.g.:
|
|
12
|
+
1. Glob `docs/plans/*-overview.md`, `*-design.md`, `*-implementation.md`, `*-progress.md` — this working tree only.
|
|
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.
|
|
15
|
+
4. Print a compact table, grouped under any umbrellas, e.g.:
|
|
18
16
|
|
|
19
17
|
```
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
18
|
+
payments-revamp (umbrella): 2 in-flight · 1 not-started
|
|
19
|
+
payments-core execute 2/3 done
|
|
20
|
+
payments-ui plan —
|
|
21
|
+
payments-webhooks not started
|
|
22
|
+
auth execute 1/2 done
|
|
24
23
|
```
|
|
25
24
|
|
|
26
|
-
|
|
25
|
+
If nothing, suggest `/skill:pwk-brainstorming`.
|
|
27
26
|
|
|
28
27
|
Keep it short — this is orientation, not analysis. No writes; the `<topic>` slug is the identity.
|
|
@@ -9,19 +9,23 @@ 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
|
|
15
17
|
|
|
16
|
-
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.
|
|
17
|
-
2. **Create the feature branch** — `git checkout -b <topic>` (branch creation is allowed in the plan phase). Design + plan docs live on this branch, committed at the start of `pwk-executing-tasks`.
|
|
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.
|
|
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`.
|
|
18
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.
|
|
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
|
-
-
|
|
23
|
-
- **`###
|
|
24
|
-
-
|
|
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. Flag a requirement for `parallel` or `inline` when it touches production-risk areas.
|
|
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.
|
|
26
30
|
- **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
31
|
- **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,6 +37,7 @@ Your writes go into `docs/plans/` and nowhere else. Source code and configuratio
|
|
|
33
37
|
|
|
34
38
|
## Overview
|
|
35
39
|
Design: docs/plans/YYYY-MM-DD-<topic>-design.md
|
|
40
|
+
Umbrella: docs/plans/YYYY-MM-DD-<umbrella>-overview.md *(umbrella part only — else omit)*
|
|
36
41
|
|
|
37
42
|
## Requirement 1: <name>
|
|
38
43
|
|
|
@@ -44,8 +49,8 @@ Your writes go into `docs/plans/` and nowhere else. Source code and configuratio
|
|
|
44
49
|
- `should <behavior>` — asserts <observable outcome>
|
|
45
50
|
- `should <error case>` — asserts <failure outcome>
|
|
46
51
|
|
|
47
|
-
### Checkpoints:
|
|
48
|
-
### Review:
|
|
52
|
+
### Checkpoints: none | full | spec
|
|
53
|
+
### Review: skip | parallel | inline
|
|
49
54
|
|
|
50
55
|
### Production-risk notes
|
|
51
56
|
- <from the design's Production-risk areas, if any>
|
|
@@ -54,8 +59,10 @@ Your writes go into `docs/plans/` and nowhere else. Source code and configuratio
|
|
|
54
59
|
…
|
|
55
60
|
|
|
56
61
|
## Feature acceptance
|
|
57
|
-
Derived from the design doc
|
|
62
|
+
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:
|
|
58
63
|
- `should <the PRD's end-to-end claim>` — Given <starting state>, When <trigger>, Then <composed outcome across requirements>.
|
|
64
|
+
### Feature review: parallel | inline
|
|
65
|
+
One review over the whole feature diff (always). Default `parallel`; `inline` for small features.
|
|
59
66
|
```
|
|
60
67
|
|
|
61
68
|
**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.)
|
|
@@ -65,7 +72,9 @@ Your writes go into `docs/plans/` and nowhere else. Source code and configuratio
|
|
|
65
72
|
5. **Audit before presenting:**
|
|
66
73
|
- Every requirement has criteria **and** matching tests, a checkpoint tag, a review tag.
|
|
67
74
|
- No `spec` + `skip` combination.
|
|
68
|
-
- A `## Feature acceptance` section exists (or the trivial-fold note).
|
|
75
|
+
- A `## Feature acceptance` section exists as the primary enforced spec (or the trivial-fold note).
|
|
76
|
+
- A feature-level `### Feature review` tag is present.
|
|
77
|
+
- Per-requirement tags default to `none` / `skip`; only requirements with complex logic, the main part of the feature, or production-risk are flagged heavier.
|
|
69
78
|
- Production-risk areas from the design are reflected.
|
|
70
79
|
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.
|
|
71
80
|
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,13 +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
|
-
|
|
13
|
-
## Documentation
|