dev-playbooks 1.1.0 → 1.2.1

package/bin/devbooks.js

@@ -305,6 +305,160 @@ function getCliVersion() {
   }
 }
 
+// ============================================================================
+// Auto-update .gitignore and .npmignore
+// ============================================================================
+
+const IGNORE_MARKERS = {
+  start: '# DevBooks managed - DO NOT EDIT',
+  end: '# End DevBooks managed'
+};
+
+/**
+ * Get entries to add to .gitignore
+ * @param {string[]} toolIds - Selected AI tool IDs
+ * @returns {string[]} - Entries to ignore
+ */
+function getGitIgnoreEntries(toolIds) {
+  const entries = [
+    '# DevBooks local config (contains user preferences, should not be committed)',
+    '.devbooks/'
+  ];
+
+  // Add corresponding AI tool directories based on selected tools
+  for (const toolId of toolIds) {
+    const tool = AI_TOOLS.find(t => t.id === toolId);
+    if (!tool) continue;
+
+    // Add slash command directory
+    if (tool.slashDir) {
+      const topDir = tool.slashDir.split('/')[0];
+      if (!entries.includes(topDir + '/')) {
+        entries.push(`${topDir}/`);
+      }
+    }
+
+    // Add rules directory
+    if (tool.rulesDir) {
+      const topDir = tool.rulesDir.split('/')[0];
+      if (!entries.includes(topDir + '/')) {
+        entries.push(`${topDir}/`);
+      }
+    }
+
+    // Add agents directory (e.g., .github/instructions)
+    if (tool.instructionsDir) {
+      const topDir = tool.instructionsDir.split('/')[0];
+      if (topDir !== '.github') { // .github directory usually needs to be kept
+        if (!entries.includes(topDir + '/')) {
+          entries.push(`${topDir}/`);
+        }
+      }
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * Get entries to add to .npmignore
+ * @returns {string[]} - Entries to ignore
+ */
+function getNpmIgnoreEntries() {
+  return [
+    '# DevBooks development docs (not needed at runtime)',
+    'dev-playbooks/',
+    '.devbooks/',
+    '',
+    '# AI tool config directories',
+    '.claude/',
+    '.cursor/',
+    '.windsurf/',
+    '.gemini/',
+    '.agent/',
+    '.opencode/',
+    '.continue/',
+    '.qoder/',
+    '.github/instructions/',
+    '.github/copilot-instructions.md',
+    '',
+    '# DevBooks instruction files',
+    'CLAUDE.md',
+    'AGENTS.md',
+    'GEMINI.md'
+  ];
+}
+
+/**
+ * Update ignore file, preserving user-defined content
+ * @param {string} filePath - ignore file path
+ * @param {string[]} entries - Entries to add
+ * @returns {object} - { updated: boolean, action: 'created' | 'updated' | 'unchanged' }
+ */
+function updateIgnoreFile(filePath, entries) {
+  const managedBlock = [
+    IGNORE_MARKERS.start,
+    ...entries,
+    IGNORE_MARKERS.end
+  ].join('\n');
+
+  if (!fs.existsSync(filePath)) {
+    // File doesn't exist, create new file
+    fs.writeFileSync(filePath, managedBlock + '\n');
+    return { updated: true, action: 'created' };
+  }
+
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const startIdx = content.indexOf(IGNORE_MARKERS.start);
+  const endIdx = content.indexOf(IGNORE_MARKERS.end);
+
+  if (startIdx !== -1 && endIdx !== -1 && startIdx < endIdx) {
+    // Managed block exists, update it
+    const before = content.slice(0, startIdx);
+    const after = content.slice(endIdx + IGNORE_MARKERS.end.length);
+    const newContent = before + managedBlock + after;
+
+    if (newContent !== content) {
+      fs.writeFileSync(filePath, newContent);
+      return { updated: true, action: 'updated' };
+    }
+    return { updated: false, action: 'unchanged' };
+  }
+
+  // No managed block, append to end of file
+  const newContent = content.trimEnd() + '\n\n' + managedBlock + '\n';
+  fs.writeFileSync(filePath, newContent);
+  return { updated: true, action: 'updated' };
+}
+
+/**
+ * Setup project's ignore files
+ * @param {string[]} toolIds - Selected AI tool IDs
+ * @param {string} projectDir - Project directory
+ * @returns {object[]} - Results array
+ */
+function setupIgnoreFiles(toolIds, projectDir) {
+  const results = [];
+
+  // Update .gitignore
+  const gitIgnorePath = path.join(projectDir, '.gitignore');
+  const gitIgnoreEntries = getGitIgnoreEntries(toolIds);
+  const gitResult = updateIgnoreFile(gitIgnorePath, gitIgnoreEntries);
+  if (gitResult.updated) {
+    results.push({ file: '.gitignore', action: gitResult.action });
+  }
+
+  // Update .npmignore
+  const npmIgnorePath = path.join(projectDir, '.npmignore');
+  const npmIgnoreEntries = getNpmIgnoreEntries();
+  const npmResult = updateIgnoreFile(npmIgnorePath, npmIgnoreEntries);
+  if (npmResult.updated) {
+    results.push({ file: '.npmignore', action: npmResult.action });
+  }
+
+  return results;
+}
+
 function showVersion() {
   console.log(`${CLI_COMMAND} v${getCliVersion()}`);
 }
@@ -459,7 +613,53 @@ function installSkills(toolIds, update = false) {
 }
 
 // ============================================================================
-// 安装 Rules（Cursor, Windsurf, Gemini, Antigravity, OpenCode, Continue）
+// Install Claude Code Custom Subagents (solves built-in subagents cannot access Skills)
+// ============================================================================
+
+function installClaudeAgents(toolIds, projectDir, update = false) {
+  const results = [];
+
+  // Only Claude Code needs custom subagents
+  if (!toolIds.includes('claude')) return results;
+
+  const agentsSrcDir = path.join(__dirname, '..', 'templates', 'claude-agents');
+  const agentsDestDir = path.join(projectDir, '.claude', 'agents');
+
+  if (!fs.existsSync(agentsSrcDir)) return results;
+
+  const agentFiles = fs.readdirSync(agentsSrcDir)
+    .filter(name => name.endsWith('.md'));
+
+  if (agentFiles.length === 0) return results;
+
+  fs.mkdirSync(agentsDestDir, { recursive: true });
+
+  let installedCount = 0;
+  for (const agentFile of agentFiles) {
+    const srcPath = path.join(agentsSrcDir, agentFile);
+    const destPath = path.join(agentsDestDir, agentFile);
+
+    if (fs.existsSync(destPath) && !update) continue;
+
+    fs.copyFileSync(srcPath, destPath);
+    installedCount++;
+  }
+
+  if (installedCount > 0) {
+    results.push({
+      tool: 'Claude Code',
+      type: 'agents',
+      count: installedCount,
+      total: agentFiles.length,
+      path: agentsDestDir
+    });
+  }
+
+  return results;
+}
+
+// ============================================================================
+// Install Rules (Cursor, Windsurf, Gemini, Antigravity, OpenCode, Continue)
 // ============================================================================
 
 function installRules(toolIds, projectDir, update = false) {
@@ -838,17 +1038,25 @@ async function initCommand(projectDir, options) {
   });
 
   if (fullSupportTools.length > 0) {
-    const skillsSpinner = ora('安装 Skills...').start();
+    const skillsSpinner = ora('Installing Skills...').start();
     const skillsResults = installSkills(fullSupportTools);
-    skillsSpinner.succeed('Skills 安装完成');
+    skillsSpinner.succeed('Skills installed');
 
     for (const result of skillsResults) {
       if (result.count > 0) {
-        console.log(chalk.gray(`  └ ${result.tool}: ${result.count}/${result.total} 个 ${result.type}`));
+        console.log(chalk.gray(`  └ ${result.tool}: ${result.count}/${result.total} ${result.type}`));
       } else if (result.note) {
         console.log(chalk.gray(`  └ ${result.tool}: ${result.note}`));
       }
     }
+
+    // Install Claude Code custom subagents (solves built-in subagents cannot access Skills)
+    const agentsResults = installClaudeAgents(fullSupportTools, projectDir);
+    for (const result of agentsResults) {
+      if (result.count > 0) {
+        console.log(chalk.gray(`  └ ${result.tool}: ${result.count} custom subagents → ${result.path}`));
+      }
+    }
   }
 
   // 安装 Rules（Rules 类似系统的工具）
@@ -867,16 +1075,28 @@ async function initCommand(projectDir, options) {
     }
   }
 
-  // 安装指令文件
-  const instructionSpinner = ora('创建指令文件...').start();
+  // Install instruction files
+  const instructionSpinner = ora('Creating instruction files...').start();
   const instructionResults = installInstructionFiles(selectedTools, projectDir);
-  instructionSpinner.succeed(`创建了 ${instructionResults.length} 个指令文件`);
+  instructionSpinner.succeed(`Created ${instructionResults.length} instruction files`);
 
   for (const result of instructionResults) {
     console.log(chalk.gray(`  └ ${result.tool}: ${path.relative(projectDir, result.path)}`));
   }
 
-  // 完成
+  // Setup ignore files
+  const ignoreSpinner = ora('Configuring ignore files...').start();
+  const ignoreResults = setupIgnoreFiles(selectedTools, projectDir);
+  if (ignoreResults.length > 0) {
+    ignoreSpinner.succeed('Ignore files configured');
+    for (const result of ignoreResults) {
+      console.log(chalk.gray(`  └ ${result.file}: ${result.action}`));
+    }
+  } else {
+    ignoreSpinner.succeed('Ignore files already up to date');
+  }
+
+  // Done
   console.log();
   console.log(chalk.green('══════════════════════════════════════'));
   console.log(chalk.green('✓') + chalk.bold(' DevBooks 初始化完成！'));
@@ -942,6 +1162,14 @@ async function updateCommand(projectDir) {
     }
   }
 
+  // Update Claude Code custom subagents (project directory)
+  const agentsResults = installClaudeAgents(configuredTools, projectDir, true);
+  for (const result of agentsResults) {
+    if (result.count > 0) {
+      console.log(chalk.green('✓') + ` ${result.tool}: updated ${result.count} custom subagents`);
+    }
+  }
+
   // Update Rules (project directory)
   const rulesTools = configuredTools.filter(id => {
     const tool = AI_TOOLS.find(t => t.id === id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-playbooks",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "AI-powered spec-driven development workflow",
   "keywords": [
     "devbooks",

package/skills/_shared/references/deviation-detection-routing-protocol.md

@@ -0,0 +1,199 @@
+# Deviation Detection and Routing Protocol
+
+> This protocol defines the deviation detection, recording, and routing mechanisms during skill execution.
+> All Apply phase skills (coder, test-owner, reviewer) must follow this protocol.
+
+## Core Problem
+
+During long tasks (e.g., coder), the following may occur:
+1. Unplanned feature modifications or additions
+2. Discovery that design document constraints need adjustment
+3. Context overflow triggers compact, causing deviation information loss
+
+**Solution**: Real-time persistence + completion-time detection + structured routing
+
+---
+
+## Completion Status Classification (MECE)
+
+Each skill must identify and declare its current status upon completion:
+
+| Code | Status | Meaning | Next Step |
+|:----:|--------|---------|-----------|
+| ✅ | COMPLETED | Completed normally, no deviations | Enter next skill |
+| ⚠️ | COMPLETED_WITH_DEVIATION | Completed but with deviations/additions | design-backport first, then next step |
+| 🔄 | HANDOFF | Needs another role to handle | Return to specified skill |
+| ❌ | BLOCKED | Blocked, needs external input | Record breakpoint, wait |
+| 💥 | FAILED | Failed, gates not passed | Fix and retry |
+
+### Status Determination Rules
+
+```
+If deviation-log.md has unwritten records
+  → COMPLETED_WITH_DEVIATION
+
+If tasks.md has incomplete items
+  → BLOCKED or FAILED (depends on reason)
+
+If tests/ modification needed (for coder)
+  → HANDOFF to test-owner
+
+If all tasks completed and no deviations
+  → COMPLETED
+```
+
+---
+
+## Deviation Log Protocol
+
+### File Location
+
+```
+<change-root>/<change-id>/deviation-log.md
+```
+
+### File Format
+
+```markdown
+# Deviation Log
+
+> This file records all deviations, additions, and temporary decisions during implementation.
+> **Important**: This file persists after compact, ensuring information is not lost.
+
+## Pending Backport Records
+
+| Time | Type | Description | Affected Files | Backported |
+|------|------|-------------|----------------|:----------:|
+| YYYY-MM-DD HH:mm | NEW_FEATURE | Added X feature | src/x.ts | ❌ |
+| YYYY-MM-DD HH:mm | CONSTRAINT_CHANGE | Timeout changed to 60s | config.ts | ❌ |
+| YYYY-MM-DD HH:mm | DESIGN_GAP | Found uncovered edge case | - | ❌ |
+
+## Completed Backport Records
+
+(Move here after design-backport completes)
+
+| Time | Type | Description | Backported To |
+|------|------|-------------|---------------|
+```
+
+### Deviation Type Definitions
+
+| Type | Code | Description | Example |
+|------|------|-------------|---------|
+| New Feature | NEW_FEATURE | Added feature not in design | New warmup() method |
+| Constraint Change | CONSTRAINT_CHANGE | Modified constraint/config from design | Timeout from 30s to 60s |
+| Design Gap | DESIGN_GAP | Found scenario not covered by design | Concurrency not considered |
+| API Change | API_CHANGE | Public interface differs from design | Added options parameter |
+| Dependency Change | DEPENDENCY_CHANGE | Introduced unplanned dependency | Added lodash |
+
+---
+
+## Real-time Persistence Protocol
+
+### When to Write to deviation-log.md
+
+**Must write immediately** in these situations:
+
+1. **Added new files/functions** not in tasks.md
+2. **Modified config/constraints** inconsistent with design.md
+3. **Found edge cases** not covered by design.md
+4. **Temporary decisions** needing later confirmation
+
+### How to Write
+
+```markdown
+## Example: Found need to add feature
+
+Append a line to deviation-log.md:
+
+| 2024-01-15 10:30 | NEW_FEATURE | Added cache warmup for better first-access performance | src/cache.ts | ❌ |
+```
+
+### Compact Protection
+
+deviation-log.md is a **persistent file** unaffected by compact. Even if conversation context is compressed:
+- File content still exists
+- Next skill can read and process
+
+---
+
+## Next Step Routing Rules
+
+### General Routing Table
+
+| Current Skill | Completion Status | Next Step |
+|---------------|-------------------|-----------|
+| Any | COMPLETED_WITH_DEVIATION | `devbooks-design-backport` |
+| coder | COMPLETED | `devbooks-code-review` |
+| coder | HANDOFF (test issue) | `devbooks-test-owner` |
+| test-owner | COMPLETED | `devbooks-coder` |
+| test-owner | HANDOFF (design issue) | `devbooks-design-backport` |
+| code-review | COMPLETED (has spec delta) | `devbooks-spec-gardener` |
+| code-review | COMPLETED (no spec delta) | Archive complete |
+| Any | BLOCKED | Record breakpoint, wait for user |
+| Any | FAILED | Fix and retry current skill |
+
+### Routing Output Template
+
+After completing a skill, must output in this format:
+
+```markdown
+## Completion Status
+
+**Status**: [COMPLETED / COMPLETED_WITH_DEVIATION / HANDOFF / BLOCKED / FAILED]
+
+**Deviation Records**: [Has N pending / None]
+
+## Next Step
+
+**Recommended**: `devbooks-xxx skill`
+
+**Reason**: [specific reason]
+
+**How to invoke**:
+Run devbooks-xxx skill for change <change-id>
+```
+
+---
+
+## Interaction with design-backport
+
+### Trigger Conditions
+
+When deviation-log.md has **pending records** (Backported=❌), must execute design-backport first.
+
+### Backport Completion Marking
+
+After design-backport completes:
+1. Move record from "Pending" to "Completed"
+2. Update "Backported" column to ✅
+3. Record specific location backported to
+
+---
+
+## Detection Script (Optional)
+
+```bash
+# Check for pending deviation backports
+check_deviation() {
+  local change_dir="$1"
+  local log_file="${change_dir}/deviation-log.md"
+
+  if [[ ! -f "$log_file" ]]; then
+    echo "NO_DEVIATION"
+    return 0
+  fi
+
+  if grep -q "| ❌" "$log_file"; then
+    echo "HAS_PENDING_DEVIATION"
+    return 1
+  fi
+
+  echo "ALL_BACKPORTED"
+  return 0
+}
+```
+
+---
+
+*This protocol is core to the DevBooks Apply phase. All implementation skills must follow it.*

package/skills/devbooks-brownfield-bootstrap/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: devbooks-brownfield-bootstrap
 description: "devbooks-brownfield-bootstrap: Brownfield project initialization. When the truth directory is empty, generate project profile, glossary, baseline specs, and minimum verification anchors to avoid 'patching specs while changing behavior'. Use when user says 'brownfield init/baseline specs/project profile/establish glossary/onboard legacy project to context protocol' etc."
-tools:
+allowed-tools:
   - Glob
   - Grep
   - Read

package/skills/devbooks-code-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: devbooks-code-review
 description: devbooks-code-review: Perform readability/consistency/dependency health/code smell reviews as a Reviewer role, outputting only review comments and actionable suggestions without discussing business correctness. Use when user says "help me do code review/review maintainability/code smells/dependency risks/consistency suggestions", or when executing as reviewer during DevBooks apply phase.
-tools:
+allowed-tools:
   - Glob
   - Grep
   - Read

package/skills/devbooks-coder/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: devbooks-coder
 description: "devbooks-coder: Implements features strictly following tasks.md as the Coder role and runs quality gates. Modifying tests/ is prohibited; tests and static checks serve as the sole completion criteria. Use when the user says 'implement as planned/fix failing tests/make all gates green/implement task items/don't modify tests', or when executing as coder during the DevBooks apply phase."
-tools:
+allowed-tools:
   - Glob
   - Grep
   - Read
@@ -245,45 +245,104 @@ Detection Results:
 
 ---
 
-## Next Step Recommendations
+## Deviation Detection and Persistence Protocol
 
-**Reference**: `skills/_shared/workflow-next-steps.md`
+**Reference**: `skills/_shared/references/deviation-detection-routing-protocol.md`
 
-After completing coder (all tasks done, gates Green), the next step is:
+### Real-time Persistence Requirements
 
-| Condition | Next Skill | Reason |
-|-----------|------------|--------|
-| All tasks completed | `devbooks-code-review` | Review for readability/consistency |
-| Test changes needed | Hand back to `devbooks-test-owner` | Coder cannot modify tests |
+During implementation, you **must immediately** write to `deviation-log.md` in these situations:
+
+| Situation | Type | Example |
+|-----------|------|---------|
+| Added functionality not in tasks.md | NEW_FEATURE | Added warmup() method |
+| Modified constraint from design.md | CONSTRAINT_CHANGE | Timeout changed to 60s |
+| Found edge case not covered by design | DESIGN_GAP | Concurrency scenario |
+| Public interface differs from design | API_CHANGE | Added parameter |
+
+### deviation-log.md Format
+
+```markdown
+# Deviation Log
+
+## Pending Backport Records
+
+| Time | Type | Description | Affected Files | Backported |
+|------|------|-------------|----------------|:----------:|
+| 2024-01-15 10:30 | NEW_FEATURE | Added cache warmup feature | src/cache.ts | ❌ |
+```
+
+### Compact Protection
+
+**Important**: deviation-log.md is a persistent file unaffected by compact. Even if the conversation is compressed, deviation information is preserved.
+
+---
+
+## Completion Status and Routing
+
+### Completion Status Classification (MECE)
+
+| Code | Status | Determination Criteria | Next Step |
+|:----:|--------|------------------------|-----------|
+| ✅ | COMPLETED | All tasks done, no deviations | `devbooks-code-review` |
+| ⚠️ | COMPLETED_WITH_DEVIATION | Tasks done, deviation-log has pending records | `devbooks-design-backport` |
+| 🔄 | HANDOFF | Found test issues needing modification | `devbooks-test-owner` |
+| ❌ | BLOCKED | Needs external input/decision | Record breakpoint, wait for user |
+| 💥 | FAILED | Gates not passed | Fix and retry |
+
+### Status Determination Flow
 
-**CRITICAL**:
-- Coder **cannot modify** `tests/**`
-- If test issues are found, hand back to Test Owner (separate chat)
-- The workflow order is:
 ```
-coder → code-review → spec-gardener (if spec deltas) → archive
+1. Check if deviation-log.md has "| ❌" records
+   → Yes: COMPLETED_WITH_DEVIATION
+
+2. Check if tests/ modification needed
+   → Yes: HANDOFF to test-owner
+
+3. Check if tasks.md is fully completed
+   → No: BLOCKED or FAILED
+
+4. All checks passed
+   → COMPLETED
 ```
 
-### Output Template
+### Routing Output Template (Required)
 
-After completing coder (all gates Green), output:
+After completing coder, you **must** output in this format:
 
 ```markdown
-## Recommended Next Step
+## Completion Status
+
+**Status**: ✅ COMPLETED / ⚠️ COMPLETED_WITH_DEVIATION / 🔄 HANDOFF / ❌ BLOCKED / 💥 FAILED
+
+**Task Progress**: X/Y completed
 
-**Next: `devbooks-code-review`**
+**Deviation Records**: Has N pending / None
 
-Reason: All tasks are complete and gates are Green. The next step is code review for readability, consistency, and maintainability.
+## Next Step
+
+**Recommended**: `devbooks-xxx skill`
+
+**Reason**: [specific reason]
 
 ### How to invoke
-```
-Run devbooks-code-review skill for change <change-id>
+Run devbooks-xxx skill for change <change-id>
 ```
 
-### After Review
-- If spec deltas exist: `devbooks-spec-gardener` to merge into truth
-- If no spec deltas: Archive complete
-```
+### Specific Routing Rules
+
+| My Status | Next Step | Reason |
+|-----------|-----------|--------|
+| COMPLETED | `devbooks-code-review` | Review readability/consistency |
+| COMPLETED_WITH_DEVIATION | `devbooks-design-backport` | Backport design first, then review |
+| HANDOFF (test issue) | `devbooks-test-owner` | Coder cannot modify tests |
+| BLOCKED | Wait for user | Record breakpoint area |
+| FAILED | Fix and retry | Analyze failure reason |
+
+**Critical Constraints**:
+- Coder **can never modify** `tests/**`
+- If test issues found, must HANDOFF to Test Owner (separate session)
+- If deviations exist, must design-backport first before continuing
 
 ---
 

package/skills/devbooks-delivery-workflow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: devbooks-delivery-workflow
 description: devbooks-delivery-workflow: Run a change through a traceable closed-loop workflow (Design->Plan->Trace->Verify->Implement->Archive), with clear DoD, traceability matrix, and role isolation (Test Owner and Coder separation). Use when the user says "run closed-loop/delivery acceptance/traceability matrix/DoD/close and archive/acceptance workflow" etc.
-tools:
+allowed-tools:
   - Glob
   - Grep
   - Read

package/skills/devbooks-design-backport/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: devbooks-design-backport
 description: devbooks-design-backport: Backport newly discovered constraints, conflicts, or gaps from implementation back to design.md (keeping design as the golden truth), with annotated decisions and impacts. Use when the user says "backport design/update design doc/Design Backport/design-implementation mismatch/need to clarify constraints" etc.
-tools:
+allowed-tools:
   - Glob
   - Grep
   - Read

package/skills/devbooks-design-doc/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: devbooks-design-doc
 description: devbooks-design-doc: Produce design documents (design.md) for change packages, focusing only on What/Constraints and AC-xxx, without implementation steps. Use when user says "write design doc/Design Doc/architecture design/constraints/acceptance criteria/AC/C4 Delta" etc.
-tools:
+allowed-tools:
   - Glob
   - Grep
   - Read