STATE.yaml for Parallel Coordination

What if sub-agents could coordinate themselves? No orchestrator polling. No token-heavy status updates. Just a shared file.

The Problem with Orchestrators

Every status check burns tokens. Ten sub-agents checking in every few minutes? You're hemorrhaging tokens on coordination alone.

The Shared State File

Instead of agents talking to each other, they talk to a file:

# STATE.yaml
tasks:
  research_competitors:
    status: complete
    agent: sub-agent-1
    result: "Notes in /research/competitors.md"
  
  draft_outline:
    status: in_progress
    agent: sub-agent-2
  
  review_pricing:
    status: pending
    depends_on: research_competitors

Each sub-agent reads the file, claims available work, does it, writes results. No orchestrator needed.

Why It's Cheaper

• No polling — Agents check the file only when they need work
• No status conversations — State is written, not discussed
• No central bottleneck — Any agent can update anytime
• No lost context — File persists across sessions

Reading a file costs nothing. Writing a few lines costs almost nothing. Coordination overhead drops to near zero.

The Pattern

1. Read STATE.yaml — What's pending?
2. Claim a task — Update status to "in_progress"
3. Do the work
4. Write results — Update status to "complete"
5. Check for more — Any other tasks to claim?

Agents don't wait for permission. They see available work, they take it. First come, first served.

When to Use Each Approach

STATE.yaml wins when:

• Tasks are relatively independent
• You want maximum parallelism
• Token cost matters

Stick with an orchestrator when:

• Complex dependencies between tasks
• Real-time decision making needed
• Human oversight required between steps

Start with three fields: task name, status, result. Add complexity only when you need it. No special tooling. No message passing. Just files.

Sometimes the best coordination is no coordination at all.