@fitlab-ai/agent-infra 0.3.0

package/lib/log.js

@@ -0,0 +1,27 @@
+const isTTY = process.stdout.isTTY;
+const isTTYErr = process.stderr.isTTY;
+
+function color(code, text, tty) {
+  return tty ? `\x1b[${code}m${text}\x1b[0m` : text;
+}
+
+function info(...args) {
+  const msg = args.join(' ');
+  process.stdout.write(`  ${color('1;34', '>', isTTY)} ${msg}\n`);
+}
+
+function ok(...args) {
+  const msg = args.join(' ');
+  process.stdout.write(`  ${color('1;32', '\u2713', isTTY)} ${msg}\n`);
+}
+
+function err(...args) {
+  const msg = args.join(' ');
+  process.stderr.write(`  ${color('1;31', '\u2717', isTTYErr)} ${msg}\n`);
+}
+
+function ask(text) {
+  process.stdout.write(`  ${color('1;33', '?', isTTY)} ${text}`);
+}
+
+export { info, ok, err, ask };

package/lib/paths.js

@@ -0,0 +1,48 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+function resolveBundledTemplateDir() {
+  return fileURLToPath(new URL('../templates', import.meta.url));
+}
+
+function resolveCloneTemplateDir() {
+  return path.join(os.homedir(), '.agent-infra', 'templates');
+}
+
+function normalizePath(targetPath) {
+  try {
+    return fs.realpathSync(targetPath);
+  } catch {
+    return path.resolve(targetPath);
+  }
+}
+
+function resolveTemplateDir() {
+  // npm install mode: templates shipped alongside the package
+  const npmPath = resolveBundledTemplateDir();
+  if (fs.existsSync(npmPath)) {
+    return npmPath;
+  }
+
+  // clone install mode: ~/.agent-infra/templates
+  const clonePath = resolveCloneTemplateDir();
+  if (fs.existsSync(clonePath)) {
+    return clonePath;
+  }
+
+  return null;
+}
+
+function resolveInstallDir() {
+  return path.join(os.homedir(), '.agent-infra');
+}
+
+function isCloneInstall() {
+  const npmPath = resolveBundledTemplateDir();
+  const clonePath = resolveCloneTemplateDir();
+  return fs.existsSync(npmPath) && normalizePath(npmPath) === normalizePath(clonePath);
+}
+
+export { resolveTemplateDir, resolveInstallDir, isCloneInstall };

package/lib/prompt.js

@@ -0,0 +1,70 @@
+import readline from 'node:readline';
+import { ask } from './log.js';
+
+let _rl = null;
+let _lines = [];
+let _lineResolve = null;
+let _stdinDone = false;
+
+function setupInterface() {
+  if (_rl || _stdinDone) return;
+  _rl = readline.createInterface({
+    input: process.stdin,
+    terminal: false
+  });
+
+  _rl.on('line', (line) => {
+    if (_lineResolve) {
+      const resolve = _lineResolve;
+      _lineResolve = null;
+      resolve(line);
+    } else {
+      _lines.push(line);
+    }
+  });
+
+  _rl.on('close', () => {
+    _stdinDone = true;
+    _rl = null;
+    if (_lineResolve) {
+      const resolve = _lineResolve;
+      _lineResolve = null;
+      resolve(null);
+    }
+  });
+}
+
+function nextLine() {
+  return new Promise((resolve) => {
+    if (_lines.length > 0) {
+      resolve(_lines.shift());
+    } else if (_stdinDone) {
+      resolve(null);
+    } else {
+      _lineResolve = resolve;
+    }
+  });
+}
+
+async function prompt(question, defaultValue) {
+  const label = defaultValue ? `${question} [${defaultValue}]: ` : `${question}: `;
+  ask(label);
+
+  setupInterface();
+
+  const line = await nextLine();
+  if (line === null) {
+    return defaultValue || '';
+  }
+  return line.trim() || defaultValue || '';
+}
+
+function closePrompt() {
+  if (_rl) {
+    _rl.close();
+    _rl = null;
+    _stdinDone = true;
+  }
+}
+
+export { prompt, closePrompt };

package/lib/render.js

