@fitlab-ai/agent-infra 0.6.5 → 0.7.0

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

@@ -224,8 +224,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 +258,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

@@ -224,8 +224,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 +258,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.
 

package/templates/.agents/rules/milestone-inference.github.zh-CN.md

@@ -1,6 +1,6 @@
 # Milestone 推断规则
 
-在 `create-task` 的平台规则、`implement-task` 或 `create-pr` 处理 milestone 之前先读取本文件。
+在 `create-task` 的平台规则、`code-task` 或 `create-pr` 处理 milestone 之前先读取本文件。
 
 ## 通用原则
 
@@ -56,7 +56,7 @@ fi
 
 如果 `has_triage=false`、推断结果为空、或 `gh issue edit` 失败，跳过并继续，不阻断 `import-issue` 工作流。
 
-## 阶段 2：`implement-task`
+## 阶段 2：`code-task`
 
 目标：开始开发时，把 Issue milestone 从版本线收窄到具体版本。
 

package/templates/.agents/rules/no-mid-flow-questions.en.md

@@ -0,0 +1,57 @@
+# General Rule - No Mid-Flow Questions During SKILL Execution
+
+> **Scope**: this rule applies to **all SKILL** executions.
+> Only the two exemption categories below may ask the user; any other mid-flow question is a violation.
+
+## Exemption Categories
+
+### Exemption 1: Literal clarification of entry-point natural-language input
+
+Allowed only when the SKILL's core responsibility is to process **natural-language input the user provided in this invocation**, and that input is unparseable or self-contradictory. The clarification must be about the **literal input itself**; it must not be used to solicit implementation preferences.
+
+SKILLs currently covered by this exemption:
+
+- `create-task`: may clarify the task description itself when the user-provided description is unclear
+- `refine-title`: requires the user's final confirmation (y/n) for a generated title
+
+### Exemption 2: Short confirmation before truly irreversible destructive operations
+
+Any SKILL may pause briefly before the following irreversible operations; routine design choices do not qualify:
+
+- `git push --force`, `rm -rf` against the user's worktree, etc.
+- Deleting or overwriting shared remote resources (e.g., shared GitHub labels)
+- Overwriting uncommitted local changes
+
+SKILLs currently covered by this exemption:
+
+- `init-labels`: may confirm before deleting legacy labels not in the final mapping
+- `commit`: may stop and confirm when its plan conflicts with the user's uncommitted changes
+
+## No-Mid-Flow-Questions Clause (default behavior)
+
+For every SKILL execution context not covered by the two exemptions above, the default behavior is:
+
+1. Do not call any user-question tool, including but not limited to `AskUserQuestion` and equivalent mechanisms that ask the user to choose.
+2. When uncertain, proceed with the most robust option without interrupting the flow. Use this priority order:
+   1. Prefer the option consistent with existing code, documentation, and rules
+   2. Prefer the more reversible option
+   3. Prefer the option with the smaller impact area
+3. If assumptions or open questions exist, write them into fixed artifact sections instead of leaving them suspended in the conversation:
+   - English artifacts use `## Assumptions` / `## Open Questions`; Chinese artifacts use `## 假设` / `## 未决问题`
+   - Meaning: the assumptions section records assumptions used for this run that may be revisited later; the open questions section records unresolved questions for human review
+   - If the artifact template does not reserve these sections, append them as needed. If there are no assumptions or open questions, do not force empty sections.
+
+## Human Review Checkpoint Semantics
+
+A mandatory human review checkpoint means:
+
+- Stop after producing the artifact: once the skill finishes an artifact such as `plan.md`, end the current invocation and wait for the user to explicitly trigger the next skill command
+- Do not pause mid-process to ask for input: do not insert interruptions such as "Do you prefer option A or B?" between execution steps
+
+If a key decision needs human judgment during execution, follow the assumptions and open questions rule above: record it in the artifact's "Open Questions" / `未决问题` section for the user to address at the review checkpoint.
+
+## Anchor Location
+
+This rule's sole global anchor lives in the project-level AGENTS.md "AI Behavior Principles" preamble, which every AI tool loads. Individual SKILL.md files no longer reference this rule, so no per-skill duplicate bullet needs to be maintained.
+
+When executing any SKILL, if AGENTS.md's preamble notes "follow this rule first," the LLM should **proactively Read** this file to load the complete exemption list and concrete constraints.

