# Multi-Agent Coordination Template

Use this template for decentralized mesh workflows across multiple agents.

## Mesh Protocol (Required)

Canonical spec: `https://raw.githubusercontent.com/bobisme/ai-docs/main/agents/mesh-protocol.md`.

Keep chat human-readable. Use labels for machine-readable events. Project is implied by channel.

Claims are mandatory for files, beads, and agent roles. Release claims when done.

## Setup (One-Time per Repo)

Use tool-provided AGENTS.md snippets when available:

- BotBus: `botbus agentsmd show` then `botbus agentsmd init`
- MAW: `maw agents init`
- Botcrit: `crit agents show` then `crit agents init`

Tools without injection should be added manually:

- Botty: add runtime/testing notes if needed
- Beads (br/bv): include the Beads Workflow block below

## BotBus Coordination

```bash
# Identity (once per session)
export BOTBUS_AGENT=$(botbus generate-name)

# Project status
botbus status
botbus history
botbus agents

# Communicate (chatty + labels)
botbus send myproj "Working on bd-123" -L mesh -L task-claim

# File and bead claims (auto-announce in #general)
botbus claim "bead://myproj/bd-123" -m "bd-123"
botbus claim "src/path/**" -m "bd-123"
botbus release --all
```

Conventions:

- Channels: `#general`, `#project-name`, `#project-topic`.
- Names: lowercase alphanumeric with hyphens.
- Messages: short, actionable, include bead IDs; use labels for event types.

## Agent Lease + Spawn

```bash
# Check if role is online
botbus agents

# Claim agent lease
botbus claim "agent://reviewer-security" -m "bd-123"

# Spawn (example)
botty spawn --name reviewer-security -- claude -p

# Announce in project channel
botbus send myproj "Spawned reviewer-security" -L mesh -L spawn-ack
```

## MAW Workspaces (jj)

```bash
maw ws list
maw ws create <assigned-name>
cd .workspaces/<assigned-name>
jj status
jj diff
jj describe -m "wip: working on X"
```

Stale workspace:

```bash
maw ws sync
```

## Reviews (Botcrit)

- Open a review and request reviewers with `crit reviews request`.
- If a reviewer is offline, claim `agent://reviewer-<name>` and spawn them.
- Reviewers loop on pending review requests, then send `review-done` messages (labels preferred).

## Beads Workflow (Required)

Create a bead before work. Do not edit `.beads/issues.jsonl` by hand.

```bash
br ready
br create --title="..." --description="..." --type=task --priority=2
br update <id> --status=in_progress
br close <id>
br sync --flush-only
```

Use `bv --robot-*` commands for dependency-aware planning.

Suggested BV loop:

```bash
bv --robot-triage
bv --robot-plan
bv --robot-priority
bv --robot-next
```

## Spawned Agent Template (Peer)

```text
You are a peer agent working on [TASK] (bead: [BEAD]).

Before starting:
1. export BOTBUS_AGENT=[AGENT_NAME]
2. botbus claim "bead://[PROJECT]/[BEAD]" -m "[BEAD]"
3. botbus claim "src/[path]/**" -m "[BEAD]"
4. maw ws create [WORKSPACE]
5. cd .workspaces/[WORKSPACE]
6. botbus send [PROJECT] "Working on [BEAD]" -L mesh -L task-claim

During work:
- Work only in your workspace
- Send task-update messages on progress or blockers

When done:
1. jj describe -m "[commit message]"
2. crit reviews create/request as needed
3. br update [BEAD] --status=closed
4. botbus send [PROJECT] "Done: [BEAD]" -L mesh -L task-update
5. botbus release --all
```

## Reviewer Agent Template

```text
You are a reviewer agent for [PROJECT].

Loop:
- Watch for review-request messages addressed to you
- Use crit to review/comment/approve
- Send review-done when finished
- Sleep/backoff when no reviews are pending
```