| name | council-guide |
| description | Run a multi-agent council for major architectural decisions — quad-model deliberation with Claude teammates (Opus) plus Codex, Gemini, and Cursor as independent external analysts. Use when a decision is too complex or high-stakes for a single agent or adversarial review. |
Council Deliberation Guide
Purpose: Operational guide for running multi-agent councils with cross-model deliberation. Councils use Claude teammates (Opus) for structured debate, plus Codex (OpenAI), Gemini (Google), and Cursor (Composer-2) as independent external analysts.
What a Council IS
A council is a deliberation, not parallel reviews. The value comes from members
seeing each other's positions, challenging them, and converging on refined recommendations.
Without cross-member discussion, you just have independent reviewers — the synthesis
is aggregation, not deliberation.
Mandatory Members
| Member | Role | Runtime |
|---|
| 4th Layer Advocate | Agent navigability, disambiguation, structural clarity | Claude teammate (Opus) |
| Visionary | Scalability, YIGNI, known future trajectory | Claude teammate (Opus) |
| Devil's Advocate | Find holes, challenge assumptions, surface what everyone missed | Claude teammate (Opus) |
| Codex | Independent autonomous analysis, no assigned role, full freedom | Background CLI (OpenAI) |
| Gemini | Independent autonomous analysis, no assigned role, full freedom | Background CLI (Google) |
| Cursor | Independent autonomous analysis, no assigned role, full freedom | Background agent (~/bin/agent, model: Composer-2) |
Optional members added per-council based on domain:
- Data Engineer, Speed, Security, UX, etc.
Why Four Model Families
Codex, Gemini, and Cursor provide cross-model diversity — three independent analyses from
different model families (OpenAI, Google, Cursor/Composer-2) that neither share context with
each other nor with the Claude teammates. This surfaces blind spots that a single model family misses.
When external analysts agree on something Claude members missed → high-confidence gap.
When external analysts disagree with each other → highest-signal finding in the council.
Infrastructure
Create a council/ subdirectory in the active RUN:
council/
├── README.md # Members, process, key context files
├── SYNTHESIS.md # Final synthesis (written by lead after deliberation)
├── <member-slug>/
│ ├── SPEC.md # Role mandate, evaluation criteria, key files to read
│ └── NOTES.md # Append-only assessment log
Claude Teammates
Use TeamCreate to create the team. Each member is an Agent teammate (all Opus).
External Agents (Codex + Gemini + Cursor)
All three run in background via CLI — launched with run_in_background: true in the Bash tool.
codex -p "council prompt here" --force --model auto --output-format stream-json 2>&1
gemini -p "council prompt here" --yolo -m gemini-2.5-pro --output-format stream-json 2>&1
agent --force --trust --model composer-2 --output-format stream-json --print "council prompt here" 2>&1
Rules for external agents:
- Launch all three at the same time as Claude teammates (Phase 1)
- Use
stream-json output format
- Peek with
head -n 50 on output file — NEVER read the full stream
- They receive the same high-level council prompt but NO role assignment
- They do NOT see each other's work or the Claude members' work
- Their independence is the point — don't contaminate it
External Agent Prompt Template
Give all three external agents the same prompt (adjusted only for CLI syntax):
You are an independent analyst on a multi-agent council. Your job is to analyze
the following topic with complete autonomy — no assigned role, no constraints
on what you focus on.
TOPIC: [council topic]
CONTEXT FILES TO READ:
- [list of key files]
DELIVERABLE: Write your analysis to council/external-[codex|gemini|cursor]/NOTES.md
Include: key observations, concerns, recommendations, and anything surprising.
There are other council members analyzing the same topic independently.
Your value is your unique perspective — don't try to be comprehensive,
focus on what YOU find most important.
Execution Flow (CRITICAL — Do Not Skip Steps)
Phase 1: Independent Review
- Launch Codex, Gemini, AND Cursor in background (full autonomy, no role, no coordination)
- Spawn all Claude teammates in parallel
- Each Claude member reads their SPEC, reads context files, writes NOTES.md, sends summary to lead
- DO NOT shut anyone down yet
Phase 2: Pre-External Synthesis
- Lead writes a PRELIMINARY synthesis based on Claude members' assessments
- Broadcast the preliminary synthesis to all Claude teammates
- Include: consensus items, disagreements, open questions
- Purpose: members see each other's positions for the first time
Phase 3: Cross-Member Discussion
- Members respond to the synthesis — challenge, agree, refine, debate
- Members can message each other directly (not just the lead)
- Lead monitors and captures key exchanges
- This is where real deliberation happens — positions evolve, disagreements resolve
Phase 4: Post-External Review
- When external agents complete, share ALL findings with all Claude teammates
- Present them as "External Agent A/B/C" — let members react to each
- Key questions to surface:
- Did any external agent catch something no Claude member did?
- Do the external agents agree with each other? Disagreements between them are high-signal.
- Does any external analysis change a Claude member's position?
- Allow a round of reactions from Claude members before moving to synthesis
Phase 5: Final Synthesis
- Lead writes SYNTHESIS.md incorporating the full deliberation arc:
- Initial positions → cross-member debate → external agent reactions → final positions
- Note where external agents converged (high confidence) vs diverged (needs attention)
- Note where external agents agreed with Claude members vs surfaced novel concerns
- This reflects actual deliberation, not just aggregation of independent reports
Phase 6: User Discussion
- Present synthesis to the user
- User discusses, pushes back, asks questions
- Council members are STILL ALIVE during this phase — user can probe any position
- External agent output is available for reference but agents themselves are done
Phase 7: Shutdown
- Only after user approves the synthesis or has no more questions
- Send shutdown requests to all teammates
- Clean up team
Anti-Patterns (Mistakes Made, Don't Repeat)
| Anti-Pattern | Why It's Wrong |
|---|
| Shutting down members after Phase 1 | Kills the deliberation before it starts. Individual reports are the STARTING POINT, not the output. |
| Synthesizing without cross-member discussion | Produces aggregation, not deliberation. Synthesis should reflect positions that EVOLVED through debate. |
| Treating council like parallel subagents | Subagents do independent work and report. Council members DISCUSS, DISAGREE, and CONVERGE. |
| Ignoring external agent disagreements | When two independent external models disagree, that's the highest-signal finding. Always surface and resolve. |
| Contaminating external agents | Don't share Claude members' work with Codex/Gemini/Cursor. Their value is independent perspective from a different model family. |
| Skipping Phase 4 if externals are slow | Wait for them. The cross-model check is a core part of the protocol, not optional. |
Quick Reference: CLI Commands
codex -p "prompt" --force --model auto --output-format stream-json 2>&1
gemini -p "prompt" --yolo -m gemini-2.5-pro --output-format stream-json 2>&1
agent --force --trust --model composer-2 --output-format stream-json --print "prompt" 2>&1
head -n 50 /path/to/output/file
Lessons from First Council (RUN-20260304-1112, eda-architecture-council)
- 6 members produced excellent independent assessments
- But no member ever saw another's work
- No cross-pollination, no debate, no position evolution
- Synthesis was lead aggregating 6 independent reports
- Value left on the table: Speed vs Data Engineer on taxonomy,
Devil's Advocate vs 4th Layer Advocate on parser validation approach,
Codex insights never challenged or adopted by the group
Takeaway: The protocol exists because this mistake was made. Follow every phase.
Last Updated: 2026-04-08
