# Mesh Protocol v0 (Draft)

Decentralized coordination for multi-agent software work. This protocol is designed
to work with BotBus (communication + claims), Beads (work tracking), MAW (workspaces),
Botty (agent runtime), and Botcrit (reviews). No single agent is privileged.

## Goals

- No central coordinator or hierarchy.
- Any agent can pick up work or spawn helpers.
- Recoverable state from shared logs (Beads + BotBus + Botcrit).
- Avoid conflicts via claims and short-lived leases.

## Roles

- **Agent**: any peer that can claim work and perform tasks.
- **Worker**: agent performing a specific bead.
- **Reviewer**: agent that provides review comments/approvals via Botcrit.

## Messages and Labels

BotBus is chat-first. Keep messages human-readable. Use labels only when you need
machine-readable events. Project is implied by channel name.

Recommended labels:

- `mesh`
- `spawn-request`, `spawn-ack`
- `task-claim`, `task-update`
- `review-request`, `review-done`

Example:

```
botbus send myproj "Working on bd-123" -L mesh -L task-claim
botbus send myproj "Review requested: cr-9ab1 (bd-123)" -L mesh -L review-request
```

## Claims and Leases

Claims are advisory locks that prevent conflicts. Claims auto-post a message to
`#general` (with structured meta), so you don't need to announce claims yourself.

Use BotBus claims for:

- Files/paths: `botbus claim "src/**" -m "bd-123"`
- Beads: `botbus claim "bead://project/bd-123" -m "bd-123"`
- Agents (lease): `botbus claim "agent://reviewer-security" -m "bd-123"`

Guidelines:

- Claims are short-lived. Renew periodically with a status update.
- If a claim appears stale (no updates), another agent may re-claim.
- Release all claims when work is done.

## Task Lifecycle

1. Create bead in Beads (`br create`).
2. Claim the bead/paths (auto-announced in `#general`).
3. Create a MAW workspace and work in isolation.
4. Post periodic `task-update` messages.
5. Open a Botcrit review and send a labeled `review-request`.
6. After review, address feedback, update bead, and close.

## Spawning Agents

Any agent may spawn another agent if the role is offline.

Spawn flow:

1. Check current agents: `botbus agents`.
2. Claim the agent lease: `botbus claim "agent://role"`.
3. Spawn the agent (e.g., `botty spawn --name role -- <runtime>`).
4. Send `spawn-ack` with role and project.
5. If the agent exits, it should release its lease and send a shutdown update.

## Reviewer Loop

Reviewer agents should run a loop:

- Check for `review-request` messages addressed to them.
- Run `crit` commands to view and comment.
- Send `review-done` when finished.
- Sleep with backoff when no reviews are pending.

## Failure Recovery

- If an agent disappears, its work remains in Beads and Botcrit.
- Claims without recent updates are considered stale and can be re-claimed.
- Reviews are anchored in Botcrit events and can be resumed by any peer.

## Versioning

- Protocol version is carried in every message: `protocol: mesh-v0`.
- Breaking changes require a new version and dual-support period.