SuperAPI AI Directory

fleet-roles

General & other

View repository

Updated 10-16 08:00

About this skill

Roles and models

The descending-model rule

The orchestrator reasons, mid-tier executes, cheap models verify mechanically. Every spawned agent names its model.

Not naming a model is the failure mode, not choosing the wrong one. An unnamed dispatch inherits whatever the caller happens to be running, so a fleet that never names models drifts to a single tier and pays either in quality or in cost, silently.

Tier Model class Work
orchestrator highest reasoning outcomes, escalations, replacement, the run's own judgement
judgement high ranking, review verdicts, release readiness, proposals
mechanical mid merges, conflicts, routing, coverage sweeps
lane mid (high for the hardest repos) implementation in one repository
worker mid one bounded edit, dispatched and discarded
verifier cheap re-run a stated command, check one fact, confirm a count

Configure the actual model per tier in fleet.config.json → models. model: accepts a tier alias, a full model id, or inherit.

Right-size every dispatch, and never fork. A verifier that needs to reason is the wrong verifier; a lane that spends its own turns on bounded edits is not delegating.

Session or subagent?

This decides more than the model does.

A role that must heartbeat, be woken by a message, or survive between turns must be its own session. Subagents cannot do any of those, and a foreground subagent call blocks the caller's turn entirely — it cannot heartbeat and cannot read messages until the call returns. One lane went 60+ minutes silent that way, and the monitor read it as hung.

Role Normally runs as
orchestrator, all management roles, all repo lanes its own session
worker, verifier a subagent, spawned in the background, unnamed

The agent files this plugin ships under agents/ serve both uses: dispatch the worker and verifier directly, and use a management or lane agent file as the brief you paste into the session that takes that role. Each such file says so in its own body.

If you must block on a foreground call, heartbeat first: waiting | <task> | foreground worker, expect silence.

Tier 0 — orchestrator

Owns outcomes, promotion decisions, escalations to the human, lane replacement, and the run directory. Receives digests from the router, not a stream, and messages nobody directly except the router.

Tier 1 — management

Run only the roles your fleet's size justifies. A three-lane fleet needs a planner and a merge gate; the rest is overhead.

Role Owns Tier Enable when
planner the ranked backlog, assignments, the numbered amendment log judgement always
reviewer APPROVE/BLOCK verdicts on lane PRs, scoped to a head SHA judgement always
gitops the merge gate, branch↔PR coverage, runner load mechanical always
conflicts base re-absorption, conflict resolution, merge forecasts mechanical more than ~4 lanes
dispatch fan-out, acks, registry upkeep, digests to tier 0 mechanical more than ~5 sessions
release per-product release board: blocker, proof, exact next action judgement anything ships
brainstorm evidence-backed proposals, planner-gated into issues judgement there is slack

Two roles are worth adding early rather than when it hurts:

  • dispatch, because without it every session messages tier 0 and tier 0 becomes the bottleneck it was created to avoid. It was added mid-run in the source fleet and immediately became the required relay.
  • release, because "what blocks the next release, and the exact next action" is nobody's job by default, and the human ends up doing it.

Scale reviewers before anything else. Reviewer attention is the scarce resource — not reviewer assignment. Two concurrent reviewers splitting the repository set, with in-flight items staying with whoever already holds them, is the shape that worked. Mechanical changes go to a peer lane instead; see the protocol's review routing.

Tier 2 — repo lanes

One session per repository, exclusive scope, from lanes[]. A lane:

  • reads its repository's own instructions before the first edit,
  • works in a per-task worktree,
  • pushes and opens the PR in one action,
  • announces the PR to the reviewer with the exact commands run and the CI state at the announced head,
  • removes its worktree only after the merge gate confirms,
  • loops until the planner says the queue is empty, then writes its report and goes to standby.

Second lane on one repository: allowed when the queue justifies it, split by file space, named and confirmed by the planner before the second lane's first edit. Task claiming locks claims, not files.

