Swarm orchestrate

swarm-orchestrate — optional local autonomy

Gate: this add-on is disabled by default. Do not enable it, configure write access, or start workers unless the user explicitly asks. Tickets and atomic claims remain the source of truth; signals and controls never override a healthy claim.

What this is for (read before configuring anything)

The goal is the right model on the right task, at the lowest token cost — parallelism is only one means to that end, and often not the right one. So orchestration has two separate decisions, and conflating them is the classic mistake:

1. Fit — always on, at every level. Which platform and which model each task deserves, from its kind (design / planning / coding / review / docs), its size, and each platform's remaining usage. A docs ticket never burns a flagship model; a design ticket never gets a cheap one. This is not something the user buys by going slower.
2. Acceleration — the speed level, and the only thing the user chooses. How eagerly work is handed to other agents instead of done in the current session.

Enable — ask two questions, nothing else

1. Confirm the project is registered and has dependency-ready tickets.
2. Ask exactly these two things:
   • "Which agentic platforms do you have?" — the tools installed on their machine: claude-code, codex (verified), gemini, opencode, droid, cursor, copilot, amp (best-effort), or any other agent CLI by name. Offer the list and an "other" option; a platform with no adapter still works as a cooperative worker, or gets a --launch-cmd template.
   • "How much acceleration is allowed?" — slow | standard | fast (below). Plus: may these workers edit code?
3. Never ask for a worker count, a usage/token limit, or a model name. Those are not the user's decisions: ceilings derive from the level, and the platform+model per task come from fit. Asking for a model produces exactly the wrong answer — one model cannot be right for both a large design task and a docs chore.
4. One command:

python3 /path/to/swarmvault.py supervisor setup --project MyApp \
  --platforms claude-code,codex --speed standard --start
# --read-only            workers may read/plan but never edit code
# --launch-cmd 'kiro=kiro run --dir {cwd} {prompt}'   wire an agent with no built-in adapter
# --self-platform codex  which platform THIS session is (else $SWARMVAULT_PLATFORM)

--project may be omitted when you are in the project directory. The supervisor runs locally, never uses a shell to launch workers, and logs every spawned process in the vault.

The speed levels — what each actually does

level	hands a task to another agent when…	ceiling (per platform / total)	usage reserve	reconcile
slow	only when another platform's model fits the task better than this session	1 / 1	35%	180s
standard	better fit, or there is genuinely independent work worth overlapping	2 / 4	15%	60s
fast	anything runnable — spread as wide as capacity allows, independent tickets batched	4 / 8	5%	30s

Every routing decision comes back marked execute: dispatch or execute: in-session:

• dispatch — launch/wake that platform's worker on that model.
• in-session — you take this ticket, now, on the model in the plan. This is not a fallback, it is the point of slow: quality routing without paying for a second context. orchestrate, board, and status.md all show these under "For this session".

So at slow a single session behaves like a well-run one-person team: it picks the right model for each task, switches to it, checkpoints and compacts when context grows (Self-management, below), and only calls in another agent when that agent is genuinely better at the task in front of it. At fast the same routing runs, but everything runnable goes out at once.

Two guarantees hold at every level: a platform below the level's usage reserve is parked unless nothing better is free (so no level eats a platform's last quota), and work over the ceiling is never dropped — one ticket is routed to the calling session and the rest are queued with a stated reason. A platform that is out of usage (not out of slots) defers instead, which is what feeds usage-limit continuation.

budget/balanced are accepted as older names for slow/standard. The per-platform configure action still exposes the raw knobs (--max-workers, --model, --models, --launch-cmd) — reach for it only when the user asks for that level of control.

Operate

• supervisor status --project MyApp — inspect enabled state, PID, workers, and status.
• orchestrate --project MyApp — one reconciliation without a daemon; prints the board afterwards (add --json for the raw state).
• signal --project MyApp --agent <id> --event heartbeat — worker health/progress.
• inbox --project MyApp --agent <id> — worker reads pending controls; acknowledge with --ack <id>.
• control --project MyApp --agent <id> --action stop|wake|retry — durable request; it is not a claim revocation or arbitrary process kill.
• supervisor stop --project MyApp — stop only the supervisor. disable prevents restart.

Smart assignment — size, budget & model fit (runs at every speed level)

• Report budgets so the scheduler can see them: signal --event budget --platform X --budget 0.7 [--used 38000 --limit 60000 --unit tokens] [--weekly 0.2 --weekly-reset <ISO>]. Unreported budget is treated as unknown, never assumed.
• Big tasks → the platform with the most remaining usage, preferring one whose configured model fits the task kind; small tasks / supervision → the least-budget platform, so the big-budget ones stay free for big work. Empty/quota platforms are skipped (→ continuation).
• Provision the model to the task kind (design / planning / coding / review / docs) and size — flagship models only where tier: top or a demanding kind needs them; cheap+fast for docs/boilerplate. Wire per-kind models with configure --models 'design=…,coding=…'.
• Keep the picks current from artificialanalysis.ai. Full method and the kind→strength table: references/model-routing.md.

This is level-independent. slow does not mean "use a weaker model" and fast does not mean "stop caring" — the same table decides the model either way. With one platform (or at slow, where most work stays here) it is you switching models per task rather than a worker being launched with one; see Self-management below.

Observability — one board for the whole swarm

board --project MyApp renders every agent, any platform, in the current CLI — so a Claude Code session sees the Codex (and other) workers as if local:

board --project MyApp            # snapshot; re-run to refresh
board --project MyApp --brief    # ONE line — use this for routine check-ins
board --project MyApp --verbose  # + each worker's dispatched prompt and recent log lines
board --project MyApp --watch 5  # live redraw every 5s in a real terminal

