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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dev-playbooks",
3
- "version": "1.6.7",
3
+ "version": "1.7.0",
4
4
  "description": "AI-powered spec-driven development workflow",
5
5
  "keywords": [
6
6
  "devbooks",
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: devbooks-coder
3
- description: "devbooks-coder: Implements features strictly following tasks.md as the Coder role and runs quality gates. Modifying tests/ is prohibited; tests and static checks serve as the sole completion criteria. Use when the user says 'implement as planned/fix failing tests/make all gates green/implement task items/don't modify tests', or when executing as coder during the DevBooks apply phase."
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
- ## Workflow Position Awareness
15
+ ## Quick Start
16
16
 
17
- > **Core Principle**: Coder executes after Test Owner Phase 1, achieving mental clarity through **mode labels** (not session isolation).
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
- ### My Position in the Overall Workflow
23
+ ## Workflow Position
20
24
 
21
25
  ```
22
26
  proposal → design → [TEST-OWNER] → [CODER] → [TEST-OWNER] → code-review → archive
23
27
  ↓ ↓
24
- Implement+fast track Evidence audit
25
- (@smoke/@critical) (no @full rerun)
28
+ Implement+fast-track Evidence audit+check off
29
+ (@smoke/@critical) (no @full rerun)
26
30
  ```
27
31
 
28
- ### AI Era Solo Development Optimization
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 track (`@smoke`/`@critical`), `@full` triggered async | Fast iteration |
36
- | Completion goes directly to Test Owner | Completion status is `Implementation Done`, wait for @full | Async doesn't block, archive is sync |
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
- | Allowed | Prohibited |
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
- ### Flow After Coder Completes
42
+ ## Prerequisites: Configuration Discovery
49
43
 
50
- 1. **Fast track tests green**: `@smoke` + `@critical` pass
51
- 2. **Trigger @full**: Commit code, CI starts running @full tests async
52
- 3. **Status change**: Set change status to `Implementation Done`
53
- 4. **Can start next change** (not blocked)
54
- 5. **Wait for @full results**:
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 Reminders**:
59
- - After Coder completes, status is `Implementation Done`, **not directly to Code Review**
60
- - Dev iteration is async (can start next change), but archive is sync (must wait for @full to pass)
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
- ## Test Layering and Run Strategy (Critical!)
56
+ ## 📚 Reference Documentation
65
57
 
66
- > **Core Principle**: Coder only runs fast track tests, @full tests are triggered async, not blocking dev iteration.
58
+ ### Must Read (Read Immediately)
67
59
 
68
- ### Test Layering Labels
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
- | Label | Purpose | When Coder Runs | Expected Time |
71
- |-------|---------|-----------------|---------------|
72
- | `@smoke` | Fast feedback, core paths | After each code change | Seconds |
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
- ### Coder's Test Run Strategy
68
+ ### Read as Needed
77
69
 
78
- ```bash
79
- # During development: frequently run @smoke
80
- npm test -- --grep "@smoke"
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
- # Before commit: run @critical
83
- npm test -- --grep "@smoke|@critical"
84
-
85
- # After commit: CI automatically runs @full (Coder doesn't wait)
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
- ### Async vs Sync Boundary
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
- | Action | Blocking/Async | Description |
93
- |--------|----------------|-------------|
94
- | `@smoke` tests | Sync | Run immediately after each change |
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
- ## Prerequisites: Configuration Discovery (Protocol-Agnostic)
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
- - `<truth-root>`: Current truth directory root
105
- - `<change-root>`: Change package directory root
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
- Before execution, you **must** search for configuration in the following order (stop when found):
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
- **Key Constraints**:
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
- ## Checkpoint Resume Protocol (Plan Persistence)
105
+ ### 1. Resume from Checkpoint
119
106
 
120
- You **must** perform the following steps at the start of each session:
107
+ **Must** execute before each start:
121
108
 
122
- 1. **Read Progress**: Open `<change-root>/<change-id>/tasks.md`, identify tasks marked with `- [x]`
123
- 2. **Locate Resume Point**: Find the first `- [ ]` after the "last `[x]`"
124
- 3. **Output Confirmation**: Clearly inform the user of current progress, for example:
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), resuming from T7.
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
- ## Real-time Progress Update Protocol
116
+ ### 2. Real-time Progress Updates
143
117
 
144
- > **Core principle**: Complete one task, check it off immediately. Never batch-check at the end.
118
+ > **Core Principle**: Complete one task, check off one immediately. Don't wait until all complete to batch check.
145
119
 
146
- **Must follow**:
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 | Do not check yet |
172
- | Compilation passes | Do not check yet |
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 completed together | Check one by one, not in batch |
175
-
176
- ### Forbidden Behaviors
127
+ | Multiple tasks complete together | Check one by one, don't batch |
177
128
 
178
- - Do not wait until all tasks are done to batch-check
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
- Prevent large outputs from polluting the context:
133
+ ### 4. Run Tests
187
134
 
188
- | Scenario | Handling Method |
189
- |----------|-----------------|
190
- | Command output > 50 lines | Keep only first and last 10 lines + middle summary |
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
- ## Evidence Path Convention (Mandatory)
139
+ # Before commit: run @critical
140
+ npm test -- --grep "@smoke|@critical"
205
141
 
206
- **Green evidence must be saved to the change package directory**:
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
- **Forbidden paths**:
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
- # Using the script
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 Boundary Constraints
229
- - **Modifying `tests/**` is prohibited** (changes to tests must be handed back to Test Owner)
230
- - **Modifying `verification.md` is prohibited** (maintained by Test Owner)
231
- - **Modifying `verification.md` Status field is prohibited** (only Reviewer can set it to Done)
232
- - **Modifying `.devbooks/`, `build/`, or engineering configuration files is prohibited** (unless explicitly stated in proposal.md)
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 residue |
242
- | `debugger` | `rg 'debugger' src/` | Debug breakpoint residue |
243
- | `// TODO` without issue | `rg 'TODO(?!.*#\d+)' src/` | Untrackable todos |
244
- | `any` type | `rg ': any[^a-z]' src/` | Type safety vulnerability |
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-Commit Checks (Required)
177
+ #### Pre-commit Checks Required
248
178
 
249
179
  ```bash
250
- # 1. Compile check (mandatory)
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
- ## Context Awareness
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
- ### Detection Flow
206
+ Prevent large outputs from polluting context:
303
207
 
304
- 1. Detect if `tasks.md` exists
305
- 2. Detect if `verification.md` exists (Test Owner has completed)
306
- 3. Detect if the current session has already executed the Test Owner role
307
- 4. Identify progress in tasks.md (completed/pending)
308
-
309
- ### Supported Modes for This Skill
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
- | Mode | Trigger Condition | Behavior |
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
- ### Prerequisites Checklist
217
+ ## Evidence Path Convention
318
218
 
319
- - [ ] `tasks.md` exists
320
- - [ ] `verification.md` exists
321
- - [ ] Current session has not executed Test Owner
322
- - [ ] `tests/**` has test files
219
+ **Green evidence must be saved**:
220
+ ```
221
+ <change-root>/<change-id>/evidence/green-final/
222
+ ```
323
223
 
324
- ### Detection Output Example
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
- Detection Results:
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 Protocol
337
-
338
- **Reference**: `skills/_shared/references/deviation-detection-routing-protocol.md`
235
+ ## Deviation Detection and Persistence
339
236
 
340
- ### Real-time Persistence Requirements
237
+ **Reference**: `~/.claude/skills/_shared/references/deviation-detection-routing-protocol.md`
341
238
 
342
- During implementation, you **must immediately** write to `deviation-log.md` in these situations:
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 constraint from design.md | CONSTRAINT_CHANGE | Timeout changed to 60s |
348
- | Found edge case not covered by design | DESIGN_GAP | Concurrency scenario |
349
- | Public interface differs from design | API_CHANGE | Added parameter |
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
- ## MCP Enhancement
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
- ### Enhanced Mode vs Basic Mode
252
+ Detection rules reference: `~/.claude/skills/_shared/context-detection-template.md`
465
253
 
466
- | Feature | Enhanced Mode | Basic Mode |
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
- ### Degradation Notice
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
- When MCP is unavailable, output the following notice:
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