@fitlab-ai/agent-infra 0.6.4 → 0.7.0

package/README.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <strong>From issue to merged PR in 9 commands.</strong> Define a requirement, let AI handle analysis, planning, coding, review, and delivery — you only step in when it matters.
+  <strong>From issue to merged PR in 11 commands.</strong> Define a requirement, let AI handle analysis, planning, coding, and three-stage review — you only step in when it matters.
 </p>
 
 <p align="center">
@@ -66,11 +66,23 @@ Once initialized, open the project in your AI TUI and install the latest skills:
 
 > AI scans the codebase, identifies `src/auth/login.ts` as the root cause, and writes `analysis.md`.
 
+```bash
+/review-analysis TASK-20260319-100000
+```
+
+> AI self-reviews the analysis: *"Approved. 0 blockers, 0 major, 0 minor — scope and root cause are clear, proceed to design."*
+
 ```bash
 /plan-task TASK-20260319-100000
 ```
 
 > AI proposes a fix plan: *"Sanitize the email input in `LoginService.validate()` and add a dedicated unit test."*
+
+```bash
+/review-plan TASK-20260319-100000
+```
+
+> AI self-reviews the plan: *"Approved with no findings. Ready for implementation."*
 >
 > **You review the plan and reply in natural language:**
 
@@ -79,22 +91,22 @@ The plan looks right, but don't change the DB schema.
 Just fix it at the application layer in LoginService.
 ```
 
-> AI updates the plan accordingly and confirms.
+> AI re-runs `/plan-task` to update the plan accordingly and confirms.
 
 ```bash
-/implement-task TASK-20260319-100000
+/code-task TASK-20260319-100000
 ```
 
 > AI writes the fix, adds a test case for `user+tag@example.com`, and runs all tests — green.
 
 ```bash
-/review-task TASK-20260319-100000
+/review-code TASK-20260319-100000
 ```
 
-> AI reviews its own implementation: *"Approved. 0 blockers, 0 major, 1 minor (missing JSDoc)."*
+> AI reviews its own code: *"Approved. 0 blockers, 0 major, 1 minor (missing JSDoc)."*
 
 ```bash
