@tianhai/pi-workflow-kit 0.17.1 → 1.0.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 (67) hide show
  1. package/README.md +91 -64
  2. package/agents/pwk-hazard-reviewer.md +24 -0
  3. package/agents/pwk-smell-reviewer.md +17 -0
  4. package/agents/pwk-spec-reviewer.md +14 -0
  5. package/agents/pwk-tracing-reviewer.md +14 -0
  6. package/docs/developer-usage-guide.md +49 -37
  7. package/docs/lessons.md +13 -0
  8. package/docs/oversight-model.md +19 -9
  9. package/docs/workflow-phases.md +58 -29
  10. package/extensions/workflow-guard.ts +190 -91
  11. package/package.json +19 -3
  12. package/skills/pwk-brainstorming/SKILL.md +60 -0
  13. package/skills/pwk-code-review/SKILL.md +46 -0
  14. package/skills/{diagnose → pwk-diagnose}/SKILL.md +3 -2
  15. package/skills/pwk-executing-tasks/SKILL.md +154 -0
  16. package/skills/pwk-finalizing/SKILL.md +78 -0
  17. package/skills/pwk-status/SKILL.md +28 -0
  18. package/skills/pwk-writing-plans/SKILL.md +83 -0
  19. package/docs/plans/2026-06-03-karpathy-guidelines-ab-comparison.md +0 -166
  20. package/docs/plans/completed/2026-04-11-checkpoint-review-gates-design.md +0 -50
  21. package/docs/plans/completed/2026-04-11-checkpoint-review-gates-implementation.md +0 -98
  22. package/docs/plans/completed/2026-04-11-finalizing-merge-options-design.md +0 -33
  23. package/docs/plans/completed/2026-04-11-finalizing-merge-options-implementation.md +0 -75
  24. package/docs/plans/completed/2026-04-11-workspace-setup-design.md +0 -28
  25. package/docs/plans/completed/2026-04-11-workspace-setup-implementation.md +0 -57
  26. package/docs/plans/completed/2026-04-15-bash-guard-design.md +0 -39
  27. package/docs/plans/completed/2026-04-15-bash-guard-implementation.md +0 -229
  28. package/docs/plans/completed/2026-04-21-workflow-guard-safe-commands-design.md +0 -172
  29. package/docs/plans/completed/2026-04-21-workflow-guard-safe-commands-implementation.md +0 -168
  30. package/docs/plans/completed/2026-04-22-go-readonly-safe-commands-implementation.md +0 -54
  31. package/docs/plans/completed/2026-04-28-executing-tasks-redesign-design.md +0 -171
  32. package/docs/plans/completed/2026-04-28-executing-tasks-redesign-implementation.md +0 -208
  33. package/docs/plans/completed/2026-04-28-executing-tasks-redesign-progress.md +0 -14
  34. package/docs/plans/completed/2026-05-01-incorporate-mattpocock-skills-design.md +0 -154
  35. package/docs/plans/completed/2026-05-01-incorporate-mattpocock-skills-implementation.md +0 -315
  36. package/docs/plans/completed/2026-05-01-incorporate-mattpocock-skills-progress.md +0 -15
  37. package/docs/plans/completed/2026-05-08-checkpoint-gates-design.md +0 -235
  38. package/docs/plans/completed/2026-05-08-checkpoint-gates-implementation.md +0 -83
  39. package/docs/plans/completed/2026-05-08-checkpoint-gates-progress.md +0 -11
  40. package/docs/plans/completed/2026-05-08-lessons-learned-design.md +0 -76
  41. package/docs/plans/completed/2026-05-08-lessons-learned-implementation.md +0 -219
  42. package/docs/plans/completed/2026-05-08-lessons-learned-progress.md +0 -15
  43. package/docs/plans/completed/2026-05-08-migrate-earendil-works-design.md +0 -39
  44. package/docs/plans/completed/2026-05-08-migrate-earendil-works-implementation.md +0 -45
  45. package/docs/plans/completed/2026-05-08-migrate-earendil-works-progress.md +0 -10
  46. package/docs/plans/completed/2026-05-08-worktree-handoff-design.md +0 -118
  47. package/docs/plans/completed/2026-05-08-worktree-handoff-implementation.md +0 -140
  48. package/docs/plans/completed/2026-05-08-worktree-handoff-progress.md +0 -10
  49. package/docs/plans/completed/2026-05-20-generic-lessons-design.md +0 -70
  50. package/docs/plans/completed/2026-05-20-generic-lessons-implementation.md +0 -114
  51. package/docs/plans/completed/2026-05-20-generic-lessons-progress.md +0 -11
  52. package/docs/plans/completed/2026-05-22-agentic-agile-enhancements-design.md +0 -77
  53. package/docs/plans/completed/2026-05-22-agentic-agile-enhancements-implementation.md +0 -473
  54. package/docs/plans/completed/2026-05-25-design-review-split-implementation.md +0 -622
  55. package/docs/plans/completed/2026-05-25-design-review-split-progress.md +0 -16
  56. package/docs/plans/completed/2026-05-25-pr5-improvements-implementation.md +0 -273
  57. package/docs/plans/completed/2026-05-25-pr5-improvements-progress.md +0 -17
  58. package/docs/plans/completed/2026-06-03-add-verify-skill-design.md +0 -51
  59. package/docs/plans/completed/2026-06-03-add-verify-skill-implementation.md +0 -111
  60. package/docs/plans/completed/2026-06-03-add-verify-skill-progress.md +0 -11
  61. package/docs/plans/completed/2026-06-03-verify-skill-design.md +0 -176
  62. package/skills/brainstorming/SKILL.md +0 -48
  63. package/skills/design-review/SKILL.md +0 -113
  64. package/skills/executing-tasks/SKILL.md +0 -350
  65. package/skills/finalizing/SKILL.md +0 -119
  66. package/skills/verify/SKILL.md +0 -170
  67. package/skills/writing-plans/SKILL.md +0 -343
