Protocol Specification

Fleet coordinates distributed AI coding agents through two plain Markdown files committed to your git repository. Any machine that can read and write to GitHub can participate in a Fleet.

---

FLEET.md — The Fleet Manifest

Lives on the main branch. Written by the commander. Read by all ships.

Schema

# Fleet manifest
Updated: <ISO timestamp>

## Commander
host: <hostname>  |  last_checkin: <ISO timestamp>  |  status: active|offline|transferred
timeout_minutes: 15

## Active missions
| ID | Branch | Ship | Agent | Status | Depends | Blocker |
|----|--------|------|-------|--------|---------|---------|
| M1 | feature/auth | ship-a | claude-code | in-progress | none | none |

## Merge queue
- M2 feature/ratelimiter — CI green, awaiting human approval

## Completed
- M0 feature/setup merged 2026-03-21

Mission status values

Status	Meaning
pending	Created, waiting for dependencies
ready	Dependencies complete, not yet assigned
assigned	Commander dispatched to a ship
in-progress	Ship is executing
blocked	Ship reported a blocker
stalled	No MISSION.md progress past stall threshold
completed	Ship marked done
merge-queued	Merge commander triggered
merged	PR approved and merged to main
failed	Unrecoverable — needs human

---

MISSION.md — The Ship’s Mission Log

Lives on each ship’s feature branch. Written by the ship. Read by the commander every poll cycle.

Critical: Ships push MISSION.md on a configurable interval (default: 60 seconds) even when no progress has been made. This push updates last_push and serves as a heartbeat. A missing or stale heartbeat signals the commander to take recovery action.

Schema

# Mission log — <branch-name>
Ship: <ship-id>  |  Agent: <adapter-name>  |  Status: <status>

## Mission brief
<Natural language task description from the commander>

## Steps
- [x] Completed step
- [ ] Pending step

## Blockers
<"none" or description of blocker>

## Heartbeat
last_push: <ISO timestamp>
push_interval_seconds: 60

---

FLEET_CONTEXT.md — Broadcast Intelligence

Optional. Generated by fleet brief --generate. Lives on main. All ships pull it before starting their mission.

Contains:

• Architecture overview
• Key directories and their purpose
• Coding conventions and patterns
• Active branches and their owners
• Do-not-touch list (files locked by other ships)

Ships inject this into their agent system prompt, skipping the 15-30 turn codebase exploration phase.

---

Task brief format

When the commander assigns a mission, it writes .fleet/task_brief.json to the ship’s branch:

{
  "mission_id": "M1",
  "branch": "feature/auth",
  "ship_id": "ship-a",
  "adapter": "claude-code",
  "description": "Implement GitHub OAuth flow. Callback at /auth/github/callback. Use existing session middleware. Tests required.",
  "depends_on": [],
  "context_file": "FLEET_CONTEXT.md",
  "created_at": "2026-03-22T14:00:00Z"
}

---

Heartbeat protocol

Config key	Default	Behaviour
heartbeat_interval_seconds	60	How often ship pushes MISSION.md
stall_threshold_minutes	30	No progress → shadow ship dispatched
unresponsive_threshold_minutes	10	No heartbeat → ship flagged dead
commander_poll_minutes	5	How often commander reads all ship states

---

Commander election

FLEET.md records the active commander. Any machine can claim the commander role:

fleet command --resume   # claim from FLEET.md, continue where previous commander left off
fleet command --handoff  # gracefully transfer to another machine

The full fleet state lives in git. No data is lost when a commander machine goes offline.

---

Implementing the protocol

Any tool can implement the Fleet protocol by:

1. Reading FLEET.md from the main branch
2. Writing MISSION.md to the ship’s feature branch on a 60-second interval
3. Reading .fleet/task_brief.json for mission instructions
4. Marking status: completed in MISSION.md when done

See adapters for the adapter interface.