dev-playbooks 1.0.19 → 1.2.1

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 (41) hide show
  1. package/README.md +40 -70
  2. package/bin/devbooks.js +236 -8
  3. package/package.json +1 -1
  4. package/skills/Skills-Usage-Guide.md +15 -74
  5. package/skills/_shared/mcp-enhancement-template.md +1 -4
  6. package/skills/_shared/references/deviation-detection-routing-protocol.md +199 -0
  7. package/skills/_shared/workflow-next-steps.md +111 -0
  8. package/skills/devbooks-brownfield-bootstrap/SKILL.md +2 -2
  9. package/skills/devbooks-brownfield-bootstrap/scripts/cod-update.sh +1 -1
  10. package/skills/devbooks-code-review/SKILL.md +34 -1
  11. package/skills/devbooks-coder/SKILL.md +103 -2
  12. package/skills/devbooks-delivery-workflow/SKILL.md +2 -2
  13. package/skills/devbooks-design-backport/SKILL.md +1 -1
  14. package/skills/devbooks-design-doc/SKILL.md +38 -1
  15. package/skills/devbooks-docs-sync/SKILL.md +338 -0
  16. package/skills/devbooks-entropy-monitor/SKILL.md +1 -1
  17. package/skills/devbooks-impact-analysis/SKILL.md +2 -2
  18. package/skills/devbooks-implementation-plan/SKILL.md +43 -1
  19. package/skills/devbooks-proposal-author/SKILL.md +41 -1
  20. package/skills/devbooks-proposal-author/references/proposal-authoring-prompt.md +10 -0
  21. package/skills/devbooks-proposal-challenger/SKILL.md +1 -1
  22. package/skills/devbooks-proposal-judge/SKILL.md +1 -1
  23. package/skills/devbooks-router/SKILL.md +44 -13
  24. package/skills/devbooks-spec-contract/SKILL.md +36 -2
  25. package/skills/devbooks-spec-gardener/SKILL.md +1 -1
  26. package/skills/devbooks-test-owner/SKILL.md +204 -1
  27. package/skills/devbooks-test-reviewer/SKILL.md +27 -1
  28. package/templates/claude-agents/devbooks-coder.md +21 -0
  29. package/templates/claude-agents/devbooks-explorer.md +21 -0
  30. package/templates/claude-agents/devbooks-reviewer.md +21 -0
  31. package/templates/claude-agents/devbooks-test-owner.md +21 -0
  32. package/templates/dev-playbooks/README.md +34 -66
  33. package/templates/dev-playbooks/docs/devbooks-setup-guide.md +1 -14
  34. package/skills/devbooks-federation/SKILL.md +0 -264
  35. package/skills/devbooks-federation/scripts/federation-check.sh +0 -144
  36. package/skills/devbooks-federation/templates/federation.yaml +0 -89
  37. package/skills/devbooks-index-bootstrap/SKILL.md +0 -240
  38. package/skills/devbooks-proposal-debate-workflow/SKILL.md +0 -78
  39. package/skills/devbooks-proposal-debate-workflow/references/11-proposal-debate-template.md +0 -35
  40. package/skills/devbooks-proposal-debate-workflow/references/proposal-debate-workflow.md +0 -24
  41. package/skills/devbooks-proposal-debate-workflow/scripts/proposal-debate-check.sh +0 -102
package/README.md CHANGED
@@ -27,22 +27,7 @@ AI coding assistants are powerful, but often **unpredictable**:
27
27
  - **Evidence-based done**: completion is defined by tests/build/evidence, not AI self-evaluation
28
28
  - **Enforced role isolation**: Test Owner and Coder must work in separate conversations
29
29
  - **Multiple quality gates**: green evidence checks, task completion, role boundary checks
