dev-playbooks 2.4.0 → 3.0.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0] - 2026-01-26
+
+### Added
+
+- **AI-native workflow and protocol updates**:
+  - Start/Router entrypoints and phase routing guidance
+  - Change package templates and protocol contracts (RUNBOOK, verification/compliance/rollback, Knife Plan, contract schemas)
+  - Quality gates and evidence structure (G0–G6, risk and audit requirements)
+  - Dependency audit script and release verification entrypoints
+  - Updated architecture/file-system views and workflow diagram template
+
+### Changed
+
+- **CLI entrypoints**:
+  - Add `start` and `router` commands for entry guidance (does not run AI)
+  - Help output links to templates and workflow docs
+
+---
+
 ## [2.3.0] - 2026-01-25
 
 ### Added

package/README.md

@@ -21,6 +21,14 @@ This skill orchestrates the full development loop: Proposal -> Design -> Spec ->
 
 **Best for**: new feature work, major refactors, teams new to DevBooks
 
+If you're not sure which entrypoint to use, start with:
+
+```bash
+/devbooks:start
+```
+
+Start is the default entrypoint. It routes you to the shortest closed-loop next step.
+
 ---
 
 ## Positioning and Writing Conventions
@@ -108,6 +116,7 @@ dev-playbooks update
 ## Docs
 
 - [DevBooks setup guide](docs/devbooks-setup-guide.md) - setup instructions
+- [AI-native workflow](docs/ai-native-workflow.md) - workflow, roles, evidence
 - [Recommended MCP](docs/Recommended-MCP.md) - MCP server recommendations
 
 ---

package/bin/devbooks.js

@@ -9,6 +9,8 @@
  *   dev-playbooks init [path] [options]
  *   dev-playbooks update [path]           # Update CLI and configured tools
  *   dev-playbooks migrate --from <framework> [options]
+ *   dev-playbooks start [options]         # Entry guidance (does not run AI)
+ *   dev-playbooks router [options]        # Routing guidance (does not run AI)
  *
  * Options:
  *   --tools <tools>    Non-interactive tool selection: all, none, or comma-separated list
@@ -33,6 +35,11 @@ const __dirname = path.dirname(__filename);
 
 const CLI_COMMAND = 'dev-playbooks';
 const XDG_CONFIG_HOME = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+const ENTRY_DOC = 'docs/ai-native-workflow.md';
+const ENTRY_TEMPLATES = {
+  start: 'templates/claude-commands/devbooks/start.md',
+  router: 'templates/claude-commands/devbooks/router.md'
+};
 
 // Version check cache configuration
 const VERSION_CACHE_FILE = path.join(os.tmpdir(), `${CLI_COMMAND}-version-cache.json`);