@@ -0,0 +1,99 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+function renderFile(src, dst, replacements) {
+  if (!fs.existsSync(src)) {
+    throw new Error(`Template file not found: ${src}`);
+  }
+
+  let content = fs.readFileSync(src, 'utf8');
+  content = content
+    .replace(/\{\{project\}\}/g, replacements.project)
+    .replace(/\{\{org\}\}/g, replacements.org || '');
+
+  const dir = path.dirname(dst);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(dst, content, 'utf8');
+}
+
+function copyFile(src, dst) {
+  if (!fs.existsSync(src)) {
+    throw new Error(`Template file not found: ${src}`);
+  }
+
+  const dir = path.dirname(dst);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.copyFileSync(src, dst);
+
+  try {
+    fs.chmodSync(dst, fs.statSync(src).mode);
+  } catch {
+    // Ignore permission sync failures on unsupported filesystems.
+  }
+}
+
+function walkFiles(dir) {
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const entryPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkFiles(entryPath));
+    } else {
+      results.push(entryPath);
+    }
+  }
+  return results;
+}
+
+function containsPlaceholders(src) {
+  const content = fs.readFileSync(src, 'utf8');
+  return content.includes('{{project}}') || content.includes('{{org}}');
+}
+
+function selectLocalizedFiles(srcDir, language) {
+  const selected = new Map();
+
+  for (const src of walkFiles(srcDir)) {
+    const relativePath = path.relative(srcDir, src);
+    if (relativePath.includes('.zh-CN.')) {
+      continue;
+    }
+    selected.set(relativePath, src);
+  }
+
+  if (language === 'zh-CN') {
+    for (const src of walkFiles(srcDir)) {
+      const relativePath = path.relative(srcDir, src);
+      if (!relativePath.includes('.zh-CN.')) {
+        continue;
+      }
+
+      selected.set(relativePath.replace('.zh-CN.', '.'), src);
+    }
+  }
+
+  return selected;
+}
+
+function copySkillDir(srcDir, dstDir, replacements, language) {
+  if (!fs.existsSync(srcDir)) {
+    throw new Error(`Template directory not found: ${srcDir}`);
+  }
+
+  for (const [relativePath, src] of selectLocalizedFiles(srcDir, language)) {
+    const dst = path.join(dstDir, relativePath);
+    if (containsPlaceholders(src)) {
+      renderFile(src, dst, replacements);
+      try {
+        fs.chmodSync(dst, fs.statSync(src).mode);
+      } catch {
+        // Ignore permission sync failures on unsupported filesystems.
+      }
+      continue;
+    }
+
+    copyFile(src, dst);
+  }
+}
+
+export { renderFile, copyFile, copySkillDir };

package/lib/update.js

