83 lines
4.0 KiB
Markdown
83 lines
4.0 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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`.
|
|
|
|
```markdown
|
|
| 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.
|