convez.ai
Agente
fitlab-ai

agent-infra

fitlab-ai/agent-infra

Ver no GitHub
BomPluginScore · de 0 a 100

Collaboration infrastructure for AI coding agents | AI 编程代理的协作基础设施

Instalação

$npx convez-ai fitlab-ai/agent-infra

1 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

Estrelas
88
Forks
5
Acompanhando
0
Saúde
75%
Último commit
há 1 dia
Versão
v0.12.4
Issues abertas
22
Contribuidores
3

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

/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-task to 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-task again to get analysis-r2.md; the full revision history is preserved
  • Severity-classified reviews — review-code 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)

# 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:

TUICommand
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/, .npmrc files containing _authToken, AI tool OAuth/access token files, or .gitconfig there. Use the dedicated SSH and credential channels, and prefer .gitconfig.local with [include] for local Git preferences.

Protected paths are ignored by the hook even if they appear under ~/.agent-infra/dotfiles/:

Path patternReason
.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_aliasesagent-infra symlinks these to .host-shell-config/, including safe.directory and GPG sync state.
README.mdagent-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

  1. Install — npm install -g @fitlab-ai/agent-infra (or brew install fitlab-ai/tap/agent-infra on macOS, or use the shell script wrapper)
  2. Initialize — ai init in the project root to generate .agents/.airc.json and install the seed command
  3. Render — run update-agent-infra in any AI TUI to detect the bundled template version and generate all managed files
  4. Develop — use built-in skills to drive the full lifecycle: analysis → analysis-review → design → design-review → code → code-review → commit
  5. 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                  │
└───────────────────────────────────────────────────────┘

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 after npm 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 the colima command is missing, agent-infra auto-installs and starts Colima via Homebrew on first run. To use OrbStack or Docker Desktop instead, set sandbox.engine in .agents/.airc.json.

Engine resource configuration

Enginevm.cpuvm.memoryvm.diskApply modeNotes
Colimaappliedappliedappliedon-startVM must be restarted (ai sandbox vm stop && ai sandbox vm start) for changes to take effect.
OrbStackappliedappliedwarnedhotApplied via orb config set on every invocation. OrbStack manages disk via thin provisioning.
Docker DesktopwarnedwarnedwarnedmanualResources 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 after npm 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 docker
    

    Validate with docker info — it should succeed without sudo.

    GPG signing works when the host gpg-agent and signing key are available; if key sync fails, ai sandbox create falls 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 info fails, check systemctl --user status docker and confirm DOCKER_HOST points at $XDG_RUNTIME_DIR/docker.sock.
  • If SSH files are still unreadable inside the sandbox, confirm the shell has not overridden DOCKER_HOST or 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 the podman-docker shim (sudo dnf install podman podman-docker; optionally sudo touch /etc/containers/nodocker to silence its per-command notice).
  • SELinux-enforcing hosts (Fedora / RHEL): ai sandbox create automatically labels bind mounts with Docker's shared :z flag — no setup required. Set AGENT_INFRA_SELINUX_DISABLE=1 to opt out for debugging.
  • ai sandbox vm is a no-op on Linux. Linux uses native Docker directly with no VM to manage; use ai sandbox create, ai sandbox exec, ai sandbox start, ai sandbox refresh, ai sandbox ls, ai sandbox rebuild, ai sandbox rm, and ai sandbox prune directly.

Windows

  • ai init, ai sync, etc.: should work after npm 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

SkillDescriptionParametersRecommended use case
create-taskCreate a task scaffold from a natural-language request and cascade Issue creation through the platform rule when available.descriptionStart a new feature, bug-fix, or improvement from scratch.
import-issueImport a GitHub Issue into the local task workspace.issue-numberConvert an existing Issue into an actionable task folder.
analyze-taskProduce a requirement analysis artifact for an existing task.task-idCapture scope, risks, and impacted files before designing.
review-analysisReview the requirement analysis and classify findings by severity.task-idConfirm the analysis is complete before design.
plan-taskWrite the technical plan with a review checkpoint.task-idDefine the approach after analysis approval.
review-planReview the technical plan and classify findings by severity.task-idConfirm the design is actionable before coding.
code-taskImplement the approved plan or fix code review findings, producing a code report.task-idWrite code, tests, and docs after plan approval, or handle review feedback.
review-codeReview the code and classify findings by severity.task-idRun a structured code review before merging.
complete-taskMark the task complete and archive it after all gates pass.task-idClose out a task after review, tests, and commit are done.

Task Status

SkillDescriptionParametersRecommended use case
check-taskInspect the current task status, workflow progress, and next step.task-idCheck progress without modifying task state.
block-taskMove 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-taskRestore 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

SkillDescriptionParametersRecommended use case
create-prOpen 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-prWatch 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

SkillDescriptionParametersRecommended use case
commitCreate a Git commit with task updates and copyright-year checks.NoneFinalize a coherent change set after tests pass.
testRun the standard project validation flow.NoneValidate compile checks and unit tests after a change.
test-integrationRun integration or end-to-end validation.NoneVerify cross-module or workflow-level behavior.

Release

SkillDescriptionParametersRecommended use case
releaseExecute the version release workflow.version (X.Y.Z)Publish a new project release.
create-release-noteGenerate release notes from PRs and commits.version, previous-version (optional)Prepare a changelog before shipping.
post-releaseRun post-release follow-up tasks (version bump, artifact rebuild, optional demo capture).NoneFinalize the release cycle after pushing a release tag.

Security

SkillDescriptionParametersRecommended use case
import-dependabotImport a Dependabot alert and create a remediation task.alert-numberConvert a dependency security alert into a tracked fix.
close-dependabotClose a Dependabot alert with a documented rationale.alert-numberRecord why an alert does not require action.
import-codescanImport a Code Scanning alert and create a remediation task.alert-numberTriage CodeQL findings through the normal task workflow.
close-codescanClose a Code Scanning alert with a documented rationale.alert-numberRecord why a scanning alert can be safely dismissed.

Project Maintenance

SkillDescriptionParametersRecommended use case
upgrade-dependencyUpgrade a dependency from one version to another and verify it.package, old-version, new-versionPerform controlled dependency maintenance.
refine-titleRewrite an Issue or PR title into Conventional Commits format.numberNormalize inconsistent GitHub titles.
init-labelsInitialize the repository's standard GitHub label set.NoneBootstrap labels in a new repository.
init-milestonesInitialize the repository's milestone structure.NoneBootstrap milestone tracking in a new repository.
archive-tasksArchive 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-infraUpdate the project's collaboration infrastructure to the latest template version.NoneRefresh 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:

TUICommand
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 ejected mechanism 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.

FieldRequiredMeaning
nameYesDisplay name shown in reports and next-step guidance, for example <your-tui-name>.
dirYesCommand directory relative to the project root, for example .<your-tui>/commands. The path must stay inside the project root.
invokeYesUser-facing command template used in next-step guidance.

Supported invoke placeholders:

PlaceholderReplaced withExample
${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.

WorkflowBest forStep chain
feature-developmentBuilding a new feature or capabilityanalysis -> analysis-review -> design -> design-review -> code -> code-review -> commit
bug-fixDiagnosing and fixing a defect with regression coverageanalysis -> analysis-review -> design -> design-review -> code -> code-review -> commit
refactoringStructural changes that should preserve behavioranalysis -> analysis-review -> design -> design-review -> code -> code-review -> commit
code-reviewReviewing an existing PR or branchanalysis -> 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

FieldMeaning
projectProject name used when rendering commands, paths, and templates.
orgGitHub organization or owner used by generated metadata and links.
languagePrimary project language or locale used by rendered templates.
templateVersionInstalled template version for future upgrades and drift tracking.
templatesOptional external template overlay configuration.
templates.sourcesOptional ordered list of external template sources. Only type: "local" is supported today.
skillsOptional custom skill sync configuration.
skills.sourcesOptional ordered list of external custom skill sources. Only type: "local" is supported today.
customTUIsOptional top-level list of custom AI TUI adapters.
filesPer-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.

StrategyMeaningUpdate behavior
managedagent-infra fully controls the fileRe-rendered and overwritten on update
mergedTemplate content and user customizations coexistAI-assisted merge preserves local additions where possible
ejectedGenerated once and then owned by the projectNever 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

  1. Remove the path from the managed array in .agents/.airc.json.
  2. Add the same path to the ejected array.
  3. 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

Ver o original no GitHub

Bom para

Relacionados