Coordination Bus
When to Use
Trigger phrases:
- "claim task", "coord status", "coordination status", "bus status"
- "heartbeat task", "complete task", "block task"
- Any multi-agent or multi-session work (RULES.md Rule 19)
Use cases:
- Claiming ownership of shared work before starting
- Signalling liveness while working
- Completing or blocking with a reason
- Checking who owns what before touching shared files
When NOT to use:
- Single-agent single-session trivial work (no bus needed)
- PaperClip issues (separate tracker — bus is for runtime ownership, not backlog)
Overview
The coordination bus (1ai-hub /coordination) records WHO owns WHAT task, what it depends on, and whether product-gate docs exist. A second claim on an owned task is rejected — the rejection is the conflict signal, not a bug.
Protocol
- Claim before work:
claim <task-id> as <your-agent-id>— via chat (CoordinationExecutor) or RESTPOST /coordination/tasks/{id}/claimwith{"owner_agent": "..."}. - Heartbeat while working:
heartbeat <task-id> as <owner>orPOST .../heartbeat. First heartbeat movesclaimed → in_progress. Stale heartbeat (>15 min) flags the task stuck in daemon supervision. - Finish:
complete <task-id> as <owner>orPOST .../complete. Blocked:block <task-id> as <owner>: <reason>orPOST .../blockwith{"reason": "..."}. - Dependencies: a task with
depends_oncannot be claimed until the dependency isdone. The bus rejects withblocked: dependency <id> is <status>. - Product gate: user-facing tasks carry
gate_required. Record docs viaPOST .../gate-docswith{"docs": "path/to/brainstorm.md,..."}before active work. Daemon flags gate violations every 60s.
Status
- Chat:
coord status [repo]— active tasks, stuck list, gate violations. - REST:
GET /coordination/active?repo=,GET /coordination/stuck,GET /coordination/gate-violations.
Anti-Rationalization Table
| Rationalization | Reality |
|---|---|
| "I'll just tell the other agent directly" | Private agreement is invisible to the daemon. Claim on the bus or the work doesn't exist. |
| "The claim rejection is a bug" | The rejection IS the conflict signal. Talk to the owner, don't retry. |
| "Gate docs later" | Active work without gate docs is flagged every 60s. Record docs first. |
| "Small task, skip the bus" | If two agents can touch it, it's not small. Claim it. |
Process
- Check —
coord status [repo]: is the task free? Are dependencies done? - Claim —
claim <id> as <owner>; rejection means someone owns it. - Work — heartbeat periodically; record gate docs if required.
- Close — complete with detail, or block with reason.
Verification
- Task claimed before any file touched
- Heartbeat fresh (< 15 min) while working
- Gate docs recorded for user-facing work
- Task completed or blocked with reason — never abandoned