@@ -103,8 +110,9 @@ const AI_TOOLS = [
     id: 'cursor',
     name: 'Cursor',
     description: 'Cursor AI IDE',
-    skillsSupport: SKILLS_SUPPORT.RULES,
+    skillsSupport: SKILLS_SUPPORT.FULL,
     slashDir: '.cursor/commands/devbooks',
+    skillsDir: '.cursor/skills',  // Project-level
     rulesDir: '.cursor/rules',
     instructionFile: null,
     available: true
@@ -1799,6 +1807,48 @@ async function migrateCommand(projectDir, options) {
 // Help Information
 // ============================================================================
 
+function showStartHelp() {
+  console.log();
+  console.log(chalk.bold('DevBooks Start') + ' - default entry guidance');
+  console.log();
+  console.log(chalk.cyan('Usage:'));
+  console.log(`  ${CLI_COMMAND} start [options]`);
+  console.log();
+  console.log(chalk.cyan('Notes:'));
+  console.log('  This command provides entry guidance only (it does not run AI or call Skills).');
+  console.log('  If you are unsure what to do next, use Start to get routing guidance.');
+  console.log();
+  console.log(chalk.cyan('Entry template:'));
+  console.log(`  ${ENTRY_TEMPLATES.start}`);
+  console.log();
+  console.log(chalk.cyan('Workflow doc:'));
+  console.log(`  ${ENTRY_DOC}`);
+  console.log();
+  console.log(chalk.cyan('Related:'));
+  console.log(`  ${CLI_COMMAND} router --help`);
+}
+
+function showRouterHelp() {
+  console.log();
+  console.log(chalk.bold('DevBooks Router') + ' - routing guidance');
+  console.log();
+  console.log(chalk.cyan('Usage:'));
+  console.log(`  ${CLI_COMMAND} router [options]`);
+  console.log();
+  console.log(chalk.cyan('Notes:'));
+  console.log('  This command provides routing guidance only (it does not run AI or call Skills).');
+  console.log('  Use Router when you need phase detection and shortest-path routing.');
+  console.log();
+  console.log(chalk.cyan('Entry template:'));
+  console.log(`  ${ENTRY_TEMPLATES.router}`);
+  console.log();
+  console.log(chalk.cyan('Workflow doc:'));
+  console.log(`  ${ENTRY_DOC}`);
+  console.log();
+  console.log(chalk.cyan('Related:'));
+  console.log(`  ${CLI_COMMAND} start --help`);
+}
+
 function showHelp() {
   console.log();
   console.log(chalk.bold('DevBooks') + ' - AI-agnostic spec-driven development workflow');
@@ -1807,6 +1857,8 @@ function showHelp() {
   console.log(`  ${CLI_COMMAND} init [path] [options]              Initialize DevBooks`);
   console.log(`  ${CLI_COMMAND} update [path]                      Update CLI and configured tools`);
   console.log(`  ${CLI_COMMAND} migrate --from <framework> [opts]  Migrate from other frameworks`);
+  console.log(`  ${CLI_COMMAND} start [options]                   Entry guidance (does not run AI)`);
+  console.log(`  ${CLI_COMMAND} router [options]                  Routing guidance (does not run AI)`);
   console.log();
   console.log(chalk.cyan('Options:'));
   console.log('  --tools <tools>    Non-interactive AI tool selection');
@@ -1820,6 +1872,11 @@ function showHelp() {
   console.log('  -h, --help         Show this help message');
   console.log('  -v, --version      Show version');
   console.log();
+  console.log(chalk.cyan('Entry templates and docs:'));
+  console.log(`  Start template:  ${ENTRY_TEMPLATES.start}`);
+  console.log(`  Router template: ${ENTRY_TEMPLATES.router}`);
+  console.log(`  Workflow doc:    ${ENTRY_DOC}`);
+  console.log();
   console.log(chalk.cyan('Supported AI Tools:'));
 
   // Group tools by Skills support level
@@ -1863,26 +1920,35 @@ function showHelp() {
   console.log(`  ${CLI_COMMAND} migrate --from openspec     # Migrate from OpenSpec`);
   console.log(`  ${CLI_COMMAND} migrate --from speckit      # Migrate from spec-kit`);
   console.log(`  ${CLI_COMMAND} migrate --from openspec --dry-run  # Dry run migration`);
+  console.log(`  ${CLI_COMMAND} start                       # Show default entry guidance`);
+  console.log(`  ${CLI_COMMAND} router                      # Show routing guidance`);
 }
 
 // ============================================================================
 // Main Entry
 // ============================================================================
 
+async function startCommand() {
+  showStartHelp();
+}
+
+async function routerCommand() {
+  showRouterHelp();
+}
+
 async function main() {
   const args = process.argv.slice(2);
 
   // Parse arguments
   let command = null;
   let projectPath = null;
-  const options = {};
+  const options = { help: false };
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
 
     if (arg === '-h' || arg === '--help') {
-      showHelp();
-      process.exit(0);
+      options.help = true;
     } else if (arg === '-v' || arg === '--version') {
       showVersion();
       process.exit(0);
@@ -1912,12 +1978,28 @@ async function main() {
 
   // 执行命令
   try {
+    if (options.help) {
+      if (command === 'start') {
+        showStartHelp();
+        return;
+      }
+      if (command === 'router') {
+        showRouterHelp();
+        return;
+      }
+      showHelp();
+      return;
+    }
     if (command === 'init' || !command) {
       await initCommand(projectDir, options);
     } else if (command === 'update') {
       await updateCommand(projectDir);
     } else if (command === 'migrate') {
       await migrateCommand(projectDir, options);
+    } else if (command === 'start') {
+      await startCommand();
+    } else if (command === 'router') {
+      await routerCommand();
     } else {
       console.log(chalk.red(`未知命令: ${command}`));
       showHelp();

package/package.json

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

package/scripts/dependency-audit.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage: dependency-audit.sh [options]
+
+Description:
+  Run a dependency audit and write a log for evidence review.
+
+Options:
+  --project-root DIR  Project root directory (default: current dir)
+  --output FILE       Output log file path (default: dependency-audit.log)
+  -h, --help          Show this help message
+
+Examples:
+  dependency-audit.sh --output evidence/audit/dependency-audit.log
+USAGE
+}
+
+project_root="$(pwd)"
+output_file="dependency-audit.log"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --project-root)
+      project_root="${2:-}"
+      shift 2
+      ;;
+    --output)
+      output_file="${2:-}"
+      shift 2
+      ;;
+    *)
+      echo "ERROR: unknown option: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [[ -z "$project_root" || -z "$output_file" ]]; then
+  echo "ERROR: project root and output file are required" >&2
+  exit 2
+fi
+
+pkg_file="${project_root}/package.json"
+lock_file="${project_root}/package-lock.json"
+
+if [[ ! -f "$pkg_file" ]]; then
+  echo "ERROR: package.json not found at ${pkg_file}" >&2
+  exit 1
+fi
+
+mkdir -p "$(dirname "$output_file")"
+
+{
+  echo "Dependency Audit"
+  echo "run_at: $(date +%Y-%m-%dT%H:%M:%S%z)"
+  echo "project_root: ${project_root}"
+  echo "package.json: ${pkg_file}"
+  if [[ -f "$lock_file" ]]; then
+    echo "package-lock.json: ${lock_file}"
+  else
+    echo "package-lock.json: missing"
+  fi
+  echo ""
+} >"$output_file"
+
+status=0
+
+if command -v npm >/dev/null 2>&1; then
+  temp_output="$(mktemp)"
+  if npm --prefix "$project_root" audit --json >"$temp_output" 2>/dev/null; then
+    echo "npm_audit: ok" >>"$output_file"
+    echo "summary: no audit errors" >>"$output_file"
+  else
+    status=1
+    echo "npm_audit: failed" >>"$output_file"
+    echo "summary: audit reported issues or failed" >>"$output_file"
+  fi
+  echo "" >>"$output_file"
+  echo "raw_audit_json:" >>"$output_file"
+  cat "$temp_output" >>"$output_file"
+  rm -f "$temp_output"
+else
+  status=1
+  echo "npm_audit: skipped (npm not found)" >>"$output_file"
+  echo "summary: audit not executed" >>"$output_file"
+fi
+
+exit "$status"
+

package/skills/devbooks-coder/SKILL.md

@@ -14,75 +14,261 @@ allowed-tools:
 
 ## Progressive Disclosure
 
-### Base (Required)
+### Base Layer (Required)
 Goal: Implement only what is specified in `tasks.md` and produce Green evidence.
-Inputs: user goal, `tasks.md`, project codebase, change package context.
-Outputs: implementation changes, updated `tasks.md`, Green evidence logs under `evidence/green-final/`.
-Boundaries: do not modify `tests/**`; do not edit `verification.md` or the AC matrix.
-Evidence: reference gate outputs and log paths.
+Inputs: User goal, existing docs, change package context, or project path.
+Outputs: Executable artifacts, updated `tasks.md`, Green evidence logs under `evidence/green-final/`.
+Boundaries: Do not replace other roles' duties; do not modify `tests/**`.
+Evidence: Reference output artifact paths or execution logs.
 
-### Advanced (Optional)
-Use when you need: risk notes, minimal-diff planning, deviation recording.
+### Advanced Layer (Optional)
+Use when: You need to refine strategies, boundaries, or highlight risks.
 
-### Extended (Optional)
-Use when you need: faster search/impact via optional MCP capabilities.
+### Extended Layer (Optional)
+Use when: You need to collaborate with external systems or optional tools.
 
 ## Recommended MCP Capability Types
-
 - Code search (code-search)
 - Reference tracking (reference-tracking)
 - Impact analysis (impact-analysis)
 
-## Role Isolation (Mandatory)
-
-- Test Owner and Coder must be separate conversations/instances.
-- Do not switch roles within one conversation.
-- If tests or `verification.md` require changes, hand off to Test Owner.
+## Quick Start
 
-## Core Responsibilities
+My Responsibilities:
+1. **Strictly implement functionality according to tasks.md**
+2. **Run acceptance anchors in the verification plan** (tests/, static checks, build, etc.)
+3. **Save Green evidence** to the change package `evidence/green-final/`
+4. **Prohibited from modifying tests/** (If tests need changes, hand back to Test Owner)
 
-1. Implement strictly according to `<change-root>/<change-id>/tasks.md`.
-2. Run the gate checks required by the change (tests/build/static checks).
-3. Save Green evidence to `<change-root>/<change-id>/evidence/green-final/`.
-4. Check off tasks only when relevant gates pass.
-5. Record discoveries that require design/spec updates to `deviation-log.md`.
+## Role Isolation (Mandatory)
 
-## Hard Boundaries
+- Test Owner and Coder must be in separate conversations/instances.
+- This Skill executes only as Coder and does not switch to other roles.
 
-- Allowed: implementation code, `tasks.md`, `deviation-log.md`, evidence logs.
-- Prohibited: `tests/**`, edits to `verification.md`, checking off the AC matrix.
+---
 
 ## Prerequisites: Configuration Discovery
 
 Before execution, you **must** search for configuration in the following order (stop when found):
 1. `.devbooks/config.yaml` (if exists) -> Parse and use its mappings
-2. `dev-playbooks/project.md` (if exists) -> Dev-Playbooks protocol, use default mappings
-3. `project.md` (if exists) -> Template protocol, use default mappings
+2. `dev-playbooks/project.md` (if exists) -> Dev-Playbooks protocol
+3. `project.md` (if exists) -> template protocol
 4. If still undetermined -> **Stop and ask the user**
 
-If the configuration specifies `agents_doc` (rules document), you **must read that document first** before performing any operations.
+**Key Constraints**:
+- If the configuration specifies `agents_doc` (rules document), you **must read that document first** before performing any operations.
+- Do not guess the directory root.
+
+---
+
+## 📚 Reference Documents
+
+### Required (Read Immediately)
+
+1. **AI Behavior Guidelines**: `~/.claude/skills/_shared/references/ai-behavior-guidelines.md`
+   - Verifiability gatekeeping, structural quality gatekeeping, completeness gatekeeping
+   - Basic rules for all skills
+
+2. **Code Implementation Prompt**: `references/code-implementation-prompt.md`
+   - Complete code implementation guide
+   - Execute strictly according to this prompt
+
+### Read on Demand
+
+3. **Test Execution Strategy**: `references/test-execution-strategy.md`
+   - Details on @smoke/@critical/@full tags
+   - Async vs. Sync boundaries
+   - *When to read*: When you need to understand the test execution strategy
+
+4. **Completion Status and Routing**: `references/completion-status-and-routing.md`
+   - Completion status classification (MECE)
+   - Routing output templates
+   - *When to read*: When outputting status upon task completion
+
+5. **Hotspot Awareness and Risk Assessment**: `references/hotspot-awareness-and-risk-assessment.md`
+   - Hotspot file warnings
+   - *When to read*: When risk assessment is needed
+
+6. **Low Risk Modification Techniques**: `references/low-risk-modification-techniques.md`
+   - Safe refactoring techniques
+   - *When to read*: When refactoring is needed
+
+7. **Coding Style Guidelines**: `references/coding-style-guidelines.md`
+   - Code style specifications
+   - *When to read*: When unsure about code style
+
+8. **Logging Standard**: `references/logging-standard.md`
+   - Log levels and formats
+   - *When to read*: When logging needs to be added
+
+9. **Error Code Standard**: `references/error-code-standard.md`
+   - Error code design
+   - *When to read*: When error codes need to be defined
+
+---
+
+## Core Workflow
+
+### 1. Resume from Breakpoint
+
+Before starting, you **must** execute:
+
+1. **Read Progress**: Open `<change-root>/<change-id>/tasks.md`, identify checked `- [x]` tasks.
+2. **Locate Resume Point**: Find the first `- [ ]` after the "last `[x]`".
+3. **Output Confirmation**: Clearly inform the user of the current progress, for example:
+   ```
+   Detected T1-T6 completed (6/10), resuming from T7.
+   ```
+
+### 2. Real-time Progress Updates
+
+> **Core Principle**: Complete one task, check one box immediately. Do not wait until all are done to batch check.
+
+**Check-off Timing**:
+
+| Timing | Action |
+|--------|--------|
+| Code writing complete | Do not check yet |
+| Compilation passes | Do not check yet |
+| Relevant tests pass | **Check immediately** |
+| Multiple tasks complete together | Check one by one, do not batch |
+
+### 3. Implement Code
+
+Execute strictly according to `references/code-implementation-prompt.md`.
+
+### 4. Run Tests
+
+```bash
+# During development: run @smoke frequently
+npm test -- --grep "@smoke"
+
+# Before committing: run @critical
+npm test -- --grep "@smoke|@critical"
+
+# After commit: CI automatically runs @full (Coder does not wait)
+git push  # triggers CI
+```
+
+### 5. Output Completion Status
+
+Refer to `references/completion-status-and-routing.md`.
+
+---
+
+## Key Constraints
+
+### Role Boundaries
+
+| Allowed | Prohibited |
+|---------|------------|
+| Modify `src/**` code | ❌ Modify `tests/**` |
+| Check `tasks.md` items | ❌ Modify `verification.md` |
+| Record deviations to `deviation-log.md` | ❌ Check AC coverage matrix |
+| Run fast-track tests (`@smoke`/`@critical`) | ❌ Set verification.md Status to Verified/Done |
+| Trigger `@full` tests (CI/Background) | ❌ Wait for @full completion (can start next change) |
+
+### Code Quality Constraints
+
+#### Forbidden Commit Patterns
+
+| Pattern | Detection Command | Reason |
+|---------|-------------------|--------|
+| `test.only` | `rg '\.only\s*\(' src/` | Skips other tests |
+| `console.log` | `rg 'console\.log' src/` | Debug code residue |
+| `debugger` | `rg 'debugger' src/` | Debug breakpoint residue |
+| `// TODO` without issue | `rg 'TODO(?!.*#\d+)' src/` | Untrackable todo |
+| `any` type | `rg ': any[^a-z]' src/` | Type safety hole |
+| `@ts-ignore` | `rg '@ts-ignore' src/` | Hides type errors |
+
+#### Pre-commit Mandatory Checks
+
+```bash
+# 1. Compilation Check (Mandatory)
+npm run compile || exit 1
+
+# 2. Lint Check (Mandatory)
+npm run lint || exit 1
+
+# 3. Test Check (Mandatory)
+npm test || exit 1
+
+# 4. test.only Check (Mandatory)
+if rg -l '\.only\s*\(' tests/ src/**/test/; then
+  echo "error: found .only() in tests" >&2
+  exit 1
+fi
+
+# 5. Debug Code Check (Mandatory)
+if rg -l 'console\.(log|debug)|debugger' src/ --type ts; then
+  echo "error: found debug statements" >&2
+  exit 1
+fi
+```
+
+---
+
+## Output Management
+
+Prevent large output from polluting context:
+
+| Scenario | Handling Method |
+|----------|-----------------|
+| Command output > 50 lines | Keep only first/last 10 lines + middle summary |
+| Test output | Extract key failure info, do not paste full log |
+| Log output | Save to disk at `<change-root>/<change-id>/evidence/`, quote path only |
+| Large file content | Quote path, do not inline |
+
+---
+
+## Evidence Path Convention
+
+**Green evidence must be saved to**:
+```
+<change-root>/<change-id>/evidence/green-final/
+```
+
+**Correct Path Examples**:
+```bash
+# Dev-Playbooks default path
+dev-playbooks/changes/<change-id>/evidence/green-final/test-$(date +%Y%m%d-%H%M%S).log
+
+# Using script
+devbooks change-evidence <change-id> --label green-final -- npm test
+```
+
+---
+
+## Deviation Detection and Recording
+
+**Reference**: `~/.claude/skills/_shared/references/deviation-detection-routing-protocol.md`
+
+During implementation, you **must immediately** write the following situations to `deviation-log.md`:
+
+| Situation | Type | Example |
+|-----------|------|---------|
+| Added feature not in tasks.md | NEW_FEATURE | Added warmup() method |
+| Changed constraint in design.md | CONSTRAINT_CHANGE | Timeout changed to 60s |
+| Found edge case not covered by design | DESIGN_GAP | Public interface inconsistent with design |
+| API Signature Change | API_CHANGE | Argument added |
+
+---
+
+## Context Awareness
 
-## Minimal Workflow
+Detection rules refer to: `~/.claude/skills/_shared/context-detection-template.md`
 
-1. Read `<change-root>/<change-id>/tasks.md` and resume from the first unchecked item.
-2. Implement tasks with a minimal diff.
-3. Run relevant gates; if any gate fails, fix implementation (not tests) and rerun.
-4. Write logs to `evidence/green-final/` and reference them in your output.
-5. Check off completed tasks; do not batch-check.
-6. If you find gaps in design/spec/tasks, write them to `deviation-log.md` and hand off.
+### Modes Supported by This Skill
 
-## References
+| Mode | Trigger Condition | Behavior |
+|------|-------------------|----------|
+| **First Implementation** | tasks.md all `[ ]` | Start from MP1.1 |
+| **Resume from Breakpoint** | tasks.md has some `[x]` | Continue from first `[ ]` after last `[x]` |
+| **Gate Fix** | Test failures need fixing | Prioritize failed items |
 
-Required:
-- `~/.claude/skills/_shared/references/ai-behavior-guidelines.md`
-- `references/code-implementation-prompt.md`
+### Prerequisite Checks
 
-As needed:
-- `references/test-execution-strategy.md`
-- `references/completion-status-and-routing.md`
-- `references/hotspot-awareness-and-risk-assessment.md`
-- `references/low-risk-modification-techniques.md`
-- `references/coding-style-guidelines.md`
-- `references/logging-standard.md`
-- `references/error-code-standard.md`
-- `~/.claude/skills/_shared/references/deviation-detection-routing-protocol.md`
+- [ ] `tasks.md` exists
+- [ ] `verification.md` exists
+- [ ] Test Owner not executed in current session
+- [ ] `tests/**` has test files

package/skills/devbooks-docs-consistency/scripts/completeness-checker.sh

@@ -58,9 +58,9 @@ report_line() {
   local ok="$2"
   local msg="$3"
   if [[ "$ok" == "1" ]]; then
-    printf "- %s: ✓ %s\n" "$name" "$msg"
+    printf -- "- %s: ✓ %s\n" "$name" "$msg"
   else
-    printf "- %s: ✗ %s\n" "$name" "$msg"
+    printf -- "- %s: ✗ %s\n" "$name" "$msg"
   fi
 }
 

package/skills/devbooks-router/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: devbooks-router
 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.
+recommended_experts: ["System Architect", "Product Manager"]
 allowed-tools:
   - Glob
   - Grep
@@ -30,6 +31,7 @@ Use when you need: prototype track, pre-archive checks, context-detection detail
 - Run config discovery (prefer `.devbooks/config.yaml`) and read `agents_doc` before routing.
 - Output 2 minimum key questions + 3-6 routing results (paths + rationale).
 - If the user asks to "start producing files", switch to the target Skill's output mode.
+- Start is the default entrypoint; use Router to output phase recommendations and shortest-path routing.
 
 ## References
 

package/skills/devbooks-router/references/routing-rules-and-templates.md

@@ -35,6 +35,18 @@ Before routing, check whether structured code analysis is available (dependency/
 
 3) If the user asks to “start producing file content”, switch to the target Skill’s output mode.
 
+## Start entry rules (default entrypoint)
+
+Start is the default entrypoint. When Start is triggered, follow these rules:
+
+1) If `<change-id>` is unclear, ask for `<change-id>` and confirm `<truth-root>/<change-root>`.
+2) If the change package state can be inferred (e.g. `pending/in_progress/review/completed`), recommend the next entrypoint:
+   - `pending` → `proposal`
+   - `in_progress` → `design/spec/plan` (recommend based on missing artifacts)
+   - `review` → `review`
+   - `completed` → `archive`
+3) Keep the routing output to 3–6 items, each including Skill + path + rationale.
+
 ## Default routing rules
 
 ### A) Proposal phase
@@ -117,4 +129,3 @@ impact_profile:
 Infer phase from existing artifacts:
 - `proposal.md`, `design.md`, `tasks.md`, `verification.md`
 - `evidence/green-final/`
-

package/templates/claude-commands/devbooks/apply.md

@@ -0,0 +1,27 @@
+---
+skill: multi-skill-combo
+skills:
+  - devbooks-test-owner
+  - devbooks-coder
+  - devbooks-reviewer
+---
+
+# DevBooks: Apply (backward compatible)
+
+Runs the apply stage as a multi-skill combo: Test Owner → Coder → Reviewer.
+
+## Usage
+
+/devbooks:apply [args]
+
+## Args
+
+$ARGUMENTS
+
+## Notes
+
+This is a backward compatible command. Prefer direct commands when possible:
+- `/devbooks:test` - acceptance tests
+- `/devbooks:code` - implementation
+- `/devbooks:review` - review
+

package/templates/claude-commands/devbooks/archive.md

@@ -0,0 +1,16 @@
+---
+skill: devbooks-archiver
+---
+
+# DevBooks: Archive (backward compatible)
+
+Use devbooks-archiver to complete the archive loop for a change package.
+
+## Usage
+
+/devbooks:archive [args]
+
+## Args
+
+$ARGUMENTS
+

package/templates/claude-commands/devbooks/backport.md

@@ -0,0 +1,16 @@
+---
+skill: devbooks-design-doc
+---
+
+# DevBooks: Design Backport
+
+Use devbooks-design-doc to backport newly discovered constraints/gaps into `design.md`.
+
+## Usage
+
+/devbooks:backport [args]
+
+## Args
+
+$ARGUMENTS
+

package/templates/claude-commands/devbooks/bootstrap.md

@@ -0,0 +1,16 @@
+---
+skill: devbooks-brownfield-bootstrap
+---
+
+# DevBooks: Bootstrap (Brownfield)
+
+Use devbooks-brownfield-bootstrap to generate baseline specs and project profile for an existing codebase.
+
+## Usage
+
+/devbooks:bootstrap [args]
+
+## Args
+
+$ARGUMENTS
+

package/templates/claude-commands/devbooks/c4.md

@@ -0,0 +1,16 @@
+---
+skill: devbooks-design-doc
+---
+
+# DevBooks: C4 / Architecture Map
+
+Use devbooks-design-doc to produce or update architecture impact (including C4 notes) for the change.
+
+## Usage
+
+/devbooks:c4 [args]
+
+## Args
+
+$ARGUMENTS
+

package/templates/claude-commands/devbooks/challenger.md

@@ -0,0 +1,16 @@
+---
+skill: devbooks-proposal-challenger
+---
+
+# DevBooks: Challenger
+
+Use devbooks-proposal-challenger to critique the proposal and surface risks, gaps, and missing acceptance criteria.
+
+## Usage
+
+/devbooks:challenger [args]
+
+## Args
+
+$ARGUMENTS
+

package/templates/claude-commands/devbooks/code.md

@@ -0,0 +1,21 @@
+---
+skill: devbooks-coder
+---
+
+# DevBooks: Code
+
+Use devbooks-coder to implement according to `tasks.md` and make the gates green.
+
+## Usage
+
+/devbooks:code [args]
+
+## Args
+
+$ARGUMENTS
+
+## Notes
+
+- Follow `tasks.md` only.
+- Must not modify `tests/**`.
+

package/templates/claude-commands/devbooks/debate.md

@@ -0,0 +1,27 @@
+---
+skill: multi-skill-combo
+skills:
+  - devbooks-proposal-author
+  - devbooks-proposal-challenger
+  - devbooks-proposal-judge
+---
+
+# DevBooks: Proposal Debate (backward compatible)
+
+Runs the full proposal debate loop: Author → Challenger → Judge.
+
+## Usage
+
+/devbooks:debate [args]
+
+## Args
+
+$ARGUMENTS
+
+## Notes
+
+This is a backward compatible command that triggers a multi-skill combo. You can also use the direct commands:
+- `/devbooks:proposal`
+- `/devbooks:challenger`
+- `/devbooks:judge`
+

package/templates/claude-commands/devbooks/delivery.md

@@ -0,0 +1,22 @@
+---
+skill: devbooks-delivery-workflow
+---
+
+# DevBooks: Delivery Workflow
+
+Use devbooks-delivery-workflow to orchestrate the full loop end-to-end.
+
+## Usage
+
+/devbooks:delivery [args]
+
+## Args
+
+$ARGUMENTS
+
+## Notes
+
+Orchestrates Proposal -> Design -> Spec -> Plan -> Test -> Implement -> Review -> Archive:
+- Coordinates multi-role collaboration (when supported by the tool)
+- Keeps the loop complete and verifiable
+

package/templates/claude-commands/devbooks/design.md

@@ -0,0 +1,23 @@
+---
+skill: devbooks-design-doc
+---
+
+# DevBooks: Design
+
+Use devbooks-design-doc to produce the change package design doc (`design.md`).
+
+## Usage
+
+/devbooks:design [args]
+
+## Args
+
+$ARGUMENTS
+
+## Notes
+
+Write What/Constraints + AC-xxx only (no implementation steps):
+- Define acceptance criteria
+- State constraints
+- Provide architecture impact (if applicable)
+

package/templates/claude-commands/devbooks/entropy.md

@@ -0,0 +1,16 @@
+---
+skill: devbooks-entropy-monitor
+---
+
+# DevBooks: Entropy Monitor
+
+Use devbooks-entropy-monitor to collect entropy metrics and generate a health report.
+
+## Usage
+
+/devbooks:entropy [args]
+
+## Args
+
+$ARGUMENTS
+

package/templates/claude-commands/devbooks/federation.md

@@ -0,0 +1,16 @@
+---
+skill: devbooks-impact-analysis
+---
+
+# DevBooks: Cross-Repo Analysis
+
+Use devbooks-impact-analysis to assess cross-repo impact and integration risks.
+
+## Usage
+
+/devbooks:federation [args]
+
+## Args
+
+$ARGUMENTS
+

package/templates/claude-commands/devbooks/gardener.md

@@ -0,0 +1,16 @@
+---
+skill: devbooks-spec-gardener
+---
+
+# DevBooks: Spec Gardener
+
+Use devbooks-spec-gardener to maintain the truth specs and keep them consistent.
+
+## Usage
+
+/devbooks:gardener [args]
+
+## Args
+
+$ARGUMENTS
+

package/templates/claude-commands/devbooks/impact.md

@@ -0,0 +1,16 @@
+---
+skill: devbooks-impact-analysis
+---
+
+# DevBooks: Impact Analysis
+
+Use devbooks-impact-analysis before cross-module or contract-affecting changes.
+
+## Usage
+
+/devbooks:impact [args]
+
+## Args
+
+$ARGUMENTS
+

package/templates/claude-commands/devbooks/index.md

@@ -0,0 +1,22 @@
+---
+skill: devbooks-router
+---
+
+# DevBooks: Index
+
+A quick index of common DevBooks commands.
+
+## Usage
+
+/devbooks:index [args]
+
+## Args
+
+$ARGUMENTS
+
+## Notes
+
+- Default entrypoint: `/devbooks:start`
+- Routing and phase detection: `/devbooks:router`
+- Full loop orchestrator: `/devbooks:delivery`
+

package/templates/claude-commands/devbooks/judge.md

@@ -0,0 +1,16 @@
+---
+skill: devbooks-proposal-judge
+---
+
+# DevBooks: Judge
+
+Use devbooks-proposal-judge to decide Approved/Revise/Rejected and write the decision log into `proposal.md`.
+
+## Usage
+
+/devbooks:judge [args]
+
+## Args
+
+$ARGUMENTS
+

package/templates/claude-commands/devbooks/plan.md

@@ -0,0 +1,16 @@
+---
+skill: devbooks-implementation-plan
+---
+
+# DevBooks: Plan
+
+Use devbooks-implementation-plan to derive a trackable `tasks.md` from `design.md`.
+
+## Usage
+
+/devbooks:plan [args]
+
+## Args
+
+$ARGUMENTS
+

package/templates/claude-commands/devbooks/proposal.md

@@ -0,0 +1,23 @@
+---
+skill: devbooks-proposal-author
+---
+
+# DevBooks: Proposal
+
+Use devbooks-proposal-author to write a change proposal (`proposal.md`).
+
+## Usage
+
+/devbooks:proposal [args]
+
+## Args
+
+$ARGUMENTS
+
+## Notes
+
+This is the proposal entrypoint and produces `proposal.md` (Why/What/Impact + Debate Packet):
+- Generates a compliant change-id
+- Clarifies motivation and goals
+- Presents options for design decisions when needed
+

package/templates/claude-commands/devbooks/quick.md

@@ -0,0 +1,20 @@
+---
+skill: devbooks-router
+---
+
+# DevBooks: Quick (backward compatible)
+
+Quick entry for small changes. Uses Router to pick the shortest path.
+
+## Usage
+
+/devbooks:quick [args]
+
+## Args
+
+$ARGUMENTS
+
+## Notes
+
+If the change becomes non-trivial (multi-file or cross-module), use `/devbooks:router` to get a full plan.
+

package/templates/claude-commands/devbooks/review.md

@@ -0,0 +1,16 @@
+---
+skill: devbooks-reviewer
+---
+
+# DevBooks: Review
+
+Use devbooks-reviewer for maintainability/consistency review.
+
+## Usage
+
+/devbooks:review [args]
+
+## Args
+
+$ARGUMENTS
+

package/templates/claude-commands/devbooks/router.md

@@ -0,0 +1,24 @@
+---
+skill: devbooks-router
+---
+
+# DevBooks: Router
+
+Use Router to detect the current status and output the shortest closed-loop routing plan.
+
+## Usage
+
+/devbooks:router [args]
+
+## Args
+
+$ARGUMENTS
+
+## Notes
+
+Router is the main entry guide for non-trivial changes (multi-file or cross-module):
+- Detects the current phase based on existing artifacts
+- Recommends the next Skill and the exact artifact paths
+
+If you already know the specific Skill to run, use the direct command. If unsure, prefer `/devbooks:start`.
+

package/templates/claude-commands/devbooks/spec.md

@@ -0,0 +1,16 @@
+---
+skill: devbooks-spec-contract
+---
+
+# DevBooks: Spec / Contract
+
+Use devbooks-spec-contract to define behavior specs and external contracts.
+
+## Usage
+
+/devbooks:spec [args]
+
+## Args
+
+$ARGUMENTS
+

package/templates/claude-commands/devbooks/start.md

@@ -0,0 +1,22 @@
+---
+skill: devbooks-router
+---
+
+# DevBooks: Start
+
+Start is the default entrypoint. It detects the current phase and routes to the shortest closed-loop next step.
+
+## Usage
+
+/devbooks:start [args]
+
+## Args
+
+$ARGUMENTS
+
+## Notes
+
+- If you're unsure what to do next, start here.
+- Router reads config mappings and existing artifacts to recommend the next Skill.
+- If you already know the change-id, provide it to reduce questions.
+

package/templates/claude-commands/devbooks/test-review.md

@@ -0,0 +1,16 @@
+---
+skill: devbooks-test-reviewer
+---
+
+# DevBooks: Test Review
+
+Use devbooks-test-reviewer to review tests quality (coverage, boundaries, maintainability).
+
+## Usage
+
+/devbooks:test-review [args]
+
+## Args
+
+$ARGUMENTS
+

package/templates/claude-commands/devbooks/test.md

@@ -0,0 +1,23 @@
+---
+skill: devbooks-test-owner
+---
+
+# DevBooks: Test (Acceptance)
+
+Use devbooks-test-owner to turn design/spec into executable acceptance tests and `verification.md`.
+
+## Usage
+
+/devbooks:test [args]
+
+## Args
+
+$ARGUMENTS
+
+## Notes
+
+As Test Owner:
+- Work in a separate conversation from Coder
+- Produce a Red baseline first
+- Maintain the traceability matrix
+