dev-playbooks 1.6.7 → 1.7.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/package.json +1 -1
- package/skills/devbooks-coder/SKILL.md +137 -350
- package/skills/devbooks-coder/references/completion-status-and-routing.md +74 -0
- package/skills/devbooks-coder/references/hotspot-awareness-and-risk-assessment.md +37 -0
- package/skills/devbooks-coder/references/test-execution-strategy.md +51 -0
- package/skills/devbooks-delivery-workflow/SKILL.md +47 -370
- package/skills/devbooks-delivery-workflow/references/gate-checks-and-error-handling.md +79 -0
- package/skills/devbooks-delivery-workflow/references/orchestration-logic-pseudocode.md +115 -0
- package/skills/devbooks-delivery-workflow/references/subagent-invocation-spec.md +42 -0
- package/skills/devbooks-test-owner/SKILL.md +156 -454
- package/skills/devbooks-test-owner/references/absolute-rules-and-constraints.md +108 -0
- package/skills/devbooks-test-owner/references/phase2-evidence-audit-checklist.md +125 -0
- package/skills/devbooks-test-owner/references/test-layering-and-execution-strategy.md +66 -0
- package/skills/devbooks-test-owner/references/verification-template-and-structure.md +139 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: devbooks-coder
|
|
3
|
-
description:
|
|
3
|
+
description: devbooks-coder: As the Coder role, strictly implements functionality according to tasks.md and runs gate tests, prohibited from modifying tests/, with tests/static checks as the sole completion criteria. Use when users say "implement according to plan/fix test failures/make gates green/implement task items/don't modify tests", or when executing as coder during DevBooks apply phase.
|
|
4
4
|
allowed-tools:
|
|
5
5
|
- Glob
|
|
6
6
|
- Grep
|
|
@@ -12,242 +12,172 @@ allowed-tools:
|
|
|
12
12
|
|
|
13
13
|
# DevBooks: Implementation Lead (Coder)
|
|
14
14
|
|
|
15
|
-
##
|
|
15
|
+
## Quick Start
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
My responsibilities:
|
|
18
|
+
1. **Strictly implement functionality according to tasks.md**
|
|
19
|
+
2. **Run fast-track tests** (@smoke + @critical)
|
|
20
|
+
3. **Trigger @full tests** (CI async)
|
|
21
|
+
4. **Prohibited from modifying tests/**
|
|
18
22
|
|
|
19
|
-
|
|
23
|
+
## Workflow Position
|
|
20
24
|
|
|
21
25
|
```
|
|
22
26
|
proposal → design → [TEST-OWNER] → [CODER] → [TEST-OWNER] → code-review → archive
|
|
23
27
|
↓ ↓
|
|
24
|
-
Implement+fast
|
|
25
|
-
(@smoke/@critical)
|
|
28
|
+
Implement+fast-track Evidence audit+check off
|
|
29
|
+
(@smoke/@critical) (no @full rerun)
|
|
26
30
|
```
|
|
27
31
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
> **Important Change**: This protocol is optimized for AI programming + solo development scenarios, **removing the mandatory "separate session" requirement**.
|
|
32
|
+
## AI Era Optimization
|
|
31
33
|
|
|
32
34
|
| Old Design | New Design | Reason |
|
|
33
35
|
|------------|------------|--------|
|
|
34
36
|
| Test Owner and Coder must use separate sessions | Same session, switch with `[TEST-OWNER]` / `[CODER]` mode labels | Reduce context rebuilding cost |
|
|
35
|
-
| Coder runs full tests and waits | Coder runs fast
|
|
36
|
-
|
|
|
37
|
-
|
|
38
|
-
### Coder's Responsibility Boundaries
|
|
37
|
+
| Coder runs full tests and waits for results | Coder runs fast-track (`@smoke`/`@critical`), `@full` triggered async | Fast iteration |
|
|
38
|
+
| Directly hand to Test Owner after completion | Status becomes `Implementation Done` after completion, wait for @full | Async doesn't block, archive syncs |
|
|
39
39
|
|
|
40
|
-
|
|
41
|
-
|---------|------------|
|
|
42
|
-
| Modify `src/**` code | ❌ Modify `tests/**` |
|
|
43
|
-
| Check off `tasks.md` items | ❌ Modify `verification.md` |
|
|
44
|
-
| Record deviations to `deviation-log.md` | ❌ Check off AC coverage matrix |
|
|
45
|
-
| Run fast track tests (`@smoke`/`@critical`) | ❌ Set verification.md Status to Verified/Done |
|
|
46
|
-
| Trigger `@full` tests (CI/background) | ❌ Wait for @full completion (can start next change) |
|
|
40
|
+
---
|
|
47
41
|
|
|
48
|
-
|
|
42
|
+
## Prerequisites: Configuration Discovery
|
|
49
43
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
- @full passes → Test Owner enters Phase 2 to audit evidence
|
|
56
|
-
- @full fails → Coder fixes
|
|
44
|
+
Before execution, **must** search for configuration in the following order (stop when found):
|
|
45
|
+
1. `.devbooks/config.yaml` (if exists) → Parse and use its mappings
|
|
46
|
+
2. `dev-playbooks/project.md` (if exists) → Dev-Playbooks protocol
|
|
47
|
+
3. `project.md` (if exists) → Template protocol
|
|
48
|
+
4. If still unable to determine → **Stop and ask user**
|
|
57
49
|
|
|
58
|
-
**Key
|
|
59
|
-
-
|
|
60
|
-
-
|
|
50
|
+
**Key Constraints**:
|
|
51
|
+
- If `agents_doc` (rules document) is specified in configuration, **must read that document first** before performing any operations
|
|
52
|
+
- Do not guess directory roots
|
|
61
53
|
|
|
62
54
|
---
|
|
63
55
|
|
|
64
|
-
##
|
|
56
|
+
## 📚 Reference Documentation
|
|
65
57
|
|
|
66
|
-
|
|
58
|
+
### Must Read (Read Immediately)
|
|
67
59
|
|
|
68
|
-
|
|
60
|
+
1. **Universal Gating Protocol**: `~/.claude/skills/_shared/references/universal-gating-protocol.md`
|
|
61
|
+
- Verifiability gating, structural quality gating, completeness gating
|
|
62
|
+
- Foundation rules for all skills
|
|
69
63
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
| `@critical` | Key functionality verification | Before commit | Minutes |
|
|
74
|
-
| `@full` | Complete acceptance tests | **Don't run**, trigger CI async | Can be slow |
|
|
64
|
+
2. **Code Implementation Prompt**: `references/code-implementation-prompt.md`
|
|
65
|
+
- Complete code implementation guide
|
|
66
|
+
- Strictly follow this prompt
|
|
75
67
|
|
|
76
|
-
###
|
|
68
|
+
### Read as Needed
|
|
77
69
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
70
|
+
3. **Test Execution Strategy**: `references/test-execution-strategy.md`
|
|
71
|
+
- @smoke/@critical/@full label details
|
|
72
|
+
- Async vs sync boundaries
|
|
73
|
+
- When to read: When needing to understand test run strategy
|
|
81
74
|
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
git push # triggers CI
|
|
87
|
-
# → Coder can start next task
|
|
88
|
-
```
|
|
75
|
+
4. **Completion Status and Routing**: `references/completion-status-and-routing.md`
|
|
76
|
+
- Completion status classification (MECE)
|
|
77
|
+
- Routing output template
|
|
78
|
+
- When to read: When outputting status upon task completion
|
|
89
79
|
|
|
90
|
-
|
|
80
|
+
5. **Hotspot Awareness and Risk Assessment**: `references/hotspot-awareness-and-risk-assessment.md`
|
|
81
|
+
- MCP enhancement features
|
|
82
|
+
- Hotspot file warnings
|
|
83
|
+
- When to read: When needing risk assessment
|
|
91
84
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
| `@critical` tests | Sync | Must pass before commit |
|
|
96
|
-
| `@full` tests | **Async** | CI runs in background, doesn't block Coder |
|
|
97
|
-
| Start next change | **Not blocked** | Coder can start immediately |
|
|
98
|
-
| Archive | **Blocked** | Must wait for @full to pass |
|
|
85
|
+
6. **Low Risk Modification Techniques**: `references/low-risk-modification-techniques.md`
|
|
86
|
+
- Safe refactoring techniques
|
|
87
|
+
- When to read: When needing refactoring
|
|
99
88
|
|
|
100
|
-
|
|
89
|
+
7. **Coding Style Guidelines**: `references/coding-style-guidelines.md`
|
|
90
|
+
- Code style specifications
|
|
91
|
+
- When to read: When uncertain about code style
|
|
101
92
|
|
|
102
|
-
|
|
93
|
+
8. **Logging Standard**: `references/logging-standard.md`
|
|
94
|
+
- Log levels and formats
|
|
95
|
+
- When to read: When needing to add logs
|
|
103
96
|
|
|
104
|
-
|
|
105
|
-
-
|
|
97
|
+
9. **Error Code Standard**: `references/error-code-standard.md`
|
|
98
|
+
- Error code design
|
|
99
|
+
- When to read: When needing to define error codes
|
|
106
100
|
|
|
107
|
-
|
|
108
|
-
1. `.devbooks/config.yaml` (if exists) -> Parse and use its mappings
|
|
109
|
-
2. `dev-playbooks/project.md` (if exists) -> Dev-Playbooks protocol, use default mappings
|
|
110
|
-
3. `project.md` (if exists) -> template protocol, use default mappings
|
|
111
|
-
5. If still unable to determine -> **Stop and ask the user**
|
|
101
|
+
---
|
|
112
102
|
|
|
113
|
-
|
|
114
|
-
- If the configuration specifies `agents_doc` (rules document), **you must read that document first** before performing any operations
|
|
115
|
-
- Do not guess directory roots
|
|
116
|
-
- Do not skip reading the rules document
|
|
103
|
+
## Core Workflow
|
|
117
104
|
|
|
118
|
-
|
|
105
|
+
### 1. Resume from Checkpoint
|
|
119
106
|
|
|
120
|
-
|
|
107
|
+
**Must** execute before each start:
|
|
121
108
|
|
|
122
|
-
1. **Read
|
|
123
|
-
2. **Locate
|
|
124
|
-
3. **Output
|
|
109
|
+
1. **Read progress**: Open `<change-root>/<change-id>/tasks.md`, identify checked `- [x]` tasks
|
|
110
|
+
2. **Locate resume point**: Find first `- [ ]` after "last `[x]`"
|
|
111
|
+
3. **Output confirmation**: Clearly inform user of current progress, e.g.:
|
|
125
112
|
```
|
|
126
|
-
Detected T1-T6 completed (6/10),
|
|
113
|
+
Detected T1-T6 completed (6/10), continuing from T7.
|
|
127
114
|
```
|
|
128
|
-
4. **Check Breakpoint Area**: If tasks.md has a "Breakpoint Area" record, prioritize restoring the breakpoint state
|
|
129
|
-
5. **Exception Handling**: If you find tasks that are "unchecked but code already exists", prompt the user for confirmation
|
|
130
|
-
|
|
131
|
-
### Breakpoint Area Format (at the end of tasks.md)
|
|
132
|
-
|
|
133
|
-
```markdown
|
|
134
|
-
### Breakpoint Area (Context Switch Breakpoint Area)
|
|
135
|
-
- Last progress: T6 completed, T7 started but not finished
|
|
136
|
-
- Current blocker: <blocking reason>
|
|
137
|
-
- Next shortest path: <suggested action>
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
---
|
|
141
115
|
|
|
142
|
-
|
|
116
|
+
### 2. Real-time Progress Updates
|
|
143
117
|
|
|
144
|
-
> **Core
|
|
118
|
+
> **Core Principle**: Complete one task, check off one immediately. Don't wait until all complete to batch check.
|
|
145
119
|
|
|
146
|
-
**
|
|
147
|
-
|
|
148
|
-
### Check Off Immediately After Each Task
|
|
149
|
-
|
|
150
|
-
After completing each task item in tasks.md, **immediately** change it from `- [ ]` to `- [x]`:
|
|
151
|
-
|
|
152
|
-
```markdown
|
|
153
|
-
# Before task completion
|
|
154
|
-
- [ ] MP1.1 Implement cache manager base structure
|
|
155
|
-
|
|
156
|
-
# After task completion, update immediately
|
|
157
|
-
- [x] MP1.1 Implement cache manager base structure
|
|
158
|
-
```
|
|
159
|
-
|
|
160
|
-
### Why Real-time Checking is Required
|
|
161
|
-
|
|
162
|
-
1. **Checkpoint Recovery**: Know exactly where to continue after interruption
|
|
163
|
-
2. **Visible Progress**: Both user and AI can clearly see current progress
|
|
164
|
-
3. **Avoid Forgetting**: Batch checking often leads to missing items
|
|
165
|
-
4. **Complete Evidence Chain**: Each checkmark represents a completed milestone
|
|
166
|
-
|
|
167
|
-
### When to Check Off
|
|
120
|
+
**Check-off Timing**:
|
|
168
121
|
|
|
169
122
|
| Timing | Action |
|
|
170
123
|
|--------|--------|
|
|
171
|
-
| Code writing complete |
|
|
172
|
-
| Compilation passes |
|
|
124
|
+
| Code writing complete | Don't check yet |
|
|
125
|
+
| Compilation passes | Don't check yet |
|
|
173
126
|
| Related tests pass | **Check immediately** |
|
|
174
|
-
| Multiple tasks
|
|
175
|
-
|
|
176
|
-
### Forbidden Behaviors
|
|
127
|
+
| Multiple tasks complete together | Check one by one, don't batch |
|
|
177
128
|
|
|
178
|
-
|
|
179
|
-
- ❌ Do not consider "code written = complete" without checking off
|
|
180
|
-
- ❌ Do not uncheck a checked item (unless rolling back code)
|
|
129
|
+
### 3. Implement Code
|
|
181
130
|
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
## Output Management Constraints (Observation Masking)
|
|
131
|
+
Strictly follow `references/code-implementation-prompt.md`.
|
|
185
132
|
|
|
186
|
-
|
|
133
|
+
### 4. Run Tests
|
|
187
134
|
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
| Test output | Extract key failure information, do not paste full output into conversation |
|
|
192
|
-
| Log output | Write to `<change-root>/<change-id>/evidence/`, only reference the path in conversation |
|
|
193
|
-
| Large file content | Reference path, do not inline |
|
|
194
|
-
|
|
195
|
-
**Example**:
|
|
196
|
-
```
|
|
197
|
-
BAD: Pasting 2000 lines of test logs
|
|
198
|
-
GOOD: 3 tests failed, see <change-root>/<change-id>/evidence/green-final/test-output.log
|
|
199
|
-
Key error: FAIL src/order.test.ts:45 - Expected 400, got 500
|
|
200
|
-
```
|
|
201
|
-
|
|
202
|
-
---
|
|
135
|
+
```bash
|
|
136
|
+
# During development: frequently run @smoke
|
|
137
|
+
npm test -- --grep "@smoke"
|
|
203
138
|
|
|
204
|
-
|
|
139
|
+
# Before commit: run @critical
|
|
140
|
+
npm test -- --grep "@smoke|@critical"
|
|
205
141
|
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
<change-root>/<change-id>/evidence/green-final/
|
|
142
|
+
# After commit: CI automatically runs @full (Coder doesn't wait)
|
|
143
|
+
git push # Trigger CI
|
|
209
144
|
```
|
|
210
145
|
|
|
211
|
-
|
|
212
|
-
- ❌ `./evidence/` (project root)
|
|
213
|
-
- ❌ `evidence/` (relative to current working directory)
|
|
214
|
-
|
|
215
|
-
**Correct path examples**:
|
|
216
|
-
```bash
|
|
217
|
-
# Dev-Playbooks default path
|
|
218
|
-
dev-playbooks/changes/<change-id>/evidence/green-final/test-$(date +%Y%m%d-%H%M%S).log
|
|
146
|
+
### 5. Output Completion Status
|
|
219
147
|
|
|
220
|
-
|
|
221
|
-
devbooks change-evidence <change-id> --label green-final -- npm test
|
|
222
|
-
```
|
|
148
|
+
Reference `references/completion-status-and-routing.md`.
|
|
223
149
|
|
|
224
150
|
---
|
|
225
151
|
|
|
226
152
|
## Key Constraints
|
|
227
153
|
|
|
228
|
-
### Role
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
154
|
+
### Role Boundaries
|
|
155
|
+
|
|
156
|
+
| Allowed | Prohibited |
|
|
157
|
+
|---------|------------|
|
|
158
|
+
| Modify `src/**` code | ❌ Modify `tests/**` |
|
|
159
|
+
| Check off `tasks.md` task items | ❌ Modify `verification.md` |
|
|
160
|
+
| Record deviations to `deviation-log.md` | ❌ Check off AC coverage matrix |
|
|
161
|
+
| Run fast-track tests (`@smoke`/`@critical`) | ❌ Set verification.md Status to Verified/Done |
|
|
162
|
+
| Trigger `@full` tests (CI/background) | ❌ Wait for @full completion (can start next change) |
|
|
233
163
|
|
|
234
164
|
### Code Quality Constraints
|
|
235
165
|
|
|
236
|
-
#### Prohibited Patterns
|
|
166
|
+
#### Prohibited Patterns for Commit
|
|
237
167
|
|
|
238
168
|
| Pattern | Detection Command | Reason |
|
|
239
169
|
|---------|-------------------|--------|
|
|
240
170
|
| `test.only` | `rg '\.only\s*\(' src/` | Skips other tests |
|
|
241
|
-
| `console.log` | `rg 'console\.log' src/` | Debug code
|
|
242
|
-
| `debugger` | `rg 'debugger' src/` | Debug breakpoint
|
|
243
|
-
| `// TODO` without issue | `rg 'TODO(?!.*#\d+)' src/` |
|
|
244
|
-
| `any` type | `rg ': any[^a-z]' src/` | Type safety
|
|
171
|
+
| `console.log` | `rg 'console\.log' src/` | Debug code remnants |
|
|
172
|
+
| `debugger` | `rg 'debugger' src/` | Debug breakpoint remnants |
|
|
173
|
+
| `// TODO` without issue | `rg 'TODO(?!.*#\d+)' src/` | Untraceable todos |
|
|
174
|
+
| `any` type | `rg ': any[^a-z]' src/` | Type safety holes |
|
|
245
175
|
| `@ts-ignore` | `rg '@ts-ignore' src/` | Hides type errors |
|
|
246
176
|
|
|
247
|
-
#### Pre-
|
|
177
|
+
#### Pre-commit Checks Required
|
|
248
178
|
|
|
249
179
|
```bash
|
|
250
|
-
# 1.
|
|
180
|
+
# 1. Compilation check (mandatory)
|
|
251
181
|
npm run compile || exit 1
|
|
252
182
|
|
|
253
183
|
# 2. Lint check (mandatory)
|
|
@@ -269,212 +199,69 @@ if rg -l 'console\.(log|debug)|debugger' src/ --type ts; then
|
|
|
269
199
|
fi
|
|
270
200
|
```
|
|
271
201
|
|
|
272
|
-
### Verification Prerequisites Constraints
|
|
273
|
-
|
|
274
|
-
**Core Requirement**: After each code modification, you must run verification commands and confirm they pass.
|
|
275
|
-
|
|
276
|
-
- [ ] Run `npm run compile` immediately after modifying code
|
|
277
|
-
- [ ] Run `npm run lint` after compilation passes
|
|
278
|
-
- [ ] Run `npm test` after lint passes
|
|
279
|
-
- [ ] Declaring "task complete" while verification fails is prohibited
|
|
280
|
-
- [ ] Verification command output must be recorded to evidence files
|
|
281
|
-
|
|
282
|
-
### Resource Cleanup Constraints
|
|
283
|
-
|
|
284
|
-
- [ ] Temporary files must be deleted when the task ends
|
|
285
|
-
- [ ] Background processes must be terminated when the task ends
|
|
286
|
-
- [ ] Cleanup must be performed regardless of success or failure
|
|
287
|
-
|
|
288
|
-
## Execution Method
|
|
289
|
-
|
|
290
|
-
1) First read and follow: `~/.claude/skills/_shared/references/universal-gating-protocol.md` (verifiability + structural quality gating).
|
|
291
|
-
2) Read low-risk modification techniques: `references/low-risk-modification-techniques.md` (read when needed).
|
|
292
|
-
3) Execute strictly according to the complete prompt: `references/code-implementation-prompt.md`.
|
|
293
|
-
|
|
294
202
|
---
|
|
295
203
|
|
|
296
|
-
##
|
|
297
|
-
|
|
298
|
-
This Skill automatically detects context before execution to ensure prerequisites are met.
|
|
299
|
-
|
|
300
|
-
Detection rules reference: `skills/_shared/context-detection-template-context-detection.md`
|
|
204
|
+
## Output Management
|
|
301
205
|
|
|
302
|
-
|
|
206
|
+
Prevent large outputs from polluting context:
|
|
303
207
|
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
208
|
+
| Scenario | Handling |
|
|
209
|
+
|----------|----------|
|
|
210
|
+
| Command output > 50 lines | Keep only first and last 10 lines + middle summary |
|
|
211
|
+
| Test output | Extract key failure info, don't paste full output in dialogue |
|
|
212
|
+
| Log output | Write to disk at `<change-root>/<change-id>/evidence/`, only reference path in dialogue |
|
|
213
|
+
| Large file contents | Reference path, don't inline |
|
|
310
214
|
|
|
311
|
-
|
|
312
|
-
|------|-------------------|----------|
|
|
313
|
-
| **First Implementation** | All items in tasks.md are `[ ]` | Start from MP1.1 |
|
|
314
|
-
| **Checkpoint Resume** | tasks.md has some `[x]` | Continue from the first `[ ]` after the last `[x]` |
|
|
315
|
-
| **Gate Fix** | Tests failed and need fixing | Prioritize fixing failed items |
|
|
215
|
+
---
|
|
316
216
|
|
|
317
|
-
|
|
217
|
+
## Evidence Path Convention
|
|
318
218
|
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
-
|
|
322
|
-
|
|
219
|
+
**Green evidence must be saved**:
|
|
220
|
+
```
|
|
221
|
+
<change-root>/<change-id>/evidence/green-final/
|
|
222
|
+
```
|
|
323
223
|
|
|
324
|
-
|
|
224
|
+
**Correct path examples**:
|
|
225
|
+
```bash
|
|
226
|
+
# Dev-Playbooks default path
|
|
227
|
+
dev-playbooks/changes/<change-id>/evidence/green-final/test-$(date +%Y%m%d-%H%M%S).log
|
|
325
228
|
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
- Artifact existence: tasks.md OK, verification.md OK
|
|
329
|
-
- Role isolation: OK (current session has not executed Test Owner)
|
|
330
|
-
- Progress: 6/10 completed
|
|
331
|
-
- Run mode: Checkpoint resume, continuing from MP1.7
|
|
229
|
+
# Using script
|
|
230
|
+
devbooks change-evidence <change-id> --label green-final -- npm test
|
|
332
231
|
```
|
|
333
232
|
|
|
334
233
|
---
|
|
335
234
|
|
|
336
|
-
## Deviation Detection and Persistence
|
|
337
|
-
|
|
338
|
-
**Reference**: `skills/_shared/references/deviation-detection-routing-protocol.md`
|
|
235
|
+
## Deviation Detection and Persistence
|
|
339
236
|
|
|
340
|
-
|
|
237
|
+
**Reference**: `~/.claude/skills/_shared/references/deviation-detection-routing-protocol.md`
|
|
341
238
|
|
|
342
|
-
During implementation,
|
|
239
|
+
During implementation, **must immediately** write to `deviation-log.md` in these situations:
|
|
343
240
|
|
|
344
241
|
| Situation | Type | Example |
|
|
345
242
|
|-----------|------|---------|
|
|
346
243
|
| Added functionality not in tasks.md | NEW_FEATURE | Added warmup() method |
|
|
347
|
-
| Modified
|
|
348
|
-
| Found
|
|
349
|
-
| Public interface
|
|
350
|
-
|
|
351
|
-
### deviation-log.md Format
|
|
352
|
-
|
|
353
|
-
```markdown
|
|
354
|
-
# Deviation Log
|
|
355
|
-
|
|
356
|
-
## Pending Backport Records
|
|
357
|
-
|
|
358
|
-
| Time | Type | Description | Affected Files | Backported |
|
|
359
|
-
|------|------|-------------|----------------|:----------:|
|
|
360
|
-
| 2024-01-15 10:30 | NEW_FEATURE | Added cache warmup feature | src/cache.ts | ❌ |
|
|
361
|
-
```
|
|
362
|
-
|
|
363
|
-
### Compact Protection
|
|
364
|
-
|
|
365
|
-
**Important**: deviation-log.md is a persistent file unaffected by compact. Even if the conversation is compressed, deviation information is preserved.
|
|
366
|
-
|
|
367
|
-
---
|
|
368
|
-
|
|
369
|
-
## Completion Status and Routing
|
|
370
|
-
|
|
371
|
-
### Completion Status Classification (MECE)
|
|
372
|
-
|
|
373
|
-
| Code | Status | Determination Criteria | Next Step |
|
|
374
|
-
|:----:|--------|------------------------|-----------|
|
|
375
|
-
| ✅ | IMPLEMENTATION_DONE | Fast track tests green, @full triggered, no deviations | Switch to `[TEST-OWNER]` wait for @full |
|
|
376
|
-
| ⚠️ | IMPLEMENTATION_DONE_WITH_DEVIATION | Fast track green, deviation-log has pending records | `devbooks-design-backport` |
|
|
377
|
-
| 🔄 | HANDOFF | Found test issues needing modification | Switch to `[TEST-OWNER]` mode to fix tests |
|
|
378
|
-
| ❌ | BLOCKED | Needs external input/decision | Record breakpoint, wait for user |
|
|
379
|
-
| 💥 | FAILED | Fast track tests not passing | Fix and retry |
|
|
380
|
-
|
|
381
|
-
### Status Determination Flow
|
|
382
|
-
|
|
383
|
-
```
|
|
384
|
-
1. Check if deviation-log.md has "| ❌" records
|
|
385
|
-
→ Yes: IMPLEMENTATION_DONE_WITH_DEVIATION
|
|
386
|
-
|
|
387
|
-
2. Check if tests/ modification needed
|
|
388
|
-
→ Yes: HANDOFF to [TEST-OWNER] mode
|
|
389
|
-
|
|
390
|
-
3. Check if fast track tests (@smoke + @critical) all pass
|
|
391
|
-
→ No: FAILED
|
|
392
|
-
|
|
393
|
-
4. Check if tasks.md is fully completed
|
|
394
|
-
→ No: BLOCKED or continue implementation
|
|
395
|
-
|
|
396
|
-
5. All checks passed, trigger @full
|
|
397
|
-
→ IMPLEMENTATION_DONE
|
|
398
|
-
```
|
|
399
|
-
|
|
400
|
-
### Routing Output Template (Required)
|
|
401
|
-
|
|
402
|
-
After completing coder, you **must** output in this format:
|
|
403
|
-
|
|
404
|
-
```markdown
|
|
405
|
-
## Completion Status
|
|
406
|
-
|
|
407
|
-
**Status**: ✅ IMPLEMENTATION_DONE / ⚠️ ... / 🔄 HANDOFF / ❌ BLOCKED / 💥 FAILED
|
|
408
|
-
|
|
409
|
-
**Task Progress**: X/Y completed
|
|
410
|
-
|
|
411
|
-
**Fast Track Tests**: @smoke ✅ / @critical ✅
|
|
412
|
-
|
|
413
|
-
**@full Tests**: Triggered (CI running async)
|
|
414
|
-
|
|
415
|
-
**Deviation Records**: Has N pending / None
|
|
416
|
-
|
|
417
|
-
## Next Step
|
|
418
|
-
|
|
419
|
-
**Recommended**: Switch to `[TEST-OWNER]` mode wait for @full / `devbooks-xxx skill`
|
|
420
|
-
|
|
421
|
-
**Reason**: [specific reason]
|
|
422
|
-
|
|
423
|
-
**Note**: Can start next change, no need to wait for @full completion
|
|
424
|
-
```
|
|
425
|
-
|
|
426
|
-
### Specific Routing Rules
|
|
427
|
-
|
|
428
|
-
| My Status | Next Step | Reason |
|
|
429
|
-
|-----------|-----------|--------|
|
|
430
|
-
| IMPLEMENTATION_DONE | Switch to `[TEST-OWNER]` mode (wait for @full) | Fast track green, wait for @full to pass then audit evidence |
|
|
431
|
-
| IMPLEMENTATION_DONE_WITH_DEVIATION | `devbooks-design-backport` | Backport design first |
|
|
432
|
-
| HANDOFF (test issue) | Switch to `[TEST-OWNER]` mode | Coder cannot modify tests |
|
|
433
|
-
| BLOCKED | Wait for user | Record breakpoint area |
|
|
434
|
-
| FAILED | Fix and retry | Analyze failure reason |
|
|
435
|
-
|
|
436
|
-
**Critical Constraints**:
|
|
437
|
-
- Coder **can never modify** `tests/**`
|
|
438
|
-
- If test issues found, must switch to `[TEST-OWNER]` mode to handle
|
|
439
|
-
- If deviations exist, must design-backport first before continuing
|
|
440
|
-
- **Coder completion status is `Implementation Done`, must wait for @full to pass before entering Test Owner Phase 2**
|
|
441
|
-
- **Mode switching replaces session isolation**: Use `[TEST-OWNER]` / `[CODER]` labels to switch modes
|
|
244
|
+
| Modified constraints in design.md | CONSTRAINT_CHANGE | Timeout changed to 60s |
|
|
245
|
+
| Found boundary case not covered by design | DESIGN_GAP | Concurrent write scenario |
|
|
246
|
+
| Public interface inconsistent with design | API_CHANGE | Parameter added |
|
|
442
247
|
|
|
443
248
|
---
|
|
444
249
|
|
|
445
|
-
##
|
|
446
|
-
|
|
447
|
-
This Skill supports MCP runtime enhancement, automatically detecting and enabling advanced features.
|
|
448
|
-
|
|
449
|
-
MCP enhancement rules reference: `skills/_shared/mcp-enhancement-template-mcp-enhancement.md`
|
|
450
|
-
|
|
451
|
-
### Required MCP Services
|
|
452
|
-
|
|
453
|
-
| Service | Purpose | Timeout |
|
|
454
|
-
|---------|---------|---------|
|
|
455
|
-
| `mcp__ckb__getHotspots` | Detect hotspot files, output warnings | 2s |
|
|
456
|
-
| `mcp__ckb__getStatus` | Detect CKB index availability | 2s |
|
|
457
|
-
|
|
458
|
-
### Detection Flow
|
|
459
|
-
|
|
460
|
-
1. Call `mcp__ckb__getStatus` (2s timeout)
|
|
461
|
-
2. If CKB available -> Call `mcp__ckb__getHotspots` to get hotspot files
|
|
462
|
-
3. If timeout or failure -> Degrade to basic mode (no hotspot warnings)
|
|
250
|
+
## Context Awareness
|
|
463
251
|
|
|
464
|
-
|
|
252
|
+
Detection rules reference: `~/.claude/skills/_shared/context-detection-template.md`
|
|
465
253
|
|
|
466
|
-
|
|
467
|
-
|---------|---------------|------------|
|
|
468
|
-
| Hotspot file warnings | CKB real-time analysis | Not available |
|
|
469
|
-
| Risk file identification | Automatic highlighting of high-hotspot changes | Manual identification |
|
|
470
|
-
| Code navigation | Symbol-level jumping | File-level search |
|
|
254
|
+
### Modes Supported by This Skill
|
|
471
255
|
|
|
472
|
-
|
|
256
|
+
| Mode | Trigger Condition | Behavior |
|
|
257
|
+
|------|-------------------|----------|
|
|
258
|
+
| **Initial Implementation** | All tasks.md are `[ ]` | Start from MP1.1 |
|
|
259
|
+
| **Resume from Checkpoint** | tasks.md has some `[x]` | Continue from first `[ ]` after last `[x]` |
|
|
260
|
+
| **Gate Fixing** | Test failures need fixing | Prioritize failed items |
|
|
473
261
|
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
```
|
|
477
|
-
WARNING: CKB unavailable, skipping hotspot detection.
|
|
478
|
-
To enable hotspot warnings, manually generate SCIP the index.
|
|
479
|
-
```
|
|
262
|
+
### Prerequisite Checks
|
|
480
263
|
|
|
264
|
+
- [ ] `tasks.md` exists
|
|
265
|
+
- [ ] `verification.md` exists
|
|
266
|
+
- [ ] Test Owner not executed in current session
|
|
267
|
+
- [ ] `tests/**` has test files
|