@@ -1,15 +0,0 @@
1
- # Progress: incorporate-mattpocock-skills
2
-
3
- Plan: docs/plans/2026-05-01-incorporate-mattpocock-skills-implementation.md
4
- Branch: incorporate-mattpocock-skills
5
- Started: 2026-05-01T00:00:00Z
6
- Last updated: 2026-05-01T00:00:00Z
7
-
8
- | # | Status | Task | Commit |
9
- |---|--------|------|--------|
10
- | 1 | ✅ done | Update brainstorming skill — design it twice + ADRs | 0231b84 |
11
- | 2 | ✅ done | Update writing-plans skill — vertical slices | 22a46df |
12
- | 3 | ✅ done | Update executing-tasks skill — deep modules refactoring | c405634 |
13
- | 4 | ✅ done | Create diagnose skill | 5e39e2d |
14
- | 5 | ✅ done | Update finalizing skill — archive ADRs | e31a1af |
15
- | 6 | ✅ done | Update documentation (README, usage guide, workflow phases) | 8c1c4eb |
@@ -1,235 +0,0 @@
1
- # Design: Checkpoint gates and pre-commit discipline
2
-
3
- ## Problem
4
-
5
- The `executing-tasks` skill instructs the agent to pause at checkpoints for human review before committing. In practice, the agent commits first then presents the review, defeating the purpose of checkpoints.
6
-
7
- Root causes in executing-tasks:
8
- 1. "PAUSE if" reads as optional — the agent interprets it as "if you remember"
9
- 2. Steps 6-12 flow together as implement→commit — the pause gets swallowed
10
- 3. The diff format asks for committed state — nudges the agent to commit first
11
-
12
- Root causes in writing-plans:
13
- 4. Task format says `git commit` after each task — the agent sees the commit line past the checkpoint and skips to it
14
- 5. Refactor and lessons are optional-sounding steps at the end of a long list — the agent skips them
15
- 6. The plan body has no structural enforcement — everything is just text the agent reads at once
16
-
17
- Secondary issue: the agent skips steps 9 (Refactor if needed) and 10 (Learn from mistakes) because they're optional-sounding steps at the end of a long list.
18
-
19
- ## Key insight
20
-
21
- The agent follows numbered steps and skips loose sections. **Output requirements** (things the agent has to produce) are stronger than instructions (things the agent is told to do). The checkpoint review format forces the agent to report refactoring and lessons — that's the enforcement mechanism.
22
-
23
- No-checkpoint tasks are simple enough that refactor/lessons genuinely aren't needed — the task author chose no checkpoint because the task is trivial.
24
-
25
- ## Solution
26
-
27
- - **writing-plans**: Generate task bodies with numbered steps (including refactor/lessons for checkpointed tasks) and checkpoint gates. Never include `git commit` in the plan.
28
- - **executing-tasks**: Simplified runner — follow the plan step by step, pause at checkpoint gates, commit after approval.
29
- - **Progress file**: Use Status column to enforce checkpoint gates. Agent can't go from `🔄 in-progress` → `✅ done` if the task has a checkpoint — must go through `⏸ test-review` or `⏸ done-review` first.
30
-
31
- ## Design
32
-
33
- ### Writing-plans: task format
34
-
35
- The plan never includes `git commit`. That's the executing-tasks skill's responsibility.
36
-
37
- **No-checkpoint task:**
38
-
39
- ```markdown
40
- ## Task 1: Create User model
41
-
42
- <!-- tdd: new-feature -->
43
- <!-- checkpoint: none -->
44
-
45
- Files:
46
- - `src/user/model.ts`
47
- - `src/user/model.test.ts`
48
-
49
- Steps:
50
- 1. Write failing test for User model creation
51
- 2. Run test — confirm it fails
52
- 3. Implement User model
53
- 4. Run test — confirm it passes
54
- ```
55
-
56
- **Checkpoint: test task:**
57
-
58
- ```markdown
59
- ## Task 2: Write auth tests
60
-
61
- <!-- tdd: new-feature -->
62
- <!-- checkpoint: test -->
63
-
64
- Files:
65
- - `src/auth/login.test.ts`
66
-
67
- Steps:
68
- 1. Write failing test for login with valid credentials
69
- 2. Run test — confirm it fails
70
-
71
- ⏸ **CHECKPOINT: test** — present test review. Wait for human approval before implementing.
72
-
73
- 3. Implement login handler
74
- 4. Run test — confirm it passes
75
- 5. Refactor — check for shallow modules, duplication, seam discipline. Run tests after changes.
76
- 6. Lessons — caught a mistake that applies to future tasks? Add rule to `docs/lessons.md`.
77
- ```
78
-
79
- **Checkpoint: done task:**
80
-
81
- ```markdown
82
- ## Task 3: Add login endpoint
83
-
84
- <!-- tdd: new-feature -->
85
- <!-- checkpoint: done -->
86
-
87
- Files:
88
- - `src/auth/login.ts`
89
- - `src/auth/login.test.ts`
90
-
91
- Steps:
92
- 1. Write failing test for login with valid credentials
93
- 2. Run test — confirm it fails
94
- 3. Implement login handler
95
- 4. Run test — confirm it passes
96
- 5. Add edge case tests (invalid password, missing email)
97
- 6. Refactor — check for shallow modules, duplication, seam discipline. Run tests after changes.
98
- 7. Lessons — caught a mistake that applies to future tasks? Add rule to `docs/lessons.md`.
99
-
100
- ⏸ **CHECKPOINT: done** — present implementation review. Wait for human approval before committing.
101
- ```
102
-
103
- **Task with both checkpoints:**
104
-
105
- ```markdown
106
- ## Task 4: Complex auth flow
107
-
108
- <!-- tdd: new-feature -->
109
- <!-- checkpoint: test -->
110
- <!-- checkpoint: done -->
111
-
112
- Steps:
113
- 1. Write failing test for auth flow
114
- 2. Run test — confirm it fails
115
-
116
- ⏸ **CHECKPOINT: test** — present test review. Wait for human approval before implementing.
117
-
118
- 3. Implement auth flow
119
- 4. Run test — confirm it passes
120
- 5. Refactor — check for shallow modules, duplication, seam discipline. Run tests after changes.
121
- 6. Lessons — caught a mistake that applies to future tasks? Add rule to `docs/lessons.md`.
122
-
123
- ⏸ **CHECKPOINT: done** — present implementation review. Wait for human approval before committing.
124
- ```
125
-
126
- ### Writing-plans: checkpoint labels table
127
-
128
- | Checkpoint | When to use | What the plan should say |
129
- |---|---|---|
130
- | *(none)* | Trivial tasks, well-understood changes | Numbered steps only |
131
- | **`checkpoint: test`** | Test design matters | Steps up to test → `⏸ CHECKPOINT: test` → implement steps (including refactor/lessons) |
132
- | **`checkpoint: done`** | Implementation review matters | Steps (including refactor/lessons) → `⏸ CHECKPOINT: done` |
133
- | Both | Non-obvious tests AND complex logic | Steps up to test → `⏸ CHECKPOINT: test` → implement steps (including refactor/lessons) → `⏸ CHECKPOINT: done` |
134
-
135
- ### Executing-tasks: simplified runner
136
-
137
- The per-task execution becomes:
138
-
139
- 1. Mark `🔄 in-progress` in progress file
140
- 2. Read the current task from the plan
141
- 3. Execute each numbered step in order
142
- 4. When hitting `⏸ CHECKPOINT` in the plan:
143
- - Update progress to `⏸ test-review` or `⏸ done-review`
144
- - Present the checkpoint review (see format below)
145
- - Wait for human approval
146
- - On approval, update progress back to `🔄 in-progress`
147
- - Continue with the next step
148
- 5. After all steps are done (or for no-checkpoint tasks, after steps + commit):
149
- - `git add` and commit with a clear message
150
- - Update progress to `✅ done` + record commit hash
151
-
152
- ### Progress file: Status-enforced gates
153
-
154
- Status values:
155
-
156
- | Status | Meaning |
157
- |--------|---------|
158
- | `⬜ pending` | Not started |
159
- | `🔄 in-progress` | Currently executing plan steps |
160
- | `⏸ test-review` | Paused at checkpoint: test, waiting for human approval |
161
- | `⏸ done-review` | Paused at checkpoint: done, waiting for human approval |
162
- | `✅ done` | Committed successfully |
163
- | `❌ failed` | Could not complete |
164
- | `⏭ skipped` | User chose to skip |
165
-
166
- Enforcement rules:
167
- - Agent cannot go from `🔄 in-progress` → `✅ done` if the task has a checkpoint
168
- - Must go through `⏸ test-review` or `⏸ done-review` first
169
- - Can only return to `🔄 in-progress` after human says "approve"
170
- - Can only go to `✅ done` after commit
171
-
172
- Example progress file:
173
-
174
- ```markdown
175
- # Progress: Auth feature
176
-
177
- Plan: docs/plans/2026-05-08-auth-implementation.md
178
- Branch: auth-feature
179
- Started: 2026-05-08T10:00:00Z
180
- Last updated: 2026-05-08T10:05:00Z
181
-
182
- | # | Status | Task | Commit |
183
- |---|--------|------|--------|
184
- | 1 | ✅ done | Create User model | abc123 |
185
- | 2 | ⏸ done-review | Add login endpoint (checkpoint: done) | — |
186
- | 3 | ⬜ pending | Add auth middleware (checkpoint: done) | — |
187
- ```
188
-
189
- ### Checkpoint review format
190
-
191
- For `checkpoint: test`:
192
-
193
- ```
194
- ⏸ Paused at checkpoint: test for task [N]
195
-
196
- **Test written:** [show test code]
197
- **Expected behavior:** [what this validates]
198
- **Next:** Continue implementing after approval
199
-
200
- **Available actions:**
201
- - **Approve** — continue to implementation
202
- - **Request changes** — describe what to change
203
- - **Revert** — undo this task and mark it back to pending
204
- - `skip` — skip this task
205
- - `stop` — pause here, resume later with `/skill:executing-tasks`
206
- ```
207
-
208
- For `checkpoint: done`:
209
-
210
- ```
211
- ⏸ Paused at checkpoint: done for task [N]
212
-
213
- **What was done:** [brief summary]
214
- **Refactoring done:** [what changed, or "none needed — [reason]"]
215
- **Lessons learned:** [new rule added, or "none"]
216
- **Diff:** [run `git diff --cached` or `git diff` — do NOT commit first]
217
- **Next:** Commit after approval
218
-
219
- **Available actions:**
220
- - **Approve** — commit and move to next task
221
- - **Request changes** — describe what to change
222
- - **Revert** — undo this task and mark it back to pending
223
- - `skip` — skip this task
224
- - `stop` — pause here, resume later with `/skill:executing-tasks`
225
- ```
226
-
227
- ## Files to change
228
-
229
- - `skills/writing-plans/SKILL.md` — update task format template and checkpoint labels section
230
- - `skills/executing-tasks/SKILL.md` — simplify per-task execution to plan-following runner, update progress file status values
231
-
232
- ## What stays the same
233
-
234
- - executing-tasks: Before you start, First run, Resume, User override commands, Receiving code review, If you're stuck, After all tasks — all unchanged
235
- - writing-plans: Process steps, vertical slices, TDD section — all unchanged
@@ -1,83 +0,0 @@
1
- # Implementation: Checkpoint gates and pre-commit discipline
2
-
3
- Design: `docs/plans/2026-05-08-checkpoint-gates-design.md`
4
-
5
- ## Overview
6
-
7
- Update two skill files so that:
8
- 1. `writing-plans` generates task bodies with checkpoint gates and numbered refactor/lessons steps, never includes `git commit`
9
- 2. `executing-tasks` becomes a simplified plan-following runner with status-enforced checkpoint gates
10
-
11
- ## Task 1: Update writing-plans task format and checkpoint labels
12
-
13
- <!-- tdd: trivial -->
14
- <!-- checkpoint: none -->
15
-
16
- Files:
17
- - `skills/writing-plans/SKILL.md`
18
-
19
- Changes:
20
-
21
- ### Task format section
22
-
23
- Replace the task format section. Key changes:
24
- - Remove `git commit` from bullet points (commit is the executing-tasks skill's responsibility)
25
- - Remove `<!-- checkpoint: none -->` from the default template (omit when no checkpoint)
26
- - Add task body examples for each checkpoint type (none, test, done, both)
27
- - For checkpointed tasks, include numbered refactor and lessons steps
28
- - For checkpointed tasks, include `⏸ CHECKPOINT` gate in the task body
29
- - No task body should include `git commit`
30
-
31
- ### Checkpoint labels section
32
-
33
- Replace the checkpoint labels table. Change the last column from "What happens during execution" to "What the plan should include", showing the gate structure for each checkpoint type.
34
-
35
- ### TDD section
36
-
37
- Remove "→ commit" from the Instructions column — commit is not part of the plan.
38
-
39
- ## Task 2: Update executing-tasks per-task execution and progress file
40
-
41
- <!-- tdd: trivial -->
42
- <!-- checkpoint: done -->
43
-
44
- Files:
45
- - `skills/executing-tasks/SKILL.md`
46
-
47
- Changes:
48
-
49
- ### Per-task execution section
50
-
51
- Replace the current 15-step list with a simplified plan-following runner:
52
-
53
- 1. Mark `🔄 in-progress` in progress file
54
- 2. Read the current task from the plan
55
- 3. Execute each numbered step in order
56
- 4. When hitting `⏸ CHECKPOINT` in the plan:
57
- - Update progress to `⏸ test-review` or `⏸ done-review`
58
- - Present the checkpoint review
59
- - Wait for human approval
60
- - On approval, update progress back to `🔄 in-progress`
61
- - Continue with the next step
62
- 5. After all steps done:
63
- - `git add` and commit with a clear message
64
- - Update progress to `✅ done` + record commit hash
65
-
66
- Remove the inline refactor/lessons steps — they're now in the plan for checkpointed tasks.
67
-
68
- ### Progress file section
69
-
70
- Add `⏸ test-review` and `⏸ done-review` status values. Add enforcement rule: agent cannot go from `🔄 in-progress` → `✅ done` if task has a checkpoint.
71
-
72
- ### Checkpoint review section
73
-
74
- Update `checkpoint: done` review to include:
75
- - **Refactoring done:** field
76
- - **Lessons learned:** field
77
- - **Diff:** uses `git diff --cached` or `git diff`, with "do NOT commit first"
78
-
79
- Simplify available actions (remove "Adjust plan" since the plan drives execution).
80
-
81
- ### Keep unchanged
82
-
83
- - Before you start, First run, Resume, User override commands, Receiving code review, If you're stuck, After all tasks
@@ -1,11 +0,0 @@
1
- # Progress: Checkpoint gates and pre-commit discipline
2
-
3
- Plan: docs/plans/2026-05-08-checkpoint-gates-implementation.md
4
- Branch: main
5
- Started: 2026-05-08T20:00:00Z
6
- Last updated: 2026-05-08T20:12:00Z
7
-
8
- | # | Status | Task | Commit |
9
- |---|--------|------|--------|
10
- | 1 | ✅ done | Update writing-plans task format and checkpoint labels | d39510c |
11
- | 2 | ✅ done | Update executing-tasks per-task execution and progress file (checkpoint: done) | 7c84f59 |
@@ -1,76 +0,0 @@
1
- # Lessons Learned
2
-
3
- Date: 2026-05-08
4
-
5
- ## Problem
6
-
7
- During task execution, the AI agent repeatedly makes the same project-specific mistakes — e.g., forgetting to run `make lint && make fmt` in Go projects, ignoring test helper conventions, or violating code style rules. These mistakes persist across sessions because there's no persistent memory the agent reads at the start of each task.
8
-
9
- ## Solution
10
-
11
- A flat rules file (`docs/lessons.md`) that the agent reads before each task and writes to when it catches repeat mistakes. Integrated into the existing 4 workflow skills.
12
-
13
- ## File: `docs/lessons.md`
14
-
15
- Created automatically when the first lesson is written. Never archived or moved.
16
-
17
- ```markdown
18
- # Lessons Learned
19
-
20
- <!--
21
- Agent: read this at the start of each task during executing-tasks.
22
- Follow every rule. Add new rules when you catch yourself making repeat mistakes.
23
- Retire rules that no longer apply during finalizing.
24
- -->
25
-
26
- ## Rules
27
-
28
- - After completing each task in a Go project, run `make lint && make fmt` before committing
29
- ```
30
-
31
- ### Rules for the agent
32
-
33
- - Each rule is a single bullet under `## Rules`
34
- - Write rules as imperative commands ("do X", "never Y", "always Z before W")
35
- - A rule is only added when it would **change future behavior** — not one-off errors
36
- - Rules can be removed (retired) during finalizing if they no longer apply
37
-
38
- ## Data flow
39
-
40
- ```
41
- brainstorming ──── reads lessons (context for design)
42
-
43
- writing-plans ──── reads lessons (informs task breakdown)
44
-
45
- executing-tasks ── reads lessons at start of EACH task
46
- │ appends new lessons when catching repeat mistakes
47
-
48
- finalizing ─────── reviews session for missed lessons
49
- retires stale rules
50
- ```
51
-
52
- Lessons are persisted to disk as soon as they're learned, so `/new` sessions don't lose them.
53
-
54
- ## Skill changes
55
-
56
- ### executing-tasks (3 changes)
57
-
58
- 1. **Per-task execution, step 2** — add bullet: "Read `docs/lessons.md` if it exists — follow all rules listed there while working on this task."
59
- 2. **New step between step 9 (refactor) and step 10 (checkpoint: done)** — "Learn from mistakes: if you caught yourself making a repeat mistake, append a rule to `docs/lessons.md`. Only add rules that would change future behavior."
60
- 3. **"If you're stuck" section** — add at end: "Check `docs/lessons.md` — a previous lesson may be relevant."
61
-
62
- ### finalizing (1 change)
63
-
64
- Add a new step before "Update documentation": "Review `docs/lessons.md` if it exists — add missed lessons, retire stale rules. Create it if lessons were learned but the file doesn't exist yet."
65
-
66
- ### brainstorming (1 change)
67
-
68
- Step 2 (understand the idea) — add after checking package.json/dependencies: "Check `docs/lessons.md` if it exists — known constraints and patterns may affect the design."
69
-
70
- ### writing-plans (1 change)
71
-
72
- Step 1 (check for a design doc) — add after reading relevant code: "Read `docs/lessons.md` if it exists — incorporate known patterns into the task breakdown."
73
-
74
- ## Slice
75
-
76
- Single slice: all 5 skill changes + file format convention. No new skills, extensions, or config.
@@ -1,219 +0,0 @@
1
- # Implementation Plan: Lessons Learned
2
-
3
- Design: `docs/plans/2026-05-08-lessons-learned-design.md`
4
-
5
- ## Overview
6
-
7
- Add a `docs/lessons.md` rules file that the agent reads at natural points in the workflow and writes to when it catches repeat mistakes. Changes are purely instructional — edits to 4 SKILL.md files plus documentation updates.
8
-
9
- No TypeScript code changes. No new extensions or skills. The existing `workflow-guard.ts` already allows writes to `docs/` during execute/finalize phases (it only blocks outside `docs/plans/` during brainstorm/plan). Since `docs/lessons.md` is at `docs/` level (not inside `docs/plans/`), it won't interfere with archiving.
10
-
11
- ---
12
-
13
- ## Task 1: Add lessons-learned read step to executing-tasks skill
14
-
15
- <!-- tdd: trivial -->
16
- <!-- checkpoint: done -->
17
-
18
- **File:** `skills/executing-tasks/SKILL.md`
19
-
20
- **Change 1** — In "Per-task execution", step 2, add a new bullet after the existing ones:
21
-
22
- ```
23
- - **Read `docs/lessons.md` if it exists** — follow all rules listed there while working on this task.
24
- ```
25
-
26
- The full step 2 should become:
27
-
28
- ```markdown
29
- 2. **Read the plan selectively** — read the plan's overview section (everything before `## Task 1:`). Skim all `## Task N:` headings for dependency awareness. Then read the current task's body in full. **Read `docs/lessons.md` if it exists** — follow all rules listed there while working on this task.
30
- ```
31
-
32
- **Change 2** — In "Per-task execution", insert a new step between step 9 (Refactor if needed) and step 10 (checkpoint: done). The new step becomes step 10, and all subsequent steps renumber by 1 (step 10→11, 11→12, 12→13, 13→14, 14→15):
33
-
34
- ```markdown
35
- 10. **Learn from mistakes** — if you caught yourself making a mistake during this task that you've made before or that would apply to future tasks, append a rule to `docs/lessons.md`. Only add rules that would change future behavior. If the file doesn't exist, create it with the standard format (see below). Do not add one-off errors or things you self-corrected immediately.
36
-
37
- **`docs/lessons.md` format:**
38
- ```markdown
39
- # Lessons Learned
40
-
41
- <!--
42
- Agent: read this at the start of each task during executing-tasks.
43
- Follow every rule. Add new rules when you catch yourself making repeat mistakes.
44
- Retire rules that no longer apply during finalizing.
45
- -->
46
-
47
- ## Rules
48
-
49
- - <new rule here>
50
- ```
51
- ```
52
-
53
- **Change 3** — In "If you're stuck" section, add a new item at the end:
54
-
55
- ```markdown
56
- 5. **Check `docs/lessons.md`** — a previous lesson may be relevant to your current problem.
57
- ```
58
-
59
- Renumber the existing item 4 to 5 if needed (it's currently the last item).
60
-
61
- **Command:**
62
- ```
63
- git add skills/executing-tasks/SKILL.md
64
- git commit -m "feat(executing-tasks): read and write lessons learned per task"
65
- ```
66
-
67
- ---
68
-
69
- ## Task 2: Add lessons-learned review step to finalizing skill
70
-
71
- <!-- tdd: trivial -->
72
- <!-- checkpoint: none -->
73
-
74
- **File:** `skills/finalizing/SKILL.md`
75
-
76
- Insert a new step between the existing step 1 (Move planning docs) and step 2 (Update documentation). The new step becomes step 2, and existing steps 2-4 renumber to 3-5:
77
-
78
- ```markdown
79
- 2. **Review lessons learned** — if `docs/lessons.md` exists, review it:
80
- - Add any lessons from this session that were missed during execution
81
- - Retire rules that no longer apply (remove the bullet)
82
- - If no changes are needed, leave it as-is
83
-
84
- If `docs/lessons.md` doesn't exist but lessons were learned this session, create it with the standard format:
85
-
86
- ```markdown
87
- # Lessons Learned
88
-
89
- <!--
90
- Agent: read this at the start of each task during executing-tasks.
91
- Follow every rule. Add new rules when you catch yourself making repeat mistakes.
92
- Retire rules that no longer apply during finalizing.
93
- -->
94
-
95
- ## Rules
96
-
97
- - <rule 1>
98
- - <rule 2>
99
- ```
100
- ```
101
-
102
- **Command:**
103
- ```
104
- git add skills/finalizing/SKILL.md
105
- git commit -m "feat(finalizing): review and update lessons learned"
106
- ```
107
-
108
- ---
109
-
110
- ## Task 3: Add lessons-learned read step to brainstorming skill
111
-
112
- <!-- tdd: trivial -->
113
- <!-- checkpoint: none -->
114
-
115
- **File:** `skills/brainstorming/SKILL.md`
116
-
117
- In step 2 (Understand the idea), add a new bullet after "check package.json/dependencies and module structure":
118
-
119
- ```markdown
120
- - **Check `docs/lessons.md`** if it exists — known constraints and patterns may affect the design.
121
- ```
122
-
123
- The full relevant part of step 2 should become:
124
-
125
- ```markdown
126
- 2. **Understand the idea** — read existing code, docs, and recent commits. Grep for related functionality, check package.json/dependencies and module structure. **Check `docs/lessons.md`** if it exists — known constraints and patterns may affect the design. Read only what's necessary to ground the design — don't read the entire codebase. Ask questions to refine the idea. Prefer multiple choice when possible. After each question, check: can you clearly articulate (a) what the user wants to build, (b) why, and (c) key constraints? If yes, present your understanding as a short summary and ask: "Should I proceed with this, or is there more to add?" The human decides when to move on.
127
- ```
128
-
129
- **Command:**
130
- ```
131
- git add skills/brainstorming/SKILL.md
132
- git commit -m "feat(brainstorming): read lessons learned for design context"
133
- ```
134
-
135
- ---
136
-
137
- ## Task 4: Add lessons-learned read step to writing-plans skill
138
-
139
- <!-- tdd: trivial -->
140
- <!-- checkpoint: none -->
141
-
142
- **File:** `skills/writing-plans/SKILL.md`
143
-
144
- In step 1 (Check for a design doc), add a new sentence after "If no design doc exists, ask the user to describe what they want to build and read relevant code.":
145
-
146
- ```markdown
147
- **Read `docs/lessons.md`** if it exists — incorporate known patterns into the task breakdown (e.g., if a lesson says "always run lint before commit," include that in relevant task instructions).
148
- ```
149
-
150
- **Command:**
151
- ```
152
- git add skills/writing-plans/SKILL.md
153
- git commit -m "feat(writing-plans): read lessons learned for task breakdown"
154
- ```
155
-
156
- ---
157
-
158
- ## Task 5: Update README.md with lessons-learned feature documentation
159
-
160
- <!-- tdd: trivial -->
161
- <!-- checkpoint: done -->
162
-
163
- **File:** `README.md`
164
-
165
- Add a new section after "TDD Three-Scenario Model" and before "Checkpoint Review Gates":
166
-
167
- ```markdown
168
- ### Lessons Learned
169
-
170
- A persistent rules file (`docs/lessons.md`) helps the agent learn from repeat mistakes across sessions. When the agent catches itself making the same error — like forgetting to run `make lint` — it writes a rule immediately. Future sessions (even after `/new`) pick it up automatically.
171
-
172
- ```
173
- brainstorm → reads lessons (design context)
174
- plan → reads lessons (task breakdown)
175
- execute → reads lessons per task, writes new ones on repeat mistakes
176
- finalize → reviews and retires stale rules
177
- ```
178
-
179
- Rules are simple imperative bullets:
180
-
181
- - After completing each task, run `make lint && make fmt` before committing
182
- - Never import `testify` in this project
183
- - Always check for existing test helpers before writing new ones
184
-
185
- No configuration needed — the file is created automatically when the first lesson is written.
186
- ```
187
-
188
- **Command:**
189
- ```
190
- git add README.md
191
- git commit -m "docs: add lessons-learned section to README"
192
- ```
193
-
194
- ---
195
-
196
- ## Task 6: Update CHANGELOG.md
197
-
198
- <!-- tdd: trivial -->
199
- <!-- checkpoint: none -->
200
-
201
- **File:** `CHANGELOG.md`
202
-
203
- Add a new entry at the top (after the header):
204
-
205
- ```markdown
206
- ## [0.13.0] - 2026-05-08
207
-
208
- ### Added
209
-
210
- - Lessons learned: persistent rules file (`docs/lessons.md`) read at every workflow phase and written to when the agent catches repeat mistakes. Survives `/new` sessions.
211
- ```
212
-
213
- Bump version in `package.json` from `0.12.0` to `0.13.0`.
214
-
215
- **Command:**
216
- ```
217
- git add CHANGELOG.md package.json
218
- git commit -m "chore: bump version to 0.13.0"
219
- ```
@@ -1,15 +0,0 @@
1
- # Progress: Lessons Learned
2
-
3
- Plan: docs/plans/2026-05-08-lessons-learned-implementation.md
4
- Branch: lessons-learned
5
- Started: 2026-05-08T04:21:50Z
6
- Last updated: 2026-05-08T04:27:15Z
7
-
8
- | # | Status | Task | Commit |
9
- |---|--------|------|--------|
10
- | 1 | ✅ done | Add lessons-learned read step to executing-tasks skill | 0ad24d6 |
11
- | 2 | ✅ done | Add lessons-learned review step to finalizing skill | 7ac8097 |
12
- | 3 | ✅ done | Add lessons-learned read step to brainstorming skill | 7cb69fe |
13
- | 4 | ✅ done | Add lessons-learned read step to writing-plans skill | ed0aab7 |
14
- | 5 | ✅ done | Update README.md with lessons-learned feature documentation | d16e407 |
15
- | 6 | ✅ done | Update CHANGELOG.md | 2525662 |