A structurally starving lane goes to standby; it is never repurposed across repositories mid-task. Repurposing a finished session to another role is fine and should be recorded explicitly — a census that counts registry rows will otherwise count one session twice.

Tier 3 — workers and verifiers

Unnamed subagents, spawned in the background, discarded after one task.

  • worker — one bounded edit with a stated acceptance test.
  • verifier — re-runs one stated command and reports the literal result.

A worker's "done" is ASSERTED. It becomes DELIVERED when a verifier re-runs the stated command, or a link (PR, SHA, check state) confirms it.

Where the velocity comes from

Discipline that costs turns slows a fleet down. The source run spent a real fraction of its day on bookkeeping and on waiting for work that was already finished. Each item below removes a measured loss, and each is a default in fleet.config.json or a command in scripts/fleet.mjs — not a rule to remember.

Loss in the source run Mechanism that removes it
566 + 68 + ~120 minutes of lanes idle on work that was already done fleet blockers <lane> every heartbeat while waiting; exit 1 = move
one reviewer, eight PRs queued, hung at hour 12; second reviewer added at hour 15 review.parallelReviewers — two from the start above four lanes, splitting the repo set
management reviewers spent on docs, templates and link fixes review.peerRoutableGlobs — a PR whose files all match goes to a peer lane that has run the same gate
5 of 15 approvals stale against a moved head, none flagged fleet verdicts <repo> at the start of every reviewer cycle
merge gate: 5–6 hand commands per merge, one of them skipped once fleet checks in the same message as the merge; exit 0 is the only state you merge from
a merge invalidated an unrelated PR's green and nobody could know fleet unblocks as part of the merge — both audiences
every session hand-writing registry rows, heartbeats, digests fleet register, fleet hb, fleet digest
an evening on a CI cap counting runs fleet queue-depth counts jobs
4 of ~40 assigned items already fixed before a worktree was cut verify the symptom before the worktree — rule 9, unchanged; it is a judgement, not a command
many PRs to the same base merged one at a time, each re-absorbing batch-integration drain: one integration branch absorbs the queue, re-absorbs the base once, merges once with a merge commit — squash orphans the heads

Two of these deserve a sentence more than the table gives them.

Two reviewers from the start. Reviewer attention is the fleet's scarce resource, not reviewer assignment. Split the repository set between two concurrent reviewers, with in-flight items staying with whoever already holds them. Adding the second reviewer late, under a queue, is how the source run did it; adding it first costs one session and removes the bottleneck the whole management tier existed to avoid.

Peer review for mechanical changes. Docs, templates, issue forms, link fixes — anything whose correctness a gate already decided — goes to a lane that has run that gate, not to a management reviewer. The peer is bound by every rule the reviewer is bound by: verdict as a PR comment, scoped to the head SHA, naming the falsifier and the set. Never route a lane to its own branch. This distributes the scarce resource without lowering the bar, and review.peerRoutableGlobs is what makes it a routing rule rather than a judgement call each time.

The RACI

Write one per run. The activities that need an explicit owner, because they are the ones that go unowned:

Activity R A
Backlog ranking and assignment planner orchestrator
Implementation in one repo that lane that lane
Second lane's file split that lane planner confirms before first edit
Verification of a worker's claim verifier the lane
Review verdict reviewer or peer lane the reviewer
Merge into the integration branch gitops orchestrator
Conflict resolution / re-absorb conflicts gitops
Branch↔PR coverage, worktree hygiene gitops + lanes gitops
Heartbeat monitoring and replacement orchestrator orchestrator
Release readiness per product release orchestrator
Promotions, releases, production, spend, trust chain the human the human
Escalation routing orchestrator orchestrator

The last two rows are the ones fleets get wrong. Everything in founderClass reaches the human as a ready-to-merge PR with proofs, never as a question that parks the work.