dev-playbooks 1.5.0 → 1.5.2

package/README.md

@@ -81,11 +81,21 @@ npx dev-playbooks@latest init
 
 ### Install targets
 
-After initialization:
-- Claude Code: `~/.claude/skills/devbooks-*`
-- Codex CLI: `~/.codex/skills/devbooks-*`
-- Qoder: `~/.qoder/` (manual setup required)
-- OpenCode: `~/.config/opencode/skill/devbooks-*`
+During initialization, you can choose the Skills installation scope:
+
+| Scope | Description | Path Example |
+|-------|-------------|--------------|
+| **Project** (default) | Available only in this project | `.claude/skills/devbooks-*` |
+| **Global** | Shared across all projects | `~/.claude/skills/devbooks-*` |
+
+```bash
+# Interactive selection
+dev-playbooks init
+
+# Non-interactive
+dev-playbooks init --tools claude --scope project  # Project-level
+dev-playbooks init --tools claude --scope global   # Global
+```
 
 ### Quick integration
 
@@ -194,6 +204,7 @@ Run devbooks-archiver skill for change add-oauth2
 |-------|-------------|
 | devbooks-entropy-monitor | System entropy metrics |
 | devbooks-brownfield-bootstrap | Brownfield project bootstrap |
+| devbooks-convergence-audit | Convergence audit (anti-deception design) |
 
 ---
 

package/bin/devbooks.js

@@ -24,7 +24,7 @@ import path from 'path';
 import os from 'os';
 import { fileURLToPath } from 'url';
 import { spawn } from 'child_process';
-import { checkbox, confirm } from '@inquirer/prompts';
+import { checkbox, confirm, select } from '@inquirer/prompts';
 import chalk from 'chalk';
 import ora from 'ora';
 
@@ -45,6 +45,15 @@ const SKILLS_SUPPORT = {
   BASIC: 'basic'     // 仅基础指令（无独立 Skills 概念）
 };
 
+// ============================================================================
+// Skills Install Scope
+// ============================================================================
+
+const INSTALL_SCOPE = {
+  GLOBAL: 'global',   // Global installation (~/.claude/skills etc.)
+  PROJECT: 'project'  // Project-level installation (.claude/skills etc.)
+};
+
 // ============================================================================
 // AI 工具配置
 // ============================================================================
@@ -540,12 +549,68 @@ async function promptToolSelection(projectDir) {
   return selectedTools;
 }
 
+async function promptInstallScope(projectDir, selectedTools) {
+  // Check if any tools support full Skills
+  const fullSupportTools = selectedTools.filter(id => {
+    const tool = AI_TOOLS.find(t => t.id === id);
+    return tool && tool.skillsSupport === SKILLS_SUPPORT.FULL;
+  });
+
+  if (fullSupportTools.length === 0) {
+    return INSTALL_SCOPE.PROJECT; // No full Skills support tools, default to project-level
+  }
+
+  // Load saved config
+  const config = loadConfig(projectDir);
+  const savedScope = config.installScope;
+
+  console.log();
+  console.log(chalk.bold('📦 Skills Installation Location'));
+  console.log(chalk.gray('─'.repeat(50)));
+  console.log();
+
+  const scope = await select({
+    message: 'Where should Skills be installed?',
+    choices: [
+      {
+        name: `Project-level ${chalk.gray('(.claude/skills etc., only for this project)')}`,
+        value: INSTALL_SCOPE.PROJECT,
+        description: 'Recommended: Skills stay with the project, no impact on other projects'
+      },
+      {
+        name: `Global ${chalk.gray('(~/.claude/skills etc., shared across all projects)')}`,
+        value: INSTALL_SCOPE.GLOBAL,
+        description: 'All projects share the same set of Skills'
+      }
+    ],
+    default: savedScope || INSTALL_SCOPE.PROJECT
+  });
+
+  return scope;
+}
+
 
 // ============================================================================
-// 安装 Skills（Claude Code, Codex CLI, Qoder）
+// Install Skills (Claude Code, Codex CLI, Qoder)
 // ============================================================================
 
