/memtrace-fleet-first

name: memtrace-fleet-first
description: "Coordinate fleets of coding agents sharing one repo+branch: publish typed intents, classify edit episodes, and resolve conflicts before they collide. Use FIRST when multiple agents work the same repo+branch, before reading/planning/editing, when joining a fleet or handing work off, and when the user says two agents are changing the same thing, asks who should proceed, has a decision waiting, or asks you to mediate a Class C conflict. Covers branch-scoped publish-edit-record plus verdict, human-resolution, and directive polling. Do not grep for who else is touching a symbol or skip coordination because a change looks small. Skip only genuinely solo sessions or docs-only edits with no coordination value."

Fleet First

The coordination layer for **fleets of coding agents** working the same repo at the same time. It stops agents from silently clobbering each other's edits, and turns unsafe overlaps into a clear decision instead of a merge-time surprise.

The Iron Law

IN A FLEET → FLEET TOOLS BEFORE EDITS. NO EXCEPTIONS.
  1. fleet_publish_intent   (declare what you'll touch; get blast radius + conflicts)
  2. edit                   (your normal edit loop)
  3. fleet_record_episode   (classify A/B/C; if C, the loop resolves it)

A typed intent serializes to ~20 tokens; a prose "I'm going to change X" averages 200+. A 10-agent fleet × 100 edits = tens of thousands of tokens saved per fleet-turn — and zero silent overwrites — when the protocol is followed.

A fleet = agents on ONE branch (always pass it)

**Coordination is branch-scoped.** Two agents only coordinate when they're on the **same `(repo, branch)`**. The branch name is the fleet identifier: a *session branch* is how a group of agents opts into one coordinating fleet.

• Working a session branch (`session/auth-revamp`)? Pass `branch` on **every**

fleet call. Your fleet coordinates together and stays isolated from agents on other branches.

• Omit `branch` only for the shared default pool (single, unnamed fleet).
• Agents on **different** branches never conflict — git already isolates them, and

whether branches merge isn't guaranteed, so the fleet never reasons across them.

{ "repo_id": "myrepo", "branch": "session/auth-revamp",
  "agent_id": "agent-a", "touched": ["auth::verify_token"],
  "intent": {"refactor": {"pattern": "change_signature"}},
  "assignment": "widen verify_token signature for pagination" }

Always include **`assignment`** — your natural-language task. When a conflict happens, that's what the judge (another agent) or a human reads to reconcile.

Check the fleet first (once per session and after idle)

Set a stable identity before any fleet call:

MEMTRACE_AGENT_ID=<your-agent-id>   # required in fleet / hosted environments

fleet_branch_context({repo_id, branch, agent_id})
  → you, peers[], pending_escalations, recent_peer_episodes, graph_revision
fleet_status()        → live_intents, active_agents, pending_escalations, mediator_mode

Call **`fleet_branch_context`** at session start and after idle periods so you do not confuse peer WIP with settled graph truth. If fleet tools respond, coordination is active — follow this skill for every edit. An empty peer list is **not** permission to skip: it just means you're the first agent in this window.

The protocol, step by step

1. **Before editing** — `fleet_preflight({repo_id, branch, agent_id, touched, intent})` (read-only) or go straight to `fleet_publish_intent(...)`. You get the blast radius, any overlapping live intents on your branch, and a `coordination` block that may already suggest who owns a contested symbol. 2. **Edit** — your normal loop. 3. **After editing** — `fleet_record_episode({repo_id, branch, agent_id, touched, intent})`. It returns a `conflict_class`:

• **A — proceed.** Additive, order-independent. Nothing to do.
• **B — re-read, then proceed.** You overlap non-destructively; re-read the

shared symbols so you build on current state.

• **C — a decision is needed.** A destructive change overlaps another agent's

work. This does **not** auto-resolve — see below.

Class C: the decision loop (read this)

A Class C means two edit paths can't both land safely. `fleet_record_episode` returns an `escalation_id` and a `mediation_request` (when mediation is enabled). What happens next depends on who judges:

• **You may be asked to judge.** The `mediation_request` carries **every agent's

assignment** — including the other side's. Read them and submit a verdict with `fleet_submit_verdict({escalation_id, agent_id, verdict})`, where `verdict` is one of:

• `{"kind":"reconcile","merge_plan":"…"}` — the changes combine; here's how.
• `{"kind":"recommend","winner":"<agent_id>","rationale":"…","confidence":0.0-1.0}` —

one path should continue.

• `{"kind":"defer_to_human","question":"…"}` — a real product call; ask a human.
• **A human may decide** in the Fleet dashboard. Either way the outcome flows back

to you.

• **Close YOUR loop**: poll `fleet_get_escalation({escalation_id, agent_id})` until

`your_directive` is no longer `wait`:

• `proceed` — you were chosen; continue.
• `defer` — another path won; stand down and rebase your work onto it.
• `review` — read the free-text `resolution`.

The daemon is a deterministic referee: it never auto-applies a destructive *removal* (delete/move) without a human, and only auto-applies when it's safe (a clear machine case, or independent agent consensus). So the judge being wrong degrades to "a human reviews a suggestion," never a silent bad merge.

Routing — what do you need?

| You're about to… | Do this | |---|---| | Start any edit in a fleet | `fleet_publish_intent` (declare it) — never skip | | Check before declaring | `fleet_preflight` (read-only "is the coast clear?") | | Finish an edit | `fleet_record_episode` (get A/B/C) | | Got a Class C as the judge | `f