sjsyrek/design-council

README preview

# 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 `tmuxPaneId`s, 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.

View full repository on GitHub →