package/templates/.agents/rules/no-mid-flow-questions.zh-CN.md

@@ -0,0 +1,57 @@
+# 通用规则 - SKILL 执行禁言
+
+> **适用范围**：本规则适用于**所有 SKILL** 的执行过程。
+> 仅以下两类例外可向用户提问；不属于这两类的发问一律按违规处理。
+
+## 例外类型
+
+### 例外 1：入口式自然语言入参的字面澄清
+
+仅当 SKILL 的本职职责就是处理**用户当次提供的自然语言入参**时，如果该入参无法解析或自相矛盾，可直接就**该入参字面**向用户澄清。不允许借此征求实现方案的偏好。
+
+当前归入本例外的 SKILL：
+
+- `create-task`：用户提供的任务描述不清晰时可澄清描述本身
+- `refine-title`：生成的新标题需要用户最终确认（y/n）
+
+### 例外 2：不可逆破坏性操作前的短暂确认
+
+任何 SKILL 在以下不可逆操作前可短暂确认；常规方案选择不属于此类：
+
+- `git push --force`、`rm -rf` 用户工作树等
+- 删除/覆盖远端共享资源（如 GitHub 共享 label）
+- 覆盖用户未提交的本机改动
+
+当前归入本例外的 SKILL：
+
+- `init-labels`：删除不在最终映射中的旧 label 前可确认
+- `commit`：检测到与用户未提交改动冲突时可停下确认
+
+## 禁言条款（默认行为）
+
+不属于上述两类例外的所有 SKILL 执行场景，遵循以下默认行为：
+
+1. **禁止调用**任何向用户发问的工具（包括但不限于 `AskUserQuestion` 及等价的「征求用户选择」机制）。
+2. **不确定时**，按「最稳健方案」自主推进，不中断对话。最稳健方案的判定优先级：
+   1. 与现有代码 / 文档 / 规则一致的方案优先
+   2. 可逆性更高的方案优先
+   3. 影响面更小的方案优先
+3. **如存在假设或未决问题**，写入产物中的固定段落，不在对话中悬置：
+   - 中文产物用 `## 假设` / `## 未决问题`；英文产物用 `## Assumptions` / `## Open Questions`
+   - 含义：`假设` 段记录本次按某假设推进、未来若假设不成立可推翻；`未决问题` 段记录本次未决、需要人工审查时裁定的问题
+   - 产物模板未预留这两段时，按需追加；没有假设或未决问题时不必强行写空段。
+
+## 人工审查检查点语义
+
+「强制性人工审查检查点」（mandatory human review checkpoint）的语义是：
+
+- **产出后停止**：技能完成产物（如 `plan.md`）后立即结束本轮调用，等待用户主动触发下一个技能命令
+- **不是过程中暂停征求意见**：不允许在执行步骤之间插入「请问您倾向 A 还是 B？」之类的中断
+
+如果在执行过程中发现需要用户裁定的关键决策，按上文「假设与未决问题」处理，记录到产物的「未决问题」/`Open Questions` 段落，由用户在审查检查点统一回应。
+
+## 锚点位置
+
+本规则的唯一全局锚点在项目级 AGENTS.md 的「AI 行为准则」preamble，所有 AI 工具加载 AGENTS.md 时即可见。各 SKILL.md 不再单独引用本规则，避免在每个 SKILL 顶部维护重复 bullet。
+
+LLM 在执行任一 SKILL 时，若 AGENTS.md 的 preamble 已说明「优先遵循本规则」，应**主动 Read** 本文件以获取完整的例外列表与具体约束。

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

@@ -24,14 +24,13 @@ Within one PR, a given `{task-id}` must have only one summary comment with this
 
 Aggregate the latest artifacts in the task directory:
 - `plan.md` or the latest `plan-r{N}.md`
-- `implementation.md` or the latest `implementation-r{N}.md`
-- `review.md` or the latest `review-r{N}.md`
-- `refinement.md` or the latest `refinement-r{N}.md`
+- `code.md` or the latest `code-r{N}.md`
+- `review-code.md` or the latest `review-code-r{N}.md`
 
 Aggregation rules:
 - extract 2-4 self-contained technical decisions from `plan*`
