Agent Infra

Collaboration infrastructure for AI coding agents — skills, workflows, and sandboxes for Claude Code, Codex, Gemini CLI, and OpenCode.

From issue to merged PR in 11 commands. Define a requirement, let AI handle analysis, planning, coding, and three-stage review — you only step in when it matters.

English · 中文

Why agent-infra?

Teams increasingly mix Claude Code, Codex, Gemini CLI, OpenCode, and other AI TUIs in the same repository, but each tool tends to introduce its own commands, prompts, and local conventions. Without a shared layer, the result is fragmented workflows, duplicated setup, and task history that is difficult to audit.

agent-infra standardizes that shared infrastructure. It gives every supported AI TUI the same task lifecycle, the same skill vocabulary, the same project governance files, isolated development sandboxes, and the same upgrade path, so teams can switch tools without rebuilding process from scratch.

See it in Action

Once initialized, open the project in your AI TUI and install the latest skills:

/update-agent-infra

AI reads .agents/.airc.json, auto-locates the installed template root, and syncs the latest skill manifests, managed files, and registry deterministically via sync-templates.js.

Scenario: Issue #42 reports "Login API returns 500 when email contains a plus sign". Here is the full fix lifecycle — AI does the heavy lifting, you stay in control:

/import-issue 42           # AI reads the issue, creates a task, extracts requirements
/analyze-task <task-id>    # AI scans the codebase, finds the root cause, writes analysis.md
/review-analysis <task-id> # AI self-reviews: "Approved. 0 blockers — proceed to design."
/plan-task <task-id>       # AI proposes a fix plan
/review-plan <task-id>     # AI self-reviews the plan: "Approved. Ready for implementation."

You review the plan and reply in natural language:

The plan looks right, but don't change the DB schema.
Just fix it at the application layer in LoginService.

AI re-runs /plan-task to update the plan accordingly and confirms.

/code-task <task-id>       # AI writes the fix, adds a test for [email protected] — green
/review-code <task-id>     # AI reviews its own code: "0 blockers, 1 minor (missing JSDoc)."
/code-task <task-id>       # AI fixes the minor issue and re-validates
/commit
/create-pr <task-id>       # PR opened, auto-linked to issue #42
/complete-task <task-id>   # task archived

11 commands. 1 natural-language correction. From issue to merged PR. That is the entire SOP — programming can have a standard operating procedure too.

Every command above works the same way in Claude Code, Codex, Gemini CLI, and OpenCode. Switch tools mid-task — the workflow state follows. For what each skill does under the hood, see Built-in AI Skills.

Key Features

• Multi-AI collaboration: one shared operating model for Claude Code, Codex, Gemini CLI, and OpenCode
• Bootstrap CLI + skill-driven execution: initialize once, then let AI skills drive day-to-day work
• Bilingual project docs: English-first docs with synchronized Chinese translations
• Template-source architecture: templates/ mirrors the rendered project structure
• AI-assisted updates: template changes can be merged while preserving project-specific customization

Quick Start

1. Install agent-infra

Option A - npm (recommended)

npm install -g @fitlab-ai/agent-infra

Option B - Shell script

# Convenience wrapper — detects Node.js and runs npm install -g internally
curl -fsSL https://raw.githubusercontent.com/fitlab-ai/agent-infra/main/install.sh | sh

Option C - Homebrew (macOS)

# Newer Homebrew refuses to load formulae from third-party taps until trusted,
# which silently blocks upgrades. Trust the tap once before installing.
brew trust fitlab-ai/tap
brew install fitlab-ai/tap/agent-infra

Updating agent-infra

npm update -g @fitlab-ai/agent-infra
# or, if installed via Homebrew:
brew upgrade agent-infra

Check your current version:

ai version
# or: agent-infra version

2. Initialize a new project

cd my-project
ai init
# or: agent-infra init

The CLI collects project metadata, installs the update-agent-infra seed command for all supported AI TUIs, and generates .agents/.airc.json.

ai is a shorthand for agent-infra. Both commands are equivalent.

3. Render the full infrastructure

Open the project in any AI TUI and run update-agent-infra:

This detects the packaged template version and renders all managed files. The same command is used both for first-time setup and for future template upgrades.

Core Commands

The most-used lifecycle commands, in delivery order. The command prefix varies by TUI (/skill in Claude Code/OpenCode, $skill in Codex, /{{project}}:skill in Gemini CLI); the workflow semantics stay the same.

See the full catalog — task status, release, security, and project-maintenance skills — in Built-in AI Skills.

What You Get

After setup, your project gains a complete AI collaboration infrastructure:

my-project/
├── .agents/               # Shared AI collaboration config
│   ├── .airc.json         # Central configuration
│   ├── workspace/         # Task workspace (git-ignored)
│   ├── skills/            # Built-in AI skills
│   ├── workflows/         # 4 prebuilt workflows
│   └── templates/         # Task and artifact templates
├── .claude/               # Claude Code config and commands
├── .gemini/               # Gemini CLI config and commands
├── .opencode/             # OpenCode config and commands
└── AGENTS.md              # Universal AI agent instructions

Documentation

In-depth guides live under docs/en/:

• Architecture Overview — bootstrap CLI, end-to-end flow, layered architecture
• Platform Support — macOS, Linux, Windows; sandbox engines and resources
• Sandbox — sandbox aliases, host-sandbox file exchange, user-level dotfiles channel
• Built-in AI Skills — the full skill catalog by use case
• Custom Skills — create and sync project-specific skills
• Custom TUI Configuration — adapt agent-infra to non-built-in AI TUIs
• Prebuilt Workflows — the gated delivery lifecycle and example flow
• Configuration Reference — .agents/.airc.json, external sources, version management
• File Management Strategies — managed / merged / ejected update strategies

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT