@fitlab-ai/agent-infra 0.5.5 → 0.5.7

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

@@ -120,6 +120,127 @@ To adapt agent-infra to a private code-hosting platform:
 4. If you maintain a fork of the template source, add matching `.{platform}.` template variants before adding that platform identifier to the sync logic.
 5. Validate the customized workflow on a test task before rolling it out broadly.
 
+## External Template And Skill Sources
+
+Teams can configure external template sources and shared skill sources in `.agents/.airc.json` for private platform templates, private rules, and shared custom skills:
+
+```json
+{
+  "templates": {
+    "sources": [
+      { "type": "local", "path": "~/private-templates" }
+    ]
+  },
+  "skills": {
+    "sources": [
+      { "type": "local", "path": "~/private-skills" }
+    ]
+  }
+}
+```
+
+Built-in templates take priority, and external templates are supplemental. Between multiple external template sources, later sources override earlier sources. The sync report lists ignored same-path files in `templateSources.conflicts`. External templates and skills may contain scripts executed by AI workflows, so only configure trusted local paths.
+
+## Custom Skills
+
+Projects can add their own skills alongside the built-in task workflow.
+
+### Local project skills
+
+Create a directory under `.agents/skills/<name>/` and add a `SKILL.md` file:
+
+```text
+.agents/skills/
+  enforce-style/
+    SKILL.md
+    reference/
+      style-guide.md
+```
+
+Recommended frontmatter:
+
+```yaml
+---
+name: enforce-style
+description: "Apply the team style guide before code review"
+args: "<task-id>"   # optional
+---
+```
+
+After adding or updating a custom skill, run `update-agent-infra` again. The sync step detects non-built-in skills and generates matching commands for Claude Code, Gemini CLI, and OpenCode automatically.
+
+### Shared skill sources
+
+To reuse centralized team skills, configure `.agents/.airc.json`:
+
+```json
+{
+  "skills": {
+    "sources": [
+      { "type": "local", "path": "~/private-skills" }
+    ]
+  }
+}
+```
+
+Each source should mirror the `.agents/skills/` layout and include `SKILL.md` at the root of every skill directory.
+
+### Sync behavior
+
+- Custom project skills in `.agents/skills/` are protected from managed-file cleanup
+- Source entries are applied in order; later custom sources overwrite earlier custom sources
+- Files deleted from an existing configured source are removed locally on the next sync for that sourced skill
+- Built-in skills are not overridable by custom sources; if a source skill name conflicts with a built-in skill, the source copy is skipped
+- Use `files.ejected` if the project must take ownership of a built-in skill or command
+
+## Custom TUI Configuration
+
+Use the top-level `.agents/.airc.json` `customTUIs` array when your team uses an AI TUI that is not one of the built-in command targets. This config lets agent-infra show the correct next-step commands and generate command files for project custom skills by learning from an existing command in the custom TUI directory.
+
+| Field | Required | Meaning |
+|-------|----------|---------|
+| `name` | Yes | Display name shown in reports and next-step guidance, for example `Acme TUI`. |
+| `dir` | Yes | Command directory relative to the project root, for example `.acme/commands`. The path must stay inside the project root. |
+| `invoke` | Yes | User-facing command template used in next-step guidance. |
+
+Supported `invoke` placeholders:
+
+| Placeholder | Replaced with | Example |
+|-------------|---------------|---------|
+| `${skillName}` | The skill command name, such as `review-task` or `commit`. | `acme ${skillName}` -> `acme review-task` |
+| `${projectName}` | The `.airc.json` `project` value. Use this for namespaced commands. | `/${projectName}:${skillName}` -> `/agent-infra:review-task` |
+
+Non-namespaced custom TUI:
+
+```json
+{
+  "customTUIs": [
+    {
+      "name": "Acme TUI",
+      "dir": ".acme/commands",
+      "invoke": "acme ${skillName}"
+    }
+  ]
+}
+```
+
+Namespaced custom TUI:
+
+```json
+{
+  "project": "agent-infra",
+  "customTUIs": [
+    {
+      "name": "Internal Gemini",
+      "dir": ".internal-gemini/commands",
+      "invoke": "/${projectName}:${skillName}"
+    }
+  ]
+}
+```
+
+`customTUIs` should contain one entry per custom TUI. To let `update-agent-infra` generate command files for custom skills, keep at least one existing command file in `dir` that references a built-in skill path such as `.agents/skills/analyze-task/SKILL.md`; agent-infra uses that file as the format reference.
+
 ## Skill Authoring Conventions
 
 When writing or updating `.agents/skills/*/SKILL.md` files and their templates, keep step numbering consistent:

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

