beadboard/skills/beadboard-driver/references/coordination-system.md

Coordination System Reference

This document is the canonical reference for BeadBoard agent coordination via bb agent and bd mail delegation.

Command Surface

All commands are available through the global CLI:

bb agent <command> [flags]

Identity Commands

Register/update an agent:

bb agent register --name silver-scribe --role ui [--display "Silver Scribe"] [--force-update]

List agents (optional filters):

bb agent list [--role ui] [--status working]

Show one agent:

bb agent show --agent silver-scribe

Refresh liveness lease:

bb agent activity-lease --agent silver-scribe

Mail Commands

Send message:

bb agent send \
  --from silver-scribe \
  --to graph-scout \
  --bead beadboard-izs.4 \
  --category HANDOFF \
  --subject "UI wiring complete" \
  --body "Please verify graph parity" \
  [--thread bead:beadboard-izs.4]

List inbox:

bb agent inbox --agent graph-scout [--state unread|read|acked] [--bead beadboard-izs.4] [--limit 25]

Mark as read:

bb agent read --agent graph-scout --message msg_20260304_001122_abcd

Acknowledge:

bb agent ack --agent graph-scout --message msg_20260304_001122_abcd

Reservation Commands

Reserve scope:

bb agent reserve --agent silver-scribe --scope src/components/social --bead beadboard-izs.4 [--ttl 120] [--takeover-stale]

Release scope:

bb agent release --agent silver-scribe --scope src/components/social

Show reservation/message status:

bb agent status [--agent silver-scribe] [--bead beadboard-izs.4]

Message Model

Categories:

• HANDOFF
• BLOCKED
• DECISION
• INFO

States:

• unread
• read
• acked

State machine:

• unread -> read -> acked
• ack on unread implicitly sets read_at and acked_at

Required acknowledgment:

• requires_ack=true for HANDOFF and BLOCKED
• requires_ack=false for DECISION and INFO

WHEN-to-Use Trigger Map

1. Task completed and ownership moves to another agent: send HANDOFF.
2. Work blocked by dependency, missing input, or failing environment: send BLOCKED.
3. Input needed but not a hard blocker: send DECISION.
4. FYI telemetry or non-blocking update: send INFO.
5. You receive a required-ack (HANDOFF/BLOCKED) message and have processed it: run ack.
6. You receive a message and need to indicate it was seen but not completed: run read.
7. You start modifying a scoped area: reserve.
8. You finish scoped work: release.

Inbox Polling Protocol

Minimum polling moments:

• Session start (before claiming work)
• Before switching beads
• Before closing a bead
• Whenever local state becomes stuck

Recommended interval:

• Every 60-120 seconds during active execution

Handling required-ack backlog:

• Prioritize unacked BLOCKED first, then HANDOFF
• If action taken, run ack immediately
• If waiting on external input, reply with DECISION or INFO and keep task status accurate

Reservation Conflict Policy

Conflict semantics for same/overlapping scope:

• Active owner blocks takeover: RESERVATION_CONFLICT
• Stale/evicted/expired owner requires explicit intent: RESERVATION_STALE_FOUND unless --takeover-stale
• Same owner can refresh reservation without conflict

Operational rule:

• Never force takeover without --takeover-stale when warned
• Include bead id in every reserve action for traceability

Worked HANDOFF Flow (End-to-End)

1. Sender completes implementation:

bb agent send \
  --from silver-scribe \
  --to graph-scout \
  --bead beadboard-izs.4 \
  --category HANDOFF \
  --subject "Social badges complete" \
  --body "Please validate edge cases and close" 

2. Recipient checks inbox:

bb agent inbox --agent graph-scout --state unread

3. Recipient reads details:

bb agent read --agent graph-scout --message <message-id>

4. Recipient validates and accepts handoff:

bb agent ack --agent graph-scout --message <message-id>

5. Recipient proceeds with assigned bead work and updates bd status/notes.

bd mail Delegate Setup (bb-backed)

bd mail delegates to external provider using:

• BEADS_MAIL_DELEGATE / BD_MAIL_DELEGATE env vars
• or mail.delegate config key

For BeadBoard driver skill, session preflight configures:

bd config set mail.delegate "node <abs-path>/skills/beadboard-driver/scripts/bb-mail-shim.mjs"

Then:

• bd mail inbox -> bb agent inbox --agent <BB_AGENT>
• bd mail send ... -> bb agent send --from <BB_AGENT> ...
• bd mail read <id> -> bb agent read --agent <BB_AGENT> --message <id>
• bd mail ack <id> -> bb agent ack --agent <BB_AGENT> --message <id>

Required env:

export BB_AGENT=silver-scribe

Fallback behavior if bb is missing:

• Shim exits non-zero and prints: bb-mail-shim: bb command not found in PATH.