@fitlab-ai/agent-infra 0.5.6 → 0.5.8

package/lib/sandbox/commands/vm.js

@@ -3,31 +3,49 @@ import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { loadConfig } from '../config.js';
 import { parsePositiveIntegerOption } from '../constants.js';
-import { detectEngine, ensureDocker, isVmManaged } from '../engine.js';
-import { run, runOk, runSafe } from '../shell.js';
+import {
+  ENGINES,
+  detectEngine,
+  engineDisplayName,
+  ensureDocker,
+  isManagedEngine,
+  stopManagedVm
+} from '../engine.js';
+import { runOk, runSafe } from '../shell.js';
 
 const USAGE = `Usage: ai sandbox vm <status|start|stop> [--cpu <n>] [--memory <n>]`;
 
-function ensureManagedVm() {
-  if (!isVmManaged()) {
-    throw new Error(`VM management is unavailable on ${detectEngine()}.`);
+function ensureManagedVm(engine) {
+  if (!isManagedEngine(engine)) {
+    throw new Error(`VM management is unavailable for engine '${engineDisplayName(engine)}'.`);
   }
 }
 
 function status() {
-  ensureManagedVm();
+  const config = loadConfig();
+  const engine = detectEngine(config);
+  const name = engineDisplayName(engine);
+  ensureManagedVm(engine);
   p.intro(pc.cyan('Sandbox VM status'));
 
-  if (runOk('colima', ['status'])) {
-    process.stdout.write(`${runSafe('colima', ['status'])}\n`);
-  } else {
-    p.log.warn('Colima VM is not running');
+  if (engine === ENGINES.COLIMA) {
+    if (runOk('colima', ['status'])) {
+      process.stdout.write(`${runSafe('colima', ['status'])}\n`);
+    } else {
+      p.log.warn('Colima VM is not running');
+    }
+    return;
+  }
+
+  if (!runOk('orb', ['status'])) {
+    p.log.warn(`${name} VM is not running`);
+    return;
   }
+
+  process.stdout.write(`${runSafe('orb', ['status'])}\n`);
 }
 
 async function start(args) {
-  ensureManagedVm();
-
   const { values } = parseArgs({
     args,
     allowPositionals: true,
@@ -45,6 +63,8 @@ async function start(args) {
   }
 
   const config = loadConfig();
+  const engine = detectEngine(config);
+  ensureManagedVm(engine);
   const effectiveConfig = {
     ...config,
     vm: {
@@ -62,15 +82,22 @@ async function start(args) {
 }
 
 function stop() {
-  ensureManagedVm();
+  const config = loadConfig();
+  const engine = detectEngine(config);
+  const name = engineDisplayName(engine);
+  ensureManagedVm(engine);
   p.intro(pc.cyan('Stopping sandbox VM'));
 
-  if (!runOk('colima', ['status'])) {
-    p.log.warn('Colima VM is not running');
+  if (engine === ENGINES.COLIMA && !runOk('colima', ['status'])) {
+    p.log.warn(`${name} VM is not running`);
+    return;
+  }
+  if (engine === ENGINES.ORBSTACK && !runOk('orb', ['status'])) {
+    p.log.warn(`${name} VM is not running`);
     return;
   }
 
-  run('colima', ['stop']);
+  stopManagedVm(config);
   p.outro(pc.green('VM stopped'));
 }
 

package/lib/sandbox/config.js

@@ -1,8 +1,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
+import { validateSandboxEngine } from './engine.js';
 
 const DEFAULTS = Object.freeze({
+  engine: null,
   runtimes: ['node20'],
   tools: ['claude-code', 'codex', 'opencode', 'gemini-cli'],
   dockerfile: null,
@@ -26,6 +28,7 @@ function detectRepoRoot() {
 
 function cloneDefaults() {
   return {
+    engine: DEFAULTS.engine,
     runtimes: [...DEFAULTS.runtimes],
     tools: [...DEFAULTS.tools],
     dockerfile: DEFAULTS.dockerfile,
@@ -49,6 +52,7 @@ export function loadConfig() {
   const airc = JSON.parse(fs.readFileSync(configPath, 'utf8'));
   const defaults = cloneDefaults();
   const sandbox = airc.sandbox ?? {};
+  const engine = validateSandboxEngine(sandbox.engine ?? defaults.engine);
   const project = airc.project;
 
   if (!project || typeof project !== 'string') {
@@ -64,6 +68,7 @@ export function loadConfig() {
     containerPrefix: `${project}-dev`,
     imageName: `${project}-sandbox:latest`,
     worktreeBase: path.join(home, '.agent-infra', 'worktrees', project),
+    engine,
     runtimes: Array.isArray(sandbox.runtimes) && sandbox.runtimes.length > 0
       ? [...sandbox.runtimes]
       : defaults.runtimes,

package/lib/sandbox/engine.js

@@ -2,26 +2,69 @@ 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'
+});
+
+export const ENGINE_DOCKER_CONTEXT = Object.freeze({
+  [ENGINES.COLIMA]: 'colima',
+  [ENGINES.ORBSTACK]: 'orbstack',
+  [ENGINES.DOCKER_DESKTOP]: 'desktop-linux'
+});
+
+const VALID_CONFIG_ENGINES = new Set(Object.values(ENGINES));
+
+function applyDockerContext(engine) {
+  const context = ENGINE_DOCKER_CONTEXT[engine];
+  if (context) {
+    process.env.DOCKER_CONTEXT = context;
+  }
+}
+
+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') {
@@ -38,6 +81,8 @@ export async function ensureColima(
   onMessage,
   { runOkFn = runOk, runSafeFn = runSafe, runVerboseFn = runVerbose } = {}
 ) {
+  applyDockerContext(ENGINES.COLIMA);
+
   if (!runOkFn('which', ['colima'])) {
     onMessage?.('Installing colima + docker via Homebrew...');
     runVerboseFn('brew', ['install', 'colima', 'docker']);
@@ -53,14 +98,58 @@ export async function ensureColima(
   }
 }
 
+export async function ensureOrbStack(
+  _config,
+  onMessage,
+  { runOkFn = runOk, runVerboseFn = runVerbose } = {}
+) {
+  applyDockerContext(ENGINES.ORBSTACK);
+
+  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 } = {}
+) {
+  applyDockerContext(ENGINES.DOCKER_DESKTOP);
+
+  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 +164,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/shell.js

@@ -60,10 +60,44 @@ export function runOk(cmd, args, opts = {}) {
   return result.status === 0;
 }
 
+export function restoreTerminal() {
+  if (!process.stdout.isTTY) {
+    return;
+  }
+
+  try {
+    process.stdout.write([
+      '\x1b[?1049l',
+      '\x1b[?25h',
+      '\x1b>',
+      '\x1b[?1000l',
+      '\x1b[?1002l',
+      '\x1b[?1003l',
+      '\x1b[?1006l'
+    ].join(''));
+  } catch {
+    // Best-effort cleanup only; preserve the original command result.
+  }
+
+  if (process.platform === 'win32') {
+    return;
+  }
+
+  try {
+    execFileSync('stty', ['sane'], { stdio: 'inherit' });
+  } catch {
+    // Some environments do not provide stty or reject sane; ANSI reset still helps.
+  }
+}
+
 export function runInteractive(cmd, args, opts = {}) {
   const resolved = resolveCommand(cmd);
-  const result = spawnSync(resolved, args, commandOptions(resolved, normalizeOptions(opts, 'inherit')));
-  return result.status ?? 1;
+  try {
+    const result = spawnSync(resolved, args, commandOptions(resolved, normalizeOptions(opts, 'inherit')));
+    return result.status ?? 1;
+  } finally {
+    restoreTerminal();
+  }
 }
 
 export function runVerbose(cmd, args, opts = {}) {

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/lib/update.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { info, ok, err } from './log.js';
 import { resolveTemplateDir } from './paths.js';
-import { renderFile, copySkillDir } from './render.js';
+import { renderFile, copySkillDir, KNOWN_PLATFORMS } from './render.js';
 
 const defaults = JSON.parse(
   fs.readFileSync(new URL('./defaults.json', import.meta.url), 'utf8')
@@ -11,7 +11,16 @@ const defaults = JSON.parse(
 const CONFIG_DIR = '.agents';
 const CONFIG_PATH = path.join(CONFIG_DIR, '.airc.json');
 
-function syncFileRegistry(config) {
+function isPathOwnedByOtherPlatform(relativePath, platformType) {
+  const top = String(relativePath || '').replace(/\\/g, '/').replace(/^\.\//, '').split('/')[0];
+  if (!top.startsWith('.')) return false;
+
+  const candidate = top.slice(1);
+  if (!KNOWN_PLATFORMS.has(candidate)) return false;
+  return candidate !== platformType;
+}
+
+function syncFileRegistry(config, platformType) {
   config.files ||= {};
   const before = JSON.stringify({
     files: {
@@ -32,12 +41,14 @@ function syncFileRegistry(config) {
   const added = { managed: [], merged: [] };
 
   for (const entry of defaults.files.managed) {
+    if (isPathOwnedByOtherPlatform(entry, platformType)) continue;
     if (!allExisting.includes(entry)) {
       config.files.managed.push(entry);
       added.managed.push(entry);
     }
   }
   for (const entry of defaults.files.merged) {
+    if (isPathOwnedByOtherPlatform(entry, platformType)) continue;
     if (!allExisting.includes(entry)) {
       config.files.merged.push(entry);
       added.merged.push(entry);
@@ -139,7 +150,7 @@ async function cmdUpdate() {
   ok('Updated .opencode/commands/update-agent-infra.md');
 
   // sync file registry
-  const { added, changed } = syncFileRegistry(config);
+  const { added, changed } = syncFileRegistry(config, platformType);
   const hasNewEntries = added.managed.length > 0 || added.merged.length > 0;
   const platformAdded = !config.platform;
   const sandboxAdded = !config.sandbox;

package/package.json

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

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

@@ -13,10 +13,27 @@ This guide walks you through using multiple AI coding assistants together on a p
 Enable the shared Git hooks path before relying on the template hook chain:
 
 ```bash
-git config core.hooksPath .github/hooks
+git config core.hooksPath .git-hooks
 ```
 
-This makes Git invoke the hooks synced into `.github/hooks/`, including `pre-commit` and `check-version-format.sh`.
+This makes Git invoke the hooks in the project repository's `.git-hooks/` directory, 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
 

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

@@ -13,10 +13,27 @@
 在依赖模板中的 Git hook 链路前，先启用共享 hooks 路径：
 
 ```bash
-git config core.hooksPath .github/hooks
+git config core.hooksPath .git-hooks
 ```
 
-这样 Git 才会调用同步到 `.github/hooks/` 下的 hook，包括 `pre-commit` 和 `check-version-format.sh`。
+这样 Git 才会调用项目仓库 `.git-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 可能包含可执行脚本，只使用可信本地路径。
 
 ## 创建第一个任务
 

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

@@ -108,7 +108,7 @@ This project uses the following collaboration label prefixes, each with a define
 | `status:` | Yes | — | PRs already have their own state flow (Open / Draft / Merged / Closed); Issues use `status:` labels for project tracking states |
 | `in:` | Yes | Yes | Both Issues and PRs can be filtered by module |
 
-The default GitHub setup initializes these labels with the `/init-labels` command.
+Run the `/init-labels` command to initialize these labels via the platform adapter.
 
 ## Private Platform Extensions
 
@@ -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: