handoff

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. brigade handoff sources init writes local handoff source coverage for Claude, Codex, OpenCode, and Hermes (flags: --target, --force, --json). brigade 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

brigade handoff draft writes a new handoff note into a selected writer inbox. One of --content or --content-file is required for the note body.

brigade handoff draft --target ./my-repo --inbox codex \
  --title "What changed" \
  --summary "Short note future agents should know." \
  --content "The durable note itself goes here."

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

brigade handoff migrate converts near-miss homegrown handoff notes (loose - Type: style metadata) into the Brigade template through the standard draft renderer, so existing notes stop failing lint identically to garbage.

brigade handoff migrate --target .
brigade 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

• brigade handoff doctor reports pending writer-inbox handoffs that are not covered by the local source list, and can check ingestor.last_run_log for 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 harness.
• brigade handoff lint validates pending handoffs before ingest. Card actions require Target card plus Suggested card content and must omit document sections. no-card actions 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.

brigade handoff doctor
brigade handoff lint

Draft queue

• brigade handoff list lists local Memory Handoff drafts from .claude/memory-handoffs/, .codex/memory-handoffs/, and configured source inboxes.
• brigade handoff show <handoff-id-or-path> shows lint status, target card or document, source import id, source fingerprint, scanner provenance, and stale age.
• brigade handoff archive <handoff-id-or-path> moves one reviewed draft into .brigade/handoffs/archive/ and records closeout metadata in .brigade/handoffs/archive.jsonl.
• brigade handoff archive --all-reviewed archives lint-valid drafts only. It does not run the canonical ingestor or edit memory.
• brigade handoff closeout <draft-id-or-path> writes local closeout metadata for reviewed drafts (--all closes out all non-archived drafts, --defer marks selected drafts deferred instead of reviewed).

brigade handoff list
brigade handoff show <handoff-id-or-path>
brigade handoff archive <handoff-id-or-path>
brigade handoff archive --all-reviewed
brigade handoff closeout <handoff-id-or-path>

Ingest receipts and issues

• brigade handoff runs and brigade handoff run-show <run-id> read normalized local ingestion receipts from .brigade/handoffs/ingest-runs/.
• brigade handoff receipt plan previews a normalized external ingestion receipt; brigade handoff receipt record writes it.
• brigade handoff reconcile parses the configured ingestor.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.
• brigade handoff issues groups handoff-ingest warnings with repair guidance.
• brigade handoff import-issues imports those issues as local work.
• brigade handoff sync-issues imports new issues and closes stale local handoff tasks/imports once the latest scan no longer reports them.

brigade handoff runs
brigade handoff run-show <run-id>
brigade handoff receipt plan
brigade handoff receipt record
brigade handoff reconcile
brigade handoff issues
brigade handoff import-issues
brigade handoff sync-issues

For handoff-ingest issues, prefer brigade 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; brigade handoff-template prints it, and --target prefers a target’s installed template when present.