@fitlab-ai/agent-infra 0.9.1 → 0.9.3

package/templates/.agents/rules/review-method.zh-CN.md

@@ -0,0 +1,98 @@
+# 通用检视方法
+
+本规则定义 `analysis`、`plan` 和 `code` 三个审查阶段共用的轻量检视协议。阶段专属检查项留在各 skill 的 `reference/review-criteria.md`；finding 状态机、人工裁决和账本写入继续以 [review-handshake.md](review-handshake.md) 为准；风险镜头只承载命中某类风险后必须加载的专项 reference。
+
+## 职责边界
+
+- 本规则规定审查顺序、证据形状和完成条件，不复制阶段 checklist。
+- 风险镜头由可观察证据触发；命中后必须读取全部对应 reference，并在报告留证。
+- 自动化检查提供事实，reviewer 负责完整性、影响、严重度、置信度和反证等语义判断。
+- 报告结构证明审查声明可追溯，不等于自动证明语义判断正确。
+
+## Readiness
+
+形成候选 finding 前必须确认：
+
+1. 任务、输入 artifact、上游来源和审查范围已解析且可读。
+2. skill 要求的状态快照、差异或其他事实证据已捕获。
+3. 本轮实际审查的 artifact、基线和上下文边界可在报告中准确标识。
+
+任一前置项缺失时，不得给出通过结论；按所属 skill 的阻塞或失败路径处理。
+
+## 多遍检视协议
+
+按顺序执行以下五遍；每遍都在报告的检视覆盖表中记录范围、证据、结果与缺口/假设。
+
+1. **Pass 1 — 原始证据**：先读任务来源、上游 artifact、变更和测试等原始证据，独立形成候选问题，避免被执行方摘要锚定。
+2. **Pass 2 — 追踪与边界**：建立来源—需求—方案—实现—测试追踪，识别遗漏、断链和意外范围扩张。
+3. **Pass 3 — 风险镜头**：依据完整上下文逐项判断注册表触发器，加载所有命中的专项 reference，并记录命中证据与结果。
+4. **Pass 4 — 反证**：主动寻找能推翻或降级每个候选 finding 的证据，并检查放行结论可能失败的反例。
+5. **Pass 5 — 归类与收敛**：将问题归为 finding、manual-validation 或 advisory，核对证据契约、账本意图、未验证假设和 verdict。
+
+## 风险镜头注册表
+
+注册行使用稳定字段：`lens_id` 标识镜头，`stages` 限定阶段，`observable_trigger` 给出可观察触发条件，`required_reference` 是命中后必读路径，`report_evidence` 规定报告留证。
+
+| lens_id | stages | observable_trigger | required_reference | report_evidence |
+|---------|--------|--------------------|--------------------|-----------------|
+| documentation-antipatterns | code | 完整变更上下文触及描述当前行为的 Markdown、规则、skill、CLI 帮助或用户文档 | `.agents/skills/review-code/reference/documentation-antipatterns.md` | 记录触发文件、`loaded=yes` 与检视结果 |
+| testing-discipline | code | 完整变更上下文触及测试、fixture、snapshot 或测试 helper | `.agents/rules/testing-discipline.md` | 记录触发文件、`loaded=yes` 与测试纪律结论 |
+| security-risks | code | 认证授权、非可信输入、敏感数据、凭据、加密、依赖或系统边界发生变化 | `.agents/skills/review-code/reference/security-risks.md` | 记录安全边界变化、`loaded=yes` 与检视结果 |
+| migration-risks | code | 持久化格式、schema、配置/frontmatter、兼容读取或迁移/回滚发生变化 | `.agents/skills/review-code/reference/migration-risks.md` | 记录兼容或迁移触发证据、`loaded=yes` 与检视结果 |
+| concurrency-risks | code | 异步协调、共享状态、锁、重试、幂等、竞态、取消或超时发生变化 | `.agents/skills/review-code/reference/concurrency-risks.md` | 记录并发触发路径、`loaded=yes` 与检视结果 |
+| cross-platform-risks | code | OS 分支、路径、shell、权限、符号链接、换行、信号或跨平台行为发生变化 | `.agents/skills/review-code/reference/cross-platform-risks.md` | 记录平台触发证据、`loaded=yes` 与检视结果 |
+
+未命中镜头也必须记录可复核的未命中证据。`loaded` 只使用 `yes`、`no`、`not-applicable`；命中但未加载时不得给出通过结论。
+
+## 自动化与语义判断
+
+| 来源 | 可支持的事实 | 不可替代的语义判断 |
+|------|--------------|--------------------|
+| snapshot、diff、link、test、artifact gate | 文件、范围、命令结果、引用存在、章节存在 | 需求是否完整、设计是否合理、实现是否正确 |
+| 追踪矩阵 | 显式映射及可见缺口 | 映射是否充分、缺口影响和优先级 |
+| 风险镜头记录 | 触发证据、加载状态、专项结果入口 | 风险是否可接受、finding 严重度与置信度 |
+
+自动化结果与语义结论冲突时，报告必须分别记录事实与推理，不得把结构 gate 的通过写成语义完整性的证明。
+
+## 上下文覆盖与追踪契约
+
+报告必须包含两张覆盖表：
+
+| pass_id | scope | evidence | result | gaps_or_assumptions |
+|---------|-------|----------|--------|---------------------|
+| pass-1..5 | 本遍实际覆盖范围 | 可定位的 artifact、文件、命令或行号 | 发现或结论 | 未覆盖项、缺口或假设 |
+
+| lens_id | trigger_evidence | loaded | result |
+|---------|------------------|--------|--------|
+| 注册表 token | 命中或未命中的可复核证据 | yes / no / not-applicable | 专项检视结论 |
+
+并包含统一追踪矩阵：
+
+| source_id | upstream | reviewed_target | verification | status_or_gap |
+|-----------|----------|-----------------|--------------|---------------|
+| 稳定来源标识 | 上游需求、决策或步骤 | 本阶段被审对象 | 自动化或人工证据 | covered / gap 及影响 |
+
+analysis 阶段追踪来源到需求、验收、影响和风险；plan 阶段追踪已批准需求到设计决策、步骤和测试策略；code 阶段追踪需求/方案到 diff 与自动化测试或人工校验。
+
+## Finding 证据契约
+
+每个 blocker 或 major finding 必须包含：
+
+1. **场景**：触发问题的前置条件和路径。
+2. **影响**：对正确性、安全、交付或验收的具体后果。
+3. **证据**：可复现的 artifact、`file:line`、命令和原始结果。
+4. **置信度**：稳定 token `high`、`medium` 或 `low`。
+5. **未验证假设**：尚未直接证明、若被推翻会改变结论的假设；没有则明确写无。
+6. **修复方向**：可执行的最小修复目标，不替执行方越权重设计。
+
+minor 保持轻量，但仍须提供具体位置和可执行建议。finding ledger 的 `evidence` 继续指向报告中的稳定锚点，不新增账本字段。manual-validation、advisory 和 `needs-human-decision` 按 review handshake 与阶段规则处理。
+
+## Completion
+
+只有同时满足以下条件才可形成最终 verdict：
+
+- 五遍检视均已记录范围、证据、结果和缺口/假设。
+- 所有风险触发器均有命中判断，命中镜头均已加载并留证。
+- 追踪矩阵覆盖本阶段职责，缺口已进入 finding、manual-validation、advisory 或明确假设。
+- 所有 blocker/major 满足统一证据契约，候选 finding 已完成反证检视。
+- 账本意图、人工校验、待裁决项、未验证假设与问题计数一致。

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

