Docs / Reference
route
Preview the deterministic route BrigadeStack derives for a task before it runs.
Use this to preview how BrigadeStack would split a task into stages before you run it.
route
brigadestack route "<task>" shows the route BrigadeStack would take for a task without running anything. Before a brigadestack run dispatches workers, a deterministic engine reads the task, derives a set of signals, and composes the stages those signals require into dependency-ordered parallel waves. brigadestack route prints that composition so you can see what the run will cover before you spend any tokens.
The derivation is a pure function. route_catalog.derive_signals maps the task text (and, at run time, the git-changed paths) to signals, and a pure-function router (brigade/router.py, algorithm adapted from alp-river, MIT) composes the required stages into waves with while/until holds. Same task in, same route out, no model call.
brigadestack route "add oauth login to the dashboard"
brigadestack route "rewrite the QUICKSTART" --json
brigadestack route "make the change" --changed-path src/auth/session.py
brigadestack route "ship the release" --approve-ship
brigadestack route "review the migration" --template
brigadestack route "<task>" prints four things:
- Signals derived from the task.
- Stages, each shown with the signal that pulled it in.
- Waves: the stages grouped into dependency-ordered parallel waves. Stages in the same wave have no dependency between them and can run at once. A later wave depends on an earlier one.
- Held stages: stages behind a
while/untilhold that will not route until the hold is released.
Flags:
--changed-path <path>seeds the route with a git-changed path (segment-matched) so you can preview how touched files steer the route.--template <hint>supplies the optional route-template hint thatbrigadestack run --route-template <hint>also reads.--approve-shipreleases a held ship stage in the preview, the same releasebrigadestack run --approve-shipperforms.--jsonemits the full structure:signals,approvals,route,waves, andheld, plustriggered_by(the live signal that pulled each stage in) andoverrides.
Signals
Each task gets exactly one path signal (code, docs, or system) that decides the shape of the route. Then up to eight lens signals and a derived needs-tests signal pull review or verification stages onto that path. The lens signals come from word-boundary keyword matches on the task text, and --changed-path can add ui-touched, migration, and auth-surface from file paths.
| Signal | What it marks |
|---|---|
bug | a defect fix, which pulls an investigate stage first |
auth-surface | authentication, secrets, or permissions, so it earns tests and a security review |
ui-touched | UI work such as a panel, dashboard, sidebar, widget, view, or tooltip, or a .tsx, .vue, .css path, so it pulls the UX review |
perf-surface | performance work such as latency, caching, or a benchmark, so it pulls the performance review |
migration | a migration or schema change, which earns tests and a migration review |
destructive-op | a destructive step such as rm -rf, a force push, or a table drop, which holds system execution until approved |
ship-requested | the task asks to ship or release, which stages a ship step behind a hold |
significant-build | a refactor, rewrite, or new feature, which adds a plan stage and earns tests |
needs-tests | derived, not matched: set for bug, auth-surface, migration, and significant-build code tasks, and pulls test-first and test-gap stages |
On a docs path only ship-requested and destructive-op are derived from the text, so “fix typo in the README and open a PR” keeps the ship hold.
A forced signal still pulls its dependents. Forcing +auth-surface also pulls in the tests and the security review that depend on it, so you get the full stage set.
Steering the route from run
brigadestack run derives the same route by default and carries it into the plan prompt. When the heuristic is wrong on a single task, --route-signal is the middle ground short of turning routing off:
brigadestack run "harden the token check" --route-signal +auth-surface
brigadestack run "note the release in the changelog" --route-signal ~ship-requested
--route-signal +<signal>force-adds a derived signal, and~<signal>suppresses one.--route-signalrefuses to add or suppress a path signal (code,docs, orsystem). The path is a derive-time decision, and stripping it collapses the route to a pathless remnant. Use it for lens and ship signals only.
Other run-time route controls:
brigadestack run --no-routeopts out of routing entirely for that run.brigadestack run --approve-shipreleases a held ship stage so it routes.brigadestack run --wait[=SECONDS]waits for an active per-target run lock with a finite timeout. Without the flag, a lock conflict stays fail-fast.
How the route reaches the plan
The derived route is carried into the plan prompt, and the plan tags each worker assignment with a covers tag naming the stage it handles. A plan that misses a required stage gets one corrective retry. If a gap remains, it is recorded in plan-attempts.json and the run does not fail. A covers tag naming a stage that is not in the route is surfaced as unknown_covers instead of being silently ignored.
The route lands in run.json telemetry, so a completed run records the signals, stages, waves, and holds it was planned against alongside the rest of the run metadata.
See run for the surrounding run flags, artifacts, and run locking.