-/refine-task TASK-20260319-100000
+/code-task TASK-20260319-100000
 ```
 
 > AI fixes the minor issue and re-validates.
@@ -107,7 +119,7 @@ Just fix it at the application layer in LoginService.
 
 > Commit created, PR #43 opened (auto-linked to issue #42), task archived.
 
-**9 commands. 1 natural-language correction. From issue to merged PR.** That is the entire SOP — programming can have a standard operating procedure too.
+**11 commands. 1 natural-language correction. From issue to merged PR.** That is the entire SOP — programming can have a standard operating procedure too.
 
 Every command above works the same way in Claude Code, Codex, Gemini CLI, and OpenCode. Switch tools mid-task — the workflow state follows.
 
@@ -115,9 +127,9 @@ Every command above works the same way in Claude Code, Codex, Gemini CLI, and Op
 
 These are not thin command aliases. Each skill encapsulates standardized processes that are tedious and error-prone when done by hand:
 
-- **Structured artifacts** — every step produces a templated document (`analysis.md`, `plan.md`, `review.md`) with consistent structure, not free-form notes
+- **Structured artifacts** — every step produces a templated document (`analysis.md`, `review-analysis.md`, `plan.md`, `review-plan.md`, `code.md`, `review-code.md`) with consistent structure, not free-form notes
 - **Multi-round versioning** — requirements changed? Run `analyze-task` again to get `analysis-r2.md`; the full revision history is preserved
-- **Severity-classified reviews** — `review-task` categorizes findings into Blocker / Major / Minor with file paths and fix suggestions, not a vague "looks good"
+- **Severity-classified reviews** — `review-code` categorizes findings into Blocker / Major / Minor with file paths and fix suggestions, not a vague "looks good"
 - **Cross-tool state continuity** — `task.md` records who did what and when; Claude can analyze, Codex can implement, Gemini can review — context transfers seamlessly
 - **Audit trail and co-authorship** — every step appends to the Activity Log; the final commit includes `Co-Authored-By` lines for all participating AI agents
 
@@ -202,9 +214,13 @@ This detects the packaged template version and renders all managed files. The sa
 
 The sandbox image also preinstalls `gh`. When `gh auth token` succeeds on the host, `ai sandbox create` injects the token into the container as `GH_TOKEN`, so `gh` commands work inside the sandbox without extra setup.
 
+`ai sandbox rebuild` keeps Docker's build cache by default, so it quickly retags the sandbox image without refreshing every package. Use `ai sandbox rebuild --refresh` when you want to upgrade the image: it passes `--no-cache --pull` to Docker, pulls the current Ubuntu base image, and reruns the apt, tmux build, and global npm install layers. Claude Code updates are disabled inside the container, and OpenCode startup update checks are disabled; `--refresh` is the routine upgrade path for sandbox-managed tools. Manual `opencode upgrade` remains outside this guard. The default `python3` provided by the Ubuntu 24.04 sandbox base is Python 3.12, so scripts that hard-code Python 3.10 paths may need adjustment.
+
 `ai sandbox exec` also forwards a small terminal-detection whitelist (`TERM_PROGRAM`, `TERM_PROGRAM_VERSION`, `LC_TERMINAL`, `LC_TERMINAL_VERSION`) into the container. This keeps interactive TUIs aligned with the host terminal for behaviors such as Claude Code's Shift+Enter newline support, without passing through the full host environment.
 
-On macOS, interactive `ai sandbox exec <branch>` sessions can bridge image paste into the sandbox. When you press `Ctrl+V` and the host clipboard currently holds an image, agent-infra reads the image from the host clipboard, writes a PNG under `~/.agent-infra/clipboard/`, and injects the container path as bracketed paste so Claude Code, Codex, Gemini CLI, and OpenCode can attach it. The host clipboard is only read, never rewritten. The bridge is best-effort: existing sandboxes must be rebuilt to receive the `/clipboard` mount, and if the optional pty dependency or clipboard probe is unavailable the session falls back to the normal interactive path.
+On macOS, interactive `ai sandbox exec <branch>` sessions can bridge image paste into the sandbox. When you press `Ctrl+V` and the host clipboard currently holds an image, agent-infra reads the image from the host clipboard, writes a PNG under `~/.agent-infra/clipboard/`, and injects the container path as bracketed paste so Claude Code, Codex, Gemini CLI, and OpenCode can attach it. The host clipboard is only read, never rewritten. The bridge is best-effort: existing sandboxes must be rebuilt to receive the `/clipboard` mount, and if the optional pty dependency or clipboard probe is unavailable the session falls back to the normal interactive path. Set `AI_SANDBOX_NO_CLIPBOARD_BRIDGE=1` to skip the bridge and enter the normal interactive path directly when diagnosing mouse, scrolling, or other input issues.
+
+When you run the sandbox from a remote Mac over SSH, use `ai cp <ssh-alias>` on the Mac in front of you to push the local clipboard image to that remote Mac first. Copy an image with Cmd+C, run `ai cp mini`, then return to the existing SSH session and press `Ctrl+V`; the sandbox bridge reads the remote Mac's NSPasteboard and injects the image as usual. This command handles PNG images only and uses non-interactive ssh/scp with key-based authentication. For now both the sender and the remote must be macOS—the remote NSPasteboard is written via `osascript`—but the remote-write step is the natural extension point for other platforms later.
 
 `ai sandbox exec` and `ai sandbox refresh` reconcile Claude Code credentials in both directions across the host credential store and every sandbox project copy under `~/.agent-infra/credentials/*`. When a long-running sandbox refreshes OAuth tokens first, the next entry or refresh command writes the freshest valid copy back to the host Keychain or `~/.claude/.credentials.json`; when the host is fresher, it updates the project copies. If every copy is stale, `ai sandbox refresh` probes `claude /status` and asks you to log in only when the probe cannot recover credentials.
 
@@ -230,6 +246,11 @@ remove only dirs without an active sandbox container.
 Existing sandboxes pick up these mounts after `ai sandbox rm <branch>` and
 `ai sandbox create <branch>`.
 
+On first `ai sandbox create`, agent-infra writes a bilingual `README.md` into
+`~/.agent-infra/share/<project>/common/` and each `branches/<branch>/`
+directory to help you discover these channels. The READMEs are idempotent and
+can be safely deleted; the scaffold only writes them when missing.
+
 ### User-level dotfiles channel
 
 `ai sandbox create` also mounts an optional read-only channel for host user preferences:
@@ -294,6 +315,7 @@ target.
 | `.config/opencode/*`, `.local/share/opencode/*` | OpenCode credentials and data use dedicated bind mounts. |
 | `.host-shell-config/*` | agent-infra managed shell and Git configuration. |
 | `.gitconfig`, `.gitignore_global`, `.stCommitMsg`, `.bash_aliases` | agent-infra symlinks these to `.host-shell-config/`, including `safe.directory` and GPG sync state. |
+| `README.md` | agent-infra scaffolds a discoverability README at the dotfiles root on first create; the link hook ignores it so `$HOME/README.md` is not shadowed. |
 
 Other existing real directories, such as `~/.config/` or `~/.cache/`, are not
 replaced by top-level dotfiles. If a file conflicts with one of those
@@ -317,7 +339,7 @@ agent-infra is intentionally simple: a bootstrap CLI creates the seed configurat
 1. **Install** — `npm install -g @fitlab-ai/agent-infra` (or `brew install fitlab-ai/tap/agent-infra` on macOS, or use the shell script wrapper)
 2. **Initialize** — `ai init` in the project root to generate `.agents/.airc.json` and install the seed command
 3. **Render** — run `update-agent-infra` in any AI TUI to detect the bundled template version and generate all managed files
-4. **Develop** — use built-in skills to drive the full lifecycle: `analysis → design → implementation → review → fix → commit`
+4. **Develop** — use built-in skills to drive the full lifecycle: `analysis → analysis-review → design → design-review → code → code-review → commit`
 5. **Update** — run `update-agent-infra` again whenever a new template version is available
 
 ### Layered Architecture
@@ -514,10 +536,11 @@ agent-infra ships with **a rich set of built-in AI skills**. They are organized
 | `create-task` | Create a task scaffold from a natural-language request and cascade Issue creation through the platform rule when available. | `description` | Start a new feature, bug-fix, or improvement from scratch. |
 | `import-issue` | Import a GitHub Issue into the local task workspace. | `issue-number` | Convert an existing Issue into an actionable task folder. |
 | `analyze-task` | Produce a requirement analysis artifact for an existing task. | `task-id` | Capture scope, risks, and impacted files before designing. |
-| `plan-task` | Write the technical implementation plan with a review checkpoint. | `task-id` | Define the approach after analysis is complete. |
-| `implement-task` | Implement the approved plan and produce an implementation report. | `task-id` | Write code, tests, and docs after plan approval. |
-| `review-task` | Review the implementation and classify findings by severity. | `task-id` | Run a structured code review before merging. |
-| `refine-task` | Fix review findings in priority order without expanding scope. | `task-id` | Address review feedback and re-validate the task. |
+| `review-analysis` | Review the requirement analysis and classify findings by severity. | `task-id` | Confirm the analysis is complete before design. |
+| `plan-task` | Write the technical plan with a review checkpoint. | `task-id` | Define the approach after analysis approval. |
+| `review-plan` | Review the technical plan and classify findings by severity. | `task-id` | Confirm the design is actionable before coding. |
+| `code-task` | Implement the approved plan or fix code review findings, producing a code report. | `task-id` | Write code, tests, and docs after plan approval, or handle review feedback. |
+| `review-code` | Review the code and classify findings by severity. | `task-id` | Run a structured code review before merging. |
 | `complete-task` | Mark the task complete and archive it after all gates pass. | `task-id` | Close out a task after review, tests, and commit are done. |
 
 <a id="task-status"></a>
@@ -684,8 +707,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:
 
@@ -722,17 +745,17 @@ Namespaced custom TUI:
 
 ## Prebuilt Workflows
 
-agent-infra includes **4 prebuilt workflows**. Three of them share the same gated delivery lifecycle:
+agent-infra includes **4 prebuilt workflows**. Three of them share the same symmetric gated delivery lifecycle:
 
-`analysis -> design -> implementation -> review -> fix -> commit`
+`analysis -> analysis-review -> design -> design-review -> code -> code-review -> commit`
 
 The fourth, `code-review`, is intentionally smaller and optimized for reviewing an existing PR or branch.
 
 | Workflow | Best for | Step chain |
 |----------|----------|------------|
-| `feature-development` | Building a new feature or capability | `analysis -> design -> implementation -> review -> fix -> commit` |
-| `bug-fix` | Diagnosing and fixing a defect with regression coverage | `analysis -> design -> implementation -> review -> fix -> commit` |
-| `refactoring` | Structural changes that should preserve behavior | `analysis -> design -> implementation -> review -> fix -> commit` |
+| `feature-development` | Building a new feature or capability | `analysis -> analysis-review -> design -> design-review -> code -> code-review -> commit` |
+| `bug-fix` | Diagnosing and fixing a defect with regression coverage | `analysis -> analysis-review -> design -> design-review -> code -> code-review -> commit` |
+| `refactoring` | Structural changes that should preserve behavior | `analysis -> analysis-review -> design -> design-review -> code -> code-review -> commit` |
 | `code-review` | Reviewing an existing PR or branch | `analysis -> review -> report` |
 
 ### Example lifecycle
@@ -748,20 +771,33 @@ import-issue #42                    Import task from GitHub Issue
   analyze-task T1                   Requirement analysis
          |
          v
-    plan-task T1                    Design solution  <-- human review
+  review-analysis T1                Review analysis
+         |
+     Issues?
+      +--YES----> analyze-task T1
+      |
+         v
+    plan-task T1                    Design solution
+         |
+         v
+  review-plan T1                    Review plan
+         |
+     Issues?
+      +--YES----> plan-task T1
+      |
          |
          v
-  implement-task T1                 Write code and tests
+  code-task T1                      Write code and tests
          |
          v
-  +-> review-task T1                Automated code review
+  +-> review-code T1                Automated code review
   |      |
   |   Issues?
   |      +--NO-------+
   |     YES          |
   |      |           |
   |      v           |
-  |  refine-task T1  |
+  |  code-task T1 (fix mode)
   |      |           |
   +------+           |
                      |
@@ -787,7 +823,7 @@ The generated `.agents/.airc.json` file is the central contract between the boot
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateVersion": "v0.6.4",
+  "templateVersion": "v0.6.5",
   "templates": {
     "sources": [
       { "type": "local", "path": "~/private-templates" }

package/README.zh-CN.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <strong>从 Issue 到合并 PR，只需 9 条命令。</strong> 定义需求，让 AI 完成分析、方案设计、编码、审查和交付 —— 你只需在关键节点介入。
+  <strong>从 Issue 到合并 PR，只需 11 条命令。</strong> 定义需求，让 AI 完成分析、方案设计、编码与三阶段审查 —— 你只需在关键节点介入。
 </p>
 
 <p align="center">
@@ -66,11 +66,23 @@ agent-infra 的目标就是把这层共享基础设施标准化。它为所有
 
 > AI 扫描代码库，定位 `src/auth/login.ts` 为根因，输出 `analysis.md`。
 
+```bash
+/review-analysis TASK-20260319-100000
+```
+
+> AI 自审分析报告：*"通过。0 阻塞项，0 主要，0 次要 —— 范围与根因清晰，可进入方案设计。"*
+
 ```bash
 /plan-task TASK-20260319-100000
 ```
 
 > AI 提出修复方案：*"在 `LoginService.validate()` 中清洗邮箱输入，并添加专项单元测试。"*
+
+```bash
+/review-plan TASK-20260319-100000
+```
+
+> AI 自审方案：*"通过且无问题。可进入编码。"*
 >
 > **你审查方案后用自然语言回复：**
 
@@ -79,22 +91,22 @@ agent-infra 的目标就是把这层共享基础设施标准化。它为所有
 只在应用层的 LoginService 里修复就行。
 ```
 
-> AI 按你的要求更新方案并确认。
+> AI 按你的要求重跑 `/plan-task` 更新方案并确认。
 
 ```bash
-/implement-task TASK-20260319-100000
+/code-task TASK-20260319-100000
 ```
 
 > AI 编写修复代码，添加 `user+tag@example.com` 的测试用例，运行全部测试 —— 通过。
 
 ```bash
-/review-task TASK-20260319-100000
+/review-code TASK-20260319-100000
 ```
 
 > AI 审查自己的实现：*"通过。0 阻塞项，0 主要问题，1 次要问题（缺少 JSDoc）。"*
 
 ```bash
-/refine-task TASK-20260319-100000
+/code-task TASK-20260319-100000
 ```
 
 > AI 修复次要问题并重新验证。
@@ -107,7 +119,7 @@ agent-infra 的目标就是把这层共享基础设施标准化。它为所有
 
 > 提交完成，PR #43 已创建（自动关联 Issue #42），任务归档。
 
-**9 条命令，1 次自然语言纠正，从 Issue 到合并 PR。** 这就是完整的 SOP —— 编程也可以有标准作业流程。
+**11 条命令，1 次自然语言纠正，从 Issue 到合并 PR。** 这就是完整的 SOP —— 编程也可以有标准作业流程。
 
 以上每条命令在 Claude Code、Codex、Gemini CLI、OpenCode 中完全通用。任务进行到一半切换工具，工作流状态照常延续。
 
@@ -115,9 +127,9 @@ agent-infra 的目标就是把这层共享基础设施标准化。它为所有
 
 这些不是简单的命令别名。每个 skill 都封装了手动操作时容易遗漏或不一致的标准化流程：
 
-- **结构化产物** — 每个步骤都输出模板化的文档（`analysis.md`、`plan.md`、`review.md`），格式统一，而非自由发挥的散文
+- **结构化产物** — 每个步骤都输出模板化的文档（`analysis.md`、`review-analysis.md`、`plan.md`、`review-plan.md`、`code.md`、`review-code.md`），格式统一，而非自由发挥的散文
 - **多轮版本化** — 需求变了？再执行一次 `analyze-task` 会生成 `analysis-r2.md`，完整修订历史自动保留
-- **分级审查机制** — `review-task` 按 Blocker / Major / Minor 分类问题，附带文件路径和修复建议，而非含糊的"看着没问题"
+- **分级审查机制** — `review-code` 按 Blocker / Major / Minor 分类问题，附带文件路径和修复建议，而非含糊的"看着没问题"
 - **跨工具状态延续** — `task.md` 记录了谁在什么时间做了什么；Claude 分析、Codex 实现、Gemini 审查——上下文无缝衔接
 - **审计轨迹与联合署名** — 每个步骤自动追加 Activity Log；最终提交包含所有参与 AI 的 `Co-Authored-By` 署名
 
@@ -202,9 +214,13 @@ CLI 会收集项目元数据，向所有支持的 AI TUI 安装 `update-agent-in
 
 沙箱镜像也会预装 `gh`。如果宿主机上的 `gh auth token` 能成功返回 token，`ai sandbox create` 会把它以 `GH_TOKEN` 环境变量注入容器，让你在沙箱里直接使用 `gh`，无需额外登录配置。
 
+`ai sandbox rebuild` 默认保留 Docker build cache，因此会快速重打沙箱镜像，不会刷新每个软件包。需要升级镜像时使用 `ai sandbox rebuild --refresh`：它会向 Docker 传入 `--no-cache --pull`，重新拉取当前 Ubuntu 基础镜像，并重跑 apt、tmux 编译和全局 npm 安装层。容器内 Claude Code 更新已关闭，OpenCode 启动时更新检查也已关闭；`--refresh` 是沙箱托管工具的常规升级入口。手动 `opencode upgrade` 不受该保护覆盖。Ubuntu 24.04 沙箱基础镜像提供的默认 `python3` 是 Python 3.12，因此硬编码 Python 3.10 路径的脚本可能需要调整。
+
 `ai sandbox exec` 也会向容器透传一小组终端检测白名单变量（`TERM_PROGRAM`、`TERM_PROGRAM_VERSION`、`LC_TERMINAL`、`LC_TERMINAL_VERSION`）。这样可以让交互式 TUI 保持与宿主终端一致的行为，例如 Claude Code 的 `Shift+Enter` 换行支持，同时避免把整个宿主环境灌入容器。
 
-在 macOS 上，交互式 `ai sandbox exec <branch>` 会尽力桥接宿主图片粘贴。当你按下 `Ctrl+V` 且宿主剪贴板当前是图片时，agent-infra 会从宿主剪贴板读取图片，将 PNG 写到 `~/.agent-infra/clipboard/`，再以 bracketed paste 注入容器内路径，让 Claude Code、Codex、Gemini CLI 和 OpenCode 按图片附件处理。宿主剪贴板只读，不会被改写。该能力会自动降级：已有沙箱需要重建后才有 `/clipboard` 挂载；如果可选 pty 依赖或剪贴板探测不可用，会回退到原本的交互进入方式。
+在 macOS 上，交互式 `ai sandbox exec <branch>` 会尽力桥接宿主图片粘贴。当你按下 `Ctrl+V` 且宿主剪贴板当前是图片时，agent-infra 会从宿主剪贴板读取图片，将 PNG 写到 `~/.agent-infra/clipboard/`，再以 bracketed paste 注入容器内路径，让 Claude Code、Codex、Gemini CLI 和 OpenCode 按图片附件处理。宿主剪贴板只读，不会被改写。该能力会自动降级：已有沙箱需要重建后才有 `/clipboard` 挂载；如果可选 pty 依赖或剪贴板探测不可用，会回退到原本的交互进入方式。排查鼠标、滚动或其他输入异常时，可以设置 `AI_SANDBOX_NO_CLIPBOARD_BRIDGE=1` 跳过桥接，直接进入原本的交互路径。
+
+当你通过 SSH 在远端 Mac 上运行沙箱时，可先在手边这台 Mac 上执行 `ai cp <ssh-alias>`，把本机剪贴板图片推送到远端 Mac。典型流程是：Cmd+C 复制图片，运行 `ai cp mini`，回到已有 SSH session 后按 `Ctrl+V`；沙箱桥会读取远端 Mac 的 NSPasteboard，并按原路径注入图片。该命令只处理 PNG 图片，并使用基于 ssh key 的非交互 ssh/scp。目前发送端与远端都需为 macOS（远端通过 `osascript` 写入 NSPasteboard），后续可扩展支持其他远端平台。
 
 `ai sandbox exec` 和 `ai sandbox refresh` 会在宿主机凭证存储与 `~/.agent-infra/credentials/*` 下的所有沙箱项目副本之间做双向 reconcile。长时间运行的沙箱如果先刷新了 OAuth token，下一次进入或刷新命令会把最新有效副本回写到宿主 Keychain 或 `~/.claude/.credentials.json`；宿主机更新时也会继续覆盖项目副本。如果所有副本都已失效，`ai sandbox refresh` 会尝试 `claude /status` 探活，只有探活无法恢复时才提示重新登录。
 
@@ -220,6 +236,11 @@ CLI 会收集项目元数据，向所有支持的 AI TUI 安装 `update-agent-in
 可先用 `ai sandbox prune --dry-run` 查看旧版本或异常中断遗留的孤儿 per-branch 状态目录，再用 `ai sandbox prune` 只删除没有活跃 sandbox 容器对应的目录。
 已有沙箱需要执行 `ai sandbox rm <branch>` 后再执行 `ai sandbox create <branch>`，才能加载新的挂载点。
 
+首次执行 `ai sandbox create` 时，agent-infra 会在
+`~/.agent-infra/share/<project>/common/` 以及每个 `branches/<branch>/`
+目录下写入一份中英双语 `README.md`，帮助你发现这些通道。README 是幂等的，
+可以安全删除；scaffold 仅在文件缺失时写入。
+
 #### 用户级 dotfiles 通道
 
 `ai sandbox create` 还会自动挂载一条可选的只读通道，用于把宿主机用户级偏好带进沙箱：
@@ -270,6 +291,7 @@ dotfiles 树解引用到
 | `.config/opencode/*`, `.local/share/opencode/*` | OpenCode 凭证和数据使用专用 bind mount。 |
 | `.host-shell-config/*` | agent-infra 管理的 shell 和 Git 配置。 |
 | `.gitconfig`, `.gitignore_global`, `.stCommitMsg`, `.bash_aliases` | agent-infra 将这些路径软链到 `.host-shell-config/`，包含 `safe.directory` 和 GPG 同步状态。 |
+| `README.md` | agent-infra 会在 dotfiles 根目录 scaffold 一份发现性 README；link hook 会忽略它，避免遮蔽 `$HOME/README.md`。 |
 
 其他已经存在的真实目录（如 `~/.config/`、`~/.cache/`）不会被顶层 dotfile 替换。如果某个文件与这类目录冲突，钩子会打印警告并跳过：
 
@@ -290,7 +312,7 @@ agent-infra 的结构刻意保持简单：引导 CLI 负责生成种子配置，
 1. **安装** — `npm install -g @fitlab-ai/agent-infra`（或在 macOS 上使用 `brew install fitlab-ai/tap/agent-infra`，或使用 shell 脚本便捷封装）
 2. **初始化** — 在项目根目录运行 `ai init`，生成 `.agents/.airc.json` 并安装种子命令
 3. **渲染** — 在任意 AI TUI 中执行 `update-agent-infra`，检测当前打包模板版本并生成所有受管理文件
-4. **开发** — 使用内置 skill 驱动完整生命周期：`analysis → design → implementation → review → fix → commit`
+4. **开发** — 使用内置 skill 驱动完整生命周期：`analysis → analysis-review → design → design-review → code → code-review → commit`
 5. **升级** — 有新模板版本时再次执行 `update-agent-infra` 即可
 
 ### 分层架构
@@ -487,10 +509,11 @@ agent-infra 提供 **丰富的内置 AI skills**。它们按使用场景分组
 | `create-task` | 根据自然语言请求创建任务骨架，并在平台规则可用时级联创建 Issue。 | `description` | 从零开始记录新功能、缺陷或改进需求。 |
 | `import-issue` | 将 GitHub Issue 导入本地任务工作区。 | `issue-number` | 把已有 Issue 转成可执行的任务目录。 |
 | `analyze-task` | 为已有任务输出需求分析产物。 | `task-id` | 在设计前明确范围、风险和受影响文件。 |
-| `plan-task` | 编写技术实施方案，并设置人工审查检查点。 | `task-id` | 分析完成后定义具体实现路径。 |
-| `implement-task` | 按批准方案实施并生成实现报告。 | `task-id` | 在方案获批后编写代码、测试和文档。 |
-| `review-task` | 审查实现结果，并按严重程度分类问题。 | `task-id` | 合入前执行结构化代码审查。 |
-| `refine-task` | 按优先级修复审查问题，不额外扩张范围。 | `task-id` | 根据 review 反馈完成修正。 |
+| `review-analysis` | 审查需求分析产物，并按严重程度分类问题。 | `task-id` | 在设计前确认分析完整可用。 |
+| `plan-task` | 编写技术实施方案，并设置审查检查点。 | `task-id` | 分析获批后定义具体实现路径。 |
+| `review-plan` | 审查技术方案，并按严重程度分类问题。 | `task-id` | 在编码前确认方案可执行。 |
+| `code-task` | 按批准方案实施，或修复代码审查问题，并生成实现报告。 | `task-id` | 在方案获批后编写代码、测试和文档，或处理 review 反馈。 |
+| `review-code` | 审查实现结果，并按严重程度分类问题。 | `task-id` | 合入前执行结构化代码审查。 |
 | `complete-task` | 在所有关卡通过后标记任务完成并归档。 | `task-id` | 测试、审查和提交都完成后收尾。 |
 
 <a id="task-status"></a>
@@ -657,8 +680,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：
 
@@ -697,15 +720,15 @@ args: "<task-id>"   # 可选
 
 agent-infra 内置 **4 个预置工作流**。其中 3 个共享同一条分阶段交付链路：
 
-`analysis -> design -> implementation -> review -> fix -> commit`
+`analysis -> analysis-review -> design -> design-review -> code -> code-review -> commit`
 
 第 4 个 `code-review` 则更轻量，专门用于审查已有 PR 或分支。
 
 | Workflow | 适用场景 | 步骤链 |
 |----------|----------|--------|
-| `feature-development` | 开发新功能或新能力 | `analysis -> design -> implementation -> review -> fix -> commit` |
-| `bug-fix` | 诊断并修复缺陷，同时补回归验证 | `analysis -> design -> implementation -> review -> fix -> commit` |
-| `refactoring` | 进行应保持行为稳定的结构性重构 | `analysis -> design -> implementation -> review -> fix -> commit` |
+| `feature-development` | 开发新功能或新能力 | `analysis -> analysis-review -> design -> design-review -> code -> code-review -> commit` |
+| `bug-fix` | 诊断并修复缺陷，同时补回归验证 | `analysis -> analysis-review -> design -> design-review -> code -> code-review -> commit` |
+| `refactoring` | 进行应保持行为稳定的结构性重构 | `analysis -> analysis-review -> design -> design-review -> code -> code-review -> commit` |
 | `code-review` | 审查已有 Pull Request 或分支 | `analysis -> review -> report` |
 
 ### 生命周期示例
@@ -721,20 +744,33 @@ import-issue #42                    从 GitHub Issue 导入任务
   analyze-task T1                   需求分析
          |
          v
-    plan-task T1                    设计方案  <-- 人工审查
+  review-analysis T1                审查需求分析
+         |
+     有问题?
+      +--YES----> analyze-task T1
+      |
+         v
+    plan-task T1                    设计方案
+         |
+         v
+  review-plan T1                    审查技术方案
+         |
+     有问题?
+      +--YES----> plan-task T1
+      |
          |
          v
-  implement-task T1                 编写代码与测试
+  code-task T1                      编写代码与测试
          |
          v
-  +-> review-task T1                自动代码审查
+  +-> review-code T1                自动代码审查
   |      |
   |   有问题?
   |      +--NO-------+
   |     YES          |
   |      |           |
   |      v           |
-  |  refine-task T1  |
+  |  code-task T1 (fix mode)
   |      |           |
   +------+           |
                      |
@@ -760,7 +796,7 @@ import-issue #42                    从 GitHub Issue 导入任务
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateVersion": "v0.6.4",
+  "templateVersion": "v0.6.5",
   "templates": {
     "sources": [
       { "type": "local", "path": "~/private-templates" }

package/bin/cli.ts

@@ -13,12 +13,13 @@ if (major < 22) {
 const USAGE = `agent-infra ${VERSION} - bootstrap AI collaboration infrastructure
 
 Usage:
-  agent-infra init        Initialize a new project with update-agent-infra seed command
-  agent-infra merge       Merge tasks from another workspace directory (active/blocked/completed/archive)
-  agent-infra update      Update seed files and sync file registry for an existing project
-  agent-infra sandbox     Manage Docker-based AI sandboxes
-  agent-infra version     Show version
-  agent-infra help        Show this help message
+  agent-infra cp <ssh-alias>  Copy local clipboard image to a remote macOS NSPasteboard
+  agent-infra help            Show this help message
+  agent-infra init            Initialize a new project with update-agent-infra seed command
+  agent-infra merge           Merge tasks from another workspace directory (active/blocked/completed/archive)
+  agent-infra sandbox         Manage Docker-based AI sandboxes
+  agent-infra update          Update seed files and sync file registry for an existing project
+  agent-infra version         Show version
 
 Shorthand: ai (e.g. ai init)
 
@@ -96,6 +97,17 @@ switch (command) {
     });
     break;
   }
+  case 'cp': {
+    const imported = await importCommand('../lib/cp.ts');
+    if (!imported) break;
+    const { cmdCp } = imported;
+    const code = await cmdCp(process.argv.slice(3)).catch((e: unknown) => {
+      process.stderr.write(`Error: ${errorMessage(e)}\n`);
+      return 1;
+    });
+    if (code) process.exitCode = code;
+    break;
+  }
   case 'version': {
     if (process.argv[3] === '--raw') {
       console.log(VERSION);

package/dist/bin/cli.js

@@ -17,12 +17,13 @@ if (major < 22) {
 const USAGE = `agent-infra ${VERSION} - bootstrap AI collaboration infrastructure
 
 Usage:
-  agent-infra init        Initialize a new project with update-agent-infra seed command
-  agent-infra merge       Merge tasks from another workspace directory (active/blocked/completed/archive)
-  agent-infra update      Update seed files and sync file registry for an existing project
-  agent-infra sandbox     Manage Docker-based AI sandboxes
-  agent-infra version     Show version
-  agent-infra help        Show this help message
+  agent-infra cp <ssh-alias>  Copy local clipboard image to a remote macOS NSPasteboard
+  agent-infra help            Show this help message
+  agent-infra init            Initialize a new project with update-agent-infra seed command
+  agent-infra merge           Merge tasks from another workspace directory (active/blocked/completed/archive)
+  agent-infra sandbox         Manage Docker-based AI sandboxes
+  agent-infra update          Update seed files and sync file registry for an existing project
+  agent-infra version         Show version
 
 Shorthand: ai (e.g. ai init)
 
@@ -99,6 +100,19 @@ switch (command) {
         });
         break;
     }
+    case 'cp': {
+        const imported = await importCommand('../lib/cp.ts');
+        if (!imported)
+            break;
+        const { cmdCp } = imported;
+        const code = await cmdCp(process.argv.slice(3)).catch((e) => {
+            process.stderr.write(`Error: ${errorMessage(e)}\n`);
+            return 1;
+        });
+        if (code)
+            process.exitCode = code;
+        break;
+    }
     case 'version': {
         if (process.argv[3] === '--raw') {
             console.log(VERSION);