# work

Use this to keep one repo's tasks, imports and verification checks in a single daily routine.

Use `brigadestack work bootstrap` once per repo. It writes or verifies `.brigade/dogfood.toml`, creates local artifact directories, creates the handoff inbox, updates `.gitignore`, and reports readiness.

## Start of day

- `brigadestack work brief` shows branch state, active sessions, pending tasks, import counts, latest self-check run, and the command to continue.
- `brigadestack work status` is the quick dashboard for branch state, self-check readiness, paths, latest run, and extracted next step.
- `brigadestack work doctor` checks self-check config, security config, evidence bundles, Codex CLI, artifact paths, handoff inbox, task acceptance, issue-backed tasks, stale active sessions, ignore coverage, and latest run context.
- `brigadestack work resume` shows the active or latest session, latest self-check run, extracted next step, and suggested command.
- `brigadestack work inbox` groups pending scanner imports by source, kind, priority, age, and acceptance coverage, then suggests plan, promote, dismiss, or run commands.
- `brigadestack work next` prints only the next task. Add `--json` for wrappers.

```bash
brigadestack work bootstrap
brigadestack work brief
brigadestack work brief --json
brigadestack work status
brigadestack work doctor
brigadestack work resume
brigadestack work next
brigadestack work next --json
```

## Task ledger

- `brigadestack work tasks` lists `.brigade/work/tasks.json`.
- `brigadestack work task add "..."` queues a task manually.
- `brigadestack work task add "..." --type feature --priority high --acceptance "..."` queues typed work with repeatable acceptance criteria.
- `brigadestack work task add "..." --template bugfix --acceptance "Regression test passes"` adds template acceptance criteria while preserving explicit acceptance criteria.
- `brigadestack work task add --from-issue 42` imports a GitHub issue with `gh issue view` when `gh` is available, including acceptance criteria parsed from issue-body checkboxes or acceptance/test sections.
- `brigadestack work task add --from-next` promotes the latest extracted self-check next step.
- `brigadestack work task plan <task-id>` shows the task metadata, acceptance checklist, template guidance, and suggested run command.
- `brigadestack work task done <task-id>` closes queued work.

```bash
brigadestack work tasks
brigadestack work task add "build the next slice"
brigadestack work task add "build the next slice" --type feature --priority high --acceptance "focused tests pass"
brigadestack work task add --from-next
brigadestack work task plan <task-id>
brigadestack work task done <task-id>
```

Available task templates are `vertical-slice`, `bugfix`, `red-green-refactor`, `docs`, and `security-follow-up`. Issue-backed tasks keep issue URL, number, title, labels, state, and source metadata in the local gitignored ledger. Issue body text is not stored, and BrigadeStack does not poll, sync, mutate, or refresh GitHub issues in the background.

## Import inbox

- `brigadestack work import add "..."` creates a scanner-ready local import.
- `brigadestack work import validate imports.jsonl` checks scanner output against the import schema.
- `brigadestack work import ingest imports.jsonl` ingests scanner output.
- `brigadestack work import memory-care` converts the memory-care refresh queue at `memory/cards/decay/refresh-queue.json` (override with `--queue`) into imports. If the queue file is missing it errors.
- `brigadestack work import memory-refresh` converts memory-refresh candidates into task imports with card identity, reason, evidence summary, and acceptance criteria.
- `brigadestack work import chat-sweep` converts `.brigade/chat-memory-sweeps/latest.json` issues into imports. Actionable sweep issues become task imports with acceptance criteria, while raw private chat text is omitted.
- `brigadestack work import triage` groups pending imports by source and kind. Use `--source`, `--kind`, and repeatable `--metadata key=value` to narrow noisy queues.
- `brigadestack work import show <import-id>` inspects one import.
- `brigadestack work import plan <import-id>` previews the exact task or handoff promotion would create, including acceptance criteria, template guidance, or handoff target.
- `brigadestack work import plan-handoff <import-id>` previews the Memory Handoff draft target for durable non-task imports.
- `brigadestack work import dismiss <import-id>` removes one noisy item, while `dismiss --all` closes filtered batches.
- `brigadestack work import promote <import-id>` promotes one reviewed import into the task ledger.
- `brigadestack work import promote-handoff <import-id>` promotes one reviewed durable import into a linted Memory Handoff draft.
- `brigadestack work import promote --run <import-id>` promotes exactly one task import, then immediately runs that task through the normal work-session loop.
- `brigadestack work import promote --all --source memory-care --kind task` batch-promotes filtered imports. Metadata filters also work for scanner-specific fields such as `handoff_issue_category=route-skip`.
- `brigadestack work inbox doctor` reports missing scanner provenance, stale pending imports, broken promoted task links, changed dismissed fingerprints, noisy sources, and scanner runs that produced no imports.
- `brigadestack work inbox archive` moves old promoted, dismissed, and superseded imports into `.brigade/work/imports/archive.jsonl` while preserving pending imports.

