ACP YAML

Top-level keys

acp: "1.0"                # Version (required)
name: string              # Machine identifier (required)
title: string             # Human-readable title
description: string       # Protocol description
roles: object             # Agent type definitions
phases: object            # Workflow stages
resources: array          # Claimable items
rules: object             # Per-role per-phase steps
governance: object        # Budget, heartbeat, quorum
variables: object         # Parameterization
topics: array             # Cross-namespace pub/sub

roles

roles:
  role_name:
    description: string           # What this role does
    count: number | string | object  # Agent count
    model_hint: string            # Suggested model
    scope: array                  # File access patterns
    primitives:
      env: array                  # Environment tool whitelist
      acp: array                  # ACP tool whitelist
    wait:
      types: array                # Event types to sleep on
      max_timeout: number         # Max sleep time (ms)
    reasoning_effort: string      # low | medium | high
    context: number               # Context windows to maintain
    agents: number                # Override count (0 = human)

count formats

Format	Example	Meaning
Number	2	Exactly 2
Min+	"2+"	At least 2
Range	"1-3"	Between 1 and 3
Array	[2, 5]	Between 2 and 5
Object	{ default: 3, min: 1, max: 10 }	Full config
Zero	0	Human-controlled

primitives.env values

read_file, write_file, patch_file, list_files, glob, grep, shell, git_status, git_diff, git_commit, git_log, fetch, scrape

primitives.acp values

publish, claim, release, get_state, set_state

phases

phases:
  phase_name:
    description: string              # What happens in this phase
    exit_condition:                   # When to transition
      state_key: string              # Key to watch
      equals: string                 # Value to match
      # OR
      event: string                  # Event type to trigger exit
      # OR
      timeout_ms: number             # Timeout
    allowed_transitions: array       # Valid next phases
    timeout_ms: number               # Phase timeout

resources

resources:
  - name: string                     # Resource identifier
    description: string              # What it represents
    max_claims: number               # Max concurrent claims (default: 1)

rules

rules:
  role_name:
    phase_name:
      steps:
        - action: string             # external | publish | set_state | claim | release
          description: string
          event: string              # For publish action
          key: string                # For set_state action
          value: string              # For set_state action
          resource: string           # For claim/release action

governance

governance:
  budget:
    max_cost: number                 # USD hard limit
    warn_at: number                  # 0-1 fraction for warning
  heartbeat:
    interval_ms: number              # Heartbeat interval
    dead_after_ms: number            # Consider dead after this silence
    auto_release_claims: boolean     # Release claims on death
  quorum:
    min_agents: number               # Minimum for decisions
  approval:
    required_for: array              # Actions needing approval
    approvers: array                 # Roles that can approve
  escalation:
    on_budget_warn: string           # notify | pause | halt
    on_agent_death: string           # redistribute | notify | spawn_replacement
    on_quorum_loss: string           # pause | halt | notify

variables

variables:
  var_name:
    type: string                     # string | number | boolean
    default: any                     # Default value
    description: string              # What this variable controls

Reference with ${var_name} anywhere in the protocol.

topics

topics:
  - name: string                     # Topic channel name
    description: string

Used for cross-namespace pub/sub in Honeycomb.