agent-infra
fitlab-ai/agent-infra
Collaboration infrastructure for AI coding agents | AI 编程代理的协作基础设施
Instalação
npx convez-ai fitlab-ai/agent-infra1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
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 viasync-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.tsas the root cause, and writesanalysis.md.
/review-analysis TASK-20260319-100000
AI self-reviews the analysis: "Approved. 0 blockers, 0 major, 0 minor — scope and root cause are clear, proceed to design."
/plan-task TASK-20260319-100000
AI proposes a fix plan: "Sanitize the email input in
LoginService.validate()and add a dedicated unit test."
/review-plan TASK-20260319-100000
AI self-reviews the plan: "Approved with no findings. 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-taskto update the plan accordingly and confirms.
/code-task TASK-20260319-100000
AI writes the fix, adds a test case for
user+tag@example.com, and runs all tests — green.
/review-code TASK-20260319-100000
AI reviews its own code: "Approved. 0 blockers, 0 major, 1 minor (missing JSDoc)."
/code-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.
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.
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,review-analysis.md,plan.md,review-plan.md,code.md,review-code.md) with consistent structure, not free-form notes - Multi-round versioning — requirements changed? Run
analyze-taskagain to getanalysis-r2.md; the full revision history is preserved - Severity-classified reviews —
review-codecategorizes findings into Blocker / Major / Minor with file paths and fix suggestions, not a vague "looks good" - Cross-tool state continuity —
task.mdrecords 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-Bylines 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)
# 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.
aiis a shorthand foragent-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 rebuild keeps Docker's build cache by default, so it quickly retags the sandbox image without refreshing every package. Use ai sandbox rebuild --refresh when you want to upgrade the image: it passes --no-cache --pull to Docker, pulls the current Ubuntu base image, and reruns the apt, tmux build, and global npm install layers. Claude Code updates are disabled inside the container, and OpenCode startup update checks are disabled; --refresh is the routine upgrade path for sandbox-managed tools. Manual opencode upgrade remains outside this guard. The default python3 provided by the Ubuntu 24.04 sandbox base is Python 3.12, so scripts that hard-code Python 3.10 paths may need adjustment.
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.
ai sandbox start <branch | TASK-id | N | '#N'> recovers a sandbox container that has stopped — for example after the host Docker daemon was restarted or replaced (a common case is installing OrbStack over an existing Docker), which leaves the container Exited. It only starts a container that already exists and is stopped; if none exists it points you to ai sandbox create, and a container that is already running is left untouched. ai sandbox exec <branch> performs the same recovery automatically: when the target container exists but is stopped, it starts the container first and then enters it. Because each worktree and per-AI state directory is persisted on the host, restarting a stopped container is safe and loses no data.
On macOS, interactive ai sandbox exec <branch> sessions can bridge image paste into the sandbox. When you press Ctrl+V and the host clipboard currently holds an image, agent-infra reads the image from the host clipboard, writes a PNG under ~/.agent-infra/clipboard/, and injects the container path as bracketed paste so Claude Code, Codex, Gemini CLI, and OpenCode can attach it. The host clipboard is only read, never rewritten. The bridge is best-effort: existing sandboxes must be rebuilt to receive the /clipboard mount, and if the optional pty dependency or clipboard probe is unavailable the session falls back to the normal interactive path. Set AI_SANDBOX_NO_CLIPBOARD_BRIDGE=1 to skip the bridge and enter the normal interactive path directly when diagnosing mouse, scrolling, or other input issues.
When you run the sandbox from a remote Mac over SSH, use ai cp <ssh-alias> on the Mac in front of you to push the local clipboard image to that remote Mac first. Copy an image with Cmd+C, run ai cp mini, then return to the existing SSH session and press Ctrl+V; the sandbox bridge reads the remote Mac's NSPasteboard and injects the image as usual. This command handles PNG images only and uses non-interactive ssh/scp with key-based authentication. For now both the sender and the remote must be macOS—the remote NSPasteboard is written via osascript—but the remote-write step is the natural extension point for other platforms later.
ai sandbox exec and ai sandbox refresh reconcile Claude Code credentials in both directions across the host credential store and every sandbox project copy under ~/.agent-infra/credentials/*. When a long-running sandbox refreshes OAuth tokens first, the next entry or refresh command writes the freshest valid copy back to the host Keychain or ~/.claude/.credentials.json; when the host is fresher, it updates the project copies. If every copy is stale, ai sandbox refresh probes claude /status and asks you to log in only when the probe cannot recover credentials.
Host-sandbox file exchange
ai sandbox create mounts two writable directories for dropping files between
the host and the sandbox without polluting the git worktree:
/share/common<-~/.agent-infra/share/<project>/common/- visible to every sandbox of the same project, regardless of branch./share/branch<-~/.agent-infra/share/<project>/branches/<branch>/- exclusive to the current branch sandbox./clipboard<-~/.agent-infra/clipboard/- read-only image paste bridge storage on macOS.
These paths are intentionally hardcoded; there is no .airc.json knob. Both
host directories are created automatically on first create. When you
ai sandbox rm <branch> or ai sandbox rm --all, you will be prompted (default
yes) to clean up the corresponding share dirs alongside the worktrees.
Use ai sandbox prune --dry-run to inspect orphaned per-branch state dirs left
behind by older versions or interrupted cleanup, then ai sandbox prune to
remove only dirs without an active sandbox container.
Existing sandboxes pick up these mounts after ai sandbox rm <branch> and
ai sandbox create <branch>.
On first ai sandbox create, agent-infra writes a bilingual README.md into
~/.agent-infra/share/<project>/common/ and each branches/<branch>/
directory to help you discover these channels. The READMEs are idempotent and
can be safely deleted; the scaffold only writes them when missing.
User-level dotfiles channel
ai sandbox create also mounts an optional read-only channel for host user preferences:
/dotfiles<-~/.agent-infra/dotfiles/- read-only, host-owned source.
The host tree mirrors the expected paths under the container $HOME, in the
same style as GNU stow or chezmoi:
~/.agent-infra/dotfiles/
├── .tmux.conf
└── .config/
├── lazygit/config.yml
└── yazi/yazi.toml
On each sandbox entry, sandbox-dotfiles-link links every file to
$HOME/<relative-path> with ln -sfn, overriding image defaults. If the host
directory does not exist, the mount and link step are skipped.
To add future preferences such as starship.toml or .gitconfig.local, put
files in ~/.agent-infra/dotfiles/; no Dockerfile or ai sandbox create
changes are needed.
Symlinks as pointers to host files
You can place symlinks inside ~/.agent-infra/dotfiles/ to point at real files
on your host:
ln -s ~/.tmux.conf ~/.agent-infra/dotfiles/.tmux.conf
ln -s ~/.config/lazygit ~/.agent-infra/dotfiles/.config/lazygit
Before each ai sandbox create and ai sandbox enter, agent-infra
dereferences the dotfiles tree into
~/.agent-infra/.cache/dotfiles-resolved/<project>/ and mounts that snapshot
into the container. Editing the host source file, then re-entering the sandbox,
is enough to pick up the latest content.
Dangling symlinks are skipped with a stderr warning. Symlink cycles and deeply
nested directories beyond 32 levels are also skipped with a warning. Symlinks
pointing outside $HOME are accepted as long as the host user can read the
target.
Do not put secrets in
~/.agent-infra/dotfiles/. The mount is read-only inside the container, but the full preference tree is linked into every project sandbox. Do not place.ssh/,.aws/credentials,.netrc,.gnupg/,.npmrcfiles containing_authToken, AI tool OAuth/access token files, or.gitconfigthere. Use the dedicated SSH and credential channels, and prefer.gitconfig.localwith[include]for local Git preferences.
Protected paths are ignored by the hook even if they appear under
~/.agent-infra/dotfiles/:
| Path pattern | Reason |
|---|---|
.ssh/* | Host SSH credentials are managed by the read-only SSH mount. |
.gnupg/* | GPG private material is managed by gpg-agent. |
.claude/*, .codex/*, .gemini/* | AI tool credentials use dedicated bind mounts. |
.config/opencode/*, .local/share/opencode/* | OpenCode credentials and data use dedicated bind mounts. |
.host-shell-config/* | agent-infra managed shell and Git configuration. |
.gitconfig, .gitignore_global, .stCommitMsg, .bash_aliases | agent-infra symlinks these to .host-shell-config/, including safe.directory and GPG sync state. |
README.md | agent-infra scaffolds a discoverability README at the dotfiles root on first create; the link hook ignores it so $HOME/README.md is not shadowed. |
Other existing real directories, such as ~/.config/ or ~/.cache/, are not
replaced by top-level dotfiles. If a file conflicts with one of those
directories, the hook prints a warning and skips it:
sandbox-dotfiles-link: skipping /home/devuser/.config (existing directory; use nested path like .config/<file> instead)
Use nested paths such as ~/.agent-infra/dotfiles/.config/lazygit/config.yml
instead of treating .config as a top-level file.
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(orbrew install fitlab-ai/tap/agent-infraon macOS, or use the shell script wrapper) - Initialize —
ai initin the project root to generate.agents/.airc.jsonand install the seed command - Render — run
update-agent-infrain 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 → analysis-review → design → design-review → code → code-review → commit - Update — run
update-agent-infraagain 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 │
└───────────────────────────────────────────────────────┘
Platform Support
agent-infra runs on macOS, Linux, and Windows. The CLI itself only needs Node.js (>=22); container-related features (ai sandbox *) additionally need Docker.
Sandbox engine selection
sandbox.engine in .agents/.airc.json selects the container engine. When it is null or omitted, agent-infra uses the platform default:
- Linux:
native - macOS:
colima - Windows:
wsl2
You can override the engine in .agents/.airc.json. Valid engines are platform-specific:
- Linux:
native,docker-desktop - macOS:
colima,orbstack,docker-desktop - Windows:
wsl2,native,docker-desktop
macOS
ai init,ai sync, etc.: works out of the box afternpm install -g @fitlab-ai/agent-infra(or Homebrew).ai sandbox *: requires Colima, OrbStack, or Docker Desktop. Colima is the default engine on macOS — when it is selected and thecolimacommand is missing, agent-infra auto-installs and starts Colima via Homebrew on first run. To use OrbStack or Docker Desktop instead, setsandbox.enginein.agents/.airc.json.
Engine resource configuration
| Engine | vm.cpu | vm.memory | vm.disk | Apply mode | Notes |
|---|---|---|---|---|---|
| Colima | applied | applied | applied | on-start | VM must be restarted (ai sandbox vm stop && ai sandbox vm start) for changes to take effect. |
| OrbStack | applied | applied | warned | hot | Applied via orb config set on every invocation. OrbStack manages disk via thin provisioning. |
| Docker Desktop | warned | warned | warned | manual | Resources must be set in Docker Desktop GUI (Settings -> Resources). |
vm.memory and --memory values are expressed in GiB.
SSH / locked keychain
On macOS over SSH, the login keychain may be locked and reject non-interactive reads or writes with errSecInteractionNotAllowed. You can unlock it on the host and re-run ai sandbox refresh:
security unlock-keychain ~/Library/Keychains/login.keychain-db
ai sandbox refresh
For long-lived SSH sessions or CI, bypass the keychain with AGENT_INFRA_CLAUDE_CREDENTIALS_FILE. macOS stores Claude Code credentials in the keychain by default, so seed the override file once from a session where the keychain is unlocked:
security unlock-keychain ~/Library/Keychains/login.keychain-db
umask 077 && mkdir -p "$HOME/.agent-infra" && \
security find-generic-password -s "Claude Code-credentials" -w \
> "$HOME/.agent-infra/claude-credentials.json"
chmod 600 "$HOME/.agent-infra/claude-credentials.json"
Then on the SSH / CI side:
export AGENT_INFRA_CLAUDE_CREDENTIALS_FILE="$HOME/.agent-infra/claude-credentials.json"
ai sandbox refresh
After that, sandbox create, exec, and refresh use the file instead of the keychain for Claude Code credential reads and writes.
Linux
-
ai init,ai sync, etc.: works out of the box afternpm install -g @fitlab-ai/agent-infra. -
ai sandbox *: requires Docker Engine on the host. Quick setup:# 1. Install Docker Engine — see https://docs.docker.com/engine/install/ # 2. Start the daemon and enable on boot sudo systemctl enable --now docker # 3. Skip 'sudo' for docker: add yourself to the docker group sudo usermod -aG docker $USER && newgrp dockerValidate with
docker info— it should succeed without sudo.GPG signing works when the host
gpg-agentand signing key are available; if key sync fails,ai sandbox createfalls back to a sanitized Git config so commits still work without host signing state.
Engine resource configuration
Linux uses native Docker on the host kernel, so there is no managed VM. sandbox.vm.* and the --cpu / --memory flags do not apply. To cap container resources, use docker run --cpus / --memory per container or configure host cgroups.
Rootless Docker (optional)
Skip this section if you followed the Quick setup above. The Quick setup installs the default rootful Docker, which works out of the box with ai sandbox — no extra configuration is required.
Rootless Docker is a separate Docker installation where the daemon runs as your normal user instead of root. It is typically chosen on shared hosts, multi-tenant servers, or when a security policy forbids a root-owned daemon. If you have intentionally installed rootless Docker (or plan to), follow the steps below; otherwise stay with rootful.
To install and verify rootless Docker:
sudo apt install -y uidmap slirp4netns dbus-user-session
dockerd-rootless-setuptool.sh install
systemctl --user enable --now docker
export DOCKER_HOST="unix:///run/user/$(id -u)/docker.sock"
docker info
Add the DOCKER_HOST export to your shell startup file after validation.
When rootless Docker is detected, agent-infra builds the sandbox image with HOST_UID=0 and HOST_GID=0. Inside the container the sandbox user can read bind mounts such as ~/.ssh without relaxing host file permissions. On the host, the daemon and container processes still run under the current user, so this does not grant host root privileges.
Known rootless differences:
- Networking uses slirp4netns by default and can be slower than rootful bridge networking.
- Processes run as UID 0 inside the container, unlike rootful Docker where agent-infra mirrors the host UID.
- The CI rootless matrix is initially allowed to fail while runner stability is observed.
Troubleshooting:
- If
docker infofails, checksystemctl --user status dockerand confirmDOCKER_HOSTpoints at$XDG_RUNTIME_DIR/docker.sock. - If SSH files are still unreadable inside the sandbox, confirm the shell has not overridden
DOCKER_HOSTor Docker build arguments.
Known limitations on Linux
These configurations are not actively tested in this release:
- Podman instead of Docker: Works on Fedora 40+ and other
dnf-based RHEL family distros (RHEL, CentOS Stream, Rocky, Alma) via thepodman-dockershim (sudo dnf install podman podman-docker; optionallysudo touch /etc/containers/nodockerto silence its per-command notice). - SELinux-enforcing hosts (Fedora / RHEL):
ai sandbox createautomatically labels bind mounts with Docker's shared:zflag — no setup required. SetAGENT_INFRA_SELINUX_DISABLE=1to opt out for debugging. ai sandbox vmis a no-op on Linux. Linux uses native Docker directly with no VM to manage; useai sandbox create,ai sandbox exec,ai sandbox start,ai sandbox refresh,ai sandbox ls,ai sandbox rebuild,ai sandbox rm, andai sandbox prunedirectly.
Windows
ai init,ai sync, etc.: should work afternpm install -g @fitlab-ai/agent-infra(Node.js >= 22). Not actively tested in this release.ai sandbox *: supported on Windows via WSL2 + Docker Desktop.
Before running ai sandbox create, install Windows 11 with WSL2, configure a default Linux distribution, install Docker Desktop, and enable Docker Desktop's WSL integration for that distribution.
You can run the CLI from PowerShell or Git Bash, but the project path must be visible from WSL, such as C:\Users\you\project or another drive mounted under /mnt/<drive>. UNC paths are not supported for sandbox mounts. If the Windows entrypoint cannot reach Docker through WSL2, run the same command from inside the WSL distribution as a fallback.
ai sandbox vm manages only the macOS Colima VM. On Windows, manage Docker Desktop and WSL2 with their native tools.
Engine resource configuration
WSL2 is the default sandbox engine on Windows. sandbox.vm.cpu, sandbox.vm.memory, and --cpu / --memory flags are not applied automatically when using WSL2 — configure CPU and memory limits in Docker Desktop (Settings → Resources) instead. sandbox.vm.disk is not applicable to WSL2. vm.memory and --memory values are expressed in GiB.
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 and cascade Issue creation through the platform rule when available. | 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. |
review-analysis | Review the requirement analysis and classify findings by severity. | task-id | Confirm the analysis is complete before design. |
plan-task | Write the technical plan with a review checkpoint. | task-id | Define the approach after analysis approval. |
review-plan | Review the technical plan and classify findings by severity. | task-id | Confirm the design is actionable before coding. |
code-task | Implement the approved plan or fix code review findings, producing a code report. | task-id | Write code, tests, and docs after plan approval, or handle review feedback. |
review-code | Review the code and classify findings by severity. | task-id | Run a structured code review before merging. |
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-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. |
watch-pr | Watch a PR's required checks and self-heal failures until green. | task-id or --pr <number> (optional; defaults to the current branch's PR) | Monitor CI after create-pr and auto-fix simple failures before merging. |
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. |
post-release | Run post-release follow-up tasks (version bump, artifact rebuild, optional demo capture). | None | Finalize the release cycle after pushing a release tag. |
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 namedescription: used when generating editor command metadataargs: 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": "~/private-skills" },
{ "type": "local", "path": "~/team-skills" }
]
}
}
Expected source layout:
~/private-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
ejectedmechanism and own that file in the project
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 <your-tui-name>. |
dir | Yes | Command directory relative to the project root, for example .<your-tui>/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-code or commit. | <your-cli> ${skillName} -> <your-cli> review-code |
${projectName} | The .airc.json project value. Use this for namespaced commands. | /${projectName}:${skillName} -> /agent-infra:review-code |
Non-namespaced custom TUI:
{
"customTUIs": [
{
"name": "<your-tui-name>",
"dir": ".<your-tui>/commands",
"invoke": "<your-cli> ${skillName}"
}
]
}
Namespaced custom TUI:
{
"project": "agent-infra",
"customTUIs": [
{
"name": "<your-tui-name>",
"dir": ".<your-tui>/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.
Prebuilt Workflows
agent-infra includes 4 prebuilt workflows. Three of them share the same symmetric gated delivery lifecycle:
analysis -> analysis-review -> design -> design-review -> code -> code-review -> 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 -> analysis-review -> design -> design-review -> code -> code-review -> commit |
bug-fix | Diagnosing and fixing a defect with regression coverage | analysis -> analysis-review -> design -> design-review -> code -> code-review -> commit |
refactoring | Structural changes that should preserve behavior | analysis -> analysis-review -> design -> design-review -> code -> code-review -> 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; Issue creation cascades when the platform rule supports it
|
| --> get task ID, e.g. T1
v
analyze-task T1 Requirement analysis
|
v
review-analysis T1 Review analysis
|
Issues?
+--YES----> analyze-task T1
|
v
plan-task T1 Design solution
|
v
review-plan T1 Review plan
|
Issues?
+--YES----> plan-task T1
|
|
v
code-task T1 Write code and tests
|
v
+-> review-code T1 Automated code review
| |
| Issues?
| +--NO-------+
| YES |
| | |
| v |
| code-task T1 (fix mode)
| | |
+------+ |
|
+-----------+
|
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.6.5",
"templates": {
"sources": [
{ "type": "local", "path": "~/private-templates" }
]
},
"skills": {
"sources": [
{ "type": "local", "path": "~/private-skills" }
]
},
"customTUIs": [
{
"name": "<your-tui-name>",
"dir": ".<your-tui>/commands",
"invoke": "<your-cli> ${skillName}"
}
],
"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. |
templates | Optional external template overlay configuration. |
templates.sources | Optional ordered list of external template sources. Only type: "local" is supported today. |
skills | Optional custom skill sync configuration. |
skills.sources | Optional ordered list of external custom skill sources. Only type: "local" is supported today. |
customTUIs | Optional top-level list of custom AI TUI adapters. |
files | Per-path update strategy configuration for managed, merged, and ejected files. |
External template and skill sources
Use external sources when your team maintains private platform templates, private rules, or shared custom skills outside this repository. You can configure them during agent-infra init or later by editing .agents/.airc.json:
{
"templates": {
"sources": [
{ "type": "local", "path": "~/private-templates" },
{ "type": "local", "path": "~/team-overrides/templates" }
]
},
"skills": {
"sources": [
{ "type": "local", "path": "~/private-skills" }
]
}
}
Template source precedence is built-in templates first, then external sources as supplements. External files with the same path as built-in templates are ignored and reported in templateSources.conflicts; between external sources, later entries override earlier entries and conflicts are also reported. Skill sources use the same local-source shape, but custom skills cannot replace built-in skills.
External template files and skill scripts can include executable JavaScript or shell commands that AI workflows may run. Only use trusted local paths.
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
managedarray in.agents/.airc.json. - Add the same path to the
ejectedarray. - Run
update-agent-infraagain 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.