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 9 commands. Define a requirement, let AI handle analysis, planning, coding, review, and delivery — you only step in when it matters.

中文版

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

Install & Initialize

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 TASK-20260319-100000, and extracts requirements.

/analyze-task TASK-20260319-100000

AI scans the codebase, identifies src/auth/login.ts as the root cause, and writes analysis.md.

/plan-task TASK-20260319-100000

AI proposes a fix plan: "Sanitize the email input in LoginService.validate() and add a dedicated unit test."

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 updates the plan accordingly and confirms.

/implement-task TASK-20260319-100000

AI writes the fix, adds a test case for user+tag@example.com, and runs all tests — green.

/review-task TASK-20260319-100000

AI reviews its own implementation: "Approved. 0 blockers, 0 major, 1 minor (missing JSDoc)."

/refine-task TASK-20260319-100000

AI fixes the minor issue and re-validates.

/commit
/create-pr TASK-20260319-100000
/complete-task TASK-20260319-100000

Commit created, PR #43 opened (auto-linked to issue #42), task archived.

9 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.

What each skill does behind the scenes

These are not thin command aliases. Each skill encapsulates standardized processes that are tedious and error-prone when done by hand:

Structured artifacts — every step produces a templated document (analysis.md, plan.md, review.md) with consistent structure, not free-form notes
Multi-round versioning — requirements changed? Run analyze-task again to get analysis-r2.md; the full revision history is preserved
Severity-classified reviews — review-task categorizes findings into Blocker / Major / Minor with file paths and fix suggestions, not a vague "looks good"
Cross-tool state continuity — task.md records who did what and when; Claude can analyze, Codex can implement, Gemini can review — context transfers seamlessly
Audit trail and co-authorship — every step appends to the Activity Log; the final commit includes Co-Authored-By lines for all participating AI agents

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)

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:

