Manage teams as code with forge iac

If you manage more than a couple of teams, you'll want them in version control — reviewable in pull requests and reproducible across environments. forge iac treats your teams like infrastructure: define them in a forge.yaml file and reconcile with plan and apply, just like Terraform.

Step 1: Export your current teams

Start from what you already have. forge iac export writes every team you own into a manifest:

forge iac export          # writes forge.yaml

Each team gets a stable key (derived from its name if it didn't have one). The key is how Forge matches a team across applies — keep it stable even if you rename the team.

Step 2: Edit the manifest

Commit forge.yaml to your repo and edit it like any code. Add a team, tweak a system prompt, add an agent:

version: 1
teams:
  - key: code-review
    name: Code Review Team
    description: Reviews pull requests
    agents:
      - role: reviewer
        name: Senior Reviewer
        system_prompt: You are an expert code reviewer...
      - role: security_auditor
        name: Security Auditor
        system_prompt: You audit code for OWASP Top 10 issues...

Step 3: Plan before you apply

forge iac plan shows exactly what would change — and touches nothing:

forge iac plan

  + create   bid-response (5 agents)
  ~ update   code-review (2 agents)
  = no-change marketing-campaign

  Plan: 1 to create, 1 to update, 0 to destroy.

Step 4: Apply

forge iac apply reconciles your teams to the manifest, prompting before it makes changes. Add --yes to skip the prompt in CI, and --prune to delete IaC-managed teams you've removed from the file:

forge iac apply             # interactive
forge iac apply --yes       # for CI pipelines
forge iac apply --prune     # remove teams not in forge.yaml

Run it from CI

Because applies are idempotent and matched by key, you can run forge iac apply --yes on every merge tomain to keep your Forge teams in lockstep with your repo. Teams, their agents, and each agent's tools are all reconciled from the manifest — add a tools: list under any agent (the same shape POST /api/v1/teams accepts) and export will pull your existing ones in.