@fitlab-ai/agent-infra 0.5.6 → 0.5.7

package/lib/sandbox/engine.js

@@ -2,26 +2,56 @@ import { platform } from 'node:os';
 import { detectHostResources } from './constants.js';
 import { run, runOk, runSafe, runVerbose } from './shell.js';
 
-export function detectEngine() {
-  const os = platform();
-  if (os === 'darwin') {
-    return 'colima';
+export const ENGINES = Object.freeze({
+  COLIMA: 'colima',
+  ORBSTACK: 'orbstack',
+  DOCKER_DESKTOP: 'docker-desktop'
+});
+
+const VALID_CONFIG_ENGINES = new Set(Object.values(ENGINES));
+
+export function validateSandboxEngine(engine) {
+  if (engine === null || engine === undefined) {
+    return null;
   }
+
+  if (VALID_CONFIG_ENGINES.has(engine)) {
+    return engine;
+  }
+
+  throw new Error(
+    `sandbox: invalid "sandbox.engine" value "${engine}". `
+    + 'Expected one of: null, colima, orbstack, docker-desktop. '
+    + 'This setting only affects macOS sandbox engine selection.'
+  );
+}
+
+export function detectEngine(config = {}, { platformFn = platform } = {}) {
+  const configured = validateSandboxEngine(config.engine);
+  const os = platformFn();
   if (os === 'linux') {
     return 'native';
   }
   if (os === 'win32') {
     return 'wsl2';
   }
+  if (os === 'darwin') {
+    if (configured) {
+      return configured;
+    }
+
+    return ENGINES.COLIMA;
+  }
   return 'unsupported';
 }
 
 function colimaArgs(config, runSafeFn = runSafe) {
   const arch = runSafeFn('uname', ['-m']);
   const defaults = detectHostResources();
-  const cpu = config.vm.cpu ?? defaults.cpu;
-  const memory = config.vm.memory ?? defaults.memory;
-  const disk = config.vm.disk ?? 60;
+  const vm = config.vm ?? {};
+  const cpu = vm.cpu ?? defaults.cpu;
+  const memory = vm.memory ?? defaults.memory;
+  const disk = vm.disk ?? 60;
   const args = ['start', '--cpu', String(cpu), '--memory', String(memory), '--disk', String(disk)];
 
   if (arch === 'arm64') {
@@ -53,14 +83,54 @@ export async function ensureColima(
   }
 }
 
+export async function ensureOrbStack(
+  _config,
+  onMessage,
+  { runOkFn = runOk, runVerboseFn = runVerbose } = {}
+) {
+  if (!runOkFn('which', ['orb'])) {
+    onMessage?.('Installing OrbStack via Homebrew...');
+    runVerboseFn('brew', ['install', '--cask', 'orbstack']);
+  }
+
+  if (!runOkFn('docker', ['info'])) {
+    onMessage?.('Starting OrbStack...');
+    runVerboseFn('orb', ['start']);
+  }
+
+  if (!runOkFn('docker', ['info'])) {
+    throw new Error('Docker daemon is not available after starting OrbStack');
+  }
+}
+
+export async function ensureDockerDesktop(
+  _config,
+  onMessage,
+  { runOkFn = runOk } = {}
+) {
+  if (!runOkFn('docker', ['info'])) {
+    throw new Error('Docker Desktop is not running. Please start Docker Desktop manually.');
+  }
+}
+
 export async function ensureDocker(config, onMessage) {
-  const engine = detectEngine();
+  const engine = detectEngine(config);
 
-  if (engine === 'colima') {
+  if (engine === ENGINES.COLIMA) {
     await ensureColima(config, onMessage);
     return;
   }
 
+  if (engine === ENGINES.ORBSTACK) {
+    await ensureOrbStack(config, onMessage);
+    return;
+  }
+
+  if (engine === ENGINES.DOCKER_DESKTOP) {
+    await ensureDockerDesktop(config, onMessage);
+    return;
+  }
+
   if (engine === 'native') {
     if (!runOk('docker', ['info'])) {
       throw new Error('Docker daemon is not running. Please start Docker first.');
@@ -75,19 +145,58 @@ export async function ensureDocker(config, onMessage) {
   throw new Error(`Unsupported sandbox engine: ${engine}`);
 }
 
-export function isVmManaged() {
-  return detectEngine() === 'colima';
+export function isVmManaged(config = {}, dependencies = {}) {
+  const engine = detectEngine(config, dependencies);
+  return isManagedEngine(engine);
 }
 
-export function startManagedVm(config) {
-  if (!isVmManaged()) {
-    throw new Error('VM management is only available on macOS with Colima.');
+export function isManagedEngine(engine) {
+  return engine === ENGINES.COLIMA || engine === ENGINES.ORBSTACK;
+}
+
+export function engineDisplayName(engine) {
+  const names = {
+    [ENGINES.COLIMA]: 'Colima',
+    [ENGINES.ORBSTACK]: 'OrbStack',
+    [ENGINES.DOCKER_DESKTOP]: 'Docker Desktop',
+    native: 'native Docker',
+    wsl2: 'WSL2'
+  };
+  return names[engine] ?? engine;
+}
+
+export function startManagedVm(
+  config,
+  { platformFn = platform, runOkFn = runOk, runVerboseFn = runVerbose } = {}
+) {
+  const engine = detectEngine(config, { platformFn });
+  if (!isManagedEngine(engine)) {
+    throw new Error(`VM management is unavailable for engine '${engineDisplayName(engine)}'.`);
   }
 
-  if (runOk('colima', ['status'])) {
+  if (engine === ENGINES.COLIMA && runOkFn('colima', ['status'])) {
+    return 'already-running';
+  }
+  if (engine === ENGINES.ORBSTACK && runOkFn('orb', ['status'])) {
     return 'already-running';
   }
 
-  runVerbose('colima', colimaArgs(config));
+  if (engine === ENGINES.COLIMA) {
+    runVerboseFn('colima', colimaArgs(config));
+  } else if (engine === ENGINES.ORBSTACK) {
+    runVerboseFn('orb', ['start']);
+  }
   return 'started';
 }
+
+export function stopManagedVm(config, { platformFn = platform, runFn = run } = {}) {
+  const engine = detectEngine(config, { platformFn });
+  if (engine === ENGINES.COLIMA) {
+    runFn('colima', ['stop']);
+    return 'stopped';
+  } else if (engine === ENGINES.ORBSTACK) {
+    runFn('orb', ['stop']);
+    return 'stopped';
+  }
+  throw new Error(`VM management is unavailable for engine '${engineDisplayName(engine)}'.`);
+}

package/lib/sandbox/task-resolver.js

@@ -2,24 +2,31 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
+const WORKSPACE_DIRS = ['active', 'completed', 'blocked', 'archive'];
+
+function stripQuotes(value) {
+  return value.replace(/^(["'])(.*)\1$/, '$2');
+}
 
 function readTaskContent(repoRoot, taskId) {
-  const taskPath = path.join(repoRoot, '.agents', 'workspace', 'active', taskId, 'task.md');
-  if (!fs.existsSync(taskPath)) {
-    throw new Error(`Task not found: ${taskId}`);
+  for (const dir of WORKSPACE_DIRS) {
+    const taskPath = path.join(repoRoot, '.agents', 'workspace', dir, taskId, 'task.md');
+    if (fs.existsSync(taskPath)) {
+      return fs.readFileSync(taskPath, 'utf8');
+    }
   }
-  return fs.readFileSync(taskPath, 'utf8');
+  throw new Error(`Task not found: ${taskId}`);
 }
 
 function resolveBranchFromTaskContent(content, taskId) {
   const frontmatterBranch = content.match(/^branch:\s*(.+)$/m);
   if (frontmatterBranch && frontmatterBranch[1].trim()) {
-    return frontmatterBranch[1].trim();
+    return stripQuotes(frontmatterBranch[1].trim());
   }
 
   const contextBranch = content.match(/^- \*\*(?:分支|Branch)\*\*：[ \t]*`?([^`\n]+)`?$/m);
   if (contextBranch && contextBranch[1].trim()) {
-    return contextBranch[1].trim();
+    return stripQuotes(contextBranch[1].trim());
   }
 
   throw new Error(`Task ${taskId} has no branch field in task.md`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -46,7 +46,7 @@
   },
   "scripts": {
     "build": "node scripts/build-inline.js",
-    "demo:regen": "vhs assets/demo-init.tape",
+    "demo:regen": "sh scripts/demo-regen.sh",
     "prepare": "git config core.hooksPath .github/hooks || true",
     "test": "node scripts/build-inline.js --check && node --test tests/cli/*.test.js tests/templates/*.test.js tests/core/*.test.js",
     "prepublishOnly": "node scripts/build-inline.js --check && node --test tests/cli/*.test.js tests/templates/*.test.js tests/core/*.test.js"

package/templates/.agents/QUICKSTART.en.md

@@ -18,6 +18,23 @@ git config core.hooksPath .github/hooks
 
 This makes Git invoke the hooks synced into `.github/hooks/`, including `pre-commit` and `check-version-format.sh`.
 
+## External Templates And Skills
+
+If your team maintains private platform templates or shared custom skills, configure local sources in `.agents/.airc.json`:
+
+```json
+{
+  "templates": {
+    "sources": [{ "type": "local", "path": "~/private-templates" }]
+  },
+  "skills": {
+    "sources": [{ "type": "local", "path": "~/private-skills" }]
+  }
+}
+```
+
+Built-in templates take priority over external templates. Later external template sources override earlier external sources, and `update-agent-infra` reports conflicts in `templateSources.conflicts`. Only use trusted local paths because external templates and skills may contain executable scripts.
+
 ## Creating Your First Task
 
 1. Copy the task template to the active workspace:

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

@@ -18,6 +18,23 @@ git config core.hooksPath .github/hooks
 
 这样 Git 才会调用同步到 `.github/hooks/` 下的 hook，包括 `pre-commit` 和 `check-version-format.sh`。
 
+## 外部模板与 Skill
+
+如果团队维护私有平台模板或共享自定义 skill，可在 `.agents/.airc.json` 中配置本地源：
+
+```json
+{
+  "templates": {
+    "sources": [{ "type": "local", "path": "~/private-templates" }]
+  },
+  "skills": {
+    "sources": [{ "type": "local", "path": "~/private-skills" }]
+  }
+}
+```
+
+内置模板优先级高于外部模板。多个外部模板源之间，后面的 source 覆盖前面的 source，`update-agent-infra` 会在 `templateSources.conflicts` 中报告冲突。外部模板和 skill 可能包含可执行脚本，只使用可信本地路径。
+
 ## 创建第一个任务
 
 1. 将任务模板复制到活跃工作区：

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

@@ -120,6 +120,27 @@ 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.
@@ -156,7 +177,7 @@ To reuse centralized team skills, configure `.agents/.airc.json`:
 {
   "skills": {
     "sources": [
-      { "type": "local", "path": "~/company-skills" }
+      { "type": "local", "path": "~/private-skills" }
     ]
   }
 }
@@ -172,6 +193,54 @@ Each source should mirror the `.agents/skills/` layout and include `SKILL.md` at
 - 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,27 @@
 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。
@@ -156,7 +177,7 @@ args: "<task-id>"   # 可选
 {
   "skills": {
     "sources": [
-      { "type": "local", "path": "~/company-skills" }
+      { "type": "local", "path": "~/private-skills" }
     ]
   }
 }
@@ -172,6 +193,54 @@ args: "<task-id>"   # 可选
 - 自定义 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.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.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

@@ -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

@@ -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:
 ```