# Brigade Overview

The full tour: every station, diagram, and workflow. The [README](../README.md) covers the core memory loop and install; this document goes deeper. The detailed command walkthrough is in the [technical guide](technical-guide.md).

## Stack At A Glance

<p align="center">
  <img src="assets/stack-at-a-glance-workflow.svg" alt="Brigade stack at a glance: writer harnesses pass through the Brigade review gate to a memory owner, durable memory, local work sessions, scanners, and release evidence" width="900">
</p>

<p align="center"><em>Generated from <code>docs/assets/workflows/stack-at-a-glance.json</code> with <code>plating workflow</code>.</em></p>

> Brigade was extracted from the [**solos-cookbook**](https://github.com/escoffier-labs/solos-cookbook), a documented 24/7 multi-agent stack running in production. If you want the full picture of how Brigade fits into a real setup, start there, and a star helps other people find it.
>
> [![Star the cookbook](https://img.shields.io/github/stars/escoffier-labs/solos-cookbook?style=social&label=Star%20solos-cookbook)](https://github.com/escoffier-labs/solos-cookbook)

## Why This Exists

Agent tools are getting good enough that people use more than one of them. That creates a boring but important problem: each tool learns a little bit, but the learning is scattered.

Brigade gives the setup a home base.

- OpenClaw or Hermes can be the main memory owner.
- Codex, Claude Code, OpenCode, Antigravity, Pi, Cursor, Aider, Goose, Continue, GitHub Copilot CLI, Qwen Code, Kimi Code, AdaL, OpenHands, Grok, Amp, Crush, and Hermes can write handoff notes.
- You can inspect and lint those notes before saving them.
- Local receipts show what happened during work, scans, and reviews.
- Risky actions stay manual.

The goal is not to make a giant automation machine. The goal is to make agent memory understandable, reviewable, and portable across harnesses.

**Agents run the system.** Install, setup, verify, and handoffs are designed to be executed by coding agents (often from a paste into Claude Code, Codex, Cursor, or OpenClaw). Humans own policy and review when a gate is ambiguous or risky. You can type every command yourself; production use is agent-driven, not a human day-to-day terminal workflow.

## Mise En Place (brand metaphor)

The product name comes from the kitchen. A *brigade de cuisine* is the staff that runs the line, and *mise en place*, pronounced "meez", means everything is in its place before the work starts. That metaphor lives in brand art and deep docs. The commands you type stay plain: `setup`, `verify`, `sync`, `code`, `evidence`.

In a kitchen, the first job is prep: label ingredients, sharpen tools, and avoid hunting for basics mid-rush. For agents, it is the same job: rules, memory, handoff inboxes, tools, guards, receipts, and verification paths set up before the session gets expensive.

Public names for the built-in engines:

| Public | Commands | Historical |
|---|---|---|
| Code map | `brigade code …` | GraphTrail |
| Evidence log | `brigade evidence …` | MiseLedger |

Standalone GraphTrail or MiseLedger installs are replaced by `brigade setup`. Some binary and path names still use the historical labels; the operator surface is the public table above.

## Start Small

Install:

```bash
pipx install brigade-cli
brigade setup
```

Set up a repo:

```bash
brigade operator quickstart --target ./my-repo --harnesses codex
brigade operator doctor --target ./my-repo --profile local-operator
```

Set up an agent workspace:

```bash
brigade operator quickstart --target ~/agent-workspace --depth workspace --harnesses openclaw,hermes --owner openclaw
brigade operator doctor --target ~/agent-workspace --profile local-operator
```

Use `--dry-run` first if you want to preview the local files Brigade will write. To wire more than one agent surface, pass a comma-separated list such as `--harnesses codex,claude,opencode,antigravity,pi,cursor,aider,goose,continue,copilot,qwen,kimi,adal,openhands,grok,amp,crush`.

If you already have a homegrown setup with scripts, handoff folders, crons, or process managers, use the adoption loop before changing it:

```bash
brigade operator adopt plan --target ~/agent-workspace --json
brigade operator adopt capture --target ~/agent-workspace --json
brigade operator adopt import-issues --target ~/agent-workspace --json
brigade operator migration status --target ~/agent-workspace --json
brigade operator migration doctor --target ~/agent-workspace --json
brigade operator migration consolidate --target ~/agent-workspace --surface shell_crontab --review-status needs-owner
brigade operator surfaces capture --target ~/agent-workspace --json
brigade operator surfaces doctor --target ~/agent-workspace --json
brigade operator surfaces review --target ~/agent-workspace --surface shell_crontab --status external-ok --all --reason reviewed-external-ownership
brigade operator surfaces reviews --target ~/agent-workspace --json
brigade operator surfaces import-issues --target ~/agent-workspace --json
```

`adopt plan` is read-only. `adopt capture` writes a redacted local snapshot under `.brigade/operator/adoption/`. `adopt import-issues` routes adoption gaps into the normal work inbox so the migration shows up in `work brief` and the daily loop. `operator migration status/doctor/import-issues/consolidate` rolls adoption state, surface review state, and pending migration work into one replacement-progress view, then lets a reviewed rollup supersede tiny record-level imports. `operator surfaces capture/list/doctor/review/reviews/import-issues` keeps a separate redacted registry for shell crontab, OpenClaw cron, and PM2 coverage under `.brigade/operator/surfaces/`. Scheduler and process surfaces are reported as counts, status totals, ordinal labels, review decisions, and fingerprints, not raw scheduler lines, job names, process names, command paths, host details, or environment values.

For a fuller first-run walkthrough and troubleshooting checklist, see [`docs/new-user-quickstart.md`](new-user-quickstart.md). For the shortest path, use [`docs/first-10-minutes.md`](first-10-minutes.md). If quickstart fails, use the Quickstart setup problem issue form and include the redacted `issue_report` from `brigade operator quickstart --json`.

Write a handoff note:

```bash
brigade handoff draft \
  --target ./my-repo \
  --inbox codex \
  --title "What changed" \
  --summary "Short note future agents should know." \
  --content "### What changed

Put the durable note here."
```

Then run your memory owner's ingester. Safe targeted notes file themselves into long-term memory automatically; only ambiguous or risky notes stay visible for review.

That is the simplest useful version of Brigade: shared handoffs, automatic filing, durable memory.

## How Memory Handoffs Work

Each writer harness gets its own local inbox. Use `brigade handoff draft --inbox <id>` to write to the matching inbox, or select the harness with `brigade operator quickstart --harnesses ...`.

| Writer | `--inbox` / harness id | Local inbox | Brigade support |
|---|---|---|---|
| Codex CLI | `codex` | `.codex/memory-handoffs/` | handoff template, ingest source, dogfood adapter, tools, skills |
| Claude Code | `claude` | `.claude/memory-handoffs/` | handoff template, ingest source, tools, skills |
| OpenCode | `opencode` | `.opencode/memory-handoffs/` | handoff template, ingest source, dogfood adapter, tools, skills |
| Antigravity | `antigravity` | `.antigravity/memory-handoffs/` | handoff template, ingest source, dogfood adapter, tools, skills |
| Pi | `pi` | `.pi/memory-handoffs/` | handoff template, ingest source, dogfood adapter, tools, skills |
| Cursor | `cursor` | `.cursor/memory-handoffs/` | handoff template, ingest source, dogfood adapter, rules, skills |
| Aider | `aider` | `.aider/memory-handoffs/` | handoff template, ingest source, dogfood adapter, tools, skills |
| Goose | `goose` | `.goose/memory-handoffs/` | handoff template, ingest source, dogfood adapter, tools, skills |
| Continue | `continue` | `.continue/memory-handoffs/` | handoff template, ingest source, dogfood adapter, rules, skills |
| GitHub Copilot CLI | `copilot` | `.copilot/memory-handoffs/` | handoff template, ingest source, dogfood adapter, instructions, skills |
| Qwen Code | `qwen` | `.qwen/memory-handoffs/` | handoff template, ingest source, dogfood adapter, tools, skills |
| Kimi Code | `kimi` | `.kimi/memory-handoffs/` | handoff template, ingest source, dogfood adapter, tools, skills |
| AdaL | `adal` | `.adal/memory-handoffs/` | handoff template, ingest source, dogfood adapter, tools, skills |
| OpenHands | `openhands` | `.openhands/memory-handoffs/` | handoff template, ingest source, dogfood adapter, instructions, skills |
| Grok CLI | `grok` | `.grok/memory-handoffs/` | handoff template, ingest source, dogfood adapter, instructions, skills |
| Amp | `amp` | `.amp/memory-handoffs/` | handoff template, ingest source, dogfood adapter, instructions, skills |
| Crush | `crush` | `.crush/memory-handoffs/` | handoff template, ingest source, dogfood adapter, instructions, skills |
| Hermes | `hermes` | `.hermes/memory-handoffs/` | handoff template, ingest source, owner adapter fragments |

OpenClaw is usually the canonical memory owner rather than a writer inbox. Add it with `--harnesses openclaw,...` when the workspace should own durable memory.

The memory owner, usually OpenClaw or Hermes, can ingest handoffs into the permanent memory files. Brigade keeps the handoff format consistent so different tools can contribute without each one inventing its own note style.

```mermaid
flowchart LR
    subgraph WRITERS [" writer inboxes "]
        C[".codex/memory-handoffs/"]
        CL[".claude/memory-handoffs/"]
        O[".opencode/memory-handoffs/"]
        A[".antigravity/memory-handoffs/"]
        P[".pi/memory-handoffs/"]
        CU[".cursor/memory-handoffs/"]
        AI[".aider/memory-handoffs/"]
        G[".goose/memory-handoffs/"]
        CO[".continue/memory-handoffs/"]
        GH[".copilot/memory-handoffs/"]
        Q[".qwen/memory-handoffs/"]
        K[".kimi/memory-handoffs/"]
        AD[".adal/memory-handoffs/"]
        OH[".openhands/memory-handoffs/"]
        GR[".grok/memory-handoffs/"]
        AM[".amp/memory-handoffs/"]
        CR[".crush/memory-handoffs/"]
        H[".hermes/memory-handoffs/"]
    end

    DRAFT["Brigade handoff draft<br/>lint · guard · classify"]
    OWNER["OpenClaw / Hermes<br/>memory owner"]
    MEM["durable memory<br/>cards · docs · learnings"]
    INBOX["review inbox<br/>ambiguous · risky"]

    C & CL & O & A & P & CU & AI & G & CO & GH & Q & K & AD & OH & H --> DRAFT --> OWNER
    OWNER -->|safe targeted, auto-filed| MEM
    OWNER -.->|needs judgment| INBOX

    classDef local fill:#eff6ff,stroke:#2563eb,color:#1e3a8a;
    classDef review fill:#fff7ed,stroke:#ea580c,color:#7c2d12;
    classDef memory fill:#ecfdf5,stroke:#059669,color:#064e3b;
    class C,CL,O,A,P,CU,AI,G,CO,GH,Q,K,AD,OH,H,DRAFT local;
    class INBOX review;
    class OWNER,MEM memory;
```

The important part is the boundary. The ingester should be conservative: safe card handoffs can become cards, targeted updates can append to the right file, and ambiguous material should be kicked back for review instead of trusted automatically.

### Card Promotion And MEMORY.md

Long-term memory has two layers. Knowledge cards under `memory/cards/` hold the detail: YAML frontmatter (`topic`, `category`, `tags`, `created`, `updated`) plus the durable facts. `MEMORY.md` is the index: one line per card, loaded at session start, never holding card content itself. When the ingester promotes a handoff, it creates or updates the card first, then adds or refreshes the one-line index entry. No-card handoffs append to the right document instead. Brigade records the receipt for every outcome but never edits `MEMORY.md` or cards itself; the memory owner does the writing.

```mermaid
flowchart LR
    HANDOFF["reviewed handoff<br/>create-card · update-card · no-card"]
    INGEST["memory ingester<br/>lint · guard · route"]
    CARD["memory/cards/&lt;name&gt;.md<br/>frontmatter + durable facts"]
    INDEX["MEMORY.md<br/>one-line index entry per card"]
    DOCS["TOOLS.md · USER.md<br/>rules/ · .learnings/"]
    RECEIPT["ingest receipt<br/>promoted · routed · skipped · failed"]

    HANDOFF --> INGEST
    INGEST -->|create-card / update-card| CARD --> INDEX
    INGEST -->|no-card| DOCS
    INGEST --> RECEIPT

    classDef local fill:#eff6ff,stroke:#2563eb,color:#1e3a8a;
    classDef memory fill:#ecfdf5,stroke:#059669,color:#064e3b;
    classDef step fill:#f1f5f9,stroke:#64748b,color:#334155;
    class HANDOFF,INGEST,RECEIPT local;
    class CARD,INDEX,DOCS memory;
```

### Keeping Cards Fresh

Memory degrades. Cards go stale, lose their backing evidence, or get superseded. `brigade memory care scan` is a read-only sweep over the card roots that checks freshness metadata (`reviewed`, `fresh_until`, confidence, evidence) and flags stale, expired, undersourced, contradictory, orphaned, and oversized cards. Flagged cards land in a refresh queue that routes into the work inbox, so a card that needs review shows up in the daily plan instead of rotting unnoticed. Brigade never edits or deletes a card automatically: the operator either refreshes it with a new reviewed date or archives it and drops the index entry.

```mermaid
flowchart LR
    CARDS["memory cards<br/>reviewed · fresh_until<br/>confidence · evidence"]
    SCAN["memory care scan<br/>read-only"]
    ISSUES["issues<br/>stale · expired · undersourced<br/>contradictory · orphaned · oversized"]
    QUEUE["refresh queue"]
    INBOX["work inbox<br/>daily plan candidates"]
    OPERATOR["operator review"]
    REFRESH["card refreshed<br/>reviewed date updated"]
    ARCHIVE["card archived<br/>index entry removed"]

    CARDS --> SCAN --> ISSUES --> QUEUE --> INBOX --> OPERATOR
    OPERATOR -->|still true| REFRESH -. fresh again .-> CARDS
    OPERATOR -->|no longer true| ARCHIVE

    classDef memory fill:#ecfdf5,stroke:#059669,color:#064e3b;
    classDef step fill:#f1f5f9,stroke:#64748b,color:#334155;
    classDef gate fill:#fff7ed,stroke:#ea580c,color:#7c2d12;
    class CARDS,REFRESH memory;
    class SCAN,ISSUES,QUEUE,INBOX step;
    class OPERATOR,ARCHIVE gate;
```

## The Local Loop

Brigade is built around a simple daily loop:

1. set up the repo or operator workspace
2. let agents work
3. run the memory ingester; it auto-files the safe notes
4. glance at anything it flagged as ambiguous or risky
5. durable memory grows with only the parts worth keeping

```mermaid
flowchart LR
    SETUP["quickstart<br/>local files"]
    WORK["agents work<br/>sessions & tasks"]
    HANDOFF["handoffs<br/>draft & lint"]
    INGEST["brigade ingest<br/>auto-files the safe ones"]
    MEMORY["durable memory<br/>only what is worth keeping"]
    REVIEW["review inbox<br/>ambiguous · risky"]
    RECEIPTS["receipts<br/>what happened"]

    SETUP --> WORK --> HANDOFF --> INGEST --> MEMORY
    INGEST -.->|needs judgment| REVIEW
    WORK --> RECEIPTS
    INGEST --> RECEIPTS
    RECEIPTS -. better context .-> WORK

    classDef step fill:#f1f5f9,stroke:#64748b,color:#334155;
    classDef gate fill:#fff7ed,stroke:#ea580c,color:#7c2d12;
    classDef memory fill:#ecfdf5,stroke:#059669,color:#064e3b;
    class SETUP,WORK,HANDOFF,INGEST,RECEIPTS step;
    class REVIEW gate;
    class MEMORY memory;
```

This loop scales from one person using one repo or OpenClaw/Hermes workspace to a more serious operator setup with scanner inboxes, work receipts, release checks, and repo-fleet summaries. You do not need all of that on day one.

## What Brigade Can Handle

For memory:

- install shared memory files, rules, and handoff templates
- keep one canonical memory owner
- lint handoff drafts before ingest
- scan handoff drafts with Content Guard before they become durable memory
- track which local inboxes the ingestor should watch
- reconcile ingester receipts so skipped, failed, routed, and promoted notes stay visible
- support OpenClaw, Hermes, Codex, Claude Code, OpenCode, Antigravity, Pi, Cursor, Aider, Goose, Continue, GitHub Copilot CLI, Qwen Code, Kimi Code, AdaL, OpenHands, Grok, Amp, and Crush conventions

For local work:

- record work sessions and verification receipts
- collect scanner findings into reviewable inboxes
- keep release-readiness evidence local and explicit
- project shared tool docs into harness-specific folders
- summarize repo/operator state before a work session

For safety:

- run Content Guard before push, release review, or handoff ingest
- import Content Guard findings into the work inbox for review
- keep generated state ignored by default
- avoid publishing, pushing, or mutating remotes automatically
- keep notification sending opt-in; `brigade work brief` may report readiness or suggest the station, but Brigade never sends unless the operator uses an explicit send action
- make risky actions visible as operator decisions

## Ecosystem

Brigade is the local operator layer. It integrates with nearby tools instead of trying to absorb all of them.

```mermaid
flowchart TB
    BRIGADE["Brigade<br/>local operator layer"]

    subgraph MEMORY [" memory and handoffs "]
        OPENCLAW["OpenClaw"]
        HERMES["Hermes"]
        MDOCTOR["brigade memory<br/>status · lint · compact"]
        BDOCTOR["bootstrap-doctor"]
    end

    subgraph SAFETY [" safety and operations "]
        GUARD["Content Guard"]
        PANTRY["Agent Pantry"]
        NOTIFY["agent-notify"]
        TOKEN["token-glace"]
        SEARCH["code-search"]
    end

    subgraph NATIVE [" native Brigade stations "]
        REPOS["repo fleet"]
        TOOLS["tool catalog"]
        SECURITY["security scan"]
        HANDOFFS["handoff promotion"]
    end

    BRIGADE --> MEMORY
    BRIGADE --> SAFETY
    BRIGADE --> NATIVE

    classDef core fill:#2563eb,stroke:#1d4ed8,color:#fff;
    classDef group fill:#f8fafc,stroke:#94a3b8,color:#334155;
    class BRIGADE core;
    class OPENCLAW,HERMES,MDOCTOR,BDOCTOR,GUARD,PANTRY,NOTIFY,TOKEN,SEARCH,REPOS,TOOLS,SECURITY,HANDOFFS group;
```

Memory and handoff tools:

- [OpenClaw](https://github.com/solomonneas/openclaw): personal AI assistant and memory owner.
- Hermes: local memory owner and handoff writer convention.
- Memory maintenance is embedded in Brigade: `brigade memory status`, `lint`, `compact`, and `init-git` (the retired [memory-doctor](https://github.com/escoffier-labs/memory-doctor) package). Use `brigade ingest` for handoff promotion.
- [bootstrap-doctor](https://github.com/escoffier-labs/bootstrap-doctor): audits and trims the full OpenClaw bootstrap set (SOUL.md, TOOLS.md, AGENTS.md, IDENTITY.md, MEMORY.md, and related session-start files), and the same idea for other harnesses with large bootstrap files.

Safety and operations tools:

- Content Guard is embedded in Brigade and powers `brigade scrub`, publish checks, and the seeded pre-push hook. `CONTENT_GUARD_DIR` remains an explicit compatibility override for older standalone checkouts.
- [Agent Pantry](https://github.com/escoffier-labs/agentpantry): encrypted browser session, cookie, and secret sync for agent machines.
- [agent-notify](https://github.com/escoffier-labs/brigade/tree/main/stations/notify) (`stations/notify/` in this monorepo): optional notification hooks for long-running agent work. Released installs resolve the pinned managed `agent-notify` binary through `brigade setup` once a stable manifest publishes its assets. The standalone [agent-notify](https://github.com/escoffier-labs/agent-notify) repository carries a migration notice pointing here.
- [Token Glace](https://github.com/escoffier-labs/token-glace): output compaction for terminal-heavy agent workflows.
- Built-in Scout skills: Brigade wires `brigade-work` and `ultra-work-scout` during `brigade init`; use Skillet when you want the full optional skill roster.

Evidence log and code map (built in):

- **Evidence log** (`brigade evidence …`): local-first ledger of runs, crawls, and imports. Engine lives at [`engines/evidence-ledger/`](https://github.com/escoffier-labs/brigade/tree/main/engines/evidence-ledger) (historically MiseLedger). Crawls sessions, files, git, and chat into SQLite with FTS5. Archived standalone [miseledger](https://github.com/escoffier-labs/miseledger) is a history mirror only.
- **Code map** (`brigade code …`): local symbol graph (callers, impact, context). Engine lives under the monorepo engines tree (historically GraphTrail). Archived standalone [graphtrail](https://github.com/escoffier-labs/graphtrail) is a history mirror only.
- Brigade CLI (process boundary):
  - `brigade setup` installs the code-map engine, its MCP bridge, the evidence engine, SessionFind, and `agent-notify` (when published on the release manifest) from the exact release manifest
  - `brigade add evidence` / `brigade add graphtrail` remain one-release compatibility shims
  - `brigade evidence status` / `doctor` - advisory health + next commands
  - `brigade evidence crawl <args...>` / `search <args...>` - engine output and exit code pass through
  - `brigade evidence crawl plan` / `export plan` - review-only plans under `.brigade/evidence/plans/`
  - `brigade receipts export miseledger --new-only --import` - export verify/run receipts into the ledger (command keeps the historical export name for now)
- Historical note only: StationTrail and SourceHarvest were absorbed into evidence crawl in v0.3.0; their archived repos are migration notes, not active products.

Search and context tools:

- [code-search-api](https://github.com/escoffier-labs/code-search-api): local semantic code-search service backed by SQLite and Ollama embeddings.
- The read-only MCP bridge is maintained under [`code-search-api/mcp`](https://github.com/escoffier-labs/code-search-api/tree/main/mcp). Brigade retains the `code-search-mcp` compatibility key and the published package remains `@solomonneas/code-search-mcp`.

Brigade also has native local workflows for [repo fleet operations](repo-fleet.md), [portable tool catalogs](tool-catalog.md), [security scans](security.md), and [handoff promotion](handoff-promotion.md). The highlights are below.

## Repo Fleet

`brigade repos` watches a configured set of local repositories and turns their state into reviewable evidence: health scans, sweeps, reports, fleet actions, and release trains.

```mermaid
flowchart LR
    CONFIG[".brigade/repos.toml<br/>configured local repos"]
    SCAN["repos scan / sweep<br/>safe metadata only"]
    REPORT["fleet report<br/>health evidence"]
    ACTIONS["reviewed actions<br/>start · done · defer"]
    RELEASE["release train<br/>manual checklist"]

    CONFIG --> SCAN --> REPORT --> ACTIONS --> RELEASE
    RELEASE -. no publish step .-> MANUAL["operator publishes manually"]

    classDef local fill:#eff6ff,stroke:#2563eb,color:#1e3a8a;
    classDef review fill:#fff7ed,stroke:#ea580c,color:#7c2d12;
    class CONFIG,SCAN,REPORT local;
    class ACTIONS,RELEASE,MANUAL review;
```

- Repos live in a gitignored `.brigade/repos.toml`. Nothing is cloned, pushed, or mutated remotely.
- `brigade repos scan` and `brigade repos sweep` collect local health evidence.
- Reports become fleet actions you start, finish, defer, or dispatch by hand.
- Release trains gather readiness evidence and checklists without publishing anything.

Full command list in [Repo fleet](repo-fleet.md).

## Tool Catalog

`brigade tools` describes local callable tools, slash commands, skills, scripts, and MCP configs across harnesses, then gates execution behind an approval queue. `brigade tools defaults` refreshes built-in portable tool entries while preserving custom repo tools.

```mermaid
flowchart LR
    SOURCE["tools/<br/>tracked portable sources"]
    CATALOG[".brigade/tools.toml<br/>catalog"]
    PROJECT["sync-tools<br/>harness projections"]
    APPROVAL["call plan / queue<br/>operator approval"]
    RUN["run receipt<br/>logs · replay · checkpoints"]

    SOURCE --> CATALOG --> PROJECT
    CATALOG --> APPROVAL --> RUN
    PROJECT -. local generated .-> HARNESSES[".codex · .claude<br/>.opencode · .antigravity · .pi · .cursor<br/>.aider · .goose · .continue · .copilot<br/>.qwen · .kimi · .adal · .openhands<br/>.grok · .amp · .crush · .mcp"]

    classDef source fill:#ecfdf5,stroke:#059669,color:#064e3b;
    classDef local fill:#eff6ff,stroke:#2563eb,color:#1e3a8a;
    classDef gate fill:#fff7ed,stroke:#ea580c,color:#7c2d12;
    class SOURCE source;
    class CATALOG,PROJECT,HARNESSES local;
    class APPROVAL,RUN gate;
```

- Discovery is read-only: `list`, `search`, `describe`, `contracts`.
- Projections write reviewed harness-specific tool docs. There is no auto-sync.
- Script calls move through plan, queue, approve, run, with run receipts and replay.
- Runtimes are supervised explicitly. Brigade never auto-starts MCP servers or stores auth.

Details in [Tool catalog](tool-catalog.md).

## Handoff Promotion

Reviewed scanner imports can be promoted into memory handoff drafts instead of being retyped by hand.

```mermaid
flowchart LR
    IMPORT["work import<br/>decision · finding · command · incident"]
    PLAN["plan-handoff<br/>preview target & blockers"]
    PROMOTE["promote-handoff<br/>write draft"]
    LINT["handoff lint<br/>format · route · guard"]
    DRAFT["memory-handoffs/<br/>reviewed draft"]
    OWNER["memory owner ingest<br/>outside Brigade"]

    IMPORT --> PLAN --> PROMOTE --> LINT --> DRAFT --> OWNER
    LINT -->|blocked| REPAIR["repair import"]

    classDef import fill:#eff6ff,stroke:#2563eb,color:#1e3a8a;
    classDef gate fill:#fff7ed,stroke:#ea580c,color:#7c2d12;
    classDef memory fill:#ecfdf5,stroke:#059669,color:#064e3b;
    class IMPORT,PLAN,PROMOTE import;
    class LINT,REPAIR gate;
    class DRAFT,OWNER memory;
```

- Works for durable non-task imports: decisions, preferences, links, commands, findings, incidents.
- `brigade work import plan-handoff` previews the target and blockers, `promote-handoff` writes the draft and lints it.
- Drafts land in the normal handoff inbox. Canonical memory is never edited directly.
- Raw private chat fields are rejected and secret-looking values are redacted before the draft is written.

See [Handoff promotion](handoff-promotion.md).

## Deep Research

`brigade research` turns a research question into a local report and a reviewed Memory Handoff. Trusted local files and configured CLI lanes are used first; browser or web sources are opt-in with `--web` and labeled as untrusted source material.

```mermaid
flowchart LR
    QUESTION["research question"]
    RUN["research run<br/>local-first · resumable"]
    REPORT["report.html<br/>report.md"]
    EXPORT["export-handoff<br/>explicit writer inbox"]
    DRAFT["memory-handoffs/<br/>linted draft"]
    MEMORY["memory owner ingest<br/>cards or learnings"]

    QUESTION --> RUN --> REPORT
    RUN --> EXPORT --> DRAFT --> MEMORY
    EXPORT -. drift visible .-> REVIEW["work brief<br/>center reviews<br/>release evidence"]

    classDef local fill:#eff6ff,stroke:#2563eb,color:#1e3a8a;
    classDef review fill:#fff7ed,stroke:#ea580c,color:#7c2d12;
    classDef memory fill:#ecfdf5,stroke:#059669,color:#064e3b;
    class QUESTION,RUN,REPORT local;
    class EXPORT,REVIEW review;
    class DRAFT,MEMORY memory;
```

```bash
brigade research run "what should we remember about this topic?" --corpus docs
brigade research export-handoff <run-id> --inbox codex
brigade research handoffs doctor
brigade research handoffs import-issues
brigade research show <run-id>
```

Exports are explicit and receipt-backed. Brigade records the source fingerprint for the handoff artifact, then warns when a completed research run has no export, a missing export path, or a stale export after the run artifact changes. The doctor is read-only; import routing creates reviewable work inbox items instead of exporting or ingesting memory automatically.

## Agent Pantry

The `pantry` station (alias `larder`) wires [Agent Pantry](https://github.com/escoffier-labs/agentpantry) into the same operator workflow: encrypted browser session, cookie, and secret sync between agent machines. Agent Pantry stays a **separate Go binary** (process boundary). Brigade installs it, plans setup, and health-checks it; it does not mint PSKs, start source/sink, or mutate browser auth files. The pantry is where the chef stores the cookies and the secret recipes.

Multi-machine path (sink on the agent host, source on the daily driver):

```bash
brigade add pantry
brigade pantry setup plan --role sink --peer 127.0.0.1:8787
brigade pantry setup plan --role source --peer <sink-host>:8787
# run the printed agentpantry commands yourself, then:
brigade pantry doctor
brigade pantry expiry-alert          # preview near-expiry cookies
brigade pantry expiry-alert --send   # optional agent-notify (install notifications first)
```

- `brigade pantry status` / `brigade pantry doctor` — advisory health with next commands.
- `brigade pantry setup plan` / `service plan` — review-only plans under `.brigade/pantry/plans/`.
- Pantry checks are advisory for workspace `doctor`. An unwired install warns but never fails a workspace run.

## Notifications

The `notifications` station wires optional `agent-notify` into the same operator workflow: private Discord, Telegram, or Signal delivery for long-running agent work. Source lives in [`stations/notify/`](../stations/notify/) in this repository. `agent-notify` stays a **separate Go binary** (process boundary). Brigade installs it, plans setup, and health-checks it; it does not send messages from doctor, status, or brief flows.

Released pipx installs resolve `agent-notify` from the pinned unified release manifest through `brigade setup` once stable publishes its assets. `go install github.com/escoffier-labs/agent-notify/cmd/agent-notify@latest` is the explicit fallback when you are on a source checkout or the component is not yet published on the running manifest. Source lives in [`stations/notify/`](../stations/notify/); the standalone [agent-notify](https://github.com/escoffier-labs/agent-notify) repository carries a migration notice pointing here.

```bash
brigade add notifications
brigade notifications status --json
brigade notifications setup plan --profile operator
# optional delivery after wiring:
brigade pantry expiry-alert --send
```

- `brigade notifications status` / `brigade notifications setup plan` inspect wiring without sending.
- `brigade work brief`, `brigade center status`, and `brigade daily status/plan` may surface notification readiness or suggest installing the station.
- Brigade never sends unless the operator uses an explicit send action such as `brigade pantry expiry-alert --send`.

## For OpenClaw Users

OpenClaw can be the memory owner. Brigade gives nearby tools a way to contribute checked handoffs back into that owner memory without forcing every tool to know OpenClaw internals.

```mermaid
flowchart LR
    WRITERS["Codex · Claude · OpenCode<br/>Antigravity · Pi · Cursor writer inboxes"]
    BRIGADE["Brigade<br/>draft · lint · source coverage"]
    OPENCLAW["OpenClaw<br/>memory owner"]
    MEMORY["canonical memory"]
    RECEIPTS["ingest receipts<br/>promoted · skipped · failed"]

    WRITERS --> BRIGADE --> OPENCLAW --> MEMORY
    OPENCLAW --> RECEIPTS --> BRIGADE

    classDef brigade fill:#2563eb,stroke:#1d4ed8,color:#fff;
    classDef owner fill:#ef4444,stroke:#b91c1c,color:#fff;
    classDef local fill:#f1f5f9,stroke:#94a3b8,color:#334155;
    class BRIGADE brigade;
    class OPENCLAW owner;
    class WRITERS,MEMORY,RECEIPTS local;
```

A repo-adjacent setup is:

```bash
brigade init --target ./my-repo --depth repo --harnesses openclaw,codex,claude,opencode,antigravity,pi,cursor,aider,goose,continue,copilot,qwen,kimi,adal,openhands,grok,amp,crush
brigade handoff sources init --target ./my-repo
brigade handoff doctor --target ./my-repo
```

An OpenClaw workspace setup does not need to be inside a code repo:

```bash
brigade init --target ~/agent-workspace --depth workspace --harnesses openclaw,hermes --owner openclaw
brigade handoff sources init --target ~/agent-workspace
brigade handoff doctor --target ~/agent-workspace
```

Then writer tools leave handoffs in their own inboxes, the memory owner's ingester files the safe targeted notes automatically, and Brigade keeps receipts for promoted, routed, skipped, failed, malformed, and warning outcomes.

## For Hermes Users

Hermes now has a first-class Brigade handoff inbox:

```mermaid
flowchart LR
    HERMES["Hermes"]
    INBOX[".hermes/memory-handoffs/"]
    FRAGMENTS[".brigade/hermes/<br/>adapter fragments"]
    VERIFY["operator verify-harness"]
    HANDOFFS["handoff list / lint"]

    HERMES --> INBOX
    HERMES --> FRAGMENTS
    INBOX --> VERIFY
    FRAGMENTS --> VERIFY
    VERIFY --> HANDOFFS

    classDef hermes fill:#7c3aed,stroke:#5b21b6,color:#fff;
    classDef local fill:#f1f5f9,stroke:#94a3b8,color:#334155;
    class HERMES hermes;
    class INBOX,FRAGMENTS,VERIFY,HANDOFFS local;
```

```bash
brigade init --target . --depth workspace --harnesses hermes
brigade handoff sources init --target .
```

```bash
brigade handoff draft --target . --inbox hermes \
  --title "Hermes note" \
  --summary "Hermes can write a local Brigade handoff." \
  --content "### Hermes note

Durable context goes here."
```

Check the local wiring with:

```bash
brigade operator verify-harness --harness hermes --target .
brigade handoff list --target .
```

The verifier checks both the `.hermes/memory-handoffs/` writer inbox and the `.brigade/hermes/` adapter fragments.

See [Hermes handoffs](hermes-handoffs.md) for the current boundaries.

## Content Guard

Brigade handles the memory and operator workflow. Content Guard checks whether content is safe to publish or save.

```mermaid
flowchart LR
    SCAN["security scan<br/>redacted findings"]
    BUNDLE[".brigade/security/latest<br/>JSON · Markdown · SARIF"]
    REVIEW["review / suppress<br/>accepted risk with reason"]
    IMPORT["work import<br/>security follow-up"]
    RELEASE["release readiness<br/>local blocker evidence"]

    SCAN --> BUNDLE --> REVIEW
    BUNDLE --> IMPORT
    REVIEW --> RELEASE
    IMPORT --> RELEASE

    classDef scan fill:#fee2e2,stroke:#dc2626,color:#7f1d1d;
    classDef local fill:#f1f5f9,stroke:#94a3b8,color:#334155;
    classDef review fill:#fff7ed,stroke:#ea580c,color:#7c2d12;
    class SCAN scan;
    class BUNDLE,IMPORT,RELEASE local;
    class REVIEW review;
```

Use it at three points:

- before memory ingest: `brigade handoff lint --content-guard`
- before publishing: `brigade scrub --policy public-repo`
- after findings appear: `brigade work import content-guard`

Policy names are intentionally plain:

- `personal`: local/internal working notes
- `public-repo`: code and docs before push
- `public-content`: stricter checks for blog, social, and site copy

`brigade operator doctor` and `brigade operator status` show whether Content Guard is installed, which policy is expected, which pre-push hook is active, and the latest local scan summary when available.

Brigade also ships a read-only local security scanner. `brigade security scan` produces redacted findings you can review, suppress with a reason, or import into the work inbox. See [Security and Content Guard](security.md).

## Tiny Glossary

- **Harness**: an agent tool such as OpenClaw, Hermes, Codex, Claude Code, OpenCode, Antigravity, Pi, or Cursor.
- **Handoff**: a note an agent writes for later review.
- **Inbox**: the local folder where handoff notes wait.
- **Memory owner**: the place that keeps durable shared memory.
- **Operator**: the human deciding what gets saved, run, or published.