dev-playbooks 2.2.1 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/README.md +133 -462
  3. package/package.json +1 -1
  4. package/scripts/config-discovery.sh +1 -1
  5. package/scripts/detect-mcp.sh +86 -0
  6. package/skills/Skill-Development-Guide.md +1 -2
  7. package/skills/_shared/mcp-enhancement-template-mcp-enhancement.md +30 -113
  8. package/skills/_shared/references/completeness-thinking-framework.md +86 -0
  9. package/skills/_shared/references/human-advice-calibration-prompt.md +27 -0
  10. package/skills/devbooks-archiver/SKILL.md +20 -12
  11. package/skills/devbooks-archiver/references/archiver-prompt.md +66 -38
  12. package/skills/devbooks-brownfield-bootstrap/SKILL.md +32 -65
  13. package/skills/devbooks-coder/SKILL.md +61 -240
  14. package/skills/devbooks-coder/references/completion-status-and-routing.md +8 -8
  15. package/skills/devbooks-convergence-audit/SKILL.md +20 -0
  16. package/skills/devbooks-delivery-workflow/SKILL.md +26 -227
  17. package/skills/devbooks-delivery-workflow/references/orchestration-bans-and-stage-table.md +45 -0
  18. package/skills/devbooks-design-backport/SKILL.md +16 -3
  19. package/skills/devbooks-design-doc/SKILL.md +21 -9
  20. package/skills/devbooks-docs-consistency/SKILL.md +170 -0
  21. package/skills/devbooks-docs-consistency/references/completeness-dimensions.yaml +31 -0
  22. package/skills/devbooks-docs-consistency/references/doc-classification.yaml +11 -0
  23. package/skills/devbooks-docs-consistency/references/docs-rules-schema.yaml +11 -0
  24. package/skills/devbooks-docs-consistency/scripts/alias.sh +5 -0
  25. package/skills/devbooks-docs-consistency/scripts/completeness-checker.sh +153 -0
  26. package/skills/devbooks-docs-consistency/scripts/doc-classifier.sh +121 -0
  27. package/skills/devbooks-docs-consistency/scripts/git-adapter.sh +32 -0
  28. package/skills/devbooks-docs-consistency/scripts/rules-engine.sh +255 -0
  29. package/skills/devbooks-docs-consistency/scripts/scanner.sh +93 -0
  30. package/skills/devbooks-docs-consistency/scripts/style-checker.sh +123 -0
  31. package/skills/devbooks-docs-sync/SKILL.md +23 -318
  32. package/skills/devbooks-entropy-monitor/SKILL.md +15 -32
  33. package/skills/devbooks-impact-analysis/SKILL.md +26 -46
  34. package/skills/devbooks-implementation-plan/SKILL.md +23 -9
  35. package/skills/devbooks-proposal-author/SKILL.md +21 -15
  36. package/skills/devbooks-proposal-challenger/SKILL.md +16 -3
  37. package/skills/devbooks-proposal-judge/SKILL.md +16 -3
  38. package/skills/devbooks-reviewer/SKILL.md +23 -42
  39. package/skills/devbooks-router/SKILL.md +22 -356
  40. package/skills/devbooks-router/references/routing-rules-and-templates.md +120 -0
  41. package/skills/devbooks-spec-contract/SKILL.md +23 -39
  42. package/skills/devbooks-test-owner/SKILL.md +68 -309
  43. package/skills/devbooks-test-reviewer/SKILL.md +15 -5
@@ -11,6 +11,26 @@ allowed-tools:
11
11
 
12
12
  # DevBooks: Proposal Author
13
13
 
