@fitlab-ai/agent-infra 0.9.1 → 0.9.2

package/templates/.agents/rules/review-method.en.md

@@ -0,0 +1,113 @@
+# Shared Review Method
+
+This rule defines the lightweight review protocol shared by the `analysis`, `plan`,
+and `code` stages. Stage-specific checks remain in each skill's
+`reference/review-criteria.md`; finding state, human decisions, and ledger writes
+remain governed by [review-handshake.md](review-handshake.md); risk lenses only route
+an observed risk to references that must then be loaded.
+
+## Responsibility Boundary
+
+- This rule defines review order, evidence shape, and completion conditions without duplicating stage checklists.
+- Observable evidence triggers risk lenses; every matched reference must be read and recorded in the report.
+- Automation supplies facts; the reviewer judges completeness, impact, severity, confidence, and counterevidence.
+- Report structure makes review claims traceable; it does not automatically prove that semantic judgments are correct.
+
+## Readiness
+
+Before forming candidate findings, confirm that:
+
+1. The task, input artifact, upstream sources, and review scope are resolved and readable.
+2. The state snapshot, diff, or other factual evidence required by the skill has been captured.
+3. The reviewed artifact, baseline, and context boundary can be identified accurately in the report.
+
+If any prerequisite is missing, an Approved verdict is forbidden; follow the owning
+skill's blocked or failure path.
+
+## Multi-pass Review Protocol
+
+Run these five passes in order. Record each pass's scope, evidence, result, and
+gaps/assumptions in the report coverage table.
+
+1. **Pass 1 — Raw evidence**: read source requests, upstream artifacts, changes, and tests before executor summaries can anchor the review; form independent candidate issues.
+2. **Pass 2 — Traceability and boundaries**: map source → requirement → plan → implementation → test, looking for omissions, broken links, and unexpected scope.
+3. **Pass 3 — Risk lenses**: evaluate every registry trigger against the complete context, load every matched reference, and record trigger evidence and results.
+4. **Pass 4 — Counterevidence**: seek evidence that disproves or downgrades each candidate finding and counterexamples that could invalidate an approval.
+5. **Pass 5 — Classification and convergence**: classify issues as findings, manual-validation, or advisories; reconcile evidence contracts, ledger intents, unverified assumptions, and the verdict.
+
+## Risk Lens Registry
+
+Registry rows use stable fields: `lens_id` identifies the lens, `stages` limits its
+scope, `observable_trigger` states observable evidence, `required_reference` is
+mandatory when matched, and `report_evidence` defines the audit trail.
+
+| lens_id | stages | observable_trigger | required_reference | report_evidence |
+|---------|--------|--------------------|--------------------|-----------------|
+| documentation-antipatterns | code | The complete change context touches Markdown, rules, skills, CLI help, or user documentation that describes current behavior | `.agents/skills/review-code/reference/documentation-antipatterns.md` | Record triggering files, `loaded=yes`, and the lens result |
+| testing-discipline | code | The complete change context touches tests, fixtures, snapshots, or test helpers | `.agents/rules/testing-discipline.md` | Record triggering files, `loaded=yes`, and the test-discipline result |
+| security-risks | code | Authentication, authorization, untrusted input, sensitive data, credentials, cryptography, dependencies, or system boundaries change | `.agents/skills/review-code/reference/security-risks.md` | Record the changed security boundary, `loaded=yes`, and the lens result |
+| migration-risks | code | Persistent formats, schemas, configuration/frontmatter, compatibility reads, migrations, or rollback behavior change | `.agents/skills/review-code/reference/migration-risks.md` | Record compatibility or migration evidence, `loaded=yes`, and the lens result |
+| concurrency-risks | code | Async coordination, shared state, locks, retries, idempotency, races, cancellation, or timeouts change | `.agents/skills/review-code/reference/concurrency-risks.md` | Record the concurrency path, `loaded=yes`, and the lens result |
+| cross-platform-risks | code | OS branches, paths, shells, permissions, symlinks, newlines, signals, or cross-platform behavior change | `.agents/skills/review-code/reference/cross-platform-risks.md` | Record platform evidence, `loaded=yes`, and the lens result |
+
+Unmatched lenses still require reproducible non-trigger evidence. `loaded` accepts
+only `yes`, `no`, or `not-applicable`; a matched but unloaded lens forbids approval.
+
+## Automation and Semantic Judgment
+
+| Source | Facts it can support | Semantic judgment it cannot replace |
+|--------|----------------------|-------------------------------------|
+| snapshot, diff, link, test, artifact gate | files, scope, command results, reference existence, section existence | requirement completeness, design soundness, implementation correctness |
+| traceability matrix | explicit mappings and visible gaps | mapping sufficiency, gap impact, priority |
+| risk-lens record | trigger evidence, load status, lens result entry point | acceptable risk, finding severity, confidence |
+
+When automated facts and semantic conclusions diverge, record each separately.
+Never present a passing structural gate as proof of semantic completeness.
+
+## Context Coverage and Traceability Contract
+
+Reports must contain both coverage tables:
+
+| pass_id | scope | evidence | result | gaps_or_assumptions |
+|---------|-------|----------|--------|---------------------|
+| pass-1..5 | scope actually reviewed in this pass | locatable artifact, file, command, or line | finding or conclusion | uncovered item, gap, or assumption |
+
+| lens_id | trigger_evidence | loaded | result |
+|---------|------------------|--------|--------|
+| registry token | reproducible trigger or non-trigger evidence | yes / no / not-applicable | lens conclusion |
+
+Reports must also contain the shared traceability matrix:
+
+| source_id | upstream | reviewed_target | verification | status_or_gap |
+|-----------|----------|-----------------|--------------|---------------|
+| stable source identifier | upstream requirement, decision, or step | object reviewed at this stage | automated or human evidence | covered / gap and impact |
+
+Analysis traces sources to requirements, acceptance, impact, and risk. Plan traces
+approved requirements to decisions, implementation steps, and test strategy. Code
+traces requirements and plan steps to the diff and automated tests or human checks.
+
+## Finding Evidence Contract
+
+Every blocker or major finding must include:
+
+1. **Scenario**: preconditions and the path that triggers the problem.
+2. **Impact**: concrete consequences for correctness, security, delivery, or acceptance.
+3. **Evidence**: reproducible artifact, `file:line`, command, and raw result.
+4. **Confidence**: stable token `high`, `medium`, or `low`.
+5. **Unverified assumptions**: claims not directly proven that would change the conclusion if disproved; explicitly state none when empty.
+6. **Fix direction**: the smallest actionable repair goal without redesigning outside the executor's authority.
+
+Minor findings stay lightweight but still need a specific location and actionable
+advice. The finding ledger's `evidence` continues to point to a stable report anchor;
+no ledger fields are added. Handle manual-validation, advisories, and
+`needs-human-decision` through the review handshake and stage rules.
+
+## Completion
+
+A final verdict is allowed only when:
+
+- All five passes record scope, evidence, result, and gaps/assumptions.
+- Every risk trigger has a decision, and every matched lens was loaded and recorded.
+- The traceability matrix covers the stage responsibility, with gaps classified as a finding, manual-validation, advisory, or explicit assumption.
+- Every blocker/major satisfies the evidence contract and every candidate finding received a counterevidence pass.
+- Ledger intents, manual checks, pending decisions, unverified assumptions, and finding counts agree.

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/skills/analyze-task/SKILL.en.md

