design-council-orchestration

# Design Council Orchestration > Skill by [ara.so](https://ara.so) — Design Skills collection. ## Overview Design Council is a Claude Code plugin that spawns 11+ independent Claude agents in parallel, each with a specialized role (principal-engineer, security-engineer, product-manager, etc.), to debate cross-cutting technical decisions. The invoking Claude acts as CEO, orchestrating the debate and writing binding decisions. Unlike single-context reviews, each seat runs in its own context with no shared history. Disagreement is structural, not simulated. Seats argue via direct peer DMs (`SendMessage`), not sequential turns through the CEO. **Key difference from other patterns**: This isn't prompt engineering within one context — it's multi-agent orchestration with genuine parallelism and independent reasoning. ## Installation ```bash # Add the plugin marketplace /plugin marketplace add sjsyrek/claude-plugins # Install design-council /plugin install design-council@sjsyrek ``` To pin a specific version: ```bash git clone https://github.com/sjsyrek/design-council.git cd design-council git checkout v0.2.0 /plugin marketplace add . /plugin install design-council@sjsyrek ``` ## When to Use **Invoke when BOTH conditions hold:** 1. Decision crosses **≥2 specialist domains** (e.g., security + performance + UX) 2. Output must **survive handoff** (decision log, tracker items, execution plan) **Natural trigger phrases:** - "Convene the council to review this API design" - "Get the design council together for this architecture" - "Council debate: pagination strategy for this endpoint" - "Run a design review on the caching layer" **Do NOT invoke for:** - Simple bug fixes (single domain) - Library/tool selection (→ use direct research) - Pure exploration without deliverable - Questions answerable by one specialist **Token economics**: Expect 10–20× the cost of single-context review. The council earns its cost on decisions that would otherwise ship with blind spots. ## Execution Phases ### Phase 0: Plan Card (Pre-Flight) Before any agents spawn, the CEO shows a confirmation card: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ DESIGN COUNCIL PLAN Mode: DEBATE Roster (8 seats): • principal-engineer [opus] • platform-engineer [sonnet] • security-engineer [sonnet] • test-engineer [sonnet] • performance-engineer [sonnet] • product-manager [opus] • technical-writer [opus] • qa-engineer [sonnet] Budget: ~180k tokens (cached brief saves ~9k × 8) ~4–7 min wall-clock (3 debate rounds) Opening prompt: "Should the /search endpoint paginate with cursor tokens or offset/limit?" Reply: go | swap X for Y | drop X | add X | abort ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` **You control the roster here:** ```bash # Accept as-is go # Swap models swap principal-engineer for sonnet # Add a seat add domain-expert # Remove a seat drop ui-ux-designer # Cancel abort ``` ### Phase 1: Brief Assembly The CEO gathers constraints **once** into `~/.claude/councils/<slug>/brief.md`: - `CLAUDE.md` constraints - Referenced specs / ADRs - Project memory (including beads if detected) - **Skill self-audit**: greps auto-memory for entries about design-council itself — memory wins over skill text (real failures > documentation) Every seat's spawn prompt points to this path → **prompt cache hits across all spawns** (~7–12k tokens saved per 8-seat council). ### Phase 2: Parallel Spawn CEO spawns all seats in **one multi-tool-call message**: ```typescript // Conceptual — the CEO does this automatically await Promise.all([ Agent({ name: "principal-engineer", run_in_background: true, team_name: "design-council-2026-05-17-pagination", model: "claude-opus-4", prompt: `You are the principal-engineer seat. Brief: file://~/.claude/councils/pagination/brief.md Four delivery rules: 1. Handshake: DM "READY: principal-engineer" within 10s 2. Cross-talk: SendMessage only (never Execute) 3. Final verdict: via SendMessage to CEO 4. Idle summary: <100 chars Opening question: Should /search paginate cursor or offset?` }), Agent({ name: "security-engineer", ... }), Agent({ name: "platform-engineer", ... }), // ... 5 more ]); ``` ### Phase 2.5: Handshake Verify CEO counts incoming `READY: <seat-name>` DMs, checks for empty `tmuxPaneId`s (silent spawn failures), remediates, and emits: ``` HANDSHAKE: 8/8 ok | verdict=PROCEED ``` If any seat fails to spawn: - CEO attempts one re-spawn - On second failure: drops seat, logs it, proceeds with reduced roster ### Phase 3: Opening Verdicts Each seat posts its opening verdict via `SendMessage` to CEO: ``` From: security-engineer To: CEO CONCERNS Offset pagination leaks record counts (DoS vector). Cursor tokens must be HMAC-signed with rotation. Need rate-limit strategy regardless of choice. ``` Verdicts: - `APPROVE` — no blocking concerns - `CONCERNS` — issues that need resolution - `BLOCK` — showstopper (requires CEO arbitration or escalation) ### Phase 4: Cross-Talk (Peer DMs) **Review mode**: skips cross-talk by default (seats → CEO only). **Debate mode**: CEO routes disagreements to direct seat-to-seat DMs: ```typescript // CEO orchestration (automatic) if (security.verdict === "CONCERNS" && platform.verdict === "APPROVE") { SendMessage({ from: "CEO", to: "security-engineer", text: "DM platform-engineer: they approved offset. Argue your HMAC requirement." }); SendMessage({ from: "CEO", to: "platform-engineer", text: "security-engineer has concerns about offset. Respond to their HMAC point." }); } ``` Seats then argue directly: ``` From: security-engineer To: platform-engineer Your offset approval ignores enumeration risk. Without signed cursors, scrapers can walk the entire dataset. Do you have a mitigation? ``` ``` From: platform-engineer To: security-engineer Rate limiting is orthogonal to pagination style. Offset + jittered delays caps enumeration to same ROC as cursor. Offset is simpler to cache. ``` **Hard cap: 3 rounds.** CEO forces convergence or arbitration. ### Phase 5: Arbitration + Decision Log For unresolved disagreements, CEO writes **binding decisions** (3–5 sentences engaging both sides): ```markdown ## Decision: Cursor pagination with signed tokens security-engineer's enumeration concern is valid and not fully mitigated by rate limiting (jitter still allows sequential walks). platform-engineer's caching argument applies to both schemes via `cache_token` param. **Adopt cursor pagination with HMAC-SHA256 signed tokens (rotate key daily).** Deferred: Rate limit strategy (filed as BEAD-127). ``` **Escalations** (to user): - Strategic tradeoffs (e.g., "ship fast vs. correct") - Budget / resourcing - Legal / compliance - Cross-team dependencies CEO emits draft log to chat: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ DECISION LOG (DRAFT) Reply: save | amend "<changes>" | discard ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` ### Phase 6: Persist + Teardown On `save`: ```bash # Decision log ~/.claude/councils/2026-05-17-pagination/log.md # Structure --- slug: pagination date: 2026-05-17 mode: DEBATE roster: [principal-engineer, security-engineer, ...] primary-tracker-id: BEAD-126 # if beads detected linked-tracker-ids: [BEAD-127] status: resolved --- # Opening Prompt Should /search paginate cursor or offset? # Resolved Disagreements ... # Arbitration Decisions ... # Execution Plan File ownership: - src/api/search.ts → platform-engineer context - src/auth/tokens.ts → security-engineer context - tests/api/search.test.ts → test-engineer context ``` CEO then: - Broadcasts shutdown via `SendMessage` - Calls `TeamDelete` (removes shared task list) - Cleans up Brief artifact ## Roster Configuration ### Default 11 Seats (Dynamic Sizing) ```yaml core: - principal-engineer # Architecture synthesis (opus) - platform-engineer # Infra / deployment (sonnet) - integration-engineer # API contracts / compat (sonnet) - test-engineer # Test strategy (sonnet) - qa-engineer # Quality gates (sonnet) - security-engineer # Threat model (sonnet) - performance-engineer # Latency / throughput (sonnet) - product-manager # User impact / scope (opus) - ui-ux-designer # Interface / flows (sonnet) - accessibility-specialist # A11y / WCAG (sonnet) - technical-writer # Docs / clarity (opus) opt-ins: - devops-engineer # CI/CD / observability - finops-engineer # Cloud cost / budget - legal-compliance # GDPR / SOC2 / licensing - domain-expert # Named SME (you provide context) - historian # Past decisions / ADRs ``` **Automatic pruning** (Phase 0): - No UI → drop `ui-ux-designer`, `accessibility-specialist` - Internal tool → drop `security-engineer`, `platform-engineer` - Pure backend → drop `ui-ux-designer` **Adding seats in plan card**: ```bash # Add domain expert add domain-expert # CEO will prompt you for context: # "What domain? Provide 2–3 sentence brief." ``` ### Model Assignment **Default strategy**: - **Opus**: synthesis-heavy (`principal-engineer`, `product-manager`, `technical-writer`, `historian`) - **Sonnet**: analytical (`test-engineer`, `performance-engineer`, `security-engineer`) **Override triggers**: - "High quality bar" → all Opus - "Ship to production" → all Opus - Plan card manual swap: `swap security-engineer for opus` ## Beads Integration (Tracker System) When [beads](https://github.com/gastownhall/beads) is detected (`.beads/` exists OR `bd` on `$PATH`): **Phase 1 (Brief)**: ```bash # CEO runs automatically bd memories # → brief.md bd ready # → brief.md (active context) bd show <id> # → brief.md (if user referenced a bead) ``` **Phase 4 (Defer)**: ```bash # CEO translates DEFER decisions to tracker items bd create \ --title "Implement rate limiting for /search" \ --type task \ --parent BEAD-126 \ --context "From design-council-2026-05-17-pagination: security-engineer raised enumeration concern" ``` **Phase 6 (Teardown)**: ```bash # Close primary bead under debate bd close BEAD-126 --force # if dependency inversion flagged # Log tracker IDs in frontmatter primary-tracker-id: BEAD-126 linked-tracker-ids: [BEAD-127, BEAD-128] ``` **Without beads**: deferred items remain prose in decision log. Protocol is strictly additive. ## Advanced Patterns ### Stop Early ```bash # At any phase stop the council ``` CEO broadcasts shutdown, saves partial log with `status: halted`, cleans up. ### Review Mode (No Cross-Talk) ```bash # User invocation "Council review of PR #47 (no debate)" ``` CEO skips Phase 4 cross-talk. Seats → CEO verdict only. Faster, cheaper, good for conformance checks. ### Implementation Handoff After decision log saves, spawn **execution agents** with `isolation: "worktree"`: ```typescript // CEO provides this in execution plan await Agent({ name: "implement-cursor-pagination", isolation: "worktree", model: "claude-sonnet-4", prompt: `Implement cursor pagination per design-council-2026-05-17-pagination. Decision log: file://~/.claude/councils/2026-05-17-pagination/log.md File ownership (avoid conflicts): - src/api/search.ts (yours) - tests/api/search.test.ts (yours) DO NOT TOUCH: - src/auth/tokens.ts (security-engineer's impl) Brief: file://~/.claude/councils/pagination/brief.md` }); ``` Worktree isolation prevents merge conflicts. See `references/implementation-handoff.md` in the plugin source for full playbook. ### Memory Self-Audit Pattern **Why it matters**: If you've used design-council before and hit a failure (e.g., "security seat always blocks on offset pagination"), that failure lands in auto-memory. Phase 1 greps for `design-council` memories and **overrides skill text** with ground truth. Example: ```markdown # In auto-memory 2026-05-10: design-council: security-engineer seat over-indexes on HMAC signatures. For internal APIs, skip security seat unless user data is involved. ``` Phase 1 brief will now include: ``` MEMORY OVERRIDE (from 2026-05-10): Skip security-engineer for internal APIs unless user data involved. Prior councils over-rotated on HMAC signatures. ``` This is automatic. Memory always wins. ## Observability (Split-Pane Mode) **Tmux / iTerm2**: Each seat renders in its own pane. Watch debates live. ```json // settings.json (Claude Code) { "teammateMode": "auto" // or "tmux" to force } ``` **Without split-pane terminal**: Seats share main pane. Cycle with Shift+Down. This is a Claude Code harness feature, not plugin-required. ## Common Issues ### Silent Spawn Failures **Symptom**: Phase 2.5 reports `HANDSHAKE: 6/8 ok | verdict=DEGRADED` **Cause**: `TeamCreate` + `Agent` race on shared task list initialization. **Remediation** (automatic): 1. CEO retries failed seats once 2. On second failure: drops seat, logs it, proceeds **User action**: Check `~/.claude/councils/<slug>/log.md` for `degraded-roster: [security-engineer]`. If critical seat dropped, re-run with `add security-engineer`. ### Token Budget Overrun **Symptom**: Debate stalls mid-round, costs spike. **Cause**: Deep research by one seat (e.g., `performance-engineer` running benchmarks). **Fix**: