Docs / Reference
handoff
Review, lint, and reconcile Memory Handoff drafts.
Use this to review, check and clean up the notes your agents leave for each other before they reach shared memory.
For machines that ingest handoffs from multiple repos, copy .brigade/handoff-sources.example.json to .brigade/handoff-sources.json and list the repo roots and writer inboxes the canonical ingestor scans. brigadestack handoff sources init writes local handoff source coverage for Claude, Codex, OpenCode, and Hermes (flags: --target, --force, --json). brigadestack handoff doctor reports pending writer-inbox files (.claude/memory-handoffs/, .codex/memory-handoffs/, and the other configured writer inboxes) that are not covered by that local source list.
Draft
brigadestack handoff draft writes a new handoff note into a selected writer inbox. One of --content or --content-file is required for the note body.
brigadestack handoff draft --target ./my-repo --inbox codex \
--title "What changed" \
--summary "Short note future agents should know." \
--content "The durable note itself goes here."
Draft files are created with mode 0600, so only your user can read them until the ingestor moves them. Related flags: --workspace points at the memory workspace that holds memory/cards and bootstrap documents (default --target), and --expected-sha supplies the SHA-256 of the current card for update-card drafts (looked up in --workspace when omitted). handoff lint also accepts --workspace.
The agent decides when to write a handoff, following the AGENTS.md that BrigadeStack generates. It writes one only when the session produced knowledge that the repo, git history, or an existing card does not already hold: a root cause, a decision with its reason, a new operational fact, or a stated preference. If nothing qualifies, it writes no file and ends the session with one line:
Nothing durable: <reason>
If the draft is written but fails lint, the command says so clearly and reports the kept path and the next step instead of failing silently.
Migrate
brigadestack handoff migrate converts near-miss homegrown handoff notes (loose - Type: style metadata) into the BrigadeStack template through the standard draft renderer, so existing notes stop failing lint identically to garbage.
brigadestack handoff migrate --target .
brigadestack handoff migrate --target . --apply
Dry-run by default. --apply rewrites convertible notes, preserves the originals under migrated-originals/, verifies the result passes lint, and records a receipt. Injection-flagged notes are never converted.
Doctor and lint
brigadestack handoff doctorreports pending writer-inbox handoffs that are not covered by the local source list, and can checkingestor.last_run_logfor stale runs, skipped malformed handoffs, and warning summaries hidden behind no-reply cron output. Absent, unwatched writer inboxes collapse into a single summary line instead of one row per unselected agent tool.brigadestack handoff lintvalidates pending handoffs before ingest. Card actions requireTarget cardplusSuggested card contentand must omit document sections.no-cardactions require document sections and must omit card sections. Lint also reports prompt-injection signal counts per file, so a poisoned note cannot read as fully clean from the lint path. The embedded content guard checks egress, not instructions.
brigadestack handoff doctor
brigadestack handoff lint
Draft queue
brigadestack handoff listlists local Memory Handoff drafts from.claude/memory-handoffs/,.codex/memory-handoffs/, and configured source inboxes.brigadestack handoff show <handoff-id-or-path>shows lint status, target card or document, source import id, source fingerprint, scanner provenance, and stale age.brigadestack handoff archive <handoff-id-or-path>moves one reviewed draft into.brigade/handoffs/archive/and records closeout metadata in.brigade/handoffs/archive.jsonl.brigadestack handoff archive --all-reviewedarchives lint-valid drafts only. It does not run the canonical ingestor or edit memory.brigadestack handoff closeout <draft-id-or-path>writes local closeout metadata for reviewed drafts (--allcloses out all non-archived drafts,--defermarks selected drafts deferred instead of reviewed).
brigadestack handoff list
brigadestack handoff show <handoff-id-or-path>
brigadestack handoff archive <handoff-id-or-path>
brigadestack handoff archive --all-reviewed
brigadestack handoff closeout <handoff-id-or-path>
Ingest receipts and issues
brigadestack handoff runsandbrigadestack handoff run-show <run-id>read normalized local ingestion receipts from.brigade/handoffs/ingest-runs/.brigadestack handoff receipt planpreviews a normalized external ingestion receipt.brigadestack handoff receipt recordwrites it.brigadestack handoff reconcileparses the configuredingestor.last_run_log, writes a normalized local receipt, and connects ingested, skipped, or failed outcomes back to draft and archive metadata. It does not run the ingestor or edit canonical memory.brigadestack handoff issuesgroups handoff-ingest warnings with repair guidance.brigadestack handoff import-issuesimports those issues as local work.brigadestack handoff sync-issuesimports new issues and closes stale local handoff tasks/imports once the latest scan no longer reports them.
brigadestack handoff runs
brigadestack handoff run-show <run-id>
brigadestack handoff receipt plan
brigadestack handoff receipt record
brigadestack handoff reconcile
brigadestack handoff issues
brigadestack handoff import-issues
brigadestack handoff sync-issues
For handoff-ingest issues, prefer brigadestack handoff sync-issues over repeated raw imports. It imports only issue ids that have not already been seen locally and marks stale handoff-ingest imports/tasks resolved when the latest log no longer contains them.
The handoff template lives at <inbox>/TEMPLATE.md. brigadestack handoff-template prints it, and --target prefers a target’s installed template when present.