Queens, Workers & Drones

Honeybee agents come in three types, each with different capabilities and costs. The hierarchy mirrors real bee colonies — not as a metaphor, but as an architecture decision.

Queens

Orchestration agents. Queens read specs, spawn workers, monitor progress, and make strategic decisions.

• Model tier: Opus (most capable, most expensive)
• Tools: Full access — wgl CLI, file I/O, shell, git, PTY
• Role: Read orders, write brood configs, spawn nests, monitor health, intervene when stuck
• Count: Typically 1 per project (can spawn sub-Queens for complex projects)

Queens don’t write code. They think, delegate, and course-correct. A Queen reads the project spec, decomposes it into tasks, writes brood.yaml configs for each work stream, and spawns worker nests. Then it monitors — watching telemetry, reading test results, and intervening when something goes wrong.

# The Queen is just a Claude Code instance with a management prompt
# Same spawn mechanism, same container, same tools
# Different system prompt = different behavior
roles:
  queen:
    description: "Project architect. Read orders, decompose tasks, spawn workers."
    count: 1
    model_hint: opus

Key insight: The Queen IS the human with a system prompt. The same tools (wgl), the same decisions, the same patterns. We know it works because we used the exact same workflow — one person coordinating Claude Code sessions — to build the entire platform.

Workers

Execution agents. Workers have full environment tools and do the actual building — reading files, writing code, running tests, deploying.

• Model tier: Sonnet or Haiku (depends on task complexity)
• Tools: Propolis (file I/O, shell, git, web, PTY) + ACP coordination
• Role: Claim tasks, write code, run tests, publish results
• Count: 1-5 per task (scales with parallelizable work)

Workers run in containers with real dev environments — git, npm, cargo, whatever the project needs. They claim tasks from the shared state, do the work, and publish completion events.

roles:
  frontend_worker:
    description: "React developer. Build UI components."
    count: 2
    model_hint: sonnet
    primitives:
      env: [read_file, write_file, shell, git_status, git_diff, git_commit]
      acp: [claim, release, publish, get_state, set_state]

Model tier matching: Complex architectural decisions → Sonnet. Repetitive tasks (CSS, tests, migrations) → Haiku. Workers don’t need to think big — they need to execute well in their lane.

Drones

Lightweight agents. Drones have ACP-only tools — no file system access, no shell. Good for review, analysis, voting, and coordination tasks.

• Model tier: Haiku (cheapest, fastest)
• Tools: ACP coordination only (publish, claim, state, events)
• Role: Review, analyze, vote, scout, coordinate
• Count: Unlimited (cheap to run)
• Execution: Serverless (Colony Durable Objects) — no container needed

Drones are ideal for tasks that don’t require environment access:

• Code review (read-only, provide feedback via events)
• Voting and decision-making (social deduction games)
• Scouting and analysis (read state, publish findings)
• Coordination helpers (watch for events, trigger workflows)

roles:
  reviewer:
    description: "Review code changes. Provide feedback via events."
    count: 3
    model_hint: haiku
    primitives:
      acp: [publish, get_state, set_state]
    # No env primitives — drones don't touch the filesystem

When to use which

Scenario	Queen	Worker	Drone
Decompose project into tasks	Yes
Write and test code		Yes
Review code changes			Yes
Run shell commands		Yes
Vote on decisions			Yes
Spawn sub-projects	Yes
Monitor health and costs	Yes
Scout for information			Yes
Deploy infrastructure		Yes

Agent types in brood.yaml

agents:
  # Worker: in-process tools, full environment access
  - role: developer
    type: worker
    tools: [read_file, write_file, shell, git_status, git_diff, git_commit]

  # Drone: MCP subprocess, ACP-only tools
  - role: reviewer
    type: drone

  # Claude: Claude Code instance via Agent SDK
  - role: architect
    type: claude

  # Mock: for testing — action sequences, no LLM calls
  - role: test_agent
    type: mock

Type comparison

Type	Execution	Tools	Cost	Use case
worker	In-process	Propolis (file, shell, git, web, PTY)	Medium	Building, testing, deploying
drone	MCP subprocess	ACP only	Low	Review, voting, coordination
claude	Agent SDK	Full Claude Code tools	High	Complex reasoning, architecture
mock	Action sequences	Dispatches to real stores	Free	Testing dance logic without LLM

Cost optimization

The hierarchy is also a cost structure. Use the cheapest agent that can do the job:

Opus Queen (1)     → $$$  — strategic decisions only
Sonnet Workers (3) → $$   — complex implementation
Haiku Workers (5)  → $    — repetitive tasks (CSS, tests, migrations)
Haiku Drones (10)  → ¢    — review, voting, coordination

A well-designed hive might use 1 Opus token for every 100 Haiku tokens. The Queen thinks; the drones execute. That’s how you optimize the bill.