@@ -230,9 +230,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 +247,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 +259,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

@@ -229,9 +229,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 +246,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 +258,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

@@ -95,11 +95,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.
 
@@ -116,9 +118,7 @@ To unblock when the issue is resolved:
   agent-infra-internal task-lifecycle {task-id} activate --agent {agent} --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}
 ```
 
 

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

@@ -96,11 +96,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} 已标记为阻塞。
 
@@ -117,9 +119,7 @@ ai sandbox rm {branch}
   agent-infra-internal task-lifecycle {task-id} activate --agent {agent} --note "{恢复说明}"
 
 下一步 - 检查任务状态（解除阻塞后）：
-  - 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.en.md

@@ -102,11 +102,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 +122,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

@@ -101,11 +101,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 +121,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 +132,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
 

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

@@ -59,7 +59,7 @@ ai task status {task-id}
 
 ### 3. 建议下一步操作
 
-根据当前工作流状态，建议合适的下一个技能。必须展示下表中所有 TUI 列的命令格式，不要只展示当前 AI 代理对应的列。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）：
+根据当前工作流状态，建议合适的下一个技能：
 
 > **⚠️ 条件判断 — 你必须先根据 `status`、`current_step`、最新产物和最新审查结果，选择下表中唯一匹配的一行：**
 >
@@ -77,21 +77,21 @@ ai task status {task-id}
 >
 > **特别注意：只要最新审查报告中存在任何问题，就不能使用对应「审查通过」行。必须改用对应「审查有问题」行。**
 >
-> 渲染最终输出前先读取 `.agents/rules/next-step-output.md` 并落实其两类规则：(1) 下方表格中命令的 `{task-ref}` 渲染为短号 `NN`（未分配/已释放时回退完整 TASK-id）；(2) 在面向用户输出的绝对最后一行追加 `Completed at` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
-
-| 当前状态           | Claude Code / OpenCode       | Gemini CLI                               | Codex CLI                    |
-|--------------------|------------------------------|------------------------------------------|------------------------------|
-| 分析完成           | `/review-analysis {task-ref}` | `/{{project}}:review-analysis {task-ref}` | `$review-analysis {task-ref}` |
-| 需求分析审查通过   | `/plan-task {task-ref}`       | `/{{project}}:plan-task {task-ref}`       | `$plan-task {task-ref}`       |
-| 需求分析审查有问题 | `/analyze-task {task-ref}`    | `/{{project}}:analyze-task {task-ref}`    | `$analyze-task {task-ref}`    |
-| 计划完成           | `/review-plan {task-ref}`     | `/{{project}}:review-plan {task-ref}`     | `$review-plan {task-ref}`     |
-| 技术方案审查通过   | `/code-task {task-ref}`       | `/{{project}}:code-task {task-ref}`       | `$code-task {task-ref}`       |
-| 技术方案审查有问题 | `/plan-task {task-ref}`       | `/{{project}}:plan-task {task-ref}`       | `$plan-task {task-ref}`       |
-| 实现完成           | `/review-code {task-ref}`     | `/{{project}}:review-code {task-ref}`     | `$review-code {task-ref}`     |
-| 代码审查通过       | `/commit`                    | `/{{project}}:commit`                    | `$commit`                    |
-| 代码审查有问题     | `/code-task {task-ref}`       | `/{{project}}:code-task {task-ref}`       | `$code-task {task-ref}`       |
-| 任务被阻塞         | 解除阻塞或提供所需信息       | —                                        | 解除阻塞或提供所需信息       |
-| 任务已完成         | 无需操作                     | —                                        | 无需操作                     |
+> 渲染最终输出前先读取 `.agents/rules/next-step-output.md`。选中可执行行后只调用一次 `agent-infra-internal agent-client next-steps --skill {next-skill} [--task-ref {task-ref}]`，将 stdout 原样输出为 `{next-step-commands}`；`任务被阻塞` 与 `任务已完成` 不调用 helper。最后追加 `Completed at` 收尾行。
+
+| 当前状态           | next skill        | task ref |
+|--------------------|-------------------|----------|
+| 分析完成           | `review-analysis` | required |
+| 需求分析审查通过   | `plan-task`       | required |
+| 需求分析审查有问题 | `analyze-task`    | required |
+| 计划完成           | `review-plan`     | required |
+| 技术方案审查通过   | `code-task`       | required |
+| 技术方案审查有问题 | `plan-task`       | required |
+| 实现完成           | `review-code`     | required |
+| 代码审查通过       | `commit`          | omitted  |
+| 代码审查有问题     | `code-task`       | required |
+| 任务被阻塞         | —                 | —        |
+| 任务已完成         | —                 | —        |
 
 ## 注意事项
 

package/templates/.agents/skills/close-codescan/SKILL.en.md

@@ -89,10 +89,12 @@ Only `status=applied|no-op` means local archival completed. If the API dismissal
 
 ### 8. Inform User
 
-> **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 the "Note:" line and before "Next step" in the output below — only when ALL of (1) `.agents/.airc.json` has a `sandbox` field, (2) step 7 located a related task by the alert number, and (3) that related task's task.md `branch` field exists and is not `main` / `master`; otherwise omit the whole block. `{branch}` is the `branch` value from the related task.md located in step 7. This block is independent of "Next step" semantics.
 
+Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill complete-task --task-ref {task-ref}`.
+
 ```
 Code Scanning alert #{alert-number} dismissed.
 
@@ -111,9 +113,7 @@ Optional: clean up this task's sandbox
 ai sandbox rm {branch}
 
 Next step - complete and archive the task if a related task exists:
-  - Claude Code / OpenCode: /complete-task {task-ref}
-  - Gemini CLI: /{{project}}:complete-task {task-ref}
-  - Codex CLI: $complete-task {task-ref}
+{next-step-commands}
 ```
 
 ## Notes

