Fleet

last-updated: 2026-05-07

Fleet runs multiple campaigns simultaneously through coordinated waves, sharing discoveries between them.

When to Use Fleet

• Work decomposes into 3+ independent streams
• Domains don't overlap in files (e.g., API + frontend + docs)
• You want institutional-scale throughput from a single session

Wave Mechanics

Wave 1: 2-3 agents run in parallel (worktree-isolated)
  │
  ← Collect results from all agents
  ← Compress each output to ~500-token discovery brief
  ← Merge branches into main
  │
Wave 2: 2-3 agents, informed by Wave 1 discoveries
  │
  ← Collect, compress, merge
  │
Wave N: Continue until work queue empty

Discovery Relay

The key innovation. After each wave:

1. Each agent's output is compressed to a ~500-token brief
2. Briefs capture: what was built, decisions made, discoveries, failures
3. Next wave's agents receive ALL previous briefs in their context
4. Agents don't rediscover what previous agents already found

Example: Wave 1 Agent A finds the API has rate limiting at 100 req/min. Wave 2 Agent C (building the frontend) starts with that knowledge and implements client-side throttling without hitting the limit first.

Worktree Isolation

A git worktree is a separate working directory linked to the same repository. Think of it as a lightweight clone — it shares the same .git history but has its own files and branch. This lets multiple agents edit files simultaneously without conflicts.

Every agent runs in its own git worktree:

• Separate working directory — no file conflicts between agents
• Independent git branch — clean merge path
• Dependencies auto-installed by the WorktreeCreate hook
• Environment files copied from main repo

Fleet Session Files

State lives in .planning/fleet/session-{slug}.md:

# Fleet Session: {name}

Status: active
Direction: {what was requested}

## Work Queue
| # | Campaign | Scope | Deps | Status | Wave | Agent | Branch | Evidence |
|---|----------|-------|------|--------|------|-------|--------|----------|
| 1 | API auth | src/api/ | none | merged | 1 | build | codex/api-auth | validator pass |
| 2 | Frontend | src/ui/ | none | validated | 1 | build | codex/frontend | validator pass |
| 3 | Integration | both | 1, 2 | pending | 2 | verify | - | - |

## Wave 1 Results
### Agent: api-builder
**Built:** JWT auth middleware
**Discoveries:** Uses jose library, tokens expire in 15min

## Shared Context
- API uses jose for JWT (inform frontend agents)
- 15min token expiry means frontend needs refresh logic

Citadel also ships a queue steward:

node scripts/fleet-steward.js --session .planning/fleet/session-{slug}.md

The steward parses the markdown table as the session DAG. It reports runnable tasks, dependency-blocked tasks, merge-order blockers, and same-wave scope conflicts. It is read-only unless --write is paired with --mark-failed, which marks the failed row and adds a repair task.

Fleet also reads .planning/verification/worktree-readiness/*.json. A task whose branch matches a blockFleet: true readiness report is shown under READINESS BLOCKED instead of READY TO RUN. Use --override-readiness only when a human has verified the worktree manually.

Shared State Merge Strategies

Parallel agents access shared .planning/ state. Each resource has a declared merge strategy to prevent silent overwrites:

Resource	File	Strategy
Discoveries	fleet/{session}/discoveries.jsonl	Append-only — each agent appends, never overwrites
Agent briefs	fleet/{session}/briefs/{agent}.md	Per-agent file — no conflicts possible
Session file	fleet/{session}-session.md	Lock-on-write — agent acquires .lock before editing, releases after
Campaign file	campaigns/{name}.md	Lock-on-write — same lock protocol
Telemetry	telemetry/agent-runs.jsonl	Append-only — atomic append per event
Wiki staging	wiki/staging/	Per-agent file — named by agent ID
Coordination claims	coordination/claims/	Per-scope file — one file per claimed directory

An agent that violates its resource's strategy may silently corrupt shared state. When in doubt, use append-only and let Fleet merge after the wave completes.

Consistency Voting

For high-stakes Fleet decisions, spawn 3 Phase Validators and require 2/3 agreement:

When to vote:

• A wave completes partially (some agents succeeded, some failed) and the next wave's scope depends on the outcome
• A failed validation merge would affect other agents' branches
• An abort decision would discard multiple agents' work

How to vote:

1. Spawn 3 Phase Validator agents with identical context
2. Each agent independently examines the evidence and returns a verdict (proceed / abort / retry)
3. Tally: majority verdict wins; timeout counts as proceed (never blocks indefinitely)
4. Log the vote and outcome to telemetry/agent-runs.jsonl

Coordination

Scope Overlap Prevention

Agents in the same wave MUST NOT touch the same files:

• Parent/child directories overlap: src/api/ and src/api/auth/ conflict
• Sibling directories are safe: src/api/ and src/ui/ don't conflict
• (read-only) scopes never conflict

Multi-Instance Coordination

If multiple Archon or Fleet instances run simultaneously:

• .citadel/scripts/coordination.js manages instance registration and scope claims
• Claims are file-based (no database needed)
• Dead instances cleaned up by npm run coord:sweep

Budget

• ~700K tokens per wave for agent outputs
• ~300K tokens reserved for Fleet's own orchestration
• Start with 2 agents per wave, scale up as you trust scope separation
• If context runs low: stop spawning waves, write continuation state

Commands

/fleet [direction]     Decompose and execute in parallel
/fleet [spec-path]     Read a spec file, decompose, execute
/fleet continue        Resume from session file
/fleet                 Health diagnostic → auto-select work

Scripts

Script	Purpose
.citadel/scripts/compress-discovery.cjs	Compress agent output to ~500-token briefs
.citadel/scripts/parse-handoff.cjs	Extract HANDOFF blocks from agent output
.citadel/scripts/coordination.js	Multi-instance scope coordination
.citadel/scripts/telemetry-log.cjs	Log agent events
.citadel/scripts/telemetry-report.cjs	Generate performance summaries
scripts/fleet-steward.js	Parse Fleet session DAGs, show ready/blocked/mergeable work, and create repair tasks
scripts/worktree-readiness.js	Record dependency, env, port, and health readiness for worktrees