@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { info, ok, err } from './log.js';
+import { resolveTemplateDir, resolveInstallDir, isCloneInstall } from './paths.js';
+import { renderFile, copySkillDir } from './render.js';
+
+const defaults = JSON.parse(
+  fs.readFileSync(new URL('./defaults.json', import.meta.url), 'utf8')
+);
+
+function syncFileRegistry(config) {
+  const allExisting = [
+    ...config.files.managed,
+    ...config.files.merged,
+    ...config.files.ejected
+  ];
+  const added = { managed: [], merged: [] };
+
+  for (const entry of defaults.files.managed) {
+    if (!allExisting.includes(entry)) {
+      config.files.managed.push(entry);
+      added.managed.push(entry);
+    }
+  }
+  for (const entry of defaults.files.merged) {
+    if (!allExisting.includes(entry)) {
+      config.files.merged.push(entry);
+      added.merged.push(entry);
+    }
+  }
+
+  return added;
+}
+
+async function cmdUpdate() {
+  console.log('');
+  console.log('  agent-infra update');
+  console.log('  ==================================');
+  console.log('');
+
+  // check .airc.json exists
+  if (!fs.existsSync('.airc.json')) {
+    err('No .airc.json found in current directory.');
+    err('Run "ai init" first to initialize the project.');
+    process.exitCode = 1;
+    return;
+  }
+
+  // resolve templates
+  const templateDir = resolveTemplateDir();
+  if (!templateDir) {
+    err('Template directory not found.');
+    err('Install via npm: npm install -g @fitlab-ai/agent-infra');
+    err('Or via clone: curl -fsSL https://raw.githubusercontent.com/fitlab-ai/agent-infra/main/install.sh | sh');
+    process.exitCode = 1;
+    return;
+  }
+
+  // auto-update: only for clone installs
+  if (isCloneInstall()) {
+    const installDir = resolveInstallDir();
+    if (fs.existsSync(path.join(installDir, '.git'))) {
+      info('Updating templates to latest version...');
+      try {
+        execSync('git pull --rebase --quiet', { cwd: installDir, stdio: 'pipe' });
+        ok('Templates updated.');
+      } catch {
+        err('Failed to update templates (network issue?). Using local version.');
+      }
+    }
+  }
+
+  // read project config
+  const config = JSON.parse(fs.readFileSync('.airc.json', 'utf8'));
+  const { project, org, language } = config;
+  const replacements = { project, org };
+
+  info(`Updating seed files for: ${project}`);
+  console.log('');
+
+  // select language-specific template filenames
+  let claudeSrc, geminiSrc, opencodeSrc;
+  if (language === 'zh-CN') {
+    claudeSrc = 'update-agent-infra.zh-CN.md';
+    geminiSrc = 'update-agent-infra.zh-CN.toml';
+    opencodeSrc = 'update-agent-infra.zh-CN.md';
+  } else {
+    claudeSrc = 'update-agent-infra.md';
+    geminiSrc = 'update-agent-infra.toml';
+    opencodeSrc = 'update-agent-infra.md';
+  }
+
+  // update skill
+  copySkillDir(
+    path.join(templateDir, '.agents', 'skills', 'update-agent-infra'),
+    path.join('.agents', 'skills', 'update-agent-infra'),
+    replacements,
+    language
+  );
+  ok('Updated .agents/skills/update-agent-infra/');
+  try {
+    fs.unlinkSync(path.join('.agents', 'skills', 'update-agent-infra', 'scripts', 'sync-templates.cjs'));
+  } catch {
+    // Ignore missing legacy script from pre-ESM installs.
+  }
+
+  // update Claude command
+  renderFile(
+    path.join(templateDir, '.claude', 'commands', claudeSrc),
+    path.join('.claude', 'commands', 'update-agent-infra.md'),
+    replacements
+  );
+  ok('Updated .claude/commands/update-agent-infra.md');
+
+  // update Gemini command
+  renderFile(
+    path.join(templateDir, '.gemini', 'commands', '_project_', geminiSrc),
+    path.join('.gemini', 'commands', project, 'update-agent-infra.toml'),
+    replacements
+  );
+  ok(`Updated .gemini/commands/${project}/update-agent-infra.toml`);
+
+  // update OpenCode command
+  renderFile(
+    path.join(templateDir, '.opencode', 'commands', opencodeSrc),
+    path.join('.opencode', 'commands', 'update-agent-infra.md'),
+    replacements
+  );
+  ok('Updated .opencode/commands/update-agent-infra.md');
+
+  // sync file registry
+  const added = syncFileRegistry(config);
+  const hasNewEntries = added.managed.length > 0 || added.merged.length > 0;
+
+  if (hasNewEntries) {
+    console.log('');
+    info('New file entries synced to .airc.json:');
+    for (const entry of added.managed) {
+      ok(`  managed: ${entry}`);
+    }
+    for (const entry of added.merged) {
+      ok(`  merged: ${entry}`);
+    }
+    fs.writeFileSync('.airc.json', JSON.stringify(config, null, 2) + '\n', 'utf8');
+    ok('Updated .airc.json');
+  }
+
+  // done
+  console.log('');
+  ok('Seed files updated successfully!');
+  console.log('');
+  console.log('  Next step: run the full update in your AI TUI:');
+  console.log('');
+  console.log('    Claude Code / OpenCode:  /update-agent-infra');
+  console.log(`    Gemini CLI:              /${project}:update-agent-infra`);
+  console.log('    Codex CLI:               $update-agent-infra');
+  console.log('');
+}
+
+export { cmdUpdate };

package/lib/version.js

