@fitlab-ai/agent-infra 0.6.5 → 0.7.1

package/lib/update.ts

@@ -3,6 +3,8 @@ import path from 'node:path';
 import { info, ok, err } from './log.ts';
 import { resolveTemplateDir } from './paths.ts';
 import { renderFile, copySkillDir, KNOWN_PLATFORMS } from './render.ts';
+import { isPathOwnedByDisabledTUI, resolveEnabledTUIs } from './builtin-tuis.ts';
+import type { BuiltinTUIId } from './builtin-tuis.ts';
 
 type FileRegistry = {
   managed: string[];
@@ -15,14 +17,19 @@ type UpdateConfig = {
   org: string;
   language: string;
   platform?: { type?: string };
+  requiresPullRequest?: boolean;
   sandbox?: Record<string, unknown>;
+  task?: { shortIdLength: number };
   labels?: Record<string, unknown>;
   files?: Partial<FileRegistry>;
+  tuis?: unknown;
 };
 
 type Defaults = {
   platform: { type: string };
+  requiresPullRequest: boolean;
   sandbox: Record<string, unknown>;
+  task: { shortIdLength: number };
   labels: Record<string, unknown>;
   files: FileRegistry;
 };
@@ -43,7 +50,7 @@ function isPathOwnedByOtherPlatform(relativePath: string, platformType: string):
   return candidate !== platformType;
 }
 