14
+ ## Progressive Disclosure
15
+
16
+ ### Base (Required)
17
+ Goal: Produce a reviewable `proposal.md` (Why/What/Impact) and keep it ready for challenge/judge.
18
+ Inputs: user goal, existing documents, change package context, or project path.
19
+ Outputs: `<change-root>/<change-id>/proposal.md` (and updated Decision Log when needed).
20
+ Boundaries: proposal stage only; do not write implementation steps; do not touch `tests/`.
21
+ Evidence: reference artifact paths and the decision/judge status.
22
+
23
+ ### Advanced (Optional)
24
+ Use when you need: option sets, risk framing, open questions, debate packet structuring.
25
+
26
+ ### Extended (Optional)
27
+ Use when you need: faster search/impact via optional MCP capabilities.
28
+
29
+ ## Recommended MCP Capability Types
30
+ - Code search (code-search)
31
+ - Reference tracking (reference-tracking)
32
+ - Impact analysis (impact-analysis)
33
+
14
34
  ## Prerequisites: Configuration Discovery (Protocol Agnostic)
15
35
 
16
36
  - `<truth-root>`: Current truth directory root
@@ -78,12 +98,6 @@ oauth2-20240116 # Wrong order
78
98
  | `improve` | Improve performance/experience |
79
99
  | `migrate` | Migrate data/system |
80
100
 
81
- ### Why This Naming Convention?
82
-
83
- 1. **Timestamp first**: Auto-sorts by time in archive directory
84
- 2. **Verb prefix**: Clearly expresses change intent, aids code review
85
- 3. **Lowercase hyphens**: Avoids cross-platform filename issues
86
-
87
101
  ### Creating Change Package
88
102
 
89
103
  After determining the change-id, call the scaffold script to initialize the change package:
@@ -165,19 +179,11 @@ OR
165
179
  OR
166
180
  **Next: `devbooks-proposal-challenger`** (if high risk, optional)
167
181
 
168
- Reason: Proposal is complete. The next step is to [clarify impact / create design document].
182
+ Next: [clarify impact / create design document].
169
183
 
170
184
  ### How to invoke
171
185
  ```
172
186
  Run devbooks-<skill-name> skill for change <change-id>
173
187
  ```