@@ -120,6 +120,127 @@
 4. 如果你维护的是模板源码分支或私有 fork，需要先补齐对应的 `.{platform}.` 模板变体，再把该平台标识加入模板同步逻辑。
 5. 在正式推广前，先用一个测试任务完整验证工作流和 gate 校验。
 
+## 外部模板与 Skill 源
+
+团队可以在 `.agents/.airc.json` 中配置外部模板源和共享 skill 源，用于接入私有平台模板、私有规则和团队维护的自定义 skill：
+
+```json
+{
+  "templates": {
+    "sources": [
+      { "type": "local", "path": "~/private-templates" }
+    ]
+  },
+  "skills": {
+    "sources": [
+      { "type": "local", "path": "~/private-skills" }
+    ]
+  }
+}
+```
+
+模板源优先级为内置模板优先，外部模板只做补充；多个外部模板源之间，后面的 source 覆盖前面的 source。同步报告会在 `templateSources.conflicts` 中列出被忽略的同名文件。外部模板和 skill 可能包含会被 AI 工作流执行的脚本，只配置可信路径。
+
+## 自定义 Skills
+
+项目可以在内置任务工作流之外增加自己的 skill。
+
+### 项目内本地 skill
+
+在 `.agents/skills/<name>/` 下创建目录，并添加 `SKILL.md`：
+
+```text
+.agents/skills/
+  enforce-style/
+    SKILL.md
+    reference/
+      style-guide.md
+```
+
+推荐 frontmatter：
+
+```yaml
+---
+name: enforce-style
+description: "在代码审查前应用团队风格规范"
+args: "<task-id>"   # 可选
+---
+```
+
+新增或修改自定义 skill 后，再执行一次 `update-agent-infra`。同步过程会自动检测非内置 skill，并为 Claude Code、Gemini CLI、OpenCode 生成对应命令。
+
+### 共享 skill 源
+
+如需复用团队集中维护的 skill，可在 `.agents/.airc.json` 中配置：
+
+```json
+{
+  "skills": {
+    "sources": [
+      { "type": "local", "path": "~/private-skills" }
+    ]
+  }
+}
+```
+
+每个 source 都应镜像 `.agents/skills/` 的目录结构，并在每个 skill 目录根部提供 `SKILL.md`。
+
+### 同步行为
+
+- `.agents/skills/` 中手动创建的项目自定义 skill 不会被 managed 文件清理删除
+- 多个 source 按声明顺序应用；后面的自定义 source 会覆盖前面的自定义 source 文件
+- 对于仍存在于配置 source 中的 skill，如果源里删掉文件，下次同步时会删除本地对应残留文件
+- 自定义 source 不能覆盖内置 skill；如果与内置 skill 同名，会跳过该 source skill
+- 如果项目必须接管某个内置 skill 或命令，请使用 `files.ejected`
+
+## 自定义 TUI 配置
+
+当团队使用的 AI TUI 不属于内置命令目标时，可以在 `.agents/.airc.json` 顶层配置 `customTUIs` 数组。该配置用于让 agent-infra 输出正确的下一步命令，并通过学习自定义 TUI 目录中的既有命令文件，为项目自定义 skill 生成同格式命令。
+
+| 字段 | 必填 | 含义 |
+|------|------|------|
+| `name` | 是 | 报告和下一步提示中展示的工具名称，例如 `Acme TUI`。 |
+| `dir` | 是 | 相对项目根目录的命令目录，例如 `.acme/commands`。路径必须位于项目根目录内。 |
+| `invoke` | 是 | 面向用户展示的命令模板，用于生成下一步提示。 |
+
+`invoke` 支持的占位符：
+
+| 占位符 | 替换为 | 示例 |
+|--------|--------|------|
+| `${skillName}` | skill 命令名，例如 `review-task` 或 `commit`。 | `acme ${skillName}` -> `acme review-task` |
+| `${projectName}` | `.airc.json` 中的 `project` 值，适用于带命名空间的命令。 | `/${projectName}:${skillName}` -> `/agent-infra:review-task` |
+
+不带命名空间的自定义 TUI：
+
+```json
+{
+  "customTUIs": [
+    {
+      "name": "Acme TUI",
+      "dir": ".acme/commands",
+      "invoke": "acme ${skillName}"
+    }
+  ]
+}
+```
+
+带命名空间的自定义 TUI：
+
+```json
+{
+  "project": "agent-infra",
+  "customTUIs": [
+    {
+      "name": "Internal Gemini",
+      "dir": ".internal-gemini/commands",
+      "invoke": "/${projectName}:${skillName}"
+    }
+  ]
+}
+```
+
+`customTUIs` 每个条目对应一个自定义 TUI。若希望 `update-agent-infra` 为自定义 skill 生成命令文件，请在 `dir` 中保留至少一个引用内置 skill 路径的既有命令文件，例如 `.agents/skills/analyze-task/SKILL.md`；agent-infra 会以该文件作为格式参考。
+
 ## Skill 编写规范
 
 编写或维护 `.agents/skills/*/SKILL.md` 及其模板时，步骤编号遵循以下规则：

