@givolt/i3-composer-agent 2.1.0 → 2.2.0

package/bin/install.cjs

@@ -17,13 +17,13 @@ function exists(file) {
   catch (error) { if (error.code === 'ENOENT') return false; throw error; }
 }
 function selectAgents(values) {
-  const ids = [...new Set(values.flatMap(value => value.split(',')).map(id => aliases[id.trim()] || id.trim()).filter(Boolean))];
-  for (const id of ids) if (!registry.agents.some(agent => agent.id === id)) throw new Error(`Unknown tool: ${id}. Use --list-agents.`);
+  const ids = [...new Set(values.flatMap(value => value.split(/[,，]/)).map(id => aliases[id.trim()] || id.trim()).filter(Boolean))];
+  for (const id of ids) if (!registry.agents.some(agent => agent.id === id)) throw new Error(`未知工具：${id}。请使用 --list-agents 查看支持列表。`);
   return ids;
 }
 function globalSkillsDir(agent, home, env) {
   const config = agent.globalSkillsDir;
-  if (!config) throw new Error(`${agent.label} supports project installation only. Choose project scope or remove this tool.`);
+  if (!config) throw new Error(`${agent.label} 仅支持项目安装（project installation only），请选择项目范围或移除此工具。`);
   let base = home;
   if (config.base === 'config') base = env.XDG_CONFIG_HOME && path.isAbsolute(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : path.join(home, '.config');
   if (config.base === 'env') base = env[config.env]?.trim() || path.join(home, config.fallback);
@@ -43,7 +43,7 @@ function destination(file) {
 function checkDestination(file) {
   const source = fs.realpathSync(root);
   if (file === source || file.startsWith(source + path.sep) || source.startsWith(file + path.sep)) {
-    throw new Error('Installation destinations must be outside this package directory.');
+    throw new Error('安装目标必须位于包目录之外。');
   }
 }
 function manifestContent(plan, asset) {
@@ -52,8 +52,8 @@ function manifestContent(plan, asset) {
 }
 function planInstallation({ agents, scope, projectDir = process.cwd(), home = os.homedir(), env = process.env }) {
   agents = selectAgents(agents);
-  if (!agents.length) throw new Error('Choose at least one tool.');
-  if (!['project', 'global'].includes(scope)) throw new Error('Choose --scope project or --scope global.');
+  if (!agents.length) throw new Error('请至少选择一个工具。');
+  if (!['project', 'global'].includes(scope)) throw new Error('请选择 --scope project 或 --scope global。');
   const targets = new Map();
   for (const id of agents) {
     const agent = registry.agents.find(item => item.id === id);
@@ -70,7 +70,7 @@ function planInstallation({ agents, scope, projectDir = process.cwd(), home = os
   const assets = [];
   function addDirectory(sourceDirectory, destinationDirectory, kind) {
     if (exists(destinationDirectory) && fs.lstatSync(destinationDirectory).isSymbolicLink()) {
-      throw new Error(`Installation directory is a symlink: ${destinationDirectory}. Choose its canonical location instead.`);
+      throw new Error(`安装目录是符号链接（symlink）： ${destinationDirectory}. 请选择其真实目录。`);
     }
     for (const entry of fs.readdirSync(path.join(root, sourceDirectory)).sort()) {
       if (entry === '.DS_Store') continue;
@@ -99,17 +99,25 @@ function planInstallation({ agents, scope, projectDir = process.cwd(), home = os
       addDirectory('.claude/commands', target.commandsDirectory, 'command');
       addDirectory('agents', target.personasDirectory, 'persona');
       const docs = path.join(target.base, 'docs');
-      if (exists(docs) && fs.lstatSync(docs).isSymbolicLink()) throw new Error(`Installation directory is a symlink: ${docs}.`);
+      if (exists(docs) && fs.lstatSync(docs).isSymbolicLink()) throw new Error(`安装目录是符号链接（symlink）： ${docs}.`);
       assets.push({ source: path.join(root, 'docs/agents.md'), destination: destination(path.join(target.base, 'docs/agents.md')), kind: 'documentation' });
     }
     const licenseDirectory = path.join(target.referencesDirectory, name);
-    if (exists(licenseDirectory) && fs.lstatSync(licenseDirectory).isSymbolicLink()) throw new Error(`Installation directory is a symlink: ${licenseDirectory}.`);
+    if (exists(licenseDirectory) && fs.lstatSync(licenseDirectory).isSymbolicLink()) throw new Error(`安装目录是符号链接（symlink）： ${licenseDirectory}.`);
     assets.push({ source: path.join(root, 'LICENSE'), destination: destination(path.join(licenseDirectory, 'LICENSE')), kind: 'attribution' });
     if (owned) {
       const legacy = fs.readdirSync(path.join(root, 'skills')).filter(id => id.startsWith('i3-')).map(id => `skills/${id.slice(3)}`);
       if (target.commandsDirectory) legacy.push(...fs.readdirSync(path.join(root, '.claude/commands')).filter(file => file.startsWith('i3-') && file.endsWith('.md')).map(file => `commands/${file.slice(3)}`));
       legacy.push(`${name}-LICENSE`, `${name}-NOTICE.md`);
-      for (const relative of legacy) {
+      const current = new Set(assets.slice(start).map(asset => path.relative(target.base, asset.destination)));
+      for (const relative of previous.assets) {
+        // Only installer-owned top-level assets can be retired. Ignore malformed
+        // or escaping manifest paths rather than extending their deletion scope.
+        if (typeof relative !== 'string' || !/^(skills|commands|agents|references)\/[^/\\]+$/.test(relative)
+          || relative.includes('\0') || ['.', '..'].includes(relative.split('/')[1])) continue;
+        if (!current.has(relative)) legacy.push(relative);
+      }
+      for (const relative of new Set(legacy)) {
         const file = destination(path.join(target.base, relative));
         if (previous.assets.includes(relative) && exists(file)) assets.push({ destination: file, kind: 'legacy' });
       }
@@ -138,7 +146,7 @@ function planInstallation({ agents, scope, projectDir = process.cwd(), home = os
   return plan;
 }
 function executeInstallation(plan, { force = false } = {}) {
-  if (plan.conflicts.length && !force) throw new Error('Existing installation assets require confirmation or --force before replacement.');
+  if (plan.conflicts.length && !force) throw new Error('已有安装内容需要确认或使用 --force 才能替换。');
   const contexts = new Map();
   const createdDirectories = [];
   const committed = [];
@@ -171,7 +179,7 @@ function executeInstallation(plan, { force = false } = {}) {
         fs.writeFileSync(asset.staged, manifestContent(plan, asset));
       } else {
         fs.cpSync(asset.source, asset.staged, { recursive: true, filter: file => {
-          if (fs.lstatSync(file).isSymbolicLink()) throw new Error(`Package contains a symlink: ${file}`);
+          if (fs.lstatSync(file).isSymbolicLink()) throw new Error(`包内容中包含符号链接（symlink）： ${file}`);
           return path.basename(file) !== '.DS_Store';
         } });
         portable(asset.staged, asset, asset.source.endsWith('.md'));
@@ -184,12 +192,12 @@ function executeInstallation(plan, { force = false } = {}) {
         const unchanged = fingerprint(asset.destination) === asset.expectedFingerprint
           && fingerprint(asset.staged) === asset.expectedFingerprint;
         if (unchanged) continue;
-        if (!force) throw new Error(`Destination changed during installation: ${asset.destination}. Retry with confirmed replacement.`);
+        if (!force) throw new Error(`安装期间目标已改变： ${asset.destination}. 请重新检查并确认替换后重试。`);
       } else if (asset.mergeable) {
-        if (fingerprint(asset.destination) !== asset.observedFingerprint && !force) throw new Error(`Manifest changed during installation: ${asset.destination}. Retry with confirmed replacement.`);
+        if (fingerprint(asset.destination) !== asset.observedFingerprint && !force) throw new Error(`安装期间清单已改变： ${asset.destination}. 请重新检查并确认替换后重试。`);
       }
       // A destination may have appeared since planning; never replace it implicitly.
-      if (exists(asset.destination) && !force && !asset.mergeable) throw new Error(`Destination appeared during installation: ${asset.destination}. Retry with confirmed replacement.`);
+      if (exists(asset.destination) && !force && !asset.mergeable) throw new Error(`安装期间出现了新的目标： ${asset.destination}. 请重新检查并确认替换后重试。`);
       const change = { destination: asset.destination, written: false };
       if (exists(asset.destination)) {
         change.backup = path.join(context.backup, path.relative(asset.base, asset.destination));

package/bin/native-content.cjs

@@ -1,29 +1,38 @@
 'use strict';
-
-// Project commands are identical for both Buddy clients, including when the
-// other client is added later. Global commands use the selected profile path.
+function replaceBlock(content, name, replacement) {
+  const start = `<!-- i3:${name}:start -->`, end = `<!-- i3:${name}:end -->`;
+  if (content.split(start).length !== 2 || content.split(end).length !== 2 || content.indexOf(start) >= content.indexOf(end)) {
+    throw new Error(`i3-ship 宿主适配标记 ${name} 缺失、重复或顺序错误，请重新安装完整发行包。`);
+  }
+  const from = content.indexOf(start), to = content.indexOf(end) + end.length;
+  return content.slice(0, from) + `${start}\n${replacement}\n${end}` + content.slice(to);
+}
+// Adapt stable blocks, never their prose. Shared project commands work for
+// either Buddy client; global paths belong to the selected profile.
 function nativeContent(content, asset) {
   content = content.replaceAll('i3-composer-agent:', '').replaceAll('agent-skills:', '');
   if (!asset.buddyCommand) return content;
   const projectPersonas = '.codebuddy/agents/';
-  const userPersonas = asset.scope === 'project'
-    ? "the current host's user-level agents directory"
+  const userPersonas = asset.scope === 'project' ? '当前宿主的用户级 agents 目录'
     : `\`${asset.personasDirectory.replaceAll('\\', '/')}/\``;
   content = content.replaceAll('CLAUDE.md', 'CODEBUDDY.md')
     .replaceAll('`~/.claude/agents/`', userPersonas)
     .replaceAll('.claude/agents/', projectPersonas);
   if (!asset.source.endsWith('i3-ship.md')) return content;
-  return content
-    .replace('Spawn three subagents concurrently using the Agent tool. **Issue all three Agent tool calls in a single assistant turn so they execute in parallel** — sequential calls defeat the purpose of this command.',
-      'Use the host\'s native subagent capability to run three specialist personas concurrently. Issue all three calls together when the host supports parallel execution.')
-    .replace("In Claude Code, each call passes `subagent_type` matching the persona's `name` field:",
-      'Select the following persona names using the host\'s native subagent mechanism:')
-    .replace('In other harnesses without an Agent tool, invoke each persona\'s system prompt sequentially and treat their outputs as if returned in parallel — the merge phase still works.',
-      'If native subagents are unavailable, read each persona prompt from the installed agents directory, perform the three reviews sequentially, and retain the same merge phase.')
-    .replace(/Constraints \(from Claude Code's subagent model\):\n[\s\S]*?\n\n\*\*Persona resolution\.\*\*[^\n]*/,
-      `Constraints:\n- Each specialist reviews independently and returns a report to this session.\n- Specialists do not delegate to one another.\n- Follow the host's execution and permission limits.\n\n**Persona resolution.** Read installed persona prompts from \`${asset.scope === 'project' ? projectPersonas : asset.personasDirectory.replaceAll('\\', '/') + '/'}\`. For project installations, check ${userPersonas} for the current host's user-defined personas, and follow its native precedence rules.`)
-    .replace('The three Phase A personas run in parallel — never sequentially.',
-      'Run the three Phase A personas in parallel when native subagents are available; otherwise use the sequential fallback above.');
-}
+  const personas = asset.scope === 'project' ? projectPersonas : asset.personasDirectory.replaceAll('\\', '/') + '/';
+  content = replaceBlock(content, 'ship-dispatch', `使用宿主的原生子代理能力同时启动三个专业角色；支持并行调用时，在同一轮发出三个调用。
 
+1. **\`code-reviewer\`**：对待发布改动进行正确性、可读性、架构、安全、性能五维审查，返回标准评审报告。
+2. **\`security-auditor\`**：审查漏洞、威胁模型、OWASP Top 10、密钥、认证授权及依赖 CVE，返回标准安全报告。
+3. **\`test-engineer\`**：检查正常、边界、错误和并发路径及测试覆盖，返回标准覆盖分析。
+
+如果宿主的原生子代理不可用，读取安装后的角色提示，依次完成三个独立审查，保留各自报告；之后仍由主会话汇总。
+
+约束：
+- 角色独立审查，只返回报告，不互相委派。
+- 遵守当前宿主的执行、上下文和权限限制。
+- 角色解析：读取 \`${personas}\`。项目安装另按宿主优先级检查${userPersonas}的自定义角色。
+- 后续主会话合并重复发现，按原门槛输出 GO/NO-GO；必须提供回滚计划。严重（Critical）问题默认 NO-GO，除非用户明确接受风险。`);
+  return replaceBlock(content, 'ship-parallel-rule', '宿主支持原生子代理时，阶段 A 的三个角色并行运行；不支持时采用上文的顺序降级。');
+}
 module.exports = { nativeContent };

package/bin/tool-menu.cjs

@@ -0,0 +1,9 @@
+'use strict';
+const registry = require('./agent-targets.json');
+const commonIds = ['codebuddy', 'workbuddy', 'codex', 'claude-code', 'cursor', 'gemini-cli'];
+const orderedAgents = [...commonIds.map(id => registry.agents.find(agent => agent.id === id)),
+  ...registry.agents.filter(agent => !commonIds.includes(agent.id))];
+if (orderedAgents.some(agent => !agent) || new Set(orderedAgents.map(agent => agent.id)).size !== registry.agents.length) {
+  throw new Error('安装目录排序与工具登记不一致。');
+}
+module.exports = { orderedAgents, commonIds };

package/bin/wizard.cjs

@@ -2,6 +2,7 @@
 
 const readline = require('node:readline');
 const { registry, selectAgents } = require('./install.cjs');
+const { orderedAgents, commonIds } = require('./tool-menu.cjs');
 
 async function session(action) {
   const terminal = readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -22,46 +23,72 @@ 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] || ''));
   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;
+    const selected = new Set(selectAgents(options.agents));
+    let view = 'common', page = 0, query = '';
+    const cancelled = input => input === null || ['q', 'cancel', '取消'].includes(input.toLowerCase());
+    while (true) {
+      const matches = view === 'common' ? orderedAgents.slice(0, commonIds.length)
+        : view === 'search' ? orderedAgents.filter(agent => `${agent.id} ${agent.label}`.toLowerCase().includes(query.toLowerCase()))
+          : orderedAgents.slice(commonIds.length);
+      const pages = Math.max(1, Math.ceil(matches.length / 10));
+      page = Math.max(0, Math.min(page, pages - 1));
+      console.log(view === 'common' ? '\n选择常用工具（支持多选）：'
+        : `\n${view === 'search' ? `搜索“${query}”` : '更多工具'}：第 ${page + 1}/${pages} 页，共 ${matches.length} 项`);
+      for (const agent of view === 'common' ? matches : matches.slice(page * 10, page * 10 + 10)) {
+        console.log(`${orderedAgents.indexOf(agent) + 1}. ${agent.label} [${agent.id}]${selected.has(agent.id) ? ' ✓ 已选' : ''}${agent.globalSkillsDir ? '' : '（仅项目安装）'}`);
+      }
+      if (view === 'common') console.log('7. 更多（m）');
+      else console.log('n 下一页 · p 上一页 · b 返回常用工具');
+      console.log(`已选：${[...selected].join(', ') || '无'}；/关键词 搜索全部 ${registry.agents.length} 个工具；回车或完成确认；-编号/ID 移除选择。`);
+      const input = await ask('输入编号/ID，可用逗号多选（q/取消退出）： ');
+      if (cancelled(input)) return null;
+      if (['', 'done', '完成'].includes(input.toLowerCase())) {
+        if (selected.size) break;
+        console.log('请至少选择一个工具。'); continue;
+      }
+      if (['m', 'more', '更多'].includes(input.toLowerCase()) || (view === 'common' && input === '7')) { view = 'more'; page = 0; continue; }
+      if (['b', 'back', '返回'].includes(input.toLowerCase())) { view = 'common'; page = 0; continue; }
+      if (view !== 'common' && ['n', '下一页'].includes(input.toLowerCase())) { page = Math.min(pages - 1, page + 1); continue; }
+      if (view !== 'common' && ['p', '上一页'].includes(input.toLowerCase())) { page = Math.max(0, page - 1); continue; }
+      if (input.startsWith('/')) { view = 'search'; query = input.slice(1).trim(); page = 0; continue; }
       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.'); }
+        const values = ['all', '全部'].includes(input.toLowerCase()) ? orderedAgents.map(agent => agent.id) : input.split(/[,，]/);
+        const additions = [], removals = [];
+        for (const value of values) {
+          const remove = value.trim().startsWith('-'), raw = value.trim().replace(/^-/, '');
+          const id = /^\d+$/.test(raw) ? orderedAgents[Number(raw) - 1]?.id || raw : raw;
+          (remove ? removals : additions).push(...selectAgents([id]));
+        }
+        for (const id of additions) selected.add(id);
+        for (const id of removals) selected.delete(id);
       } catch (error) { console.log(error.message); }
     }
+    const agents = [...selected];
+    if (agents.includes('workbuddy')) console.log('WorkBuddy 桌面版建议全局安装，以便技能列表和输入补全发现 Skills；项目安装仍支持命令，技能列表可能不显示。');
     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}`);
   }
-  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 需按宿主方式注册和启用。');
   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