sjsyrek/design-council

README preview

# Design Council

> A Claude Code plugin that convenes 11 role-specialized peer agents to debate a non-trivial technical decision in real time. The invoking Claude acts as CEO — convening, routing peer DMs, arbitrating deadlocks, and persisting a one-page decision log.

## 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

1. **Brief (single context, yours).** You describe the decision. The CEO gathers binding constraints from `CLAUDE.md`, referenced specs, and the project's memory system (including beads, if detected — see Integrations below). It drafts an opening prompt and picks which opt-in seats to add.
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: ...)`. Each seat receives its role brief, the binding constraints, and the opening prompt — then runs in its own context.
3. **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 observes via idle notifications and routes: pairs disagreers, invites tiebreakers, forces narrowing questions. Hard cap of 3 rounds.
4. **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.
5. **Log + teardown.** One-page decision log at `~/.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 for parallel implementers. Team shuts down via `shutdown_request`; `TeamDelete` removes the shared task list.

## Benefits

View full repository on GitHub →