Imports are stored under `.brigade/work/imports/inbox.jsonl`, stay gitignored, and do not write memory directly. Scanner-authored task imports may include `type`, `priority`, `template`, and `acceptance`. Promotion preserves those fields so imported tasks can enter the normal TDD task flow. Durable non-task imports such as decisions, preferences, links, commands, findings, and incidents can be promoted only into reviewed Memory Handoff drafts. For handoff-ingest issues, prefer `brigadestack handoff sync-issues` over repeated raw imports.

## Beads (bd) integration

`brigadestack work import bd` mirrors a Beads (`bd`) project's issues and dependency edges into the task ledger, keyed by bd id, so `work ready` and `work claim` honor bd blockers. It reads bd only. It runs `bd version --json` and `bd export` and nothing else, pins the bd 1.3.x export schema (tested with 1.3.1, 1.3.2 and 1.3.4), and fails closed on any other version.

- `--bd-repo <dir>` reads the bd project in another repo. It defaults to `--target`.
- `--bd-bin <path>` runs a specific bd executable instead of the one on `PATH`.
- `--from-jsonl <file>` reads a saved bd export instead of running bd. Pair it with `--bd-version X.Y.Z`, the bd release that wrote the file.
- `--dry-run` reports changes without writing. `--json` prints machine-readable output.

```bash
brigadestack work import bd --dry-run
brigadestack work import bd --from-jsonl bd-export.jsonl --bd-version 1.3.1
```

Real failures from a repo with no bd installed, and from an export written by an unsupported bd:

```text receipt="brigadestack work import bd · exit 2"
error: bd (Beads) was not found: bd. Install bd, pass --bd-bin PATH, or import a saved export with --from-jsonl FILE --bd-version X.Y.Z.
```

```text receipt="brigadestack work import bd --from-jsonl bad.jsonl --bd-version 1.2.0 · exit 2"
error: bd 1.2.0 export schema is not supported (supported: 1.3.x; tested: 1.3.1, 1.3.2, 1.3.4). Pin bd to a supported release or upgrade Brigade.
```

`brigadestack work export bd-outcomes --output <file.jsonl>` goes the other way. It writes closeout receipts and PR links per bd issue id as JSONL, so the result of a Brigade run can be attached back to the bd issue.

```bash
brigadestack work export bd-outcomes --output bd-outcomes.jsonl
```

The older `brigadestack work import --from-bd-jsonl <file> --bd-version <version>` inbox import, which stages an additive export snapshot, uses the same version pin.

Readiness also fails closed. `work ready`, `work claim`, and explicit task runs refuse tasks whose blockers or ancestor parents are missing from the ledger instead of treating them as clear. The JSON output separates unfinished and missing dependencies, and `work ready --explain` names the edge-removal repairs.

## Dispatch waves

`brigadestack work dispatch` launches one ready wave of tasks into branch-backed worktrees. Use `--dry-run` first: it writes only the session and plan files without claiming tasks or launching anything.

