design-council

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

0. 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.
1. 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).
2. 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).
3. 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.
4. 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.
5. 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.
6. 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