---
name: swarm-orchestrate
description: Optional autonomy control plane — set up (which platforms you have + a pace: budget/balanced/fast), launch, monitor, recover, or stop local CLI-agent workers (Claude Code and Codex verified; Gemini, OpenCode, Droid, Cursor, Copilot best-effort; any other agent via a launch-command template) through SwarmVault's durable supervisor, with budget- and model-fit-aware task assignment, a cross-platform observability board (usage/limits, tokens, per-agent progress), safe-state context compaction, and usage-limit continuation so long projects survive quota resets. Use when the user asks to orchestrate agents, enable/disable a supervisor, dispatch work across platforms, assign work by usage limits or model strength, view or monitor a live board of all agents, add a launch adapter, compact/continue past a usage limit, or recover idle work.
---

# 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:

```bash
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, `checkpoint`s 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](https://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:

  ```bash
  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:**

   ```bash
   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.*