-- build the review-history table from `review*` and `refinement*`
-- extract the test summary from `implementation*` or `refinement*`
+- build the review-history table from `review-code*` and `code*`
+- extract the test summary from `code*`
 - if one artifact class is missing, treat it as "no data for this stage" and continue
 
 ## Comment Body Template

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

@@ -24,14 +24,13 @@
 
 聚合当前任务目录中的最新产物：
 - `plan.md` 或最新 `plan-r{N}.md`
-- `implementation.md` 或最新 `implementation-r{N}.md`
-- `review.md` 或最新 `review-r{N}.md`
-- `refinement.md` 或最新 `refinement-r{N}.md`
+- `code.md` 或最新 `code-r{N}.md`
+- `review-code.md` 或最新 `review-code-r{N}.md`
 
 聚合规则：
 - 从 `plan*` 提取 2-4 条自包含的关键技术决策
-- 用 `review*` 与 `refinement*` 构建审查历程表
-- 从 `implementation*` 或 `refinement*` 提取测试结果摘要
+- 用 `review-code*` 与 `code*` 构建审查历程表
+- 从 `code*` 提取测试结果摘要
 - 某一类产物缺失时，按“无该阶段数据”处理并继续生成
 
 ## 评论体模板

package/templates/.agents/rules/task-management.en.md

@@ -5,10 +5,12 @@
 Map user intent to the corresponding workflow command:
 - "analyze issue #123" -> `import-issue`
 - "analyze task TASK-20260306-143022" -> `analyze-task`
+- "review requirement analysis" -> `review-analysis`
 - "design a plan" -> `plan-task`
-- "implement" or "build" -> `implement-task`
-- "review" -> `review-task`
-- "fix review feedback" -> `refine-task`
+- "review a plan" or "review technical design" -> `review-plan`
+- "implement" or "build" -> `code-task`
+- "code review" or "review code" -> `review-code`
+- "fix review feedback" -> `code-task`
 
 ## Task State Management
 
@@ -25,10 +27,11 @@ Map user intent to the corresponding workflow command:
 - `import-dependabot`: update `current_step`, `updated_at`, `assigned_to`, `agent_infra_version`
 - `restore-task`: update `status`, `updated_at`, `assigned_to`, `agent_infra_version`
 - `analyze-task`: update `current_step`, `updated_at`, `assigned_to`, `agent_infra_version`
+- `review-analysis`: update `current_step`, `updated_at`, `agent_infra_version`
 - `plan-task`: update `current_step`, `updated_at`, `agent_infra_version`
-- `implement-task`: update `current_step`, `updated_at`, `agent_infra_version`
-- `review-task`: update `current_step`, `updated_at`, `agent_infra_version`
-- `refine-task`: update `current_step`, `updated_at`, `agent_infra_version`
+- `review-plan`: update `current_step`, `updated_at`, `agent_infra_version`
+- `code-task`: update `current_step`, `updated_at`, `agent_infra_version`
+- `review-code`: update `current_step`, `updated_at`, `agent_infra_version`
 - `create-pr`: update `pr_number`, `updated_at`, `agent_infra_version`
 - `commit`: update `updated_at`, `agent_infra_version`; update `current_step` when needed (see `commit/reference/task-status-update.md`)
 - `complete-task`: update `status`, `current_step`, `completed_at`, `updated_at`, `agent_infra_version`

package/templates/.agents/rules/task-management.zh-CN.md

@@ -5,10 +5,12 @@
 根据用户意图自动映射到对应工作流命令：
 - “分析 issue #123” -> `import-issue`
 - “分析任务 TASK-20260306-143022” -> `analyze-task`
+- “审查需求分析” -> `review-analysis`
 - “设计方案” -> `plan-task`
-- “实施/实现” -> `implement-task`
-- “审查” -> `review-task`
-- “修复审查问题” -> `refine-task`
+- “审查方案/审查技术方案” -> `review-plan`
+- “实施/实现” -> `code-task`
+- “审查代码/代码审查” -> `review-code`
+- “修复审查问题” -> `code-task`
 
 ## 任务状态管理
 
@@ -25,10 +27,11 @@
 - `import-dependabot`：更新 `current_step`、`updated_at`、`assigned_to`、`agent_infra_version`
 - `restore-task`：更新 `status`、`updated_at`、`assigned_to`、`agent_infra_version`
 - `analyze-task`：更新 `current_step`、`updated_at`、`assigned_to`、`agent_infra_version`
