Search BrigadeStack

Search BrigadeStack pages and docs.

BrigadeStack
Menu
Docs menu

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

receiptbrigadestack 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.
receiptbrigadestack 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.

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

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