@@ -19,6 +19,17 @@ Map user intent to the corresponding workflow command:
 - Before updating `agent_infra_version`, read `.agents/rules/version-stamp.md`
 - Activity Log entries are append-only and must never overwrite history
 
+## Collaborator Token Specification
+
+`--agent` values must converge on the standard AI collaborator tokens; OS usernames (e.g. `devuser`) and git usernames (e.g. a human name) are forbidden. The standard set (short tokens are the single source of truth for the activity log):
+
+- AI short tokens: `claude` / `codex` / `antigravity` / `opencode` / `cursor`
+- Long-name mapping (normalized to the short token before writing): `claude-code` -> `claude`, `antigravity-cli` -> `antigravity`
+- Historical `gemini` / `gemini-cli` remain read-only for `ai task log` rendering and are not writable
+- Manual-step exception: no matter which agent is used, a human-made decision is always declared as `human`
+
+The six internal commands (`task-event` / `task-lifecycle` / `platform-issue` / `platform-comment` / `platform-pr` / `task-orchestration`) hard-validate `--agent` against a whitelist: they accept a short token, a long name, or `human`, and reject non-standard values with the matching `*_PAYLOAD_INVALID` error; long names are normalized to the short token before being persisted or forwarded. The `ai task log` renderer keeps unknown tokens grouped as `human` but appends a visible `(unknown)` marker.
+
 ## State Snapshot and Completion Verification Entrypoints
 
 - Runtime skills that record git, task-directory, and task.md tail evidence must call `agent-infra-internal task-snapshot {task-id} --format text`; they must not resolve short ids, scan workspaces, or reconstruct the three observations themselves.

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

@@ -19,6 +19,17 @@
 - 更新 `agent_infra_version` 前，先读取 `.agents/rules/version-stamp.md`
 - Activity Log 只能追加，不能覆盖历史记录
 
+## 合作者 token 规范
+
+`--agent` 取值必须收敛到标准 AI 合作者 token，禁止填入 OS 系统用户名（如 `devuser`）或 git 用户名（如 `季聿阶`）。标准集合（短名为活动日志唯一事实来源）：
+
+- AI 短名：`claude` / `codex` / `antigravity` / `opencode` / `cursor`
+- 长名映射（写入前归一化为短名）：`claude-code` → `claude`、`antigravity-cli` → `antigravity`
+- 历史 `gemini` / `gemini-cli` 仅保留 `ai task log` 渲染兼容，不接受写入
+- 人工步骤例外：无论使用哪个 Agent，只要是人做的决定，统一声明 `human`
+
+六个内部命令（`task-event` / `task-lifecycle` / `platform-issue` / `platform-comment` / `platform-pr` / `task-orchestration`）对 `--agent` 做白名单硬校验：接受短名、长名或 `human`，非标准值返回对应 `*_PAYLOAD_INVALID` 错误；长名在落库/透传前归一化为短名。渲染端 `ai task log` 对无法识别的 token 保留 `human` 归类并附加 `(unknown)` 标记。
+
 ## 状态快照与完成验证入口
 
 - 运行时 SKILL 需要记录 git、任务目录和 task.md tail 证据时，统一调用 `agent-infra-internal task-snapshot {task-id} --format text`；不得自行解析短号、扫描 workspace 或重新拼接三段状态命令。

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

@@ -7,6 +7,9 @@ description: >
 ---
 
 # Analyze Task
+> `--agent` values follow the "Collaborator Token Specification" in `.agents/rules/task-management.md`: standard AI short tokens (`claude`/`codex`/`antigravity`/`opencode`/`cursor`), long-name normalization (`claude-code`->`claude`, `antigravity-cli`->`antigravity`), or the `human` manual exception.
+
+If the entry operands contain `--orchestrated`, bind `{execution-flag}` to `--orchestrated` and forward it unchanged to the completed event; otherwise bind it to an empty value. Never infer it from `orchestration.json`, environment variables, or prior artifacts.
 
 ## Boundary / Critical Rules
 
@@ -36,7 +39,7 @@ Before the state check is complete, do not make external-state assertions such a
 
 ## Step Start: Declare the started Event
 
-After resolving the artifact context and before this round's first artifact action, run `agent-infra-internal task-event {task-id} analyze.started --agent {agent}` and verify the returned `artifactContext`.
+After resolving the artifact context and before this round's first artifact action, run `agent-infra-internal task-event {task-id} analyze.started --agent {standard-agent-token}` and verify the returned `artifactContext`.
 
 ## Steps
 
@@ -103,8 +106,8 @@ Runs after Step 0 state check and Step 3 (questioning is an external-state actio
   1. Decide this round's question (consistent with 4.2):
      - if a `pending_question` already exists (the previous question is still unanswered) → restate that `pending_question`, do **not** modify it and do **not** increment `question_count`;
      - otherwise (no pending question) → pick the single highest-value question (acceptance criteria > scope > ambiguity) and write `## Brainstorming`: `status: asking`, `pending_question: <question>`, `question_count += 1`.
-  2. If `start_date` is empty, write today (`date +%F`), then run `agent-infra-internal task-event {task-id} analyze.awaiting-input --agent {agent} --question {question_count}` so the core updates base metadata and Activity Log.
-  3. Issue sync (when `issue_number` exists, skip on any failure): run `agent-infra-internal platform-comment sync {task-id} --kind task --agent {agent}` to update only the **task comment**; keep the `status` label at `pending-design-work`; do **not** publish an analysis artifact comment.
+  2. If `start_date` is empty, write today (`date +%F`), then run `agent-infra-internal task-event {task-id} analyze.awaiting-input --agent {standard-agent-token} --question {question_count}` so the core updates base metadata and Activity Log.
+  3. Issue sync (when `issue_number` exists, skip on any failure): run `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}` to update only the **task comment**; keep the `status` label at `pending-design-work`; do **not** publish an analysis artifact comment.
   4. Verification (replaces the step 8 artifact gate): `agent-infra-internal task-verify {task-id} analyze.awaiting-input --format text` (the early-exit set `current_step: requirement-analysis` and wrote `start_date`, so it should pass); also keep `rg -n 'Analyze Task \(Brainstorming\)' .agents/workspace/active/{task-id}/task.md` and the task-comment sync evidence. Do **not** run the artifact gate, nor `check activity-log` / `check platform-sync` (both bind to the analysis artifact path).
   5. User output: show only the current **single question** plus how to answer/continue (re-trigger `analyze-task {task-ref}` with the answer), and append the `Completed at` line per `.agents/rules/next-step-output.md`.
   6. **STOP** and wait for the answer. The next trigger returns to this step.
@@ -198,14 +201,14 @@ Update `.agents/workspace/active/{task-id}/task.md`:
   - Overwrite the `priority` field in frontmatter with the new value
   - Append a `## Priority Re-estimate` section to this round's analysis artifact `{analysis-artifact}`, recording: `priority {old} → {new} (rationale: {short basis grounded in this analysis})`
   If the re-estimated value matches the current value, skip it: do not write the `## Priority Re-estimate` section. The Flow A sync that follows reads the possibly updated frontmatter and propagates the new value to the Issue automatically.
-After the business fields are updated, run `agent-infra-internal task-event {task-id} analyze.completed --agent {agent} --artifact {analysis-artifact}` so the core atomically records the link, stage, agent, metadata, and Activity Log.
+After the business fields are updated, run `agent-infra-internal task-event {task-id} analyze.completed --agent {standard-agent-token} --artifact {analysis-artifact} {execution-flag}` so the core atomically records the link, stage, agent, metadata, and Activity Log.
   - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Analyze Task (Round {N})** by {agent} — Analysis completed → {analysis-artifact}
   ```
 
 If task.md contains a valid `issue_number`, perform these sync actions (skip and continue on any failure):
-- Run `agent-infra-internal platform-issue sync {task-id} --agent {agent} --status pending-design-work --fields`
-- Run `agent-infra-internal platform-comment sync {task-id} --kind task --agent {agent}`
-- Run `agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {analysis-artifact} --agent {agent}`
+- Run `agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --status pending-design-work --fields`
+- Run `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}`
+- Run `agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {analysis-artifact} --agent {standard-agent-token}`
 
 ### 8. Verification Gate
 
@@ -230,9 +233,11 @@ Keep the gate output in your reply as fresh evidence. Do not claim completion wi
 
 > Execute this step only after the verification gate passes.
 
-> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name). Before rendering the final output, read `.agents/rules/next-step-output.md` and apply both of its rules: (1) render `{task-ref}` in the "Next steps" commands as the short id `NN` (falling back to the full TASK-id when unallocated or released); (2) append the `Completed at` line as the very last line of the user-facing output (this applies to every user-facing output — success, error, and early-return paths alike, not only the success path).
+> Before rendering next steps, read `.agents/rules/next-step-output.md`, invoke the shared helper only for the selected scenario, and insert its stdout at `{next-step-commands}`.
 
 Output format:
+Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill review-analysis --task-ref {task-ref}`.
+
 ```
 Analysis complete for task {task-id}.
 
@@ -245,9 +250,7 @@ Output file:
 - Analysis report: .agents/workspace/active/{task-id}/{analysis-artifact}
 
 Next step - review the analysis:
-  - Claude Code / OpenCode: /review-analysis {task-ref}
-  - Gemini CLI: /{{project}}:review-analysis {task-ref}
-  - Codex CLI: $review-analysis {task-ref}
+{next-step-commands}
 ```
 
 ## Completion Checklist
