brood.yaml

Top-level

name: string              # Project name (required)
provider: string          # Default LLM provider (required)
hives: object             # Map of hive name → hive config (required)

Provider format

# Full: provider/model
provider: cerebras/llama-3.3-70b

# Aliases
provider: fast       # → cerebras/llama-3.3-70b
provider: smart      # → openai/gpt-4o
provider: local      # → ollama/llama3.3

# Provider only (uses catalog default model)
provider: cerebras   # → cerebras/llama-3.3-70b
provider: groq       # → groq/llama-3.3-70b
provider: anthropic  # → anthropic/claude-sonnet
provider: openai     # → openai/gpt-4o
provider: ollama     # → ollama/llama3.3

Hive config

hives:
  my-hive:
    acp: string | object     # ACP protocol (file path, URL, or inline)
    agents: array             # Agent definitions
    dances: string            # Dance file path (ESM module)
    variables: object         # Variable overrides for protocol
    workspace: string         # 'real' (default) or 'memfs'
    plugins: array            # Additional incubator plugins

Field aliases

Canonical	Alias
acp	spec, protocol
agents	workers
dances	logic

Agent definition

agents:
  - role: string              # Role name from ACP spec (required)
    type: string              # worker | drone | claude | mock (default: drone)
    provider: string          # Override default provider
    tools: array              # Filter propolis tools (worker type only)
    wake_on: object           # Reactive sleep/wake config
    agents: number            # Agent count (0 = human-controlled)

type

Value	Description
worker	In-process agent with propolis tools (file, shell, git, web, PTY)
drone	MCP subprocess with ACP-only tools
claude	Claude Code instance via Agent SDK
mock	Testing agent with action sequences (no LLM)

tools (worker type)

Available tools to filter:

tools:
  - read_file
  - write_file
  - patch_file
  - list_files
  - glob
  - grep
  - shell
  - git_status
  - git_diff
  - git_commit
  - git_log
  - fetch
  - scrape

Omit tools to allow all propolis tools.

wake_on

wake_on:
  types: [task.assigned, review.requested]  # Event types to wake on
  timeout: 300000                            # Max sleep time (ms)

Glob patterns supported: turn.* matches turn.player_2.

Mock agent behavior

- role: test_bot
  type: mock
  behavior:
    - action: publish
      type: greeting
      data: { message: "Hello!" }
    - action: set_state
      key: last_event
      value: $last.type       # Template: previous action result
    - action: claim
      resource: task-1

$last.field resolves to a field from the previous action’s result.

Complete example

name: code-review-team
provider: cerebras/llama-3.3-70b

hives:
  review:
    acp: code-review.acp.yaml
    dances: review-logic.js
    variables:
      max_reviewers: 3
      target_branch: main
    workspace: real
    agents:
      - role: author
        type: worker
        provider: anthropic/claude-sonnet
        tools: [read_file, write_file, patch_file, shell, git_status, git_diff, git_commit]
      - role: reviewer
        type: drone
        wake_on:
          types: [code.submitted, revision.complete]
      - role: lead
        type: drone
        provider: anthropic/claude-opus