dev-playbooks-cn 1.0.7 → 1.0.10

package/bin/devbooks.js

@@ -202,26 +202,6 @@ function copyDirSync(src, dest) {
   return count;
 }
 
-function copyCodexPromptsSync(srcDir, destDir) {
-  if (!fs.existsSync(srcDir)) return 0;
-  fs.mkdirSync(destDir, { recursive: true });
-
-  let count = 0;
-  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
-  for (const entry of entries) {
-    if (!entry.isFile()) continue;
-    if (!entry.name.endsWith('.md')) continue;
-
-    const srcPath = path.join(srcDir, entry.name);
-    const destName = entry.name.startsWith('devbooks-') ? entry.name : `devbooks-${entry.name}`;
-    const destPath = path.join(destDir, destName);
-    fs.copyFileSync(srcPath, destPath);
-    count++;
-  }
-
-  return count;
-}
-
 function getSkillsSupportLabel(level) {
   switch (level) {
     case SKILLS_SUPPORT.FULL:
@@ -327,40 +307,6 @@ async function promptToolSelection(projectDir) {
   return selectedTools;
 }
 
-// ============================================================================
-// 安装 Slash 命令
-// ============================================================================
-
-function installSlashCommands(toolIds, projectDir) {
-  const slashSrcDir = path.join(__dirname, '..', 'templates', 'claude-commands', 'devbooks');
-
-  if (!fs.existsSync(slashSrcDir)) {
-    return { results: [], total: 0 };
-  }
-
-  const results = [];
-
-  for (const toolId of toolIds) {
-    const tool = AI_TOOLS.find(t => t.id === toolId);
-    if (!tool) continue;
-
-    let destDir;
-    if (tool.slashDir) {
-      destDir = path.join(projectDir, tool.slashDir);
-    } else if (tool.globalSlashDir) {
-      destDir = expandPath(tool.globalSlashDir);
-    } else {
-      continue;
-    }
-
-    const count = toolId === 'codex'
-      ? copyCodexPromptsSync(slashSrcDir, destDir)
-      : copyDirSync(slashSrcDir, destDir);
-    results.push({ tool: tool.name, count, path: destDir });
-  }
-
-  return { results, total: results.length };
-}
 
 // ============================================================================
 // 安装 Skills（Claude Code, Codex CLI, Qoder）
@@ -624,6 +570,7 @@ function createProjectStructure(projectDir) {
     'dev-playbooks/specs/architecture',
     'dev-playbooks/changes',
     'dev-playbooks/scripts',
+    'dev-playbooks/docs',
     '.devbooks'
   ];
 
@@ -641,6 +588,18 @@ function createProjectStructure(projectDir) {
     { src: '.devbooks/config.yaml', dest: '.devbooks/config.yaml' }
   ];
 
+  // 动态添加 docs 目录下的所有文件
+  const docsDir = path.join(templateDir, 'dev-playbooks', 'docs');
+  if (fs.existsSync(docsDir)) {
+    const docFiles = fs.readdirSync(docsDir).filter(f => f.endsWith('.md'));
+    for (const docFile of docFiles) {
+      templateFiles.push({
+        src: `dev-playbooks/docs/${docFile}`,
+        dest: `dev-playbooks/docs/${docFile}`
+      });
+    }
+  }
+
   let copiedCount = 0;
   for (const { src, dest } of templateFiles) {
     const srcPath = path.join(templateDir, src);
@@ -750,15 +709,6 @@ async function initCommand(projectDir, options) {
     return;
   }
 
-  // 安装 Slash 命令
-  const slashSpinner = ora('安装 Slash 命令...').start();
-  const slashResults = installSlashCommands(selectedTools, projectDir);
-  slashSpinner.succeed(`安装了 ${slashResults.results.length} 个工具的 Slash 命令`);
-
-  for (const result of slashResults.results) {
-    console.log(chalk.gray(`  └ ${result.tool}: ${result.count} 个命令`));
-  }
-
   // 安装 Skills（仅完整支持的工具）
   const fullSupportTools = selectedTools.filter(id => {
     const tool = AI_TOOLS.find(t => t.id === id);
@@ -824,10 +774,8 @@ async function initCommand(projectDir, options) {
   // 下一步提示
   console.log(chalk.bold('下一步：'));
   console.log(`  1. 编辑 ${chalk.cyan('dev-playbooks/project.md')} 添加项目信息`);
-  console.log(`  2. 使用 ${chalk.cyan('/devbooks:proposal')} 创建第一个变更提案`);
+  console.log(`  2. 使用 ${chalk.cyan('devbooks-proposal-author')} Skill 创建第一个变更提案`);
   console.log();
-  console.log(chalk.yellow('重要提示：'));
-  console.log('  Slash 命令在 IDE 启动时加载，请重启你的 AI 工具以使命令生效。');
 }
 
 // ============================================================================
@@ -861,12 +809,6 @@ async function updateCommand(projectDir) {
   });
   console.log(chalk.blue('ℹ') + ` 检测到已配置的工具: ${toolNames.join(', ')}`);
 
-  // 更新 Slash 命令
-  const slashResults = installSlashCommands(configuredTools, projectDir);
-  for (const result of slashResults.results) {
-    console.log(chalk.green('✓') + ` ${result.tool}: 更新了 ${result.count} 个 slash 命令`);
-  }
-
   // 更新 Skills
   const skillsResults = installSkills(configuredTools, true);
   for (const result of skillsResults) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-playbooks-cn",
-  "version": "1.0.7",
+  "version": "1.0.10",
   "description": "AI-driven spec-based development workflow",
   "keywords": [
     "devbooks",

package/templates/dev-playbooks/README.md

@@ -7,6 +7,8 @@
 [![npm](https://img.shields.io/npm/v/dev-playbooks-cn)](https://www.npmjs.com/package/dev-playbooks-cn)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../LICENSE)
 
+![DevBooks 工作流](docs/workflow-diagram.svg)
+
 ---
 
 ## 为什么选择 DevBooks？
@@ -46,29 +48,6 @@ AI 编码助手很强大，但往往**不可预测**：
 
 ## 工作原理
 
-```
-                           DevBooks 工作流
-
-    PROPOSAL 阶段                  APPLY 阶段                     ARCHIVE 阶段
-    (禁止编码)                     (角色隔离强制)                  (质量闸门)
-
-    ┌─────────────────┐            ┌─────────────────┐            ┌─────────────────┐
-    │  /devbooks:     │            │   对话 A        │            │  /devbooks:     │
-    │   proposal      │            │  ┌───────────┐  │            │   gardener      │
-    │   impact        │────────────│  │Test Owner │  │────────────│   delivery      │
-    │   design        │            │  │(先跑 Red) │  │            │                 │
-    │   spec          │            │  └───────────┘  │            │  质量闸门:       │
-    │   plan          │            │                 │            │  ✓ Green 证据   │
-    └─────────────────┘            │   对话 B        │            │  ✓ 任务完成     │
-           │                       │  ┌───────────┐  │            │  ✓ 角色边界     │
-           ▼                       │  │  Coder    │  │            │  ✓ 无失败       │
-    ┌─────────────────┐            │  │(禁改测试!)│  │            └─────────────────┘
-    │ 三角对辩        │            │  └───────────┘  │
-    │ Author/Challenger│            └─────────────────┘
-    │ /Judge          │
-    └─────────────────┘
-```
-
 **核心约束**：Test Owner 与 Coder **必须在独立对话**中工作。这是硬性约束，不是建议。Coder 不能修改 `tests/**`，完成由测试/构建验证，而非 AI 自评。
 
 ---
@@ -77,19 +56,18 @@ AI 编码助手很强大，但往往**不可预测**：
 
 ### 支持的 AI 工具
 
-| 工具 | Slash 命令 | 自然语言 | 配置文件 |
-|------|-----------|----------|----------|
-| **Claude Code** | `/devbooks:*` | 支持 | `CLAUDE.md` |
-| **Codex CLI** | `/devbooks:*` | 支持 | `AGENTS.md` |
-| **Cursor** | - | 支持 | `.cursorrules` |
-| **Windsurf** | - | 支持 | `.windsurfrules` |
-| **Continue.dev** | - | 支持 | `.continuerules` |
-| **GitHub Copilot** | - | 支持 | `.github/copilot-instructions.md` |
-| **Gemini Code Assist** | - | 支持 | - |
-| **Aider** | - | 支持 | `.aider.conf.yml` |
-| **Cline** | - | 支持 | `.clinerules` |
+| 工具 | 支持级别 | 配置文件 |
+|------|----------|----------|
+| **Claude Code** | 完整 Skills | `CLAUDE.md` |
+| **Codex CLI** | 完整 Skills | `AGENTS.md` |
+| **Qoder** | 完整 Skills | `AGENTS.md` |
+| **Cursor** | Rules 系统 | `.cursor/rules/` |
+| **Windsurf** | Rules 系统 | `.windsurf/rules/` |
+| **Gemini CLI** | Rules 系统 | `GEMINI.md` |
+| **Continue** | Rules 系统 | `.continue/rules/` |
+| **GitHub Copilot** | 自定义指令 | `.github/copilot-instructions.md` |
 
-> **提示**：对于不支持 Slash 命令的工具，使用自然语言指令，例如："运行 DevBooks proposal skill..."
+> **提示**：使用自然语言调用 Skills，例如："运行 devbooks-proposal-author skill..."
 
 ### 安装与初始化
 
@@ -119,7 +97,7 @@ npx dev-playbooks-cn@latest init
 
 初始化后：
 - Claude Code：`~/.claude/skills/devbooks-*`
-- Codex CLI：`$CODEX_HOME/skills/devbooks-*`（默认 `~/.codex/skills/devbooks-*`）
+- Codex CLI：`~/.codex/skills/devbooks-*`
 
 ### 快速集成
 
@@ -130,7 +108,7 @@ DevBooks 使用两个目录根：
 | `<truth-root>` | 当前规格（只读真理） | `dev-playbooks/specs/` |
 | `<change-root>` | 变更包（工作区） | `dev-playbooks/changes/` |
 
-详见 `docs/DevBooks集成模板（协议无关）.md` 或使用 `docs/DevBooks安装提示词.md` 让 AI 自动配置。
+详见 `docs/DevBooks配置指南.md`。
 
 ---
 
@@ -138,20 +116,20 @@ DevBooks 使用两个目录根：
 
 ### 使用 Router（推荐）
 
+告诉 AI 你的需求，让 Router 分析并输出执行计划：
+
 ```
-/devbooks:router <你的需求>
+请运行 devbooks-router skill，分析需求：<你的需求>
 ```
 
-Router 分析需求并输出执行计划，告诉你下一步用哪个命令。
-
-### 直达命令
+### Skills 直达
 
 熟悉流程后，直接调用 Skill：
 
 **1. Proposal 阶段（禁止编码）**
 
 ```
-/devbooks:proposal 添加 OAuth2 用户认证
+请运行 devbooks-proposal-author skill，创建提案：添加 OAuth2 用户认证
 ```
 
 产物：`proposal.md`（必需）、`design.md`、`tasks.md`
@@ -162,10 +140,10 @@ Router 分析需求并输出执行计划，告诉你下一步用哪个命令。
 
 ```
 # 对话 A - Test Owner
-/devbooks:test add-oauth2
+请运行 devbooks-test-owner skill，变更 ID：add-oauth2
 
 # 对话 B - Coder
-/devbooks:code add-oauth2
+请运行 devbooks-coder skill，变更 ID：add-oauth2
 ```
 
 - Test Owner：写 `verification.md` + 测试，先跑 **Red**
@@ -174,64 +152,64 @@ Router 分析需求并输出执行计划，告诉你下一步用哪个命令。
 **3. Review 阶段**
 
 ```
-/devbooks:review add-oauth2
+请运行 devbooks-code-review skill，变更 ID：add-oauth2
 ```
 
 **4. Archive 阶段**
 
 ```
-/devbooks:gardener add-oauth2
+请运行 devbooks-spec-gardener skill，变更 ID：add-oauth2
 ```
 
 ---
 
-## 命令参考
+## Skills 参考
 
 ### Proposal 阶段
 
-| 命令 | Skill | 说明 |
-|------|-------|------|
-| `/devbooks:router` | devbooks-router | 智能路由到合适的 Skill |
-| `/devbooks:proposal` | devbooks-proposal-author | 创建变更提案 |
-| `/devbooks:impact` | devbooks-impact-analysis | 跨模块影响分析 |
-| `/devbooks:challenger` | devbooks-proposal-challenger | 质疑和挑战提案 |
-| `/devbooks:judge` | devbooks-proposal-judge | 裁决提案 |
-| `/devbooks:debate` | devbooks-proposal-debate-workflow | 三角对辩（Author/Challenger/Judge） |
-| `/devbooks:design` | devbooks-design-doc | 创建设计文档 |
-| `/devbooks:spec` | devbooks-spec-contract | 定义规格与契约 |
-| `/devbooks:c4` | devbooks-c4-map | 生成 C4 架构地图 |
-| `/devbooks:plan` | devbooks-implementation-plan | 创建实现计划 |
+| Skill | 说明 |
+|-------|------|
+| `devbooks-router` | 智能路由到合适的 Skill |
+| `devbooks-proposal-author` | 创建变更提案 |
+| `devbooks-impact-analysis` | 跨模块影响分析 |
+| `devbooks-proposal-challenger` | 质疑和挑战提案 |
+| `devbooks-proposal-judge` | 裁决提案 |
+| `devbooks-proposal-debate-workflow` | 三角对辩（Author/Challenger/Judge） |
+| `devbooks-design-doc` | 创建设计文档 |
+| `devbooks-spec-contract` | 定义规格与契约 |
+| `devbooks-c4-map` | 生成 C4 架构地图 |
+| `devbooks-implementation-plan` | 创建实现计划 |
 
 ### Apply 阶段
 
-| 命令 | Skill | 说明 |
-|------|-------|------|
-| `/devbooks:test` | devbooks-test-owner | Test Owner 角色（必须独立对话） |
-| `/devbooks:code` | devbooks-coder | Coder 角色（必须独立对话） |
-| `/devbooks:backport` | devbooks-design-backport | 回写发现到设计文档 |
+| Skill | 说明 |
+|-------|------|
+| `devbooks-test-owner` | Test Owner 角色（必须独立对话） |
+| `devbooks-coder` | Coder 角色（必须独立对话） |
+| `devbooks-design-backport` | 回写发现到设计文档 |
 
 ### Review 阶段
 
-| 命令 | Skill | 说明 |
-|------|-------|------|
-| `/devbooks:review` | devbooks-code-review | 代码评审（可读性/一致性） |
-| `/devbooks:test-review` | devbooks-test-reviewer | 测试质量与覆盖率评审 |
+| Skill | 说明 |
+|-------|------|
+| `devbooks-code-review` | 代码评审（可读性/一致性） |
+| `devbooks-test-reviewer` | 测试质量与覆盖率评审 |
 
 ### Archive 阶段
 
-| 命令 | Skill | 说明 |
-|------|-------|------|
-| `/devbooks:gardener` | devbooks-spec-gardener | 规格维护与去重 |
-| `/devbooks:delivery` | devbooks-delivery-workflow | 完整交付闭环 |
+| Skill | 说明 |
+|-------|------|
+| `devbooks-spec-gardener` | 规格维护与去重 |
+| `devbooks-delivery-workflow` | 完整交付闭环 |
 
 ### 独立技能
 
-| 命令 | Skill | 说明 |
-|------|-------|------|
-| `/devbooks:entropy` | devbooks-entropy-monitor | 系统熵度量 |
-| `/devbooks:federation` | devbooks-federation | 跨仓库联邦分析 |
-| `/devbooks:bootstrap` | devbooks-brownfield-bootstrap | 存量项目初始化 |
-| `/devbooks:index` | devbooks-index-bootstrap | 生成 SCIP 索引 |
+| Skill | 说明 |
+|-------|------|
+| `devbooks-entropy-monitor` | 系统熵度量 |
+| `devbooks-federation` | 跨仓库联邦分析 |
+| `devbooks-brownfield-bootstrap` | 存量项目初始化 |
+| `devbooks-index-bootstrap` | 生成 SCIP 索引 |
 
 ---
 
@@ -353,7 +331,7 @@ DevBooks 跟踪四维系统熵：
 | 测试熵 | 测试覆盖率和质量衰减 |
 | 依赖熵 | 外部依赖健康度 |
 
-用 `/devbooks:entropy` 生成报告，识别重构机会。
+用 `devbooks-entropy-monitor` 生成报告，识别重构机会。
 
 脚本（位于 `~/.claude/skills/devbooks-entropy-monitor/scripts/`）：`entropy-measure.sh`、`entropy-report.sh`
 
@@ -362,13 +340,8 @@ DevBooks 跟踪四维系统熵：
 <details>
 <summary><strong>存量项目初始化</strong></summary>
 
-当 `<truth-root>` 为空时：
+当 `<truth-root>` 为空时，使用 `devbooks-brownfield-bootstrap` 生成：
 
-```
-/devbooks:bootstrap
-```
-
-生成：
 - 项目画像和术语表
 - 从现有代码生成基线规格
 - 最小验证锚点
@@ -380,13 +353,7 @@ DevBooks 跟踪四维系统熵：
 <details>
 <summary><strong>跨仓库联邦</strong></summary>
 
-多仓库分析：
-
-```
-/devbooks:federation
-```
-
-分析跨仓库边界的契约和依赖，支持协调变更。
+多仓库分析用 `devbooks-federation`，分析跨仓库边界的契约和依赖，支持协调变更。
 
 </details>
 
@@ -405,27 +372,23 @@ DevBooks Skills 支持 MCP（Model Context Protocol）优雅降级：在没有 M
 
 | MCP 状态 | 行为 |
 |----------|------|
-| CKB 可用 | 增强模式：符号级影响分析/引用查找/调用图/热点（`mcp__ckb__analyzeImpact`、`mcp__ckb__findReferences`、`mcp__ckb__getCallGraph`、`mcp__ckb__getHotspots`） |
+| CKB 可用 | 增强模式：符号级影响分析/引用查找/调用图/热点 |
 | CKB 不可用 | 基础模式：Grep + Glob 文本搜索（功能完整，精度降低） |
 
 ### 自动检测
 
-- 需要 MCP 的 Skills 会先调用 `mcp__ckb__getStatus` 探测可用性（2s 超时）
+- 需要 MCP 的 Skills 会先探测可用性（2s 超时）
 - 超时/失败 → 静默降级到基础模式，不阻塞执行
 - 无需手动选择"基础/增强"模式
 
-如需启用增强能力：按 `docs/推荐MCP.md` 配置 CKB，并运行 `/devbooks:index` 生成 `index.scip`。
+如需启用增强能力：按 `docs/推荐MCP.md` 配置 CKB，并运行 `devbooks-index-bootstrap` 生成 `index.scip`。
 
 </details>
 
 <details>
 <summary><strong>提案对辩工作流</strong></summary>
 
-严格提案审查用三角对辩：
-
-```
-/devbooks:debate
-```
+严格提案审查用三角对辩 `devbooks-proposal-debate-workflow`：
 
 三个角色：
 1. **Author**：创建并捍卫提案
@@ -462,7 +425,6 @@ dev-playbooks-cn migrate --from openspec --keep-old
 - `openspec/changes/` → `dev-playbooks/changes/`
 - `openspec/project.md` → `dev-playbooks/project.md`
 - 所有路径引用自动更新
-- AI 工具命令目录自动清理（`.claude/commands/openspec/` 等）
 
 ### 从 GitHub spec-kit 迁移
 
@@ -507,7 +469,7 @@ dev-playbooks-cn migrate --from speckit --keep-old
 1. 运行 `dev-playbooks-cn init` 设置 DevBooks Skills
 2. 检查 `dev-playbooks/` 中的迁移文件
 3. 更新 `verification.md` 文件的 AC 映射
-4. 如需基线规格，运行 `/devbooks:bootstrap`
+4. 如需基线规格，运行 `devbooks-brownfield-bootstrap`
 
 ---
 
@@ -524,20 +486,18 @@ dev-playbooks/
 ├── changes/               # 变更包（工作区）
 ├── scripts/               # 辅助脚本
 └── docs/                  # 文档
-    ├── Slash 命令使用指南.md
-    ├── 推荐MCP.md
-    ├── DevBooks集成模板（协议无关）.md
-    └── DevBooks安装提示词.md
+    ├── workflow-diagram.svg   # 工作流程图
+    ├── 推荐MCP.md             # MCP 配置建议
+    └── DevBooks配置指南.md    # 配置指南
 ```
 
 ---
 
 ## 文档
 
-- [Slash 命令使用指南](docs/Slash%20命令使用指南.md)
+- [工作流程图](docs/workflow-diagram.svg)
 - [MCP 配置建议](docs/推荐MCP.md)
-- [集成模板（协议无关）](docs/DevBooks集成模板（协议无关）.md)
-- [安装提示词](docs/DevBooks安装提示词.md)
+- [配置指南](docs/DevBooks配置指南.md)
 
 ---
 

package/templates/dev-playbooks/docs/DevBooks/351/205/215/347/275/256/346/214/207/345/215/227.md

@@ -0,0 +1,204 @@
+# DevBooks 配置指南
+
+> 本指南帮助你在项目中集成 DevBooks 工作流。
+
+---
+
+## 快速开始（让 AI 自动配置）
+
+将以下提示词发送给 AI，它会自动完成配置：
+
+```text
+你是"DevBooks 上下文协议适配器安装员（DevBooks Context Protocol Adapter Installer）"。你的目标是在目标项目中，把 DevBooks 的协议无关约定（<truth-root>/<change-root> + 角色隔离 + DoD + Skills 索引）集成到该项目的上下文协议里。
+
+前置条件（先检查，缺失则停止并说明原因）：
+- 系统依赖已安装（必需：jq、ripgrep；推荐：scc、radon）
+  检查命令：command -v jq rg scc radon
+  若缺失，运行：<devbooks-root>/scripts/install-dependencies.sh
+- 你能定位该项目的"标牌文件（signpost file）"（由上下文协议决定，常见：CLAUDE.md / AGENTS.md / PROJECT.md / <protocol>/project.md）。
+
+硬约束（必须遵守）：
+1) 本次安装只允许改"上下文/文档标牌"，不得修改业务代码、tests、也不得引入新依赖。
+2) 若目标项目已有"上下文协议托管区块（managed block）"，自定义内容必须放在托管区块之外，避免被后续自动更新覆盖。
+3) 安装必须明确写出两个目录根：
+   - <truth-root>：当前真理目录根
+   - <change-root>：变更包目录根
+
+任务（按顺序执行）：
+0) 检查系统依赖：
+   - 运行：command -v jq rg scc radon
+   - 若缺失必需依赖（jq、rg），提示用户先运行：./scripts/install-dependencies.sh
+   - 若缺失推荐依赖（scc、radon），说明这是可选项，用于启用"复杂度加权热点"等能力
+1) 识别上下文协议类型（至少两条分支）：
+   - 若检测到 DevBooks（存在 dev-playbooks/project.md）：使用 DevBooks 默认值（<truth-root>=dev-playbooks/specs，<change-root>=dev-playbooks/changes）
+   - 否则：使用手动配置部分进行集成
+2) 为该项目确定目录根：
+   - 若项目已有 specs/changes 等目录约定：直接沿用作为 <truth-root>/<change-root>
+   - 若项目没有定义：推荐在仓库根目录使用 `specs/` 与 `changes/`
+3) 将模板内容合入标牌文件（以追加方式合并）：
+   - 写入：<truth-root>/<change-root>、变更包结构约定、角色隔离、DoD、devbooks-* Skills 索引
+4) 验证（必须输出检查结果）：
+   - 产物落点是否一致（proposal/design/tasks/verification/specs/evidence）
+   - 是否包含 Test Owner/Coder 隔离与"Coder 禁止修改 tests"
+   - 是否包含 DoD（MECE）
+   - 是否包含 devbooks-* Skills 索引
+
+完成后输出：
+- 系统依赖检查结果（哪些已安装、哪些缺失）
+- 你修改了哪些文件（列表）
+- 该项目最终的 <truth-root>/<change-root> 值
+- 下一步最短路径示例（用自然语言点 2-3 个关键 skills）
+```
+
+---
+
+## 手动配置
+
+如果你想手动配置，将以下内容添加到项目的标牌文件（`CLAUDE.md`、`AGENTS.md` 或 `PROJECT.md`）中：
+
+### 目录根配置
+
+```yaml
+# DevBooks 目录约定
+truth_root: dev-playbooks/specs/    # 当前真理目录根
+change_root: dev-playbooks/changes/ # 变更包目录根
+```
+
+### 单次变更包结构
+
+每次变更的产物按以下结构组织：
+
+| 产物 | 路径 | 说明 |
+|------|------|------|
+| 提案 | `<change-root>/<change-id>/proposal.md` | Why/What/Impact |
+| 设计 | `<change-root>/<change-id>/design.md` | What/Constraints + AC-xxx |
+| 计划 | `<change-root>/<change-id>/tasks.md` | 可跟踪的编码任务 |
+| 验证 | `<change-root>/<change-id>/verification.md` | 追溯矩阵 + MANUAL-* 清单 |
+| 规格增量 | `<change-root>/<change-id>/specs/**` | 本次变更的规格 delta |
+| 证据 | `<change-root>/<change-id>/evidence/**` | Red/Green 证据（按需） |
+
+### 当前真理目录结构
+
+```
+<truth-root>/
+├── _meta/
+│   ├── project-profile.md    # 项目画像/约束/闸门
+│   └── glossary.md           # 统一语言术语表
+├── architecture/
+│   └── c4.md                 # C4 架构地图
+└── engineering/
+    └── pitfalls.md           # 高 ROI 坑库（可选）
+```
+
+### 角色隔离（强制）
+
+```markdown
+## DevBooks 角色隔离规则
+
+- Test Owner 与 Coder 必须在**独立对话/独立实例**中工作
+- 允许并行，但不允许共享上下文造成"自证式测试"
+- Coder **禁止修改** `tests/**`
+- 如需调整测试，必须交回 Test Owner 决策与修改
+```
+
+### DoD（完成定义，MECE）
+
+每次变更必须声明覆盖哪些闸门，未覆盖项必须写明原因：
+
+| 闸门 | 类型 | 示例 |
+|------|------|------|
+| 行为 | unit/integration/e2e | pytest, jest |
+| 契约 | OpenAPI/Proto/Schema | contract tests |
+| 结构 | 分层/依赖方向/无环 | fitness tests |
+| 静态/安全 | lint/typecheck/build | SAST/secret scan |
+| 证据 | 截图/录像/报告 | UI、性能（按需） |
+
+---
+
+## Skills 索引
+
+### 按角色
+
+| 角色 | Skill | 产物落点 |
+|------|-------|----------|
+| Router | `devbooks-router` | 路由与下一步建议 |
+| Proposal Author | `devbooks-proposal-author` | `proposal.md` |
+| Proposal Challenger | `devbooks-proposal-challenger` | 质疑报告 |
+| Proposal Judge | `devbooks-proposal-judge` | 裁决回写 |
+| Impact Analyst | `devbooks-impact-analysis` | Impact 章节 |
+| Design Owner | `devbooks-design-doc` | `design.md` |
+| Spec & Contract | `devbooks-spec-contract` | `specs/**` |
+| Planner | `devbooks-implementation-plan` | `tasks.md` |
+| Test Owner | `devbooks-test-owner` | `verification.md` + `tests/` |
+| Coder | `devbooks-coder` | 按 tasks 实现（禁止改 tests） |
+| Reviewer | `devbooks-code-review` | 评审意见 |
+| Spec Gardener | `devbooks-spec-gardener` | 归档修剪 |
+| C4 Map | `devbooks-c4-map` | `architecture/c4.md` |
+| Design Backport | `devbooks-design-backport` | 回写设计缺口 |
+
+### 按工作流
+
+| 工作流 | Skill | 说明 |
+|--------|-------|------|
+| Proposal Debate | `devbooks-proposal-debate-workflow` | 三角辩论 |
+| Delivery | `devbooks-delivery-workflow` | 变更闭环 |
+| Brownfield Bootstrap | `devbooks-brownfield-bootstrap` | 存量项目初始化 |
+
+### 度量与索引
+
+| 功能 | Skill | 说明 |
+|------|-------|------|
+| Entropy Monitor | `devbooks-entropy-monitor` | 系统熵度量 |
+| Index Bootstrap | `devbooks-index-bootstrap` | 生成 SCIP 索引 |
+| Federation | `devbooks-federation` | 跨仓库分析 |
+
+---
+
+## 高级选项
+
+### 自定义目录映射
+
+在 `.devbooks/config.yaml` 中配置：
+
+```yaml
+# 目录映射
+mapping:
+  truth_root: specs/           # 自定义真理目录
+  change_root: changes/        # 自定义变更目录
+  agents_doc: AGENTS.md        # 规则文档路径
+
+# AI 工具配置
+ai_tools:
+  - claude
+  - cursor
+```
+
+### CI/CD 集成
+
+将 `templates/ci/` 中的模板复制到 `.github/workflows/`：
+
+- `devbooks-guardrail.yml`：PR 上检查复杂度/热点/分层违规
+- `devbooks-cod-update.yml`：push 后更新 COD 模型
+
+### 跨仓库联邦
+
+多仓库项目可配置 `.devbooks/federation.yaml`：
+
+```bash
+cp skills/devbooks-federation/templates/federation.yaml .devbooks/federation.yaml
+```
+
+详见 `skills/devbooks-federation/SKILL.md`
+
+---
+
+## 自动 Skill 路由
+
+AI 可以根据用户意图自动选择 Skills：
+
+| 用户意图 | 自动路由 |
+|----------|----------|
+| "修 bug"、"定位问题" | `devbooks-impact-analysis` → `devbooks-coder` |
+| "重构"、"优化代码" | `devbooks-code-review` → `devbooks-coder` |
+| "新功能"、"实现 XX" | `devbooks-router` → 输出闭环路线 |
+| "写测试"、"补测试" | `devbooks-test-owner` |