30
- - **21 Skills**: proposal, design, debate, review, entropy metrics, federation, and more
31
-
32
- ---
33
-
34
- ## DevBooks At a Glance (Comparison)
35
-
36
- | Dimension | DevBooks | OpenSpec | spec-kit | No spec |
37
- |------|----------|----------|----------|--------|
38
- | Spec-driven workflow | Yes | Yes | Yes | No |
39
- | Artifact traceability | Change package (proposal/design/spec/tasks/verification/evidence) | Mostly folder/file organization | Docs + tasks orchestration | None |
40
- | Role & responsibility boundaries | **Enforced** (Test Owner / Coder) | Convention-based (not enforced) | Convention-based (not enforced) | None |
41
- | Definition of Done (DoD) | **Evidence + gates** (tests/build/audit) | Manual definition/checks | Manual definition/checks | Often subjective |
42
- | Code quality assurance | Gates + metrics (entropy/hotspots) + review roles | External tools / manual review | External tools / manual review | Unstable |
43
- | Impact analysis | CKB graph capability (falls back to grep) | Text search / manual reasoning | Text search / manual reasoning | Easy to miss |
44
- | Brownfield onboarding | Baseline specs/glossary/minimal verification anchors | Manual | Limited | - |
45
- | Automation coverage | 21 Skills (proposal→implementation→archive loop) | 3 core commands | Toolkit (greenfield-leaning) | - |
30
+ - **18 Skills**: proposal, design, review, entropy metrics, and full workflow coverage
46
31
 
47
32
  ---
48
33
 
@@ -175,7 +160,6 @@ Run devbooks-spec-gardener skill for change add-oauth2
175
160
  | devbooks-impact-analysis | Cross-module impact analysis |
176
161
  | devbooks-proposal-challenger | Challenge a proposal |
177
162
  | devbooks-proposal-judge | Adjudicate a proposal |
178
- | devbooks-proposal-debate-workflow | Triangle debate (Author/Challenger/Judge) |
179
163
  | devbooks-design-doc | Create a design doc |
180
164
  | devbooks-spec-contract | Define specs & contracts |
181
165
  | devbooks-implementation-plan | Create an implementation plan |
@@ -193,6 +177,7 @@ Run devbooks-spec-gardener skill for change add-oauth2
193
177
  | Skill | Description |
194
178
  |-------|-------------|
195
179
  | devbooks-code-review | Code review (readability/consistency) |
180
+ | devbooks-test-reviewer | Test quality and coverage review |
196
181
 
197
182
  ### Archive stage
198
183
 
@@ -206,9 +191,7 @@ Run devbooks-spec-gardener skill for change add-oauth2
206
191
  | Skill | Description |
207
192
  |-------|-------------|
208
193
  | devbooks-entropy-monitor | System entropy metrics |
209
- | devbooks-federation | Cross-repo federation analysis |
210
194
  | devbooks-brownfield-bootstrap | Brownfield project bootstrap |
211
- | devbooks-index-bootstrap | Generate a SCIP index |
212
195
 
213
196
  ---
214
197
 
@@ -218,52 +201,53 @@ Run devbooks-spec-gardener skill for change add-oauth2
218
201
 