@@ -0,0 +1,7 @@
+import { readFileSync } from 'node:fs';
+
+const { version: VERSION } = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8')
+);
+
+export { VERSION };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@fitlab-ai/agent-infra",
+  "version": "0.3.0",
+  "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
+  "license": "MIT",
+  "type": "module",
+  "author": "CodeCaster <codecaster365@outlook.com>",
+  "homepage": "https://github.com/fitlab-ai/agent-infra#readme",
+  "bugs": {
+    "url": "https://github.com/fitlab-ai/agent-infra/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fitlab-ai/agent-infra.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "bin": {
+    "agent-infra": "./bin/cli.js",
+    "ai": "./bin/cli.js"
+  },
+  "files": [
+    "bin/cli.js",
+    "lib/",
+    "templates/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai",
+    "collaboration",
+    "claude-code",
+    "codex",
+    "gemini",
+    "opencode",
+    "cli",
+    "bootstrap",
+    "installer"
+  ],
+  "scripts": {
+    "build": "node scripts/build-inline.js",
+    "test": "node scripts/build-inline.js --check && node --test tests/*.test.js",
+    "prepublishOnly": "node scripts/build-inline.js --check && node --test tests/*.test.js"
+  }
+}

package/templates/.agent-workspace/README.md

@@ -0,0 +1,26 @@
+# AI Workspace
+
+This directory is the runtime workspace for multi-AI collaboration. All contents are **git-ignored** except for this README and `.gitkeep` files.
+
+## Directory Structure
+
+```
+.agent-workspace/
+  active/           # Currently active tasks and handoff documents
+  blocked/          # Tasks that are blocked and waiting for resolution
+  completed/        # Completed tasks (kept for reference)
+  logs/             # Collaboration logs and session records
+```
+
+## Usage
+
+- **active/**: Place task files here when work begins. Move them to `completed/` or `blocked/` as appropriate.
+- **blocked/**: Move tasks here when they cannot proceed. Document the blocker in the task file.
+- **completed/**: Move tasks here when they are done. These serve as a historical record.
+- **logs/**: Store session logs, AI conversation exports, or collaboration notes.
+
+## Important
+
+- Contents of this directory are **not version-controlled** (git-ignored).
+- Do not store anything here that needs to be shared via git.
+- Templates and workflow definitions belong in `.agents/`, not here.

package/templates/.agent-workspace/README.zh-CN.md

@@ -0,0 +1,26 @@
+# AI 工作区
+
+本目录是多 AI 协作的运行时工作区。除本 README 和 `.gitkeep` 文件外，所有内容均被 **git ignore**。
+
+## 目录结构
+
+```
+.agent-workspace/
+  active/           # 当前活跃的任务和交接文档
+  blocked/          # 被阻塞的任务，等待解决
+  completed/        # 已完成的任务（保留供参考）
+  logs/             # 协作日志和会话记录
+```
+
+## 使用方法
+
+- **active/**：工作开始时将任务文件放在这里。根据情况将其移至 `completed/` 或 `blocked/`。
+- **blocked/**：当任务无法继续时将其移至此处。在任务文件中记录阻塞原因。
+- **completed/**：任务完成后将其移至此处。这些作为历史记录保留。
+- **logs/**：存储会话日志、AI 对话导出或协作笔记。
+
+## 重要事项
+
+- 本目录的内容**不受版本控制**（已被 git ignore）。
+- 不要在这里存储需要通过 git 共享的内容。
+- 模板和工作流定义属于 `.agents/` 目录，而非此处。

package/templates/.agents/QUICKSTART.md

@@ -0,0 +1,166 @@
+# Quick Start: Multi-AI Collaboration
+
+This guide walks you through using multiple AI coding assistants together on a project.
+
+## Prerequisites
+
+- At least one AI coding tool installed (Claude Code, Codex CLI, Gemini CLI, or Cursor)
+- A project with `.agents/` directory set up (this project)
+- Familiarity with your project's codebase
+
+## Creating Your First Task
+
+1. Copy the task template to the active workspace:
+
+```bash
+cp .agents/templates/task.md .agent-workspace/active/task-001.md
+```
+
+2. Fill in the task metadata:
+
+```yaml
+id: task-001
+type: feature          # feature | bugfix | refactor | docs | review
+status: open           # open | in-progress | review | blocked | completed
+assigned_to: claude    # claude | codex | gemini | cursor | human
+```
+
+3. Describe the task in the body of the document.
+
+## Using Different AIs for Different Phases
+
+### Phase 1: Analysis (Recommended: Claude Code)
+
+```bash
+# Start Claude Code and ask it to analyze the task
+claude
+
+# Example prompt:
+# "Analyze task-001. Explore the codebase and identify all files
+#  that need to change. Update the task with your findings."
+```
+
+Claude Code excels at codebase exploration and understanding complex relationships between files.
+
+### Phase 2: Design (Recommended: Claude Code or Gemini CLI)
+
+```bash
+# Continue with Claude Code or switch to Gemini CLI for large codebases
+gemini
+
+# Example prompt:
+# "Based on the analysis in .agent-workspace/active/task-001.md,
+#  create a technical design. Define interfaces and outline the approach."
+```
+
+### Phase 3: Implementation (Recommended: Codex CLI or Cursor)
+
+```bash
+# Switch to Codex CLI for implementation
+codex
+
+# Example prompt:
+# "Implement the changes described in .agent-workspace/active/task-001.md.
+#  Follow the design section. Create a new branch for this work."
+```
+
+### Phase 4: Review (Recommended: Claude Code)
+
+```bash
+# Switch back to Claude Code for review
+claude
+
+# Example prompt:
+# "Review the implementation on branch feature-xxx.
+#  Check for correctness, style, and best practices.
+#  Create a review report."
+```
+
+## Common Scenarios
+
+### Bug Fix
+
+1. **Reproduce & Analyze** (Claude Code): Identify the root cause.
+2. **Implement Fix** (Codex CLI / Cursor): Write the fix and tests.
+3. **Review** (Claude Code): Verify the fix is correct and complete.
+4. **Commit**: Create PR with bug fix description.
+
+```bash
+# Quick bug fix workflow
+cp .agents/templates/task.md .agent-workspace/active/bugfix-001.md
+# Edit the task, then:
+# 1. Use Claude Code to analyze
+# 2. Use Codex/Cursor to fix
+# 3. Use Claude Code to review
+```
+
+### Code Review
+
+1. **Load Context** (Claude Code): Read the PR diff and related files.
+2. **Review** (Claude Code): Check logic, style, tests, and edge cases.
+3. **Report**: Generate review report from template.
+
+```bash
+cp .agents/templates/review-report.md .agent-workspace/active/review-pr-42.md
+# Use Claude Code to fill in the review
+```
+
+### Refactoring
+
+1. **Analyze Scope** (Claude Code / Gemini CLI): Map all affected areas.
+2. **Design** (Claude Code): Plan the refactoring approach.
+3. **Implement** (Codex CLI / Cursor): Execute the refactoring.
+4. **Verify** (Claude Code): Ensure no regressions, run tests.
+
+```bash
+cp .agents/templates/task.md .agent-workspace/active/refactor-001.md
+# Follow the refactoring workflow in .agents/workflows/refactoring.yaml
+```
+
+## Creating Handoff Documents
+
+When switching between AI tools, create a handoff document:
+
+```bash
+cp .agents/templates/handoff.md .agent-workspace/active/handoff-task-001-phase2.md
+```
+
+Fill in:
+- What was completed
+- Current state of the code
+- What needs to happen next
+- Any blockers or concerns
+
+The receiving AI should read this document first to get up to speed.
+
+## Best Practices
+
+### 1. One AI Per Phase
+
+Don't have multiple AIs working on the same files simultaneously. Follow the sequential workflow: analyze, design, implement, review, fix, commit.
+
+### 2. Always Create Handoff Documents
+
+Even if you're switching between AIs quickly, a brief handoff note saves time and prevents context loss.
+
+### 3. Use the Right Tool for the Job
+
+- Complex analysis? Use Claude Code or Gemini CLI.
+- Straightforward implementation? Use Codex CLI or Cursor.
+- Large file review? Use Gemini CLI.
+
+### 4. Keep Tasks Small
+
+Break large tasks into smaller, well-defined subtasks. Each subtask should be completable in a single AI session.
+
+### 5. Version Control Your Progress
+
+Commit frequently. Each phase completion is a good commit point. This makes it easy to roll back if needed.
+
+### 6. Update Task Status
+
+Always update the task's `status`, `current_step`, and `assigned_to` fields when transitioning between phases.
+
+### 7. Review AI Output
+
+Always review what an AI produces before committing. AI tools are assistants, not autonomous agents.