You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
→ Update TODO.md: mark @id [x], update Cycle State to next test
37
38
→ pick next failing test
38
39
```
39
40
40
41
**Hard gates**: The cycle has two hard gates — you must STOP before the reviewer check, and WAIT for APPROVED before committing. Never batch multiple tests before a reviewer interaction. Never commit without reviewer approval.
41
42
42
43
Never write production code before picking a specific failing test. Never refactor while tests are red.
43
44
45
+
**TODO.md Cycle State is mandatory.** Update `## Cycle State` at every phase transition (RED → GREEN → REFACTOR → REVIEWER → COMMITTED). If the Cycle State block is missing, add it before proceeding.
46
+
44
47
## Step 2 — Architecture (do this first)
45
48
46
-
Before writing any production code, add `## Architecture` to `docs/features/in-progress/<name>/discovery.md`:
49
+
**Prerequisites — verify before starting:**
50
+
1.`docs/features/in-progress/` contains only `.gitkeep` (no feature folders). If another feature folder exists, **STOP** — another feature is already in progress.
51
+
2. The feature's `discovery.md` has `Status: BASELINED`. If not, escalate to the PO — Step 1 is incomplete.
52
+
3. At least one `.feature` file in the feature folder contains `Example:` blocks with `@id` tags. If not, escalate to PO — criteria have not been written.
53
+
54
+
**Steps:**
47
55
48
56
1. Move the feature folder from `backlog/` to `in-progress/`:
2. Read both `docs/features/discovery.md` (project-level) and the feature's `discovery.md`
53
-
3. Run a silent pre-mortem: design patterns, SOLID, DRY, KISS, Object Calisthenics
54
-
4. Add the Architecture section:
60
+
2. Update `TODO.md` Source path from `backlog/` to `in-progress/`.
61
+
3. Read both `docs/features/discovery.md` (project-level) and the feature's `discovery.md`
62
+
4. Run a silent pre-mortem: YAGNI, KISS, DRY, SOLID, Object Calisthenics, design patterns
63
+
5. Add the Architecture section to `docs/features/in-progress/<name>/discovery.md`:
55
64
56
65
```markdown
57
66
## Architecture
@@ -70,12 +79,15 @@ Alternatives considered: <what was rejected and why>
70
79
- New runtime dependency: <name> — reason: <why>
71
80
```
72
81
73
-
5.**Architecture contradiction check**: Compare each ADR against each AC. If any architectural decision contradicts or circumvents an acceptance criterion, flag it and resolve with the PO before writing any production code.
74
-
6. If a user story is not technically feasible, escalate to the PO.
75
-
7. If any build changes need PO approval, stop and ask before proceeding.
82
+
6.**Architecture contradiction check**: Compare each ADR against each AC. If any architectural decision contradicts or circumvents an acceptance criterion, flag it and resolve with the PO before writing any production code.
83
+
7.**PO domain acknowledgement**: Share the Architecture section with the PO for domain model acknowledgement before Step 3 begins. A one-line response ("no contradictions") is sufficient.
84
+
8. If a user story is not technically feasible, escalate to the PO.
85
+
9. If any build changes need PO approval, stop and ask before proceeding.
76
86
77
87
Commit: `feat(<feature-name>): add architecture`
78
88
89
+
**After committing:** Run `uv run task gen-tests -- --check` to verify stub sync. If changes are shown, run `uv run task gen-tests` to apply them.
90
+
79
91
## Implementation Order
80
92
81
93
1. Start with the simplest test: data classes, value objects, pure functions
@@ -90,6 +102,12 @@ uv run pytest tests/features/<name>/<story>_test.py::test_<func> -v
90
102
91
103
Expected: `FAILED` or `ERROR`. If it passes before you've written code, the test is wrong — fix it.
92
104
105
+
Update `## Cycle State` in TODO.md:
106
+
```
107
+
Test: `@id:<hex>` — <description>
108
+
Phase: RED
109
+
```
110
+
93
111
## GREEN — Minimum Implementation
94
112
95
113
Write the least code that makes **this one test** pass. "Green" means the specific test under work passes — not the full suite.
@@ -105,6 +123,8 @@ uv run pytest tests/features/<name>/<story>_test.py::test_<func> -v # this tes
105
123
uv run task test-fast # no regressions
106
124
```
107
125
126
+
Update `## Cycle State` Phase: `GREEN`
127
+
108
128
## REFACTOR — Apply Principles (in priority order)
109
129
110
130
1.**DRY**: extract duplication
@@ -146,6 +166,14 @@ Use when a pattern solves a structural problem you already have:
| Event-driven flow | Observer or pub/sub | Decouples producers from consumers |
148
168
169
+
### Doctest Check
170
+
171
+
If you added or modified a `Examples:` block in a Google-style docstring, verify it passes:
172
+
173
+
```bash
174
+
uv run pytest --doctest-modules <module_path>
175
+
```
176
+
149
177
> **Note**: `uv run task test` runs `--doctest-modules`. Keep `Examples:` blocks in Google-style docstrings valid and executable.
150
178
151
179
```bash
@@ -154,12 +182,19 @@ uv run task test-fast # must still pass — the ONLY check during refactor
154
182
155
183
Do NOT run `uv run task lint` or `uv run task static-check` during the cycle. Those are handoff-only checks (before Step 5).
156
184
185
+
Update `## Cycle State` Phase: `REFACTOR`
186
+
157
187
## REVIEWER CHECK — Code Design Only
158
188
159
-
After each test goes green + refactor, **STOP** and request a reviewer check. The reviewer loads the `verify` skill but is scoped to **code design only**:
189
+
After each test goes green + refactor, **STOP** and request a reviewer check.
190
+
191
+
**STOP — request a reviewer check of code design and semantic alignment.**
192
+
**WAIT for APPROVED before committing.**
193
+
194
+
The reviewer is scoped to **code design only** (not full Step 5):
160
195
161
196
**What the reviewer checks (code-design scope)**:
162
-
-**YAGNI, KISS, DRY, SOLID, Object Calisthenics** — are design principles followed in priority order?
197
+
-**YAGNI > KISS > DRY > SOLID > Object Calisthenics** — are design principles followed in priority order?
163
198
-**Appropriate design patterns** — is the code structure right for the problem?
164
199
-**Semantic alignment** — does the test operate at the same abstraction level as the AC?
165
200
-**No internal-state testing** — assertions on observable behavior, not private attributes
@@ -170,7 +205,26 @@ After each test goes green + refactor, **STOP** and request a reviewer check. Th
170
205
- Coverage metrics
171
206
- Full test suite
172
207
173
-
The reviewer responds with **APPROVED** or **REJECTED** with specific issues. If REJECTED, fix the issues and request review again. This is a **hard gate** — do not commit until APPROVED.
208
+
The reviewer responds using this template:
209
+
210
+
```markdown
211
+
## Code-Design Check — @id:<hex>
212
+
213
+
Design principles: PASS/FAIL — <note>
214
+
Semantic alignment: PASS/FAIL — <note>
215
+
Decision: APPROVED / REJECTED
216
+
```
217
+
218
+
If REJECTED:
219
+
- Mark the `@id` row as `[~]` in TODO.md (do not downgrade to `[ ]`)
220
+
- Update `## Cycle State` Phase to `REVIEWER(code-design)`
221
+
- Fix the specific issues raised
222
+
- Do not commit
223
+
- Request re-review after fix
224
+
225
+
This is a **hard gate** — do not commit until APPROVED.
3. Run `git status` — understand what is committed vs. what is not
21
22
4. Confirm scope: you are working on exactly one step of one feature
22
23
23
-
If TODO.md says "No feature in progress", check `docs/features/backlog/` for feature folders. If the backlog is empty, the PO needs to define the next feature.
24
+
If TODO.md says "No feature in progress", report to the PO that backlog features are waiting. **The developer never self-selects a feature from the backlog — only the PO picks.**
24
25
25
26
## Session End
26
27
27
28
1. Update TODO.md:
28
29
- Mark completed criteria `[x]`
29
30
- Mark in-progress criteria `[~]`
30
31
- Update the "Next" line with one concrete action
31
-
2. Commit any uncommitted work (even WIP):
32
+
2. Run `uv run task gen-todo` to sync any new @id rows from .feature files into TODO.md.
33
+
3. Commit any uncommitted work (even WIP):
32
34
```bash
33
35
git add -A
34
36
git commit -m "WIP(<feature-name>): <what was done>"
35
37
```
36
-
3. If a step is fully complete, use the proper commit message instead of WIP.
38
+
4. If a step is fully complete, use the proper commit message instead of WIP.
39
+
40
+
## Step Completion Protocol
41
+
42
+
When a step completes within a session:
43
+
44
+
1. Update TODO.md to reflect the completed step before doing any other work.
45
+
2. Commit the TODO.md update:
46
+
```bash
47
+
git add TODO.md
48
+
git commit -m "chore: complete step <N> for <feature-name>"
49
+
```
50
+
3. Only then begin the next step (in a new session where possible — see Rule 4).
@@ -69,7 +88,7 @@ Next: PO picks feature from docs/features/backlog/ and moves it to docs/features
69
88
70
89
## Step 4 Cycle-Aware TODO Format
71
90
72
-
During Step 4 (Implementation), the TODO.md format includes cycle state to track Red-Green-Refactor-Review progress:
91
+
During Step 4 (Implementation), TODO.md **must** include a `## Cycle State` block to track Red-Green-Refactor-Review progress. This block is **mandatory** — missing it means the cycle is unverifiable.
0 commit comments