219
202
  [OpenSpec](https://github.com/Fission-AI/OpenSpec) is a lightweight spec-driven framework with three core commands (proposal/apply/archive), organizing changes by feature folders.
220
203
 
221
- **What DevBooks adds:**
222
- - **Role isolation**: hard boundary between Test Owner and Coder (separate chats)
223
- - **Quality gates**: 5+ verification gates to block false completion
224
- - **21 Skills**: proposal, debate, review, entropy metrics, federation, etc.
225
- - **Evidence-based done**: tests/build define “done”, not self-evaluation
226
-
227
- **Choose OpenSpec**: you want a lightweight spec workflow.
204
+ **OpenSpec's limitations:**
205
+ - No role isolation, AI may self-verify "done"
206
+ - No quality gates, false completion is hard to catch
207
+ - Only 3 commands, insufficient coverage for complex changes
228
208
 
229
- **Choose DevBooks**: you need role separation and verification gates for larger changes.
209
+ **DevBooks solutions:**
210
+ - **Enforced role isolation**: Test Owner and Coder must work in separate conversations, preventing self-verification
211
+ - **5+ quality gates**: Green evidence checks, task completion rate, role boundary checks
212
+ - **18 Skills**: Full coverage from proposal to implementation to archive
230
213
 
231
214
  ### vs. spec-kit
232
215
 
233
216
  [GitHub spec-kit](https://github.com/github/spec-kit) is a spec-driven toolkit with a constitution file, multi-step refinement, and structured planning.
234
217
 
235
- **What DevBooks adds:**
236
- - **Brownfield-first**: generates baseline specs for existing repos
237
- - **Role isolation**: test authoring and implementation are separated
238
- - **Quality gates**: runtime verification, not just workflow guidance
239
- - **Prototype mode**: safe experiments without polluting main `src/`
218
+ **spec-kit's limitations:**
219
+ - Focused on greenfield (0→1) projects, limited brownfield support
220
+ - No enforced role isolation, tests and implementation may get confused
221
+ - Relies on manual checks, no runtime verification
240
222
 
241
- **Choose spec-kit**: greenfield projects with supported AI tools.
242
-
243
- **Choose DevBooks**: brownfield repos or when you want enforced gates.
223
+ **DevBooks solutions:**
224
+ - **Brownfield-first**: `devbooks-brownfield-bootstrap` auto-generates baseline specs
225
+ - **Enforced role isolation**: Test authoring and implementation are physically separated
226
+ - **Runtime gates**: Automated verification, not dependent on manual checks
244
227
 
245
228
  ### vs. Kiro.dev
246
229
 
247
- [Kiro](https://kiro.dev/) is an AWS agentic IDE with a three-phase workflow (EARS requirements, design, tasks), but stores specs separately from implementation artifacts.
248
-
249
- **DevBooks differences:**
250
- - **Change package**: proposal/design/spec/plan/verification/evidence in one place for lifecycle traceability
251
- - **Role isolation**: Test Owner and Coder are separated
252
- - **Quality gates**: verified through gates, not just task completion
230
+ [Kiro](https://kiro.dev/) is an AWS agentic IDE with a three-phase workflow (EARS requirements, design, tasks).
253
231
 
254
- **Choose Kiro**: you want an IDE experience and AWS ecosystem integration.
232
+ **Kiro's limitations:**
233
+ - Specs and implementation artifacts stored separately, hard to trace
234
+ - No enforced role isolation
235
+ - Requires a specific IDE environment
255
236
 
256
- **Choose DevBooks**: you want change packages to bundle artifacts and enforce role boundaries.
237
+ **DevBooks solutions:**
238
+ - **Change packages**: proposal/design/spec/plan/verification/evidence centralized, full traceability
239
+ - **Enforced role isolation**: Hard boundary between Test Owner and Coder
240
+ - **Tool-agnostic**: Supports Claude Code, Codex CLI, Cursor, and more
257
241
 
258
242
  ### vs. no spec
259
243
 
260
- Without specs, the assistant generates code from vague prompts, leading to unpredictable output, scope creep, and hallucinated completion”.
244
+ Without specs, the assistant generates code from vague prompts, leading to unpredictable output, scope creep, and "hallucinated completion".
261
245
 
262
246
  **DevBooks brings:**
263
- - Specs agreed before implementation
264
- - Quality gates that verify real completion
265
- - Role isolation to prevent self-verification
266
- - Evidence chain per change
247
+ - Specs agreed before implementation, clear and controlled scope
248
+ - Quality gates verify real completion
249
+ - Role isolation prevents self-verification
250
+ - Complete evidence chain per change
267
251
 
268
252
  ---
269
253
 
@@ -354,18 +338,6 @@ Generates:
354
338
 
355
339
  </details>
356
340
 
357
- <details>
358
- <summary><strong>Cross-repo federation</strong></summary>
359
-
360
- For multi-repo analysis:
361
-
362
- ```
363
- Run devbooks-federation skill
364
- ```
365
-
366
- Analyzes cross-repo contracts and dependencies to support coordinated changes.
367
-
368
- </details>
369
341
 
370
342
  <details>
371
343
  <summary><strong>MCP auto-detection</strong></summary>
@@ -391,23 +363,21 @@ DevBooks Skills support graceful MCP (Model Context Protocol) degradation: you c
391
363
  - Timeout/failure → silently falls back to basic mode (non-blocking)
392
364
  - No manual “basic/enhanced” switch required
393
365
 
394
- To enable enhanced mode: configure CKB per `docs/Recommended-MCP.md` and run `devbooks-index-bootstrap` skill to generate `index.scip`.
366
+ To enable enhanced mode: configure CKB per `docs/Recommended-MCP.md` and manually generate `index.scip`.
395
367
 
396
368
  </details>
397
369
 
398
370
  <details>
399
- <summary><strong>Proposal debate workflow</strong></summary>
371
+ <summary><strong>Proposal review workflow</strong></summary>
400
372
 
401
- For strict proposal review, run the triangle debate:
373
+ For strict proposal review, use separate conversations for Challenger and Judge:
402
374
 
403
- ```
404
- Run devbooks-proposal-debate-workflow skill
405
- ```
375
+ Three roles (must work in separate conversations):
376
+ 1. **Author**: creates and defends the proposal (use `devbooks-proposal-author`)
377
+ 2. **Challenger**: challenges assumptions, finds gaps, identifies risks (use `devbooks-proposal-challenger`)
378
+ 3. **Judge**: makes the final decision and records rationale (use `devbooks-proposal-judge`)
406
379
 
407
- Three roles:
408
- 1. **Author**: creates and defends the proposal
409
- 2. **Challenger**: challenges assumptions, finds gaps, identifies risks
410
- 3. **Judge**: makes the final decision and records rationale
380
+ **Important**: The three roles must work in **separate conversations** to avoid role confusion and self-verification.
411
381
 
412
382
  Decision: `Approved`, `Revise`, `Rejected`
413
383
 
package/bin/devbooks.js CHANGED
@@ -305,6 +305,160 @@ function getCliVersion() {
305
305
  }
306
306
  }
307
307
 
308
+ // ============================================================================
309
+ // Auto-update .gitignore and .npmignore
310
+ // ============================================================================
311
+
312
+ const IGNORE_MARKERS = {
313
+ start: '# DevBooks managed - DO NOT EDIT',
314
+ end: '# End DevBooks managed'
315
+ };
316
+
317
+ /**
318
+ * Get entries to add to .gitignore
319
+ * @param {string[]} toolIds - Selected AI tool IDs
320
+ * @returns {string[]} - Entries to ignore
321
+ */
322
+ function getGitIgnoreEntries(toolIds) {
323
+ const entries = [
324
+ '# DevBooks local config (contains user preferences, should not be committed)',
325
+ '.devbooks/'
326
+ ];
327
+
328
+ // Add corresponding AI tool directories based on selected tools
329
+ for (const toolId of toolIds) {
330
+ const tool = AI_TOOLS.find(t => t.id === toolId);
331
+ if (!tool) continue;
332
+
333
+ // Add slash command directory
334
+ if (tool.slashDir) {
335
+ const topDir = tool.slashDir.split('/')[0];
336
+ if (!entries.includes(topDir + '/')) {
337
+ entries.push(`${topDir}/`);
338
+ }
339
+ }
340
+
341
+ // Add rules directory
342
+ if (tool.rulesDir) {
343
+ const topDir = tool.rulesDir.split('/')[0];
344
+ if (!entries.includes(topDir + '/')) {
345
+ entries.push(`${topDir}/`);
346
+ }
347
+ }
348
+
349
+ // Add agents directory (e.g., .github/instructions)
350
+ if (tool.instructionsDir) {
351
+ const topDir = tool.instructionsDir.split('/')[0];
352
+ if (topDir !== '.github') { // .github directory usually needs to be kept
353
+ if (!entries.includes(topDir + '/')) {
354
+ entries.push(`${topDir}/`);
355
+ }
356
+ }
357
+ }
358
+ }
359
+
360
+ return entries;
361
+ }
362
+
363
+ /**
364
+ * Get entries to add to .npmignore
365
+ * @returns {string[]} - Entries to ignore
366
+ */
367
+ function getNpmIgnoreEntries() {
368
+ return [
369
+ '# DevBooks development docs (not needed at runtime)',
370
+ 'dev-playbooks/',
371
+ '.devbooks/',
372
+ '',
373
+ '# AI tool config directories',
374
+ '.claude/',
375
+ '.cursor/',
376
+ '.windsurf/',
377
+ '.gemini/',
378
+ '.agent/',
379
+ '.opencode/',
380
+ '.continue/',
381
+ '.qoder/',
382
+ '.github/instructions/',
383
+ '.github/copilot-instructions.md',
384
+ '',
385
+ '# DevBooks instruction files',
386
+ 'CLAUDE.md',
387
+ 'AGENTS.md',
388
+ 'GEMINI.md'
389
+ ];
390
+ }
391
+
392
+ /**
393
+ * Update ignore file, preserving user-defined content
394
+ * @param {string} filePath - ignore file path
395
+ * @param {string[]} entries - Entries to add
396
+ * @returns {object} - { updated: boolean, action: 'created' | 'updated' | 'unchanged' }
397
+ */
398
+ function updateIgnoreFile(filePath, entries) {
399
+ const managedBlock = [
400
+ IGNORE_MARKERS.start,
401
+ ...entries,
402
+ IGNORE_MARKERS.end
403
+ ].join('\n');
404
+
405
+ if (!fs.existsSync(filePath)) {
406
+ // File doesn't exist, create new file
407
+ fs.writeFileSync(filePath, managedBlock + '\n');
408
+ return { updated: true, action: 'created' };
409
+ }
410
+
411
+ const content = fs.readFileSync(filePath, 'utf-8');
412
+ const startIdx = content.indexOf(IGNORE_MARKERS.start);
413
+ const endIdx = content.indexOf(IGNORE_MARKERS.end);
414
+
415
+ if (startIdx !== -1 && endIdx !== -1 && startIdx < endIdx) {
416
+ // Managed block exists, update it
417
+ const before = content.slice(0, startIdx);
418
+ const after = content.slice(endIdx + IGNORE_MARKERS.end.length);
419
+ const newContent = before + managedBlock + after;
420
+
421
+ if (newContent !== content) {
422
+ fs.writeFileSync(filePath, newContent);
423
+ return { updated: true, action: 'updated' };
424
+ }
425
+ return { updated: false, action: 'unchanged' };
426
+ }
427
+
428
+ // No managed block, append to end of file
429
+ const newContent = content.trimEnd() + '\n\n' + managedBlock + '\n';
430
+ fs.writeFileSync(filePath, newContent);
431
+ return { updated: true, action: 'updated' };
432
+ }
433
+
434
+ /**
435
+ * Setup project's ignore files
436
+ * @param {string[]} toolIds - Selected AI tool IDs
437
+ * @param {string} projectDir - Project directory
438
+ * @returns {object[]} - Results array
439
+ */
440
+ function setupIgnoreFiles(toolIds, projectDir) {
441
+ const results = [];
442
+
443
+ // Update .gitignore
444
+ const gitIgnorePath = path.join(projectDir, '.gitignore');
445
+ const gitIgnoreEntries = getGitIgnoreEntries(toolIds);
446
+ const gitResult = updateIgnoreFile(gitIgnorePath, gitIgnoreEntries);
447
+ if (gitResult.updated) {
448
+ results.push({ file: '.gitignore', action: gitResult.action });
449
+ }
450
+
451
+ // Update .npmignore
452
+ const npmIgnorePath = path.join(projectDir, '.npmignore');
453
+ const npmIgnoreEntries = getNpmIgnoreEntries();
454
+ const npmResult = updateIgnoreFile(npmIgnorePath, npmIgnoreEntries);
455
+ if (npmResult.updated) {
456
+ results.push({ file: '.npmignore', action: npmResult.action });
457
+ }
458
+
459
+ return results;
460
+ }
461
+
308
462
  function showVersion() {
309
463
  console.log(`${CLI_COMMAND} v${getCliVersion()}`);
310
464
  }
@@ -459,7 +613,53 @@ function installSkills(toolIds, update = false) {
459
613
  }
460
614
 
461
615
  // ============================================================================
462
- // 安装 Rules(Cursor, Windsurf, Gemini, Antigravity, OpenCode, Continue)
616
+ // Install Claude Code Custom Subagents (solves built-in subagents cannot access Skills)
617
+ // ============================================================================
618
+
619
+ function installClaudeAgents(toolIds, projectDir, update = false) {
620
+ const results = [];
621
+
622
+ // Only Claude Code needs custom subagents
623
+ if (!toolIds.includes('claude')) return results;
624
+
625
+ const agentsSrcDir = path.join(__dirname, '..', 'templates', 'claude-agents');
626
+ const agentsDestDir = path.join(projectDir, '.claude', 'agents');
627
+
628
+ if (!fs.existsSync(agentsSrcDir)) return results;
629
+
630
+ const agentFiles = fs.readdirSync(agentsSrcDir)
631
+ .filter(name => name.endsWith('.md'));
632
+
633
+ if (agentFiles.length === 0) return results;
634
+
635
+ fs.mkdirSync(agentsDestDir, { recursive: true });
636
+
637
+ let installedCount = 0;
638
+ for (const agentFile of agentFiles) {
639
+ const srcPath = path.join(agentsSrcDir, agentFile);
640
+ const destPath = path.join(agentsDestDir, agentFile);
641
+
642
+ if (fs.existsSync(destPath) && !update) continue;
643
+
644
+ fs.copyFileSync(srcPath, destPath);
645
+ installedCount++;
646
+ }
647
+
648
+ if (installedCount > 0) {
649
+ results.push({
650
+ tool: 'Claude Code',
651
+ type: 'agents',
652
+ count: installedCount,
653
+ total: agentFiles.length,
654
+ path: agentsDestDir
655
+ });
656
+ }
657
+
658
+ return results;
659
+ }
660
+
661
+ // ============================================================================
662
+ // Install Rules (Cursor, Windsurf, Gemini, Antigravity, OpenCode, Continue)
463
663
  // ============================================================================
464
664
 
465
665
  function installRules(toolIds, projectDir, update = false) {
@@ -838,17 +1038,25 @@ async function initCommand(projectDir, options) {
838
1038
  });
839
1039
 
840
1040
  if (fullSupportTools.length > 0) {
841
- const skillsSpinner = ora('安装 Skills...').start();
1041
+ const skillsSpinner = ora('Installing Skills...').start();
842
1042
  const skillsResults = installSkills(fullSupportTools);
843
- skillsSpinner.succeed('Skills 安装完成');
1043
+ skillsSpinner.succeed('Skills installed');
844
1044
 
845
1045
  for (const result of skillsResults) {
846
1046
  if (result.count > 0) {
847
- console.log(chalk.gray(` └ ${result.tool}: ${result.count}/${result.total} ${result.type}`));
1047
+ console.log(chalk.gray(` └ ${result.tool}: ${result.count}/${result.total} ${result.type}`));
848
1048
  } else if (result.note) {
849
1049
  console.log(chalk.gray(` └ ${result.tool}: ${result.note}`));
850
1050
  }
851
1051
  }
1052
+
1053
+ // Install Claude Code custom subagents (solves built-in subagents cannot access Skills)
1054
+ const agentsResults = installClaudeAgents(fullSupportTools, projectDir);
1055
+ for (const result of agentsResults) {
1056
+ if (result.count > 0) {
1057
+ console.log(chalk.gray(` └ ${result.tool}: ${result.count} custom subagents → ${result.path}`));
1058
+ }
1059
+ }
852
1060
  }
853
1061
 
854
1062
  // 安装 Rules(Rules 类似系统的工具)
@@ -867,16 +1075,28 @@ async function initCommand(projectDir, options) {
867
1075
  }
868
1076
  }
869
1077
 
870
- // 安装指令文件
871
- const instructionSpinner = ora('创建指令文件...').start();
1078
+ // Install instruction files
1079
+ const instructionSpinner = ora('Creating instruction files...').start();
872
1080
  const instructionResults = installInstructionFiles(selectedTools, projectDir);
873
- instructionSpinner.succeed(`创建了 ${instructionResults.length} 个指令文件`);
1081
+ instructionSpinner.succeed(`Created ${instructionResults.length} instruction files`);
874
1082
 
875
1083
  for (const result of instructionResults) {
876
1084
  console.log(chalk.gray(` └ ${result.tool}: ${path.relative(projectDir, result.path)}`));
877
1085
  }
878
1086
 
879
- // 完成
1087
+ // Setup ignore files
1088
+ const ignoreSpinner = ora('Configuring ignore files...').start();
1089
+ const ignoreResults = setupIgnoreFiles(selectedTools, projectDir);
1090
+ if (ignoreResults.length > 0) {
1091
+ ignoreSpinner.succeed('Ignore files configured');
1092
+ for (const result of ignoreResults) {
1093
+ console.log(chalk.gray(` └ ${result.file}: ${result.action}`));
1094
+ }
1095
+ } else {
1096
+ ignoreSpinner.succeed('Ignore files already up to date');
1097
+ }
1098
+
1099
+ // Done
880
1100
  console.log();
881
1101
  console.log(chalk.green('══════════════════════════════════════'));
882
1102
  console.log(chalk.green('✓') + chalk.bold(' DevBooks 初始化完成!'));
@@ -942,6 +1162,14 @@ async function updateCommand(projectDir) {
942
1162
  }
943
1163
  }
944
1164
 
1165
+ // Update Claude Code custom subagents (project directory)
1166
+ const agentsResults = installClaudeAgents(configuredTools, projectDir, true);
1167
+ for (const result of agentsResults) {
1168
+ if (result.count > 0) {
1169
+ console.log(chalk.green('✓') + ` ${result.tool}: updated ${result.count} custom subagents`);
1170
+ }
1171
+ }
1172
+
945
1173
  // Update Rules (project directory)
946
1174
  const rulesTools = configuredTools.filter(id => {
947
1175
  const tool = AI_TOOLS.find(t => t.id === id);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dev-playbooks",
3
- "version": "1.0.19",
3
+ "version": "1.2.1",
4
4
  "description": "AI-powered spec-driven development workflow",
5
5
  "keywords": [
6
6
  "devbooks",
@@ -115,26 +115,6 @@ If you are not using DevBooks, replace `dev-playbooks/specs` / `dev-playbooks/ch
115
115
 
116
116
  ---
117
117
 
118
- ## `devbooks-proposal-debate-workflow` (Proposal Debate Workflow)
119
-
120
- - Purpose: run “proposal → challenge → judgment” as a 3-role triangular debate (Author/Challenger/Judge isolation), and ensure the Decision Log is explicit.
121
- - When to use:
122
- - You want enforced 3-role contention to raise proposal quality
123
- - Your team often “starts coding before risks are stated”
124
- - Copy-paste prompt:
125
- ```text
126
- You are Proposal Debate Orchestrator. Explicitly use `devbooks-proposal-debate-workflow`.
127
- First read: `dev-playbooks/project.md`
128
- Constraint: Author/Challenger/Judge must be separate conversations/instances; if I cannot provide that, stop and explain why.
129
- Goal: `dev-playbooks/changes/<change-id>/proposal.md` Decision Log must end in Approved/Revise/Rejected (no Pending).
130
- Tell me, step by step, what instruction I should copy-paste into each separate conversation, and what outputs I should paste back here.
131
-
132
- My request:
133
- <one-sentence request + background + constraints>
134
- ```
135
-
136
- ---
137
-
138
118
  ## `devbooks-design-doc` (Design Owner / Design Doc)
139
119
 
140
120
  - Purpose: write `design.md` with What/Constraints + AC-xxx only (no implementation steps). This is the golden truth for tests and planning.
@@ -364,62 +344,23 @@ If you are not using DevBooks, replace `dev-playbooks/specs` / `dev-playbooks/ch
364
344
 
365
345
  ---
366
346
 
367
- ## `devbooks-index-bootstrap` (Index Bootstrapper) [New]
347
+ ## Generating SCIP Index (Manual)
368
348
 
369
- - Purpose: detect project language stack and generate a SCIP index to unlock graph-based code understanding (call graph, impact analysis, symbol references, etc.).
370
- - Triggers:
371
- - User asks for “index initialization / code graph / graph analysis”
372
- - `mcp__ckb__getStatus` reports `healthy: false` for SCIP backend
373
- - New project and `index.scip` does not exist
374
- - When to use:
375
- - You want graph-mode in `devbooks-impact-analysis`
376
- - You want hotspot awareness in `devbooks-coder` / `devbooks-code-review`
377
- - CKB MCP tools report “SCIP backend unavailable”
378
- - Copy-paste prompt:
379
- ```text
380
- Explicitly use `devbooks-index-bootstrap`.
381
- Goal: detect project stack, generate SCIP index, enable graph-based understanding.
382
- Project root: $(pwd)
383
- ```
384
- - Manual indexing (no Skill required):
385
- ```bash
386
- # TypeScript/JavaScript
387
- npm install -g @anthropic-ai/scip-typescript
388
- scip-typescript index --output index.scip
389
-
390
- # Python
391
- pip install scip-python
392
- scip-python index . --output index.scip
393
-
394
- # Go
395
- go install github.com/sourcegraph/scip-go@latest
396
- scip-go --output index.scip
397
- ```
349
+ If you need graph-based code understanding (call graph, impact analysis, symbol references), you can generate a SCIP index manually:
398
350
 
399
- ---
351
+ ```bash
352
+ # TypeScript/JavaScript
353
+ npm install -g @anthropic-ai/scip-typescript
354
+ scip-typescript index --output index.scip
400
355
 
401
- ## `devbooks-federation` (Federation Analyst) [New]
356
+ # Python
357
+ pip install scip-python
358
+ scip-python index . --output index.scip
402
359
 
403
- - Purpose: cross-repo federation analysis and contract synchronization: detect contract changes, analyze cross-repo impact, notify downstream consumers.
404
- - Triggers:
405
- - User asks for “cross-repo impact / federation analysis / contract sync / upstream-downstream dependencies”
406
- - The change touches contract files defined in `federation.yaml`
407
- - When to use:
408
- - Multi-repo projects where you need downstream impact analysis
409
- - External API/contract changes requiring consumer notification
410
- - You want cross-repo traceability
411
- - Prerequisite:
412
- - `.devbooks/federation.yaml` exists at project root (copy from `skills/devbooks-federation/templates/federation.yaml`)
413
- - Copy-paste prompt:
414
- ```text
415
- Explicitly use `devbooks-federation`.
416
- Goal: analyze cross-repo impact for this change, detect contract changes, generate an impact report.
417
- Project root: $(pwd)
418
- Changed files: <list of changed files>
419
- ```
420
- - Script usage:
421
- ```bash
422
- # Check federation contract changes
423
- bash ~/.claude/skills/devbooks-federation/scripts/federation-check.sh --project-root "$(pwd)"
424
- ```
360
+ # Go
361
+ go install github.com/sourcegraph/scip-go@latest
362
+ scip-go --output index.scip
363
+ ```
364
+
365
+ See `docs/Recommended-MCP.md` for more details on configuring CKB.
425
366
 
@@ -48,7 +48,7 @@ When MCP is unavailable, output:
48
48
 
49
49
  ```
50
50
  ⚠️ CKB unavailable (timeout or not configured), running in basic mode.
51
- To enable enhanced features, run devbooks-index-bootstrap skill to build the index.
51
+ To enable enhanced features, manually generate SCIP index.
52
52
  ```
53
53
  ```
54
54
 
@@ -65,7 +65,6 @@ The following Skills do not depend on MCP and do not need an MCP Enhancement sec
65
65
  - devbooks-proposal-author (document-only)
66
66
  - devbooks-proposal-challenger (review-only)
67
67
  - devbooks-proposal-judge (verdict-only)
68
- - devbooks-proposal-debate-workflow (workflow orchestration)
69
68
  - devbooks-design-backport (document backport)
70
69
  - devbooks-spec-gardener (file pruning)
71
70
  - devbooks-test-reviewer (test review)
@@ -88,8 +87,6 @@ The following Skills depend on MCP and require the full MCP Enhancement section:
88
87
  | devbooks-code-review | mcp__ckb__getHotspots | Hotspot highlighting |
89
88
  | devbooks-impact-analysis | mcp__ckb__analyzeImpact, findReferences | Precise impact analysis |
90
89
  | devbooks-brownfield-bootstrap | mcp__ckb__* | COD model generation |
91
- | devbooks-index-bootstrap | mcp__ckb__getStatus | Index status detection |
92
- | devbooks-federation | mcp__ckb__*, mcp__github__* | Cross-repo analysis |
93
90
  | devbooks-router | mcp__ckb__getStatus | Index availability detection |
94
91
  | devbooks-spec-contract | mcp__ckb__findReferences | Reference detection |
95
92
  | devbooks-entropy-monitor | mcp__ckb__getHotspots | Hotspot trend analysis |