/design-council
Use when the user says "convene the council", "design debate", "council review", "get the team together", "run a design review", or "debate this design"; OR describes a cross-domain decision or review with real stakes — architecture pivot, API surface, pre-release hardening,
$ npx -y skills add sjsyrek/design-council --skill design-council --agent claude-codeHow it fires
How this skill gets triggered: by you, by Claude, or both.
- Fires itselfAuto-invocation. Claude auto-loads it when your prompt matches the work.Auto-invocation is when the right skill fires by itself at the right moment, driven by a FLOW.md router and a hook, instead of you invoking it by name. It is the difference between a skill being installed and a skill actually getting used.Read the full definition →
- You can call itInvoke it directly when you want it.
- Slash command
/design-council
Context preview
The summary Claude sees to decide when to auto-load this skill.
Use when the user says "convene the council", "design debate", "council review", "get the team together", "run a design review", or "debate this design"; OR describes a cross-domain decision or review with real stakes — architecture pivot, API surface, pre-release hardening,
SKILL.md
design-council.SKILL.mdname: design-council
description: Use when the user says "convene the council", "design debate", "council review", "get the team together", "run a design review", or "debate this design"; OR describes a cross-domain decision or review with real stakes — architecture pivot, API surface, pre-release hardening, codebase-wide audit. Convenes parallel role-specialized agents (default Opus) who debate in real time via inter-agent messaging while the invoking Claude serves as CEO. Do NOT invoke for single-specialist questions, bug fixes, or quick library picks.
version: 0.4.1
design-council
Convene a **parallel team of role-specialized agents** to debate a non-trivial technical decision (or audit a codebase in Review mode) in real time. The invoking Claude is **CEO**: convenes, routes peer-DMs, arbitrates deadlocks, writes a one-page decision log. Every teammate has its own context — not a subagent inheriting yours — so disagreement is structural, not simulated.
What the user sees
1. **Plan card.** Before any seat spawns, the CEO shows a one-screen card: mode, roster, per-seat model, rough token/wall-clock budget, drafted opening question. You reply `go`, `swap X for Y`, `drop X`, `add X`, or `abort`. 2. **Handshake status.** After spawn, the CEO emits one line — e.g. `HANDSHAKE: 8/8 ok | verdict=PROCEED` — so you know every seat actually started. 3. **Cross-talk.** Seats post opening verdicts, DM each other to debate, CEO routes deadlocks. Bounded: 3 rounds max. 4. **Log preview.** Before saving, the CEO posts the draft decision log to chat. Reply `save`, `amend <note>`, or `discard`. 5. **Output.** One-page decision log at `~/.claude/councils/<yyyy-mm-dd>-<slug>/log.md` (outside any repo). 6. **Stop early.** Say "stop the council" at any phase — CEO broadcasts shutdown, saves a `status: halted` partial log, cleans up.
Invocation: `/design-council:design-council [decision-or-focus]` or any of the trigger phrases below.
When to invoke
Both conditions must hold: (a) decision or review crosses **≥2 specialist domains**, and (b) output must **survive handoff** — a decision log, tracker items, or an execution plan. Natural triggers: "convene the council", "design debate", "council review", "run a design review", "debate this design", "get the team together".
Do **NOT** invoke for: bug fixes, single-specialist questions, library/tool picks, pure exploration (→ `Explore`), one-turn sanity checks.
Default roster (size matches decision shape)
| # | Slug | Owns | |---|------|------| | 1 | `principal-engineer` | Architecture, module boundaries, simplicity (opens the debate) | | 2 | `platform-engineer` | Systems, infra, data shape, operational cost, observability | | 3 | `integration-engineer` | Downstream consumers, third-party developers, backwards compat | | 4 | `test-engineer` | TDD, mutation ritual, coverage, assertion hygiene | | 5 | `qa-engineer` | User flows ↔ spec alignment, regression surface, manual test plan | | 6 | `security-engineer` | Input validation, secrets, path safety, error sanitization | | 7 | `performance-engineer` | Batching, memory, concurrency, measurement-before-optimization | | 8 | `product-manager` | UX alignment, product coherence, best-practice conformance | | 9 | `ui-ux-designer` | Ergonomics, visual consistency, interaction design | | 10 | `accessibility-specialist` | a11y, keyboard nav, screen reader, contrast | | 11 | `technical-writer` | Docs, in-app help, CHANGELOG, API reference |
**Opt-ins:** `devops-engineer` (deploy risk, CI/CD, rollback), `sre-engineer` (production reliability, SLOs, blast radius, rollback validation; pair with `devops-engineer` when production stakes are high), `finops-engineer` (cloud/API cost, unit economics, resource lifecycle), `legal-compliance` (privacy, licensing), `domain-expert` (subject-matter SME), `historian` (codebase precedent on mature repos).
**Dynamic sizing is the default, not an exception.** No runtime UI → drop ui-ux + a11y. No user input / no infra → drop security + platform. Internal-tooling defaults can be 4–6 seats. Full 11+opt-ins only when every role-lens applies. The CEO decides at Phase 0 and surfaces the roster in the plan card.
Model choice (state it, don't default quietly)
Default: **Opus for synthesis-heavy seats** (principal-engineer, product-manager, technical-writer, historian) and **Sonnet for analytical seats** (test, performance, platform, qa). Override all → Opus on a high-quality-bar framing. The plan card shows which seats got which model; users can adjust before spawn.
Variants
- **Debate mode** (default) — single decision, verdict tags (APPROVE / CONCERNS / BLOCK), peer DMs resolve disagreements, CEO arbitrates what's left.
- **Review mode** — codebase audit, P0/P1 findings, cross-talk skipped, CEO dedupes and files tracker items. See `references/review-mode.md`.
Protocol (six phases)
| Phase | Name | CEO does | |-------|------|----------| | 0 | **Plan card** | Draft roster + models + budget + opening question; show to user; wait for `go` | | 1 | **Brief** | Gather binding constraints verbatim (CLAUDE.md, spec, memory, tracker); **self-audit** — grep auto-memory + prior decision logs for entries about the council skill; flag any memory-vs-skill contradiction and follow memory; write everything to `~/.claude/councils/<slug>/brief.md` once; draft opening prompt | | 2 | **Convene** | `TeamCreate` + parallel `Agent` spawns in **one multi-tool-call message**; every spawn prompt points to `brief.md` (prompt-cache hits across seats) | | 2.5 | **Handshake verify** | Count incoming handshake DMs; inspect team config for empty `tmuxPaneId`; remediate or drop silent-spawn failures; emit `HANDSHAKE: N/N ok` line | | 3 | **Cross-talk** | Route peer DMs, ask narrowing questions, bridge converged tracks; **3-round hard cap**. Skipped by default in Review mode. | | 4 | **Arbitrate** | Write decision + rationale for every unresolved disagreement. Escalate strategic/legal/budg
Read more
name: design-council description: Use when the user says "convene the council", "design debate", "council review", "get the team together", "run a design review", or "debate this design"; OR describes a cross-domain decision or review with real stakes — architecture pivot, API surface, pre-release hardening, codebase-wide audit. Convenes parallel role-specialized agents (default Opus) who debate in real time via inter-agent messaging while the invoking Claude serves as CEO. Do NOT invoke for single-specialist questions, bug fixes, or quick library picks. version: 0.4.1
design-council
Convene a **parallel team of role-specialized agents** to debate a non-trivial technical decision (or audit a codebase in Review mode) in real time. The invoking Claude is **CEO**: convenes, routes peer-DMs, arbitrates deadlocks, writes a one-page decision log. Every teammate has its own context — not a subagent inheriting yours — so disagreement is structural, not simulated.
What the user sees
1. **Plan card.** Before any seat spawns, the CEO shows a one-screen card: mode, roster, per-seat model, rough token/wall-clock budget, drafted opening question. You reply `go`, `swap X for Y`, `drop X`, `add X`, or `abort`. 2. **Handshake status.** After spawn, the CEO emits one line — e.g. `HANDSHAKE: 8/8 ok | verdict=PROCEED` — so you know every seat actually started. 3. **Cross-talk.** Seats post opening verdicts, DM each other to debate, CEO routes deadlocks. Bounded: 3 rounds max. 4. **Log preview.** Before saving, the CEO posts the draft decision log to chat. Reply `save`, `amend <note>`, or `discard`. 5. **Output.** One-page decision log at `~/.claude/councils/<yyyy-mm-dd>-<slug>/log.md` (outside any repo). 6. **Stop early.** Say "stop the council" at any phase — CEO broadcasts shutdown, saves a `status: halted` partial log, cleans up.
Invocation: `/design-council:design-council [decision-or-focus]` or any of the trigger phrases below.
When to invoke
Both conditions must hold: (a) decision or review crosses **≥2 specialist domains**, and (b) output must **survive handoff** — a decision log, tracker items, or an execution plan. Natural triggers: "convene the council", "design debate", "council review", "run a design review", "debate this design", "get the team together".
Do **NOT** invoke for: bug fixes, single-specialist questions, library/tool picks, pure exploration (→ `Explore`), one-turn sanity checks.
Default roster (size matches decision shape)
| # | Slug | Owns | |---|------|------| | 1 | `principal-engineer` | Architecture, module boundaries, simplicity (opens the debate) | | 2 | `platform-engineer` | Systems, infra, data shape, operational cost, observability | | 3 | `integration-engineer` | Downstream consumers, third-party developers, backwards compat | | 4 | `test-engineer` | TDD, mutation ritual, coverage, assertion hygiene | | 5 | `qa-engineer` | User flows ↔ spec alignment, regression surface, manual test plan | | 6 | `security-engineer` | Input validation, secrets, path safety, error sanitization | | 7 | `performance-engineer` | Batching, memory, concurrency, measurement-before-optimization | | 8 | `product-manager` | UX alignment, product coherence, best-practice conformance | | 9 | `ui-ux-designer` | Ergonomics, visual consistency, interaction design | | 10 | `accessibility-specialist` | a11y, keyboard nav, screen reader, contrast | | 11 | `technical-writer` | Docs, in-app help, CHANGELOG, API reference |
**Opt-ins:** `devops-engineer` (deploy risk, CI/CD, rollback), `sre-engineer` (production reliability, SLOs, blast radius, rollback validation; pair with `devops-engineer` when production stakes are high), `finops-engineer` (cloud/API cost, unit economics, resource lifecycle), `legal-compliance` (privacy, licensing), `domain-expert` (subject-matter SME), `historian` (codebase precedent on mature repos).
**Dynamic sizing is the default, not an exception.** No runtime UI → drop ui-ux + a11y. No user input / no infra → drop security + platform. Internal-tooling defaults can be 4–6 seats. Full 11+opt-ins only when every role-lens applies. The CEO decides at Phase 0 and surfaces the roster in the plan card.
Model choice (state it, don't default quietly)
Default: **Opus for synthesis-heavy seats** (principal-engineer, product-manager, technical-writer, historian) and **Sonnet for analytical seats** (test, performance, platform, qa). Override all → Opus on a high-quality-bar framing. The plan card shows which seats got which model; users can adjust before spawn.
Variants
- **Debate mode** (default) — single decision, verdict tags (APPROVE / CONCERNS / BLOCK), peer DMs resolve disagreements, CEO arbitrates what's left.
- **Review mode** — codebase audit, P0/P1 findings, cross-talk skipped, CEO dedupes and files tracker items. See `references/review-mode.md`.
Protocol (six phases)
| Phase | Name | CEO does | |-------|------|----------| | 0 | **Plan card** | Draft roster + models + budget + opening question; show to user; wait for `go` | | 1 | **Brief** | Gather binding constraints verbatim (CLAUDE.md, spec, memory, tracker); **self-audit** — grep auto-memory + prior decision logs for entries about the council skill; flag any memory-vs-skill contradiction and follow memory; write everything to `~/.claude/councils/<slug>/brief.md` once; draft opening prompt | | 2 | **Convene** | `TeamCreate` + parallel `Agent` spawns in **one multi-tool-call message**; every spawn prompt points to `brief.md` (prompt-cache hits across seats) | | 2.5 | **Handshake verify** | Count incoming handshake DMs; inspect team config for empty `tmuxPaneId`; remediate or drop silent-spawn failures; emit `HANDSHAKE: N/N ok` line | | 3 | **Cross-talk** | Route peer DMs, ask narrowing questions, bridge converged tracks; **3-round hard cap**. Skipped by default in Review mode. | | 4 | **Arbitrate** | Write decision + rationale for every unresolved disagreement. Escalate strategic/legal/budg
Convene a parallel team of specialist Claude agents with independent contexts — they argue your call, partition the work, and ship it.