Debate

new opus

Multi-agent debate orchestrator. Spawn 2-5 dynamic agents with unique characters, run structured debates, and produce judge-verified decisions. Three modes for different goals: select the best option, synthesize strategy, or find all weaknesses.

Tip

Research-First Debates — Evidence, Not Opinions. Every debate begins with a Discovery phase: 2-3 agents research your codebase and the web in parallel before any argument starts. A Codebase Explorer searches for relevant code, patterns, and dependencies. Web Researchers find current best practices, official docs, and community discussions. All findings land in discovery.md with full sources (file paths, URLs). Every debate argument must cite evidence — unsourced claims are challenged by the judge. This makes decisions grounded in real project code and current industry knowledge, not hallucinated reasoning.

✏️

CHALLENGE

Generate or receive variants, debate to select the best one. Defenders argue FOR, critics attack. Outcome: selected variant with justification.

⭐

STRATEGY

Deep analysis — each agent independently forms their approach, then debate to converge. Outcome: synthesized strategy or ranked approaches.

🔍

CRITIC

Find all weaknesses and risks in a given solution, plan, or code. All agents are critics with different perspectives. Outcome: prioritized issue list.

Quick Reference

Field	Value
Command	`/brewcode:debate`
Arguments	`[topic] [-m challenge\|strategy\|critic] [-n 2-5] [-r max-rounds] [--review]`
Modes	Challenge (default), Strategy, Critic
Agents	2-5 dynamic agents + secretary + judge (main session)
Rounds	1-10 (default: 5)
Log format	JSONL — one entry per debate turn
Model	opus
Output	`decisions.md`, `summary.md`, `debate-log.jsonl`

Quick Start

# Challenge mode -- compare options (default)
/brewcode:debate "React vs Vue vs Svelte for our new dashboard"

# Strategy mode -- deep analysis
/brewcode:debate "Migration plan from monolith to microservices" -m strategy

# Critic mode -- find all weaknesses
/brewcode:debate "Review our authentication flow" -m critic

# Custom agent count and max rounds
/brewcode:debate "Kubernetes vs ECS" -n 4 -r 8

# Auto-detect mode from keywords
/brewcode:debate "Which database should we pick for time-series data"

Workflow

Phase 0 — Validation
Run validate.sh to check all skill files exist. Load archetypes into context. Stop on failure.
Phase 1-2 — Parse and Init
Parse arguments: topic, mode (-m), agent count (-n), max rounds (-r). Auto-detect mode from keywords if not specified. Create report directory and empty JSONL log.
Phase 3 — User Interview
Confirm or adjust: mode, agent count, agent profiles (auto or custom), max rounds. Interactive via AskUserQuestion.
Phase 4 — Agent Generation
Detect domain, assign roles (mode-aware), select character archetypes. Display full agent table: name, role, character, perspective, rationale. User confirms or adjusts.
Phase 4.5 — Discovery (Research)
2-3 research agents run in parallel: Codebase Explorer searches the project for relevant code, patterns, and dependencies; Web Researcher(s) search the internet for current best practices, official docs, and community discussions. All findings are documented with sources (file paths, URLs) in discovery.md. This evidence base is injected into every debate agent’s context.
Phase 5 — Debate
Execute mode-specific flow. Every argument must cite Discovery evidence — unsourced claims are challenged by the judge. Each agent sees previous entries via JSONL log. Judge monitors for consensus, stalemate, or max rounds. Sequential execution ensures coherent argumentation.
Phase 6 — Summary
Secretary agent writes summary.md with key arguments, turning points, and areas of agreement/disagreement.
Phase 7 — Decision
Judge (main session) writes decisions.md with final verdict, reasoning, and minority opinions.
Phase 8 — Final Output
Status table, outcome (consensus / partial / none), decision bullets, links to all artifacts. Optional /brewcode:review if —review flag was set.

Modes Deep Dive

Challenge

Goal: Select the best variant from multiple options.

Agent Roles:

Defenders argue FOR their assigned variant(s)
Critics attack all variants, probing weaknesses

Role split by agent count:

Agents	Defenders	Critics
2	1	1
3	1	2
4	2	2
5	2	3

Flow: Discovery agents research codebase and web first. Defenders present variants with evidence-backed arguments. Critics challenge each one citing counter-evidence. Multiple rounds until judge detects consensus or max rounds reached.

Best for: Technology choices, architecture decisions, comparing approaches, “A vs B” questions.

Strategy

Goal: Synthesize the strongest approach from independent proposals.

Agent Roles: All agents are Strategists with different archetypes.

Four-phase flow:

Discovery — research agents gather evidence from codebase and web (parallel)
Independent proposals — each agent formulates their approach using Discovery evidence, without seeing others (parallel thinking)
Judge picks opening order — most divergent proposals go first to maximize productive tension
Debate to converge — agents discuss, challenge, and synthesize, citing sources. Goal is convergence, not winner selection

Best for: Migration plans, system design, strategic decisions, “how should we approach X” questions.

Critic

Goal: Find every weakness, risk, and flaw in a given solution.

Agent Roles: All agents are Critics with different perspectives (operational, security, UX, financial, architectural).

Flow: Discovery agents research the codebase and web for relevant context first. No defender — the document/plan/code IS the target. Each critic analyzes from their unique angle, citing evidence. Rounds build on previous findings. Judge consolidates into prioritized issue list with severity ratings.

Best for: Code review, architecture review, plan validation, risk assessment, security audit.

Agent Archetypes

