Brigade
Coordinate a fleet of cheap parallel coding agents from any ticket source (Notion, ClickUp, Obsidian vault boards, or a local folder of markdown files). Runs a board-first session: research a ticket with scouts, decompose it into a DAG of tiny disjoint work items, cook them in parallel git worktrees on tier-selected models, gate every diff through an adversarial inspector, land them in dependency order, and hand off one PR. For grooming or organizing a board without cooking, use the companion groom skill instead.From its SKILL.md
npx -y skills add jimador/brigade --skill brigadeAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
55.7 KB, as published. Nobody here has run it
Brigade
A brigade is a kitchen's line crew — the brigade de cuisine: tickets come in, every cook owns their station, and nothing leaves without passing inspection. This Skill turns one Claude Code session into the Planner of a parallel dev fleet:
Ticket → scouts research the codebase → Planner decomposes into a DAG of tiny, disjoint work items (each with a self-contained work packet) → parallel Cooks (models set by the service tier) implement in isolated git worktrees → an Inspector adversarially reviews each diff → landed linearly in dependency order onto the delivery branch → ticket updated, PR opened for the one human review.
It is a Claude Code-native fleet workflow with two deliberate design choices:
- The ticket source is pluggable. Notion is the reference adapter
(
sources/notion.md); ClickUp (sources/clickup.md), a local folder of markdown files (sources/local.md), and Obsidian vault boards (sources/obsidian.md) ship alongside it. Any source works if it can answer four questions (seesources/TEMPLATE.md). The dependency DAG does not live in the source — it lives in a local plan file — so the source only needs tickets, statuses, and comments. - Cost is a first-class constraint. The expensive model (this session) plans and
coordinates only. All token-heavy work — codebase exploration, implementation, review —
runs on the tier's cheap subagents (see
TIERS.md). The granularity rules below exist to make haiku viable.
Claude and Codex Brigade share one wire protocol. A dish planned or partially executed
by either runtime is resumed by the other from the same .brigade PLAN, artifacts,
branches, and worktrees without conversion.
Roles
| Role | Who runs it | Model (by tier) | Job |
|---|---|---|---|
| Planner | this session (you) | the session model — the tier's planning row | intake, decomposition, dispatch, merges, ticket updates. Never implements. Never explores the codebase directly. |
| Design | brigade-design subagent (or this session in design-only mode) | sonnet | one-shot swag: research, open questions, readiness; never claims or cooks |
| Scout | brigade-scout subagent | haiku (all tiers) | answers one focused codebase question, returns a compact brief |
| Cook | brigade-cook subagent | haiku; ★★★ dispatches the heavy cook first | implements exactly one work packet in its own worktree |
| Heavy Cook | brigade-cook-heavy subagent | sonnet | same contract as Cook, for escalations and known-hard slices |
| Inspector | brigade-inspector subagent | sonnet | adversarial PASS/FAIL review of one work item's diff before merge; optional pre-dispatch plan check |
| Analyst | brigade-analyst subagent | sonnet | self-improvement pass over a dish's reports/verdicts; proposes concrete process changes |
Model policy lives in TIERS.md (three-star / two-star / one-star); the tier also sets
scout caps, plan-check policy, and retro cadence.
The prime directive: protect the expensive tokens
You (the Planner) are the most expensive component in the system. Every rule below follows from that:
- Never read source files to "get oriented." Dispatch a Scout with a specific question
and read its brief instead. You may read: plan files, scout briefs, cook reports, inspector
verdicts,
git diff --stat, config, and small named files a brief points you at when a decision genuinely requires it. - Never implement or fix code yourself except as the documented last-rung escalation (below), and say so out loud when you do.
- Front-load context into work packets so Cooks never explore. A haiku Cook that has to hunt for context produces garbage; a haiku Cook handed exact files, contracts, and a verification command produces mergeable code. The packet is where your intelligence gets cheap leverage.
- Batch source I/O. Read the board once per phase, not per thought.
Service tiers (stars)
Model policy is a service tier, defined in TIERS.md: ★★★ three-star (say
"brigade heavy"), ★★ two-star (plain "brigade" — the default), ★ one-star (say
"brigade light"). The repo default lives in .brigade/config.md (tier: key under
## Repo; absent means two-star); a trigger phrase overrides it per dish. Record the
dish's tier in PLAN.md frontmatter tier:.
Session-model handshake. The Planner IS the session. At dish intake, compare the
session model to the resolved plannerModel when a config layer sets one, else to the
tier's planning row in TIERS.md (fable is the intended frontier value; nothing
hard-codes a planning model). If they differ, tell the operator which model to /model to,
or proceed degraded and say so. When a difficult-planning
trigger fires (the trigger list is in TIERS.md), escalate the planning checkpoint to the
tier's difficult-planning model the same way, then drop back.
Mechanical helpers — brigade-status, brigade-config, brigade-validate,
brigade-coord, brigade-risk, brigade-evidence — live at
${CLAUDE_PLUGIN_ROOT}/scripts/ (SessionStart echoes the
resolved path in brigade repos). They are NOT on PATH: whenever this document names one,
run it from that directory. They cost zero model tokens.
Whatever the tier:
- Plan once. The single planning checkpoint is the only expensive thinking per dish; after approval, everything is mechanical dispatch/merge. Never re-derive the plan.
- Resume mechanically. Run
brigade-status(zero model tokens) instead of re-reading dish artifacts to figure out where things stand. The SessionStart hook injects the same snapshot automatically in brigade repos. - Give scouts strict output budgets (the
briefschema has them) and don't start a second research round unless a specific decomposition decision is blocked.
Artifact contract (SCHEMAS.md)
Every artifact in this system — plan, packet, brief, report, verdict, plan check, analyst
report, heuristic, learnings entry — has a typed shape defined in SCHEMAS.md next to
this file: a YAML frontmatter envelope (doc, schema, dish, item, role,
model, created + type fields) and fixed body sections with length budgets and
authority rules (what counts as a valid source for that type's claims).
- When dispatching, paste the output type's schema block from
SCHEMAS.mdinto the subagent's prompt (the file also ships with the brigade plugin, next to this SKILL, for reference). Subagents emit conforming documents or their output is re-requested once with the schema, then treated as a failed attempt. - When consuming, dispatch on
doc:and trust the frontmatter as machine state — that's what makes resume, plan-state tracking, and the analyst's scoring mechanical instead of interpretive. - Conformance is checked mechanically, not by you. Run
brigade-validate(zero model tokens;--jsonfor scripts) after subagent waves and before resume-critical decisions: it checks every dish artifact's envelope, enum values, plan-DAG sanity (unknown statuses, danglingdepends_on, duplicate slugs), body budgets, and required sections. A FAIL from the validator is handled like any malformed artifact — re-request once with the schema, then treat as a failed attempt.
Claude/Codex coordination
Each dish is a single-writer shared state machine. Claude and Codex may run different dishes concurrently; they must not mutate the same dish simultaneously.
The dish slug is a canonical identity, not a title. Resolve it mechanically with
brigade-coord key <source> <immutable-ticket-id>: the helper first reuses an existing
PLAN.md whose source: and verbatim ticket: match, otherwise it normalizes
<source>-<ticket-id> by lowercasing, collapsing every run outside [a-z0-9] to -,
and trimming leading/trailing -. For work with no source ticket, first mint a stable local ticket id
local-<UTC-compact-timestamp>-<short-title-slug> and record it verbatim in PLAN. If
lookup is ambiguous or normalization is empty, stop. Claude and Codex must run this exact
derivation before acquiring or creating a dish.
Before the first mutation of a dish, run:
"${CLAUDE_PLUGIN_ROOT}/scripts/brigade-coord" acquire <dish-slug> claude
Retain the returned owner token. If another runtime holds the lease, remain read-only:
show its runtime and heartbeat, reconcile status/git/artifacts, and let the operator
decide whether to wait or investigate. Never silently break a lease.
Heartbeat after every Scout, Cook, Inspector, and landing wave. Release before yielding at a human approval/question checkpoint and at completed handoff:
"${CLAUDE_PLUGIN_ROOT}/scripts/brigade-coord" heartbeat <dish-slug> <owner-token>
"${CLAUDE_PLUGIN_ROOT}/scripts/brigade-coord" release <dish-slug> <owner-token>
A leftover lease is not stale merely because time passed. Check live sessions,
brigade-status, git worktree list, branches, and artifact timestamps. Only after
explicit operator approval, archive it with
brigade-coord break <dish-slug> --force, then acquire a new lease.
Lifecycle updates are serialized by a short operation mutex. If a crashed helper leaves
one behind, status reports operation_busy; after the same live-state checks and
separate operator approval, archive only that mutex with
brigade-coord recover-lock <dish-slug> --force, then run break or resume normally.
The shared wire contract is the canonical paths and shapes in SCHEMAS.md: PLAN statuses,
reports/<item>-cook.md, reports/<item>-verdict.md, state/<item>.md,
wip/<delivery-slug>/<item>, .brigade/worktrees/<delivery-slug>--<item>, and attempt
records {model, trigger, result}. Runtime/model identifiers are opaque provenance
strings; preserve unfamiliar Codex values.
The shared config keeps Claude agent overrides in
models.scout|cook|cookHeavy|inspector|analyst|design|steward. Codex uses separate
nested keys prefixed codex; never consume or rewrite them.
Setup and workspaces (SETUP.md)
First run in a repo (no .brigade/config.md), or a session cwd that matches a
~/.brigade/workspaces.md workspace: run /brigade:onboard (preferred) — or, as a manual
fallback, read SETUP.md (next to this SKILL) and follow its init interview and
.brigade/ layout — before anything else. Two rules hold whether or not
you read it: never commit .brigade/ (keep it in .git/info/exclude), and
brigade-config layers + doctor are free — run them before touching config by hand.
Dish artifacts live under .brigade/dishes/<dish-slug>/ (PLAN.md, briefs/,
reports/, analyst.md); executor worktrees under .brigade/worktrees/.
Design swag — one-shot research, leave in Design
Use when the operator wants a first cut, not a cook:
- "flesh out the design …", "swag this ticket …",
/brigade:design
Load agents/brigade-design.md. Write .brigade/dishes/<slug>/DESIGN.md (doc: design_swag).
Mirror open questions + status design (or scoping). Do not claim, set worker, or
dispatch cooks. Acquire <slug> as claude before writing and release it before
stopping for human curation.
Claim the ticket (mandatory before cook / decompose)
Exception — Design swag: do not claim.
Otherwise, before decompose/dispatch:
- Derive the dish slug and acquire it as
claude. - Set
assigneeto the human operator running the session. - Ensure
kindis set. - Move status
todo→in_progress(mapped native names). - On each dispatch, set
workerto the cook roster name in the same turn.
Confirm with a read-back. Skipping claim/worker while cooking in chat is a readiness
failure.
Configuration (layered — resolve it mechanically, never by reading files)
Settings come from four layers, later winning key by key: built-in defaults →
~/.brigade/config.json (global personal) → <repo>/brigade.config.json (team,
committed) → <repo>/.brigade/config.local.json (repo personal). .brigade/config.md
stays the board wiring (source, board id, identity, status mapping, gate commands);
the JSON layers carry fleet behavior and win where both express the same thing.
Resolve once per dish with brigade-config (zero model tokens):
"${CLAUDE_PLUGIN_ROOT}/scripts/brigade-config" resolve --json # merged settings + which layer set each key
"${CLAUDE_PLUGIN_ROOT}/scripts/brigade-config" prompts --json # prompt-override stacks, by role
"${CLAUDE_PLUGIN_ROOT}/scripts/brigade-config" doctor # validate every layer; exit 1 on problems
Pass the resolved settings into the Workflow scripts as overrides, and the prompt stacks
as promptOverrides (Phases 1 and 3–5). The scripts fold them over the tier policy
themselves — cook/inspector/steward agent types, scoutCap, maxParallel, and the
circuit-breaker thresholds are all overridable without editing any script.
A doctor failure is a readiness failure: fix it, or tell the user exactly which file and
key, before dispatching. The SessionStart hook already ran layers + doctor.
Context sources merge by id across the same layers, so a later layer retunes or
disables one without restating the list. Types: static-file, mcp, skill, command
(localOnly). Every source soft-fails. Write the digest to
.brigade/dishes/<slug>/CONTEXT.md at dish or design start.
KB — if the resolved kb.enabled is true and kb.cli is on PATH, run it with the
configured search_args / ingest_args; otherwise skip silently. Never hard-require a
specific vendor CLI.
Prompt overrides
Settings replace values; prompt overrides stack. Every layer with text for a role contributes, appended after the shipped prompt in layer order:
~/.brigade/overrides/{agents,prompts}/<role>.md— global personal<repo>/.brigade-overrides/{agents,prompts}/<role>.md— team, committed<repo>/.brigade/overrides/{agents,prompts}/<role>.md— repo personal- config
prompts.<role>.append— short inline additions
Roles: scout, cook, cookHeavy, inspector, analyst, design, steward,
planner. Resolve with brigade-config prompts --json at dish start and pass the result
through; agents never read override files themselves.
Overrides only ADD instructions. They never remove the Inspector gate, the Analyst pass, or the evidence requirements — forking the agent file is the honest way to do that.
HITL (Claude Code)
Prefer AskUserQuestion for fixed-choice gates (plan approval, grooming batch, ambiguity). At most one question per turn. When unavailable, ask in short prose with options + recommendation. Default: ask on ambiguity; assumptions only at very high confidence.
Phase 0 — Intake
Starting from a whole board? If the user hands you a board (or says "let's break down
my tickets / this feature") rather than one ticket, run a grooming session first — the
companion groom skill in this plugin: cluster tickets by product feature, split
multi-behavior tickets, merge duplicates, sharpen goals/acceptance with scout + inspector
review, iterating with the user. Grooming never cooks; a dish starts only when the user
picks a ticket and says go.
A dish starts from one of:
- A ticket assigned to the user. Resolve which ticket by inference, not by reflex — stop at the first rule that resolves: (1) the user named it; (2) the session has been working one ticket — continuity wins, never assume a switch without a signal; (3) the source's list my tickets op returns exactly one — take it; (4) otherwise present the list and ask. Then read the full ticket (title, body, comments) once.
- A raw idea. Do not decompose a fuzzy idea. Grill it in two stages (product intent
and system shape are different interviews):
- Product grill (PM hat): who is this for, what experience changes, what does success look like, what is explicitly out of scope. Output: a terse product brief.
- Technical grill (Architect hat): which contracts/modules are touched (ground with
scouts first, don't guess), data model implications, integration points, constraints,
risks, and how each acceptance criterion will be mechanically verified. Output: the
spec, with real decisions persisted where the repo keeps them (CONTEXT/ADRs).
If the
grillingorgrill-with-docsskill is installed (~/.claude/skills/), run it for the interview discipline — but keep the two-stage separation: product questions before system questions, one question at a time, stop when you can write the spec without hedging. Then (optionally) create a ticket on the source so the work is visible on the board.
Intake sweep: before decomposing, scan the user's other open tickets for scope overlap
with this dish. For each overlap record one decision in PLAN.md: absorb (fold it in,
comment + close the old ticket), cross-reference (comment linking the two), or leave
(checked, unrelated). An unreconciled overlap is a readiness failure — resolve it or ask.
Derive <dish-slug> with the canonical source-plus-ticket algorithm in
Claude/Codex coordination and <ticket> as the source's verbatim immutable id or key.
Create .brigade/dishes/<dish-slug>/.
Phase 1 — Research (scouts, not you)
Check memory first (cheap, before any scout). Read the last few entries of
.brigade/LEARNINGS.md. If ~/.brigade/config.json (or .brigade/config.local.json) has
kb.enabled: true and kb.cli is on PATH, run the configured search_args for the live
heuristic set and apply it while decomposing; then search for prior art on this
repo/domain with a second search using ticket keywords. Past decisions found here are
pasted into packets like any scout finding. No KB CLI / disabled → skip silently.
Formulate the smallest set of focused questions whose answers you need to decompose safely. Typical questions: "Which files/modules implement X and what are their public contracts?", "How is Y tested and what's the test command?", "What would break if we changed Z?".
Invoking the brigade-research Workflow script is the Planner's opt-in to multi-agent
orchestration — fanning the questions out to scouts rather than answering them yourself.
Build the questions array — one entry per question, {n, topic, question, why, allowWeb}
— and invoke the Workflow tool with:
scriptPath: the resolved ABSOLUTE path tobrigade-research.js. Prefer$CLAUDE_PLUGIN_ROOT/workflows/brigade-research.jswhen that env is set (SessionStart echoes it in brigade repos); otherwise resolve from the skill base:<skill-base>/../../workflows/brigade-research.js. Absolute plugin/cache paths are accepted by the Workflow tool — do not copy scripts into.brigade/workflows/.- args (may be passed as a JSON string):
{ dishDir, repoRoot, now, tier, questions, overrides, promptOverrides }—overridesis theconfigobject frombrigade-config resolve --json(passing the whole resolve output also works — the scripts unwrap.config),promptOverridesthe map frombrigade-config prompts --json. Both are optional; omitting them runs pure tier policy.
The script caps dispatch at the resolved scout budget (dropping and logging the rest) and
returns { briefs: [{n, topic, answer, confidence, briefPath, notVerified}], dropped, failed }. At ★★★ the Planner may additionally read pivotal files directly — the one tier
where that is not a violation.
Read the briefs. If a brief surfaces a genuine unknown that changes scope, ask the user — one question at a time, decision-ready framing. Do not start a second research round unless a specific decomposition decision is blocked without it.
Research dishes. When a dish's deliverables are research reports rather than code, the
work items are research tickets and their outputs are research-type artifacts
(SCHEMAS.md). Mark the plan kind: research — no packets; each item's board ticket
carries its goal/context/acceptance criteria. Give every item a research depth at plan
time — light (haiku, ≤ 150 lines, repo-first), medium (sonnet, ≤ 250 lines, one
candidate/area with web sourcing), heavy (opus, ≤ 400 lines, decision-grade surveys and
rubric scoring). Depth sets the researcher's model and the report's budget, independent of
the service tier. Dispatch in waves like cooks (≤ 4 at a time; when siblings score against
a shared rubric, the rubric-producing item goes in an earlier wave), and the planner
writes the synthesis itself. Two rules for that rubric and that synthesis: a build-vs-buy or
tool-choice rubric carries a weighted governance/longevity criterion (maintenance
activity, bus factor, single-vendor rot risk) alongside the technical-fit axes, or a
well-executed custom build scores as a ceiling the rubric can't discount; and convergence
between researchers counts as independent validation only when the converging reports did
not share the inputs that would explain it — same rubric, same grounding briefs, same source
docs. State what they shared, and call material overlap "consistent with shared grounding"
rather than confirmation.
Phase 2 — Decompose (your most important job)
Every rule below is numbered so a retro, a plan check, or an analyst report can cite it
(P3, D5) instead of restating it in prose. Each carries the evidence that earned it —
that clause is why the rule survives contact with a plausible-sounding exception.
Write the plan
Write .brigade/dishes/<dish-slug>/PLAN.md conforming to the plan type in SCHEMAS.md:
frontmatter carries the ticket, intake decisions, and the machine-readable item list (slug,
status, depends_on, heavy, files); the body carries one work packet per item (format in
templates/work-packet.md).
A groomed ticket's ## Proposed breakdown is a hint, not a contract. Check each
proposed piece against the scout briefs and the rules below, keep what holds, split or
merge what doesn't, and note material deviations in PLAN.md so the ticket author can see
why the shape changed.
P — Verify every premise before it goes in a packet
Any contract a packet states as fact is read at source level before dispatch. An unanchored scout claim is an inference to re-derive, not a fact to paste.
-
P1 — Source-level reads. Quote the actual library signature, the precedent's actual calls, the query builder's WHERE/label clause, or the primary doc. Never paste a contract you have only read about.
-
P2 — Dry-run every gate, and classify what it proves. Run each distinct gate command and self-check grep on the base branch before dispatch. Then classify them — a green exit says nothing about scope on its own:
"${CLAUDE_PLUGIN_ROOT}/scripts/brigade-evidence" classify --json <gate-cmd>...Anything it reports
targetedproves one file or one package, not the repo. A suite silently narrowed by--filter,--project,-k, or a path argument exits 0 exactly like the full suite. Record each gate'sscopein the packet's Verify block so the cook, the inspector, and Phase 6 all know what a pass there is worth. -
P3 — Exhaustiveness claims are re-derived. "All call sites", "all files with X" is produced by your own grep at packet-write time, never copied from a brief or a review. Every copied list so far has been short.
-
P4 — Parity claims are checked against base. "Matches today's behavior" is verified against the base branch itself. Sibling artifacts written alongside the change (docs, tests, comments) validate each other circularly and prove nothing.
-
P5 — Coverage claims carry proof. "Existing tests already cover X" cites the covering test's name and line, or the grep output that proves it. Two sibling packets in one dish repeated the same unverified coverage claim that a one-line grep disproved.
-
P6 — Propagation claims are read off the resolver. "Existing records pick this up automatically", "the profile change flows through" — data denormalized at write time never retro-updates. When it doesn't propagate, the item carries the backfill or seed-migration step rather than a hope.
-
P7 — Grep for the existing receiver before adding a new one. Before proposing any new listener, sync, trigger, or handler class, find the thing that already receives that event and read its doc comment. If you still want a new one, the item note cites the existing handler as the thing being extended or deliberately bypassed, with the reason. A new mechanism with no such citation is an unfinished plan — one Planner drafted four duplicate mechanisms across two dishes on the same branch, every one caught downstream instead of at drafting time.
D — Shape the DAG
- D1 — Disjointness is the spine. Two items in the same wave must not touch the same
files, doc files included. Anything that genuinely overlaps is sequenced with a dependency
edge, not parallelized. A merge conflict later means the decomposition was wrong — record
it in
LEARNINGS.mdand sequence such work next time. - D2 — A rewrite invalidates a verdict. Any rewrite of a file that already carries an inspector PASS needs a re-verdict covering the new content before merge.
- D3 — Shared contracts own their blast radius. An item that edits a shared type, schema, or interface names every consumer that must compile against it in its scope, and goes first in the DAG so dependents branch from the merged contract.
- D4 — Ownership runs the whole call chain. An item adding a leaf API, callback, or config flag names every hop the real consumer traverses (leaf → panel → section → host; producer → resolver → policy) and verifies through the consumer end, not the producer in isolation. "The mechanism exists" is not "callers actually traverse it", so a scout question covers invocation topology — who mounts this, how do the existing tests mount it — whenever behavior routes through a central handler, middleware, or DI.
- D5 — The producing item creates the shared facade. A shared facade or re-export that ≥2 sibling items import is in the producing item's own files list, never left for the first downstream cook to discover missing.
- D6 — Cross-dish shared artifacts get a tracked bridge. When a shared artifact is also compiled against by another in-flight dish, widen it behind a temporary backward-compatible overload so the other branches keep building, and record removing that scaffolding as an explicit cleanup item in PLAN.md. An untracked bridge becomes permanent API.
- D7 — A wave-boundary gate is pasted into a packet. A gate the plan schedules at a wave boundary goes verbatim into the Verify block of the packet that closes that wave. A gate that lives only in plan prose is a gate nobody runs — a promised post-wave production build never ran, and a blocking prerender regression survived every per-item gate.
The haiku bar
The bar every first-attempt packet must clear, whatever model cooks it. All of:
- Touches 1–3 named files (plus its own new test file).
- ≤ ~150 changed lines expected.
- One behavior — describable in one sentence without "and".
- Zero exploration required — every contract, snippet, and convention the Cook needs is in the packet. If you can't write the packet without hedging ("look around for…"), you haven't finished researching or splitting.
- Mechanically verifiable — the packet names the exact command(s) that prove it done. Count-style checks assert the delta against base (new occurrences, changed lines), never an absolute count of a term the base file already contains.
An item that can't meet the bar gets split further.
Heavy flags
An item that is irreducible and still hard is marked heavy: true in the plan and dispatches
to the heavy Cook from the start, at any tier. Hard means one of:
- Cross-cutting, concurrency, security, data correctness, or subtle contracts.
- A proven cheap-model failure class: comparisons across two serialization/hash domains; soundness or under-approximation proofs; packets pasting verbatim external signatures or citations; precision-text work demanding literal placeholder text; byte-faithful extraction or mirroring; exact alignment.
- A named-but-self-enforced hazard — any packet that must NAME a specific data-structure alignment, ordering, or drop-semantics hazard and require the cook to hold it in mind rather than a gate that mechanically enforces it. Cheap cooks went 0/4 across this class and same-model retries fixed nothing.
- An exact-message assertion — any test packet asserting an EXACT error or output string. Haiku repeatedly fabricates the expected string or swaps the case rather than reporting the mismatch; a prose ban has not held.
Plain verbatim insertion at an exact quoted anchor is not in this class — cheap cooks
paste-at-anchor cleanly (proven first-attempt clean where reformatting went 0/4). Leave those
heavy: false.
Mechanical risk check. At packet-write time run
"${CLAUDE_PLUGIN_ROOT}/scripts/brigade-risk" --json --files <item's files> over every item's
files list; the table lives in policies/risk-escalation.md. An escalate: true result forces
heavy: true in the item's frontmatter entry as a plain value — never an inline # comment
inside the flow mapping, or brigade-validate's manual parser breaks — and records the matching
categories in the packet header line (**heavy:** true — table: auth). Table flags are add-only:
your judgment may add heavy flags, never remove one the table triggered.
Heavy items are the exception. More than ~1 in 5 means the decomposition is too coarse — that guideline counts judgment-based flags only; table-triggered flags are exempt.
Adversarial plan check
Policy is set by the tier (TIERS.md: ★★★ always; ★★ when the dish has ≥ 6 items, touches a
shared contract, or burned you last time; ★ never — run the packet-quality self-check against
the bar above instead).
When it runs, before showing the user the plan, dispatch brigade-inspector in plan check
mode: it first sketches its own decomposition from the ticket + scout briefs without reading
your plan (blind, to break groupthink), then reads PLAN.md and writes a comparison —
coverage differences, per-divergence which version is stronger and why, and concrete merge
recommendations.
It executes the packet's pasted Verify commands and premise-probes against the real tree, never just reads them. Every executing plan check this fleet has run caught a defect a reading pass would have shipped: an invalid-JSON repro payload, a second latent bug under the stated one, a hard-FAIL that would brick a complete historical dish, a Verify command that dies on this environment's own shell shims.
Three things the check resolves rather than reports:
- When two sibling packets assert the same runtime string or output, or a packet embeds a payload from a scout brief, the check executes that shared case once and pastes the literal captured output into every packet that asserts it. Packet authors never re-derive or analogize it — an analogized deny message burned a full escalation ladder.
- When it raises a blocking contradiction between a sourced scout claim and an assumption your plan overrides, and the assumption is cheap to test, the resolution is a live probe run before dispatch — never an unsourced assertion from either side.
- When another active dish shares this dish's delivery branch, paste that dish's item file lists into the plan-check packet with an explicit overlap instruction. A file both plans touch is a blocking coordination point, not something commit ordering can be trusted to sort out.
You fold in what's right. You own the plan; the check is information, not instruction. A bad decomposition costs far more than one sonnet pass, but not every dish can afford the pass — that trade is what the tier already decided.
The planning checkpoint
Show the user the plan (item titles, DAG edges, wave layout, heavy flags, and the plan check verdict if one ran) and get one confirmation before creating branches. This is the single planning checkpoint. Release the dish lease before yielding for that confirmation.
Phase 3–5 — Execute the DAG (brigade-execute Workflow script)
Pre-flight. Reacquire the dish lease, then reconcile PLAN.md, artifacts, branches,
and worktrees before dispatch. Before creating the delivery worktree, run
"${CLAUDE_PLUGIN_ROOT}/scripts/brigade-coord" preflight <dish-slug> --branch <delivery-branch>.
Any conflict is a stop condition: report what's already in flight (the branch, the PR URL,
or the other dish's overlapping items) and stop for the operator — never route around a
collision by renaming the branch or proceeding, and never treat it as a merge problem to
solve later. State UNCHECKED entries (offline, no gh) in the pre-flight report rather
than assuming they're clean. Branches become PRs and history — name them for WHAT THEY DELIVER, in the
repo's own convention, never for the process that made them (no "brigade" in any branch or
worktree name). Pick a short delivery slug at plan time and record it in PLAN.md
frontmatter as delivery_branch: — e.g. feat/config-users, fix/async-401,
docs/everyday-setup — matching whatever prefix convention the repo already uses (check
git log/existing branches). Cut it from the repo's main line and create the standing
delivery worktree once, before dispatch (the location .brigade/worktrees/ stays — tidy
and git-excluded):
git worktree add .brigade/worktrees/<delivery-slug> -b <delivery-branch> <main-line>
Set every item about to be dispatched to its dispatched-equivalent PLAN.md status. On the
first dispatch of the dish, move the source ticket to in-progress and post a short
human-facing comment (plain language, no jargon, no local paths). Then build the execute
args from .brigade/config.md's gate commands and the plan's item list.
Invoking brigade-execute is the Planner's opt-in to multi-agent orchestration for the
cook/inspect/land loop. Resolve scriptPath the same way as research —
$CLAUDE_PLUGIN_ROOT/workflows/brigade-execute.js when set, else
<skill-base>/../../workflows/brigade-execute.js. Invoke with args (may arrive as a JSON
string): { dishDir, repoRoot, now, tier, deliverySlug, deliveryBranch, gate: [], maxParallel, overrides, promptOverrides, items: [{slug, status, dependsOn: [], heavy, packet}] } — packet is the item's full, standalone work-packet text; gate is the
repo's verification gate commands (resolved gate wins over .brigade/config.md);
overrides is the config object from brigade-config resolve --json (passing the whole
resolve output also works — the scripts unwrap .config), and promptOverrides comes from
brigade-config prompts --json — as in Phase 1.
When building items from PLAN.md, map frontmatter depends_on → dependsOn (the script
also accepts depends_on as an alias).
The script runs the whole DAG: per-item worktree creation, the tier's escalation ladder
(haiku retry → heavy cook, in order), adversarial review, linear rebase + fast-forward
landing, cleanup, and a circuit breaker on repeated failure. It returns one ledger:
{ items: [{slug, status: 'done'|'rework-needed'|'blocked'|'blocked-on-dep'|'skipped', attempts: [{agentType, result}], landedRange, reportPath, verdictPath, findings, blockedReason}], stoppedEarly, reason }.
Applying the ledger. The ledger is a subagent's claim about artifact state, not the
state itself: any assertion the Planner writes into PLAN.md or a landing note about
artifacts — verdict existence, who wrote a file, reconstruction counts, gate reruns —
derives from an artifact scan (brigade-validate, brigade-status, or reading the file's
own frontmatter), never from a workflow return value alone. Telemetry is provisional
until disk-verified; where they disagree, the artifact wins and the discrepancy is
itself a finding. For each item: mirror status and attempts into PLAN.md; record
landedRange next to it when present; if the item is also a board ticket, transition it
live per Status mapping below (in-progress → done, or → blocked) — never batched. Then run
the retro-readiness check: every done item has a populated attempts: entry in PLAN.md
AND both a surviving reports/<item>-cook.md and reports/<item>-verdict.md on disk —
the items most worth auditing are exactly the ones whose trail goes missing — subagents have returned verdicts to the ledger
without writing the file, leaving resume and retro blind. Reconstruct any missing artifact
from the ledger's structured data (attributed as a reconstruction) before the dish counts
as retro-ready — and report it as healed, never folded into a clean pass. A reconstructed
verdict that gated a heavy or otherwise high-risk item gets a real re-inspection: rebuilding
it from telemetry drops precisely the gate-rerun evidence that made the verdict worth
anything. Then act on status:
done— landed and cleaned up; nothing further.skipped— was alreadystatus: donein PLAN.md when the script started (resume).blocked-on-dep— a dependency didn't land this run; re-invoke execute once it does.rework-needed— the ladder got a PASS but landing itself failed (rebase conflict, contamination in the main checkout, or the branch turned out not to be contained in the delivery branch). ReadblockedReasonto see which; if it's a conflict, resolving it changes the shipped diff, so fix it in the item worktree and re-run the Inspector on the resolved state before landing it yourself with the same recipe (contamination check, rebase, fast-forward, cleanup) — this is the one path the script can't retry unattended.blocked—blockedReasonnames the cause; causes include a steward-create failure, a cook-reported readiness/underspecified-value block, an escalation ladder exhausted with no PASS, and an item that never got a cook dispatched because the circuit breaker had already tripped before its turn. The first two need a decision-ready question — name the exact value needed, never guess one to keep moving; a cook that blocked on an impossible packet step instead of inventing a workaround did its job, so rule on the question and fix the packet rather than re-dispatching the same contradiction. An escalation ladder exhausted with no PASS is the Planner's rung-3: fix it yourself (announce it, keep the diff minimal), re-run the Inspector on your fix, then land it yourself the same way. The breaker-already- tripped case needs neither — it's subsumed bystoppedEarlybelow, which is where you actually act on it.
If stoppedEarly is true, the circuit breaker tripped (repeated FAILs across items, or an
item's ladder exhausted) — evidence the starting assumptions were invalid, not bad luck. Do
not keep re-dispatching: step back and re-plan from first principles — re-derive what's
actually being built, re-scout the premises the packet was written from, question the
decomposition itself, and bring the operator in if the requirements themselves are suspect.
A third rework attempt against a wrong premise is the most expensive way to discover it.
With graphite_restack: true in the repo config, you (the Planner) own gt for
landing/rework rebases — the execute script always lands with plain git. After the script
returns a ledger, apply Graphite restack/absorb yourself per GRAPHITE.md (next to this
SKILL) for sequential chains that need it; never ask cooks/scouts/inspectors to run gt.
graphite_platform still only changes Phase 6 handoff (gt submit --stack).
Worktrees are script-owned, not native. The execute script's steward stage creates each
item's worktree (git worktree add .brigade/worktrees/<delivery-slug>--<item-slug> -b wip/<delivery-slug>/<item-slug> <delivery-branch>) before its first cook attempt, and on
PASS lands it: a stand-down check first — git status --porcelain against the main
checkout — refuses to land if anything outside .brigade/ is modified or untracked, so a
stray cook can never contaminate the main checkout; then rebase in the item worktree,
fast-forward-only merge in the delivery worktree, then removes the worktree and branch. The
Planner never runs these commands directly; PLAN.md still gets the landed SHA range for
traceability.
Native Claude Code worktree support was evaluated for this and not adopted: its base ref is
origin/HEAD or HEAD, never a moving delivery tip that dependent items should branch
from; its branch names are auto-generated rather than delivery-scoped and traceable; its
location is .claude/worktrees/ rather than the git-excluded .brigade/worktrees/; and it
has no rebase-then-fast-forward landing choreography of its own.
Working memory is script-decided, not planner-decided. The execute script attaches a
ledger (MEMORY.md next to this SKILL) to heavy items and rework attempts: the cook
keeps the packet's constraints as protected Canon plus its own verified World state at
.brigade/dishes/<dish>/state/<item>.md, the next attempt inherits it, and the
Inspector audits it. On by default; workingMemory: false in any config layer disables
it fleet-wide. Packets need no extra section — Canon is seeded from the packet's
existing file list, contracts, and Verify commands, which is one more reason those must
be pasted and exact.
Phase 6 — Handoff & analyst
When all items are merged:
-
Run the full verification gate once on the integration branch (dispatch a Cook to run it if output is long; you only need the pass/fail tail). Before any handoff text calls that gate green, prove the commands that actually ran cover every claimed kind at full scope:
"${CLAUDE_PLUGIN_ROOT}/scripts/brigade-evidence" cover --claim test,lint,typecheck -- <commands actually run>A non-zero exit means a claimed kind was covered only by a targeted run. Never upgrade a targeted check into repo green — fix the coverage or say plainly, per kind, what was and was not proven. When the dish assembled one feature incrementally across items (a resolver, dispatcher, pipeline) or contains a heavy data-correctness item, also run a whole-feature adversarial review scoped to the assembled behavior — per-item reviews are structurally blind to properties that span sibling diffs (proven twice: a cross-context leak and a data-corruption blocker each passed every per-item inspection). A dish where one config or data value is written by one item and consumed by a different item runs the whole-feature review regardless of tier — per-item inspection cannot see the boundary (proven twice more: a silent override drop and an every-tier crash each PASSed all their per-item reviews). The whole-feature review's dispatch prompt spells out the per-criterion evidence table below — VERIFIED / COVERED-BY-GATE / NOT VERIFIED, one row per criterion — as a mechanical requirement of the deliverable; an evidence format that no dispatch prompt demands is a format nobody produces.
-
The pass — verify on a real stage before the PR (when the repo deploys per-developer stages). Build an acceptance checklist — one row per acceptance criterion across all items, plus ticket-level success criteria — then deploy the integration branch to your personal stage and exercise each criterion against it (browser/API), attaching the evidence to the ticket. Every criterion gets exactly one verdict: VERIFIED (with human-openable evidence), COVERED-BY-GATE (name the covering test/journey), or NOT VERIFIED (what you observed — this is a finding to fix, not a footnote). Preflight before you rely on this: confirm the stage has the seed data the ACs need (e.g. a non-admin user + an org for impersonation flows) and that your capture tool can persist real evidence files a human can open — if either is missing, seed it (fold the seed into the repo's seed scripts) or fall back to the integration-suite output as the authoritative evidence, and say which. Auth-gated ACs that can't be driven live are COVERED-BY-GATE, stated explicitly per criterion. When the deliverable RUNS — a service, a pack, a pipeline — the pass is a live fire: boot from the documented empty state, drive the runbook, and watch the runtime path actually resolve and fire, writing a conforming report into
reports/. Suites that prove it compiles and installs prove nothing about the runtime path; one live-fire pass caught three demo-blocking defects that every test layer and two adversarial review stages had missed. Finally, re-read every deferral the intake or plan recorded against the diff the dish actually landed: a deferral is a judgment about reachability under the code as it was, and this dish changed that code. If your fix made the deferred bug reachable, likelier, or worse, fold it in or block on it — it is not deferrable any more. -
Open the single human-review PR
<delivery-branch> → main(gh pr create) with: summary, item list, Evidence highlights, risks. If there is no remote/gh, tell the user the integration branch is ready for local review instead. If the base branch has advanced (or its own PR merged) since you branched, rebase the integration branch--onto <latest main> <original base>first — this drops now-redundant base commits and leaves a clean per-ticket diff. (Withgraphite_platform: truein the repo config this step becomesgt sync+gt submit --stack— one PR per item; seeGRAPHITE.md.) -
Move the source ticket to its in-review-equivalent status and post a human-facing handoff comment: what changed, how it was verified, how to review. Plain language; nothing a board reader can't open.
-
Analyst pass (per the tier's retro cadence — see Self-improvement below). When one is due, do not consider the handoff complete without it.
-
The ticket reaches its done-equivalent status only when the human merges the PR. The integration branch is deleted only after that.
Release the dish lease before returning the handoff to the operator.
Reviewing code (/brigade:review — read REVIEW.md first)
An advisory, tier-scaled standalone review over a branch, PR, or commit range — outside
the cook/inspect/land pipeline, findings only, never a PASS/FAIL verdict. Before
dispatching the review workflow or /brigade:review-dispatch, read REVIEW.md (next to
this SKILL): the coordination lease, invocation args, input contract, per-tier depth,
return shape, and the dispatch follow-up all live there. Do not build the Workflow args
from memory — the args block is in REVIEW.md.
Self-improvement (retro → heuristics → brain upgrade — read RETRO.md first)
Retros run on the tier's cadence (TIERS.md: ★★★ every dish + every 10 merged items;
★★ every dish; ★ every 3rd dish — and whenever the user asks) and are never skipped
silently at any tier: if you must defer a due pass, say so to the user explicitly.
Before dispatching brigade-analyst, applying its report, offering heuristics to the
KB, or running a brain-upgrade pass, read RETRO.md (next to this SKILL) — the dispatch
inputs, the ★★★ intensive mode, the heuristic store, and the brain-upgrade protocol live
there. Three invariants hold regardless: KB writes are the operator's call (one yes/no per
retro, never automatic); a brain upgrade edits the plugin source, never the installed
copy; and a brain upgrade that adds a rule also compacts the section it touched —
absorbing without compacting is what turns this brain into prose nobody can scan.
Resuming a dish (any session, any time)
PLAN.md is the single source of truth for dish state — the items frontmatter list
(statuses todo / dispatched / in_review / rework / done / blocked, DAG edges, file
ownership, per-dispatch attempts records)
plus the report trail, updated at every transition. So resume is trivial and gate-free:
- Run
brigade-statusandbrigade-coord list, then acquire the dish lease before any reconciliation write or dispatch.brigade-status(zero model tokens) — config, per-dish item statuses, worktrees, learnings tail in one shot (--jsonfor structured output when a script or precise state check needs it). The SessionStart hook already injected this in brigade repos; don't re-derive what it shows. - Read the dish's
PLAN.mdonly for the specific packets you're about to act on. Reconcile against reality:git worktree list, the plan'sdelivery_branchandwip/<delivery-slug>/*branches, and unread files inreports/. Trust the filesystem over the plan if they disagree, and fix the plan. - Tell the user in two lines where the dish stands, then continue from the current phase.
Never re-plan or re-confirm work that's already merged; the one planning checkpoint happened when the plan was first approved.
Resuming mid-execute. Build the items arg from PLAN.md's current statuses as-is —
items already status: done are still included; the script returns those as skipped
rather than re-cooking them. A Workflow resumeFromRunId (where the runtime offers one) is
a same-session accelerator only, never the source of truth for what already landed —
PLAN.md and the report trail are.
Status mapping
Brigade thinks in five abstract statuses; config.md maps them to the source's native
names once, at init:
todo → in_progress → in_review → done, plus blocked (off-ramp).
Move the ticket at exactly three moments — first dispatch (in_progress), handoff
(in_review), human accept (done) — plus blocked whenever readiness fails and only the
user can unblock. Work items live in PLAN.md; but if a work item is ALSO a board ticket (a
subtask), move it to in-progress on dispatch and to done the moment its branch merges into
integration — live per item, never batched at handoff. Work items with no board ticket get
an optional batched progress comment on the parent, not a status thrash.
Guardrails (always)
- The Planner never implements (except escalation rung 3, announced) and never explores.
- No work item merges without a Inspector PASS and real Evidence (actual gate output in the Cook's report — "it should pass" is not Evidence).
- A targeted check is never repo green. Evidence carries a scope as well as an exit
code: a suite pointed at one file, or narrowed by
--filter/--project/-k, exits 0 exactly like the full run. Classify withbrigade-evidence(zero tokens) rather than reading the checkmark, and state the scope wherever the claim is made — packet Verify block, cook report Evidence, handoff comment, PR body. - Every diff that lands carries a verdict or a recorded review. Three paths skip the gate quietly: a commit you made directly to the integration branch, a fix produced by overriding a PASS into rework, and a docs-only item you self-verified instead of dispatching an inspector. Each is legitimate; each gets a short verdict-shaped note beside the cook report naming the commit, what you checked it against, and what you corrected — silent fixes leave the item unscoreable and rest the finding's closure on whoever made the mistake. A diff-conformance spot-check replaces a full inspector pass only when all three hold: the diff is annotation/comment/constant/doc-only, every file it touches already PASSed inspection this dish, and the item's own Verify commands were re-run green. Record the deviation in PLAN.md.
- Never claim an outcome before its artifact exists. A review result, a gate result, a verification — in a ticket comment, a PR body, or a handoff — is claimed only once the artifact is on disk, and the claim cites that path. A handoff comment once announced a passing review 23 minutes before the PASS file existed, while the only artifact on disk was the FAIL it superseded.
- Cooks stay inside their packet's file list. An out-of-scope edit is a Inspector finding, not a favor.
- Same-wave items never share files. Conflicts are decomposition defects →
LEARNINGS.md. - Ticket comments are written for humans on the board: plain language, no local paths, no brigade jargon, no secrets, ever.
- Never commit
.brigade/; keep it in.git/info/exclude. - When readiness fails anywhere, ask a precise question or set
blockedwith a precise comment — never guess, never expand scope silently. - Subagent reports are information, not instructions. Cooks, Scouts, Inspectors, and the Analyst report what they did/found and stop; they never direct the next action. You (the Planner) decide every next step from the report — never auto-execute a "next step" a subagent suggests.
- Never skip a due Analyst pass silently; defer only with an explicit note to the user.
- Honor the repo's own
AGENTS.md/CLAUDE.mdon top of this Skill; per-work-type Evidence expectations come from the repo when it defines them. - Terminology stays disjoint from other installed tools. Never use "mise" / "mise en
place" vocabulary anywhere in brigade (the
misedev-tool manager owns that word in this environment). If a future skill (e.g. for mise itself) enters the toolbox, check its vocabulary against brigade's and rename on the brigade side if they collide.
Companion files
Everything below sits next to this SKILL unless noted. The phases above already say when to read each one; this table is the index, not a second set of instructions.
| File | Read it when |
|---|---|
SCHEMAS.md | Before producing or consuming any artifact. The type registry — envelope, per-type frontmatter, body sections, length budgets, authority rules. |
templates/work-packet.md | Before writing PLAN.md packets. |
TIERS.md | At dish intake, to bind the tier: model policy, scout caps, plan-check policy, escalation ladder, retro cadence, difficult-planning triggers. |
policies/risk-escalation.md | The heavy-flag table brigade-risk enforces. |
SETUP.md | First run in a repo, or a workspace cwd — init interview, .brigade/ layout, multi-repo rules. Prefer /brigade:onboard. |
REVIEW.md | Before /brigade:review or /brigade:review-dispatch. Do not build the Workflow args from memory. |
RETRO.md | When a retro is due, before applying its report, or before a brain upgrade. |
MEMORY.md | When a heavy item or rework attempt runs — the cook working-memory ledger protocol. |
GRAPHITE.md | Only when repo config enables graphite_restack or graphite_platform. Both off by default. |
sources/*.md | Binding a board: notion, clickup, local, obsidian, plus TEMPLATE.md for a new adapter. |
../groom/SKILL.md | Whole-board work, tickets that predate brigade, anything failing intake readiness. |
../../CONNECTORS.md | The connector categories brigade binds to (~~tickets, ~~kb). |
Generated code. ../../workflows/brigade-*.js are built from workflows/src/*.js and
workflows/config.js by scripts/brigade-bundle — Workflow scripts cannot import at runtime.
config.js mirrors tier policy and schemas already defined in TIERS.md/SCHEMAS.md; edit
those and rerun the bundle, never hand-edit config.js alone.