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.
- package/CHANGELOG.md +30 -0
- package/README.md +133 -462
- package/package.json +1 -1
- package/scripts/config-discovery.sh +1 -1
- package/scripts/detect-mcp.sh +86 -0
- package/skills/Skill-Development-Guide.md +1 -2
- package/skills/_shared/mcp-enhancement-template-mcp-enhancement.md +30 -113
- package/skills/_shared/references/completeness-thinking-framework.md +86 -0
- package/skills/_shared/references/human-advice-calibration-prompt.md +27 -0
- package/skills/devbooks-archiver/SKILL.md +20 -12
- package/skills/devbooks-archiver/references/archiver-prompt.md +66 -38
- package/skills/devbooks-brownfield-bootstrap/SKILL.md +32 -65
- package/skills/devbooks-coder/SKILL.md +61 -240
- package/skills/devbooks-coder/references/completion-status-and-routing.md +8 -8
- package/skills/devbooks-convergence-audit/SKILL.md +20 -0
- package/skills/devbooks-delivery-workflow/SKILL.md +26 -227
- package/skills/devbooks-delivery-workflow/references/orchestration-bans-and-stage-table.md +45 -0
- package/skills/devbooks-design-backport/SKILL.md +16 -3
- package/skills/devbooks-design-doc/SKILL.md +21 -9
- package/skills/devbooks-docs-consistency/SKILL.md +170 -0
- package/skills/devbooks-docs-consistency/references/completeness-dimensions.yaml +31 -0
- package/skills/devbooks-docs-consistency/references/doc-classification.yaml +11 -0
- package/skills/devbooks-docs-consistency/references/docs-rules-schema.yaml +11 -0
- package/skills/devbooks-docs-consistency/scripts/alias.sh +5 -0
- package/skills/devbooks-docs-consistency/scripts/completeness-checker.sh +153 -0
- package/skills/devbooks-docs-consistency/scripts/doc-classifier.sh +121 -0
- package/skills/devbooks-docs-consistency/scripts/git-adapter.sh +32 -0
- package/skills/devbooks-docs-consistency/scripts/rules-engine.sh +255 -0
- package/skills/devbooks-docs-consistency/scripts/scanner.sh +93 -0
- package/skills/devbooks-docs-consistency/scripts/style-checker.sh +123 -0
- package/skills/devbooks-docs-sync/SKILL.md +23 -318
- package/skills/devbooks-entropy-monitor/SKILL.md +15 -32
- package/skills/devbooks-impact-analysis/SKILL.md +26 -46
- package/skills/devbooks-implementation-plan/SKILL.md +23 -9
- package/skills/devbooks-proposal-author/SKILL.md +21 -15
- package/skills/devbooks-proposal-challenger/SKILL.md +16 -3
- package/skills/devbooks-proposal-judge/SKILL.md +16 -3
- package/skills/devbooks-reviewer/SKILL.md +23 -42
- package/skills/devbooks-router/SKILL.md +22 -356
- package/skills/devbooks-router/references/routing-rules-and-templates.md +120 -0
- package/skills/devbooks-spec-contract/SKILL.md +23 -39
- package/skills/devbooks-test-owner/SKILL.md +68 -309
- 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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 (
|
|
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
|
-
|
|
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-
|
|
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
|
-
##
|
|
13
|
+
## Progressive Disclosure
|
|
14
14
|
|
|
15
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
38
|
+
## Recommended MCP Capability Types
|
|
372
39
|
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
```
|
|
40
|
+
- Code search (code-search)
|
|
41
|
+
- Reference tracking (reference-tracking)
|
|
42
|
+
- Impact analysis (impact-analysis)
|