- `--worker <seat>` assigns one seat to every selected task. `--seat-map CLASS=SEAT` (repeatable) maps task classes to seats.
- `--max`, `--batch-size`, `--max-total`, `--deadline`, and `--spawn-delay` bound worker count, batch size, total launches including retries, wall-clock seconds, and the gap between launches.
- `--base <ref>` sets the committed base ref for child worktrees. `--commit` commits successful child changes locally after exit.
- `--watch` keeps reconciling and refilling capacity until stopped, with `--interval` seconds between ticks.

Inspect and recover with the companion commands:

- `brigadestack work dispatches` lists dispatch sessions and tripped task circuit breakers.
- `brigadestack work dispatch-show <dispatch-id|latest>` shows one session, its intents, and event receipts.
- `brigadestack work dispatch-reset <task-id> --reason "..."` resets a task's circuit breaker and records the reason. `--release-unknown` releases inspected unknown intents only after their children have exited.

```bash
brigadestack work dispatch --dry-run
brigadestack work dispatches
brigadestack work dispatch-show latest
```

## Scanner registry

- `brigadestack work scanners init` writes gitignored `.brigade/scanners.toml` with local producer entries for chat sweep, chat surfaces, memory refresh, memory care, handoff ingest sync, backup health, security findings, tool catalog health, and friction scan (nine entries).
- `brigadestack work scanners list` and `show <scanner-id>` inspect configured scanner commands, sources, cadence, timeout, output paths, and conflict windows.
- `brigadestack work scanners plan` calculates intended run windows, reports overlaps or clustered jobs, and prints a suggested staggered schedule.
- `brigadestack work scanners run <scanner-id>`, `run --all`, and `run --due` execute configured enabled scanner entries explicitly, never through a shell, and refuse disabled, risky, or overlapping runs unless the matching review flag is present.
- `brigadestack work scanners run <scanner-id> --ingest-output` validates and ingests the scanner's configured JSONL `import_path` after a successful run.
- `brigadestack work scanners runs` and `run-show <run-id>` inspect receipts under `.brigade/scanners/runs/`.
- `brigadestack work scanners doctor --import-issues` reports missing config, disabled required producers, bad commands, missing or stale output paths, schedule conflicts, failed or timed-out runs, malformed receipts, missing logs, and due scanners, then can import those health issues as local task imports.

## Daily scanner run

- `brigadestack work sweep` is the daily operator action for scanner review. It runs due scanners by default, or `--all` / `--scanner <id>` when selected, ingests configured JSONL outputs unless `--no-ingest` is present, and writes one report under `.brigade/scanners/sweeps/`.
- `brigadestack work sweeps` and `brigadestack work sweep-show <sweep-id>` review sweep reports, including scanner run receipt paths, import counts, inbox hygiene, and suggested next commands.
- `brigadestack work sweep-review <sweep-id>` and `sweep-review latest` triage one sweep by grouping created imports by source, kind, priority, acceptance coverage, provenance completeness, and status.

Scanners run when you call `work scanners run`. `brief` and `doctor` do not run them, and BrigadeStack does not promote scanner output or change it beyond the configured command's own behavior.

## Code review

- `brigadestack work review init` writes gitignored `.brigade/reviews.toml` with disabled starter entries for Codex review, Claude Opus review, and custom local reviewers.
- `brigadestack work review plan` shows configured reviewer commands, cwd, timeout, target paths, base ref, output path, findings path, and command blockers without executing anything.
- `brigadestack work review run <reviewer-id>` and `run --all` execute configured reviewers explicitly, never through a shell, and write receipts under `.brigade/reviews/runs/`.
- `brigadestack work review runs` and `brigadestack work review show <run-id>` inspect review receipts.
- `brigadestack work review import-findings <run-id>` reads the run's normalized findings JSON, redacts unsafe values, and routes findings into the existing work inbox with source `code-review`.
- `brigadestack work review findings` and `finding-show <finding-id-or-import-id>` inspect imported review findings.
- `brigadestack work review closeout <run-id>` or `closeout latest` writes a local closeout record that connects review findings to pending imports, dismissals, promoted tasks, completed tasks, and source-fingerprint changes requiring re-review.

