multi-agent-protocol

# Multi-Agent Collaboration Protocol

Production playbook for orchestrating multiple sub-agents in OpenClaw with structured task
flow, quality gates, inter-agent communication, and automatic fault recovery.

Synthesized from community research: `subagent-driven-development`, `beads`, `swarm-self-heal`,
`agent-team-orchestration`, and `http-retry-circuit-breaker` patterns.

---

## When to Use

Use this skill when:
- Spawning 2+ sub-agents on a complex task
- Tasks have dependencies between agents
- Quality matters (not just "done", but "correct and well-built")
- You need fault tolerance without manual intervention
- Multiple agents need to share state without going through the orchestrator

**Don't use for:**
- Single-agent tasks (unnecessary overhead)
- One-off spawns with no handoff
- Simple question delegation

---

## Core Principles

1. **Spec-First** — No spawning without a spec file. No spec = no work starts.
2. **Two-Stage Review** — Every implementation goes through Spec Review, then Quality Review.
3. **Serial Implementation** — Only one Implementer runs at a time. Parallel = research/analysis only.
4. **Blackboard Communication** — Agents read/write a shared file directly. Orchestrator is not a relay.
5. **Circuit Breaker** — Failures have a ceiling. After threshold → alert human, don't loop forever.
6. **Fixed sessionKeys** — Same role = same sessionKey = agent memory persists across spawns.

---

## Directory Layout

```
{project-root}/
  .beads/              ← beads task graph (git-tracked, auto-managed)
  specs/
    {task-id}.md       ← Task spec (MUST exist before spawning Implementer)
  shared/
    blackboard.json    ← Live state bus (any agent reads/writes directly)
    artifacts/
      {role}/          ← Each agent's output artifacts
```

---

## Task Lifecycle

```
Write Spec → bd create → bd ready → Claim → Implement → Self-Review
  → Spec Review → Quality Review → bd close → bd sync
```

---

## Step 1 — Write the Spec

Before spawning anythin...