package/templates/.agents/skills/close-codescan/SKILL.zh-CN.md

@@ -89,10 +89,12 @@ agent-infra-internal task-lifecycle {task-id} close-codescan --agent {agent} \
 
 ### 8. 告知用户
 
-> **重要**：以下「下一步」中列出的所有 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) 第 7 步按告警号定位到了关联任务、(3) 该关联任务 task.md 的 `branch` 字段存在且不是 `main` / `master` 时，才渲染下方输出中「注意：…」之后、「下一步」之前的「可选：清理本任务的沙箱」块；任一不满足则整段省略。`{branch}` 取第 7 步定位到的关联任务 task.md 的 `branch` 值。该块独立于「下一步」语义。
 
+使用 `agent-infra-internal agent-client next-steps --skill complete-task --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
+
 ```
 Code Scanning 告警 #{alert-number} 已关闭。
 
@@ -111,9 +113,7 @@ Code Scanning 告警 #{alert-number} 已关闭。
 ai sandbox rm {branch}
 
 下一步 - 完成并归档任务（如有关联任务）：
-  - Claude Code / OpenCode：/complete-task {task-ref}
-  - Gemini CLI：/{{project}}:complete-task {task-ref}
-  - Codex CLI：$complete-task {task-ref}
+{next-step-commands}
 ```
 
 ## 注意事项

package/templates/.agents/skills/close-dependabot/SKILL.en.md

@@ -97,10 +97,12 @@ Only `status=applied|no-op` means local archival completed. If the API dismissal
 
 ### 8. Inform User
 
-> **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 the "Note:" line and before "Next step" in the output below — only when ALL of (1) `.agents/.airc.json` has a `sandbox` field, (2) step 7 located a related task by the alert number, and (3) that related task's task.md `branch` field exists and is not `main` / `master`; otherwise omit the whole block. `{branch}` is the `branch` value from the related task.md located in step 7. This block is independent of "Next step" semantics.
 
+Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill complete-task --task-ref {task-ref}`.
+
 ```
 Security alert #{alert-number} dismissed.
 
@@ -119,9 +121,7 @@ Optional: clean up this task's sandbox
 ai sandbox rm {branch}
 
 Next step - complete and archive the task if a related task exists:
-  - Claude Code / OpenCode: /complete-task {task-ref}
-  - Gemini CLI: /{{project}}:complete-task {task-ref}
-  - Codex CLI: $complete-task {task-ref}
+{next-step-commands}
 ```
 
 ## Notes

