Design Council
Convene a parallel team of specialist Claude agents with independent contexts — they argue your call, partition the work, and ship it.
What problem it solves
A single context, no matter how capable, evaluates a cross-cutting design decision from one vantage point. "Should this API paginate cursor-style or offset-style?" touches integration, performance, security, docs, and product — and the answer you get depends on which hat you happened to be wearing when asked. Iterating with the same context doesn't fix this: each turn inherits the prior framing.
Design Council spawns each seat as an independent Claude agent with its own context. They don't inherit yours. The security-engineer has no cached rationale for the principal-engineer's architecture; the accessibility-specialist doesn't share the performance-engineer's priors about batching. Disagreement is structural, not simulated. The CEO's job is to route the disagreement productively and write the decision down.
How it works
- Plan card (you confirm before anything spawns). The CEO shows a one-screen card: mode (debate / review), roster with per-seat model, rough token/wall-clock budget, and the drafted opening question. You reply
go, swap X for Y, drop X, add X, or abort.
- Brief (single context, yours). The CEO gathers binding constraints from
CLAUDE.md, referenced specs, and the project's memory system (including beads if detected). Skill self-audit runs here too: the CEO greps auto-memory and prior decision logs for entries about the council skill itself; any memory that contradicts the skill's own prescriptions wins (memory is written after real failures, so it's ground truth). Everything lands once in ~/.claude/councils/<slug>/brief.md — every seat's spawn prompt points to that path, so prompt caching hits across parallel spawns (~7–12k tokens saved per 8-seat council).
- Convene (parallel fan-out). In one multi-tool-call message, the CEO spawns every seat via
TeamCreate + Agent(... run_in_background: true, team_name: ...). Every spawn prompt inlines the four delivery rules (handshake, SendMessage-only, final-via-SendMessage, idle-summary-short).
- Handshake verify (Phase 2.5). The CEO counts incoming handshake DMs, inspects team config for empty
tmuxPaneIds, remediates silent-spawn failures, and emits a structured HANDSHAKE: N/N ok | verdict=PROCEED line.
- Cross-talk (peer DMs, bounded). Seats post opening verdicts (
APPROVE / CONCERNS / BLOCK), then DM each other directly via SendMessage to argue the live disagreements. The CEO routes — pairs disagreers, invites tiebreakers, forces narrowing questions, bridges converged tracks. Hard cap of 3 rounds. Review mode skips cross-talk by default.
- Arbitrate (CEO writes). For every disagreement cross-talk didn't resolve, the CEO writes a 3–5 sentence decision with rationale engaging the loser's argument. Strategic / budget / legal / cross-team calls escalate to the user.
- Log + teardown. The CEO posts the draft decision log to chat for your
save / amend / discard. On save: ~/.claude/councils/<yyyy-mm-dd>-<slug>/log.md (outside any project repo). Includes opening prompt, roster, resolved disagreements, arbitration decisions, deferred items with tracker IDs, and an execution plan with file-ownership mapping. Team shuts down via shutdown_request; TeamDelete removes the shared task list.
Stop early at any phase by saying "stop the council" — the CEO broadcasts shutdown, saves a partial log with status: halted, and cleans up.
Benefits
- Genuine parallelism. Independent contexts reasoning concurrently, not sequential turns. Wall-clock cost ≈ slowest seat, not sum of seats.
- Structurally independent perspectives. Each seat is a separate Claude with its own context — no priming bleeds across roles.
- Direct peer debate.
SendMessage lets seats argue with each other without round-tripping through the CEO, which is how real cross-discipline reviews work.
- Cheap fan-out via prompt cache. The shared
brief.md pattern means identical constraints hit the 5-minute prompt cache across every spawn, recovering meaningful tokens on constraint-heavy projects.
- Durable artifact outside any repo. Decision logs are portable — they outlive branch pivots, repo renames, and migrations.
~/.claude/councils/ is per-user artifact space.
- Merge-conflict-aware execution plan. Phase 5 closes with file-ownership mapping so parallel implementers — spawned as fresh agents with
isolation: "worktree" after teardown — can ship the decision without colliding. See references/implementation-handoff.md for the full playbook (including why git checkout <SHA> -- <files> beats cherry-pick for mixed-base handoffs).
Tradeoffs