# Ultraswarm

> Orchestrate complex coding work through the ultraswarm v3 standalone runner.

- Skill: `fubak/ultraswarm-3` (Agent Skill)
- Install (CLI): `npx skillmds@latest add fubak/ultraswarm-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fubak/ultraswarm-3/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: fubak (https://skillmd.com/u/fubak)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/fubak/ultraswarm-3

---


# Ultraswarm v3 for agent

Use the repository's standalone runner as the only orchestration implementation. Do not recreate orchestration in the host, and do not implement delegated feature code directly.

Invocation: `ultraswarm`

## Runner

Resolve the checkout from `ULTRASWARM_HOME`, this skill's real path, or `~/projects/ultraswarm`. It must contain `bin/ultraswarm.mjs` and installed dependencies. Node >=22 is required.

## Workflow

1. Functionally verify the worker pool: `node <root>/bin/ultraswarm.mjs preflight`. This runs a cached smoke test (not just `--version`) and prints a roster marking each CLI INSTALLED and FUNCTIONAL. Drop any worker shown UNUSABLE — do not pin a task to it — and confirm at least the policy minimum of functional workers remain.
2. Inspect the target repository and prepare a validated JSON plan. Scope each task's `contract.allowed_paths` to include coupled test files, not just the obvious source — flipping a value often has a test blast radius.
3. Preview with `node <root>/bin/ultraswarm.mjs run --plan-file .ultraswarm-plan.json`. Show tasks, waves, routing explanations, policy findings, and gates. Obtain explicit plan approval.
4. Execute with `node <root>/bin/ultraswarm.mjs run --plan-file .ultraswarm-plan.json --approve-plan`, keeping the runner's stderr visible and relaying its live progress to the user as it streams: wave headers, per-agent dispatch lines, gate results, and the periodic active/idle heartbeat that shows every worker's state.
5. Report the run ID and present the runner's final human-readable summary — per-task outcome, which worker landed each task, and the tokens-saved estimate (the implementation work external CLIs did off your context). Integrated work remains off the checked-out branch.
6. Commit any working-tree changes first, then obtain separate merge approval and run `node <root>/bin/ultraswarm.mjs merge <run-id> --approve`.

Never translate approval from an earlier conversation into either runner approval flag.

When the functional pool is thin (e.g. only one CLI passes preflight), forced high-risk competition can be net-negative — a broken competitor can corrupt the good lane. Prefer disabling competition (policy) over racing unverified workers, and compensate by reviewing the full diff before merge.

## Operations

- `preflight [--smoke] [--json]`: functionally verify enabled CLIs (cached); `--smoke` forces a re-probe.
- `doctor` and `workers` (`--json` for machine output): policy, gates, CLI health, and capabilities.
- `explain-routing <task>`: worker ranking with fit and repository-local metrics.
- `status [run-id] [--json]`: durable run, task, and attempt state (human roster by default).
- `logs <run-id> [--after N] [--json]`: append-only events.
- `cancel <run-id>`: terminate worker process trees and mark cancelled.
- `resume <run-id>`: recover an awaiting-merge or stale-base run.
- `export <run-id>`: machine-readable provenance bundle.
- Per-task worktrees default to `<repo>/.ultraswarm/worktrees` so Node build gates resolve the repo's `node_modules`; override with `--worktree-root`.
- User-defined `aliases` in config appear in the roster alongside built-in CLIs; `preflight`/`doctor`/`workers` and `explain-routing` show them, and the decomposition roster routes to them by specialty (respecting any `maxTier` cap).

## Plan Contract

Each task requires `id`, `description`, `files`, `complexity_score`, `risk`, `dependencies`, and `prompt`. `cli` and `model_tier` are optional. Use `contract.commands`, `contract.assertions`, and `contract.allowed_paths` for executable acceptance criteria. High-risk tasks must compete unless policy says otherwise.

The runner owns worktrees, retries, worker supervision, routing, QA, integration, persistence, recovery, and merge. Treat its exit codes and durable state as authoritative.