Adaptive Swarm
Adaptive Swarm is an execution mode for a Project. Instead of one agent working a task list, a PM agent assembles a team, writes a plan, and coordinates worker agents that build in parallel — each in its own git worktree — while QA and E2E agents review the integrated result. You stay in control through approval gates and can steer at any point.
When to use it
Section titled “When to use it”Reach for a swarm when a goal is big enough to decompose into interdependent pieces that benefit from parallel work and independent review — a multi-file feature, a migration, a build-then-test-then-harden effort. For a single focused task, a normal Project or a Loop is simpler.
The kickoff wizard
Section titled “The kickoff wizard”Picking Adaptive Swarm on the New Project screen opens a five-step wizard:
- Define — name the project, state the goal, choose the execution sandbox and repo mode (below).
- Team — pick the PM (required) and optional workers, set the QA/E2E team sizes, and configure per-gate overrides (below).
- Brainstorm — shape the idea with the PM and team in a live chat. The plan is built from this conversation.
- Plan — the PM generates a plan (phases → tasks → owners). An audit pass surfaces any missed design questions for you to answer, folding the answers back in.
- Launch — review the run summary and sign off on the plan. Approving it is the PLAN gate; the run advances to build and opens the execution console.
The run lifecycle
Section titled “The run lifecycle”A run moves through phases: assembly → planning → build → QA → E2E → sign-off → done. Build fans work out to worker agents (respecting task dependencies), QA and E2E review the integrated whole, and findings route back to the owning tasks for a fix-and-re-audit loop until they’re clean or you resolve them.
If QA gets stuck, the run raises a stuck-QA escalation with three choices — accept as is, change approach, or drop the task. On change approach you can attach free-text guidance that steers the redo.
Involvement levels and gates
Section titled “Involvement levels and gates”Involvement sets how much the swarm checks in with you, from Strict (approve
almost everything) to Full and Autonomous (proceed on its own, notifying you
of the important moments). Each checkpoint is a gate: require (you decide),
notify (proceeds after a short veto window), or skip.
You can override individual gates beyond the involvement default in the Team step —
for example, keep the plan gate on require even at high autonomy, or skip the
team-assembly gate. Overrides are set per swarm and apply to its runs.
Contract agents
Section titled “Contract agents”When the team lacks an expertise a task needs, the PM can mint a contract specialist on the fly — a lightweight agent with its own persona and skills, no workspace. It’s assigned to the relevant tasks for the rest of the run, and you can promote a useful one to a durable, workspace-backed agent afterward.
Git cadence
Section titled “Git cadence”Repo mode controls how work lands:
- none — the deliverable stays in the workspace; no git.
- local_git — each worker builds in its own worktree off an integration branch; the PM squash-merges completed work, bounces merge conflicts back to the owner, and the final result lands on your base branch after sign-off. In-app diff review is available.
- github_pr — the same cadence, but pushed to a private GitHub repo as real PRs.
Budget rails and cost
Section titled “Budget rails and cost”A run stops safely when it hits a rail — max iterations, tokens, duration, or consecutive errors — pausing (resumable) rather than failing where it makes sense. The execution console’s HUD shows live token / agent / duration meters, a burn rate, and a cost-by-phase breakdown so you can see where the budget went (planning vs build vs QA vs E2E).
Resuming and cleanup
Section titled “Resuming and cleanup”If the daemon restarts mid-run, the swarm reconciles interrupted runs on startup: runs with a valid checkpoint are paused so you can resume from where they left off; runs that can’t resume cleanly (no checkpoint, or their worktrees are gone) are failed. Stale per-run worktrees from completed or long-finished runs are garbage- collected automatically.
Related
Section titled “Related”- Projects & Tasks — the container a swarm runs inside.
- Use Sub-Agents — the primitive workers are built on.
- Run a Loop — single-agent goal-seeking, the swarm’s simpler cousin.
