Claude Code Council

A multi-agent debate orchestration system for Claude Code. Spawn multiple AI agents with distinct personas to debate complex topics, producing structured analysis and professional PDF reports.

What It Does

Instead of asking Claude for one perspective, this system creates 6-12 agents with different viewpoints who actually argue with each other. The result is:

• Real debate: Agents quote, attack, and rebut each other's arguments
• Multiple perspectives: From different stakeholders, ideologies, or expertise areas
• Structured outputs: Position maps, crux identification, synthesis reports, PDFs
• Evidence-backed: Agents do web research to ground arguments in facts

Debate Types

The system adapts to different kinds of questions:

Type	Example Topics	Key Outputs
Policy	AI regulation, immigration, climate law	Policy options, stakeholder impacts
Technical	Architecture decisions, framework choices	Decision matrix, recommendation
Strategic	Market entry, product roadmap, M&A	Options analysis, risk register
Ethical	AI ethics, bioethics, research ethics	Ethical framework, guidance
Research	Scientific controversies, methodology	Evidence synthesis, research agenda
Risk	Cybersecurity, operational risk, safety	Risk register, mitigation strategies

Quick Start

1. Clone and enter the project:

   git clone https://github.com/justusaugust/claude-code-council.git
   cd claude-code-council

2. Start Claude Code from this folder:

   claude

3. Give it a topic:

   Run a debate on: "Should our startup build vs buy our data infrastructure?"
   

4. Claude will:

   • Read the orchestration instructions
   • Ask you clarifying questions
   • Create agents (CTO, CFO, Lead Engineer, etc.)
   • Run a multi-wave debate
   • Produce synthesis and PDF report

How It Works

Architecture

claude-code-council/
├── quick_start.md                 # Read this first
├── debate_initialisation_prompt.md # Full orchestration instructions
├── post_debate_review.md          # Post-debate improvement process
├── _master_templates/             # Shared templates
│   ├── debate_rules.json          # Forbidden phrases, required behaviors
│   ├── persona_card_template.json # Agent persona structure
│   ├── moderator_prompts.json     # Escalation prompts
│   └── completion_checklist.json  # Phase tracking
├── _persona_library/              # Pre-built personas (optional)
├── .claude/                       # Claude Code hooks
│   ├── settings.json
│   └── hooks/                     # Auto-reminders for common mistakes
└── debates/                       # Your debates go here (gitignored)

The Debate Process

1. Phase 0: Orchestrator researches topic, detects debate type, asks clarifying questions
2. Phase 1: Maps the opinion spectrum (what positions exist?)
3. Phase 2: Creates agent personas with distinct viewpoints
4. Phase 3: Agents research and state initial positions
5. Phase 4: Cross-critiques and steelmanning
6. Phase 5: Live debate in sequential waves (2-3 agents at a time)
7. Phase 6: Reflections and belief updates
8. Phase 7: Synthesis, crux identification, type-specific deliverables
9. Phase 7.5: PDF generation with XeLaTeX
10. Phase 8: Post-debate review and system improvement

Built-in Safeguards

The system includes hooks that automatically remind the orchestrator about common mistakes:

• Research reminder: Triggers when writing positions (did you do web searches?)
• State update reminder: Triggers after each debate wave (update tracking files!)
• Final phases reminder: Triggers after synthesis (don't forget PDF + review!)

Requirements

• Claude Code CLI
• XeLaTeX for PDF generation (optional but recommended)
  • macOS: brew install --cask mactex
  • Linux: sudo apt install texlive-xetex
  • Windows: MiKTeX

Example Output

A typical debate produces:

debates/ai_regulation_2025/
├── _config/                    # Copied rules and prompts
├── _agents/                    # Agent persona cards (JSON)
├── _state/                     # Attack registry, contribution tracking
├── 01_opinion_spectrum.md      # Position mapping
├── 02_subagents_manifest.md    # Agent definitions
├── 03_positions.md             # Initial positions with evidence
├── 04_cross_critiques.md       # Steelmans and critiques
├── 05_debate_log.md            # Full debate transcript
├── 06_reflections.md           # Post-debate belief updates
├── 07_cruxes.md                # Core disagreements identified
├── 07_synthesis.md             # Analysis and findings
├── 07_matrix.json              # Structured data export
└── 08_final_report_ai_regulation_2025.pdf

Tips for Good Debates

1. Be specific: "AI regulation" is too broad; "Should the EU AI Act require frontier model licensing?" is better
2. Let it research: The system does web searches - give it time to find current evidence
3. Trust the process: Sequential waves feel slower but produce actual back-and-forth
4. Check the PDF: It's the polished deliverable; the markdown files are working documents

Contributing

This system improves through use. After each debate, Phase 8 prompts you to:

• Evaluate what went well/poorly
• Update the templates and instructions
• Document changes in the change log

Feel free to submit PRs with improvements you've discovered.

License

MIT