# route

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.

```bash
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.

| 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:

```bash
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](/docs/commands/run) for the surrounding run flags, artifacts, and run locking.