10 character archetypes define HOW an agent argues. Combined with roles (defender/critic/strategist) to create unique debate personas.

✅

Pragmatist

Results-oriented, impatient with theory. “What actually works in production?” Cites real-world outcomes, dismisses hypotheticals.

⭐

Visionary

Big-picture, future-oriented. “Where is this heading in 5 years?” Argues from trends, first principles, emerging patterns.

🔍

Skeptic

Cautious, evidence-demanding. “Show me the data.” Finds edge cases, stress-tests assumptions, demands proof.

✏️

Architect

Systematic, pattern-focused. “How does this fit the bigger system?” Argues from design principles, consistency, modularity.

🔧

Operator

Reliability-focused, operations-minded. “Who maintains this at 3 AM?” Argues from operational reality and incident response.

heart

Advocate

User-centric, empathetic. “What does the end user experience?” Argues from UX, adoption, accessibility, learning curve.

📄

Economist

Cost-conscious, ROI-focused. “What’s the total cost of ownership?” Argues with numbers, trade-off matrices, opportunity cost.

information

Historian

Precedent-aware, pattern-matching. “We tried this in 2019 and it failed because…” Argues from past failures and case studies.

warning

Provocateur

Contrarian, challenges consensus. “What if we’re solving the wrong problem?” Reframes the debate, asks uncomfortable questions.

⚡

Diplomat

Consensus-seeking, synthesizing. “I hear both sides — what if we combine…” Finds common ground, proposes compromises.

Tip

Archetypes are auto-selected to create productive tension. Challenge mode pairs contrasting styles (e.g., Pragmatist defender vs Visionary critic). Avoid pairing archetypes that argue identically.

Configuration

Flag	Default	Description
`-m`	auto-detect	Mode: `challenge`, `strategy`, `critic`
`-n`	3	Agent count: 2-5
`-r`	5	Max debate rounds: 1-10
`--review`	off	Run `/brewcode:review` on final output
(positional)	—	Topic text or file path

Auto-detect mode when -m is omitted:

Keywords in topic	Detected mode
compare, choose, select, best, vs, versus, pick, which	`challenge`
strategy, approach, plan, how to, design, architecture	`strategy`
critique, weakness, risk, flaw, review, audit, problem	`critic`
(no match)	`challenge` (default)

Output Format

All artifacts are written to .claude/reports/{TS}_debate/.

JSONL Log

Each debate turn is a single line in debate-log.jsonl:

{"ts":"2026-04-05T14:30:00","from":"agent-1","to":["agent-2"],"what":"React has larger ecosystem","why":"More packages, hiring pool, community support","type":"argument","mode":"challenge"}
{"ts":"2026-04-05T14:30:15","from":"agent-2","to":["agent-1"],"what":"Ecosystem size != quality","why":"Vue's curated ecosystem avoids dependency hell","type":"counter","mode":"challenge"}
{"ts":"2026-04-05T14:31:00","from":"agent-3","to":["all"],"what":"Both miss the point","why":"Developer experience and bundle size matter more for our team size","type":"redirect","mode":"challenge"}

Entry types: argument, counter, proposal, agree, question, redirect

Artifacts

File	Content
`discovery.md`	Research findings with sources: file paths, URLs, code snippets, best practices
`decisions.md`	Judge verdict, reasoning, minority opinions
`summary.md`	Secretary summary: key arguments, turning points, agreement areas
`debate-log.jsonl`	Full debate log, one entry per turn

Examples

Tech Choice

# Compare frontend frameworks for a new project
/brewcode:debate "React vs Vue vs Svelte for our dashboard" -n 3

# 3 agents: 1 defender (Pragmatist), 2 critics (Skeptic, Visionary)
# Output: selected framework with full justification

Architecture

# Strategy for migration
/brewcode:debate "How to migrate from REST to GraphQL" -m strategy -n 4

# 4 strategists: Architect, Operator, Economist, Pragmatist
# Each proposes independently, then debate to converge

Code Review

# Critic mode on authentication flow
/brewcode:debate "Critique our JWT auth implementation in auth/" -m critic -n 5

# 5 critics: Skeptic (edge cases), Operator (ops risks),
# Architect (design flaws), Advocate (UX), Economist (cost)

Design Decision

# Database selection with extended rounds
/brewcode:debate "PostgreSQL vs DynamoDB for our event store" -n 4 -r 8

# 4 agents, up to 8 rounds for thorough analysis
# Auto-detects challenge mode from "vs" keyword

Risk Assessment

# Find weaknesses in a deployment plan
/brewcode:debate "Review our Kubernetes migration plan" -m critic --review

# All-critic team reviews the plan
# --review flag triggers /brewcode:review on output

Note

Tips for effective debates:

Be specific in the topic — “React vs Vue for our 5-person team building a real-time dashboard” produces better arguments than “React vs Vue”
Use 3 agents for focused debates, 4-5 for complex multi-faceted topics
Strategy mode works best when the problem space is open-ended
Critic mode shines when you already have a solution and want to stress-test it
The judge (main session) can intervene mid-debate to redirect if agents go off-topic

Key Design Decisions

Decision	Rationale
Agent tool for debaters	Dynamic prompts with unique characters, no pre-defined agent files needed
Sequential execution	Each agent sees previous entries for coherent argumentation
JSONL shared state	Minimal tokens, scriptable, easy to parse and filter
Bash scripts for I/O	Prevents malformed JSON, schema enforcement
Judge = main session	No extra agent overhead, maintains full context
Mode-specific flows	Progressive disclosure, token efficiency — only load relevant flow