# Run a task on another agent

If you work in a single-vendor tool, you cannot ask another vendor's agent for help. `brigadestack run "<task>"` can. Ask Codex to build what Claude planned, or ask a second model to review a change, and the result comes back to you with a record of who did what. BrigadeStack shells out to each agent tool's own CLI, so it keeps no provider keys.

```bash
brigadestack run "review this repo and suggest the next step" --read-only
brigadestack run "plan the migration" --dry-run
```

`--dry-run` prints the plan and stops. `--read-only` tells every agent to inspect and recommend only.

## How a run works

One orchestrator plans the work, assigned workers execute through their own CLIs, then the orchestrator writes the final answer. That is two orchestrator calls plus the worker calls in the plan. Keep the expensive model on planning and synthesis, and let a cheaper one spend long context on edits and tests.

Plans can give assignments an integer `stage`. Same-stage assignments run in parallel, stages run lowest to highest, and later workers see earlier results. Without `stage`, everything runs as one parallel stage.

## Choose which agent runs each role

The roster is the file that says which agent runs each role.

```bash
brigadestack roster init
brigadestack roster doctor
```

`roster init` writes `.brigade/roster.toml` with a Codex orchestrator, a Codex coder and an optional Ollama researcher. Agent names are arbitrary, and the `orchestrator` key picks the agent that plans. Files that name that agent `chef` still work. The core of the file:

```toml
orchestrator = "orchestrator"

[agents.orchestrator]
cli = "codex"
role = "Plan the work, choose useful workers, and synthesize the final answer."

[agents.coder]
cli = "codex"
role = "Make precise code changes and report what changed."

[limits]
max_workers = 4
timeout_seconds = 600
allow_models = ["codex", "ollama:*"]
```

The generated file also carries a local Ollama agent and commented examples for pinning models. Ollama models are never pulled for you, so run `ollama pull` first.

`limits.timeout_seconds` is the default per-agent timeout, and `agents.<name>.timeout_seconds` overrides it for one agent. `roster init` refuses to write when `~/.brigade/roster.toml` already applies, because the starter would hide it. With no `--roster`, BrigadeStack reads `.brigade/roster.toml` in `--cwd`. In a linked git worktree it then tries the same file in the parent clone, and last it falls back to `~/.brigade/roster.toml`.

The `cli` values are adapters for installed tools: `codex`, `claude`, `opencode`, `antigravity`, `pi`, `cursor`, `aider`, `goose`, `continue`, `copilot`, `qwen`, `kimi`, `adal`, `openhands`, `grok`, `amp`, `crush`, and `ollama:<model>`. `brigadestack roster doctor` checks the syntax and which CLIs are on `PATH`.

## Check readiness

`brigadestack roster ready` inspects a worker pool without dispatching anything. Name agents with `--worker`, and optionally set `--concurrency`, `--route {brigade,t3}`, `--isolation {shared,worktree}` and `--capability`:

```bash
brigadestack roster ready --worker coder --worker local_researcher --concurrency 2 --json
```

It reports `ready` (exit 0), `blocked` (exit 2) or `unverified` (exit 3). The evidence lines are the health checks for each selected seat (declaration, executable identity, authentication and entitlement, transport liveness, version gates, model reachability and isolation compatibility), then four checks for the operation: route support, isolation, admission and capacity. A fresh roster usually comes back `unverified`. Treat it as a list of what to check.

## Pin models

`agents.<name>.model` pins the model a CLI agent runs, on the `claude`, `codex`, `grok`, `opencode`, `pi`, `kimi`, `cursor` and `antigravity` adapters. Use it with staged plans when one model should design the work and another should build it. `brigadestack roster doctor` fails before dispatch if a pin is set on an adapter that cannot take one.

## Limits and policy

- **Sandbox.** `limits.sandbox` (`read-only`, `workspace-write` or `danger-full-access`) sets the native Codex sandbox. `--sandbox` overrides it for one run. `--read-only` also adds a prompt-level review-only instruction for every adapter.
- **Dirty tree.** A write run in a git worktree refuses to start on a dirty tree unless you pass `--allow-dirty`. Dry runs, read-only runs and `--worktree` runs are exempt. `--allow-dirty` is itself refused in a primary checkout that has uncommitted changes, because BrigadeStack would attribute that earlier work to the worker. Commit or stash, run from a linked git worktree, or pass `--worktree`.
- **One run at a time.** A local `.brigade/run.lock` stops two runs from changing the same checkout. Locks from dead processes are replaced.
- **Detached checkout.** `--worktree` runs agents in a detached checkout under `~/.cache/brigade/worktrees/`, writes the diff to `changes.patch`, removes the checkout and leaves yours untouched. It cannot be combined with `--no-artifacts`.

## Common flags

- `--dry-run` prints the planned assignments as JSON and stops.
- `--show-plan` and `--verbose` print the plan, worker statuses and synthesis status.
- `--cwd` sets the working directory for agent CLI calls, and `--roster` picks a roster file.
- `--handoff` writes a handoff for a successful run, and `--handoff-inbox` sets where it goes.
- `--inspect` prints the same summary as `brigadestack runs show`.
- `--output-dir` picks the artifact directory, and `--no-artifacts` skips artifacts.