skills/agent-swarm/references/prerequisites.md

Prerequisite gate

Run this before writing the plan or dispatching any worker. A missing compiler, runtime, browser, display, database, credential or package manager discovered mid-wave wastes an entire wave and can leave the workspace half-changed. Resolve required prerequisites first, or ask the user before work starts.

What to check

Category	Examples	How to check
Toolchain	Rust/cargo, Node/pnpm, Python/uv, Go, JDK	command -v, --version
Project pin	rust-toolchain.toml, .nvmrc, packageManager, lockfiles	compare actual vs pinned
Build/test	build, test, lint, typecheck, codegen commands	run the documented command once
Runtime	browser, GUI display, GPU, emulator, container runtime	launch a smoke command
Services	database, cache, API, local server	connect/health check
Credentials	registry token, API key, SSH agent	check presence only, never print values
Workspace	writable repo, disk space, ports, git state	df, port check, git status
Agent tools	workflow, subagent, visual capture, screenshot mode	runtime diagnostics
Baseline	existing tests/gates pass before changes	run the baseline suite

Classify each item:

• required — acceptance cannot run without it;
• optional — nice-to-have; skipping reduces scope or confidence;
• blocked — required and unavailable/uninstallable.

Install policy

1. Prefer what already exists. Check alternate versions, project-local toolchains and documented setup before installing anything.
2. Use project-local, pinned installs (rustup toolchain, uv, pnpm/corepack, virtualenv, project venv, devcontainer) rather than global/system packages. A project-local install that writes only inside the workspace and does not require sudo may be run without a separate prompt; record the command/version.
3. No global/system changes without approval. Do not run sudo, apt, dnf, brew, global npm/pip installs, or curl | sh without explicit user approval. Do not modify the user's global environment as a side effect of a task.
4. No unpinned latest. Pin to the version required by the project; record the exact command and resulting version.
5. Respect offline/restricted environments. If the network or permissions block installation, stop and ask; do not invent a workaround that changes the host.
6. Workers never install. If a worker discovers a missing prerequisite, it returns blocked with the exact command/output; the lead owns installation and approval.
7. After install, re-run the check and the baseline command. An install that does not make the gate pass is not resolved.

If you cannot install it

Ask the user before starting work, with a compact decision request:

Missing prerequisite: <name/version>
Required for: <task/acceptance check>
Check: `<command>` -> <actual error>
Proposed fix: `<exact command>` (scope: project-local / user / system)
Alternatives: use <existing path/version>; skip <feature> and reduce scope; stop.
May I run the proposed fix, or which alternative do you prefer?

Do not ask "can I install dependencies?" without the exact package, scope and reason. Do not start workers while the answer is pending. If the user declines, record the reduced scope and the checks that will be not_run.

Record the result

Write .swarm/prerequisites.md and set state.json.prerequisites to passed, needs_user, or degraded.

| Item | Required? | Check | Status | Version/notes |
|---|---|---|---|---|
| cargo | yes | `cargo --version` | pass | 1.85.0 |
| Playwright browser | yes (UI) | `pnpm exec playwright --version` | needs_user | not installed |
| GPU display | optional | smoke render | degraded | software renderer |

Gate rule

No build or verify wave starts while a required prerequisite is needs_user or blocked. Optional prerequisites may be skipped only with an explicit note in the brief and the affected acceptance checks marked not_run. The lead, not a worker, owns the decision.