package/templates/.agents/rules/issue-pr-commands.en.md

@@ -0,0 +1,5 @@
+# Issue and PR Commands
+
+This code platform does not provide built-in issue or pull request commands.
+
+Platform-specific automation is skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates. Keep local task artifacts as the source of truth, or install a platform-specific template pack before running the workflow.

package/templates/.agents/rules/issue-pr-commands.zh-CN.md

@@ -0,0 +1,5 @@
+# Issue 和 PR 命令
+
+当前代码平台未内置 Issue 或 Pull Request 命令支持。
+
+自定义平台会跳过平台专属自动化，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板。请以本地任务产物作为事实来源，或先安装平台专属模板包再运行工作流。

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

@@ -0,0 +1,5 @@
+# Issue Sync
+
+This code platform does not provide built-in issue synchronization.
+
+Issue metadata, labels, milestones, assignees, and comments are skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates and platform adapters. Continue writing local task artifacts normally.

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

@@ -0,0 +1,5 @@
+# Issue 同步
+
+当前代码平台未内置 Issue 同步支持。
+
+自定义平台会跳过 Issue 元数据、标签、里程碑、负责人和评论同步，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板和平台适配器。请继续正常写入本地任务产物。

package/templates/.agents/rules/label-milestone-setup.en.md

@@ -0,0 +1,5 @@
+# Label and Milestone Setup
+
+This code platform does not provide built-in label or milestone setup.
+
+Initialization of remote labels and milestones is skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates and scripts. Local task workflow files remain usable without remote metadata setup.

package/templates/.agents/rules/label-milestone-setup.zh-CN.md

@@ -0,0 +1,5 @@
+# Label 和 Milestone 初始化
+
+当前代码平台未内置标签或里程碑初始化支持。
+
+自定义平台会跳过远端标签和里程碑初始化，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板和脚本。即使没有远端元数据初始化，本地任务工作流文件仍可使用。

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

@@ -0,0 +1,5 @@
+# Milestone Inference
+
+This code platform does not provide built-in milestone inference.
+
+Milestone narrowing and reuse are skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates. Do not block task progress when no platform-specific milestone implementation is available.

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

@@ -50,17 +50,18 @@ Goal: narrow the Issue milestone from a release line to a concrete version when
 
 Preconditions:
 - task.md contains a valid `issue_number`
-- the current Issue milestone matches the release-line format `X.Y.x`
+- the current Issue milestone matches the release-line format `X.Y.x` or is `General Backlog`
 
 Sequence:
 1. Query the current Issue milestone
