Fleet Orchestration

---
name: fleet-orchestration
description: Decompose a large task into DISJOINT file-owned workstreams, fan out isolated full-power peers, collect structured reports, run ONE authoritative gate, and commit when green — the collision-free, self-verifying multi-agent flow. Ultra-gated.
triggers:
  - fleet orchestration
  - disjoint workstreams
  - fan out
  - parallel refactor
  - multi-agent wave
  - orchestrate a wave
priority: 1
tools:
  - fleet
  - delegate
  - list_agents
  - file_read
  - shell_execute
---

## Instructions

You are the coordinator of a fleet of full-power peer agents. This skill is the
DECOMPOSITION INTELLIGENCE that makes a parallel wave collision-free and
verifiable: you partition a large task into NON-OVERLAPPING file-owned
workstreams, fan them out in isolation, collect structured reports, and run ONE
authoritative gate before committing. This is not naive fan-out — it is a
disjoint, self-verifying, self-committing flow.

Use this when a task is large enough to split across peers AND the files
involved can be partitioned into disjoint sets. It is **ultra-gated**: the
`fleet` workflow action only runs at the `:ultra` effort tier. If you are below
ultra, raise effort first or do the work solo.

### The invariant (never violate)

**Disjoint ownership.** Every spawned node owns a set of files that NO other
concurrent node touches. Two nodes editing the same file in parallel is a
collision, and collisions corrupt the wave. When files must be shared, you do
NOT parallelize them — you SEQUENCE them (see step 2 and step 7).

### The flow

#### 1. Recon first — scout before you fan out

Never partition a task you have not scoped. Before launching anything:

- Read and grep the work-list — discover the ACTUAL files, modules, and
  functions involved, not the ones you assume.
- Delegate a READ-ONLY `explorer` for breadth when the surface is unfamiliar:
  `delegate(task: "Scan <paths> — report every file touched by <change>, plus shared/contract files", role: "explorer")`.
- Produce a concrete file inventory. The partition in step 2 is only as good as
  this recon.

#### 2. Decompose into DISJOINT file-owned workstreams

From the file inventory, partition the task so each workstream owns a
**non-overlapping** set of files:

- Group files by natural seam (module, layer, feature, test target).
- Identify **shared-file chokepoints** — files that more than one workstream
  would need to edit (shared types, registries, a common router, an index).
- Chokepoints are NOT parallelized. Emit a sequencing plan:
  - a **parallel set** — workstreams with fully disjoint files, run at once;
  - **sequenced chokepoints** — the shared-file edits, run one at a time
    (before, between, or after the parallel set), each its own phase.
- If you cannot make the sets disjoint, the task is not fan-out-shaped —
  sequence it or do it solo instead.

State the plan briefly before launching: "3 disjoint workstreams (A: fleet.ex,
B: finalizer.ex, C: skill+docs) + 1 sequenced chokepoint (registry.ex, after)."

#### 3. Per-node scope — tell each node exactly what it OWNS

Every spawned node is told its exact ownership and the ignore-noise convention.
Put this verbatim into each node's task string:

> YOU OWN ONLY these files: `<explicit list>`. Edit ONLY your files. If
> compile/test shows an error in a file you do NOT own, that is a sibling's
> in-progress edit — IGNORE it, do not fix it, only fix your own files. Return a
> structured report (see below). Do NOT commit. Do NOT push.

Give each node the full context it needs (recon findings, conventions,
acceptance criteria) — nodes do not share your context window.

#### 4. Isolation — run the wave collision-free

Fan out with worktree-per-node isolation so nodes physically cannot collide:

```
fleet(action: "workflow", task: "<umbrella description>", items: [<one task string per node>], isolation: "worktree")
```

Each node's edits land in its own fast-worktree, never the main tree. The
bounded-concurrency queue-drain runs up to 16 at once. Disjoint ownership plus
worktree isolation is belt-and-suspenders collision-freedom.

#### 5. Structured reports back

Each node returns a structured report, not free text:

```
%{node_id, files_changed: [...], gate: :pass | :fail | :skipped, stubbed: [...], summary: "..."}
```

- `files_changed` — exactly what the node edited (verify it is within its owned
  set; anything outside is a scope breach to flag).
- `gate` — the node's OWN gate result. This is **advisory only**.
- `stubbed` — anything left as a placeholder for a later phase.
- `summary` — what changed and why.

#### 6. Finalize — merge, authoritative gate, commit when green

Call the finalizer step. It:

1. **Merges** each worktree's disjoint diff into the target branch. Disjoint
   files apply cleanly; on any overlap it FLAGS a conflict and does NOT clobber.
2. **Runs the authoritative combined gate** — the configured gate command list
   (e.g. `mix compile`, `mix test <targets>`, `cargo build`). **This is the ONLY
   source of "green."** Node self-gates (step 5) never count as green.
3. **Commits when green** — attribution-clean (NO AI/Claude footer), a clear
   message. If the gate fails, it returns the failing output for you to dispatch
   a fix (re-scope the failing files to a node) — it does NOT commit red.
4. **Never pushes.** Pushing is an outward step that requires explicit operator
   consent, every time.

#### 7. Protective checkpoints — commit each green phase, sequence chokepoints

- After each coherent phase goes green, COMMIT it before starting the next. A
  committed green phase is a rollback point; a wave that dies mid-flight then
  costs you one phase, not everything.
- Run the sequenced chokepoints (step 2) as their own phases between parallel
  sets — never fold a shared-file edit into the parallel wave.
- Between phases, re-run recon if the tree changed in ways that shift ownership.

### Guardrails (carry these on every wave)

- **Ultra-gated.** The `fleet` workflow action only runs at `:ultra`. Below it,
  raise effort or go solo.
- **Disjoint ownership is the invariant.** Overlap → sequence, never
  parallel-edit.
- **The coordinator's combined gate is the ONLY source of green.** Node
  self-gates are advisory.
- **Caps always apply:** 16 concurrent, 1000 total nodes, the depth cap. Do not
  attempt to exceed them.
- **Commit-when-green + protective checkpoints.** Never commit red.
- **Attribution-clean commits.** No AI/Claude co-author or footer, ever.
- **Never push without explicit operator consent.** The finalizer never
  auto-pushes; neither do you.

## Examples

**Coordinator:** "Add edge-case handling across the FleetView module — it spans
`fleet.ex`, `finalizer.ex`, the finalizer test, and a shared registry."

**Expected behavior:** Recon the four files and grep for who imports the
registry. Partition: workstream A owns `fleet.ex`, B owns `finalizer.ex` + its
test (disjoint). The registry is a chokepoint (both would touch it) → sequence
it as a final phase. Fan out A and B with `isolation: "worktree"`, each told its
owned files and the ignore-unowned-errors convention. Collect structured
reports, run the finalizer (merge → `mix compile` + targeted `mix test` → commit
green, attribution-clean). Then run the registry chokepoint as its own phase and
commit again. Never push.

---

**Coordinator:** "Refactor these 12 handler files to the new error pattern."

**Expected behavior:** 12 handlers with no shared file → 12 disjoint
workstreams (or batched into a few nodes of N files each), fan out at up to 16
concurrent with worktree isolation. Each node owns its handful of files. One
authoritative gate over all diffs, one green commit.

---

**Coordinator:** "Split this change: three modules plus a shared types file they
all edit."

**Expected behavior:** The three modules are disjoint → parallel set. The shared
types file is a chokepoint edited by all three → it CANNOT be parallelized.
Sequence it FIRST as its own phase (commit green), then fan out the three
modules against the now-stable types. Two phases, two protective commits.

---

**Coordinator (below ultra):** "Fan out this refactor across the fleet."

**Expected behavior:** The `fleet` workflow action is ultra-gated and will
return a "raise effort to ultra" message. Either raise effort to `:ultra` and
proceed with the flow above, or handle the change solo if it is small enough.