TUI	Command
Claude Code	`/update-agent-infra`
Codex	`$update-agent-infra`
Gemini CLI	`/{{project}}:update-agent-infra`
OpenCode	`/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.

Sandbox aliases and GitHub CLI

ai sandbox create now bootstraps the host-side aliases file at ~/.agent-infra/aliases/sandbox.sh on first run. The generated file includes ready-to-edit yolo shortcuts for Claude, Codex, Gemini CLI, and OpenCode, and every sandbox syncs that file into /home/devuser/.bash_aliases.

The sandbox image also preinstalls gh. When gh auth token succeeds on the host, ai sandbox create injects the token into the container as GH_TOKEN, so gh commands work inside the sandbox without extra setup.

ai sandbox exec also forwards a small terminal-detection whitelist (TERM_PROGRAM, TERM_PROGRAM_VERSION, LC_TERMINAL, LC_TERMINAL_VERSION) into the container. This keeps interactive TUIs aligned with the host terminal for behaviors such as Claude Code's Shift+Enter newline support, without passing through the full host environment.

Architecture Overview

agent-infra is intentionally simple: a bootstrap CLI creates the seed configuration, then AI skills and workflows take over.

End-to-End Flow

Install — npm install -g @fitlab-ai/agent-infra (or brew install fitlab-ai/tap/agent-infra on macOS, or use the shell script wrapper)
Initialize — ai init in the project root to generate .agents/.airc.json and install the seed command
Render — run update-agent-infra in any AI TUI to detect the bundled template version and generate all managed files
Develop — use built-in skills to drive the full lifecycle: analysis → design → implementation → review → fix → commit
Update — run update-agent-infra again whenever a new template version is available

Layered Architecture

┌───────────────────────────────────────────────────────┐
│                     AI TUI Layer                      │
│  Claude Code  ·  Codex  ·  Gemini CLI  ·  OpenCode    │
└──────────────────────────┬────────────────────────────┘
                           │ slash commands
                           ▼
┌───────────────────────────────────────────────────────┐
│                     Shared Layer                      │
│         Skills  ·  Workflows  ·  Templates            │
└──────────────────────────┬────────────────────────────┘
                           │ renders into
                           ▼
┌───────────────────────────────────────────────────────┐
│                    Project Layer                      │
│               .agents/  ·  AGENTS.md                  │
└───────────────────────────────────────────────────────┘

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

Built-in AI Skills

agent-infra ships with a rich set of built-in AI skills. They are organized by use case, but they all share the same design goal: every AI TUI should be able to execute the same workflow vocabulary in the same repository.

Task Lifecycle

Skill	Description	Parameters	Recommended use case
`create-task`	Create a task scaffold from a natural-language request.	`description`	Start a new feature, bug-fix, or improvement from scratch.
`import-issue`	Import a GitHub Issue into the local task workspace.	`issue-number`	Convert an existing Issue into an actionable task folder.
`analyze-task`	Produce a requirement analysis artifact for an existing task.	`task-id`	Capture scope, risks, and impacted files before designing.
`plan-task`	Write the technical implementation plan with a review checkpoint.	`task-id`	Define the approach after analysis is complete.
`implement-task`	Implement the approved plan and produce an implementation report.	`task-id`	Write code, tests, and docs after plan approval.
`review-task`	Review the implementation and classify findings by severity.	`task-id`	Run a structured code review before merging.
`refine-task`	Fix review findings in priority order without expanding scope.	`task-id`	Address review feedback and re-validate the task.
`complete-task`	Mark the task complete and archive it after all gates pass.	`task-id`	Close out a task after review, tests, and commit are done.

Task Status

Skill	Description	Parameters	Recommended use case
`check-task`	Inspect the current task status, workflow progress, and next step.	`task-id`	Check progress without modifying task state.
`block-task`	Move a task to blocked state and record the blocker reason.	`task-id`, `reason` (optional)	Pause work when an external dependency or decision is missing.
`restore-task`	Restore local task files from GitHub Issue sync comments.	`issue-number`, `task-id` (optional)	Recover a task workspace after switching machines or clearing local state.

Issue and PR

Skill	Description	Parameters	Recommended use case
`create-issue`	Create a GitHub Issue from a task file.	`task-id`	Push a local task into GitHub tracking.
`create-pr`	Open a Pull Request to an inferred or explicit target branch.	`task-id` (optional), `target-branch` (optional)	Publish reviewed changes for merge, with optional explicit task linkage after a fresh session.

Code Quality

Skill	Description	Parameters	Recommended use case
`commit`	Create a Git commit with task updates and copyright-year checks.	None	Finalize a coherent change set after tests pass.
`test`	Run the standard project validation flow.	None	Validate compile checks and unit tests after a change.
`test-integration`	Run integration or end-to-end validation.	None	Verify cross-module or workflow-level behavior.

Release

Skill	Description	Parameters	Recommended use case
`release`	Execute the version release workflow.	`version` (`X.Y.Z`)	Publish a new project release.
`create-release-note`	Generate release notes from PRs and commits.	`version`, `previous-version` (optional)	Prepare a changelog before shipping.

Security

Skill	Description	Parameters	Recommended use case
`import-dependabot`	Import a Dependabot alert and create a remediation task.	`alert-number`	Convert a dependency security alert into a tracked fix.
`close-dependabot`	Close a Dependabot alert with a documented rationale.	`alert-number`	Record why an alert does not require action.
`import-codescan`	Import a Code Scanning alert and create a remediation task.	`alert-number`	Triage CodeQL findings through the normal task workflow.
`close-codescan`	Close a Code Scanning alert with a documented rationale.	`alert-number`	Record why a scanning alert can be safely dismissed.

Project Maintenance

Skill	Description	Parameters	Recommended use case
`upgrade-dependency`	Upgrade a dependency from one version to another and verify it.	`package`, `old-version`, `new-version`	Perform controlled dependency maintenance.
`refine-title`	Rewrite an Issue or PR title into Conventional Commits format.	`number`	Normalize inconsistent GitHub titles.
`init-labels`	Initialize the repository's standard GitHub label set.	None	Bootstrap labels in a new repository.
`init-milestones`	Initialize the repository's milestone structure.	None	Bootstrap milestone tracking in a new repository.
`archive-tasks`	Archive completed tasks into a date-organized directory with a manifest index.	`[--days N \| --before DATE \| TASK-ID...]`	Periodically clean up the `completed/` directory.
`update-agent-infra`	Update the project's collaboration infrastructure to the latest template version.	None	Refresh shared AI tooling without rebuilding local conventions.

Every skill works across supported AI TUIs. The command prefix changes, but the workflow semantics stay the same.

Custom Skills

Built-in skills cover the standard delivery lifecycle, but teams often need project-specific instructions such as coding standards, deployment checks, or internal review rules. agent-infra supports that through custom skills.

Create a custom skill in the project

Create a directory under .agents/skills/<name>/ and add a SKILL.md file:

.agents/skills/
  enforce-style/
    SKILL.md
    reference/
      style-guide.md

Minimum frontmatter:

---
name: enforce-style
description: "Apply team style checks before submitting code"
args: "<task-id>"   # optional
---

name: user-facing skill name
description: used when generating editor command metadata
args: optional argument hint; agent-infra uses it when generating slash commands for supported AI TUIs

After adding the skill, run update-agent-infra again:

TUI	Command
Claude Code	`/update-agent-infra`
Codex	`$update-agent-infra`
Gemini CLI	`/{{project}}:update-agent-infra`
OpenCode	`/update-agent-infra`

That refresh detects non-built-in skill directories in .agents/skills/ and generates matching commands for Claude Code, Gemini CLI, and OpenCode automatically.

Sync custom skills from shared sources

If you maintain reusable team skills outside the repository, declare them in .agents/.airc.json:

{
  "skills": {
    "sources": [
      { "type": "local", "path": "~/company-skills" },
      { "type": "local", "path": "~/team-skills" }
    ]
  }
}

Expected source layout:

~/company-skills/
  enforce-style/
    SKILL.md
  release-check/
    SKILL.md
    reference/
      checklist.md

Behavior:

Sources are applied in list order; later sources overwrite earlier custom sources when they define the same file
type: "local" is the only supported source type today; the structure leaves room for future source types
~ in source paths is expanded to the current user's home directory

Sync behavior and conflict rules

When update-agent-infra runs:

Manually created custom skills in .agents/skills/ are protected from managed-file cleanup
Files synced from external custom sources are copied into .agents/skills/
For synced skills that still exist in a configured source, files removed from the source are also removed locally during the next sync
Built-in skills always win over custom sources; if a source defines a skill with the same name as a built-in skill, agent-infra skips that custom source skill instead of overriding the built-in one
If you truly need to replace a built-in skill or command, use the existing ejected mechanism and own that file in the project

Prebuilt Workflows

agent-infra includes 4 prebuilt workflows. Three of them share the same gated delivery lifecycle:

analysis -> design -> implementation -> review -> fix -> commit

The fourth, code-review, is intentionally smaller and optimized for reviewing an existing PR or branch.

Workflow	Best for	Step chain
`feature-development`	Building a new feature or capability	`analysis -> design -> implementation -> review -> fix -> commit`
`bug-fix`	Diagnosing and fixing a defect with regression coverage	`analysis -> design -> implementation -> review -> fix -> commit`
`refactoring`	Structural changes that should preserve behavior	`analysis -> design -> implementation -> review -> fix -> commit`
`code-review`	Reviewing an existing PR or branch	`analysis -> review -> report`

Example lifecycle

The simplest end-to-end delivery loop looks like this:

import-issue #42                    Import task from GitHub Issue
(or: create-task "add dark mode")   Or create a task from a description
         |
         |  --> get task ID, e.g. T1
         v
  analyze-task T1                   Requirement analysis
         |
         v
    plan-task T1                    Design solution  <-- human review
         |
         v
  implement-task T1                 Write code and tests
         |
         v
  +-> review-task T1                Automated code review
  |      |
  |   Issues?
  |      +--NO-------+
  |     YES          |
  |      |           |
  |      v           |
  |  refine-task T1  |
  |      |           |
  +------+           |
                     |
         +-----------+
         |
         v
      commit                        Commit final code
         |
         v
  complete-task T1                  Archive and finish

Configuration Reference

The generated .agents/.airc.json file is the central contract between the bootstrap CLI, templates, and future updates.

Example `.agents/.airc.json`

{
  "project": "my-project",
  "org": "my-org",
  "language": "en",
  "templateVersion": "v0.5.6",
  "skills": {
    "sources": [
      { "type": "local", "path": "~/company-skills" }
    ]
  },
  "files": {
    "managed": [
      ".agents/workspace/README.md",
      ".agents/skills/",
      ".agents/templates/",
      ".agents/workflows/",
      ".claude/commands/",
      ".gemini/commands/",
      ".opencode/commands/"
    ],
    "merged": [
      ".agents/README.md",
      ".gitignore",
      "AGENTS.md"
    ],
    "ejected": []
  }
}

Field reference

Field	Meaning
`project`	Project name used when rendering commands, paths, and templates.
`org`	GitHub organization or owner used by generated metadata and links.
`language`	Primary project language or locale used by rendered templates.
`templateVersion`	Installed template version for future upgrades and drift tracking.
`skills`	Optional custom skill sync configuration.
`skills.sources`	Optional ordered list of external custom skill sources. Only `type: "local"` is supported today.
`files`	Per-path update strategy configuration for managed, merged, and ejected files.

File Management Strategies

Each generated path is assigned an update strategy. That strategy determines how update-agent-infra treats the file later.

Strategy	Meaning	Update behavior
managed	agent-infra fully controls the file	Re-rendered and overwritten on update
merged	Template content and user customizations coexist	AI-assisted merge preserves local additions where possible
ejected	Generated once and then owned by the project	Never touched again by future updates

Example strategy configuration

{
  "files": {
    "managed": [
      ".agents/skills/",
      ".agents/workspace/README.md"
    ],
    "merged": [
      ".gitignore",
      "AGENTS.md"
    ],
    "ejected": [
      "docs/architecture.md"
    ]
  }
}

Moving a file from `managed` to `ejected`

Remove the path from the managed array in .agents/.airc.json.
Add the same path to the ejected array.
Run update-agent-infra again so future updates stop managing that file.

Use this when a file starts as template-owned but later becomes project-specific enough that automatic updates would create more noise than value.

Version Management

agent-infra uses semantic versioning through Git tags and GitHub releases. The installed template version is recorded in .agents/.airc.json as templateVersion, which gives both humans and AI tools a stable reference point for upgrades.

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 221 Commits
.agents		.agents
.claude		.claude
.codex		.codex
.gemini		.gemini
.github		.github
.opencode		.opencode
assets		assets
bin		bin
lib		lib
scripts		scripts
src		src
templates		templates
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
.mailmap		.mailmap
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
License.txt		License.txt
README.md		README.md
README.zh-CN.md		README.zh-CN.md
RELEASING.md		RELEASING.md
SECURITY.md		SECURITY.md
SECURITY.zh-CN.md		SECURITY.zh-CN.md
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

Agent Infra

Why agent-infra?

See it in Action

Install & Initialize

What each skill does behind the scenes

Key Features

Quick Start

1. Install agent-infra

Updating agent-infra

2. Initialize a new project

3. Render the full infrastructure

Sandbox aliases and GitHub CLI

Architecture Overview

End-to-End Flow

Layered Architecture

What You Get

Built-in AI Skills

Task Lifecycle

Task Status

Issue and PR

Code Quality

Release

Security

Project Maintenance

Custom Skills

Create a custom skill in the project

Sync custom skills from shared sources

Sync behavior and conflict rules

Prebuilt Workflows

Example lifecycle

Configuration Reference

Example .agents/.airc.json

Field reference

File Management Strategies

Example strategy configuration

Moving a file from managed to ejected

Version Management

Contributing

License

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 22

Contributors

Uh oh!

Languages

Example `.agents/.airc.json`

Moving a file from `managed` to `ejected`