@@ -259,7 +262,7 @@ Next step - review the analysis:
 - [ ] Updated `assigned_to` in task.md
 - [ ] Appended an Activity Log entry to task.md
 - [ ] Marked requirement-analysis as complete in workflow progress
-- [ ] Informed the user of the next step (must include all TUI command formats, including any custom TUIs; do not filter)
+- [ ] Rendered the selected next-step commands through the shared helper
 - [ ] **Did not modify any business code**
 
 ## STOP

package/templates/.agents/skills/analyze-task/SKILL.zh-CN.md

@@ -7,6 +7,9 @@ description: >
 ---
 
 # 分析任务
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」：标准 AI 短名（`claude`/`codex`/`antigravity`/`opencode`/`cursor`）、长名归一化（`claude-code`→`claude`、`antigravity-cli`→`antigravity`）或人工例外 `human`。
+
+若入口业务操作数包含 `--orchestrated`，绑定 `{execution-flag}` = `--orchestrated` 并原样转发给 completed 事件；否则绑定为空。不得从 `orchestration.json`、环境变量或历史产物推断该标记。
 
 ## 行为边界 / 关键规则
 
@@ -39,7 +42,7 @@ agent-infra-internal task-snapshot {task-id} --format text
 确认前置条件和轮次后、本轮第一个产出动作之前执行：
 
 ```bash
-agent-infra-internal task-event {task-id} analyze.started --agent {agent}
+agent-infra-internal task-event {task-id} analyze.started --agent {standard-agent-token}
 ```
 
 ## 执行步骤
@@ -106,8 +109,8 @@ agent-infra-internal task-event {task-id} analyze.started --agent {agent}
   1. 确定本轮要问的问题（与 4.2 保持一致）：
      - 若已存在 `pending_question`（上一问尚未得到答案）→ 复述该 `pending_question`，**不**修改它、**不**增加 `question_count`；
      - 否则（无待答问题）→ 选最高价值的一个问题（验收标准 > 范围 > 歧义），写入 `## Brainstorming`：`status: asking`、`pending_question: <问题>`、`question_count += 1`。
-  2. 若 `start_date` 为空，写入当日日期（`date +%F`）；随后执行 `agent-infra-internal task-event {task-id} analyze.awaiting-input --agent {agent} --question {question_count}`，由核心统一更新基础 frontmatter 和 Activity Log。
-  3. Issue 同步（存在 `issue_number` 时，任一失败跳过）：调用 `agent-infra-internal platform-comment sync {task-id} --kind task --agent {agent}` 更新 **task 评论**；`status` label 维持 `pending-design-work`；**不**发布分析产物评论。
+  2. 若 `start_date` 为空，写入当日日期（`date +%F`）；随后执行 `agent-infra-internal task-event {task-id} analyze.awaiting-input --agent {standard-agent-token} --question {question_count}`，由核心统一更新基础 frontmatter 和 Activity Log。
+  3. Issue 同步（存在 `issue_number` 时，任一失败跳过）：调用 `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}` 更新 **task 评论**；`status` label 维持 `pending-design-work`；**不**发布分析产物评论。
   4. 校验（替代步骤 8 的 artifact gate）：`agent-infra-internal task-verify {task-id} analyze.awaiting-input --format text`（早退已置 `current_step: requirement-analysis` 且已写入 `start_date`，预期通过）；并保留 `rg -n 'Analyze Task \(Brainstorming\)' .agents/workspace/active/{task-id}/task.md` 与 task 评论同步证据。**不**跑 artifact gate，也不跑 `check activity-log` / `check platform-sync`（二者绑定分析产物路径）。
   5. 用户输出：只展示当前**单个问题** + 如何回答/继续（再次触发 `analyze-task {task-ref}` 并附答案），并按 `.agents/rules/next-step-output.md` 在末行追加 `Completed at`。
   6. **STOP**，等待回答。下一次触发回到本步骤。
@@ -199,12 +202,12 @@ agent-infra-internal task-event {task-id} analyze.started --agent {agent}
   - 用新值覆盖 frontmatter 的 `priority` 字段
   - 在本轮分析产物 `{analysis-artifact}` 中追加 `## 优先级重估` 段，记录一条：`priority {old} → {new} (rationale: {基于本轮分析的简短依据})`
   若重估值与当前值一致，跳过：不写入 `## 优先级重估` 段。后续 Flow A 同步会读取可能更新过的 frontmatter，并自动把新值同步到 Issue。
-- 完成业务内容更新后执行 `agent-infra-internal task-event {task-id} analyze.completed --agent {agent} --artifact {analysis-artifact}`，由核心原子登记链接、阶段、代理、时间、版本和 Activity Log。
+- 完成业务内容更新后执行 `agent-infra-internal task-event {task-id} analyze.completed --agent {standard-agent-token} --artifact {analysis-artifact} {execution-flag}`，由核心原子登记链接、阶段、代理、时间、版本和 Activity Log。
 
 如果 task.md 中存在有效的 `issue_number`，执行以下同步操作（任一失败则跳过并继续）：
-- 调用 `agent-infra-internal platform-issue sync {task-id} --agent {agent} --status pending-design-work --fields`
-- 调用 `agent-infra-internal platform-comment sync {task-id} --kind task --agent {agent}`
-- 调用 `agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {analysis-artifact} --agent {agent}`
+- 调用 `agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --status pending-design-work --fields`
+- 调用 `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}`
+- 调用 `agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {analysis-artifact} --agent {standard-agent-token}`
 
 ### 8. 完成校验
 
@@ -229,9 +232,11 @@ agent-infra-internal task-verify {task-id} analyze.completed --artifact {analysi
 
 > 仅在校验通过后执行本步骤。
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。 渲染最终输出前，先读取 `.agents/rules/next-step-output.md` 并落实其两类规则：(1) 「下一步」命令把 `{task-ref}` 渲染为短号 `NN`（未分配/已释放时回退完整 TASK-id）；(2) 在面向用户输出的绝对最后一行追加 `Completed at` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
+> 渲染下一步前先读取 `.agents/rules/next-step-output.md`，仅为已选场景调用统一 helper，并将 stdout 填入 `{next-step-commands}`。
 
 输出格式：
+使用 `agent-infra-internal agent-client next-steps --skill review-analysis --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
+
 ```
 任务 {task-id} 分析完成。
 
@@ -244,9 +249,7 @@ agent-infra-internal task-verify {task-id} analyze.completed --artifact {analysi
 - 分析报告：.agents/workspace/active/{task-id}/{analysis-artifact}
 
 下一步 - 审查需求分析：
-  - Claude Code / OpenCode：/review-analysis {task-ref}
-  - Gemini CLI：/{{project}}:review-analysis {task-ref}
-  - Codex CLI：$review-analysis {task-ref}
+{next-step-commands}
 ```
 
 ## 完成检查清单
@@ -258,7 +261,7 @@ agent-infra-internal task-verify {task-id} analyze.completed --artifact {analysi
 - [ ] 更新了 task.md 中的 `assigned_to`
 - [ ] 追加了 Activity Log 条目到 task.md
 - [ ] 在工作流进度中标记了 requirement-analysis 为已完成
-- [ ] 告知了用户下一步（必须展示所有 TUI 的命令格式，含自定义 TUI，不要筛选）
+- [ ] 已通过统一 helper 渲染已选场景的下一步命令
 - [ ] **没有修改任何业务代码**
 
 ## 停止

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

@@ -7,6 +7,8 @@ description: >
 ---
 
 # Block Task
+> `--agent` values follow the "Collaborator Token Specification" in `.agents/rules/task-management.md`: standard AI short tokens (`claude`/`codex`/`antigravity`/`opencode`/`cursor`), long-name normalization (`claude-code`->`claude`, `antigravity-cli`->`antigravity`), or the `human` manual exception.
+
 
 ## Boundary / Critical Rules
 
@@ -53,7 +55,7 @@ Before blocking, thoroughly analyze:
 ### 3. Apply the Local Lifecycle Intent
 
 ```bash
-agent-infra-internal task-lifecycle {task-id} block --agent {agent} \
+agent-infra-internal task-lifecycle {task-id} block --agent {standard-agent-token} \
   --reason "{one-line reason}" --unblock-condition "{unblock condition}"
 ```
 
@@ -73,8 +75,8 @@ ls .agents/workspace/blocked/{task-id}/task.md
 
 Check whether `task.md` includes a valid `issue_number`. If not, skip this step.
 
-If a valid `issue_number` exists, run `agent-infra-internal platform-issue sync {task-id} --agent {agent} --status blocked`.
-Then run `agent-infra-internal platform-comment sync {task-id} --kind task --agent {agent}`.
+If a valid `issue_number` exists, run `agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --status blocked`.
+Then run `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}`.
 
 ### 7. Verification Gate
 
@@ -95,11 +97,13 @@ Keep the gate output in your reply as fresh evidence. Do not claim completion wi
 
 > Execute this step only after the verification gate passes.
 
-> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name). Before rendering the final output, read `.agents/rules/next-step-output.md` and apply both of its rules: (1) render `{task-ref}` in the "Next steps" commands as the short id `NN` (falling back to the full TASK-id when unallocated or released); (2) append the `Completed at` line as the very last line of the user-facing output (this applies to every user-facing output — success, error, and early-return paths alike, not only the success path).
+> Before rendering next steps, read `.agents/rules/next-step-output.md`, invoke the shared helper only for the selected scenario, and insert its stdout at `{next-step-commands}`.
 
 > **Optional sandbox-cleanup hint (gated)**: Render the "Optional: clean up this task's sandbox" block — placed after "Archived to" and before "To unblock" in the output below — only when BOTH (1) `.agents/.airc.json` has a `sandbox` field and (2) task.md's `branch` field exists and is not `main` / `master`; otherwise omit the whole block. `{branch}` is the `branch` value from the task.md you already loaded (the task has moved to blocked/, so read it from `.agents/workspace/blocked/{task-id}/task.md`). This block is independent of "Next step" semantics.
 
 Output format:
+Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill check-task --task-ref {task-ref}`.
+
 ```
 Task {task-id} marked as blocked.
 
@@ -113,12 +117,10 @@ Optional: clean up this task's sandbox
 ai sandbox rm {branch}
 
 To unblock when the issue is resolved:
-  agent-infra-internal task-lifecycle {task-id} activate --agent {agent} --note "{activation note}"
+  agent-infra-internal task-lifecycle {task-id} activate --agent {standard-agent-token} --note "{activation note}"
 
 Next step - check task status after unblocking:
-  - Claude Code / OpenCode: /check-task {task-ref}
-  - Gemini CLI: /{{project}}:check-task {task-ref}
-  - Codex CLI: $check-task {task-ref}
+{next-step-commands}
 ```
 
 
@@ -136,7 +138,7 @@ Next step - check task status after unblocking:
 When the blocking issue is resolved:
 
 ```bash
-agent-infra-internal task-lifecycle {task-id} activate --agent {agent} --note "{activation note}"
+agent-infra-internal task-lifecycle {task-id} activate --agent {standard-agent-token} --note "{activation note}"
 ```
 
 Resume from the preserved `current_step`. On failure, retry the same intent from the structured recovery fields instead of hand-editing lifecycle state.

package/templates/.agents/skills/block-task/SKILL.zh-CN.md

@@ -7,6 +7,8 @@ description: >
 ---
 
 # 标记任务阻塞
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」：标准 AI 短名（`claude`/`codex`/`antigravity`/`opencode`/`cursor`）、长名归一化（`claude-code`→`claude`、`antigravity-cli`→`antigravity`）或人工例外 `human`。
+
 
 ## 行为边界 / 关键规则
 
@@ -52,7 +54,7 @@ description: >
 ### 3. 执行本地生命周期意图
 
 ```bash
-agent-infra-internal task-lifecycle {task-id} block --agent {agent} \
+agent-infra-internal task-lifecycle {task-id} block --agent {standard-agent-token} \
   --reason "{一行原因}" --unblock-condition "{解除阻塞条件}"
 ```
 
@@ -74,8 +76,8 @@ ls .agents/workspace/blocked/{task-id}/task.md
 
 检查 `task.md` 中是否存在有效的 `issue_number`。如果没有，跳过。
 
-如果存在有效的 `issue_number`，调用 `agent-infra-internal platform-issue sync {task-id} --agent {agent} --status blocked`。
-随后调用 `agent-infra-internal platform-comment sync {task-id} --kind task --agent {agent}` 更新 task 评论。
+如果存在有效的 `issue_number`，调用 `agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --status blocked`。
+随后调用 `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}` 更新 task 评论。
 
 ### 7. 完成校验
 
@@ -96,11 +98,13 @@ agent-infra-internal task-verify {task-id} block-task.completed --format text
 
 > 仅在校验通过后执行本步骤。
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。 渲染最终输出前，先读取 `.agents/rules/next-step-output.md` 并落实其两类规则：(1) 「下一步」命令把 `{task-ref}` 渲染为短号 `NN`（未分配/已释放时回退完整 TASK-id）；(2) 在面向用户输出的绝对最后一行追加 `Completed at` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
+> 渲染下一步前先读取 `.agents/rules/next-step-output.md`，仅为已选场景调用统一 helper，并将 stdout 填入 `{next-step-commands}`。
 
 > **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) task.md 的 `branch` 字段存在且不是 `main` / `master` 时，才渲染下方输出中「归档路径」之后、「解除阻塞时执行」之前的「可选：清理本任务的沙箱」块；任一不满足则整段省略。`{branch}` 取已读入的 task.md 的 `branch` 值（任务此时已移动到 blocked/，从 `.agents/workspace/blocked/{task-id}/task.md` 读取）。该块独立于「下一步」语义。
 
 输出格式：
