@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.
- package/README.md +91 -64
- package/agents/pwk-hazard-reviewer.md +24 -0
- package/agents/pwk-smell-reviewer.md +17 -0
- package/agents/pwk-spec-reviewer.md +14 -0
- package/agents/pwk-tracing-reviewer.md +14 -0
- package/docs/developer-usage-guide.md +49 -37
- package/docs/lessons.md +13 -0
- package/docs/oversight-model.md +19 -9
- package/docs/workflow-phases.md +58 -29
- package/extensions/workflow-guard.ts +190 -91
- package/package.json +19 -3
- package/skills/pwk-brainstorming/SKILL.md +60 -0
- package/skills/pwk-code-review/SKILL.md +46 -0
- package/skills/{diagnose → pwk-diagnose}/SKILL.md +3 -2
- package/skills/pwk-executing-tasks/SKILL.md +154 -0
- package/skills/pwk-finalizing/SKILL.md +78 -0
- package/skills/pwk-status/SKILL.md +28 -0
- package/skills/pwk-writing-plans/SKILL.md +83 -0
- package/docs/plans/2026-06-03-karpathy-guidelines-ab-comparison.md +0 -166
- package/docs/plans/completed/2026-04-11-checkpoint-review-gates-design.md +0 -50
- package/docs/plans/completed/2026-04-11-checkpoint-review-gates-implementation.md +0 -98
- package/docs/plans/completed/2026-04-11-finalizing-merge-options-design.md +0 -33
- package/docs/plans/completed/2026-04-11-finalizing-merge-options-implementation.md +0 -75
- package/docs/plans/completed/2026-04-11-workspace-setup-design.md +0 -28
- package/docs/plans/completed/2026-04-11-workspace-setup-implementation.md +0 -57
- package/docs/plans/completed/2026-04-15-bash-guard-design.md +0 -39
- package/docs/plans/completed/2026-04-15-bash-guard-implementation.md +0 -229
- package/docs/plans/completed/2026-04-21-workflow-guard-safe-commands-design.md +0 -172
- package/docs/plans/completed/2026-04-21-workflow-guard-safe-commands-implementation.md +0 -168
- package/docs/plans/completed/2026-04-22-go-readonly-safe-commands-implementation.md +0 -54
- package/docs/plans/completed/2026-04-28-executing-tasks-redesign-design.md +0 -171
- package/docs/plans/completed/2026-04-28-executing-tasks-redesign-implementation.md +0 -208
- package/docs/plans/completed/2026-04-28-executing-tasks-redesign-progress.md +0 -14
- package/docs/plans/completed/2026-05-01-incorporate-mattpocock-skills-design.md +0 -154
- package/docs/plans/completed/2026-05-01-incorporate-mattpocock-skills-implementation.md +0 -315
- package/docs/plans/completed/2026-05-01-incorporate-mattpocock-skills-progress.md +0 -15
- package/docs/plans/completed/2026-05-08-checkpoint-gates-design.md +0 -235
- package/docs/plans/completed/2026-05-08-checkpoint-gates-implementation.md +0 -83
- package/docs/plans/completed/2026-05-08-checkpoint-gates-progress.md +0 -11
- package/docs/plans/completed/2026-05-08-lessons-learned-design.md +0 -76
- package/docs/plans/completed/2026-05-08-lessons-learned-implementation.md +0 -219
- package/docs/plans/completed/2026-05-08-lessons-learned-progress.md +0 -15
- package/docs/plans/completed/2026-05-08-migrate-earendil-works-design.md +0 -39
- package/docs/plans/completed/2026-05-08-migrate-earendil-works-implementation.md +0 -45
- package/docs/plans/completed/2026-05-08-migrate-earendil-works-progress.md +0 -10
- package/docs/plans/completed/2026-05-08-worktree-handoff-design.md +0 -118
- package/docs/plans/completed/2026-05-08-worktree-handoff-implementation.md +0 -140
- package/docs/plans/completed/2026-05-08-worktree-handoff-progress.md +0 -10
- package/docs/plans/completed/2026-05-20-generic-lessons-design.md +0 -70
- package/docs/plans/completed/2026-05-20-generic-lessons-implementation.md +0 -114
- package/docs/plans/completed/2026-05-20-generic-lessons-progress.md +0 -11
- package/docs/plans/completed/2026-05-22-agentic-agile-enhancements-design.md +0 -77
- package/docs/plans/completed/2026-05-22-agentic-agile-enhancements-implementation.md +0 -473
- package/docs/plans/completed/2026-05-25-design-review-split-implementation.md +0 -622
- package/docs/plans/completed/2026-05-25-design-review-split-progress.md +0 -16
- package/docs/plans/completed/2026-05-25-pr5-improvements-implementation.md +0 -273
- package/docs/plans/completed/2026-05-25-pr5-improvements-progress.md +0 -17
- package/docs/plans/completed/2026-06-03-add-verify-skill-design.md +0 -51
- package/docs/plans/completed/2026-06-03-add-verify-skill-implementation.md +0 -111
- package/docs/plans/completed/2026-06-03-add-verify-skill-progress.md +0 -11
- package/docs/plans/completed/2026-06-03-verify-skill-design.md +0 -176
- package/skills/brainstorming/SKILL.md +0 -48
- package/skills/design-review/SKILL.md +0 -113
- package/skills/executing-tasks/SKILL.md +0 -350
- package/skills/finalizing/SKILL.md +0 -119
- package/skills/verify/SKILL.md +0 -170
- 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 |
|