# Fleet Coordination Architecture — Multi-Model Synthesis
*4 models consulted: Kimi K2.5, Sonnet 4, DeepSeek (Builder perspective), MiniMax M2.5 (pending)*
*Date: 2026-02-17 05:57 AEDT*

---

## 🔑 Where ALL Models Agree (High-Confidence Design Decisions)

### 1. JSON over Markdown
Every model independently said: **use structured JSON, not markdown kanban boards.**
- LLMs parse structured data more reliably than prose
- JSON is scriptable (automated stall detection)
- Smaller token footprint (~1KB vs ~9KB)

### 2. Single Source of Truth: One Global State File
All proposed a central `status.json` or `WORLD.json` containing:
- Agent status (active/idle/blocked/stalled)
- Current task assignments
- Active blockers with timestamps
- Alerts and escalation triggers

### 3. Minimal Startup Protocol: 3 Files Max
Every model converged on agents reading exactly 3 files:
1. Global state (who's doing what, what's blocked)
2. Their own task queue / status
3. Agent-specific context (identity, domain knowledge)

### 4. Automated Stall Detection (Not Manual Scanning)
All models said: **don't have Rivet manually scan for stalls.** Use automated scripts:
- Cron job checks timestamps every 5 minutes
- Agent not updated in >15 min = auto-flagged
- Task not progressed in >30 min = auto-escalated
- Optional: auto-wake stalled agents via HTTP bridge

### 5. Lock Files or Claims to Prevent Duplication
All models proposed some form of task claiming/locking:
- Agent "claims" a task before starting
- Other agents see the claim and skip it
- Expired claims auto-released

---

## 🔀 Where Models Diverge (Design Choices Needed)

### Event Bus vs Direct File Updates
- **Kimi**: Proposes a rolling event bus (`EVENTS.json`) — agents publish events, others subscribe
- **Sonnet**: Similar event approach with `FLOW.json` for dependency tracking
- **Builder/DeepSeek**: Says event bus is overengineered — just update `status.json` directly

**Rivet's take:** Builder is right for now. Event bus is elegant but adds complexity. Start simple, add events later if needed.

### Hierarchical Scaling (Squad Leaders)
- **Kimi**: Proposes squad leaders for 20+ agents (Engineering Lead, Business Lead, etc.)
- **Sonnet**: Similar department hierarchy with partitioned workspaces
- **Builder/DeepSeek**: Says we're at 8 agents, don't overengineer for 20

**Rivet's take:** Design the file structure to support hierarchy later, but don't build it now.

### State Machine Complexity
- **Kimi**: Full state machines with transition conditions per task
- **Sonnet**: Similar complexity with capability-based assignment
- **Builder/DeepSeek**: Simple status fields (backlog/in_progress/blocked/done) are enough

**Rivet's take:** Start with simple status. Add state machine transitions when we actually need conditional logic.

---

## ⚠️ Builder's Practical Warnings

The Builder perspective (DeepSeek) flagged critical implementation issues:

1. **Current system burns 17KB/cycle across shared files** — needs to drop to ~1.5KB
2. **Kanban board is duplicated** (shared/ and memory/fleet/) — wasted tokens
3. **No standardized startup protocol** — each agent reads different files
4. **Manual coordination is Rivet's bottleneck** — automate stall detection
5. **Markdown-based system will break at 10+ agents** — switch to JSON now

---

## 📐 Recommended Architecture (Synthesis)

### Phase 1: Build Today
```
/home/ccuser/shared/
├── fleet-state.json        # Single source of truth (~1KB)
├── ROADMAP.md              # Goals (read once per session, not every heartbeat)
├── LESSONS.md              # Shared mistakes (read once per session)
└── locks/                  # Task claim files
    ├── grant-research.lock
    └── lead-enrichment.lock

/home/ccuser/{agent}/
├── SOUL.md                 # Identity (read once)
├── AGENTS.md               # Operating rules (read once)
├── queue.json              # Agent's personal task queue
└── status.json             # Agent's current state (updated every heartbeat)
```

### fleet-state.json Schema
```json
{
  "timestamp": "2026-02-17T06:00:00Z",
  "cycle": 42,
  "agents": {
    "harper": {
      "status": "active",
      "task": "grant-research",
      "last_heartbeat": "2026-02-17T05:45:00Z",
      "progress": 0.7,
      "blocked_on": null
    }
  },
  "tasks": {
    "in_progress": [...],
    "blocked": [...],
    "backlog": [...]
  },
  "alerts": [],
  "decisions_needed": []
}
```

### Agent Heartbeat Protocol (Every Cycle)
1. Read `fleet-state.json` (1KB) — what's happening
2. Read own `queue.json` (0.5KB) — what should I do
3. Do the work
4. Update own `status.json` — what I did
5. Chief of Staff merges agent statuses into fleet-state.json

### Automated Monitoring
- `stall-detector.js` runs every 5 min via cron
- Checks all agent `status.json` timestamps
- Updates `alerts` in fleet-state.json
- Auto-wakes stalled agents via HTTP bridge

### Phase 2: Next Week
- Add task dependency graph
- Add capability-based assignment
- Performance tracking (estimated vs actual)

### Phase 3: When We Hit 15+ Agents
- Department-level coordination
- Squad leaders
- Partitioned workspaces