Docs / Reference
work
The task ledger, import inbox, scanners, reviews, verification and backups for one repo's daily 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 briefshows branch state, active sessions, pending tasks, import counts, latest self-check run, and the command to continue.brigadestack work statusis the quick dashboard for branch state, self-check readiness, paths, latest run, and extracted next step.brigadestack work doctorchecks 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 resumeshows the active or latest session, latest self-check run, extracted next step, and suggested command.brigadestack work inboxgroups pending scanner imports by source, kind, priority, age, and acceptance coverage, then suggests plan, promote, dismiss, or run commands.brigadestack work nextprints only the next task. Add--jsonfor wrappers.
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 taskslists.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 42imports a GitHub issue withgh issue viewwhenghis available, including acceptance criteria parsed from issue-body checkboxes or acceptance/test sections.brigadestack work task add --from-nextpromotes 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.
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.jsonlchecks scanner output against the import schema.brigadestack work import ingest imports.jsonlingests scanner output.brigadestack work import memory-careconverts the memory-care refresh queue atmemory/cards/decay/refresh-queue.json(override with--queue) into imports. If the queue file is missing it errors.brigadestack work import memory-refreshconverts memory-refresh candidates into task imports with card identity, reason, evidence summary, and acceptance criteria.brigadestack work import chat-sweepconverts.brigade/chat-memory-sweeps/latest.jsonissues into imports. Actionable sweep issues become task imports with acceptance criteria, while raw private chat text is omitted.brigadestack work import triagegroups pending imports by source and kind. Use--source,--kind, and repeatable--metadata key=valueto 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, whiledismiss --allcloses 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 taskbatch-promotes filtered imports. Metadata filters also work for scanner-specific fields such ashandoff_issue_category=route-skip.brigadestack work inbox doctorreports 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 archivemoves old promoted, dismissed, and superseded imports into.brigade/work/imports/archive.jsonlwhile 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 onPATH.--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-runreports changes without writing.--jsonprints machine-readable output.
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:
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.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.
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-delaybound 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.--commitcommits successful child changes locally after exit.--watchkeeps reconciling and refilling capacity until stopped, with--intervalseconds between ticks.
Inspect and recover with the companion commands:
brigadestack work dispatcheslists 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-unknownreleases inspected unknown intents only after their children have exited.
brigadestack work dispatch --dry-run
brigadestack work dispatches
brigadestack work dispatch-show latest
Scanner registry
brigadestack work scanners initwrites gitignored.brigade/scanners.tomlwith 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 listandshow <scanner-id>inspect configured scanner commands, sources, cadence, timeout, output paths, and conflict windows.brigadestack work scanners plancalculates intended run windows, reports overlaps or clustered jobs, and prints a suggested staggered schedule.brigadestack work scanners run <scanner-id>,run --all, andrun --dueexecute 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-outputvalidates and ingests the scanner’s configured JSONLimport_pathafter a successful run.brigadestack work scanners runsandrun-show <run-id>inspect receipts under.brigade/scanners/runs/.brigadestack work scanners doctor --import-issuesreports 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 sweepis 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-ingestis present, and writes one report under.brigade/scanners/sweeps/.brigadestack work sweepsandbrigadestack 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>andsweep-review latesttriage 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 initwrites gitignored.brigade/reviews.tomlwith disabled starter entries for Codex review, Claude Opus review, and custom local reviewers.brigadestack work review planshows 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>andrun --allexecute configured reviewers explicitly, never through a shell, and write receipts under.brigade/reviews/runs/.brigadestack work review runsandbrigadestack 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 sourcecode-review.brigadestack work review findingsandfinding-show <finding-id-or-import-id>inspect imported review findings.brigadestack work review closeout <run-id>orcloseout latestwrites 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.
brigadestack work run
brigadestack work run --queue-next
brigadestack work run "review today's changes"
Useful work run switches:
--queue-nextqueues the successful run’s extracted next step for the next session.--titlenames the session.--no-handoffskips the work handoff.--dogfood-handoffalso 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 writesstart.md.brigadestack work note "checkpoint"appends a timestamped note to the active session.brigadestack work end --note "what happened"closes the active session and writesend.md.brigadestack work end --handoffalso writes a Memory Handoff.
brigadestack work start "next slice"
brigadestack work note "wired parser and tests"
brigadestack work end --note "tests passed" --handoff
Inspect local work sessions with:
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 planpreviews the local verification commands and current evidence snapshot without running anything.brigadestack work verify runexecutes explicit local verification commands without a shell and writes receipts under.brigade/work/verify-runs/.brigadestack work verify runsandbrigadestack 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 throughwork verify runand 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 onlyengineer(strict) andyolo(off). 0.32.0 addsobserveand 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 checkexits 3 when rails are off, which the pre-push hook uses.
See Modes for what each mode keeps and what it costs.
Backup health
brigadestack work backup initwrites gitignored.brigade/backups.tomlwith local NAS and cloud destination examples.brigadestack work backup statusanddoctorread local JSON summaries for latest snapshot, check, prune, and restore rehearsal status.brigadestack work backup import-issuesturns stale snapshots, failed checks, stale prunes, missing summaries, overdue restore rehearsals, and unsafe summary fields into localbackup-healthwork 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.