-2. If it is not in `X.Y.x` format, treat it as already specific enough and keep it unchanged
-3. If it is in `X.Y.x` format, narrow it according to branch mode:
+2. If it is `General Backlog`, re-infer the release line using Phase 1, then try to narrow it to a concrete version; if inference fails, keep `General Backlog` unchanged
+3. If it is not in `X.Y.x` format, treat it as already specific enough and keep it unchanged
+4. If it is in `X.Y.x` format, narrow it according to branch mode:
    - Trunk mode: query open concrete-version milestones on that release line (for example `0.4.4`) and choose the latest one
    - Multi-version branch mode:
      - If the task branch was created from `origin/X.Y.x`, choose the latest concrete version on that line
      - If the task branch was created from `main`, find the highest release line and choose the latest concrete version on that line
-4. When a target concrete version is found, run:
+5. When a target concrete version is found, run:
 
 ```bash
 if [ "$has_triage" = "true" ]; then
@@ -68,7 +69,7 @@ if [ "$has_triage" = "true" ]; then
 fi
 ```
 
-5. If `has_triage=false`, the target milestone does not exist, or the branch ancestry cannot be determined reliably, keep the original milestone unchanged
+6. If `has_triage=false`, the target milestone does not exist, or the branch ancestry cannot be determined reliably, keep the original milestone unchanged
 
 Suggested concrete-version query:
 

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

@@ -50,17 +50,18 @@ Milestone 设置属于 `has_triage` 权限范围；如果调用方检测到 `has
 
 前置条件：
 - `task.md` 存在有效 `issue_number`
-- 当前 Issue milestone 为版本线格式 `X.Y.x`
+- 当前 Issue milestone 为版本线格式 `X.Y.x` 或 `General Backlog`
 
 执行顺序：
 1. 查询 Issue 当前 milestone
-2. 如果 milestone 不是 `X.Y.x` 格式 -> 视为已足够具体，保持不变
-3. 如果 milestone 是 `X.Y.x` -> 按分支模式收窄：
+2. 如果 milestone 是 `General Backlog` -> 按阶段 1 规则重新推断版本线，再尝试收窄到具体版本；如果推断失败则保持 `General Backlog` 不变
+3. 如果 milestone 不是 `X.Y.x` 格式 -> 视为已足够具体，保持不变
+4. 如果 milestone 是 `X.Y.x` -> 按分支模式收窄：
    - 主干模式：查询该版本线下 open 的具体版本 milestone（如 `0.4.4`），取最新版本
    - 多版本分支模式：
      - 当前任务分支来自 `origin/X.Y.x` release line -> 在该版本线下取最新具体版本
      - 当前任务分支来自 `main` -> 找最高版本线，再取该版本线下的最新具体版本
-4. 找到目标具体版本后，执行：
+5. 找到目标具体版本后，执行：
 
 ```bash
 if [ "$has_triage" = "true" ]; then
