/swarm-orchestrate

name: swarm-orchestrate
description: Optional autonomy control plane — configure, plan, launch, monitor, recover, or stop local CLI-agent workers through SwarmVault's durable supervisor. Use for fit/budget-aware platform + model + reasoning-effort routing; a consistent pre-start/live/boundary/on-demand board with ticket drill-down; TOLD/MEASURED/EST usage and run accounting; bounded event-driven waits; stale-worker and possible-quota recovery; safe context compaction; launch adapters; and consent-gated continuation across provider resets.

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, model, and reasoning effort 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 — two design questions, then the numbers only they can see

1. Confirm the project is registered and has dependency-ready tickets. 2. Ask the two **design** questions:

• **"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 concurrency ceiling, 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. **Do ask for the usage numbers — you cannot read them.** Per platform: *which plan are you on · what limits does it show (per session/day, per week, both) · when do they reset · are any other sessions running I can't see · may I schedule a continuation automatically if a limit is about to run out?* Look up per-model costs yourself first; ask only if the lookup fails. See **Usage — you are blind without the user** below; the full interview and the per-platform notes are in `references/usage-limits.md`. 5. 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
# --isolation worktree   each worker gets its own git worktree + branch (see below)
# --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.

Read what `setup` prints back. Two of its lines are about this machine rather than your choices, and both change what actually happens:

• **`host`** — how many concurrent workers this machine holds. A worker is not just an agent

process; it also runs the ticket's tests and build, which dominate. The ceiling is `(available memory − reserve) ÷ per-worker footprint`, measured from `/proc/meminfo` and any cgroup limit, and it **overrides the speed level's ceiling when it is lower**. Over-subscribing memory does not degrade gracefully: the host kills the guest, and every worker, the lead session and the supervisor die at once with nothing recorded. Tune the footprint with `supervisor configure --platform <p> --worker-memory-mb N` if your suite is heavier or lighter than the 1200 MB default (that number is an EST, and it says so).

• **`tree`** — whether workers share one working tree. See below.

Working-tree isolation

`shared` is the default because it is the only mode that works for every project shape — no git, whole-file generated artefacts, uncommittable local state. Above one worker it is genuinely unsafe, and the board says so rather than letting you find out:

• a half-written file from one ticket breaks an unrelated ticket's build;
• an in-flight edit (a widget arming a timer, a half-applied migration) can hang everybody's

tests;

• whole-file generated output means any commit touching it carries other tickets' changes;
• **no worker can run the suite to check its own work**, because the suite reflects six other

tickets' half-finished states.

`--isolation worktree` gives each worker its own `git worktree` on branch `swarmvault/tk-nnn`, and the lead merges the branches. Nothing in a worktree is ever deleted automatically — an uncommitted change there is somebody's unmerged work, and the board lists each worktree with its dirty count so it can be dealt with deliberately.

The speed levels — what each actually does

| level | hands a task to another agent when… | ceiling (per platform / total) | usage reserve | reconcile | |---|---|---|---|---| | `slow` | **only**