+使用 `agent-infra-internal agent-client next-steps --skill check-task --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
+
 ```
 任务 {task-id} 已标记为阻塞。
 
@@ -114,12 +118,10 @@ agent-infra-internal task-verify {task-id} block-task.completed --format text
 ai sandbox rm {branch}
 
 解除阻塞时执行：
-  agent-infra-internal task-lifecycle {task-id} activate --agent {agent} --note "{恢复说明}"
+  agent-infra-internal task-lifecycle {task-id} activate --agent {standard-agent-token} --note "{恢复说明}"
 
 下一步 - 检查任务状态（解除阻塞后）：
-  - Claude Code / OpenCode：/check-task {task-ref}
-  - Gemini CLI：/{{project}}:check-task {task-ref}
-  - Codex CLI：$check-task {task-ref}
+{next-step-commands}
 ```
 
 
@@ -137,7 +139,7 @@ ai sandbox rm {branch}
 当阻塞问题解决后：
 
 ```bash
-agent-infra-internal task-lifecycle {task-id} activate --agent {agent} --note "{恢复说明}"
+agent-infra-internal task-lifecycle {task-id} activate --agent {standard-agent-token} --note "{恢复说明}"
 ```
 
 成功后从保留的 `current_step` 继续。失败时按结构化 recovery 字段以同一 intent 重试，不手工移动目录或编辑基础元数据。

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

@@ -7,6 +7,8 @@ description: >
 ---
 
 # Cancel Task
+> `--agent` values follow the "Collaborator Token Specification" in `.agents/rules/task-management.md`: standard AI short tokens (`claude`/`codex`/`antigravity`/`opencode`/`cursor`), long-name normalization (`claude-code`->`claude`, `antigravity-cli`->`antigravity`), or the `human` manual exception.
+
 
 ## Boundary / Critical Rules
 
@@ -53,7 +55,7 @@ When syncing to the Issue, replace any existing `status:` labels with the inferr
 ### 3. Apply the Local Lifecycle Intent
 
 ```bash