Reviewers write receipts locally. `work run` does not start them, and BrigadeStack does not apply fixes, post review comments, change GitHub, store auth, or promote findings. Model-backed reviewers use their configured provider when you run them.

## The daily loop

Run the daily loop with `brigadestack work run`. It opens a work session, resolves the next task, runs `brigadestack dogfood`, and closes completed ledger tasks after successful runs. When the resolved ledger task has acceptance criteria, `work run` includes them in the task prompt as the definition of done. Then it ends the session, writes a work-session Memory Handoff by default, and prints a recap.

```bash
brigadestack work run
brigadestack work run --queue-next
brigadestack work run "review today's changes"
```

Useful `work run` switches:

- `--queue-next` queues the successful run's extracted next step for the next session.
- `--title` names the session.
- `--no-handoff` skips the work handoff.
- `--dogfood-handoff` also lets the underlying self-check run write its own handoff.
- Passing a task overrides the resolved next step.

## Manual sessions

- `brigadestack work start "title"` opens `.brigade/work/<id>/`, records starting context, and writes `start.md`.
- `brigadestack work note "checkpoint"` appends a timestamped note to the active session.
- `brigadestack work end --note "what happened"` closes the active session and writes `end.md`.
- `brigadestack work end --handoff` also writes a Memory Handoff.

```bash
brigadestack work start "next slice"
brigadestack work note "wired parser and tests"
brigadestack work end --note "tests passed" --handoff
```

Inspect local work sessions with:

```bash
brigadestack work list
brigadestack work latest
brigadestack work show <session-id-or-path>
brigadestack work recap
brigadestack work recap --since 2026-05-26
```

## Verification and closeout

- `brigadestack work verify plan` previews the local verification commands and current evidence snapshot without running anything.
- `brigadestack work verify run` executes explicit local verification commands without a shell and writes receipts under `.brigade/work/verify-runs/`.
- `brigadestack work verify runs` and `brigadestack work verify show <run-id>` inspect local verification receipts.
- `brigadestack work closeout <session-id-or-latest>` writes a local closeout receipt under `.brigade/work/closeouts/` that collects task acceptance, latest verification, scanner sweep status, code review closeout state, handoff draft status, and session evidence.

Verification and closeout are local gates. They do not change CI, GitHub, reviewers, scanner promotions, or handoff ingestion.

## Work mode and safety rails

- `brigadestack work mode show --target .` prints the work mode and the safety-rails state.
- `brigadestack work mode set strict|observe|off --target .` switches the mode. Strict, the default, routes checks through `work verify run` and keeps the Stop check-record gate. Off keeps the brief, recall, backend messages and handoffs on request, and drops that enforcement. Observe blocks nothing and records the raw checks agents run where the tool's hooks allow it. 0.31.0 accepts only `engineer` (strict) and `yolo` (off). 0.32.0 adds `observe` and keeps both old names as aliases.
- `brigadestack work rails show|on|off --target .` reads or changes the safety rails: the content guard, secret scanning and pre-push checks. `rails check` exits 3 when rails are off, which the pre-push hook uses.

See [Modes](/docs/concepts/modes) for what each mode keeps and what it costs.

## Backup health

- `brigadestack work backup init` writes gitignored `.brigade/backups.toml` with local NAS and cloud destination examples.
- `brigadestack work backup status` and `doctor` read local JSON summaries for latest snapshot, check, prune, and restore rehearsal status.
- `brigadestack work backup import-issues` turns stale snapshots, failed checks, stale prunes, missing summaries, overdue restore rehearsals, and unsafe summary fields into local `backup-health` work imports.

Backup health summaries are local and read-only. BrigadeStack does not run `restic`, mount storage, prune, restore, send webhooks, or mutate remote backup state.