@@ -68,7 +69,7 @@ if [ "$has_triage" = "true" ]; then
 fi
 ```
 
-5. 如果 `has_triage=false`、目标 milestone 不存在，或无法可靠判断 -> 保持原 milestone 不变
+6. 如果 `has_triage=false`、目标 milestone 不存在，或无法可靠判断 -> 保持原 milestone 不变
 
 具体版本查询建议：
 

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

@@ -0,0 +1,5 @@
+# Milestone 推断
+
+当前代码平台未内置里程碑推断支持。
+
+自定义平台会跳过里程碑收窄和复用逻辑，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板。没有平台专属里程碑实现时，不要阻塞任务推进。

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

@@ -0,0 +1,5 @@
+# PR Sync
+
+This code platform does not provide built-in pull request synchronization.
+
+PR creation, metadata updates, labels, milestones, assignees, and summary comments are skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates and adapters. Keep local task artifacts up to date.

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

@@ -0,0 +1,5 @@
+# PR 同步
+
+当前代码平台未内置 Pull Request 同步支持。
+
+自定义平台会跳过 PR 创建、元数据更新、标签、里程碑、负责人和摘要评论同步，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板和适配器。请保持本地任务产物更新。

package/templates/.agents/rules/release-commands.en.md

@@ -0,0 +1,5 @@
+# Release Commands
+
+This code platform does not provide built-in release commands.
+
+Remote release automation is skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates and scripts. Continue using local release artifacts or your platform-specific release process.

package/templates/.agents/rules/release-commands.zh-CN.md

@@ -0,0 +1,5 @@
+# Release 命令
+
+当前代码平台未内置发布命令支持。
+
+自定义平台会跳过远端发布自动化，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板和脚本。请继续使用本地发布产物或你的平台专属发布流程。

package/templates/.agents/rules/security-alerts.en.md

@@ -0,0 +1,5 @@
+# Security Alerts
+
+This code platform does not provide built-in security alert integration.
+
+Code scanning and dependency alert import or close actions are skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates and adapters. Track security work through local task artifacts or a platform-specific integration.

package/templates/.agents/rules/security-alerts.zh-CN.md

@@ -0,0 +1,5 @@
+# 安全告警
+
+当前代码平台未内置安全告警集成。
+
+自定义平台会跳过代码扫描和依赖告警的导入或关闭操作，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板和适配器。请通过本地任务产物或平台专属集成跟踪安全工作。

package/templates/.agents/scripts/platform-adapters/platform-sync.github.js

@@ -935,22 +935,22 @@ function resolveUpstreamRepo(taskDir) {
     return ownerRepo;
   }
 
-  const upstreamResult = ghText([
+  const repoResult = ghJson([
     "api",
-    `repos/${ownerRepo.value}`,
-    "--jq",
-    "if .fork then .parent.full_name else .full_name end"
+    `repos/${ownerRepo.value}`
   ], taskDir);
 
-  if (!upstreamResult.ok) {
-    return upstreamResult;
+  if (!repoResult.ok) {
+    return repoResult;
   }
 
-  if (isBlank(upstreamResult.value)) {
+  const repo = repoResult.value && typeof repoResult.value === "object" ? repoResult.value : {};
+  const upstreamRepo = repo.fork ? repo.parent?.full_name : repo.full_name;
+  if (isBlank(upstreamRepo)) {
     return { ok: false, message: "Unable to resolve upstream repository" };
   }
 
-  return { ok: true, value: upstreamResult.value };
+  return { ok: true, value: upstreamRepo };
 }
 
 function resolveOwnerRepo(taskDir) {
@@ -1017,11 +1017,12 @@ function ghText(args, cwd) {
 }
 
 function ghCommand(args, cwd) {
-  const result = spawnSync("gh", args, {
+  const command = resolveCommand("gh");
+  const result = spawnSync(command, args, commandOptions(command, {
     cwd,
     encoding: "utf8",
     env: process.env
-  });
+  }));
 
   if (result.status !== 0) {
     const stderr = `${result.stderr || ""}${result.stdout || ""}`.trim();
@@ -1037,11 +1038,12 @@ function ghPaginatedJson(args, cwd) {
 }
 
 function gitText(args, cwd) {
-  const result = spawnSync("git", args, {
+  const command = resolveCommand("git");
+  const result = spawnSync(command, args, commandOptions(command, {
     cwd,
     encoding: "utf8",
     env: process.env
-  });
+  }));
 
   if (result.status !== 0) {
     const stderr = `${result.stderr || ""}${result.stdout || ""}`.trim();
@@ -1110,6 +1112,39 @@ function sleep(delayMs) {
   Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delayMs);
 }
 
+function resolveCommand(cmd) {
+  if (process.platform !== "win32" || path.extname(cmd)) {
+    return cmd;
+  }
+
+  const pathValue = process.env.Path || process.env.PATH || "";
+  const extensions = (process.env.PATHEXT || ".COM;.EXE;.BAT;.CMD")
+    .split(";")
+    .filter(Boolean);
+
+  for (const dir of pathValue.split(path.delimiter).filter(Boolean)) {
+    for (const extension of extensions) {
+      const lowerCandidate = path.join(dir, `${cmd}${extension.toLowerCase()}`);
+      if (fs.existsSync(lowerCandidate)) {
+        return lowerCandidate;
+      }
+      const upperCandidate = path.join(dir, `${cmd}${extension.toUpperCase()}`);
+      if (fs.existsSync(upperCandidate)) {
+        return upperCandidate;
+      }
+    }
+  }
+
+  return cmd;
+}
+
+function commandOptions(cmd, options) {
+  if (process.platform === "win32" && /\.(?:bat|cmd)$/i.test(cmd)) {
+    return { ...options, shell: true };
+  }
+  return options;
+}
+
 function interpolate(template, taskDir, artifactFile) {
   const artifactStem = artifactFile ? path.basename(artifactFile, path.extname(artifactFile)) : "";
   return template

package/templates/.agents/scripts/platform-adapters/platform-sync.js

@@ -0,0 +1,6 @@
+export function check(_context, shared) {
+  return shared.passResult(
+    "platform-sync",
+    "Skipped: this code platform does not provide a built-in platform-sync adapter"
+  );
+}

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

@@ -121,8 +121,8 @@ Update `.agents/workspace/active/{task-id}/task.md`:
 If task.md contains a valid `issue_number`, perform these sync actions (skip and continue on any failure):
 - Read `.agents/rules/issue-sync.md` before syncing, and complete upstream repository detection plus permission detection
 - Set `status: pending-design-work` by following issue-sync.md
-- Publish the `{analysis-artifact}` comment
 - Create or update the `<!-- sync-issue:{task-id}:task -->` comment (follow the task.md comment sync rule in issue-sync.md)
+- Publish the `{analysis-artifact}` comment
 
 ### 7. Verification Gate
 
@@ -143,7 +143,7 @@ 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.
+> **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).
 
 Output format:
 ```
