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	fleet_submit_verdict (reconcile/recommend/defer)
Blocked on a Class C	poll fleet_get_escalation until your_directive ≠ wait
A human chose the outcome	fleet_resolve_escalation (record the decision)
See the needs-human queue	fleet_list_escalations
See who's in the fleet	fleet_status (active_agents, pending decisions)
Inspect a symbol's coordination state	fleet_get_node_state

Parameter notes

• Pass intent as JSON (externally-tagged, snake_case): {"refactor":{"pattern":"rename_symbol"}}, {"bug_fix":{"defect":"logic_error"}}. Destructive kinds: refactor/change_signature, refactor/move_symbol, cleanup/dead_code — these are what trigger Class C over shared symbols.
• touched is a list of qualified symbol identities (e.g. "module::Symbol").
• Always include branch (your session branch) and assignment (your task).

Full parameter spec for every Memtrace tool: references/mcp-parameters.md (bundled at the memtrace-skills plugin root).

When to skip

Skip the protocol only for a genuinely solo session (you're the only agent and no one else shares your branch) or pure docs-only edits where coordination has zero value. Everything else in a fleet goes through the protocol.

Output

Key return shapes (fields documented above):

// fleet_record_episode →
{ "conflict_class": "C", "escalation_id": "…", "mediation_request": { /* every agent's assignment */ } }
// fleet_get_escalation →
{ "your_directive": "wait | proceed | defer | review", "resolution": "free text (read on review)" }
// fleet_status →
{ "live_intents": [ /* … */ ], "active_agents": [ /* … */ ], "pending_escalations": [ /* … */ ], "mediator_mode": "…" }