174
- ```
175
188
 
176
189
  ---
177
-
178
- ## MCP Enhancement
179
-
180
- This Skill does not depend on MCP services and requires no runtime detection.
181
-
182
- MCP enhancement rules reference: `skills/_shared/mcp-enhancement-template-mcp-enhancement.md`
183
-
@@ -78,9 +78,22 @@ Detection Result:
78
78
 
79
79
  ---
80
80
 
81
- ## MCP Enhancement
82
81
 
83
- This Skill does not depend on MCP services, no runtime detection needed.
82
+ ## Progressive Disclosure
83
+ ### Base (Required)
84
+ Goal: Clarify this Skill's core outputs and usage scope.
85
+ Inputs: User goals, existing documents, change package context, or project path.
86
+ Outputs: Executable artifacts, next-step guidance, or recorded paths.
87
+ Boundaries: Does not replace other roles; does not touch `tests/`.
88
+ Evidence: Reference output paths or execution records.
84
89
 
85
- MCP enhancement rules reference: `skills/_shared/mcp-enhancement-template-mcp-enhancement.md`
90
+ ### Advanced (Optional)
91
+ Use when you need to refine strategy, boundaries, or risk notes.
86
92
 
93
+ ### Extended (Optional)
94
+ Use when you need to coordinate with external systems or optional tools.
95
+
96
+ ## Recommended MCP Capability Types
97
+ - Code search (code-search)
98
+ - Reference tracking (reference-tracking)
99
+ - Impact analysis (impact-analysis)
@@ -70,9 +70,22 @@ Detection Result:
70
70
 
71
71
  ---
72
72
 
73
- ## MCP Enhancement
74
73
 
75
- This Skill does not depend on MCP services and requires no runtime detection.
74
+ ## Progressive Disclosure
75
+ ### Base (Required)
76
+ Goal: Clarify this Skill's core outputs and usage scope.
77
+ Inputs: User goals, existing documents, change package context, or project path.
78
+ Outputs: Executable artifacts, next-step guidance, or recorded paths.
79
+ Boundaries: Does not replace other roles; does not touch `tests/`.
80
+ Evidence: Reference output paths or execution records.
76
81
 
77
- MCP enhancement rules reference: `skills/_shared/mcp-enhancement-template-mcp-enhancement.md`
82
+ ### Advanced (Optional)
83
+ Use when you need to refine strategy, boundaries, or risk notes.
78
84
 
85
+ ### Extended (Optional)
86
+ Use when you need to coordinate with external systems or optional tools.
87
+
88
+ ## Recommended MCP Capability Types
89
+ - Code search (code-search)
90
+ - Reference tracking (reference-tracking)
91
+ - Impact analysis (impact-analysis)
@@ -10,6 +10,26 @@ allowed-tools:
10
10
 
11
11
  # DevBooks: Code Review (Reviewer)
12
12
 
13
+ ## Progressive Disclosure
14
+
15
+ ### Base (Required)
16
+ Goal: Produce review comments focused on maintainability (readability, consistency, dependencies), without changing code.
17
+ Inputs: change package context, diffs, key touched modules, and Green evidence availability.
18
+ Outputs: review notes and actionable suggestions for follow-up changes.
19
+ Boundaries: do not modify code or `tests/**`; do not discuss business correctness; do not check off AC matrix.
20
+ Evidence: reference reviewed paths and any detected risks.
21
+
22
+ ### Advanced (Optional)
23
+ Use when you need: resource management checks, smell detection, dependency health deep-dive.
24
+
25
+ ### Extended (Optional)
26
+ Use when you need: faster search/refs/impact via optional MCP capabilities.
27
+
28
+ ## Recommended MCP Capability Types
29
+ - Code search (code-search)
30
+ - Reference tracking (reference-tracking)
31
+ - Impact analysis (impact-analysis)
32
+
13
33
  ## Workflow Position Awareness
14
34
 
15
35
  > **Core Principle**: Code Review executes after Test Owner Phase 2 verification, as the final review step before archiving.
@@ -142,7 +162,7 @@ Detection rules reference: `skills/_shared/context-detection-template-context-de
142
162
 
143
163
  1. Detect if change package exists
144
164
  2. Detect if there are code changes (git diff)
145
- 3. Detect hotspot files (via CKB getHotspots)
165
+ 3. Detect hotspot files (based on change history and complexity analysis)
146
166
 
147
167
  ### Modes Supported by This Skill
148
168
 
@@ -196,50 +216,11 @@ After completing code-review, output:
196
216
  OR
197
217
  **Archive complete** (if no spec deltas)
198
218
 
199
- Reason: Code review is complete. The next step is to [merge spec deltas into truth / complete archiving].
219
+ Next: merge spec deltas into truth / complete archiving.
200
220
 
201
221
  ### How to invoke (if spec deltas exist)
202
222
  ```
203
- Run devbooks-spec-gardener skill for change <change-id>
204
- ```
223
+ Run devbooks-archiver skill for change <change-id>
205
224
  ```
206
225
 
207
226
  ---
208
-
209
- ## MCP Enhancement
210
-
211
- This Skill supports MCP runtime enhancement, automatically detecting and enabling advanced features.
212
-
213
- MCP enhancement rules reference: `skills/_shared/mcp-enhancement-template-mcp-enhancement.md`
214
-
215
- ### Dependent MCP Services
216
-
217
- | Service | Purpose | Timeout |
218
- |---------|---------|---------|
219
- | `mcp__ckb__getHotspots` | Detect hotspot files for priority review | 2s |
220
- | `mcp__ckb__getStatus` | Detect CKB index availability | 2s |
221
-
222
- ### Detection Flow
223
-
224
- 1. Call `mcp__ckb__getStatus` (2s timeout)
225
- 2. If CKB available -> Call `mcp__ckb__getHotspots` to get hotspot files
226
- 3. Perform priority review on hotspot files
227
- 4. If timeout or failure -> Fallback to basic mode
228
-
229
- ### Enhanced Mode vs Basic Mode
230
-
231
- | Feature | Enhanced Mode | Basic Mode |
232
- |---------|---------------|------------|
233
- | Hotspot priority review | Automatically identify high-risk files | Review in change order |
234
- | Dependency direction check | Based on module graph analysis | Inferred from file paths |
235
- | Circular dependency detection | CKB precise detection | Grep heuristic detection |
236
-
237
- ### Fallback Notice
238
-
239
- When MCP is unavailable, output the following notice:
240
-
241
- ```
242
- Warning: CKB unavailable, cannot perform hotspot priority review.
243
- Reviewing in change file order.
244
- ```
245
-
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: devbooks-router
3
- description: devbooks-router: DevBooks workflow entry guidance. Helps users determine which skill to start with, detects project current status, and provides shortest closed-loop path. Use when user says "what's next/where to start/run DevBooks closed-loop/project status" etc. Note: Routing after skill completion is handled by each skill itself, no need to call router.
3
+ description: devbooks-router: DevBooks workflow entry guidance. Helps users determine which skill to start with, detects project current status, and provides shortest closed-loop path. Use when the user says "what's next/where to start/run DevBooks closed-loop/project status" etc. Note: Routing after skill completion is handled by each skill itself, no need to call router.
4
4
  allowed-tools:
5
5
  - Glob
6
6
  - Grep
@@ -10,367 +10,33 @@ allowed-tools:
10
10
 
11
11
  # DevBooks: Workflow Entry Guide (Router)
12
12
 
13
- ## Positioning Statement
13
+ ## Progressive Disclosure
14
14
 
15
- > **Important**: Router's responsibility is **entry guidance**, not step-by-step routing.
15
+ ### Base (must read)
16
+ Goal: determine the current phase and output the shortest closed-loop routing (skills + artifact paths + rationale).
17
+ Input: user request, config mapping (truth-root/change-root), existing artifacts, change package status.
18
+ Output: 2 minimum key questions + 3-6 routing results + next-step suggestion.
19
+ Boundaries: do not directly produce change package artifacts; do not replace other Skills; must read `agents_doc` first.
20
+ Evidence: reference artifact paths and the detection conclusion.
16
21
 
17
- | Scenario | Use Router? |
18
- |----------|:-----------:|
19
- | "Where should I start?" | ✅ Use |
20
- | "What's the project status?" | ✅ Use |
21
- | "What's next after coder?" | ❌ Don't use (coder outputs it) |
22
- | "What's next after this skill?" | ❌ Don't use (each skill outputs its own) |
22
+ ### Advanced (optional)
23
+ Use when you need: impact profile parsing, degradation notes, detailed routing rules.
23
24
 
24
- **Principle**: Each skill outputs its own next-step recommendation upon completion, following `_shared/references/deviation-detection-routing-protocol.md`.
25
+ ### Extended (optional)
26
+ Use when you need: prototype track, pre-archive checks, context-detection details.
25
27
 
26
- ---
27
-
28
- ## Prerequisites: Configuration Discovery (Protocol-Agnostic)
29
-
30
- - `<truth-root>`: Current truth directory root
31
- - `<change-root>`: Change package directory root
32
-
33
- Before execution, you **must** search for configuration in the following order (stop when found):
34
- 1. `.devbooks/config.yaml` (if exists) → Parse and use its mappings
35
- 2. `dev-playbooks/project.md` (if exists) → Dev-Playbooks protocol, use default mappings
36
- 3. `project.md` (if exists) → Template protocol, use default mappings
37
- 4. If still undetermined → **Stop and ask user**
38
-
39
- **Key Constraints**:
40
- - If configuration specifies `agents_doc` (rules document), **you must read that document first** before executing any operations
41
- - Do not guess directory roots
42
- - Do not skip reading the rules document
43
-
44
- ## Prerequisites: Graph Index Health Check (Automatic)
45
-
46
- **Automatically executed before routing**, checks CKB graph index status:
47
-
48
- 1. Call `mcp__ckb__getStatus` to check SCIP backend
49
- 2. If `backends.scip.healthy = false`:
50
- - Prompt user: "Code graph index not activated detected, impact analysis/call graph and other graph-based capabilities unavailable"
51
- - Provide the command to manually generate the index (see script above)
52
- - Continue routing but mark "graph capabilities degraded"
53
-
54
- 3. If `backends.scip.healthy = true`:
55
- - Pass silently, continue routing
56
-
57
- **Check Script** (for reference):
58
- ```bash
59
- # Detect language and generate index
60
- if [ -f "tsconfig.json" ]; then
61
- scip-typescript index --output index.scip
62
- elif [ -f "pyproject.toml" ]; then
63
- scip-python index . --output index.scip
64
- elif [ -f "go.mod" ]; then
65
- scip-go --output index.scip
66
- fi
67
- ```
68
-
69
- **Degraded Mode Notes**:
70
- - Without index, `devbooks-impact-analysis` degrades to Grep text search (reduced accuracy)
71
- - Without index, `devbooks-reviewer` cannot obtain call graph context
72
- - Recommend completing index generation before the Apply phase
73
-
74
- ## Your Task
75
-
76
- Map the user's natural language request to:
77
- 1) Current phase (proposal / apply / review / archive)
78
- 2) Required artifacts for this change (proposal/design/tasks/verification) and optional artifacts (spec deltas/contract/c4/evidence)
79
- 3) Which `devbooks-*` Skill(s) to use next
80
- 4) File path for each artifact
81
-
82
- ## Output Requirements (Mandatory)
83
-
84
- 1) **Ask 2 minimum key questions first** (skip if context already provides answers):
85
- - What is the `<change-id>`?
86
- - What are the final values of `<truth-root>` / `<change-root>` for this project?
87
- 2) Provide "next-step routing results" (3-6 items):
88
- - Each item includes: Skill to use + artifact path + why it's needed
89
- 3) Only enter the corresponding Skill's output mode if the user explicitly asks you to "start producing file content directly."
90
-
91
- ---
92
-
93
- ## Impact Profile Parsing (AC-003 / AC-012)
94
-
95
- When `proposal.md` exists, Router **should automatically parse** the Impact section to generate a more precise execution plan.
96
-
97
- ### Impact Profile Structure
98
-
99
- ```yaml
100
- impact_profile:
101
- external_api: true/false # External API changes
102
- architecture_boundary: true/false # Architecture boundary changes
103
- data_model: true/false # Data model changes
104
- cross_repo: true/false # Cross-repository impact
105
- risk_level: high/medium/low # Risk level
106
- affected_modules: # List of affected modules
107
- - name: <module-path>
108
- type: add/modify/delete
109
- files: <count>
110
- ```
111
-
112
- ### Parsing Flow
113
-
114
- 1. Check if `proposal.md` exists
115
- 2. If exists, find `## Impact` section
116
- 3. Extract `impact_profile:` YAML block
117
- 4. Validate required fields: `external_api`, `risk_level`, `affected_modules`
118
-
119
- ### Routing Enhancement Based on Impact Profile
120
-
121
- | Impact Field | Value | Auto-Append Skill |
122
- |--------------|-------|-------------------|
123
- | `external_api: true` | - | `devbooks-spec-contract` |
124
- | `architecture_boundary: true` | - | `devbooks-design-doc` (ensure Architecture Impact section is complete) |
125
- | `cross_repo: true` | - | Manual cross-repo impact analysis |
126
- | `risk_level: high` | - | `devbooks-proposal-challenger` + `devbooks-proposal-judge` |
127
- | `affected_modules` count > 5 | - | `devbooks-impact-analysis` (deep analysis) |
128
-
129
- ### Execution Plan Output Format
130
-
131
- ```markdown
132
- ## Execution Plan (Based on Impact Profile)
133
-
134
- ### Must Execute
135
- 1. `devbooks-proposal-author skill` → proposal.md (proposal exists, skip)
136
- 2. `devbooks-design-doc skill` → design.md (required)
137
- 3. `devbooks-implementation-plan skill` → tasks.md (required)
138
-
139
- ### Recommended (Based on Impact Analysis)
140
- 4. `devbooks-spec-contract skill` → specs/** (detected external_api: true)
141
- 5. `devbooks-design-doc skill` → design.md Architecture Impact section (detected architecture_boundary: true)
142
-
143
- ### Optional
144
- 6. `devbooks-impact-analysis skill` → Deep impact analysis (affected_modules > 5)
145
- ```
146
-
147
- ### Parse Failure Handling (AC-012)
148
-
149
- **When Impact Profile is missing**:
150
-
151
- ```
152
- Warning: Impact profile not found in proposal.md.
153
-
154
- Missing items:
155
- - Impact section does not exist
156
- - Or impact_profile YAML block is missing
157
-
158
- Suggested actions:
159
- 1. Run `devbooks-impact-analysis skill` to generate impact analysis
160
- 2. Or use the appropriate skill directly
161
-
162
- Skill list:
163
- - devbooks-design-doc skill → Design document
164
- - devbooks-implementation-plan skill → Implementation plan
165
- - devbooks-spec-contract skill → Specification definition
166
- ```
167
-
168
- **When YAML parsing fails**:
169
-
170
- ```
171
- Warning: Impact profile parsing failed.
172
-
173
- Error: <specific error message>
174
-
175
- Suggested actions:
176
- 1. Check impact_profile YAML format in proposal.md
177
- 2. Or use the appropriate skill to bypass Router
178
- ```
179
-
180
- ---
181
-
182
- ## Routing Rules (Quality-First Default)
183
-
184
- ### A) Proposal (Proposal Phase)
185
-
186
- Trigger signals: User says "proposal/why change/scope/risk/code smell refactoring/should we do this/don't write code yet" etc.
187
-
188
- Default routing:
189
- - `devbooks-proposal-author` → `(<change-root>/<change-id>/proposal.md)` (required)
190
- - `devbooks-design-doc` → `(<change-root>/<change-id>/design.md)` (required for non-trivial changes; only write What/Constraints + AC-xxx)
191
- - `devbooks-implementation-plan` → `(<change-root>/<change-id>/tasks.md)` (required; derive only from design)
192
-
193
- Append as needed (add only when conditions are met):
194
- - **Cross-module/unclear impact**: `devbooks-impact-analysis` (recommend writing back to proposal Impact)
195
- - **Obvious risks/controversies/trade-offs**: `devbooks-proposal-challenger` + `devbooks-proposal-judge` (Author/Challenger/Judge in separate conversations, write back to Decision Log after debate)
196
- - **External behavior/contract/data invariant changes**: `devbooks-spec-contract` → `(<change-root>/<change-id>/specs/**)` + `design.md` Contract section
197
- - If you need "deterministic spec delta file creation/avoid path errors": `change-spec-delta-scaffold.sh <change-id> <capability> ...`
198
- - **Module boundary/dependency direction/architecture shape changes**: Ensure `devbooks-design-doc` outputs complete Architecture Impact section → merged to `(<truth-root>/architecture/c4.md)` by `devbooks-spec-gardener` during archiving
199
-
200
- Hard constraint reminders:
201
- - Proposal phase prohibits writing implementation code; implementation happens in apply phase with tests/gates as completion criteria.
202
- - If you need "deterministic scaffold creation/avoid missing files": prefer running `devbooks-delivery-workflow` scripts
203
- - `change-scaffold.sh <change-id> ...`
204
- - `change-check.sh <change-id> --mode proposal ...`
205
-
206
- ### B) Apply (Implementation Phase: Test Owner / Coder)
207
-
208
- Trigger signals: User says "start implementation/run tests/fix failures/follow tasks/make all gates green" etc.
209
-
210
- Default routing (mandatory role separation):
211
- - Test Owner (separate conversation/separate instance): `devbooks-test-owner`
212
- - Artifacts: `(<change-root>/<change-id>/verification.md)` + `tests/**`
213
- - First run to produce **Red** baseline, and record evidence (e.g., `(<change-root>/<change-id>/evidence/**)`)
214
- - Coder (separate conversation/separate instance): `devbooks-coder`
215
- - Input: `tasks.md` + test errors + codebase
216
- - Prohibited from modifying `tests/**`
217
-
218
- Apply phase deterministic checks (recommended):
219
- - Test Owner: `change-check.sh <change-id> --mode apply --role test-owner ...`
220
- - Test Owner (evidence recording): `change-evidence.sh <change-id> --label red-baseline -- <test-command>`
221
- - Coder: `change-check.sh <change-id> --mode apply --role coder ...` (additionally checks that `tests/**` is unmodified in git diff)
222
-
223
- LSC (Large-Scale Codemods) recommendations:
224
- - First use `change-codemod-scaffold.sh <change-id> --name <codemod-name> ...` to generate codemod script scaffold, then use script for batch changes and record evidence
225
-
226
- ### C) Review (Review Phase)
227
-
228
- Trigger signals: User says "review/code smells/maintainability/dependency risks/consistency" etc.
229
-
230
- Default routing:
231
- - `devbooks-reviewer` (output actionable suggestions; do not change business conclusions or tests)
232
- - `devbooks-test-reviewer` (review test quality, coverage, edge cases)
233
-
234
- ### D) Docs Sync (Documentation Sync)
235
-
236
- Trigger signals: User says "update docs/sync docs/README update/API docs" etc.
237
-
238
- Default routing:
239
- - `devbooks-docs-sync` (maintain user documentation consistency with code)
240
- - Incremental mode: In change package context, only update docs related to this change
241
- - Global mode: With --global parameter, scan all docs and generate difference report
242
-
243
- **Trigger conditions** (not required for every change):
244
- - Add/modify/remove public API
245
- - Change user-visible behavior
246
- - Modify configuration options
247
- - Change CLI commands
248
-
249
- ### E) Archive (Archive Phase)
250
-
251
- Trigger signals: User says "archive/merge specs/close out/wrap up" etc.
252
-
253
- Default routing:
254
- - If spec deltas were produced this time: `devbooks-archiver` (prune `<truth-root>/**` before archive merge)
255
- - If design decisions need to be written back: `devbooks-design-backport` (as needed)
256
- - If user documentation affected: `devbooks-docs-sync` (ensure docs consistent with code)
257
-
258
- Pre-archive deterministic checks (recommended):
259
- - `change-check.sh <change-id> --mode strict ...` (requires: proposal Approved, tasks all checked, trace matrix has no TODOs, structural gate decisions filled in)
260
-
261
- ### F) Prototype (Prototype Mode)
262
-
263
- > Source: "The Mythical Man-Month" Chapter 11 "Plan to Throw One Away" — "The first system built is never suitable for use...plan to throw one away"
264
-
265
- Trigger signals: User says "prototype first/quick validation/spike/--prototype/throwaway prototype/Plan to Throw One Away" etc.
266
-
267
- **Prototype mode applicable scenarios**:
268
- - Technical approach uncertain, need quick feasibility validation
269
- - First time building this type of feature, expect to rewrite
270
- - Need to explore actual behavior of APIs/libraries/frameworks
271
-
272
- **Default routing (prototype track constraints)**:
273
-
274
- 1. Create prototype scaffold:
275
- - `change-scaffold.sh <change-id> --prototype ...`
276
- - Artifacts: `(<change-root>/<change-id>/prototype/)`
277
-
278
- 2. Test Owner (separate conversation) uses `devbooks-test-owner --prototype`:
279
- - Artifacts: `(<change-root>/<change-id>/prototype/characterization/)`
280
- - Generate **characterization tests** (record actual behavior) rather than acceptance tests
281
- - **No Red baseline required** — characterization tests assert "current state"
282
-
283
- 3. Coder (separate conversation) uses `devbooks-coder --prototype`:
284
- - Output path: `(<change-root>/<change-id>/prototype/src/)`
285
- - Allowed to bypass lint/complexity thresholds
286
- - **Prohibited from landing directly to repository `src/`**
287
-
288
- **Hard constraints (must follow)**:
289
- - Prototype code and production code are **physically isolated** (different directories)
290
- - Test Owner and Coder must still have **separate conversations/instances** (role separation unchanged)
291
- - Promoting prototype to production requires **explicit trigger** `prototype-promote.sh <change-id>`
292
-
293
- **Prerequisites for promoting prototype to production**:
294
- 1. Create production-grade `design.md` (distill What/Constraints/AC-xxx from prototype learnings)
295
- 2. Test Owner produces acceptance tests `verification.md` (replacing characterization tests)
296
- 3. Complete the promotion checklist in `prototype/PROTOTYPE.md`
297
- 4. Run `prototype-promote.sh <change-id>` and pass all gates
298
-
299
- **Prototype discard flow**:
300
- 1. Record key insights learned to `proposal.md` Decision Log
301
- 2. Delete `prototype/` directory
302
-
303
- ## DevBooks Skill Adaptation
304
-
305
- DevBooks uses `devbooks-proposal-author skill`, `devbooks-test-owner/coder skill`, `devbooks-archiver skill` as entry points.
306
- Route according to A/B/C/D above, artifact paths follow `<truth-root>/<change-root>` mappings in project signposts.
307
-
308
- ---
309
-
310
- ## Context Awareness
311
-
312
- This Skill automatically detects context before execution, selecting appropriate routing strategy.
313
-
314
- Detection rules reference: `skills/_shared/context-detection-template-context-detection.md`
315
-
316
- ### Detection Flow
317
-
318
- 1. Detect if change package exists
319
- 2. Detect existing artifacts (proposal/design/tasks/verification)
320
- 3. Infer current phase (proposal/apply/archive)
321
- 4. Select default routing based on phase
322
-
323
- ### Modes Supported by This Skill
324
-
325
- | Mode | Trigger Condition | Behavior |
326
- |------|-------------------|----------|
327
- | **New Change** | Change package doesn't exist or is empty | Route to proposal phase, suggest creating proposal.md |
328
- | **In Progress** | Change package exists, has partial artifacts | Recommend next step based on missing artifacts |
329
- | **Ready to Archive** | Gates passed, `evidence/green-final/` exists | Route to archive phase |
330
-
331
- ### Detection Output Example
332
-
333
- ```
334
- Detection results:
335
- - Change package status: exists
336
- - Existing artifacts: proposal.md ✓, design.md ✓, tasks.md ✓, verification.md ✗
337
- - Current phase: apply
338
- - Suggested routing: devbooks-test-owner (establish Red baseline first)
339
- ```
340
-
341
- ---
342
-
343
- ## MCP Enhancement
344
-
345
- This Skill supports MCP runtime enhancement, automatically detecting and enabling advanced features.
346
-
347
- MCP enhancement rules reference: `skills/_shared/mcp-enhancement-template-mcp-enhancement.md`
348
-
349
- ### Required MCP Services
350
-
351
- | Service | Purpose | Timeout |
352
- |---------|---------|---------|
353
- | `mcp__ckb__getStatus` | Detect CKB index availability | 2s |
354
-
355
- ### Detection Flow
356
-
357
- 1. Call `mcp__ckb__getStatus` (2s timeout)
358
- 2. If CKB available → Mark "graph capabilities activated" in routing suggestions
359
- 3. If timeout or failure → Mark "graph capabilities degraded" in routing suggestions, recommend manually generating SCIP index
28
+ ## Core Notes
360
29
 
361
- ### Enhanced Mode vs Basic Mode
30
+ - Run config discovery (prefer `.devbooks/config.yaml`) and read `agents_doc` before routing.
31
+ - Output 2 minimum key questions + 3-6 routing results (paths + rationale).
32
+ - If the user asks to "start producing files", switch to the target Skill's output mode.
362
33
 
363
- | Feature | Enhanced Mode | Basic Mode |
364
- |---------|---------------|------------|
365
- | Impact analysis recommendation | Use CKB precise analysis | Use Grep text search |
366
- | Code navigation | Symbol-level navigation available | File-level search |
367
- | Hotspot detection | CKB real-time analysis | Unavailable |
34
+ ## References
368
35
 
369
- ### Degradation Notice
36
+ - `skills/devbooks-router/references/routing-rules-and-templates.md`: positioning, config discovery, impact profile parsing, routing rules, prototype track, context detection.
370
37
 
371
- When MCP is unavailable, output the following notice:
38
+ ## Recommended MCP Capability Types
372
39
 
373
- ```
374
- Warning: CKB index not activated, graph capabilities (impact analysis, call graph, etc.) will be degraded.
375
- Recommend manually generating SCIP index for full functionality.
376
- ```
40
+ - Code search (code-search)
41
+ - Reference tracking (reference-tracking)
42
+ - Impact analysis (impact-analysis)