-agent-infra-internal task-lifecycle {task-id} cancel --agent {agent} --reason "{one-line cancellation reason}"
+agent-infra-internal task-lifecycle {task-id} cancel --agent {standard-agent-token} --reason "{one-line cancellation reason}"
 ```
 
 Only `status=applied|no-op` means local cancellation completed. On `status=failed`, show the structured error and recovery steps and retry the same intent; do not manually edit task.md, move the directory, or release the short id.
@@ -75,9 +77,9 @@ Confirm the task directory was moved successfully.
 Check whether `task.md` contains a valid `issue_number`. If not, skip this step.
 
 If a valid `issue_number` exists:
-- Run `agent-infra-internal platform-issue sync {task-id} --agent {agent} --status {reason} --in-labels none --assignees none --milestone none --state closed --close-reason not_planned`
-- Write the cancellation body to a temporary file and run `agent-infra-internal platform-comment sync {task-id} --kind cancel --body-file {path} --agent {agent}`
-- Run `agent-infra-internal platform-comment sync {task-id} --kind task --agent {agent}`
+- Run `agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --status {reason} --in-labels none --assignees none --milestone none --state closed --close-reason not_planned`
+- Write the cancellation body to a temporary file and run `agent-infra-internal platform-comment sync {task-id} --kind cancel --body-file {path} --agent {standard-agent-token}`
+- Run `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}`
 
 The cancellation comment must include at least:
 - the cancellation reason
@@ -102,11 +104,13 @@ Keep the gate output in your reply as fresh evidence. Do not claim completion wi
 
 > Execute this step only after the verification gate passes.
 
-> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name). Before rendering the final output, read `.agents/rules/next-step-output.md` and apply both of its rules: (1) render `{task-ref}` in the "Next steps" commands as the short id `NN` (falling back to the full TASK-id when unallocated or released); (2) append the `Completed at` line as the very last line of the user-facing output (this applies to every user-facing output — success, error, and early-return paths alike, not only the success path).
+> Before rendering next steps, read `.agents/rules/next-step-output.md`, invoke the shared helper only for the selected scenario, and insert its stdout at `{next-step-commands}`.
 
 > **Optional sandbox-cleanup hint (gated)**: Render the "Optional: clean up this task's sandbox" block — placed after "Target path" and before "Next step" in the output below — only when BOTH (1) `.agents/.airc.json` has a `sandbox` field and (2) task.md's `branch` field exists and is not `main` / `master`; otherwise omit the whole block. `{branch}` is the `branch` value from the task.md you already loaded (the task has moved to completed/, so read it from `.agents/workspace/completed/{task-id}/task.md`). This block is independent of "Next steps" semantics.
 
 Output format:
+Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill check-task --task-ref {task-ref}`.
+
 ```
 Task {task-id} cancelled; task directory moved to completed/.
 
@@ -120,9 +124,7 @@ Optional: clean up this task's sandbox
 ai sandbox rm {branch}
 
 Next step - inspect the moved task:
-  - Claude Code / OpenCode: /check-task {task-ref}
-  - Gemini CLI: /{{project}}:check-task {task-ref}
-  - Codex CLI: $check-task {task-ref}
+{next-step-commands}
 ```
 
 

package/templates/.agents/skills/cancel-task/SKILL.zh-CN.md

@@ -7,6 +7,8 @@ description: >
 ---
 
 # 取消任务
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」：标准 AI 短名（`claude`/`codex`/`antigravity`/`opencode`/`cursor`）、长名归一化（`claude-code`→`claude`、`antigravity-cli`→`antigravity`）或人工例外 `human`。
+
 
 ## 行为边界 / 关键规则
 
@@ -52,7 +54,7 @@ description: >
 ### 3. 执行本地生命周期意图
 
 ```bash
-agent-infra-internal task-lifecycle {task-id} cancel --agent {agent} --reason "{一行取消原因}"
+agent-infra-internal task-lifecycle {task-id} cancel --agent {standard-agent-token} --reason "{一行取消原因}"
 ```
 
 仅 `status=applied|no-op` 视为本地取消完成。`status=failed` 时展示结构化 `error` 与 recovery steps，并以同一 intent 重试；不得手工编辑 task.md、移动目录或释放短号。
@@ -74,9 +76,9 @@ ls .agents/workspace/completed/{task-id}/task.md
 检查 `task.md` 中是否存在有效的 `issue_number`。如果没有，跳过此步骤。
 
 如果存在有效的 `issue_number`：
-- 调用 `agent-infra-internal platform-issue sync {task-id} --agent {agent} --status {reason} --in-labels none --assignees none --milestone none --state closed --close-reason not_planned`
-- 将取消正文写入临时文件，调用 `agent-infra-internal platform-comment sync {task-id} --kind cancel --body-file {path} --agent {agent}`
-- 调用 `agent-infra-internal platform-comment sync {task-id} --kind task --agent {agent}`
+- 调用 `agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --status {reason} --in-labels none --assignees none --milestone none --state closed --close-reason not_planned`
+- 将取消正文写入临时文件，调用 `agent-infra-internal platform-comment sync {task-id} --kind cancel --body-file {path} --agent {standard-agent-token}`
+- 调用 `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}`
 
 取消评论至少包含：
 - 取消原因
@@ -101,11 +103,13 @@ agent-infra-internal task-verify {task-id} cancel-task.completed --format text
 
 > 仅在校验通过后执行本步骤。
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。 渲染最终输出前，先读取 `.agents/rules/next-step-output.md` 并落实其两类规则：(1) 「下一步」命令把 `{task-ref}` 渲染为短号 `NN`（未分配/已释放时回退完整 TASK-id）；(2) 在面向用户输出的绝对最后一行追加 `Completed at` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
+> 渲染下一步前先读取 `.agents/rules/next-step-output.md`，仅为已选场景调用统一 helper，并将 stdout 填入 `{next-step-commands}`。
 
 > **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) task.md 的 `branch` 字段存在且不是 `main` / `master` 时，才渲染下方输出中「目标路径」之后、「下一步」之前的「可选：清理本任务的沙箱」块；任一不满足则整段省略。`{branch}` 取已读入的 task.md 的 `branch` 值（任务此时已移动到 completed/，从 `.agents/workspace/completed/{task-id}/task.md` 读取）。该块独立于「下一步」语义。
 
 输出格式：