@@ -172,7 +172,7 @@ Next step - create technical plan:
 - [ ] 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; do not filter)
+- [ ] Informed the user of the next step (must include all TUI command formats, including any custom TUIs; do not filter)
 - [ ] **Did not modify any business code**
 
 ## STOP

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

@@ -121,8 +121,8 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 如果 task.md 中存在有效的 `issue_number`，执行以下同步操作（任一失败则跳过并继续）：
 - 执行前先读取 `.agents/rules/issue-sync.md`，完成 upstream 仓库检测和权限检测
 - 按 issue-sync.md 设置 `status: pending-design-work`
-- 发布 `{analysis-artifact}` 评论
 - 创建或更新 `<!-- sync-issue:{task-id}:task -->` 评论（按 issue-sync.md 的 task.md 评论同步规则）
+- 发布 `{analysis-artifact}` 评论
 
 ### 7. 完成校验
 
@@ -143,7 +143,7 @@ node .agents/scripts/validate-artifact.js gate analyze-task .agents/workspace/ac
 
 > 仅在校验通过后执行本步骤。
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
 
 输出格式：
 ```
@@ -172,7 +172,7 @@ node .agents/scripts/validate-artifact.js gate analyze-task .agents/workspace/ac
 - [ ] 更新了 task.md 中的 `assigned_to`
 - [ ] 追加了 Activity Log 条目到 task.md
 - [ ] 在工作流进度中标记了 requirement-analysis 为已完成
-- [ ] 告知了用户下一步（必须展示所有 TUI 的命令格式，不要筛选）
+- [ ] 告知了用户下一步（必须展示所有 TUI 的命令格式，含自定义 TUI，不要筛选）
 - [ ] **没有修改任何业务代码**
 
 ## 停止

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

@@ -93,7 +93,7 @@ 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.
+> **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).
 
 Output format:
 ```

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

@@ -93,7 +93,7 @@ node .agents/scripts/validate-artifact.js gate block-task .agents/workspace/bloc
 
 > 仅在校验通过后执行本步骤。
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
 
 输出格式：
 ```

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

@@ -106,7 +106,7 @@ 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.
+> **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).
 
 Output format:
 ```

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

@@ -106,7 +106,7 @@ node .agents/scripts/validate-artifact.js gate cancel-task .agents/workspace/com
 
 > 仅在校验通过后执行本步骤。
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
 
 输出格式：
 ```
@@ -128,7 +128,7 @@ node .agents/scripts/validate-artifact.js gate cancel-task .agents/workspace/com
 - [ ] 已将任务目录移动到 `.agents/workspace/completed/`
 - [ ] 已在存在 Issue 时完成 Issue 同步
 - [ ] 已运行 gate 校验并通过
-- [ ] 已向用户展示完整的下一步命令
+- [ ] 已向用户展示完整的下一步命令（含自定义 TUI）
 
 ## 注意事项
 

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

@@ -100,7 +100,7 @@ Next step:
 
 ### 5. 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.
+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).
 
 > **⚠️ 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:**
 >