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.
- package/README.md +40 -70
- package/bin/devbooks.js +236 -8
- package/package.json +1 -1
- package/skills/Skills-Usage-Guide.md +15 -74
- package/skills/_shared/mcp-enhancement-template.md +1 -4
- package/skills/_shared/references/deviation-detection-routing-protocol.md +199 -0
- package/skills/_shared/workflow-next-steps.md +111 -0
- package/skills/devbooks-brownfield-bootstrap/SKILL.md +2 -2
- package/skills/devbooks-brownfield-bootstrap/scripts/cod-update.sh +1 -1
- package/skills/devbooks-code-review/SKILL.md +34 -1
- package/skills/devbooks-coder/SKILL.md +103 -2
- package/skills/devbooks-delivery-workflow/SKILL.md +2 -2
- package/skills/devbooks-design-backport/SKILL.md +1 -1
- package/skills/devbooks-design-doc/SKILL.md +38 -1
- package/skills/devbooks-docs-sync/SKILL.md +338 -0
- package/skills/devbooks-entropy-monitor/SKILL.md +1 -1
- package/skills/devbooks-impact-analysis/SKILL.md +2 -2
- package/skills/devbooks-implementation-plan/SKILL.md +43 -1
- package/skills/devbooks-proposal-author/SKILL.md +41 -1
- package/skills/devbooks-proposal-author/references/proposal-authoring-prompt.md +10 -0
- package/skills/devbooks-proposal-challenger/SKILL.md +1 -1
- package/skills/devbooks-proposal-judge/SKILL.md +1 -1
- package/skills/devbooks-router/SKILL.md +44 -13
- package/skills/devbooks-spec-contract/SKILL.md +36 -2
- package/skills/devbooks-spec-gardener/SKILL.md +1 -1
- package/skills/devbooks-test-owner/SKILL.md +204 -1
- package/skills/devbooks-test-reviewer/SKILL.md +27 -1
- package/templates/claude-agents/devbooks-coder.md +21 -0
- package/templates/claude-agents/devbooks-explorer.md +21 -0
- package/templates/claude-agents/devbooks-reviewer.md +21 -0
- package/templates/claude-agents/devbooks-test-owner.md +21 -0
- package/templates/dev-playbooks/README.md +34 -66
- package/templates/dev-playbooks/docs/devbooks-setup-guide.md +1 -14
- package/skills/devbooks-federation/SKILL.md +0 -264
- package/skills/devbooks-federation/scripts/federation-check.sh +0 -144
- package/skills/devbooks-federation/templates/federation.yaml +0 -89
- package/skills/devbooks-index-bootstrap/SKILL.md +0 -240
- package/skills/devbooks-proposal-debate-workflow/SKILL.md +0 -78
- package/skills/devbooks-proposal-debate-workflow/references/11-proposal-debate-template.md +0 -35
- package/skills/devbooks-proposal-debate-workflow/references/proposal-debate-workflow.md +0 -24
- 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
|
-
- **
|
|
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
|
-
**
|
|
222
|
-
-
|
|
223
|
-
-
|
|
224
|
-
-
|
|
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
|
-
**
|
|
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
|
-
**
|
|
236
|
-
-
|
|
237
|
-
-
|
|
238
|
-
-
|
|
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
|
-
**
|
|
242
|
-
|
|
243
|
-
**
|
|
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)
|
|
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
|
-
**
|
|
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
|
-
**
|
|
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
|
|
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
|
|
265
|
-
- Role isolation
|
|
266
|
-
-
|
|
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
|
|
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
|
|
371
|
+
<summary><strong>Proposal review workflow</strong></summary>
|
|
400
372
|
|
|
401
|
-
For strict proposal review,
|
|
373
|
+
For strict proposal review, use separate conversations for Challenger and Judge:
|
|
402
374
|
|
|
403
|
-
|
|
404
|
-
|
|
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
|
-
|
|
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
|
-
//
|
|
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('
|
|
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}
|
|
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('
|
|
1078
|
+
// Install instruction files
|
|
1079
|
+
const instructionSpinner = ora('Creating instruction files...').start();
|
|
872
1080
|
const instructionResults = installInstructionFiles(selectedTools, projectDir);
|
|
873
|
-
instructionSpinner.succeed(
|
|
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
|
@@ -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
|
-
##
|
|
347
|
+
## Generating SCIP Index (Manual)
|
|
368
348
|
|
|
369
|
-
|
|
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
|
-
|
|
356
|
+
# Python
|
|
357
|
+
pip install scip-python
|
|
358
|
+
scip-python index . --output index.scip
|
|
402
359
|
|
|
403
|
-
|
|
404
|
-
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
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,
|
|
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 |
|