Monitoring must not cost what it monitors (FR-21). Three cheap paths, in order:

1. Every reconciliation rewrites the full board into 30 Plans/<project>/orchestration/status.md. Reading that file costs nothing and needs no agent turn — point the user at it for continuous watching, or run --watch in a spare terminal.
2. Every session's injected context already carries a one-line swarm summary, so a fresh session knows the state without asking.
3. When an agent does check in mid-work, use --brief (one line), not the full board. Reach for the full board at real decision points — a done, a blocked, a milestone, or when the user asks — not on a timer and never per heartbeat.

It shows: a ticket-progress bar; per-platform usage/limits (percent left, tokens used/limit, reset time, and a weekly-cap bar that flags "near weekly limit"); and one row per worker — platform · model · effort · task — latest progress, live (●) or idle (○) — plus a recent-changes feed built from workers' progress/done signals. Workers make it rich by signalling meaningfully: signal --event progress --reason "auth wired, tests green".

Agent roster & launch adapters

Any agent can be a cooperative worker — run the swarm-implement worker loop (claim → build → test → release) against the shared vault; claims are the referee. The supervisor can also launch workers headlessly, via a declarative adapter registry with three tiers:

• Verified — claude-code, codex. Spawned without a shell, exact flags known, ownership verified by the atomic claim. Both a write and a real read-only mode.

• Best-effort — gemini, opencode, droid, cursor, copilot. Sensible default invocations for fast-moving CLIs. Confirm the flags for your installed version, or override. These launch only with --allow-write: read-only headless launch is offered only where a genuine read/plan mode is known, so a read-only request can never accidentally start a writing agent. A wrong flag fails visibly (the exited process is logged as blocked), never silently.

• Any other agent (Windsurf, Kiro, Trae, Continue, Augment, Warp, …) — wire it with a command template you vouch for:

  supervisor configure --project MyApp --platform kiro --allow-write \
    --launch-cmd 'kiro run --dir {cwd} {prompt}'      # tokens: {cwd} {model} {prompt}
  

  With no adapter and no --launch-cmd, the supervisor records a manual-action request (start that agent yourself) rather than guessing a command.

Never assume one platform can command another (Claude Code cannot drive Codex, or vice versa); each adapter only declares what it can do.

Usage limits & continuation (FR-23)

Long projects outlast a single provider usage window. This works with or without the supervisor — even a solo agent should offer it.

1. Watch your own budget. As you approach the provider usage limit (~90%+), stop and raise it rather than dying mid-ticket.

2. Get consent, once, in-session. Ask: "You're near your usage limit. Continue automatically after it resets — until the whole project is finished, or until a point you name (e.g. end of M3)? Or stop here?" Do not schedule anything without an explicit yes.

3. Read the reset time. Use the real datetime the limit resets — never invent one. If it is unknown, say so and schedule nothing; leave a note instead.

4. Schedule the wake with your platform's native scheduler (Claude Code scheduled task / cron / equivalent) to fire the prompt continue project <P> at the reset time. The vault holds all state, so a cold session resumes from memory + tickets + flow-state alone.

5. Record it durably so every agent sees it:

   python3 /path/to/swarmvault.py plan-continue set --project MyApp \
     --resume-at 2026-07-25T09:00:00Z --scope until-finish \
     --platforms claude-code,codex --reason "usage ~92%"
   

   This surfaces in session context (⏳ Scheduled continuation) and as a queryable note, so a fresh session — on any platform — knows a continuation is pending and won't double-schedule.

6. Clean up when done. When the project (or the named --scope) is finished, delete the native scheduled task and clear the record: plan-continue clear --project MyApp. A resumed session that finds the work already complete clears it instead of looping.

For the supervisor path, a worker that hits a limit emits quota-wait --retry-at <ISO>; the supervisor persists the wait, avoids relaunch loops, and retries only at/after that time, and may choose another eligible provider only if the ticket policy permits.

Self-management — one session, orchestrated (this IS slow)

At slow — and any time a plan entry comes back execute: in-session — orchestration means managing yourself instead of spawning anyone:

1. Switch model to the task. Use the model in the plan entry (or the per-kind table in references/model-routing.md): strong model for design/planning/review or a tier: top ticket, cheap and fast for docs and boilerplate. On platforms where the user drives the model choice, say which model you want and why in one line rather than silently continuing on the wrong one.
2. Compact at safe boundaries rather than carrying a bloated context into the next ticket (below).
3. Only then consider a second agent — when the routing says another platform's model genuinely fits the next task better, dispatch that one ticket, not the whole queue.

This is the token-frugal path: one context, right-sized model per task, no re-establishing project state in a fresh agent for work you could finish here.

On a long task, when your context grows large and you are at a safe, resumable point (ticket done, phase boundary, a planning milestone recorded):

1. checkpoint --project MyApp --did "…" --next "…" — records a safe-state session note.
2. Make sure flow-state, tickets, and memory are current (they are your real state, J1).
3. Compact/clear your context (your platform's mechanism), then continue — the SessionStart context rebuilds from the vault.

Quality outranks token-saving. Never compact mid-reasoning, mid-edit, or when continuity is carrying the task — if the work needs the tokens, keep them and finish well. Compaction is for safe boundaries only.

Recovery and quota limits

Workers signal quota-wait --retry-at <ISO-8601> rather than retrying blindly. The supervisor records the state and status. A stopped worker is surfaced as blocked with its log path; inspect the ticket and log before reassigning. Reassignment always goes through the normal stale-claim protocol.

---

Influences: SwarmVault's existing claim, checkpoint, and adapter contracts.