+- `review-analysis`：更新 `current_step`、`updated_at`、`agent_infra_version`
 - `plan-task`：更新 `current_step`、`updated_at`、`agent_infra_version`
-- `implement-task`：更新 `current_step`、`updated_at`、`agent_infra_version`
-- `review-task`：更新 `current_step`、`updated_at`、`agent_infra_version`
-- `refine-task`：更新 `current_step`、`updated_at`、`agent_infra_version`
+- `review-plan`：更新 `current_step`、`updated_at`、`agent_infra_version`
+- `code-task`：更新 `current_step`、`updated_at`、`agent_infra_version`
+- `review-code`：更新 `current_step`、`updated_at`、`agent_infra_version`
 - `create-pr`：更新 `pr_number`、`updated_at`、`agent_infra_version`
 - `commit`：更新 `updated_at`、`agent_infra_version`；必要时更新 `current_step`（详见 `commit/reference/task-status-update.md`）
 - `complete-task`：更新 `status`、`current_step`、`completed_at`、`updated_at`、`agent_infra_version`

package/templates/.agents/rules/testing-discipline.en.md

@@ -12,13 +12,13 @@ When a positive assertion already covers the expected behavior, do not add anoth
 
 Bad:
 ```ts
-assert.match(content, /^name: implement-task$/m);    // The positive assertion already covers the expected value.
+assert.match(content, /^name: code-task$/m);         // The positive assertion already covers the expected value.
 assert.doesNotMatch(content, /^name: wrong-name$/m); // Redundant: permanently remembers a value that should not appear.
 ```
 
 Good:
 ```ts
-assert.match(content, /^name: implement-task$/m);    // The positive assertion is enough.
+assert.match(content, /^name: code-task$/m);         // The positive assertion is enough.
 ```
 
 If the positive assertion passes, the value is correct. The extra negative assertion adds no protection, only maintenance cost, and can become a test that permanently remembers a concept after the feature is gone.

package/templates/.agents/rules/testing-discipline.zh-CN.md

@@ -12,13 +12,13 @@
 
 ❌ 反例：
 ```ts
-assert.match(content, /^name: implement-task$/m);    // 正向已覆盖期望值
+assert.match(content, /^name: code-task$/m);         // 正向已覆盖期望值
 assert.doesNotMatch(content, /^name: wrong-name$/m); // 多余：永久记住一个不该出现的值
 ```
 
 ✅ 正例：
 ```ts
-assert.match(content, /^name: implement-task$/m);    // 正向断言已足够
+assert.match(content, /^name: code-task$/m);         // 正向断言已足够
 ```
 
 正向断言通过即证明值正确；额外的反向断言不增加保护，只增加维护成本，并会在功能删除后退化为"测试永久记住一个不再存在的概念"。

package/templates/.agents/scripts/validate-artifact.js

@@ -203,7 +203,7 @@ function runCheck(type, context) {
   }
 }
 
-// === Check Implementations ===
+// === Check Functions ===
 
 function checkTaskMeta({ taskDir, config }) {
   const task = loadTask(taskDir);

package/templates/.agents/skills/analyze-task/SKILL.en.md

@@ -115,6 +115,18 @@ Create `.agents/workspace/active/{task-id}/{analysis-artifact}`.
 ## Dependencies
 - {Required dependencies and coordination with other modules}
 
+## Assumptions
+
+> If this analysis depends on assumptions, list them here; omit this section if there are none.
+
+- {assumption}
+
+## Open Questions
+
+> If there are unresolved questions for human review, list them here; omit this section if there are none.
+
+- {open question}
+
 ## Effort and Complexity Assessment
 - Complexity: {High/Medium/Low}
 - Risk level: {High/Medium/Low}
@@ -189,10 +201,10 @@ Summary:
 Output file:
 - Analysis report: .agents/workspace/active/{task-id}/{analysis-artifact}
 
-Next step - create technical plan:
-  - Claude Code / OpenCode: /plan-task {task-id}
-  - Gemini CLI: /{{project}}:plan-task {task-id}
-  - Codex CLI: $plan-task {task-id}
+Next step - review the analysis:
+  - Claude Code / OpenCode: /review-analysis {task-id}
+  - Gemini CLI: /{{project}}:review-analysis {task-id}
+  - Codex CLI: $review-analysis {task-id}
 ```
 
 ## Completion Checklist