@givolt/i3-composer-agent 2.1.1 → 2.2.1

package/bin/wizard.cjs

@@ -1,7 +1,8 @@
 'use strict';
 
 const readline = require('node:readline');
-const { registry, selectAgents } = require('./install.cjs');
+const { selectAgents } = require('./install.cjs');
+const { selectTools } = require('./tool-selector.cjs');
 
 async function session(action) {
   const terminal = readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -22,47 +23,35 @@ async function session(action) {
 }
 async function choose(options, identity) {
   console.log(identity);
-  console.log('\nChoose tools (multiple selections are supported):');
-  const entries = registry.agents.map((agent, index) => `${index + 1}. ${agent.label} [${agent.id}]${agent.globalSkillsDir ? '' : ' (project only)'}`);
-  for (let index = 0; index < entries.length; index += 2) console.log(entries[index].padEnd(49) + (entries[index + 1] || ''));
+  const agents = await selectTools(selectAgents(options.agents));
+  if (!agents) return null;
+  if (agents.includes('workbuddy')) console.log('WorkBuddy 桌面版建议全局安装，以便技能列表和输入补全发现 Skills；项目安装仍支持命令，技能列表可能不显示。');
   return session(async ask => {
-    let agents;
-    while (!agents) {
-      const input = await ask(`Select tools by number or ID, comma-separated${options.agents.length ? ` [${options.agents.join(',')}]` : ''} (q cancels): `);
-      if (input === null || ['q', 'cancel'].includes(input.toLowerCase())) return null;
-      try {
-        const values = input === 'all' ? registry.agents.map(agent => agent.id) : input ? input.split(',').map(value => {
-          const trimmed = value.trim();
-          return /^\d+$/.test(trimmed) ? registry.agents[Number(trimmed) - 1]?.id || trimmed : trimmed;
-        }) : options.agents;
-        agents = selectAgents(values);
-        if (!agents.length) { agents = undefined; console.log('Choose at least one tool.'); }
-      } catch (error) { console.log(error.message); }
-    }
-    if (agents.includes('workbuddy')) console.log('WorkBuddy desktop: global installation is recommended for Skills list and input completion. Project Skills may be absent from the Skills list.');
+    const cancelled = input => input === null || ['q', 'cancel', '取消'].includes(input.toLowerCase());
     let scope = options.scope;
     while (!scope) {
-      const input = await ask('Installation scope: 1. Project (current project), 2. Global (all projects) [1] (q cancels): ');
-      if (input === null || ['q', 'cancel'].includes(input.toLowerCase())) return null;
-      if (['', '1', 'project'].includes(input)) scope = 'project';
-      else if (['2', 'global'].includes(input)) scope = 'global';
-      else console.log('Choose 1 (project) or 2 (global).');
+      const input = await ask('安装范围：1. 项目（当前项目），2. 全局（所有项目）[1]（q/取消退出）： ');
+      if (cancelled(input)) return null;
+      if (['', '1', 'project', '项目'].includes(input)) scope = 'project';
+      else if (['2', 'global', '全局'].includes(input)) scope = 'global';
+      else console.log('请选择 1（项目）或 2（全局）。');
     }
     return { agents, scope };
   });
 }
 async function confirm(plan) {
-  console.log(`\nInstallation scope: ${plan.scope}`);
+  console.log(`\n安装范围：${plan.scope === 'project' ? '项目' : '全局'}`);
   for (const target of plan.targets) {
     console.log(`  ${target.agents.join(', ')}: ${target.skillsDirectory}`);
-    if (target.commandsDirectory) console.log(`  Commands: ${target.commandsDirectory}`);
+    if (target.commandsDirectory) console.log(`  命令：${target.commandsDirectory}`);
+    console.log(`  完整配套（evals、hooks、scripts）：${target.supportDirectory}`);
   }
-  if (plan.conflicts.length) console.log(`${plan.conflicts.length} existing assets will be replaced. Previous files are removed after successful installation.`);
-  if (plan.reused.length) console.log(`${plan.reused.length} unchanged assets from the same version will be reused.`);
-  console.log('Includes all skills and shared references. Plugin hooks require native plugin registration.');
+  if (plan.conflicts.length) console.log(`将替换 ${plan.conflicts.length} 个已有内容；安装成功后清理旧文件，失败则恢复。`);
+  if (plan.reused.length) console.log(`将复用同版本的 ${plan.reused.length} 个未修改内容。`);
+  console.log('包含技能、共享资料和完整评测/Hook/脚本配套。安装不执行评测；Hook 需按宿主方式启用。');
   return session(async ask => {
-    const answer = await ask('Install these files? [y/N]: ');
-    return answer !== null && ['y', 'yes'].includes(answer.toLowerCase());
+    const answer = await ask('确认安装这些内容？[y/N]： ');
+    return answer !== null && ['y', 'yes', '是', '确认'].includes(answer.toLowerCase());
   });
 }
 module.exports = { choose, confirm };

package/commands/i3-build.toml

@@ -1,6 +1,18 @@
-description = "Implement tasks incrementally — build, test, verify, commit. Add \"auto\" to run the whole plan in one approved pass."
+description = "按任务增量实现、构建、测试、验证并提交；添加 auto 可按已获批准的完整计划执行。"
+# i3-description-source: "description = \"Implement tasks incrementally — build, test, verify, commit. Add \\\"auto\\\" to run the whole plan in one approved pass.\""
 
 prompt = """
+<!-- i3:zh-CN:start -->
+## 中文交互与输出
+
+默认使用简体中文回复，包括追问、选项说明、阶段进度、分析、规格、计划、验收、代码审查与发布报告。只有用户明确要求其他语言时才切换；输入中出现英文术语、代码或引用不构成切换语言的要求。
+下文的工程步骤、审批要求、退出条件和工具约束完整有效。英文示例中的人类可读标题、说明和占位内容在实际输出时应译为中文；保留原有信息与验证标准，不删减方法。
+Skill/Command/Agent 标识、文件路径、命令参数、代码/API 名称、工具调用参数、JSON 键/类型/枚举、机器状态、测试期望字面量及引用原文保持原样。生成文档正文用中文，SPEC.md、tasks/plan.md、tasks/todo.md、CONSTRAINTS.md 等约定路径不改名。
+严重程度按原规则判断，面向用户可写“严重（Critical）”“必须修复（Required）”“小问题（Nit）”“可选（Optional）”“建议考虑（Consider）”“仅供参考（FYI）”；High/Medium/Low、APPROVE/REQUEST CHANGES 和 GO/NO-GO 保留其原始语义与机器值。不得因翻译降低门槛，角色不能互相委派。
+
+适用说明：按任务增量实现、构建、测试、验证并提交；添加 auto 可按已获批准的完整计划执行。
+<!-- i3:zh-CN:end -->
+
 Invoke the i3-incremental-implementation skill alongside i3-test-driven-development.
 
 ## Modes

package/commands/i3-code-simplify.toml

@@ -1,6 +1,18 @@
-description = "Simplify code for clarity and maintainability — reduce complexity without changing behavior"
+description = "简化代码，降低复杂度，提高可读性与维护性，并保持既有行为不变。"
+# i3-description-source: "description = \"Simplify code for clarity and maintainability — reduce complexity without changing behavior\""
 
 prompt = """
+<!-- i3:zh-CN:start -->
+## 中文交互与输出
+
+默认使用简体中文回复，包括追问、选项说明、阶段进度、分析、规格、计划、验收、代码审查与发布报告。只有用户明确要求其他语言时才切换；输入中出现英文术语、代码或引用不构成切换语言的要求。
+下文的工程步骤、审批要求、退出条件和工具约束完整有效。英文示例中的人类可读标题、说明和占位内容在实际输出时应译为中文；保留原有信息与验证标准，不删减方法。
+Skill/Command/Agent 标识、文件路径、命令参数、代码/API 名称、工具调用参数、JSON 键/类型/枚举、机器状态、测试期望字面量及引用原文保持原样。生成文档正文用中文，SPEC.md、tasks/plan.md、tasks/todo.md、CONSTRAINTS.md 等约定路径不改名。
+严重程度按原规则判断，面向用户可写“严重（Critical）”“必须修复（Required）”“小问题（Nit）”“可选（Optional）”“建议考虑（Consider）”“仅供参考（FYI）”；High/Medium/Low、APPROVE/REQUEST CHANGES 和 GO/NO-GO 保留其原始语义与机器值。不得因翻译降低门槛，角色不能互相委派。
+
+适用说明：简化代码，降低复杂度，提高可读性与维护性，并保持既有行为不变。
+<!-- i3:zh-CN:end -->
+
 Invoke the i3-code-simplification skill.
 
 Simplify recently changed code (or the specified scope) while preserving exact behavior:

package/commands/i3-constraints.toml

@@ -1,6 +1,18 @@
-description = "Define and enforce this project's quality bar — interview, sane defaults, CONSTRAINTS.md"
+description = "访谈并定义项目质量门槛，提供合理默认值，写入 CONSTRAINTS.md 并落实约束。"
+# i3-description-source: "description = \"Define and enforce this project's quality bar — interview, sane defaults, CONSTRAINTS.md\""
 
 prompt = """
+<!-- i3:zh-CN:start -->
+## 中文交互与输出
+
+默认使用简体中文回复，包括追问、选项说明、阶段进度、分析、规格、计划、验收、代码审查与发布报告。只有用户明确要求其他语言时才切换；输入中出现英文术语、代码或引用不构成切换语言的要求。
+下文的工程步骤、审批要求、退出条件和工具约束完整有效。英文示例中的人类可读标题、说明和占位内容在实际输出时应译为中文；保留原有信息与验证标准，不删减方法。
+Skill/Command/Agent 标识、文件路径、命令参数、代码/API 名称、工具调用参数、JSON 键/类型/枚举、机器状态、测试期望字面量及引用原文保持原样。生成文档正文用中文，SPEC.md、tasks/plan.md、tasks/todo.md、CONSTRAINTS.md 等约定路径不改名。
+严重程度按原规则判断，面向用户可写“严重（Critical）”“必须修复（Required）”“小问题（Nit）”“可选（Optional）”“建议考虑（Consider）”“仅供参考（FYI）”；High/Medium/Low、APPROVE/REQUEST CHANGES 和 GO/NO-GO 保留其原始语义与机器值。不得因翻译降低门槛，角色不能互相委派。
+
+适用说明：访谈并定义项目质量门槛，提供合理默认值，写入 CONSTRAINTS.md 并落实约束。
+<!-- i3:zh-CN:end -->
+
 Invoke the i3-constraint-driven-development skill.
 
 $ARGUMENTS

package/commands/i3-planning.toml

@@ -1,6 +1,18 @@
-description = "Break work into small verifiable tasks with acceptance criteria and dependency ordering"
+description = "把工作拆成带验收标准、验证步骤和依赖顺序的小任务。"
+# i3-description-source: "description = \"Break work into small verifiable tasks with acceptance criteria and dependency ordering\""
 
 prompt = """
+<!-- i3:zh-CN:start -->
+## 中文交互与输出
+
+默认使用简体中文回复，包括追问、选项说明、阶段进度、分析、规格、计划、验收、代码审查与发布报告。只有用户明确要求其他语言时才切换；输入中出现英文术语、代码或引用不构成切换语言的要求。
+下文的工程步骤、审批要求、退出条件和工具约束完整有效。英文示例中的人类可读标题、说明和占位内容在实际输出时应译为中文；保留原有信息与验证标准，不删减方法。
+Skill/Command/Agent 标识、文件路径、命令参数、代码/API 名称、工具调用参数、JSON 键/类型/枚举、机器状态、测试期望字面量及引用原文保持原样。生成文档正文用中文，SPEC.md、tasks/plan.md、tasks/todo.md、CONSTRAINTS.md 等约定路径不改名。
+严重程度按原规则判断，面向用户可写“严重（Critical）”“必须修复（Required）”“小问题（Nit）”“可选（Optional）”“建议考虑（Consider）”“仅供参考（FYI）”；High/Medium/Low、APPROVE/REQUEST CHANGES 和 GO/NO-GO 保留其原始语义与机器值。不得因翻译降低门槛，角色不能互相委派。
+
+适用说明：把工作拆成带验收标准、验证步骤和依赖顺序的小任务。
+<!-- i3:zh-CN:end -->
+
 Invoke the i3-planning-and-task-breakdown skill.
 
 Read the existing spec (SPEC.md or equivalent) and the relevant codebase sections. Then:

package/commands/i3-review.toml

@@ -1,6 +1,18 @@
-description = "Conduct a five-axis code review — correctness, readability, architecture, security, performance"
+description = "从正确性、可读性、架构、安全和性能五个维度审查代码。"
+# i3-description-source: "description = \"Conduct a five-axis code review — correctness, readability, architecture, security, performance\""
 
 prompt = """
+<!-- i3:zh-CN:start -->
+## 中文交互与输出
+
+默认使用简体中文回复，包括追问、选项说明、阶段进度、分析、规格、计划、验收、代码审查与发布报告。只有用户明确要求其他语言时才切换；输入中出现英文术语、代码或引用不构成切换语言的要求。
+下文的工程步骤、审批要求、退出条件和工具约束完整有效。英文示例中的人类可读标题、说明和占位内容在实际输出时应译为中文；保留原有信息与验证标准，不删减方法。
+Skill/Command/Agent 标识、文件路径、命令参数、代码/API 名称、工具调用参数、JSON 键/类型/枚举、机器状态、测试期望字面量及引用原文保持原样。生成文档正文用中文，SPEC.md、tasks/plan.md、tasks/todo.md、CONSTRAINTS.md 等约定路径不改名。
+严重程度按原规则判断，面向用户可写“严重（Critical）”“必须修复（Required）”“小问题（Nit）”“可选（Optional）”“建议考虑（Consider）”“仅供参考（FYI）”；High/Medium/Low、APPROVE/REQUEST CHANGES 和 GO/NO-GO 保留其原始语义与机器值。不得因翻译降低门槛，角色不能互相委派。
+
+适用说明：从正确性、可读性、架构、安全和性能五个维度审查代码。
+<!-- i3:zh-CN:end -->
+
 Invoke the i3-code-review-and-quality skill.
 
 Review the current changes (staged or recent commits) across all five axes:

package/commands/i3-ship.toml

@@ -1,6 +1,18 @@
-description = "Run the pre-launch checklist via parallel fan-out to specialist personas, then synthesize a go/no-go decision"
+description = "并行调用三个专业角色执行发布前检查，主会话汇总 GO/NO-GO 决策与回滚计划。"
+# i3-description-source: "description = \"Run the pre-launch checklist via parallel fan-out to specialist personas, then synthesize a go/no-go decision\""
 
 prompt = """
+<!-- i3:zh-CN:start -->
+## 中文交互与输出
+
+默认使用简体中文回复，包括追问、选项说明、阶段进度、分析、规格、计划、验收、代码审查与发布报告。只有用户明确要求其他语言时才切换；输入中出现英文术语、代码或引用不构成切换语言的要求。
+下文的工程步骤、审批要求、退出条件和工具约束完整有效。英文示例中的人类可读标题、说明和占位内容在实际输出时应译为中文；保留原有信息与验证标准，不删减方法。
+Skill/Command/Agent 标识、文件路径、命令参数、代码/API 名称、工具调用参数、JSON 键/类型/枚举、机器状态、测试期望字面量及引用原文保持原样。生成文档正文用中文，SPEC.md、tasks/plan.md、tasks/todo.md、CONSTRAINTS.md 等约定路径不改名。
+严重程度按原规则判断，面向用户可写“严重（Critical）”“必须修复（Required）”“小问题（Nit）”“可选（Optional）”“建议考虑（Consider）”“仅供参考（FYI）”；High/Medium/Low、APPROVE/REQUEST CHANGES 和 GO/NO-GO 保留其原始语义与机器值。不得因翻译降低门槛，角色不能互相委派。
+
+适用说明：并行调用三个专业角色执行发布前检查，主会话汇总 GO/NO-GO 决策与回滚计划。
+<!-- i3:zh-CN:end -->
+
 Invoke the i3-shipping-and-launch skill.
 
 `/i3-ship` is a **fan-out orchestrator**. It runs three specialist personas in parallel against the current change, then merges their reports into a single go/no-go decision with a rollback plan. The personas operate independently — no shared state, no ordering — which is what makes parallel execution safe and useful here.

package/commands/i3-spec.toml

@@ -1,6 +1,18 @@
-description = "Start spec-driven development — write a structured specification before writing code"
+description = "先编写结构化规格、目标、范围与验收标准，再进入实现。"
+# i3-description-source: "description = \"Start spec-driven development — write a structured specification before writing code\""
 
 prompt = """
+<!-- i3:zh-CN:start -->
+## 中文交互与输出
+
+默认使用简体中文回复，包括追问、选项说明、阶段进度、分析、规格、计划、验收、代码审查与发布报告。只有用户明确要求其他语言时才切换；输入中出现英文术语、代码或引用不构成切换语言的要求。
+下文的工程步骤、审批要求、退出条件和工具约束完整有效。英文示例中的人类可读标题、说明和占位内容在实际输出时应译为中文；保留原有信息与验证标准，不删减方法。
+Skill/Command/Agent 标识、文件路径、命令参数、代码/API 名称、工具调用参数、JSON 键/类型/枚举、机器状态、测试期望字面量及引用原文保持原样。生成文档正文用中文，SPEC.md、tasks/plan.md、tasks/todo.md、CONSTRAINTS.md 等约定路径不改名。
+严重程度按原规则判断，面向用户可写“严重（Critical）”“必须修复（Required）”“小问题（Nit）”“可选（Optional）”“建议考虑（Consider）”“仅供参考（FYI）”；High/Medium/Low、APPROVE/REQUEST CHANGES 和 GO/NO-GO 保留其原始语义与机器值。不得因翻译降低门槛，角色不能互相委派。
+
+适用说明：先编写结构化规格、目标、范围与验收标准，再进入实现。
+<!-- i3:zh-CN:end -->
+
 Invoke the i3-spec-driven-development skill.
 
 Begin by understanding what the user wants to build. Ask clarifying questions about:

package/commands/i3-test.toml

@@ -1,6 +1,18 @@
-description = "Run TDD workflow — write failing tests, implement, verify. For bugs, use the Prove-It pattern."
+description = "执行 TDD：先编写失败测试，再实现和验证；缺陷使用 Prove-It 模式复现。"
+# i3-description-source: "description = \"Run TDD workflow — write failing tests, implement, verify. For bugs, use the Prove-It pattern.\""
 
 prompt = """
+<!-- i3:zh-CN:start -->
+## 中文交互与输出
+
+默认使用简体中文回复，包括追问、选项说明、阶段进度、分析、规格、计划、验收、代码审查与发布报告。只有用户明确要求其他语言时才切换；输入中出现英文术语、代码或引用不构成切换语言的要求。
+下文的工程步骤、审批要求、退出条件和工具约束完整有效。英文示例中的人类可读标题、说明和占位内容在实际输出时应译为中文；保留原有信息与验证标准，不删减方法。
+Skill/Command/Agent 标识、文件路径、命令参数、代码/API 名称、工具调用参数、JSON 键/类型/枚举、机器状态、测试期望字面量及引用原文保持原样。生成文档正文用中文，SPEC.md、tasks/plan.md、tasks/todo.md、CONSTRAINTS.md 等约定路径不改名。
+严重程度按原规则判断，面向用户可写“严重（Critical）”“必须修复（Required）”“小问题（Nit）”“可选（Optional）”“建议考虑（Consider）”“仅供参考（FYI）”；High/Medium/Low、APPROVE/REQUEST CHANGES 和 GO/NO-GO 保留其原始语义与机器值。不得因翻译降低门槛，角色不能互相委派。
+
+适用说明：执行 TDD：先编写失败测试，再实现和验证；缺陷使用 Prove-It 模式复现。
+<!-- i3:zh-CN:end -->
+
 Invoke the i3-test-driven-development skill.
 
 For new features:

package/commands/i3-webperf.toml

@@ -1,6 +1,18 @@
-description = "Run a web performance audit via the web-performance-auditor persona"
+description = "调用 web-performance-auditor 角色审查网页性能与 Core Web Vitals。"
+# i3-description-source: "description = \"Run a web performance audit via the web-performance-auditor persona\""
 
 prompt = """
+<!-- i3:zh-CN:start -->
+## 中文交互与输出
+
+默认使用简体中文回复，包括追问、选项说明、阶段进度、分析、规格、计划、验收、代码审查与发布报告。只有用户明确要求其他语言时才切换；输入中出现英文术语、代码或引用不构成切换语言的要求。
+下文的工程步骤、审批要求、退出条件和工具约束完整有效。英文示例中的人类可读标题、说明和占位内容在实际输出时应译为中文；保留原有信息与验证标准，不删减方法。
+Skill/Command/Agent 标识、文件路径、命令参数、代码/API 名称、工具调用参数、JSON 键/类型/枚举、机器状态、测试期望字面量及引用原文保持原样。生成文档正文用中文，SPEC.md、tasks/plan.md、tasks/todo.md、CONSTRAINTS.md 等约定路径不改名。
+严重程度按原规则判断，面向用户可写“严重（Critical）”“必须修复（Required）”“小问题（Nit）”“可选（Optional）”“建议考虑（Consider）”“仅供参考（FYI）”；High/Medium/Low、APPROVE/REQUEST CHANGES 和 GO/NO-GO 保留其原始语义与机器值。不得因翻译降低门槛，角色不能互相委派。
+
+适用说明：调用 web-performance-auditor 角色审查网页性能与 Core Web Vitals。
+<!-- i3:zh-CN:end -->
+
 /i3-webperf targets web applications specifically. Do not use it for utility libraries, CLIs, or server-only code with no browser-facing output.
 
 ## Determine the mode

package/docs/adoption-guide.md

@@ -1,5 +1,13 @@
 # Adoption Guide: New Projects vs. Established Codebases
 
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
 How to roll out i3-composer-agent depends heavily on where your codebase is in its life. A greenfield project can adopt the full lifecycle from commit one. A codebase with years of history needs an incremental path that respects what already exists, its conventions, its undocumented decisions, and its lack of test coverage in places you'd rather not touch blind.
 
 This guide covers both paths. For installation mechanics, see [getting-started.md](getting-started.md) and the per-tool setup guides. For what each skill does, see the [skill catalog in the README](../README.md#all-25-skills).

package/docs/agents.md

@@ -1,5 +1,13 @@
 # Agent Personas
 
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+code-reviewer 审查五维代码质量；security-auditor 审计安全；test-engineer 分析测试；web-performance-auditor 审计网页性能。输出中文报告，保留各角色权限、严重程度、证据字段和调用边界。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
 Specialist personas that play a single role with a single perspective. Each persona is a Markdown file consumed as a system prompt by your harness (Claude Code, Cursor, Copilot, etc.).
 
 | Persona | Role | Best for |

package/docs/antigravity-setup.md

@@ -1,5 +1,13 @@
 # Using i3-composer-agent with Antigravity CLI (agy)
 
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
 The `i3-composer-agent` package can be installed as a native plugin in the Antigravity CLI (`agy`), giving the agent access to structured workflows and personas.
 
 ## Setup

package/docs/codebuddy-setup.md

@@ -1,27 +1,21 @@
-# Using i3 Composer Agent with CodeBuddy
+# 在 CodeBuddy 使用 i3 Composer Agent
 
-## Desktop IDE installation
+## 桌面 IDE 安装
 
-Run inside your business project:
+在业务项目运行：
 
 ```bash
 npx @givolt/i3-composer-agent --codebuddy
 ```
 
-The terminal wizard preselects CodeBuddy, still allows multiple tools, and asks
-for project or global scope before installing. Project scope writes these paths:
+向导预选 CodeBuddy，可增加其他工具，再选择项目或全局范围。
+项目安装提供 `.codebuddy/skills/`（25 个技能）、`references/`、
+`commands/`（9 个命令）和 `agents/`（4 个角色）。
+同级 `i3-composer-agent/` 默认提供完整的 `evals/`、`hooks/`、`scripts/` 和依赖资料。
+全局使用 `~/.codebuddy/` 的相同结构。默认中文说明和回复；技能/命令标识不改名。
+安装成功清理旧内容，失败恢复；设置与自定义命令保留。
 
-- `.codebuddy/skills/` — all 25 skills with `i3-` IDs.
-- `.codebuddy/references/` — shared checklists used by skill-relative links.
-- `.codebuddy/commands/` — all 9 existing lifecycle workflows.
-- `.codebuddy/agents/` — all 4 persona definitions.
-
-Global scope uses the same layout under `~/.codebuddy/`. Unchanged manifest-owned
-assets from the same version are reused. Modified files, unowned collisions and
-upgrades require confirmed replacement. Previous files are removed after
-successful installation; a failure restores them. Settings are preserved.
-Reload the CodeBuddy window or start a new chat, then inspect
-the Skills list and type `/` to inspect the command menu.
+重新加载窗口或新建会话，检查技能列表与 `/` 命令补全：
 
 ```text
 /i3-spec
@@ -32,71 +26,46 @@ the Skills list and type `/` to inspect the command menu.
 /i3-ship
 ```
 
-The command wrappers reference installed skill IDs without the plugin namespace.
-Their workflow content and approval gates are retained. File installation does
-not itself prove that the IDE has discovered or executed every workflow.
-
-For multiple tools or a noninteractive installation:
+命令直接调用安装的技能 ID，保留 `$ARGUMENTS`、原工程规则和审批边界。
+发布命令按宿主能力并行审查或顺序降级，主会话汇总并提供回滚计划。
 
 ```bash
 npx @givolt/i3-composer-agent --agents codebuddy,codex --scope project --yes
 npx @givolt/i3-composer-agent --agents codebuddy,workbuddy --scope global --yes
-npx @givolt/i3-composer-agent --codebuddy --scope global --yes
 ```
 
-CodeBuddy and WorkBuddy share `.codebuddy/` project files. Installing either
-client first and adding the other at the same package version reuses unmodified
-owned files and merges the client IDs. Global WorkBuddy files use
-`~/.workbuddy/`, independently of `~/.codebuddy/`. See [WorkBuddy setup](workbuddy-setup.md).
+CodeBuddy 与 WorkBuddy 项目共用 `.codebuddy/`；同版本追加客户端会复用未修改内容。
+全局目录彼此独立。WorkBuddy 桌面版建议全局安装，详见 [WorkBuddy 说明](workbuddy-setup.md)。
+升级或同名冲突先查看 `--dry-run`，再确认或使用 `--yes --force`。
 
-For WorkBuddy desktop, global installation is recommended because WorkBuddy
-5.7.7 does not list the shared `.codebuddy/skills/` project Skills. You can keep
-CodeBuddy at project scope and install WorkBuddy separately with
-`--workbuddy --scope global`.
+## 配套检查
 
-CodeBuddy documents [IDE skills](https://www.codebuddy.cn/docs/ide/Features/Skills)
-and [IDE custom commands](https://www.codebuddy.cn/docs/ide/User-guide/Slash-Commands).
-The directory layout follows its [configuration directory reference](https://www.codebuddy.cn/docs/cli/codebuddy-dir).
+进入 `.codebuddy/i3-composer-agent/`（全局安装使用对应全局路径）运行 `npm test`，
+可检查技能格式及中英文触发，不调用模型。行为评测、样例和脚本用法见
+[评测说明](../evals/README.md)。Hook 文件已安装，需要按宿主协议单独启用。
 
-## CodeBuddy Code native plugin registration
+## 通过 CodeBuddy Code 插件管理器安装
 
-For the terminal CodeBuddy Code plugin manager, explicitly prepare the full
-plugin instead of native skill installation:
+这是另一种由宿主插件管理器管理的安装方式；已完成原生安装时无需再次执行。
+`--prepare` 只导出文件并显示注册步骤，不自动注册插件或启用 Hook：
 
 ```bash
 npx @givolt/i3-composer-agent --prepare --codebuddy
 ```
 
-In CodeBuddy Code, register the prepared directory and install the plugin:
+在 CodeBuddy Code 中执行 CLI 显示的注册命令，目录不同时使用绝对路径：
 
 ```text
 /plugin marketplace add ./i3-composer-agent
 /plugin install i3-composer-agent@i3-composer-agent
 ```
 
-Use the absolute directory printed by the CLI if CodeBuddy has a different
-working directory. Choose the intended installation scope in CodeBuddy Code's native
-plugin manager. Reload plugins or start a new session after installation.
-
-CodeBuddy Code supports the existing `.claude-plugin/plugin.json` compatibility
-manifest. It declares `.claude/commands/` and `commands/`, preserving the nine
-original lifecycle commands and their workflow content.
-
-```text
-/i3-composer-agent:i3-spec
-/i3-composer-agent:i3-plan
-/i3-composer-agent:i3-build
-/i3-composer-agent:i3-build auto
-/i3-composer-agent:i3-review
-/i3-composer-agent:i3-ship
-```
-
-Skill IDs and command filenames use `i3-`. Persona names, artifact paths,
-and workflow gates retain their upstream behavior. The plugin namespace is
-`i3-composer-agent`.
-
-The prepared plugin includes all skills, personas, commands, hooks and shared
-`references/`. Native skill installation above does not enable plugin hooks.
+按宿主选择范围并启用后新建会话。兼容清单声明 `.claude/commands/` 与 `commands/`。
+插件命令示例为 `/i3-composer-agent:i3-spec`、`/i3-composer-agent:i3-plan`、
+`/i3-composer-agent:i3-build auto` 和 `/i3-composer-agent:i3-ship`。
+默认安装和导出均包含完整评测、Hook 与脚本；Hook 不自动启用。
+文件落盘、宿主发现和模型实际执行应分别验证。
 
-In this explicit mode the CLI prepares files and prints registration commands. Actual host discovery
-and model execution should be verified after registering the plugin.
+目录遵循 [配置目录参考](https://www.codebuddy.cn/docs/cli/codebuddy-dir)，可参照
+[IDE Skills](https://www.codebuddy.cn/docs/ide/Features/Skills) 与
+[自定义命令](https://www.codebuddy.cn/docs/ide/User-guide/Slash-Commands) 检查发现与调用。

package/docs/codex-setup.md

@@ -1,45 +1,34 @@
-# Using i3 Composer Agent with Codex
+# 在 Codex 使用 i3 Composer Agent
 
-For the multi-tool native skill wizard, run in your project:
+在项目中运行多工具安装向导：
 
 ```bash
 npx @givolt/i3-composer-agent --codex
 ```
 
-Choose project or global scope. Native installation uses `.agents/skills/`
-or `~/.agents/skills/`, plus the sibling `references/` directory. It installs
-the 25 skills with `i3-` IDs. This mode does not add short lifecycle
-slash commands or enable plugin hooks.
+项目范围写入 `.agents/skills/`，全局写入 `~/.agents/skills/`，并安装同级 `references/`。
+提供全部 25 个 `i3-` 技能，中文选择说明与默认中文回复在每个入口独立生效。
+同级 `i3-composer-agent/` 默认提供完整评测、Hook、脚本及依赖资料。
+进入该配套目录执行 `npm test` 可进行结构和中英文触发检查，不调用模型；详见
+[评测说明](../evals/README.md)。原生调用使用技能 ID，Hook 文件需按宿主能力单独启用。
 
-For complete plugin registration, prepare a persistent bundle explicitly:
+## 通过插件管理器安装
 
 ```bash
 npx @givolt/i3-composer-agent --prepare --codex
-```
-
-This mode copies a persistent `./i3-composer-agent/` bundle and prints these
-native registration commands. Run them to enable the plugin:
-
-```bash
 codex plugin marketplace add ./i3-composer-agent
 codex plugin add i3-composer-agent@i3-composer-agent
 ```
 
-Start a new Codex session after registration. All 25 skills use
-`i3-` IDs. In CLI/IDE, use `/skills` or `$i3-spec-driven-development`; in chat,
-explicitly request the relevant skill from i3 Composer Agent.
-
-The adapter in `.codex-plugin/plugin.json` points at the unchanged `skills/`
-layout. Shared checklists remain under `references/`, so skill-relative links
-resolve inside the complete plugin bundle.
-
-The short lifecycle commands (`/i3-spec`, `/i3-plan`, `/i3-build`, `/i3-ship`) remain
-available in hosts that load the Claude-compatible command manifest. Codex
-lifecycle-command adaptation is separate from this brand conversion. Native
-Codex `/plan` switches planning mode; it is not the plugin's planning wrapper.
+准备模式另行导出持久目录并显示注册命令，不自动注册或启用 Hook。
+已完成原生安装时无需再次准备。选择插件安装方式并注册启用后新建会话，
+通过 `/skills`、`$i3-spec-driven-development` 等技能名称，或在聊天中明确指定技能调用。
+插件适配清单指向 `skills/`；共享资料保留相对链接可解析的 `references/` 布局。
 
-Do not preload `i3-using-agent-skills/SKILL.md` into always-on context: Codex routes
-skills natively. The meta-skill can remain installed and explicitly invoked.
+Codex 原生 `/plan` 切换宿主计划模式，不是插件命令包装。
+`/i3-spec`、`/i3-plan`、`/i3-build`、`/i3-ship` 供支持兼容命令清单的宿主使用。
+Codex 短命令适配是独立的宿主能力，不影响技能中文化与品牌标识。
 
-For local source testing, replace `./i3-composer-agent` above with the absolute
-path to the branded checkout. The CLI does not modify existing plugin settings.
+Codex 已有原生技能路由，勿把元技能全文预加载为常驻上下文。
+元技能仍可安装并按需显式调用。CLI 保留已有插件设置；测试本地目录时使用绝对路径。
+文件安装、宿主发现与实际模型工作流分别验证。

package/docs/commandcode-setup.md

@@ -1,5 +1,13 @@
 # Using i3-composer-agent with Command Code
 
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
 [Command Code](https://commandcode.ai) has a native skills system. The built-in `cmd skills` command clones a GitHub repo, recursively discovers every `SKILL.md`, and installs the ones you pick.
 
 The Command Code binary is available as `cmd` (with aliases `cmdc` on Windows and `command-code`). The examples below use `cmd`.

package/docs/copilot-cli-setup.md

@@ -1,5 +1,13 @@
 # Using i3-composer-agent with GitHub Copilot CLI
 
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
 The standalone `copilot` command-line tool installs this repository as a plugin and discovers every skill in `skills/`. For Copilot inside VS Code, see [copilot-setup.md](copilot-setup.md) instead — the setup and the invocation model are different.
 
 ## Install

package/docs/copilot-setup.md

@@ -1,5 +1,13 @@
 # Using i3-composer-agent with GitHub Copilot
 
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
 This guide covers Copilot in VS Code. For the standalone `copilot` command-line tool, see [copilot-cli-setup.md](copilot-cli-setup.md).
 
 **What an install actually gives you:** the skills. Each installed skill becomes a slash command named after its frontmatter `name` — `/i3-spec-driven-development`, `/i3-test-driven-development`, and so on. `npx skills add /path/to/i3-composer-agent` and the manual copy below both install skills only. Neither of those two routes copies this repo's short lifecycle wrappers (`/i3-spec`, `/i3-plan`, `/i3-build`, `/i3-test`, `/i3-review`, `/i3-ship`) — those are Claude Code commands living in `.claude/commands/`. Use the full skill names, or add your own aliases — see [Lifecycle workflows](#lifecycle-workflows).

package/docs/cursor-setup.md

@@ -1,5 +1,13 @@
 # Using i3-composer-agent with Cursor
 
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
 How to wire [i3-composer-agent](../README.md) into **Cursor** using current, supported project context — not legacy monolith files or Kaizen-specific layouts.
 
 ---

package/docs/gemini-cli-setup.md

@@ -1,5 +1,13 @@
 # Using i3-composer-agent with Gemini CLI
 
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
 ## Setup
 
 ### Option 1: Install as Skills (Recommended)

package/docs/getting-started.md

@@ -1,5 +1,13 @@
 # Getting Started with i3-composer-agent
 
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+安装后新建宿主会话，以任务意图选择技能。规格、计划、实施、验证和发布保持原审批边界，默认中文交互。CodeBuddy/WorkBuddy 原生安装可调用 /i3-spec、/i3-plan、/i3-build、/i3-ship；Codex 使用技能名称。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
 i3-composer-agent works with any AI coding agent that accepts Markdown instructions. This guide covers the universal approach. For tool-specific setup, see the dedicated guides.
 
 Want a worked example before setting up your own project? The