+使用 `agent-infra-internal agent-client next-steps --skill check-task --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
+
 ```
 任务 {task-id} 已取消，任务目录已转移到 completed/。
 
@@ -119,9 +123,7 @@ agent-infra-internal task-verify {task-id} cancel-task.completed --format text
 ai sandbox rm {branch}
 
 下一步 - 查看已转移任务：
-  - Claude Code / OpenCode：/check-task {task-ref}
-  - Gemini CLI：/{{project}}:check-task {task-ref}
-  - Codex CLI：$check-task {task-ref}
+{next-step-commands}
 ```
 
 
@@ -132,7 +134,7 @@ ai sandbox rm {branch}
 - [ ] 已将任务目录移动到 `.agents/workspace/completed/`
 - [ ] 已在存在 Issue 时完成 Issue 同步
 - [ ] 已运行 gate 校验并通过
-- [ ] 已向用户展示完整的下一步命令（含自定义 TUI）
+- [ ] 已通过统一 helper 渲染已选场景的下一步命令
 
 ## 注意事项
 

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

@@ -59,7 +59,7 @@ Workflow progress:
 
 ### 3. Recommend Next Action
 
-Recommend the appropriate next skill based on the current workflow state. You must show command formats for all TUI columns in the table below, not just the current AI agent. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name).
+Recommend the appropriate next skill based on the current workflow state.
 
 > **⚠️ CONDITION CHECK — you must choose the single matching row in the table below based on `status`, `current_step`, the latest artifacts, and the latest review result:**
 >
@@ -77,21 +77,21 @@ Recommend the appropriate next skill based on the current workflow state. You mu
 >
 > **Important: if the latest review report contains any issue at all, do not use the corresponding review-passed row. Use the corresponding has-issues row instead.**
 >
-> Before rendering the final output, read `.agents/rules/next-step-output.md` and apply both of its rules: (1) render `{task-ref}` in the table commands below as the short id `NN` (falling back to the full TASK-id when unallocated or released); (2) append the `Completed at` line as the very last line of the user-facing output (this applies to every user-facing output — success, error, and early-return paths alike, not only the success path).
-
-| Current State              | Claude Code / OpenCode                              | Gemini CLI                               | Codex CLI                                           |
-|----------------------------|-----------------------------------------------------|------------------------------------------|-----------------------------------------------------|
-| Analysis Complete          | `/review-analysis {task-ref}`                        | `/{{project}}:review-analysis {task-ref}` | `$review-analysis {task-ref}`                        |
-| Analysis Review Passed     | `/plan-task {task-ref}`                              | `/{{project}}:plan-task {task-ref}`       | `$plan-task {task-ref}`                              |
-| Analysis Review Has Issues | `/analyze-task {task-ref}`                           | `/{{project}}:analyze-task {task-ref}`    | `$analyze-task {task-ref}`                           |
-| Plan Complete              | `/review-plan {task-ref}`                            | `/{{project}}:review-plan {task-ref}`     | `$review-plan {task-ref}`                            |
-| Plan Review Passed         | `/code-task {task-ref}`                              | `/{{project}}:code-task {task-ref}`       | `$code-task {task-ref}`                              |
-| Plan Review Has Issues     | `/plan-task {task-ref}`                              | `/{{project}}:plan-task {task-ref}`       | `$plan-task {task-ref}`                              |
-| Code Complete              | `/review-code {task-ref}`                            | `/{{project}}:review-code {task-ref}`     | `$review-code {task-ref}`                            |
-| Code Review Passed         | `/commit`                                           | `/{{project}}:commit`                    | `$commit`                                           |
-| Code Review Has Issues     | `/code-task {task-ref}`                              | `/{{project}}:code-task {task-ref}`       | `$code-task {task-ref}`                              |
-| Task Blocked               | Unblock the task or provide the missing information | —                                        | Unblock the task or provide the missing information |
-| Task Completed             | No action needed                                    | —                                        | No action needed                                    |
+> Before rendering the final output, read `.agents/rules/next-step-output.md`. After selecting an actionable row, invoke `agent-infra-internal agent-client next-steps --skill {next-skill} [--task-ref {task-ref}]` exactly once and render stdout verbatim as `{next-step-commands}`. Do not invoke the helper for `Task Blocked` or `Task Completed`. Append the `Completed at` trailing line last.
+
+| Current State              | next skill        | task ref |
+|----------------------------|-------------------|----------|
+| Analysis Complete          | `review-analysis` | required |
+| Analysis Review Passed     | `plan-task`       | required |
+| Analysis Review Has Issues | `analyze-task`    | required |
+| Plan Complete              | `review-plan`     | required |
+| Plan Review Passed         | `code-task`       | required |
+| Plan Review Has Issues     | `plan-task`       | required |
+| Code Complete              | `review-code`     | required |
+| Code Review Passed         | `commit`          | omitted  |
+| Code Review Has Issues     | `code-task`       | required |
+| Task Blocked               | —                 | —        |
+| Task Completed             | —                 | —        |
 
 ## Notes