package/templates/.agents/skills/close-dependabot/SKILL.zh-CN.md

@@ -97,10 +97,12 @@ agent-infra-internal task-lifecycle {task-id} close-dependabot --agent {agent} \
 
 ### 8. 告知用户
 
-> **重要**：以下「下一步」中列出的所有 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) 第 7 步按告警号定位到了关联任务、(3) 该关联任务 task.md 的 `branch` 字段存在且不是 `main` / `master` 时，才渲染下方输出中「注意：…」之后、「下一步」之前的「可选：清理本任务的沙箱」块；任一不满足则整段省略。`{branch}` 取第 7 步定位到的关联任务 task.md 的 `branch` 值。该块独立于「下一步」语义。
 
+使用 `agent-infra-internal agent-client next-steps --skill complete-task --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
+
 ```
 安全告警 #{alert-number} 已关闭。
 
@@ -119,9 +121,7 @@ agent-infra-internal task-lifecycle {task-id} close-dependabot --agent {agent} \
 ai sandbox rm {branch}
 
 下一步 - 完成并归档任务（如有关联任务）：
-  - Claude Code / OpenCode：/complete-task {task-ref}
-  - Gemini CLI：/{{project}}:complete-task {task-ref}
-  - Codex CLI：$complete-task {task-ref}
+{next-step-commands}
 ```
 
 ## 注意事项