Search BrigadeStack

Search BrigadeStack pages and docs.

BrigadeStack
Menu
Docs menu

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/until hold 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 that brigadestack run --route-template <hint> also reads.
  • --approve-ship releases a held ship stage in the preview, the same release brigadestack run --approve-ship performs.
  • --json emits the full structure: signals, approvals, route, waves, and held, plus triggered_by (the live signal that pulled each stage in) and overrides.

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.

SignalWhat it marks
buga defect fix, which pulls an investigate stage first
auth-surfaceauthentication, secrets, or permissions, so it earns tests and a security review
ui-touchedUI work such as a panel, dashboard, sidebar, widget, view, or tooltip, or a .tsx, .vue, .css path, so it pulls the UX review
perf-surfaceperformance work such as latency, caching, or a benchmark, so it pulls the performance review
migrationa migration or schema change, which earns tests and a migration review
destructive-opa destructive step such as rm -rf, a force push, or a table drop, which holds system execution until approved
ship-requestedthe task asks to ship or release, which stages a ship step behind a hold
significant-builda refactor, rewrite, or new feature, which adds a plan stage and earns tests
needs-testsderived, 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-signal refuses to add or suppress a path signal (code, docs, or system). 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-route opts out of routing entirely for that run.
  • brigadestack run --approve-ship releases 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.