Council System — Câmara de Deliberação Multi-Agente
colingoonth/council-system
Deliberação estruturada de 54 agentes para decisões arquiteturais críticas
Ver no GitHubUm sistema de 54 agentes especializados que deliberam sobre decisões arquiteturais complexas em 8 fases estruturadas, gerando um veredito rastreado com dissensões registradas. Funciona como uma câmara de debate integrada ao Claude Code — apenas decide, nunca executa.
Instalação
npx convez-ai colingoonth/council-system1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Resolver impasses arquiteturais com múltiplas abordagens defensáveis
- Documentar decisões técnicas complexas com rastreamento de dissensões
- Validar escolhas estruturais de alto custo antes da execução
Veredito

Sistema robusto para times que precisam de decisões auditáveis em projetos de longa duração, mas deliberadamente overkill para a maioria dos cenários. Excelente para documentar o *porquê* das escolhas arquiteturais, não para substituir julgamento rápido.
README
A tradução para o português deste README ainda está na fila.
The Council
A standing, multi-agent deliberation body for Claude Code. When you hit a genuinely contested design decision — two or more defensible approaches, and picking wrong costs you weeks — you convene a council of 54 specialized subagents that argue it out across eight structured phases and hand you back a reasoned verdict with recorded dissents. It decides, it never executes.
Think of it as a debate chamber bolted onto Claude Code: proposers build the strongest case for each approach, a devil's advocate and a premortem-runner try to kill them, domain specialists stress-test the survivor, and an arbiter reads the whole transcript and calls it — rewarding the proposers who updated their position over the ones who entrenched.
The single most important rule: the default verdict is always SOLO. The council is expensive and deliberately rare. The gatekeeper (main Claude) runs a triage rubric first and convenes the full body only when the question clears a high bar. Most questions should never reach the council at all.
Table of contents
- Is this for you?
- The core idea in 60 seconds
- How a session flows
- The 54 seats at a glance
- Install
- Your first council
- Repository layout
- Customizing it for yourself
- Cost
- Requirements
- Full documentation index
- Credits & license
Is this for you?
This system was built by someone who uses subagents heavily and wanted a repeatable, auditable way to make high-stakes architecture calls instead of one-shotting them. It's a good fit if you:
- run Claude Code and are comfortable with custom subagents and skills,
- work on long-lived projects where a wrong structural decision compounds,
- want decisions recorded (with dissents) so future-you knows why.
It's overkill for: quick edits, single-file changes, questions answerable by one read, or anything an existing skill already handles. The system itself will tell you so — that's what the triage gate is for.
The core idea in 60 seconds
You ask a hard question
│
▼
┌───────────────────┐ most questions stop here
│ TRIAGE (gate) │──────────────► VERDICT: SOLO → you just do it
│ run by main │
│ Claude, not an │ only if ≥2 defensible approaches AND you can't
│ agent │ pre-pick AND wrong choice has multi-week cost
└─────────┬─────────┘
│ VERDICT: COUNCIL (you approve)
▼
┌───────────────────────────────────────────────────────────┐
│ CONVENE: pre-flight self-select + vote → who sits? │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 8 deliberation phases (see below) │ │
│ │ proposers argue → critics attack → specialists │ │
│ │ check → arbiter decides │ │
│ └─────────────────────────────────────────────────────┘ │
│ RECORD: decision doc + dissents + decisions.log │
└───────────────────────────────────────────────────────────┘
│
▼
You get a verdict + a written record. Execution happens later, by solo Claude.
Three properties make it more than "spawn a bunch of agents":
- Structured phases. Argument, critique, and judgment happen in a fixed order. Critics can't pile on before proposers have made their case; the arbiter can't rule before specialists have weighed in.
- Contracts. Every seat emits a fixed text schema (
C-01…C-14) so the next phase can consume it predictably. Seecouncil/_meta/contracts.md. - Memory. Each project accumulates a
decisions.log, adissents.md(losing positions worth revisiting if assumptions change), and per-session records. Ahistorianseat reads them to flag when a new question rhymes with an old one.
How a session flows
Eight phases, executed in order (defined in council/_meta/phases.json):
| # | Phase | What happens |
|---|---|---|
| 1 | frame | Scribe restates the question + constraints. Reversibility-checker classifies it as a one-way or two-way door. False-dichotomy-breaker checks the framing isn't a fake A-vs-B. |
| 2 | background | Historian flags past-decision echoes. Base-rate-keeper anchors the reference class ("how often do attempts like this actually work?"). Assumption-surfacer extracts unstated premises. |
| 3 | proposals | 2–3 proposer agents each build the strongest case for one approach (C-03). Steelmanner recasts any weak version. |
| 4 | critique | Devil's-advocate attacks every proposal (C-04). Premortem-runner writes the 6-months-out failure obituary (C-05). Evidence-fetcher resolves any web lookups. |
| 5 | response | Proposers may update their position. Bayesian-updater tracks who shifted. Synthesizer hunts for a unified option. |
| 6 | domain-check | Engineer + voted-in specialists + value-keepers interject only if relevant (C-06/C-07); everyone else passes cheaply. |
| 7 | arbitration | Arbiter reads the full transcript and emits chosen / tied / kick-back (C-10). Cost-of-deliberation-tracker can call "good enough, ship it." Max one kick-back per session. |
| 8 | record | Scribe writes the decision doc, appends decisions.log, records dissents, truncates the session buffer. |
Two pre-flight phases run before phase 1 to decide who sits: every T1 seat self-selects in or out and recommends specialists from its guild, then the participating T1s vote the specialists up or down.
A full walkthrough — using the real council-self session as the example — is in
docs/04-lifecycle.md.
The 54 seats at a glance
Seats are organized into three tiers. The full roster with one-line descriptions
is in docs/03-roster.md; the authoritative index is
council/_meta/registry.md.
- T1 — 13 core seats. The load-bearing machinery:
arbiter,scribe,devils-advocate,proposer(template),engineer,historian,base-rate-keeper,premortem-runner, plus value-keepers and process seats. These self-select and vote in pre-flight. - T2 — 22 process & perspective seats.
moderator,steelmanner,synthesizer,false-dichotomy-breaker,stakeholder-empath,product-thinker, and the "owner-meta" seats that protect documented preferences (local-first-auditor,humanize-checker, etc.). - T3 — 19 specialist seats (guilds). Summoned by vote only when relevant:
ml-engineer,security-reviewer,numerical-stability,eval-designer,statistics-reviewer,api-designer, and more. Each has exactly one T1 sponsor (seecouncil/_meta/guilds.md).
Install
git clone <this-repo-url> council-system
cd council-system
./install.sh # interactive; backs up any file it would overwrite
The installer copies:
agents/*.md→~/.claude/agents/(the 54 seats)skill/SKILL.md→~/.claude/skills/council/council/_meta/+PROJECT_TEMPLATE/→~/.claude/council/
It never deletes or overwrites your own agents without first copying them to a
timestamped backup folder, and it leaves any existing PROJECT_TEMPLATE
untouched. Run ./install.sh --dry-run to preview, or --yes for
non-interactive. Then restart Claude Code so it picks up the new agents and
skill.
Verify the install is self-consistent at any time:
bash scripts/lint.sh # lint the repo
bash scripts/lint.sh --claude-dir ~/.claude # lint your installed copy
The lint cross-checks every agent's frontmatter against phases.json,
guilds.md, and the registry. (It already caught and fixed two real
inconsistencies in the original system — see CHANGELOG.md.)
Your first council
In Claude Code:
/council Should the embeddings service use a local model or a hosted API for v1?
Main Claude will run triage and show you a verdict block. If it says SOLO,
it'll explain why and just answer. If it says COUNCIL, it shows you the seats
it wants to spin and waits for your explicit approve before spending
anything. You're always in control:
| Command | Effect |
|---|---|
/council <question> | Triage → convene if warranted |
/council status | List all projects and their state |
/council resume <slug> | Re-convene an existing project with a new question |
/council note <slug> <text> | Append context to a project's buffer for next time |
/council pause <slug> / close <slug> | Park or finalize a project |
/council check | Ask the watcher whether a council is warranted right now |
⚠️ Customize before you rely on it. Several seats encode the original author's personal context (a specific research program, career goals, UI preferences). Out of the box they'll enforce his rules, not yours. See Customizing it for yourself — this is a 15-minute job and the docs walk you through every seat that needs it.
Repository layout
council-system/
├── README.md ← you are here
├── install.sh / uninstall.sh ← idempotent, backup-safe installers
├── scripts/
│ ├── lint.py ← validates the whole system for consistency
│ └── lint.sh ← wrapper
├── skill/
│ └── SKILL.md ← the /council command (triage + orchestration)
├── agents/ ← the 54 council seats (one .md per agent)
│ ├── arbiter.md ← canonical worked example; mirror it for new seats
│ └── … (53 more)
├── council/
│ ├── _meta/ ← source of truth (read by skill + agents)
│ │ ├── registry.md ← index of all 54 seats
│ │ ├── phases.json ← phase definitions + subscriber lists
│ │ ├── contracts.md ← every seat's output schema (C-01…C-14)
│ │ ├── guilds.md ← T1 → T3 sponsorship map
│ │ ├── models.md ← which seats run on opus vs sonnet, and why
│ │ ├── agent_template.md ← required structure for any new seat
│ │ ├── logging-spec.md ← (deferred) observability design
│ │ └── deferred-fixes.md ← structural fixes parked until logs justify them
│ ├── PROJECT_TEMPLATE/ ← skeleton copied on first convene of a project
│ └── examples/
│ └── council-self/ ← a REAL session: the council deliberating its own design
└── docs/ ← extended documentation (see index below)
Customizing it for yourself
The mechanical core (phases, contracts, arbiter, proposers, critics, specialists) is universal — it works for anyone. About 11 value-keeper seats are personalized to the original author and read specific memory files that won't exist on your machine. You have two clean paths:
- Global rename + targeted rewrite (recommended). Swap the author's name for
yours across the agents, then rewrite the ~11 personal seats to encode your
rules (or delete the ones you don't want). Every seat is mapped, line by line,
in
docs/07-personal-seats.md. - Disable them. Delete the personal seats entirely; the council still runs with the 43 universal ones. The lint will confirm nothing breaks.
Full step-by-step: docs/06-customization.md.
Cost
Per the skill's own estimate, a full session is roughly $2–3 of API-equivalent usage (free on a Claude Max plan, where it's effectively negligible):
| Stage | Approx. cost |
|---|---|
| Triage | free (main Claude runs it) |
| Pre-flight (self-select + vote) | ~$0.50 |
| Deliberation (8 phases) | ~$1.50–2.00 |
The whole design philosophy is to make this rare. If you're convening daily, the
gate is miscalibrated — read docs/08-faq.md.
Requirements
- Claude Code (CLI, desktop, or IDE extension) with custom agents + skills enabled.
- A Claude Max plan is strongly recommended — the council fans out to dozens of opus/sonnet agents per session; on metered API billing the cost adds up.
- python3 (only for
scripts/lint.py; ships with macOS and most Linux). The council itself needs nothing but Claude Code. - macOS or Linux for the install scripts. On Windows, copy the three directories
by hand (see
docs/00-install.md).
Full documentation index
| Doc | What's in it |
|---|---|
docs/00-install.md | Install details, manual install, troubleshooting |
docs/01-overview.md | The philosophy and design rationale |
docs/02-architecture.md | Tiers, guilds, phases, contracts — the full mental model |
docs/03-roster.md | All 54 seats, what each one does |
docs/04-lifecycle.md | A session start-to-finish, walked through the real example |
docs/05-contracts.md | How the output schemas chain phase-to-phase |
docs/06-customization.md | Make it yours (step by step) |
docs/07-personal-seats.md | Every personalized seat, what it encodes, how to adapt |
docs/08-faq.md | When to convene, when not to, gotchas |
docs/09-glossary.md | Every term: tier, guild, seat, phase, contract, kick-back… |
CONTRIBUTING.md | How to add or modify a seat without breaking the lint |
Credits & license
Built by Colin as a personal Claude Code system and packaged here for a
friend. The council-self example under council/examples/ is a genuine session
in which the council deliberated on its own architecture — included verbatim
because it's the best possible demonstration of the system working.
Released under the MIT License. It's a set of prompts and scripts; adapt it freely.