ACP Variables

ACP variables let you write one protocol and customize it for different projects. Variables are defined in the protocol and resolved at parse time.

Defining variables

variables:
  max_reviewers:
    type: number
    default: 3
    description: "Maximum number of reviewers"
  target_branch:
    type: string
    default: main
    description: "Branch to review against"
  strict_mode:
    type: boolean
    default: false
    description: "Require all reviewers to approve"

Supported types

Type	Values	Example
string	Any text	"main", "src/**"
number	Integer or float	3, 10.5
boolean	true or false	true

Using variables

Reference variables with ${var_name} anywhere in the protocol:

roles:
  reviewer:
    count: "1-${max_reviewers}"
    description: "Review changes against ${target_branch}"

phases:
  review:
    description: "Review mode: strict=${strict_mode}"

Variables work in strings, numbers, and nested values. The parser resolves them before the protocol is loaded.

Overriding at runtime

CLI

# Override when loading a protocol
wgl protocol load spec.yaml --var max_reviewers=5 --var target_branch=develop

# Override when starting a brood
wgl up --var max_reviewers=5

SDK

import { parseProtocol } from '@agentcoordinationprotocol/spec';

const protocol = parseProtocol(yaml, {
  variables: { max_reviewers: 5, target_branch: 'develop' },
});

brood.yaml

hives:
  main:
    acp: code-review.acp.yaml
    variables:
      max_reviewers: 5
      target_branch: develop

Resolution order

1. Explicit overrides (CLI flags, SDK options, brood.yaml)
2. Default values from the protocol
3. Error if no default and no override provided

Use cases

One protocol, many teams

team-review.acp.yaml

variables:
  team_size: { type: number, default: 3 }
  language: { type: string, default: "typescript" }
  coverage_threshold: { type: number, default: 80 }

Team A: --var team_size=5 --var language=python --var coverage_threshold=90 Team B: --var team_size=2 --var language=rust

Environment-specific configuration

variables:
  budget: { type: number, default: 5 }
  model_tier: { type: string, default: "haiku" }

governance:
  budget:
    max_cost: ${budget}

roles:
  worker:
    model_hint: ${model_tier}

Development: --var budget=1 --var model_tier=haiku Production: --var budget=50 --var model_tier=sonnet