-function installSkills(toolIds, update = false) {
+function getSkillsDestDir(tool, scope, projectDir) {
+  // Determine destination directory based on install scope
+  if (scope === INSTALL_SCOPE.PROJECT) {
+    // Project-level installation: use relative path within project directory
+    if (tool.id === 'claude') {
+      return path.join(projectDir, '.claude', 'skills');
+    } else if (tool.id === 'codex') {
+      return path.join(projectDir, '.codex', 'skills');
+    } else if (tool.id === 'opencode') {
+      return path.join(projectDir, '.opencode', 'skill');
+    }
+  }
+  // Global installation: use tool's defined global directory
+  return tool.skillsDir;
+}
+
+function installSkills(toolIds, projectDir, scope = INSTALL_SCOPE.GLOBAL, update = false) {
   const results = [];
 
   for (const toolId of toolIds) {
@@ -555,7 +620,7 @@ function installSkills(toolIds, update = false) {
     // Claude Code / Codex CLI / OpenCode (incl. oh-my-opencode) share the same Skills format
     if ((toolId === 'claude' || toolId === 'codex' || toolId === 'opencode') && tool.skillsDir) {
       const skillsSrcDir = path.join(__dirname, '..', 'skills');
-      const skillsDestDir = tool.skillsDir;
+      const skillsDestDir = getSkillsDestDir(tool, scope, projectDir);
 
       if (!fs.existsSync(skillsSrcDir)) continue;
 
@@ -601,13 +666,15 @@ function installSkills(toolIds, update = false) {
         type: 'skills',
         count: installedCount,
         total: skillDirs.length,
-        removed: removedCount
+        removed: removedCount,
+        scope: scope,
+        path: skillsDestDir
       });
     }
 
-    // Qoder: 创建 agents 目录结构（但不复制 Skills，因为格式不同）
+    // Qoder: Create agents directory structure (but don't copy Skills, different format)
     if (toolId === 'qoder') {
-      results.push({ tool: 'Qoder', type: 'agents', count: 0, total: 0, note: '需要手动创建 agents/' });
+      results.push({ tool: 'Qoder', type: 'agents', count: 0, total: 0, note: 'Manual agents/ creation required' });
     }
   }
 
@@ -1006,29 +1073,40 @@ function createProjectStructure(projectDir) {
 }
 
 // ============================================================================
-// 保存配置
+// Save Configuration
 // ============================================================================
 
-function saveConfig(toolIds, projectDir) {
+function saveConfig(toolIds, projectDir, installScope = INSTALL_SCOPE.PROJECT) {
   const configPath = path.join(projectDir, '.devbooks', 'config.yaml');
 
-  // 读取现有配置或创建新配置
+  // Read existing config or create new
   let configContent = '';
   if (fs.existsSync(configPath)) {
     configContent = fs.readFileSync(configPath, 'utf-8');
   }
 
-  // 更新 ai_tools 部分
+  // Update ai_tools section
   const toolsYaml = `ai_tools:\n${toolIds.map(id => `  - ${id}`).join('\n')}`;
 
   if (configContent.includes('ai_tools:')) {
-    // 替换现有的 ai_tools 部分
+    // Replace existing ai_tools section
     configContent = configContent.replace(/ai_tools:[\s\S]*?(?=\n\w|\n$|$)/, toolsYaml + '\n');
   } else {
-    // 追加 ai_tools 部分
+    // Append ai_tools section
     configContent = configContent.trimEnd() + '\n\n' + toolsYaml + '\n';
   }
 
+  // Update install_scope section
+  const scopeYaml = `install_scope: ${installScope}`;
+
+  if (configContent.includes('install_scope:')) {
+    // Replace existing install_scope section
+    configContent = configContent.replace(/install_scope:.*/, scopeYaml);
+  } else {
+    // Append install_scope section
+    configContent = configContent.trimEnd() + '\n\n' + scopeYaml + '\n';
+  }
+
   fs.writeFileSync(configPath, configContent);
 }
 
@@ -1036,38 +1114,42 @@ function loadConfig(projectDir) {
   const configPath = path.join(projectDir, '.devbooks', 'config.yaml');
 
   if (!fs.existsSync(configPath)) {
-    return { aiTools: [] };
+    return { aiTools: [], installScope: null };
   }
 
   const content = fs.readFileSync(configPath, 'utf-8');
-  const match = content.match(/ai_tools:\s*([\s\S]*?)(?=\n\w|\n$|$)/);
-
-  if (!match) {
-    return { aiTools: [] };
-  }
 
-  const tools = match[1]
-    .split('\n')
-    .map(line => line.trim())
-    .filter(line => line.startsWith('-'))
-    .map(line => line.replace(/^-\s*/, '').trim());
-
-  return { aiTools: tools };
+  // Parse ai_tools
+  const toolsMatch = content.match(/ai_tools:\s*([\s\S]*?)(?=\n\w|\n$|$)/);
+  const tools = toolsMatch
+    ? toolsMatch[1]
+        .split('\n')
+        .map(line => line.trim())
+        .filter(line => line.startsWith('-'))
+        .map(line => line.replace(/^-\s*/, '').trim())
+    : [];
+
+  // Parse install_scope
+  const scopeMatch = content.match(/install_scope:\s*(\w+)/);
+  const installScope = scopeMatch ? scopeMatch[1] : null;
+
+  return { aiTools: tools, installScope };
 }
 
 // ============================================================================
-// Init 命令
+// Init Command
 // ============================================================================
 
 async function initCommand(projectDir, options) {
   console.log();
   console.log(chalk.cyan('╔══════════════════════════════════════╗'));
-  console.log(chalk.cyan('║') + chalk.bold('         DevBooks 初始化向导         ') + chalk.cyan('║'));
+  console.log(chalk.cyan('║') + chalk.bold('       DevBooks Initialization        ') + chalk.cyan('║'));
   console.log(chalk.cyan('╚══════════════════════════════════════╝'));
   console.log();
 
-  // 确定选择的工具
+  // Determine selected tools
   let selectedTools;
+  let installScope = INSTALL_SCOPE.PROJECT; // Default to project-level installation
 
   if (options.tools) {
     if (options.tools === 'all') {
@@ -1079,27 +1161,35 @@ async function initCommand(projectDir, options) {
         AI_TOOLS.some(tool => tool.id === t)
       );
     }
-    console.log(chalk.blue('ℹ') + ` 非交互式模式：${selectedTools.length > 0 ? selectedTools.join(', ') : '无'}`);
+    console.log(chalk.blue('ℹ') + ` Non-interactive mode: ${selectedTools.length > 0 ? selectedTools.join(', ') : 'none'}`);
+
+    // In non-interactive mode, check --scope option
+    if (options.scope) {
+      installScope = options.scope === 'global' ? INSTALL_SCOPE.GLOBAL : INSTALL_SCOPE.PROJECT;
+    }
   } else {
     selectedTools = await promptToolSelection(projectDir);
+
+    // Interactive scope selection
+    installScope = await promptInstallScope(projectDir, selectedTools);
   }
 
-  // 创建项目结构
-  const spinner = ora('创建项目结构...').start();
+  // Create project structure
+  const spinner = ora('Creating project structure...').start();
   const templateCount = createProjectStructure(projectDir);
-  spinner.succeed(`创建了 ${templateCount} 个模板文件`);
+  spinner.succeed(`Created ${templateCount} template files`);
 
-  // 保存配置
-  saveConfig(selectedTools, projectDir);
+  // Save configuration (including install scope)
+  saveConfig(selectedTools, projectDir, installScope);
 
   if (selectedTools.length === 0) {
     console.log();
-    console.log(chalk.green('✓') + ' DevBooks 项目结构已创建！');
-    console.log(chalk.gray(`  运行 \`${CLI_COMMAND} init\` 并选择 AI 工具来配置集成。`));
+    console.log(chalk.green('✓') + ' DevBooks project structure created!');
+    console.log(chalk.gray(`  Run \`${CLI_COMMAND} init\` and select AI tools to configure integration.`));
     return;
   }
 
-  // 安装 Skills（仅完整支持的工具）
+  // Install Skills (only for full support tools)
   const fullSupportTools = selectedTools.filter(id => {
     const tool = AI_TOOLS.find(t => t.id === id);
     return tool && tool.skillsSupport === SKILLS_SUPPORT.FULL;
@@ -1107,12 +1197,16 @@ async function initCommand(projectDir, options) {
 
   if (fullSupportTools.length > 0) {
     const skillsSpinner = ora('Installing Skills...').start();
-    const skillsResults = installSkills(fullSupportTools);
+    const skillsResults = installSkills(fullSupportTools, projectDir, installScope);
     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}`));
+        const scopeLabel = result.scope === INSTALL_SCOPE.PROJECT ? 'project-level' : 'global';
+        console.log(chalk.gray(`  └ ${result.tool}: ${result.count}/${result.total} ${result.type} (${scopeLabel})`));
+        if (result.path) {
+          console.log(chalk.gray(`    → ${result.path}`));
+        }
       } else if (result.note) {
         console.log(chalk.gray(`  └ ${result.tool}: ${result.note}`));
       }
@@ -1127,14 +1221,14 @@ async function initCommand(projectDir, options) {
     }
   }
 
-  // 安装 Rules（Rules 类似系统的工具）
+  // Install Rules (for Rules-like system tools)
   const rulesTools = selectedTools.filter(id => {
     const tool = AI_TOOLS.find(t => t.id === id);
     return tool && tool.skillsSupport === SKILLS_SUPPORT.RULES;
   });
 
   if (rulesTools.length > 0) {
-    const rulesSpinner = ora('安装 Rules...').start();
+    const rulesSpinner = ora('Installing Rules...').start();
     const rulesResults = installRules(rulesTools, projectDir);
     rulesSpinner.succeed(`创建了 ${rulesResults.length} 个规则文件`);
 
@@ -1213,6 +1307,7 @@ async function updateCommand(projectDir) {
   // Load config
   const config = loadConfig(projectDir);
   const configuredTools = config.aiTools;
+  const installScope = config.installScope || INSTALL_SCOPE.PROJECT;
 
   if (configuredTools.length === 0) {
     console.log(chalk.yellow('⚠') + ` No AI tools configured. Run \`${CLI_COMMAND} init\` to configure.`);
@@ -1223,13 +1318,17 @@ async function updateCommand(projectDir) {
     const tool = AI_TOOLS.find(t => t.id === id);
     return tool ? tool.name : id;
   });
-  console.log(chalk.blue('ℹ') + ` Detected configured tools: ${toolNames.join(', ')}`);
+  const scopeLabel = installScope === INSTALL_SCOPE.PROJECT ? 'project-level' : 'global';
+  console.log(chalk.blue('ℹ') + ` Detected configured tools: ${toolNames.join(', ')} (${scopeLabel} installation)`);
 
-  // Update Skills (global directory)
-  const skillsResults = installSkills(configuredTools, true);
+  // Update Skills (using saved install scope from config)
+  const skillsResults = installSkills(configuredTools, projectDir, installScope, true);
   for (const result of skillsResults) {
     if (result.count > 0) {
       console.log(chalk.green('✓') + ` ${result.tool} ${result.type}: updated ${result.count}/${result.total}`);
+      if (result.path) {
+        console.log(chalk.gray(`    → ${result.path}`));
+      }
     }
     if (result.removed && result.removed > 0) {
       console.log(chalk.green('✓') + ` ${result.tool} ${result.type}: removed ${result.removed} obsolete skills`);
@@ -1356,31 +1455,33 @@ async function migrateCommand(projectDir, options) {
 }
 
 // ============================================================================
-// 帮助信息
+// Help Information
 // ============================================================================
 
 function showHelp() {
   console.log();
   console.log(chalk.bold('DevBooks') + ' - AI-agnostic spec-driven development workflow');
   console.log();
-  console.log(chalk.cyan('用法:'));
-  console.log(`  ${CLI_COMMAND} init [path] [options]              初始化 DevBooks`);
-  console.log(`  ${CLI_COMMAND} update [path]                      更新已配置的工具`);
-  console.log(`  ${CLI_COMMAND} migrate --from <framework> [opts]  从其他框架迁移`);
+  console.log(chalk.cyan('Usage:'));
+  console.log(`  ${CLI_COMMAND} init [path] [options]              Initialize DevBooks`);
+  console.log(`  ${CLI_COMMAND} update [path]                      Update configured tools`);
+  console.log(`  ${CLI_COMMAND} migrate --from <framework> [opts]  Migrate from other frameworks`);
   console.log();
-  console.log(chalk.cyan('选项:'));
-  console.log('  --tools <tools>    非交互式指定 AI 工具');
-  console.log('                     可用值: all, none, 或逗号分隔的工具 ID');
-  console.log('  --from <framework> 迁移来源框架 (openspec, speckit)');
-  console.log('  --dry-run          模拟运行，不实际修改文件');
-  console.log('  --keep-old         迁移后保留原目录');
-  console.log('  --force            强制重新执行所有步骤');
-  console.log('  -h, --help         显示此帮助信息');
+  console.log(chalk.cyan('Options:'));
+  console.log('  --tools <tools>    Non-interactive AI tool selection');
+  console.log('                     Values: all, none, or comma-separated tool IDs');
+  console.log('  --scope <scope>    Skills installation location (non-interactive mode)');
+  console.log('                     Values: project (default), global');
+  console.log('  --from <framework> Migration source framework (openspec, speckit)');
+  console.log('  --dry-run          Dry run, no actual file modifications');
+  console.log('  --keep-old         Keep original directory after migration');
+  console.log('  --force            Force re-execute all steps');
+  console.log('  -h, --help         Show this help message');
   console.log('  -v, --version      Show version');
   console.log();
-  console.log(chalk.cyan('支持的 AI 工具:'));
+  console.log(chalk.cyan('Supported AI Tools:'));
 
-  // 按 Skills 支持级别分组显示
+  // Group tools by Skills support level
   const groupedTools = {
     [SKILLS_SUPPORT.FULL]: [],
     [SKILLS_SUPPORT.RULES]: [],
@@ -1393,43 +1494,44 @@ function showHelp() {
   }
 
   console.log();
-  console.log(chalk.green('  ★ 完整 Skills 支持:'));
+  console.log(chalk.green('  ★ Full Skills Support:'));
   for (const tool of groupedTools[SKILLS_SUPPORT.FULL]) {
     console.log(`    ${tool.id.padEnd(15)} ${tool.name}`);
   }
 
   console.log();
-  console.log(chalk.blue('  ◆ Rules 系统支持:'));
+  console.log(chalk.blue('  ◆ Rules System Support:'));
   for (const tool of groupedTools[SKILLS_SUPPORT.RULES]) {
     console.log(`    ${tool.id.padEnd(15)} ${tool.name}`);
   }
 
   console.log();
-  console.log(chalk.yellow('  ● 自定义指令支持:'));
+  console.log(chalk.yellow('  ● Custom Instructions Support:'));
   for (const tool of groupedTools[SKILLS_SUPPORT.AGENTS]) {
     console.log(`    ${tool.id.padEnd(15)} ${tool.name}`);
   }
 
   console.log();
   console.log();
-  console.log(chalk.cyan('示例:'));
-  console.log(`  ${CLI_COMMAND} init                        # 交互式初始化`);
-  console.log(`  ${CLI_COMMAND} init my-project             # 在 my-project 目录初始化`);
-  console.log(`  ${CLI_COMMAND} init --tools claude,cursor  # 非交互式`);
-  console.log(`  ${CLI_COMMAND} update                      # 更新已配置的工具`);
-  console.log(`  ${CLI_COMMAND} migrate --from openspec     # 从 OpenSpec 迁移`);
-  console.log(`  ${CLI_COMMAND} migrate --from speckit      # 从 spec-kit 迁移`);
-  console.log(`  ${CLI_COMMAND} migrate --from openspec --dry-run  # 模拟迁移`);
+  console.log(chalk.cyan('Examples:'));
+  console.log(`  ${CLI_COMMAND} init                        # Interactive initialization`);
+  console.log(`  ${CLI_COMMAND} init my-project             # Initialize in my-project directory`);
+  console.log(`  ${CLI_COMMAND} init --tools claude,cursor  # Non-interactive (project-level by default)`);
+  console.log(`  ${CLI_COMMAND} init --tools claude --scope global  # Non-interactive (global installation)`);
+  console.log(`  ${CLI_COMMAND} update                      # Update configured tools`);
+  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`);
 }
 
 // ============================================================================
-// 主入口
+// Main Entry
 // ============================================================================
 
 async function main() {
   const args = process.argv.slice(2);
 
-  // 解析参数
+  // Parse arguments
   let command = null;
   let projectPath = null;
   const options = {};
@@ -1445,6 +1547,8 @@ async function main() {
       process.exit(0);
     } else if (arg === '--tools') {
       options.tools = args[++i];
+    } else if (arg === '--scope') {
+      options.scope = args[++i];
     } else if (arg === '--from') {
       options.from = args[++i];
     } else if (arg === '--dry-run') {

package/package.json

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

package/skills/Skills-Usage-Guide.md

@@ -344,6 +344,54 @@ If you are not using DevBooks, replace `dev-playbooks/specs` / `dev-playbooks/ch
 
 ---
 
+## `devbooks-test-reviewer` (Test Reviewer) [New]
+
+- Purpose: review test quality in `tests/` (coverage, boundary conditions, readability, maintainability); output review comments only; do not modify code.
+- When to use:
+  - After Test Owner completes tests, an independent quality review is needed
+  - You want to find coverage gaps, missing boundary conditions, and maintainability issues
+- Copy-paste prompt:
+  ```text
+  You are Test Reviewer. Explicitly use `devbooks-test-reviewer`.
+  Review test quality only (coverage/boundary conditions/readability/maintainability); do not modify code.
+  Inputs: `tests/**` + `dev-playbooks/changes/<change-id>/verification.md` (if present)
+  Output: coverage gaps / missing boundary conditions / maintainability risks / improvement suggestions.
+  ```
+
+---
+
+## `devbooks-convergence-audit` (Convergence Auditor) [New]
+
+- Purpose: evaluate DevBooks workflow convergence using "evidence-first, distrust declarations" principle; detect "Sisyphus anti-pattern" and "false completion". Actively verify rather than trust document assertions.
+- Anti-confusion design: never trust any assertion in documents (Status: Done, AC checked, etc.); must confirm through verifiable evidence.
+- When to use:
+  - You want to evaluate true workflow convergence (not document claims)
+  - You suspect a change package is "false completion" or has "stale evidence"
+  - You want to detect Sisyphus trap (repeated rework without convergence)
+- Copy-paste prompt:
+  ```text
+  You are Convergence Auditor. Explicitly use `devbooks-convergence-audit`.
+  First read: `dev-playbooks/project.md` (if present)
+  Goal: perform a convergence audit on a specified change package.
+
+  Execute with anti-confusion principles:
+  1) Read all documents under `dev-playbooks/changes/<change-id>/`
+  2) Verify each "declaration" (Status=Done, AC checked, etc.) against evidence
+  3) Actually run tests for verification (if possible)
+  4) Output: declaration vs evidence comparison table + trustworthiness score + confusion detection results
+
+  Change package: <change-id>
+  truth-root: dev-playbooks/specs
+  change-root: dev-playbooks/changes
+  ```
+- Trustworthiness scoring:
+  - 90-100: ✅ Trustworthy convergence, continue current workflow
+  - 70-89: ⚠️ Partially trustworthy, needs additional verification
+  - 50-69: 🟠 Questionable, parts need rework
+  - < 50: 🔴 Untrustworthy (Sisyphus trap), needs full review
+
+---
+
 ## Generating SCIP Index (Manual)
 
 If you need graph-based code understanding (call graph, impact analysis, symbol references), you can generate a SCIP index manually:

package/skills/devbooks-impact-analysis/SKILL.md

@@ -28,7 +28,42 @@ Before execution, **must** search for configuration in the following order (stop
 
 ## Output Location
 
-- Recommended: Write to the Impact section of `<change-root>/<change-id>/proposal.md` (or create a separate analysis document and backfill later)
+- **Must** write to: The Impact section of `<change-root>/<change-id>/proposal.md`
+- Alternative: Separate `impact-analysis.md` file (to be backfilled to proposal.md later)
+
+## Output Behavior (Critical Constraint)
+
+> **Golden Rule**: **Write directly to document, do NOT output to conversation window**
+
+### Must Follow
+
+1. **Direct Write**: Use `Edit` or `Write` tool to write analysis results directly to target document
+2. **No Echo**: Do NOT display the complete analysis content in the conversation
+3. **Brief Notification**: After completion, only inform the user "Impact analysis written to `<file-path>`"
+
+### Correct vs Incorrect Behavior
+
+| Scenario | ❌ Incorrect Behavior | ✅ Correct Behavior |
+|----------|----------------------|---------------------|
+| Analysis complete | Output full Impact table in conversation | Use Edit tool to write to proposal.md |
+| Notify user | Repeat analysis content | "Impact analysis written to `changes/xxx/proposal.md`" |
+| Large results | Paginate output to conversation | Write all to file, inform file location |
+
+### Example Conversation
+
+```
+User: Analyze the impact of modifying UserService
+
+AI: [Uses Grep/CKB to analyze references]
+    [Uses Edit tool to write to proposal.md]
+
+    Impact analysis written to the Impact section of `changes/refactor-user/proposal.md`.
+    - Direct impact: 8 files
+    - Indirect impact: 12 files
+    - Risk level: Medium
+
+    Open the file to view details.
+```
 
 ## Execution Method