-function syncFileRegistry(config: UpdateConfig, platformType: string) {
+function syncFileRegistry(config: UpdateConfig, platformType: string, enabledTUIs: Set<BuiltinTUIId>) {
   config.files ||= {};
   const before = JSON.stringify({
     files: {
@@ -65,6 +72,7 @@ function syncFileRegistry(config: UpdateConfig, platformType: string) {
 
   for (const entry of defaults.files.managed) {
     if (isPathOwnedByOtherPlatform(entry, platformType)) continue;
+    if (isPathOwnedByDisabledTUI(entry, enabledTUIs)) continue;
     if (!allExisting.includes(entry)) {
       config.files.managed.push(entry);
       added.managed.push(entry);
@@ -72,6 +80,7 @@ function syncFileRegistry(config: UpdateConfig, platformType: string) {
   }
   for (const entry of defaults.files.merged) {
     if (isPathOwnedByOtherPlatform(entry, platformType)) continue;
+    if (isPathOwnedByDisabledTUI(entry, enabledTUIs)) continue;
     if (!allExisting.includes(entry)) {
       config.files.merged.push(entry);
       added.merged.push(entry);
@@ -116,6 +125,7 @@ async function cmdUpdate(): Promise<void> {
   const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8')) as UpdateConfig;
   const { project, org, language } = config;
   const platformType = config.platform?.type || defaults.platform.type;
+  const enabledTUIs = resolveEnabledTUIs(config.tuis);
   const replacements = { project, org };
 
   info(`Updating seed files for: ${project}`);
@@ -148,36 +158,44 @@ async function cmdUpdate(): Promise<void> {
     // Ignore missing legacy script from pre-ESM installs.
   }
 
-  // update Claude command
-  renderFile(
-    path.join(templateDir, '.claude', 'commands', claudeSrc),
-    path.join('.claude', 'commands', 'update-agent-infra.md'),
-    replacements
-  );
-  ok('Updated .claude/commands/update-agent-infra.md');
+  // update Claude command (only if enabled)
+  if (enabledTUIs.has('claude-code')) {
+    renderFile(
+      path.join(templateDir, '.claude', 'commands', claudeSrc),
+      path.join('.claude', 'commands', 'update-agent-infra.md'),
+      replacements
+    );
+    ok('Updated .claude/commands/update-agent-infra.md');
+  }
 
-  // update Gemini command
-  renderFile(
-    path.join(templateDir, '.gemini', 'commands', '_project_', geminiSrc),
-    path.join('.gemini', 'commands', project, 'update-agent-infra.toml'),
-    replacements
-  );
-  ok(`Updated .gemini/commands/${project}/update-agent-infra.toml`);
+  // update Gemini command (only if enabled)
+  if (enabledTUIs.has('gemini-cli')) {
+    renderFile(
+      path.join(templateDir, '.gemini', 'commands', '_project_', geminiSrc),
+      path.join('.gemini', 'commands', project, 'update-agent-infra.toml'),
+      replacements
+    );
+    ok(`Updated .gemini/commands/${project}/update-agent-infra.toml`);
+  }
 
-  // update OpenCode command
-  renderFile(
-    path.join(templateDir, '.opencode', 'commands', opencodeSrc),
-    path.join('.opencode', 'commands', 'update-agent-infra.md'),
-    replacements
-  );
-  ok('Updated .opencode/commands/update-agent-infra.md');
+  // update OpenCode command (only if enabled)
+  if (enabledTUIs.has('opencode')) {
+    renderFile(
+      path.join(templateDir, '.opencode', 'commands', opencodeSrc),
+      path.join('.opencode', 'commands', 'update-agent-infra.md'),
+      replacements
+    );
+    ok('Updated .opencode/commands/update-agent-infra.md');
+  }
 
   // sync file registry
-  const { added, changed } = syncFileRegistry(config, platformType);
+  const { added, changed } = syncFileRegistry(config, platformType, enabledTUIs);
   const hasNewEntries = added.managed.length > 0 || added.merged.length > 0;
   const platformAdded = !config.platform;
   const sandboxAdded = !config.sandbox;
+  const taskAdded = !config.task;
   const labelsAdded = !config.labels;
+  const requiresPullRequestAdded = config.requiresPullRequest === undefined;
   let configChanged = changed;
 
   if (platformAdded) {
@@ -190,11 +208,21 @@ async function cmdUpdate(): Promise<void> {
     configChanged = true;
   }
 
+  if (taskAdded) {
+    config.task = structuredClone(defaults.task);
+    configChanged = true;
+  }
+
   if (labelsAdded) {
     config.labels = structuredClone(defaults.labels);
     configChanged = true;
   }
 
+  if (requiresPullRequestAdded) {
+    config.requiresPullRequest = defaults.requiresPullRequest;
+    configChanged = true;
+  }
+
   if (configChanged) {
     console.log('');
     if (hasNewEntries) {
@@ -205,28 +233,40 @@ async function cmdUpdate(): Promise<void> {
       for (const entry of added.merged) {
         ok(`  merged: ${entry}`);
       }
-    } else if (platformAdded || sandboxAdded || labelsAdded) {
+    } else if (platformAdded || sandboxAdded || taskAdded || labelsAdded || requiresPullRequestAdded) {
       if (platformAdded) {
         info(`Default platform config added to ${CONFIG_PATH}.`);
       }
       if (sandboxAdded) {
         info(`Default sandbox config added to ${CONFIG_PATH}.`);
       }
+      if (taskAdded) {
+        info(`Default task.shortIdLength=${defaults.task.shortIdLength} added to ${CONFIG_PATH}.`);
+      }
       if (labelsAdded) {
         info(`Default labels.in config added to ${CONFIG_PATH}.`);
       }
+      if (requiresPullRequestAdded) {
+        info(`Default requiresPullRequest=${defaults.requiresPullRequest} added to ${CONFIG_PATH}.`);
+      }
     } else {
       info(`File registry changed in ${CONFIG_PATH}.`);
     }
     if (hasNewEntries && sandboxAdded) {
       info(`Default sandbox config added to ${CONFIG_PATH}.`);
     }
+    if (hasNewEntries && taskAdded) {
+      info(`Default task.shortIdLength=${defaults.task.shortIdLength} added to ${CONFIG_PATH}.`);
+    }
     if (hasNewEntries && labelsAdded) {
       info(`Default labels.in config added to ${CONFIG_PATH}.`);
     }
     if (hasNewEntries && platformAdded) {
       info(`Default platform config added to ${CONFIG_PATH}.`);
     }
+    if (hasNewEntries && requiresPullRequestAdded) {
+      info(`Default requiresPullRequest=${defaults.requiresPullRequest} added to ${CONFIG_PATH}.`);
+    }
     fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', 'utf8');
     ok(`Updated ${CONFIG_PATH}`);
   }
@@ -235,12 +275,27 @@ async function cmdUpdate(): Promise<void> {
   console.log('');
   ok('Seed files updated successfully!');
   console.log('');
-  console.log('  Next step: run the full update in your AI TUI:');
-  console.log('');
-  console.log('    Claude Code / OpenCode:  /update-agent-infra');
-  console.log(`    Gemini CLI:              /${project}:update-agent-infra`);
-  console.log('    Codex CLI:               $update-agent-infra');
-  console.log('');
+  if (enabledTUIs.size === 0) {
+    console.log('  No built-in TUI enabled (tuis: []).');
+    console.log(`  Configure "customTUIs" in ${CONFIG_PATH} if needed.`);
+    console.log('');
+  } else {
+    console.log('  Next step: run the full update in your AI TUI:');
+    console.log('');
+    const claudeOrOpencode: string[] = [];
+    if (enabledTUIs.has('claude-code')) claudeOrOpencode.push('Claude Code');
+    if (enabledTUIs.has('opencode')) claudeOrOpencode.push('OpenCode');
+    if (claudeOrOpencode.length > 0) {
+      console.log(`    ${claudeOrOpencode.join(' / ')}:  /update-agent-infra`);
+    }
+    if (enabledTUIs.has('gemini-cli')) {
+      console.log(`    Gemini CLI:              /${project}:update-agent-infra`);
+    }
+    if (enabledTUIs.has('codex')) {
+      console.log('    Codex CLI:               $update-agent-infra');
+    }
+    console.log('');
+  }
 }
 
 export { cmdUpdate };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.6.5",
+  "version": "0.7.1",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",

package/templates/.agents/QUICKSTART.en.md

@@ -164,7 +164,7 @@ The receiving AI should read this document first to get up to speed.
 
 ### 1. One AI Per Phase
 
-Don't have multiple AIs working on the same files simultaneously. Follow the sequential workflow: analyze, design, implement, review, fix, commit.
+Don't have multiple AIs working on the same files simultaneously. Follow the sequential workflow: analysis → analysis-review → design → design-review → code → code-review → commit (when any review finds issues, re-run the matching upstream stage).
 
 ### 2. Always Create Handoff Documents
 

package/templates/.agents/QUICKSTART.zh-CN.md

@@ -164,7 +164,7 @@ cp .agents/templates/handoff.md .agents/workspace/active/handoff-task-001-phase2
 
 ### 1. 每个阶段一个 AI
 
-不要让多个 AI 同时处理相同的文件。遵循顺序工作流：分析、设计、实现、审查、修复、提交。
+不要让多个 AI 同时处理相同的文件。遵循顺序工作流：分析 → 分析审查 → 设计 → 设计审查 → 编码 → 代码审查 → 提交（任一审查发现问题时，回到同名上游阶段重跑）。
 
 ### 2. 始终创建交接文档
 

package/templates/.agents/README.en.md

@@ -210,6 +210,38 @@ The `files` field in `.agents/.airc.json` groups project files into three catego
 
 `ejected` entries support literal paths or globs, using the same matching rules as `merged`.
 
+## Built-in TUI Selection
+
+Use the top-level `.agents/.airc.json` `tuis` array to pick which built-in TUIs (`claude-code`, `codex`, `gemini-cli`, `opencode`) agent-infra should install command files for and keep in sync.
+
+| Value | Meaning |
+|-------|---------|
+| `tuis` missing or `null` | All four built-in TUIs are enabled (backward-compatible default for legacy `.airc.json` predating this field). |
+| `tuis: []` | No built-in TUI is managed. Use this when the project only relies on `customTUIs` and does not need any built-in command files installed. |
+| `tuis: [<subset>]` | Only the listed TUIs are managed. Unknown ids are ignored. |
+
+`ai init` includes an interactive multi-select for this field:
+
+- Press Enter to accept the default (all built-in TUIs enabled).
+- Type comma-separated numbers or ids (e.g. `1,3` or `claude-code,opencode`) to keep a subset.
+- Type `none` to explicitly disable every built-in TUI (typically combined with a `customTUIs` entry added later).
+- Invalid input (duplicate, out-of-range, unknown id, whitespace-only) aborts init with a non-zero exit code.
+
+### Side effects of disabling a TUI
+
+When you disable a built-in TUI (either via `ai init` or by hand-editing `.airc.json`), the next `ai update` / `update-agent-infra` will:
+
+- skip seed command writes for that TUI (e.g. `.gemini/commands/<project>/update-agent-infra.toml`);
+- skip the TUI's owned default entries when backfilling `files.managed` / `files.merged`;
+- **clean up existing files** under the TUI's owned path prefix (`.claude/`, `.codex/`, `.gemini/`, `.opencode/`) — these are listed in `report.managed.removed`, mirroring the cleanup behavior when switching `platform`.
+
+To opt a specific file out of this cleanup, list it in `files.ejected`; ejected entries owned by disabled TUIs are preserved as-is and are not re-created by sync.
+
+### Relation to other config fields
+
+- `tuis` controls **which TUI command files agent-infra writes and maintains**. It is independent from `sandbox.tools`, which controls **which CLIs the sandbox image installs**. Toggling one does not affect the other; the README for `sandbox.tools` lives in the Sandbox section.
+- `tuis` is independent from `customTUIs` (see below). CustomTUI command files are not removed when you disable a built-in TUI, even if the customTUI's `dir` falls under that TUI's owned prefix (e.g. a customTUI configured with `dir: ".codex/commands"` is preserved when `codex` is disabled).
+
 ## Custom TUI Configuration
 
 Use the top-level `.agents/.airc.json` `customTUIs` array when your team uses an AI TUI that is not one of the built-in command targets. This config lets agent-infra show the correct next-step commands and generate command files for project custom skills by learning from an existing command in the custom TUI directory.
@@ -224,8 +256,8 @@ Supported `invoke` placeholders:
 
 | Placeholder | Replaced with | Example |
 |-------------|---------------|---------|
-| `${skillName}` | The skill command name, such as `review-task` or `commit`. | `<your-cli> ${skillName}` -> `<your-cli> review-task` |
-| `${projectName}` | The `.airc.json` `project` value. Use this for namespaced commands. | `/${projectName}:${skillName}` -> `/agent-infra:review-task` |
+| `${skillName}` | The skill command name, such as `review-code` or `commit`. | `<your-cli> ${skillName}` -> `<your-cli> review-code` |
+| `${projectName}` | The `.airc.json` `project` value. Use this for namespaced commands. | `/${projectName}:${skillName}` -> `/agent-infra:review-code` |
 
 Non-namespaced custom TUI:
 
@@ -258,6 +290,83 @@ Namespaced custom TUI:
 
 `customTUIs` should contain one entry per custom TUI. To let `update-agent-infra` generate command files for custom skills, keep at least one existing command file in `dir` that references a built-in skill path such as `.agents/skills/analyze-task/SKILL.md`; agent-infra uses that file as the format reference.
 
+## Sandbox Custom Tools
+
+`customTUIs` (above) generates slash-command files but does not change the sandbox image. To install a non-npm TUI (pip / cargo / curl-based / pre-built binary) into the sandbox image and live-mount its credentials, declare it under `sandbox.customTools` in `.agents/.airc.json`. Built-in tools (`claude-code`, `codex`, `opencode`, `gemini-cli`) keep working unchanged.
+
+### Required fields
+
+| Field | Meaning |
+|-------|---------|
+| `id` | Lowercase id matching `^[a-z0-9][a-z0-9-]*$`. Referenced from `sandbox.tools`. Must not collide with a built-in id. |
+| `install` | Install descriptor. `{ "type": "npm", "cmd": "<npm package spec>" }` runs `npm install -g <cmd>`. `{ "type": "shell", "cmd": "<shell>" }` runs the shell command(s) as `devuser` during image build. `cmd` must be non-empty. |
+
+Minimal entry — the contract for getting a tool into the image is just these two fields:
+
+```json
+{
+  "sandbox": {
+    "tools": ["my-shell-tool"],
+    "customTools": [
+      {
+        "id": "my-shell-tool",
+        "install": { "type": "shell", "cmd": "curl -fsSL https://example.com/install.sh | bash" }
+      }
+    ]
+  }
+}
+```
+
+### Optional integration fields
+
+Add only the fields your tool actually needs. Omit them and the loader fills sensible defaults; provide them and the loader uses your value. Provide an explicit empty string and the loader rejects it (preventing silent install-verification bypass).
+
+| Field | Default when omitted | When to provide |
+|-------|---------------------|-----------------|
+| `name` | `id` | A friendlier display name in sandbox reports / hints. |
+| `containerMount` | `/home/devuser/.<id>` | Your tool stores its config / state somewhere other than `~/.<id>`. Must be an absolute path. |
+| `versionCmd` | `which <id>` | The installed binary name differs from `id` (e.g. id `anthropic-claude`, binary `claude`); set `"claude --version"` so sandbox-create can verify the install. |
+| `setupHint` | `Run \`<id>\` inside the container to set up.` | The setup story is non-obvious and worth a one-liner. |
+| `envVars` | (none) | Your tool reads config from a path the env points to (e.g. `XDG_CONFIG_HOME`-style or a custom `*_CONFIG` env). Shape: `Record<string, string>`. |
+| `hostPreSeedFiles` / `hostPreSeedDirs` | (none) | Seed the tool's sandbox dir from host files / directories on first launch. |
+| `pathRewriteFiles` | (none) | Seeded files contain absolute host paths that need rewriting to container paths. |
+| `hostLiveMounts` | (none) | Share host credentials live (e.g. OAuth tokens) with the container. Read-write. |
+| `postSetupCmds` | (none) | Run commands inside the container after first setup (e.g. symlinks). |
+
+> **`sandboxBase` is not user-configurable.** The loader always assigns `~/.agent-infra/sandboxes/<id>` so `ai sandbox rm` / `prune` can find tool state. Any `sandboxBase` value in `customTools` entries is silently ignored.
+
+Real-world example — `anthropic-claude` as a user-defined id with binary name `claude` and host credential live-mount:
+
+```json
+{
+  "sandbox": {
+    "tools": ["claude-code", "anthropic-claude"],
+    "customTools": [
+      {
+        "id": "anthropic-claude",
+        "install": { "type": "npm", "cmd": "@anthropic-ai/claude-code@stable" },
+        "versionCmd": "claude --version",
+        "hostLiveMounts": [
+          { "hostPath": "~/.claude/.credentials.json", "containerSubpath": ".credentials.json" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Trust boundary and execution context
+
+- `install.cmd` runs as user `devuser` (non-root) during `docker build`. It can write to the container's filesystem but cannot escape to the host. The trust model is the same as for the `sandbox.dockerfile` escape hatch — you own the `.airc.json` in your repo, so you own what runs at build time.
+- Because the build runs as `devuser`, shell installs cannot `sudo` / `apt-get`. Available options for non-npm distributions:
+  - User-scope installers landing in `~/.local/bin`, `~/.cargo/bin`, `~/.npm-global/bin` (e.g. `pipx`, `cargo install`, `curl … | bash` with `INSTALL_DIR=$HOME/.local/bin`).
+  - When you genuinely need root or system packages, fall back to the existing `sandbox.dockerfile` field and own the full Dockerfile.
+- Changing `install.cmd` (or any field that participates in the image signature) triggers exactly one image rebuild on the next `ai sandbox` invocation.
+
+### Interaction with `sandbox.dockerfile`
+
+When you set `sandbox.dockerfile` to point at your own Dockerfile, agent-infra still passes both `AI_TOOL_PACKAGES` (space-separated npm package specs) and `AI_TOOLS_SHELL_INSTALL_B64` (base64-encoded shell install script) as `--build-arg`. Your custom Dockerfile decides whether to consume them; if it does not declare the matching `ARG`, the shell installs for `customTools` are silently skipped — taking over the Dockerfile means taking over the install path.
+
 ## Skill Authoring Conventions
 
 When writing or updating `.agents/skills/*/SKILL.md` files and their templates, keep step numbering consistent:

package/templates/.agents/README.zh-CN.md

@@ -210,6 +210,38 @@ args: "<task-id>"   # 可选
 
 `ejected` 条目支持字面路径或 glob，匹配规则与 `merged` 相同。
 
+## 内建 TUI 选择
+
+`.agents/.airc.json` 顶层 `tuis` 数组用于决定 agent-infra 应当为哪些内建 TUI（`claude-code`、`codex`、`gemini-cli`、`opencode`）安装并维护命令文件。
+
+| 取值 | 含义 |
+|------|------|
+| `tuis` 缺失或为 `null` | 启用全部四个内建 TUI（向后兼容默认，适用于本字段引入之前的 `.airc.json`） |
+| `tuis: []` | 不维护任何内建 TUI。适用于只依赖 `customTUIs`、不需要安装任何内建命令文件的项目 |
+| `tuis: [<子集>]` | 仅维护列出的 TUI；未知 id 会被忽略 |
+
+`ai init` 会通过交互式多选询问该字段：
+
+- 直接回车 = 接受默认值（全部内建 TUI 启用）。
+- 输入逗号分隔的编号或 id（如 `1,3` 或 `claude-code,opencode`）= 只保留子集。
+- 输入 `none` = 明确不启用任何内建 TUI（通常配合后续在 `customTUIs` 添加条目使用）。
+- 非法输入（重复、超界、未知 id、纯空白）会让 init 以非零退出码终止。
+
+### 取消某个 TUI 的副作用
+
+通过 `ai init` 或手工编辑 `.airc.json` 取消某个内建 TUI 后，下一次 `ai update` / `update-agent-infra` 会：
+
+- 跳过该 TUI 的 seed 命令文件写入（例如 `.gemini/commands/<project>/update-agent-infra.toml`）；
+- 在回填 `files.managed` / `files.merged` 时跳过该 TUI owned 的默认条目；
+- **物理清理**该 TUI owned 路径前缀（`.claude/`、`.codex/`、`.gemini/`、`.opencode/`）下的已有文件——清理列表会出现在 `report.managed.removed`，与切换 `platform` 时的清理行为一致。
+
+若希望保留某个具体文件，把它加入 `files.ejected`：被 ejected 的、属于已取消 TUI 的条目会保持原状，sync 不会重新创建也不会删除。
+
+### 与其他配置字段的关系
+
+- `tuis` 控制 **agent-infra 写入与维护哪些 TUI 的命令文件**，与 `sandbox.tools`（控制**沙箱镜像里安装哪些 CLI**）相互独立。两者互不影响；`sandbox.tools` 的说明见 Sandbox 一节。
+- `tuis` 与 `customTUIs`（见下）相互独立。取消某个内建 TUI 时 customTUI 命令文件不会被清理，即便 customTUI 的 `dir` 落在该 TUI 的 owned 前缀下（例如 `dir: ".codex/commands"` 的 customTUI 在 `codex` 被取消时仍会保留）。
+
 ## 自定义 TUI 配置
 
 当团队使用的 AI TUI 不属于内置命令目标时，可以在 `.agents/.airc.json` 顶层配置 `customTUIs` 数组。该配置用于让 agent-infra 输出正确的下一步命令，并通过学习自定义 TUI 目录中的既有命令文件，为项目自定义 skill 生成同格式命令。
@@ -224,8 +256,8 @@ args: "<task-id>"   # 可选
 
 | 占位符 | 替换为 | 示例 |
 |--------|--------|------|
-| `${skillName}` | skill 命令名，例如 `review-task` 或 `commit`。 | `<your-cli> ${skillName}` -> `<your-cli> review-task` |
-| `${projectName}` | `.airc.json` 中的 `project` 值，适用于带命名空间的命令。 | `/${projectName}:${skillName}` -> `/agent-infra:review-task` |
+| `${skillName}` | skill 命令名，例如 `review-code` 或 `commit`。 | `<your-cli> ${skillName}` -> `<your-cli> review-code` |
+| `${projectName}` | `.airc.json` 中的 `project` 值，适用于带命名空间的命令。 | `/${projectName}:${skillName}` -> `/agent-infra:review-code` |
 
 不带命名空间的自定义 TUI：
 
@@ -258,6 +290,83 @@ args: "<task-id>"   # 可选
 
 `customTUIs` 每个条目对应一个自定义 TUI。若希望 `update-agent-infra` 为自定义 skill 生成命令文件，请在 `dir` 中保留至少一个引用内置 skill 路径的既有命令文件，例如 `.agents/skills/analyze-task/SKILL.md`；agent-infra 会以该文件作为格式参考。
 
+## 沙箱自定义工具（Sandbox Custom Tools）
+
+上文 `customTUIs` 只负责生成 slash-command 文件，**不影响沙箱镜像**。如果要把一个非 npm 分发的 TUI（pip / cargo / curl 脚本 / 裸二进制）装进沙箱镜像、并 live-mount 它的凭证目录，需要在 `.agents/.airc.json` 的 `sandbox.customTools` 中声明。内建的四个工具（`claude-code` / `codex` / `opencode` / `gemini-cli`）行为保持不变。
+
+### 必填字段
+
+| 字段 | 含义 |
+|------|------|
+| `id` | 小写 id，匹配 `^[a-z0-9][a-z0-9-]*$`；由 `sandbox.tools` 引用；不可与内建 id 冲突。 |
+| `install` | 安装描述符。`{ "type": "npm", "cmd": "<npm 包规范>" }` 执行 `npm install -g <cmd>`；`{ "type": "shell", "cmd": "<shell>" }` 在镜像构建阶段以 `devuser` 执行 shell。`cmd` 必须非空。 |
+
+最小入口——把一个工具装进镜像所需的契约只有这两个字段：
+
+```json
+{
+  "sandbox": {
+    "tools": ["my-shell-tool"],
+    "customTools": [
+      {
+        "id": "my-shell-tool",
+        "install": { "type": "shell", "cmd": "curl -fsSL https://example.com/install.sh | bash" }
+      }
+    ]
+  }
+}
+```
+
+### 可选集成字段
+
+只在你的工具真正需要时才加。**省略**则 loader 用合理默认值；**显式提供**则用你给的值；**显式给空串**会被拒绝（防止安装验证被绕过）。
+
+| 字段 | 省略时的默认值 | 什么时候应该提供 |
+|------|---------------|----------------|
+| `name` | `id` | 想在沙箱报告 / 提示里显示更友好的名称。 |
+| `containerMount` | `/home/devuser/.<id>` | 工具的配置 / 状态目录不在 `~/.<id>` 而在别处。必须是绝对路径。 |
+| `versionCmd` | `which <id>` | 安装后的可执行文件名与 `id` 不同（例如 id 是 `anthropic-claude`，二进制名是 `claude`）；填 `"claude --version"` 让 sandbox-create 能验证安装。 |
+| `setupHint` | `Run \`<id>\` inside the container to set up.` | setup 流程不一目了然，值得用一行说明。 |
+| `envVars` | （无） | 工具通过环境变量找配置（如 `XDG_CONFIG_HOME` 风格或自定义 `*_CONFIG` 变量）。形状：`Record<string, string>`。 |
+| `hostPreSeedFiles` / `hostPreSeedDirs` | （无） | 首次启动时从宿主复制文件 / 目录到工具沙箱配置目录。 |
+| `pathRewriteFiles` | （无） | seed 进来的文件里有宿主绝对路径，需要改写为容器路径。 |
+| `hostLiveMounts` | （无） | 把宿主凭证（如 OAuth token）实时挂进容器，读写共享。 |
+| `postSetupCmds` | （无） | 首次安装完成后在容器内执行命令（如建符号链接）。 |
+
+> **`sandboxBase` 不由用户配置。** loader 永远使用 `~/.agent-infra/sandboxes/<id>`，这样 `ai sandbox rm` / `prune` 才能找到工具状态目录。`customTools` 条目里写的任何 `sandboxBase` 都会被静默忽略。
+
+实际场景示例——`anthropic-claude` 作为用户自定义 id，二进制名是 `claude`，并把宿主凭证 live-mount 进来：
+
+```json
+{
+  "sandbox": {
+    "tools": ["claude-code", "anthropic-claude"],
+    "customTools": [
+      {
+        "id": "anthropic-claude",
+        "install": { "type": "npm", "cmd": "@anthropic-ai/claude-code@stable" },
+        "versionCmd": "claude --version",
+        "hostLiveMounts": [
+          { "hostPath": "~/.claude/.credentials.json", "containerSubpath": ".credentials.json" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### 信任边界与执行身份
+
+- `install.cmd` 在 `docker build` 阶段以 `devuser`（非 root）身份执行，只能写容器内文件系统，不能逃逸到宿主。信任模型与现有 `sandbox.dockerfile` 一致：你是 `.airc.json` 的作者，本次构建做什么由你负责。
+- 因为不是 root，shell 安装无法 `sudo` / `apt-get`。非 npm 分发的几条可用路径：
+  - 用户态安装器，落到 `~/.local/bin`、`~/.cargo/bin`、`~/.npm-global/bin`（如 `pipx`、`cargo install`、`curl … | bash` 配合 `INSTALL_DIR=$HOME/.local/bin`）。
+  - 确实需要 root / 系统包时，仍走原有 `sandbox.dockerfile` 字段，接管整个 Dockerfile。
+- 修改 `install.cmd` 或任何参与镜像签名的字段，下次 `ai sandbox` 命令会触发一次镜像重建。
+
+### 与 `sandbox.dockerfile` 的交互
+
+当 `sandbox.dockerfile` 指向自定义 Dockerfile 时，agent-infra 仍会把 `AI_TOOL_PACKAGES`（空格分隔的 npm 包规范）和 `AI_TOOLS_SHELL_INSTALL_B64`（base64 编码的 shell 安装脚本）作为 `--build-arg` 传入。你的自定义 Dockerfile 若未声明对应 `ARG`，shell 安装路径会被 docker build 静默忽略——这是接管 Dockerfile 后的应有代价。
+
 ## Skill 编写规范
 
 编写或维护 `.agents/skills/*/SKILL.md` 及其模板时，步骤编号遵循以下规则：

package/templates/.agents/rules/create-issue.en.md

@@ -2,4 +2,4 @@
 
 This code platform does not provide an Issue creation rule.
 
-`create-task` skips the cascade Issue creation step on this platform; the local `task.md` remains a valid artifact. If you later want to bind the task to an Issue, manually write `issue_number` into `task.md` and the subsequent skills (`commit` / `refine-task` / `complete-task`, etc.) will pick up Issue metadata syncing through the existing cascade rules.
+`create-task` skips the cascade Issue creation step on this platform; the local `task.md` remains a valid artifact. If you later want to bind the task to an Issue, manually write `issue_number` into `task.md` and the subsequent skills (`commit` / `code-task` / `complete-task`, etc.) will pick up Issue metadata syncing through the existing cascade rules.

package/templates/.agents/rules/create-issue.github.en.md

@@ -5,7 +5,7 @@ After `create-task` writes the local `task.md`, follow this rule to cascade Issu
 ## Boundary
 
 - Issue title and body must come from `task.md` only
-- Do not read `analysis.md`, `plan.md`, `implementation.md`, or any review artifact
+- Do not read `analysis.md`, `review-analysis.md`, `plan.md`, `review-plan.md`, `code.md`, or any review-code artifact
 - Persistent outputs are limited to the remote Issue and the `issue_number` written back to `task.md`
 - If Issue creation fails, do not roll back `task.md`; the current task remains valid for the workflow, and the user can later manually fill `issue_number` so other skills' cascade sync takes over
 

package/templates/.agents/rules/create-issue.github.zh-CN.md

@@ -5,7 +5,7 @@
 ## 行为边界
 
 - Issue 标题和正文只能来自 `task.md`
-- 不读取 `analysis.md`、`plan.md`、`implementation.md` 或审查产物
+- 不读取 `analysis.md`、`review-analysis.md`、`plan.md`、`review-plan.md`、`code.md` 或代码审查产物
 - 持久产物只有：远端 Issue + `task.md` 中回写的 `issue_number`
 - Issue 创建失败时不回滚 `task.md`；当前 task 仍可继续后续工作流，未来可由用户手动写入 `issue_number`，让其它技能的级联同步接管
 

package/templates/.agents/rules/create-issue.zh-CN.md

@@ -2,4 +2,4 @@
 
 当前代码平台未提供 Issue 创建规则。
 
-`create-task` 在本平台上会跳过级联创建 Issue 步骤；本地 `task.md` 仍然是有效产物。如果将来需要把任务绑定到一个 Issue，可手动在 `task.md` 中写入 `issue_number`，后续技能（`commit` / `refine-task` / `complete-task` 等）会按既有的级联同步规则自动接管 Issue 元数据更新。
+`create-task` 在本平台上会跳过级联创建 Issue 步骤；本地 `task.md` 仍然是有效产物。如果将来需要把任务绑定到一个 Issue，可手动在 `task.md` 中写入 `issue_number`，后续技能（`commit` / `code-task` / `complete-task` 等）会按既有的级联同步规则自动接管 Issue 元数据更新。

package/templates/.agents/rules/issue-sync.github.en.md

@@ -123,7 +123,7 @@ When a skill creates or imports an Issue, automatically add the current executor
 
 ## `in:` Label Sync
 
-> **Trigger timing**: run `in:` label sync only after code is committed (the `commit` skill). Do not run it during `implement-task` or `refine-task`. During `create-pr`, only copy the labels from the Issue to the PR without recomputing them.
+> **Trigger timing**: run `in:` label sync only after code is committed (the `commit` skill). Do not run it during `code-task`. During `create-pr`, only copy the labels from the Issue to the PR without recomputing them.
 
 Read the `labels.in` mapping from `.agents/.airc.json`.
 
@@ -262,7 +262,7 @@ task comment sync always runs and is never downgraded.
 
 ## Backfill Rules (run before `/complete-task` archives)
 
-- Scan `task.md`, `analysis*.md`, `plan*.md`, `implementation*.md`, `review*.md`, and `refinement*.md` in the task directory
+- Scan `task.md`, `analysis*.md`, `review-analysis*.md`, `plan*.md`, `review-plan*.md`, `code*.md`, and `review-code*.md` in the task directory
 - Check whether each `{file-stem}` was already published by its hidden marker; publish only missing artifacts
 - Backfill only appends missing comments and never deletes or reorders existing comments
 - Resolve `{agent}` for backfilled comments in this order:
@@ -281,10 +281,11 @@ Title mapping:
 
 - `task` -> `Task File`
 - `analysis` / `analysis-r{N}` -> `Requirements Analysis` / `Requirements Analysis (Round {N})`
+- `review-analysis` / `review-analysis-r{N}` -> `Requirements Analysis Review (Round 1)` / `Requirements Analysis Review (Round {N})`
 - `plan` / `plan-r{N}` -> `Technical Plan` / `Technical Plan (Round {N})`
-- `implementation` / `implementation-r{N}` -> `Implementation Report (Round 1)` / `Implementation Report (Round {N})`
-- `review` / `review-r{N}` -> `Review Report (Round 1)` / `Review Report (Round {N})`
-- `refinement` / `refinement-r{N}` -> `Refinement Report (Round 1)` / `Refinement Report (Round {N})`
+- `review-plan` / `review-plan-r{N}` -> `Technical Plan Review (Round 1)` / `Technical Plan Review (Round {N})`
+- `code` / `code-r{N}` -> `Code Report (Round 1)` / `Code Report (Round {N})`
+- `review-code` / `review-code-r{N}` -> `Code Review (Round 1)` / `Code Review (Round {N})`
 - `summary` -> `Delivery Summary`
 
 Backfilled comments are also not gated by `has_triage` or `has_push`.

package/templates/.agents/rules/issue-sync.github.zh-CN.md

@@ -123,7 +123,7 @@ fi
 
 ## `in:` label 同步
 
-> **触发时机**：`in:` label 同步应在代码提交后（commit 技能）执行，不在 implement-task 或 refine-task 阶段执行。create-pr 阶段仅从 Issue 复制到 PR，不重新计算。
+> **触发时机**：`in:` label 同步应在代码提交后（commit 技能）执行，不在 code-task 阶段执行。create-pr 阶段仅从 Issue 复制到 PR，不重新计算。
 
 读取 `.agents/.airc.json` 的 `labels.in` 映射。
 
@@ -262,7 +262,7 @@ task 留言同步始终执行，不受权限降级影响。
 
 ## 补发规则（`/complete-task` 归档前执行）
 
-- 扫描任务目录中的 `task.md`、`analysis*.md`、`plan*.md`、`implementation*.md`、`review*.md`、`refinement*.md`
+- 扫描任务目录中的 `task.md`、`analysis*.md`、`review-analysis*.md`、`plan*.md`、`review-plan*.md`、`code*.md`、`review-code*.md`
 - 对每个 `{file-stem}` 用隐藏标记检查是否已发布；未发布则补发，已发布则跳过
 - 补发只追加缺失评论，不删除或重排已有评论
 - 补发评论的 `{agent}` 按以下顺序确定：
@@ -281,10 +281,11 @@ task 留言同步始终执行，不受权限降级影响。
 
 - `task` -> `任务文件`
 - `analysis` / `analysis-r{N}` -> `需求分析` / `需求分析（Round {N}）`
+- `review-analysis` / `review-analysis-r{N}` -> `需求分析审查（Round 1）` / `需求分析审查（Round {N}）`
 - `plan` / `plan-r{N}` -> `技术方案` / `技术方案（Round {N}）`
-- `implementation` / `implementation-r{N}` -> `实现报告（Round 1）` / `实现报告（Round {N}）`
-- `review` / `review-r{N}` -> `审查报告（Round 1）` / `审查报告（Round {N}）`
-- `refinement` / `refinement-r{N}` -> `修复报告（Round 1）` / `修复报告（Round {N}）`
+- `review-plan` / `review-plan-r{N}` -> `技术方案审查（Round 1）` / `技术方案审查（Round {N}）`
+- `code` / `code-r{N}` -> `实现报告（Round 1）` / `实现报告（Round {N}）`
+- `review-code` / `review-code-r{N}` -> `代码审查（Round 1）` / `代码审查（Round {N}）`
 - `summary` -> `交付摘要`
 
 补发评论同样不受 `has_triage` / `has_push` 限制。

package/templates/.agents/rules/milestone-inference.github.en.md

@@ -1,6 +1,6 @@
 # Milestone Inference Rules
 
-Read this file before the `create-task` platform rule, `implement-task`, or `create-pr` handles a milestone.
+Read this file before the `create-task` platform rule, `code-task`, or `create-pr` handles a milestone.
 
 ## General Principles
 
@@ -56,7 +56,7 @@ fi
 
 If `has_triage=false`, inference returns empty, or `gh issue edit` fails, skip and continue without blocking the `import-issue` workflow.
 
-## Phase 2: `implement-task`
+## Phase 2: `code-task`
 
 Goal: narrow the Issue milestone from a release line to a concrete version when implementation starts.