mirror of
https://github.com/kochetkov-ma/claude-brewcode.git
synced 2026-09-14 20:16:41 +08:00
v3.4.28: debate skill — evidence-based multi-agent debates with Discovery phase
This commit is contained in:
kochetkov-ma
@@ -6,13 +6,13 @@
|
||||
},
|
||||
"metadata": {
|
||||
"description": "Claude Code plugin suite: brewcode for infinite task execution and brewdoc for documentation tools",
|
||||
"version": "3.4.27"
|
||||
"version": "3.4.28"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "brewcode",
|
||||
"description": "Brewcode - full-featured development platform for Claude Code: infinite focus tasks, prompt optimization, skill/agent creation, quorum reviews, rules management",
|
||||
"version": "3.4.27",
|
||||
"version": "3.4.28",
|
||||
"category": "productivity",
|
||||
"keywords": [
|
||||
"brewcode",
|
||||
@@ -46,7 +46,7 @@
|
||||
{
|
||||
"name": "brewdoc",
|
||||
"description": "Brewdoc - Claude Code documentation tools: auto-sync for skills/agents/rules, my-claude installation docs, memory optimization, md-to-pdf conversion",
|
||||
"version": "3.4.27",
|
||||
"version": "3.4.28",
|
||||
"category": "productivity",
|
||||
"keywords": [
|
||||
"brewdoc",
|
||||
@@ -74,7 +74,7 @@
|
||||
{
|
||||
"name": "brewtools",
|
||||
"description": "Brewtools - universal utilities for Claude Code: text optimization, humanization, secrets scanning",
|
||||
"version": "3.4.27",
|
||||
"version": "3.4.28",
|
||||
"category": "productivity",
|
||||
"keywords": [
|
||||
"brewtools",
|
||||
|
||||
@@ -259,7 +259,7 @@ Skill writes mode → state file → hooks inject on every event
|
||||
|
||||
---
|
||||
|
||||
## Brewcode Skills (12)
|
||||
## Brewcode Skills (14)
|
||||
|
||||
| Skill | Purpose |
|
||||
|-------|---------|
|
||||
@@ -275,6 +275,7 @@ Skill writes mode → state file → hooks inject on every event
|
||||
| `/brewcode:convention` | Extract etalon classes, patterns, architecture into convention docs + rules |
|
||||
| `/brewcode:agents` | Interactive agent creation and improvement |
|
||||
| `/brewcode:teams` | Create and manage dynamic teams of domain-specific agents |
|
||||
| `/brewcode:debate` | Evidence-based multi-agent debate: Discovery phase researches codebase + web before every debate. Challenge, Strategy, Critic modes |
|
||||
| `/brewcode:teardown` | Remove plugin configuration (keeps task data) |
|
||||
|
||||
## Brewtools Skills (3)
|
||||
|
||||
@@ -2,6 +2,14 @@
|
||||
|
||||
---
|
||||
|
||||
## v3.4.28 (2026-04-05)
|
||||
|
||||
### brewcode
|
||||
#### Added
|
||||
- **debate:** New `/brewcode:debate` skill — evidence-based multi-agent debate orchestration with Discovery phase (parallel codebase + web research before every debate), 3 modes (Challenge, Strategy, Critic), dynamic agent generation (2-5 agents), mandatory source citations for all arguments, sequential debates with JSONL logging, secretary summaries, and judge decisions
|
||||
|
||||
---
|
||||
|
||||
## v3.4.26 (2026-04-04)
|
||||
|
||||
### brewcode
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "brewcode",
|
||||
"version": "3.4.27",
|
||||
"version": "3.4.28",
|
||||
"description": "Brewcode - full-featured development platform for Claude Code: infinite focus tasks, prompt optimization, skill/agent creation, quorum reviews, rules management",
|
||||
"author": {
|
||||
"name": "Maksim Kochetkov",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "claude-plugin-brewcode",
|
||||
"version": "3.4.27",
|
||||
"version": "3.4.28",
|
||||
"description": "Infinite task execution with automatic handoff for Claude Code",
|
||||
"keywords": [
|
||||
"claude-code",
|
||||
@@ -36,6 +36,6 @@
|
||||
},
|
||||
"claude-plugin": {
|
||||
"name": "brewcode",
|
||||
"version": "3.4.27"
|
||||
"version": "3.4.28"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,207 @@
|
||||
# brewcode:debate
|
||||
|
||||
Multi-agent debate orchestration skill. Spawns 2-5 dynamic agents with unique character archetypes, runs sequential debate rounds, and produces structured decisions with full audit trail.
|
||||
|
||||
Three modes: **Challenge** (pick the best variant), **Strategy** (deep collaborative analysis), **Critic** (find every weakness).
|
||||
|
||||
## Evidence-Based Debate
|
||||
|
||||
Every debate starts with a **Discovery phase** -- parallel research agents gather real evidence before any argument begins:
|
||||
|
||||
| Agent | Scope | Output |
|
||||
|-------|-------|--------|
|
||||
| **Codebase Explorer** | Searches project for relevant code, patterns, dependencies, existing implementations | File paths, code snippets, architecture facts |
|
||||
| **Web Researcher(s)** | Searches the internet for current best practices, official docs, recent changes, community discussions | URLs, quotes, version-specific findings |
|
||||
|
||||
**How it works:**
|
||||
1. 2-3 research agents run in parallel before the debate starts (Phase 4.5)
|
||||
2. All findings are documented with sources (file paths, URLs) in `discovery.md`
|
||||
3. Every debate argument MUST cite evidence from Discovery -- unsourced claims are challenged by the judge
|
||||
4. The judge weights arguments by evidence quality: primary sources > blog posts > opinion
|
||||
|
||||
This is the key differentiator: debates produce decisions grounded in actual project code and current industry knowledge, not hallucinated reasoning.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```
|
||||
/brewcode:debate "Redis vs Memcached for session storage" -m challenge -n 3
|
||||
/brewcode:debate "Migration strategy for monolith to microservices" -m strategy -n 4
|
||||
/brewcode:debate "Review our auth flow for security gaps" -m critic -n 3 -r 8
|
||||
```
|
||||
|
||||
Topic can be inline text or a file path. Mode auto-detects from keywords when `-m` is omitted. Discovery runs automatically before every debate -- agents research your codebase and the web to gather evidence.
|
||||
|
||||
## Modes
|
||||
|
||||
### Challenge (default)
|
||||
|
||||
Select the best option from competing variants. Agents split into defenders and critics.
|
||||
|
||||
| Agents | Split |
|
||||
|--------|-------|
|
||||
| 2 | 1 defender + 1 critic |
|
||||
| 3 | 1 defender + 2 critics |
|
||||
| 4 | 2 defenders + 2 critics |
|
||||
| 5 | 2 defenders + 3 critics |
|
||||
|
||||
**Outcome:** Selected variant with justification and minority opinions.
|
||||
|
||||
### Strategy
|
||||
|
||||
Deep analysis where each agent independently proposes an approach before debating.
|
||||
|
||||
1. Independent proposals (parallel)
|
||||
2. Judge picks opening order
|
||||
3. Debate rounds to converge or rank
|
||||
|
||||
**Outcome:** Synthesized strategy or ranked approaches.
|
||||
|
||||
### Critic
|
||||
|
||||
All agents are critics attacking a given solution, plan, or code from different angles. No defender — the document itself is the target.
|
||||
|
||||
**Outcome:** Prioritized issue list with severity and recommendations.
|
||||
|
||||
## Arguments
|
||||
|
||||
| Flag | Default | Description |
|
||||
|------|---------|-------------|
|
||||
| `-m` | auto-detect | Mode: `challenge`, `strategy`, `critic` |
|
||||
| `-n` | 3 | Agent count (2-5) |
|
||||
| `-r` | 5 | Max debate rounds |
|
||||
| `--review` | off | Run `/brewcode:review` on output after debate |
|
||||
| (positional) | required | Topic text or file path |
|
||||
|
||||
### Auto-detect rules (when `-m` omitted)
|
||||
|
||||
| Keywords | 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 |
|
||||
| none matched | challenge |
|
||||
|
||||
## Agent Archetypes
|
||||
|
||||
Each agent gets a character archetype that defines HOW they argue, combined with a role (defender/critic/strategist) that defines WHAT they argue for.
|
||||
|
||||
| # | Archetype | Style | Best For |
|
||||
|---|-----------|-------|----------|
|
||||
| 1 | Pragmatist | "What works in production?" Results over theory | Challenge: defend proven solutions |
|
||||
| 2 | Visionary | "Where is this in 5 years?" First principles, trends | Strategy: transformative proposals |
|
||||
| 3 | Skeptic | "Show me the data." Evidence-demanding, edge cases | Critic: any mode |
|
||||
| 4 | Architect | "How does it fit the system?" Patterns, modularity | Strategy: system-level analysis |
|
||||
| 5 | Operator | "Who maintains this at 3 AM?" Reliability, ops reality | Critic: operational risks |
|
||||
| 6 | Advocate | "What does the user experience?" UX, accessibility | Challenge: defend user-friendly options |
|
||||
| 7 | Economist | "What's the total cost?" ROI, trade-off matrices | Strategy: cost-benefit analysis |
|
||||
| 8 | Historian | "We tried this before." Precedents, past failures | Critic: pattern recognition |
|
||||
| 9 | Provocateur | "Wrong problem entirely." Contrarian, reframes debate | Critic: assumption-busting |
|
||||
| 10 | Diplomat | "What if we combine both?" Consensus, synthesis | Strategy: bridge-building |
|
||||
|
||||
Archetypes are selected to create productive tension — contrasting perspectives, not redundant ones.
|
||||
|
||||
## Output
|
||||
|
||||
All artifacts land in `.claude/reports/{TS}_debate/`:
|
||||
|
||||
```
|
||||
.claude/reports/20260405-143000_debate/
|
||||
discovery.md # Research findings with sources (URLs, file paths)
|
||||
debate-log.jsonl # Full debate transcript (machine-readable)
|
||||
summary.md # Secretary agent's synthesis
|
||||
decisions.md # Judge's final ruling
|
||||
```
|
||||
|
||||
### JSONL Log Format
|
||||
|
||||
Each agent turn produces one entry:
|
||||
|
||||
```jsonl
|
||||
{"ts":"2026-04-05T14:30:15","from":"agent-1","to":["agent-2"],"what":"<20 words","why":"<40 words","type":"argument","mode":"challenge"}
|
||||
```
|
||||
|
||||
| Field | Values |
|
||||
|-------|--------|
|
||||
| `type` | `argument`, `counter`, `proposal`, `agree`, `question`, `redirect` |
|
||||
| `mode` | `challenge`, `strategy`, `critic` |
|
||||
|
||||
### decisions.md
|
||||
|
||||
Written by the judge (main session). Contains:
|
||||
- Winning position or synthesized result
|
||||
- Key arguments that decided the outcome
|
||||
- Minority opinions worth noting
|
||||
- Confidence level (high / medium / low)
|
||||
- Recommended next steps
|
||||
|
||||
### summary.md
|
||||
|
||||
Written by the secretary agent. Neutral synthesis of the full debate.
|
||||
|
||||
## Configuration
|
||||
|
||||
The skill runs an interactive interview (Phase 3) before starting. You can confirm defaults or customize:
|
||||
|
||||
1. **Mode** — switch between challenge/strategy/critic
|
||||
2. **Agent count** — 2 to 5 agents
|
||||
3. **Max rounds** — cap on debate iterations (default 5)
|
||||
4. **Agent profiles** — accept auto-generated team or describe custom profiles
|
||||
|
||||
After profile generation, you review the agent table (name, role, archetype, perspective) and can swap individual agents or regenerate the full team.
|
||||
|
||||
## Examples
|
||||
|
||||
### Compare technologies
|
||||
|
||||
```
|
||||
/brewcode:debate "Redis vs PostgreSQL for job queue" -m challenge -n 4
|
||||
```
|
||||
|
||||
4 agents (2 defenders, 2 critics) debate the two options. Judge selects winner with justification.
|
||||
|
||||
### Plan a migration
|
||||
|
||||
```
|
||||
/brewcode:debate "How should we migrate from REST to gRPC across 12 services?" -m strategy -n 5 -r 8
|
||||
```
|
||||
|
||||
5 agents each propose an independent strategy, then debate across 8 rounds to converge on a ranked plan.
|
||||
|
||||
### Audit existing code
|
||||
|
||||
```
|
||||
/brewcode:debate path/to/auth-module.md -m critic -n 3
|
||||
```
|
||||
|
||||
3 critic agents (e.g., Skeptic, Operator, Historian) attack the auth module from different angles. Output is a prioritized issue list.
|
||||
|
||||
### Quick 2-agent challenge
|
||||
|
||||
```
|
||||
/brewcode:debate "Monorepo vs polyrepo for our 4-person team"
|
||||
```
|
||||
|
||||
Auto-detects challenge mode from "vs". 2 agents, 5 rounds, minimal setup.
|
||||
|
||||
### With post-debate review
|
||||
|
||||
```
|
||||
/brewcode:debate "API rate limiting strategy" -m strategy --review
|
||||
```
|
||||
|
||||
After debate completes, automatically runs `/brewcode:review` on the output artifacts.
|
||||
|
||||
## Workflow
|
||||
|
||||
```
|
||||
Phase 0 Validate skill files
|
||||
Phase 1 Parse arguments, detect mode
|
||||
Phase 2 Init report directory + JSONL log
|
||||
Phase 3 User interview (confirm/adjust settings)
|
||||
Phase 4 Generate agent profiles (archetypes + roles)
|
||||
Phase 4.5 Discovery — parallel research (codebase + web) → discovery.md
|
||||
Phase 5 Run debate (mode-specific flow, all arguments cite Discovery evidence)
|
||||
Phase 6 Secretary writes summary.md
|
||||
Phase 7 Judge writes decisions.md
|
||||
Phase 8 Display results + optional review
|
||||
```
|
||||
@@ -0,0 +1,233 @@
|
||||
---
|
||||
name: brewcode:debate
|
||||
description: "Orchestrates multi-agent debates with 3 modes: Challenge (select best variant), Strategy (deep analysis with independent proposals), Critic (find all weaknesses). Triggers: debate, challenge, compare options, strategy analysis, critique, find weaknesses."
|
||||
disable-model-invocation: true
|
||||
user-invocable: true
|
||||
argument-hint: "[topic] [-m challenge|strategy|critic] [-n 2-5] [-r max-rounds] [--review]"
|
||||
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion, Skill
|
||||
model: opus
|
||||
---
|
||||
|
||||
# Multi-Agent Debate
|
||||
|
||||
Orchestrates sequential multi-agent debates. Dynamic agents (2-5) with unique characters debate, main session acts as judge, secretary summarizes, judge writes final decisions.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0: Validation
|
||||
|
||||
**EXECUTE** using Bash tool:
|
||||
```bash
|
||||
bash "${CLAUDE_SKILL_DIR}/scripts/validate.sh" && echo "VALID" || echo "FAILED"
|
||||
```
|
||||
|
||||
> **STOP if FAILED** — fix missing files before continuing.
|
||||
|
||||
Read archetypes into context:
|
||||
|
||||
Read file: `${CLAUDE_SKILL_DIR}/agents/archetypes.md`
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Parse Arguments
|
||||
|
||||
**Arguments:** `$ARGUMENTS`
|
||||
|
||||
| Flag | Default | Description |
|
||||
|------|---------|-------------|
|
||||
| `-m` | ask user | Mode: `challenge`, `strategy`, `critic` |
|
||||
| `-n` | 3 | Agent count: 2-5 |
|
||||
| `-r` | 5 | Max debate rounds |
|
||||
| `--review` | off | Run `/brewcode:review` on output |
|
||||
| (positional) | — | Topic text or file path |
|
||||
|
||||
### Mode not specified (when `-m` omitted)
|
||||
|
||||
If mode is NOT explicitly provided via `-m` flag or clearly stated in the topic text, **do NOT auto-detect**. Ask user using AskUserQuestion:
|
||||
|
||||
> **Which debate mode?**
|
||||
>
|
||||
> 1. **Challenge** — generate/receive variants, debate to select the best one
|
||||
> 2. **Strategy** — each agent proposes independently, then debate to converge
|
||||
> 3. **Critic** — all agents attack the given solution to find weaknesses/risks
|
||||
>
|
||||
> Reply with mode name or number.
|
||||
|
||||
Only proceed after explicit user choice.
|
||||
|
||||
If topic is a file path (exists on disk) — read file content as topic.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Init + Display
|
||||
|
||||
**EXECUTE** using Bash tool:
|
||||
```bash
|
||||
bash "${CLAUDE_SKILL_DIR}/scripts/init-log.sh" && echo "INIT_OK" || echo "INIT_FAILED"
|
||||
```
|
||||
|
||||
> **STOP if INIT_FAILED** — cannot create report directory.
|
||||
|
||||
Capture output — it prints:
|
||||
```
|
||||
REPORT_DIR=<path>
|
||||
LOG_FILE=<path>
|
||||
```
|
||||
|
||||
Store `REPORT_DIR` and `LOG_FILE` for all subsequent phases.
|
||||
|
||||
Display to user:
|
||||
|
||||
```
|
||||
Debate Setup
|
||||
Mode: {detected_mode}
|
||||
Agents: {n}
|
||||
Max rounds: {r}
|
||||
Report: {REPORT_DIR}
|
||||
Log: {LOG_FILE}
|
||||
Topic: {topic_summary}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: User Interview
|
||||
|
||||
Ask user using AskUserQuestion tool:
|
||||
|
||||
> **Debate configuration:**
|
||||
>
|
||||
> Mode: **{mode}** | Agents: **{n}** | Max rounds: **{r}**
|
||||
> Topic: {topic_first_100_chars}
|
||||
>
|
||||
> Options:
|
||||
> 1. Proceed with these settings
|
||||
> 2. Change mode (challenge/strategy/critic)
|
||||
> 3. Change agent count (2-5)
|
||||
> 4. Change max rounds
|
||||
> 5. Describe custom agent profiles (instead of auto-generated)
|
||||
|
||||
Apply any user changes. If user provides custom profiles — skip auto-generation in Phase 4 and use their descriptions.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Agent Profiles
|
||||
|
||||
Read reference for agent generation:
|
||||
|
||||
Read file: `${CLAUDE_SKILL_DIR}/references/setup-flow.md`
|
||||
|
||||
Follow setup-flow.md to generate agent profiles. Result: a table of agents with name, role, character archetype, perspective, and WHY chosen.
|
||||
|
||||
Display agent table to user. Ask confirmation using AskUserQuestion:
|
||||
|
||||
> **Agent Team:**
|
||||
>
|
||||
> | # | Name | Role | Archetype | Perspective |
|
||||
> |---|------|------|-----------|-------------|
|
||||
> | ... | ... | ... | ... | ... |
|
||||
>
|
||||
> Options:
|
||||
> 1. Proceed
|
||||
> 2. Swap an agent (specify which)
|
||||
> 3. Regenerate all
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Discovery (Mandatory)
|
||||
|
||||
Research phase — gather current, verified information before debate begins.
|
||||
|
||||
Read file: `${CLAUDE_SKILL_DIR}/references/discovery-flow.md`
|
||||
|
||||
Follow discovery-flow.md to spawn parallel research agents:
|
||||
1. **Codebase Explorer** — searches project for relevant code, patterns, dependencies
|
||||
2. **Web Researcher** — searches internet for current best practices, official docs, recent changes
|
||||
|
||||
All findings saved to `{REPORT_DIR}/discovery.md` with sources.
|
||||
|
||||
> **Every debate argument in Phase 6 MUST reference findings from discovery.md.**
|
||||
> Unsourced claims are not valid arguments.
|
||||
|
||||
Display discovery summary to user before proceeding to debate.
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Debate
|
||||
|
||||
Load mode-specific flow reference and execute debate.
|
||||
|
||||
| Mode | Reference |
|
||||
|------|-----------|
|
||||
| challenge | `${CLAUDE_SKILL_DIR}/references/challenge-flow.md` |
|
||||
| strategy | `${CLAUDE_SKILL_DIR}/references/strategy-flow.md` |
|
||||
| critic | `${CLAUDE_SKILL_DIR}/references/critic-flow.md` |
|
||||
|
||||
Read the matching reference file and follow its instructions exactly.
|
||||
|
||||
**Agent spawning:** Use Task tool with `subagent_type: "general-purpose"`. Build each agent's prompt dynamically by combining:
|
||||
1. Base template from `${CLAUDE_SKILL_DIR}/agents/debater-template.md`
|
||||
2. Role overlay from `${CLAUDE_SKILL_DIR}/agents/{role}-template.md`
|
||||
3. Agent's character traits from archetypes
|
||||
4. Discovery findings from `{REPORT_DIR}/discovery.md` (injected as Evidence Base)
|
||||
5. Current debate context (recent JSONL entries)
|
||||
|
||||
**After each agent turn**, append to log:
|
||||
|
||||
**EXECUTE** using Bash tool:
|
||||
```bash
|
||||
bash "${CLAUDE_SKILL_DIR}/scripts/append-log.sh" "LOG_FILE_PATH" '{"ts":"...","from":"agent-name","to":["targets"],"what":"<20 words","why":"<40 words (include [Source: #N] refs)","type":"argument","mode":"MODE"}'
|
||||
```
|
||||
|
||||
**Judge interventions** (main session): After each round, evaluate if consensus emerging, redirect if stuck, end early if unanimous agreement.
|
||||
|
||||
---
|
||||
|
||||
## Phase 7: Summary
|
||||
|
||||
Read file: `${CLAUDE_SKILL_DIR}/references/summary-flow.md`
|
||||
|
||||
Follow summary-flow.md:
|
||||
1. Read full debate log and `{REPORT_DIR}/discovery.md`
|
||||
2. Spawn secretary agent to write `summary.md` in REPORT_DIR
|
||||
|
||||
---
|
||||
|
||||
## Phase 8: Decision
|
||||
|
||||
Judge (main session) writes `decisions.md`:
|
||||
- Winning position or synthesized result
|
||||
- Key arguments that decided the outcome
|
||||
- Minority opinions worth noting
|
||||
- Confidence level: high / medium / low
|
||||
- Recommended next steps
|
||||
|
||||
Write to: `{REPORT_DIR}/decisions.md`
|
||||
|
||||
---
|
||||
|
||||
## Phase 9: Final Output
|
||||
|
||||
Display final status:
|
||||
|
||||
```
|
||||
Debate Complete
|
||||
Mode: {mode}
|
||||
Rounds: {actual_rounds}/{max_rounds}
|
||||
Outcome: {consensus | partial | no-consensus}
|
||||
Agents: {agent_table_brief}
|
||||
|
||||
Decisions (top 3-5):
|
||||
- {bullet_1}
|
||||
- {bullet_2}
|
||||
- {bullet_3}
|
||||
|
||||
Artifacts:
|
||||
- {REPORT_DIR}/discovery.md
|
||||
- {REPORT_DIR}/decisions.md
|
||||
- {REPORT_DIR}/summary.md
|
||||
- {REPORT_DIR}/debate-log.jsonl
|
||||
```
|
||||
|
||||
If `--review` flag was set:
|
||||
|
||||
Invoke: `Skill(skill="brewcode:standards-review", args="{REPORT_DIR}")`
|
||||
@@ -0,0 +1,25 @@
|
||||
# Agent Character Archetypes
|
||||
|
||||
10 archetypes that define HOW an agent argues. Combined with roles (defender/critic/strategist) to create unique debate personas.
|
||||
|
||||
| # | Archetype | Traits | Arguing Style | Best For |
|
||||
|---|-----------|--------|---------------|----------|
|
||||
| 1 | **Pragmatist** | Practical, results-oriented, impatient with theory | "What actually works in production?" Cites real-world outcomes, dismisses hypotheticals | Challenge: defender of proven solutions; Strategy: incremental approach |
|
||||
| 2 | **Visionary** | Big-picture, future-oriented, tolerates ambiguity | "Where is this heading in 5 years?" Argues from trends, first principles, emerging patterns | Strategy: transformative proposals; Challenge: defender of innovative options |
|
||||
| 3 | **Skeptic** | Cautious, evidence-demanding, risk-aware | "Show me the data." Demands proof, finds edge cases, stress-tests assumptions | Critic: any mode; Challenge: critic role |
|
||||
| 4 | **Architect** | Systematic, pattern-focused, thinks in structures | "How does this fit the bigger system?" Argues from design principles, consistency, modularity | Strategy: system-level proposals; Critic: structural analysis |
|
||||
| 5 | **Operator** | Operations-minded, reliability-focused, practical | "Who maintains this at 3 AM?" Argues from operational reality, monitoring, incident response | Critic: operational risks; Challenge: defender of reliable options |
|
||||
| 6 | **Advocate** | User-centric, empathetic, accessibility-aware | "What does the end user experience?" Argues from UX, adoption, accessibility, learning curve | Challenge: defender of user-friendly options; Critic: usability gaps |
|
||||
| 7 | **Economist** | Cost-conscious, ROI-focused, quantitative | "What's the total cost of ownership?" Argues with numbers, trade-off matrices, opportunity cost | Strategy: cost-benefit analysis; Critic: financial risks |
|
||||
| 8 | **Historian** | Pattern-matching, precedent-aware, cautious about repetition | "We tried this in 2019 and it failed because..." Argues from past failures, industry case studies | Critic: pattern recognition; Challenge: historical context |
|
||||
| 9 | **Provocateur** | Contrarian, challenges consensus, creative | "What if we're solving the wrong problem?" Reframes the debate, asks uncomfortable questions | Critic: assumption-busting; Strategy: alternative framing |
|
||||
| 10 | **Diplomat** | Consensus-seeking, synthesizing, bridge-building | "I hear both sides — what if we combine..." Finds common ground, proposes compromises | Strategy: synthesis; Challenge: final-round mediation |
|
||||
|
||||
## Usage
|
||||
|
||||
When generating agent profiles, select archetypes that create productive tension:
|
||||
- Challenge mode: mix defenders and critics with contrasting archetypes (e.g., Pragmatist defender vs Visionary critic)
|
||||
- Strategy mode: select archetypes that approach problems from genuinely different angles
|
||||
- Critic mode: choose archetypes that find different TYPES of issues (technical, operational, financial, user-facing)
|
||||
|
||||
Avoid pairing archetypes that argue identically (e.g., Pragmatist + Operator both focus on practical concerns).
|
||||
@@ -0,0 +1,43 @@
|
||||
# Critic Role Overlay (Challenge + Critic Modes)
|
||||
|
||||
## Role: Critic
|
||||
|
||||
You are assigned to CRITIQUE — find weaknesses, risks, and flaws. Your job is rigorous adversarial analysis.
|
||||
|
||||
## Critic Behavior
|
||||
|
||||
- Attack the weakest points of each proposal/variant
|
||||
- Ask probing questions that expose hidden assumptions
|
||||
- Identify risks: technical debt, scalability limits, security gaps, maintenance burden
|
||||
- Compare against industry standards and known failure modes
|
||||
- Propose severity levels for each issue found
|
||||
- Suggest mitigations when pointing out problems (not just negativity)
|
||||
|
||||
## Critic Focus Areas
|
||||
|
||||
| Area | Questions |
|
||||
|------|-----------|
|
||||
| Feasibility | Can this actually be built/done with available resources? |
|
||||
| Scalability | What breaks at 10x / 100x scale? |
|
||||
| Maintenance | Who maintains this in 2 years? What's the bus factor? |
|
||||
| Edge cases | What happens with empty input, max load, network failure? |
|
||||
| Dependencies | What external factors could derail this? |
|
||||
| Alternatives | Is there a simpler way that was overlooked? |
|
||||
|
||||
## Critic Strategy
|
||||
|
||||
1. **Identify:** Pick the most critical flaw, not the most obvious
|
||||
2. **Evidence:** Show WHY it's a flaw with concrete scenarios
|
||||
3. **Severity:** Rate as critical / major / minor
|
||||
4. **Mitigation:** Suggest a fix or workaround (constructive criticism)
|
||||
|
||||
## Evidence Citation
|
||||
|
||||
Your critique MUST cite specific evidence. When pointing out weaknesses, reference the source that supports your claim: [Source: #N]. Unsourced criticisms carry less weight.
|
||||
|
||||
## Do NOT
|
||||
|
||||
- Criticize style or formatting — focus on substance
|
||||
- Repeat criticisms already raised by other critics
|
||||
- Be negative without constructive alternatives
|
||||
- Dismiss entire proposals over minor issues
|
||||
@@ -0,0 +1,56 @@
|
||||
# Debater Base Template
|
||||
|
||||
You are **{AGENT_NAME}**, a debate participant with the character archetype **{ARCHETYPE}**.
|
||||
|
||||
## Your Identity
|
||||
|
||||
- **Name:** {AGENT_NAME}
|
||||
- **Role:** {ROLE} (defender / critic / strategist)
|
||||
- **Archetype:** {ARCHETYPE}
|
||||
- **Traits:** {TRAITS}
|
||||
- **Perspective:** {PERSPECTIVE}
|
||||
|
||||
## Debate Context
|
||||
|
||||
- **Mode:** {MODE}
|
||||
- **Topic:** {TOPIC}
|
||||
- **Round:** {CURRENT_ROUND} of {MAX_ROUNDS}
|
||||
|
||||
## Evidence Base
|
||||
|
||||
{DISCOVERY_FINDINGS}
|
||||
|
||||
**RULE: Every argument you make MUST reference at least one finding from the evidence base above. Use format: [Source: #N] where N is the finding number. Unsourced claims are not valid.**
|
||||
|
||||
## Previous Discussion
|
||||
|
||||
{RECENT_LOG_ENTRIES}
|
||||
|
||||
If no entries above, you are speaking first in this debate.
|
||||
|
||||
## Rules
|
||||
|
||||
1. Stay in character — your archetype defines HOW you argue, not WHAT you argue
|
||||
2. Address specific points from previous speakers by name
|
||||
3. Provide concrete evidence, examples, or reasoning
|
||||
4. Acknowledge strong counterarguments — concede when genuinely convinced
|
||||
5. Keep responses focused: 200-400 words
|
||||
6. End with a clear position statement
|
||||
|
||||
## Response Format
|
||||
|
||||
```
|
||||
### {AGENT_NAME} — Round {CURRENT_ROUND}
|
||||
|
||||
**Position:** [1-sentence stance]
|
||||
|
||||
[Your argument — 200-400 words, addressing previous points]
|
||||
|
||||
**Status:** [holding | shifting | conceding]
|
||||
**Confidence:** [high | medium | low]
|
||||
**Key point:** [single most important argument in <20 words]
|
||||
```
|
||||
|
||||
## What to return
|
||||
|
||||
Return ONLY your debate response in the format above. Do not add meta-commentary about the debate process.
|
||||
@@ -0,0 +1,36 @@
|
||||
# Defender Role Overlay (Challenge Mode)
|
||||
|
||||
## Role: Defender
|
||||
|
||||
You are assigned to DEFEND a specific variant/position. Your job is to make the strongest possible case FOR it.
|
||||
|
||||
## Defender Behavior
|
||||
|
||||
- Present the strongest arguments for your assigned variant
|
||||
- Anticipate and preemptively address likely criticisms
|
||||
- Find real-world evidence, precedents, and success stories
|
||||
- Highlight unique advantages that no other variant offers
|
||||
- When attacked, strengthen your argument rather than deflecting
|
||||
- Concede minor points gracefully to maintain credibility on major ones
|
||||
|
||||
## Assigned Variant
|
||||
|
||||
**Variant:** {VARIANT_DESCRIPTION}
|
||||
|
||||
## Defender Strategy
|
||||
|
||||
1. **Open:** State your variant's core value proposition clearly
|
||||
2. **Build:** Layer supporting evidence — technical, practical, strategic
|
||||
3. **Counter:** Address the strongest criticism head-on
|
||||
4. **Close:** Reaffirm why this variant wins on the criteria that matter most
|
||||
|
||||
## Evidence Citation
|
||||
|
||||
Your defense MUST cite specific evidence from the discovery findings. Reference sources by number: [Source: #N]. Every major claim requires at least one source.
|
||||
|
||||
## Do NOT
|
||||
|
||||
- Attack other variants without first strengthening your own
|
||||
- Ignore legitimate weaknesses — acknowledge and reframe
|
||||
- Repeat the same argument with different words
|
||||
- Abandon your position unless the counterargument is genuinely irrefutable
|
||||
@@ -0,0 +1,82 @@
|
||||
# Secretary Agent
|
||||
|
||||
You are the **Secretary** — a neutral observer who produces an accurate, structured summary of the debate.
|
||||
|
||||
## Input
|
||||
|
||||
You will receive:
|
||||
1. The debate topic
|
||||
2. The full debate log (JSONL entries)
|
||||
3. The list of agents with their roles and archetypes
|
||||
|
||||
## Task
|
||||
|
||||
Write `summary.md` — a comprehensive debate summary.
|
||||
|
||||
## Output Format
|
||||
|
||||
```markdown
|
||||
# Debate Summary
|
||||
|
||||
## Topic
|
||||
{topic}
|
||||
|
||||
## Participants
|
||||
|
||||
| Agent | Role | Archetype | Final Position |
|
||||
|-------|------|-----------|----------------|
|
||||
| ... | ... | ... | ... |
|
||||
|
||||
## Key Arguments
|
||||
|
||||
### Round-by-Round
|
||||
|
||||
#### Round 1
|
||||
- **{agent}:** {key point} ({type}: argument/counter/proposal)
|
||||
- ...
|
||||
|
||||
#### Round N
|
||||
...
|
||||
|
||||
### Strongest Arguments
|
||||
|
||||
| Rank | Agent | Argument | Impact |
|
||||
|------|-------|----------|--------|
|
||||
| 1 | ... | ... | Changed N positions |
|
||||
| 2 | ... | ... | ... |
|
||||
|
||||
## Points of Agreement
|
||||
- {shared conclusion 1}
|
||||
- {shared conclusion 2}
|
||||
|
||||
## Unresolved Disagreements
|
||||
- {disagreement 1}: {agent_a} vs {agent_b}
|
||||
- {disagreement 2}: ...
|
||||
|
||||
## Consensus Level
|
||||
{unanimous | strong-majority | weak-majority | split | no-consensus}
|
||||
|
||||
## Statistics
|
||||
- Rounds: {N}
|
||||
- Total arguments: {N}
|
||||
- Position changes: {N}
|
||||
- Questions asked: {N}
|
||||
```
|
||||
|
||||
## Mode-Specific Format
|
||||
|
||||
Adapt your summary structure to the debate mode:
|
||||
|
||||
| Mode | Focus |
|
||||
|------|-------|
|
||||
| Challenge | Round-by-round with position tracking per variant; highlight which agents shifted toward which variant |
|
||||
| Strategy | Proposals comparison table + synthesis narrative; track how proposals evolved and merged |
|
||||
| Critic | Issue consolidation matrix — group by severity, show consensus level per issue across critics |
|
||||
|
||||
## Rules
|
||||
|
||||
1. Be strictly neutral — do not judge which side is correct
|
||||
2. Attribute every point to the agent who made it
|
||||
3. Distinguish between arguments, counterarguments, proposals, and concessions
|
||||
4. Track position changes explicitly
|
||||
5. Keep the summary factual — no interpretation or recommendation
|
||||
@@ -0,0 +1,42 @@
|
||||
# Strategist Role Overlay (Strategy Mode)
|
||||
|
||||
## Role: Strategist
|
||||
|
||||
You independently analyze the problem and propose your own approach. Then defend it in debate.
|
||||
|
||||
## Strategist Behavior
|
||||
|
||||
- Think from first principles — don't anchor on others' proposals
|
||||
- Consider the full problem lifecycle: design, implementation, operation, evolution
|
||||
- Quantify trade-offs where possible (cost, time, complexity, risk)
|
||||
- Map dependencies and critical path
|
||||
- Identify what must be true for your approach to succeed (assumptions)
|
||||
- Propose concrete next steps, not abstract recommendations
|
||||
|
||||
## Strategy Framework
|
||||
|
||||
1. **Problem reframe:** State the core problem in your own words (may differ from original framing)
|
||||
2. **Approach:** Your proposed strategy in 3-5 key decisions
|
||||
3. **Trade-offs:** What you gain vs. what you sacrifice
|
||||
4. **Risks:** Top 2-3 risks and mitigations
|
||||
5. **Timeline:** Rough phases and milestones
|
||||
6. **Success criteria:** How to measure if this approach worked
|
||||
|
||||
## In Debate Phase
|
||||
|
||||
When responding to other strategists:
|
||||
- Find synthesis opportunities — combine the best parts of multiple approaches
|
||||
- Identify genuine conflicts vs. apparent conflicts (different words, same idea)
|
||||
- Propose hybrid approaches when pure approaches have complementary weaknesses
|
||||
- Challenge assumptions, not conclusions
|
||||
|
||||
## Evidence Citation
|
||||
|
||||
Your proposal MUST be grounded in evidence from the discovery findings. Reference sources for every key decision: [Source: #N]. Unsourced recommendations are not valid.
|
||||
|
||||
## Do NOT
|
||||
|
||||
- Copy another strategist's approach with minor modifications
|
||||
- Propose an approach you wouldn't actually recommend in practice
|
||||
- Ignore implementation reality for theoretical elegance
|
||||
- Refuse to synthesize when two approaches are genuinely compatible
|
||||
@@ -0,0 +1,96 @@
|
||||
# Challenge Mode Debate Flow
|
||||
|
||||
## Overview
|
||||
|
||||
Defenders present and argue FOR variant(s), critics attack. Sequential rounds until consensus, judge intervention, or max rounds reached.
|
||||
|
||||
## Pre-Debate Setup
|
||||
|
||||
1. Read agent templates:
|
||||
- `${CLAUDE_SKILL_DIR}/agents/debater-template.md` (base)
|
||||
- `${CLAUDE_SKILL_DIR}/agents/defender-template.md` (defender overlay)
|
||||
- `${CLAUDE_SKILL_DIR}/agents/critic-template.md` (critic overlay)
|
||||
|
||||
2. If topic has explicit variants — assign to defenders
|
||||
3. If no explicit variants — defenders propose their own in round 1
|
||||
|
||||
## Round Structure
|
||||
|
||||
Each round = all agents speak once, in order: defenders first, then critics.
|
||||
|
||||
### Round 1: Opening Statements
|
||||
|
||||
**Defenders:** Present their variant(s). If no pre-defined variants, each defender proposes one.
|
||||
|
||||
**Critics:** Initial critique of all presented variants.
|
||||
|
||||
### Rounds 2-N: Rebuttals
|
||||
|
||||
**Defenders:** Respond to criticisms, strengthen their position.
|
||||
|
||||
**Critics:** Dig deeper, raise new concerns, or acknowledge addressed issues.
|
||||
|
||||
## Agent Spawning (per turn)
|
||||
|
||||
For each agent's turn, spawn via Task tool:
|
||||
|
||||
```
|
||||
Task(
|
||||
description: "{agent_name} round {N}",
|
||||
prompt: "{combined_prompt}",
|
||||
subagent_type: "general-purpose"
|
||||
)
|
||||
```
|
||||
|
||||
Build `{combined_prompt}` by:
|
||||
1. Reading base template, replacing placeholders: AGENT_NAME, ROLE, ARCHETYPE, TRAITS, PERSPECTIVE, MODE, TOPIC, CURRENT_ROUND, MAX_ROUNDS, VARIANT_DESCRIPTION, DISCOVERY_FINDINGS
|
||||
2. Appending role overlay (defender or critic)
|
||||
3. Including relevant discovery findings in each agent's prompt — agents must cite evidence
|
||||
4. Appending recent log entries (last 2 rounds or all if short)
|
||||
|
||||
## After Each Agent Turn
|
||||
|
||||
1. Extract key points from agent's response
|
||||
2. Append to JSONL log:
|
||||
|
||||
**EXECUTE** using Bash tool:
|
||||
```bash
|
||||
bash "${CLAUDE_SKILL_DIR}/scripts/append-log.sh" "LOG_FILE" '{"ts":"TIMESTAMP","from":"AGENT_NAME","to":["TARGET_AGENTS"],"what":"SUMMARY_20_WORDS","why":"REASONING_40_WORDS","type":"argument|counter|agree","mode":"challenge"}'
|
||||
```
|
||||
|
||||
## Judge Evaluation (After Each Round)
|
||||
|
||||
After all agents have spoken in a round, the judge (main session) evaluates:
|
||||
|
||||
| Signal | Action |
|
||||
|--------|--------|
|
||||
| All agents agree on one variant | End debate — declare consensus |
|
||||
| Clear majority (>60%) favoring one | Ask minority for final objection, then end |
|
||||
| Debate is circular (same arguments repeated) | Introduce a new constraint or angle to break deadlock |
|
||||
| Agents talking past each other | Redirect: "Agent X, address Agent Y's point about Z specifically" |
|
||||
| Max rounds reached | End debate — summarize current state |
|
||||
|
||||
### Judge Log Entry
|
||||
|
||||
After evaluation, append judge entry:
|
||||
|
||||
**EXECUTE** using Bash tool:
|
||||
```bash
|
||||
bash "${CLAUDE_SKILL_DIR}/scripts/append-log.sh" "LOG_FILE" '{"ts":"TIMESTAMP","from":"judge","to":["all"],"what":"JUDGE_SUMMARY","why":"JUDGE_REASONING","type":"redirect|agree","mode":"challenge"}'
|
||||
```
|
||||
|
||||
## Convergence Detection
|
||||
|
||||
Track each agent's position across rounds:
|
||||
|
||||
| Change | Meaning |
|
||||
|--------|---------|
|
||||
| `holding` | Agent maintains position — no convergence |
|
||||
| `shifting` | Agent moving toward another position — convergence in progress |
|
||||
| `conceding` | Agent concedes — convergence achieved for this agent |
|
||||
|
||||
**Early exit:** If all agents report `conceding` or `shifting` toward same variant — end debate.
|
||||
|
||||
## Output
|
||||
|
||||
Debate log (JSONL) is complete. Proceed to Phase 7 (Summary).
|
||||
@@ -0,0 +1,89 @@
|
||||
# Critic Mode Debate Flow
|
||||
|
||||
## Overview
|
||||
|
||||
All agents are critics with different perspectives. No defender — the document/plan/code itself is the target. Goal: find all weaknesses, risks, and flaws.
|
||||
|
||||
## Pre-Debate Setup
|
||||
|
||||
1. Read agent templates:
|
||||
- `${CLAUDE_SKILL_DIR}/agents/debater-template.md` (base)
|
||||
- `${CLAUDE_SKILL_DIR}/agents/critic-template.md` (critic overlay)
|
||||
|
||||
2. Load the target material:
|
||||
- If topic is a file path — read file content
|
||||
- If topic is text — use directly
|
||||
- If topic references code — use Grep/Glob to gather context
|
||||
|
||||
## Round Structure
|
||||
|
||||
### Round 1: Independent Critique
|
||||
|
||||
Each critic independently reviews the target from their archetype's perspective. No access to other critics' findings.
|
||||
|
||||
Spawn each critic with:
|
||||
- Base template + critic overlay
|
||||
- Target material
|
||||
- Discovery findings (replace `{DISCOVERY_FINDINGS}` with evidence from `{REPORT_DIR}/discovery.md`) — critics must cite evidence
|
||||
- Instruction: "Find issues from your perspective. Do NOT repeat what's obvious — dig deep. Cite discovery sources."
|
||||
|
||||
Each critic outputs issues in format:
|
||||
```
|
||||
| # | Severity | Issue | Evidence | Mitigation |
|
||||
|---|----------|-------|----------|------------|
|
||||
| 1 | critical | ... | ... | ... |
|
||||
```
|
||||
|
||||
After each critic, append to log with `type: "argument"`.
|
||||
|
||||
### Round 2+: Cross-Critique
|
||||
|
||||
Critics now see each other's findings. In subsequent rounds:
|
||||
|
||||
1. **Validate:** Agree or disagree with other critics' findings
|
||||
2. **Deepen:** Add depth to issues others found superficially
|
||||
3. **Discover:** Find new issues inspired by others' perspectives
|
||||
4. **Prioritize:** Argue for severity adjustments
|
||||
|
||||
Build prompts with:
|
||||
- Base template + critic overlay
|
||||
- Target material
|
||||
- Discovery findings (replace `{DISCOVERY_FINDINGS}`)
|
||||
- ALL previous findings (log entries)
|
||||
- Instruction: "Review other critics' findings. Validate, deepen, discover, or re-prioritize. Cite discovery sources."
|
||||
|
||||
## Judge Evaluation (After Each Round)
|
||||
|
||||
| Signal | Action |
|
||||
|--------|--------|
|
||||
| Critics finding new issues | Continue — productive |
|
||||
| Critics only agreeing with each other | End debate — diminishing returns |
|
||||
| Severity disagreements | Judge mediates: "Critics A and B, defend your severity rating for issue X" |
|
||||
| Duplicate findings | Judge consolidates and redirects |
|
||||
| Max rounds reached | End debate |
|
||||
|
||||
Judge log entry after each round:
|
||||
|
||||
**EXECUTE** using Bash tool:
|
||||
```bash
|
||||
bash "${CLAUDE_SKILL_DIR}/scripts/append-log.sh" "LOG_FILE" '{"ts":"TIMESTAMP","from":"judge","to":["all"],"what":"SUMMARY","why":"REASONING","type":"redirect","mode":"critic"}'
|
||||
```
|
||||
|
||||
## Issue Consolidation
|
||||
|
||||
After debate ends, judge consolidates all issues into a master list:
|
||||
|
||||
| # | Severity | Issue | Found By | Agreed By | Mitigation | Status |
|
||||
|---|----------|-------|----------|-----------|------------|--------|
|
||||
| 1 | critical | ... | critic-1 | critic-2, critic-3 | ... | confirmed |
|
||||
| 2 | major | ... | critic-2 | — | ... | disputed |
|
||||
|
||||
Severity scale:
|
||||
- **critical** — must fix, blocks progress
|
||||
- **major** — should fix, significant risk
|
||||
- **minor** — nice to fix, low risk
|
||||
- **info** — observation, no action needed
|
||||
|
||||
## Output
|
||||
|
||||
JSONL log + consolidated issue list. Proceed to Phase 7 (Summary).
|
||||
@@ -0,0 +1,58 @@
|
||||
# Discovery Flow
|
||||
|
||||
## Purpose
|
||||
|
||||
Before any debate, research agents gather current, verified information on the topic. All debate arguments must be backed by evidence and sources.
|
||||
|
||||
## Process
|
||||
|
||||
Spawn 2-3 agents IN PARALLEL using Task tool:
|
||||
|
||||
| Agent | subagent_type | Focus | Tools |
|
||||
|-------|---------------|-------|-------|
|
||||
| Codebase Explorer | Explore | Project code, configs, patterns, dependencies related to the topic | Glob, Grep, Read |
|
||||
| Web Researcher 1 | general-purpose | Current information, best practices, recent changes, official docs | WebSearch, WebFetch |
|
||||
| Web Researcher 2 (complex topics only) | general-purpose | Alternative viewpoints, competing approaches, known issues, community discussions | WebSearch, WebFetch |
|
||||
|
||||
**When to spawn Web Researcher 2:** Topic involves external technologies, frameworks, or architectural decisions with multiple competing approaches.
|
||||
|
||||
## Output Format (per agent)
|
||||
|
||||
```markdown
|
||||
## Findings: {agent_role}
|
||||
|
||||
### Finding 1: {title}
|
||||
- **Source:** {URL or file path}
|
||||
- **Date:** {when published/last updated}
|
||||
- **Key facts:** {2-3 bullet points}
|
||||
- **Relevance:** {why this matters for the debate}
|
||||
|
||||
### Finding 2: ...
|
||||
```
|
||||
|
||||
## Aggregation
|
||||
|
||||
Combine all findings into `{REPORT_DIR}/discovery.md`:
|
||||
|
||||
1. Deduplicate overlapping findings
|
||||
2. Flag conflicting information from different sources
|
||||
3. Create Evidence Summary table:
|
||||
|
||||
```markdown
|
||||
## Evidence Summary
|
||||
|
||||
| # | Fact | Source | Verified |
|
||||
|---|------|--------|----------|
|
||||
| 1 | ... | URL/path | yes/no |
|
||||
| 2 | ... | URL/path | yes/no |
|
||||
```
|
||||
|
||||
## Rules
|
||||
|
||||
| Rule | Details |
|
||||
|------|---------|
|
||||
| Minimum findings | 3 per agent |
|
||||
| Source requirement | Every finding MUST have a source (URL, file path, or doc reference) |
|
||||
| Common knowledge | Still needs a source reference |
|
||||
| Stale data | Flag findings older than 1 year as potentially stale |
|
||||
| Conflicts | Explicitly note when sources disagree — both sides cited |
|
||||
@@ -0,0 +1,85 @@
|
||||
# Agent Profile Generation (Setup Flow)
|
||||
|
||||
## Input
|
||||
|
||||
- Topic text
|
||||
- Mode: challenge / strategy / critic
|
||||
- Agent count: N (2-5)
|
||||
- Archetypes (loaded from `agents/archetypes.md`)
|
||||
- Optional: user-provided custom profiles
|
||||
|
||||
## Step 1: Domain Detection
|
||||
|
||||
Analyze the topic to identify domain(s):
|
||||
|
||||
| Domain | Indicators |
|
||||
|--------|------------|
|
||||
| Backend | API, database, server, microservices, scalability |
|
||||
| Frontend | UI, UX, components, design system, accessibility |
|
||||
| Infrastructure | deploy, CI/CD, containers, cloud, monitoring |
|
||||
| Architecture | patterns, modules, coupling, system design |
|
||||
| Data | pipeline, analytics, ML, storage, ETL |
|
||||
| Business | cost, ROI, timeline, stakeholders, requirements |
|
||||
| Security | auth, encryption, vulnerability, compliance |
|
||||
| General | none of the above — use broad archetypes |
|
||||
|
||||
Multiple domains possible. Primary domain = most referenced in topic.
|
||||
|
||||
## Step 2: Role Assignment (Mode-Aware)
|
||||
|
||||
### Challenge Mode
|
||||
|
||||
| N agents | Defenders | Critics |
|
||||
|----------|-----------|---------|
|
||||
| 2 | 1 | 1 |
|
||||
| 3 | 1 | 2 |
|
||||
| 4 | 2 | 2 |
|
||||
| 5 | 2 | 3 |
|
||||
|
||||
If topic contains explicit variants (e.g., "Option A vs Option B"):
|
||||
- Assign each defender to a specific variant
|
||||
- Critics attack all variants equally
|
||||
|
||||
### Strategy Mode
|
||||
|
||||
All agents are **strategists**. Each proposes independently.
|
||||
|
||||
### Critic Mode
|
||||
|
||||
All agents are **critics**. Each critiques from a different perspective.
|
||||
|
||||
## Step 3: Character Selection
|
||||
|
||||
For each agent, select an archetype from the 10 available. Rules:
|
||||
|
||||
1. **Maximize diversity** — no two agents share an archetype
|
||||
2. **Match domain** — prefer archetypes listed as "Best For" matching the topic domain
|
||||
3. **Create tension** — pair archetypes with naturally opposing viewpoints
|
||||
4. **Avoid redundancy** — if two archetypes would argue identically on this topic, replace one
|
||||
|
||||
### Selection priority by mode
|
||||
|
||||
| Mode | Prefer | Avoid |
|
||||
|------|--------|-------|
|
||||
| Challenge | Opposing pairs (Pragmatist vs Visionary, Skeptic vs Advocate) | Two similar critics |
|
||||
| Strategy | Maximum perspective diversity | Two archetypes that approach same way |
|
||||
| Critic | Different issue types (technical, ops, financial, UX) | All-technical team |
|
||||
|
||||
## Step 4: Generate Profiles
|
||||
|
||||
For each agent, produce:
|
||||
|
||||
```
|
||||
Agent {N}:
|
||||
Name: {descriptive_name} (e.g., "Ops-Realist", "Cost-Analyst", "UX-Champion")
|
||||
Role: defender / critic / strategist
|
||||
Archetype: {from archetypes.md}
|
||||
Perspective: {1-sentence: what angle they bring}
|
||||
WHY chosen: {1-sentence: why this archetype for this topic}
|
||||
```
|
||||
|
||||
Names should be short (1-2 words with hyphen), descriptive, and unique within the team.
|
||||
|
||||
## Step 5: Display for Confirmation
|
||||
|
||||
Present the full agent table to the user for approval before proceeding to debate.
|
||||
@@ -0,0 +1,84 @@
|
||||
# Strategy Mode Debate Flow
|
||||
|
||||
## Overview
|
||||
|
||||
Three-phase flow: independent proposals, judge-ordered presentation, convergence debate. All agents are strategists.
|
||||
|
||||
## Pre-Debate Setup
|
||||
|
||||
1. Read agent templates:
|
||||
- `${CLAUDE_SKILL_DIR}/agents/debater-template.md` (base)
|
||||
- `${CLAUDE_SKILL_DIR}/agents/strategist-template.md` (strategist overlay)
|
||||
|
||||
## Phase A: Independent Proposals
|
||||
|
||||
Each strategist independently analyzes the topic and proposes their approach. No access to other proposals.
|
||||
|
||||
For each agent, spawn via Task tool:
|
||||
|
||||
```
|
||||
Task(
|
||||
description: "{agent_name} proposal",
|
||||
prompt: "{combined_prompt_WITHOUT_other_proposals}",
|
||||
subagent_type: "general-purpose"
|
||||
)
|
||||
```
|
||||
|
||||
The prompt includes:
|
||||
- Base template with placeholders filled (set `{RECENT_LOG_ENTRIES}` to "No previous discussion — this is your independent proposal." to prevent later agents from seeing earlier proposals)
|
||||
- Strategist overlay
|
||||
- Discovery findings (replace `{DISCOVERY_FINDINGS}` with evidence from `{REPORT_DIR}/discovery.md`) — agents must cite evidence
|
||||
- Topic only — NO other agents' proposals
|
||||
- Instruction: "Write your independent proposal using the Strategy Framework in your overlay. Cite discovery sources."
|
||||
|
||||
After each proposal, append to log with `type: "proposal"`.
|
||||
|
||||
## Phase B: Judge Orders Presentation
|
||||
|
||||
After all proposals received, judge:
|
||||
|
||||
1. Reads all proposals
|
||||
2. Orders presentation sequence (most different approaches first to maximize contrast)
|
||||
3. Identifies key dimensions where approaches differ
|
||||
|
||||
Log entry:
|
||||
|
||||
**EXECUTE** using Bash tool:
|
||||
```bash
|
||||
bash "${CLAUDE_SKILL_DIR}/scripts/append-log.sh" "LOG_FILE" '{"ts":"TIMESTAMP","from":"judge","to":["all"],"what":"Presentation order: A, B, C","why":"Ordered by maximum contrast on key dimensions","type":"redirect","mode":"strategy"}'
|
||||
```
|
||||
|
||||
## Phase C: Convergence Debate
|
||||
|
||||
Now agents debate — each sees all proposals and previous discussion.
|
||||
|
||||
### Round structure
|
||||
|
||||
Each round, agents respond to each other's proposals. Build prompts with:
|
||||
- Base template + strategist overlay
|
||||
- Discovery findings (replace `{DISCOVERY_FINDINGS}`)
|
||||
- ALL proposals summary
|
||||
- Recent log entries (last 2 rounds)
|
||||
- Judge's identified key dimensions
|
||||
|
||||
### Convergence patterns
|
||||
|
||||
| Pattern | Action |
|
||||
|---------|--------|
|
||||
| Two approaches are complementary | Judge suggests synthesis: "Agents X and Y, explore combining your approaches" |
|
||||
| One approach clearly dominates | Ask its proponents to address remaining weaknesses |
|
||||
| Genuine conflict (mutually exclusive) | Judge frames as explicit trade-off decision |
|
||||
| All approaches converge | End debate — consensus forming |
|
||||
|
||||
### After each round
|
||||
|
||||
Append log entries. Judge evaluates using same convergence detection as Challenge mode.
|
||||
|
||||
## Output
|
||||
|
||||
Complete JSONL log with three phases marked:
|
||||
- `type: "proposal"` — Phase A entries
|
||||
- `type: "redirect"` — Judge ordering (Phase B)
|
||||
- `type: "argument|counter|agree"` — Phase C debate entries
|
||||
|
||||
Proceed to Phase 7 (Summary).
|
||||
@@ -0,0 +1,30 @@
|
||||
# Summary + Decision Flow
|
||||
|
||||
## Phase 6: Secretary Summary
|
||||
|
||||
### Step 1: Read Full Log
|
||||
|
||||
**EXECUTE** using Bash tool:
|
||||
```bash
|
||||
bash "${CLAUDE_SKILL_DIR}/scripts/read-log.sh" "LOG_FILE" all
|
||||
```
|
||||
|
||||
### Step 2: Spawn Secretary
|
||||
|
||||
Read secretary prompt: `${CLAUDE_SKILL_DIR}/agents/secretary.md`
|
||||
|
||||
Spawn secretary via Task tool:
|
||||
|
||||
```
|
||||
Task(
|
||||
description: "Secretary writes debate summary",
|
||||
prompt: "{secretary_prompt}\n\n## Debate Log\n{full_log_content}\n\n## Agent Profiles\n{agent_table}\n\n## Topic\n{topic}",
|
||||
subagent_type: "general-purpose"
|
||||
)
|
||||
```
|
||||
|
||||
### Step 3: Write Summary
|
||||
|
||||
Write secretary's output to `{REPORT_DIR}/summary.md`.
|
||||
|
||||
Proceed to Phase 7 (Decision) in SKILL.md — the judge writes `decisions.md` there.
|
||||
Executable
+60
@@ -0,0 +1,60 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
command -v python3 >/dev/null 2>&1 || { echo "ERROR: python3 required for JSONL validation" >&2; exit 1; }
|
||||
|
||||
# Append entry to debate JSONL log with schema validation
|
||||
# Usage: bash append-log.sh <log_file> '<json_entry>'
|
||||
# Example: bash append-log.sh path/to/debate-log.jsonl '{"ts":"...","from":"agent-1","to":["agent-2"],"what":"summary","why":"reasoning","type":"argument","mode":"challenge"}'
|
||||
|
||||
LOG_FILE="${1:-}"
|
||||
ENTRY="${2:-}"
|
||||
|
||||
if [ -z "$LOG_FILE" ]; then
|
||||
echo "ERROR: log file path required as first argument" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [ -z "$ENTRY" ]; then
|
||||
echo "ERROR: JSON entry required as second argument" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [ ! -f "$LOG_FILE" ]; then
|
||||
echo "ERROR: log file does not exist: $LOG_FILE" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Validate JSON structure using python (available on Mac by default)
|
||||
VALID=$(python3 -c "
|
||||
import json, sys
|
||||
try:
|
||||
d = json.loads(sys.argv[1])
|
||||
required = {'ts', 'from', 'to', 'what', 'why', 'type', 'mode'}
|
||||
missing = required - set(d.keys())
|
||||
if missing:
|
||||
print(f'MISSING_FIELDS: {missing}', file=sys.stderr)
|
||||
sys.exit(1)
|
||||
valid_types = {'argument', 'counter', 'proposal', 'agree', 'question', 'redirect'}
|
||||
if d['type'] not in valid_types:
|
||||
print(f'INVALID_TYPE: {d[\"type\"]} (expected: {valid_types})', file=sys.stderr)
|
||||
sys.exit(1)
|
||||
valid_modes = {'challenge', 'strategy', 'critic'}
|
||||
if d['mode'] not in valid_modes:
|
||||
print(f'INVALID_MODE: {d[\"mode\"]} (expected: {valid_modes})', file=sys.stderr)
|
||||
sys.exit(1)
|
||||
if not isinstance(d['to'], list):
|
||||
print('INVALID_TO: must be array', file=sys.stderr)
|
||||
sys.exit(1)
|
||||
# Output compact JSON (normalized)
|
||||
print(json.dumps(d, ensure_ascii=False, separators=(',', ':')))
|
||||
except json.JSONDecodeError as e:
|
||||
print(f'INVALID_JSON: {e}', file=sys.stderr)
|
||||
sys.exit(1)
|
||||
" "$ENTRY" 2>&1) || {
|
||||
echo "VALIDATION FAILED: $VALID" >&2
|
||||
exit 1
|
||||
}
|
||||
|
||||
echo "$VALID" >> "$LOG_FILE"
|
||||
echo "OK: appended to $LOG_FILE"
|
||||
Executable
+25
@@ -0,0 +1,25 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
# Initialize debate report directory and empty JSONL log
|
||||
# Usage: bash init-log.sh
|
||||
# Output: REPORT_DIR=<path> and LOG_FILE=<path>
|
||||
|
||||
# Timestamp: use gdate if available (Mac + coreutils), fallback to POSIX date
|
||||
if command -v gdate >/dev/null 2>&1; then
|
||||
TS="$(gdate -u +%Y%m%d-%H%M%S)"
|
||||
elif date -u +%Y%m%d-%H%M%S >/dev/null 2>&1; then
|
||||
TS="$(date -u +%Y%m%d-%H%M%S)"
|
||||
else
|
||||
TS="$(date +%Y%m%d-%H%M%S)"
|
||||
fi
|
||||
|
||||
BASE="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
|
||||
REPORT_DIR="${BASE}/.claude/reports/${TS}_debate"
|
||||
LOG_FILE="${REPORT_DIR}/debate-log.jsonl"
|
||||
|
||||
mkdir -p "$REPORT_DIR"
|
||||
touch "$LOG_FILE"
|
||||
|
||||
echo "REPORT_DIR=${REPORT_DIR}"
|
||||
echo "LOG_FILE=${LOG_FILE}"
|
||||
Executable
+106
@@ -0,0 +1,106 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
# Read debate log entries
|
||||
# Usage:
|
||||
# bash read-log.sh <log_file> all — all entries
|
||||
# bash read-log.sh <log_file> last <N> — last N entries
|
||||
# bash read-log.sh <log_file> agent <name> — entries from specific agent
|
||||
# bash read-log.sh <log_file> round <N> — entries from round N (by position)
|
||||
# bash read-log.sh <log_file> stats — summary statistics
|
||||
|
||||
LOG_FILE="${1:-}"
|
||||
CMD="${2:-all}"
|
||||
ARG="${3:-}"
|
||||
|
||||
if [ -z "$LOG_FILE" ]; then
|
||||
echo "ERROR: log file path required" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [ ! -f "$LOG_FILE" ]; then
|
||||
echo "ERROR: log file does not exist: $LOG_FILE" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
case "$CMD" in
|
||||
all)
|
||||
cat "$LOG_FILE"
|
||||
;;
|
||||
last)
|
||||
N="${ARG:-5}"
|
||||
tail -n "$N" "$LOG_FILE"
|
||||
;;
|
||||
agent)
|
||||
if [ -z "$ARG" ]; then
|
||||
echo "ERROR: agent name required" >&2
|
||||
exit 1
|
||||
fi
|
||||
python3 -c "
|
||||
import json, sys
|
||||
for line in open(sys.argv[1]):
|
||||
line = line.strip()
|
||||
if not line: continue
|
||||
d = json.loads(line)
|
||||
if d.get('from') == sys.argv[2]:
|
||||
print(line)
|
||||
" "$LOG_FILE" "$ARG"
|
||||
;;
|
||||
round)
|
||||
if [ -z "$ARG" ]; then
|
||||
echo "ERROR: round number required" >&2
|
||||
exit 1
|
||||
fi
|
||||
N="$ARG"
|
||||
python3 -c "
|
||||
import json, sys
|
||||
entries = []
|
||||
for line in open(sys.argv[1]):
|
||||
line = line.strip()
|
||||
if not line: continue
|
||||
entries.append(json.loads(line))
|
||||
n = int(sys.argv[2])
|
||||
# Determine agent count (unique non-judge 'from' values)
|
||||
agents = sorted(set(e['from'] for e in entries if e['from'] != 'judge'))
|
||||
agent_count = len(agents) if agents else 1
|
||||
# Round N = entries[(N-1)*agent_count : N*agent_count] (judge entries interleaved are included)
|
||||
# Group entries into rounds: each round = agent_count non-judge entries + any judge entries between them
|
||||
non_judge = [(i, e) for i, e in enumerate(entries) if e['from'] != 'judge']
|
||||
total_rounds = (len(non_judge) + agent_count - 1) // agent_count
|
||||
if n < 1 or n > total_rounds:
|
||||
print(f'ERROR: round {n} out of range (1-{total_rounds})', file=sys.stderr)
|
||||
sys.exit(1)
|
||||
start = (n - 1) * agent_count
|
||||
end = min(n * agent_count, len(non_judge))
|
||||
# Get index range in original entries list
|
||||
first_idx = non_judge[start][0] if start < len(non_judge) else 0
|
||||
last_idx = non_judge[end - 1][0] if end > 0 else len(entries) - 1
|
||||
# Include all entries (including judge) within the index range
|
||||
for i, e in enumerate(entries):
|
||||
if first_idx <= i <= last_idx:
|
||||
print(json.dumps(e, ensure_ascii=False, separators=(',', ':')))
|
||||
" "$LOG_FILE" "$N"
|
||||
;;
|
||||
stats)
|
||||
python3 -c "
|
||||
import json, sys
|
||||
entries = []
|
||||
for line in open(sys.argv[1]):
|
||||
line = line.strip()
|
||||
if not line: continue
|
||||
entries.append(json.loads(line))
|
||||
agents = set(e['from'] for e in entries)
|
||||
types = {}
|
||||
for e in entries:
|
||||
types[e['type']] = types.get(e['type'], 0) + 1
|
||||
print(f'Total entries: {len(entries)}')
|
||||
print(f'Agents: {sorted(agents)}')
|
||||
print(f'Types: {dict(sorted(types.items()))}')
|
||||
print(f'Mode: {entries[0][\"mode\"] if entries else \"unknown\"}')
|
||||
" "$LOG_FILE"
|
||||
;;
|
||||
*)
|
||||
echo "ERROR: unknown command '$CMD' (expected: all, last, agent, round, stats)" >&2
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
Executable
+49
@@ -0,0 +1,49 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
# Validate all debate skill files exist
|
||||
# Usage: bash validate.sh
|
||||
# Returns: 0 if all files present, 1 if any missing
|
||||
|
||||
SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
|
||||
MISSING=0
|
||||
|
||||
check_file() {
|
||||
if [ ! -f "$SKILL_DIR/$1" ]; then
|
||||
echo "MISSING: $1"
|
||||
MISSING=$((MISSING + 1))
|
||||
fi
|
||||
}
|
||||
|
||||
# Core
|
||||
check_file "SKILL.md"
|
||||
|
||||
# Agents
|
||||
check_file "agents/debater-template.md"
|
||||
check_file "agents/defender-template.md"
|
||||
check_file "agents/critic-template.md"
|
||||
check_file "agents/strategist-template.md"
|
||||
check_file "agents/secretary.md"
|
||||
check_file "agents/archetypes.md"
|
||||
|
||||
# References
|
||||
check_file "references/setup-flow.md"
|
||||
check_file "references/challenge-flow.md"
|
||||
check_file "references/strategy-flow.md"
|
||||
check_file "references/critic-flow.md"
|
||||
check_file "references/discovery-flow.md"
|
||||
check_file "references/summary-flow.md"
|
||||
|
||||
# Scripts
|
||||
check_file "scripts/validate.sh"
|
||||
check_file "scripts/init-log.sh"
|
||||
check_file "scripts/append-log.sh"
|
||||
check_file "scripts/read-log.sh"
|
||||
|
||||
if [ "$MISSING" -gt 0 ]; then
|
||||
echo "VALIDATION FAILED: $MISSING file(s) missing"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "All debate skill files present ($SKILL_DIR)"
|
||||
exit 0
|
||||
@@ -0,0 +1,29 @@
|
||||
# Test: Challenge Mode — Basic 2-Agent
|
||||
|
||||
## Setup
|
||||
|
||||
```
|
||||
/brewcode:debate REST API vs GraphQL for a new public-facing product catalog API -m challenge -n 2
|
||||
```
|
||||
|
||||
## Expected Behavior
|
||||
|
||||
1. Phase 0: Validation passes
|
||||
2. Phase 1: Parses mode=challenge, n=2, topic="REST API vs GraphQL..."
|
||||
3. Phase 2: Creates report dir, empty log
|
||||
4. Phase 3: User confirms settings
|
||||
5. Phase 4: Generates 1 defender (REST) + 1 critic (GraphQL attacker) — or vice versa
|
||||
6. Phase 5: Challenge flow — at least 2 rounds
|
||||
7. Phase 6: Secretary writes summary.md
|
||||
8. Phase 7: Judge writes decisions.md with selected variant
|
||||
9. Phase 8: Final output with links
|
||||
|
||||
## Assertions
|
||||
|
||||
- [ ] Report dir exists: `.claude/reports/*_debate/`
|
||||
- [ ] `debate-log.jsonl` has entries with `"mode":"challenge"`
|
||||
- [ ] At least 2 entries with `"type":"argument"`
|
||||
- [ ] At least 1 entry with `"from":"judge"`
|
||||
- [ ] `summary.md` exists and contains participant table
|
||||
- [ ] `decisions.md` exists and contains "Selected Variant"
|
||||
- [ ] Final output shows consensus level
|
||||
@@ -0,0 +1,25 @@
|
||||
# Test: Challenge Mode — 5 Agents with 2 Defenders
|
||||
|
||||
## Setup
|
||||
|
||||
```
|
||||
/brewcode:debate "Monolith vs Microservices vs Modular Monolith for a mid-size fintech startup" -m challenge -n 5 -r 4
|
||||
```
|
||||
|
||||
## Expected Behavior
|
||||
|
||||
1. 5 agents generated: 2 defenders + 3 critics
|
||||
2. Defenders assigned to different variants (e.g., one defends Microservices, one defends Modular Monolith)
|
||||
3. 3 critics with distinct archetypes (e.g., Skeptic, Operator, Economist)
|
||||
4. Max 4 rounds
|
||||
5. Each round: 5 log entries (one per agent) + judge entry
|
||||
|
||||
## Assertions
|
||||
|
||||
- [ ] Agent table shows exactly 2 defenders and 3 critics
|
||||
- [ ] All 5 agents have different archetypes
|
||||
- [ ] JSONL log has entries from 5 distinct agent names + judge
|
||||
- [ ] No more than 4 rounds of debate
|
||||
- [ ] Each defender assigned to a specific variant
|
||||
- [ ] `decisions.md` references all three architectural options
|
||||
- [ ] `summary.md` tracks position changes across rounds
|
||||
@@ -0,0 +1,24 @@
|
||||
# Test: Early Consensus + Judge Intervention
|
||||
|
||||
## Setup
|
||||
|
||||
```
|
||||
/brewcode:debate "Should we use TypeScript or JavaScript for our new Node.js backend service? Team is experienced with both." -m challenge -n 3 -r 6
|
||||
```
|
||||
|
||||
## Expected Behavior
|
||||
|
||||
This topic has a strong industry consensus (TypeScript for backend). Agents should converge quickly.
|
||||
|
||||
1. Round 1: Defender argues for one option, critics raise points
|
||||
2. Round 2: If agents converge — judge should detect early consensus and end debate
|
||||
3. If not converging — judge intervenes with a redirect
|
||||
|
||||
## Assertions
|
||||
|
||||
- [ ] Debate ends in fewer than 6 rounds (early consensus)
|
||||
- [ ] At least 1 agent reports status "conceding" or "shifting"
|
||||
- [ ] Judge entry with `"type":"agree"` or noting consensus
|
||||
- [ ] `summary.md` shows "Consensus Level: strong-majority" or "unanimous"
|
||||
- [ ] `decisions.md` confidence is "high"
|
||||
- [ ] Total entries < max_rounds * agent_count (early exit proof)
|
||||
@@ -0,0 +1,24 @@
|
||||
# Test: Critic Mode
|
||||
|
||||
## Setup
|
||||
|
||||
```
|
||||
/brewcode:debate "Review our authentication system: JWT tokens with 24h expiry, stored in localStorage, refresh via /api/refresh endpoint, no rate limiting" -m critic -n 3
|
||||
```
|
||||
|
||||
## Expected Behavior
|
||||
|
||||
1. 3 critic agents with different perspectives (e.g., security, operations, UX)
|
||||
2. Round 1: Independent critiques — each finds issues from their angle
|
||||
3. Round 2+: Cross-critique — validate, deepen, discover, re-prioritize
|
||||
4. Consolidated issue list with severity levels
|
||||
|
||||
## Assertions
|
||||
|
||||
- [ ] All agents have role "critic"
|
||||
- [ ] Round 1 entries are independent (no references to other critics)
|
||||
- [ ] At least 1 "critical" severity issue found (localStorage JWT is a known anti-pattern)
|
||||
- [ ] At least 3 distinct issues across all critics
|
||||
- [ ] `decisions.md` contains "Issue Summary" with severity counts
|
||||
- [ ] `decisions.md` contains "Top Issues" table
|
||||
- [ ] Each issue has: severity, description, found-by, mitigation
|
||||
@@ -0,0 +1,46 @@
|
||||
# Test: File-Based Topic Input
|
||||
|
||||
## Setup
|
||||
|
||||
Create a temp file first, then invoke:
|
||||
|
||||
```bash
|
||||
cat > /tmp/debate-topic.md << 'EOF'
|
||||
# Proposal: Switch from PostgreSQL to MongoDB
|
||||
|
||||
## Current State
|
||||
- PostgreSQL 15 with 200+ tables
|
||||
- Complex JOIN queries for reporting
|
||||
- 50M rows in largest table
|
||||
|
||||
## Proposed Change
|
||||
- Migrate to MongoDB 7
|
||||
- Denormalize data models
|
||||
- Use aggregation pipeline for reporting
|
||||
|
||||
## Motivation
|
||||
- Schema flexibility for rapid feature development
|
||||
- Better horizontal scaling
|
||||
- JSON-native storage for our API-first architecture
|
||||
EOF
|
||||
```
|
||||
|
||||
```
|
||||
/brewcode:debate /tmp/debate-topic.md -m critic -n 4
|
||||
```
|
||||
|
||||
## Expected Behavior
|
||||
|
||||
1. Phase 1: Detects `/tmp/debate-topic.md` as file path, reads content
|
||||
2. Auto-detect mode = `critic` (matches `-m critic`)
|
||||
3. 4 critics analyze the migration proposal
|
||||
4. Issues should include: data integrity, migration complexity, reporting regression
|
||||
|
||||
## Assertions
|
||||
|
||||
- [ ] File content loaded into topic (not the path string)
|
||||
- [ ] JSONL entries reference specific points from the document (table counts, JOIN queries)
|
||||
- [ ] At least 1 issue about data migration risk
|
||||
- [ ] At least 1 issue about reporting capability regression
|
||||
- [ ] `decisions.md` references the specific PostgreSQL-to-MongoDB context
|
||||
- [ ] Temp file is NOT modified
|
||||
@@ -0,0 +1,25 @@
|
||||
# Test: Max Rounds Limit
|
||||
|
||||
## Setup
|
||||
|
||||
```
|
||||
/brewcode:debate "Tabs vs Spaces for code indentation" -m challenge -n 2 -r 2
|
||||
```
|
||||
|
||||
## Expected Behavior
|
||||
|
||||
This is an intentionally polarizing topic with no clear technical winner. Agents should NOT reach consensus easily, hitting the max rounds limit.
|
||||
|
||||
1. Round 1: Strong arguments on both sides
|
||||
2. Round 2: Continued disagreement — max rounds hit
|
||||
3. Judge ends debate, declares partial/no consensus
|
||||
|
||||
## Assertions
|
||||
|
||||
- [ ] Exactly 2 rounds of debate (not more)
|
||||
- [ ] Both agents maintain "holding" status through both rounds
|
||||
- [ ] Judge entry acknowledges max rounds reached
|
||||
- [ ] `summary.md` shows "Consensus Level: split" or "no-consensus"
|
||||
- [ ] `decisions.md` still makes a decision (judge decides even without consensus)
|
||||
- [ ] `decisions.md` confidence is "low" or "medium"
|
||||
- [ ] JSONL entry count = exactly 2 rounds * 2 agents + judge entries
|
||||
@@ -0,0 +1,25 @@
|
||||
# Test: Strategy Mode
|
||||
|
||||
## Setup
|
||||
|
||||
```
|
||||
/brewcode:debate "How should we migrate our legacy Java monolith to a modern stack? Budget: 500K, timeline: 12 months, team: 8 developers" -m strategy -n 4
|
||||
```
|
||||
|
||||
## Expected Behavior
|
||||
|
||||
1. 4 strategist agents generated with diverse archetypes
|
||||
2. Phase A: 4 independent proposals (no cross-contamination)
|
||||
3. Phase B: Judge orders presentation by maximum contrast
|
||||
4. Phase C: Debate rounds seeking convergence/synthesis
|
||||
5. Summary includes all 4 proposals + synthesis
|
||||
|
||||
## Assertions
|
||||
|
||||
- [ ] All agents have role "strategist"
|
||||
- [ ] JSONL has 4 entries with `"type":"proposal"` (Phase A)
|
||||
- [ ] JSONL has 1+ entry with `"from":"judge"` and `"type":"redirect"` (Phase B ordering)
|
||||
- [ ] Phase C entries have `"type":"argument|counter|agree"`
|
||||
- [ ] No proposal references another agent's proposal (independence)
|
||||
- [ ] `decisions.md` contains "Synthesized Strategy" section
|
||||
- [ ] `decisions.md` has "Approaches Considered" table with all 4 agents
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "brewdoc",
|
||||
"version": "3.4.27",
|
||||
"version": "3.4.28",
|
||||
"description": "Brewdoc - Claude Code documentation tools: auto-sync for skills/agents/rules, my-claude installation docs, memory optimization",
|
||||
"author": {
|
||||
"name": "Maksim Kochetkov",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "brewtools",
|
||||
"version": "3.4.27",
|
||||
"version": "3.4.28",
|
||||
"description": "Brewtools - universal utilities for Claude Code: text optimization, humanization, secrets scanning",
|
||||
"author": {
|
||||
"name": "Maksim Kochetkov",
|
||||
|
||||
@@ -0,0 +1,323 @@
|
||||
---
|
||||
title: "Debate"
|
||||
description: "Multi-agent debate orchestrator -- 3 modes, dynamic agents, structured decisions"
|
||||
order: 1115
|
||||
---
|
||||
import { Card, CardGrid, Callout, Steps, Badge, Tabs, TabItem } from '../../../../components/mdx';
|
||||
|
||||
# Debate
|
||||
|
||||
<Badge variant="accent" text="new" /> <Badge variant="primary" text="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.
|
||||
|
||||
<Callout type="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.
|
||||
</Callout>
|
||||
|
||||
<CardGrid>
|
||||
<Card title="CHALLENGE" icon="pencil">
|
||||
Generate or receive variants, debate to select the best one. Defenders argue FOR, critics attack. Outcome: selected variant with justification.
|
||||
</Card>
|
||||
<Card title="STRATEGY" icon="star">
|
||||
Deep analysis -- each agent independently forms their approach, then debate to converge. Outcome: synthesized strategy or ranked approaches.
|
||||
</Card>
|
||||
<Card title="CRITIC" icon="search">
|
||||
Find all weaknesses and risks in a given solution, plan, or code. All agents are critics with different perspectives. Outcome: prioritized issue list.
|
||||
</Card>
|
||||
</CardGrid>
|
||||
|
||||
## 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
<Steps>
|
||||
<li>
|
||||
<div>
|
||||
<strong>Phase 0 -- Validation</strong>
|
||||
<p>Run <code>validate.sh</code> to check all skill files exist. Load archetypes into context. Stop on failure.</p>
|
||||
</div>
|
||||
</li>
|
||||
<li>
|
||||
<div>
|
||||
<strong>Phase 1-2 -- Parse and Init</strong>
|
||||
<p>Parse arguments: topic, mode (<code>-m</code>), agent count (<code>-n</code>), max rounds (<code>-r</code>). Auto-detect mode from keywords if not specified. Create report directory and empty JSONL log.</p>
|
||||
</div>
|
||||
</li>
|
||||
<li>
|
||||
<div>
|
||||
<strong>Phase 3 -- User Interview</strong>
|
||||
<p>Confirm or adjust: mode, agent count, agent profiles (auto or custom), max rounds. Interactive via <code>AskUserQuestion</code>.</p>
|
||||
</div>
|
||||
</li>
|
||||
<li>
|
||||
<div>
|
||||
<strong>Phase 4 -- Agent Generation</strong>
|
||||
<p>Detect domain, assign roles (mode-aware), select character archetypes. Display full agent table: name, role, character, perspective, rationale. User confirms or adjusts.</p>
|
||||
</div>
|
||||
</li>
|
||||
<li>
|
||||
<div>
|
||||
<strong>Phase 4.5 -- Discovery (Research)</strong>
|
||||
<p>2-3 research agents run in parallel: <strong>Codebase Explorer</strong> searches the project for relevant code, patterns, and dependencies; <strong>Web Researcher(s)</strong> search the internet for current best practices, official docs, and community discussions. All findings are documented with sources (file paths, URLs) in <code>discovery.md</code>. This evidence base is injected into every debate agent's context.</p>
|
||||
</div>
|
||||
</li>
|
||||
<li>
|
||||
<div>
|
||||
<strong>Phase 5 -- Debate</strong>
|
||||
<p>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.</p>
|
||||
</div>
|
||||
</li>
|
||||
<li>
|
||||
<div>
|
||||
<strong>Phase 6 -- Summary</strong>
|
||||
<p>Secretary agent writes <code>summary.md</code> with key arguments, turning points, and areas of agreement/disagreement.</p>
|
||||
</div>
|
||||
</li>
|
||||
<li>
|
||||
<div>
|
||||
<strong>Phase 7 -- Decision</strong>
|
||||
<p>Judge (main session) writes <code>decisions.md</code> with final verdict, reasoning, and minority opinions.</p>
|
||||
</div>
|
||||
</li>
|
||||
<li>
|
||||
<div>
|
||||
<strong>Phase 8 -- Final Output</strong>
|
||||
<p>Status table, outcome (consensus / partial / none), decision bullets, links to all artifacts. Optional <code>/brewcode:review</code> if <code>--review</code> flag was set.</p>
|
||||
</div>
|
||||
</li>
|
||||
</Steps>
|
||||
|
||||
## Modes Deep Dive
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="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.
|
||||
</TabItem>
|
||||
<TabItem label="Strategy">
|
||||
**Goal:** Synthesize the strongest approach from independent proposals.
|
||||
|
||||
**Agent Roles:** All agents are **Strategists** with different archetypes.
|
||||
|
||||
**Four-phase flow:**
|
||||
1. **Discovery** -- research agents gather evidence from codebase and web (parallel)
|
||||
2. **Independent proposals** -- each agent formulates their approach using Discovery evidence, without seeing others (parallel thinking)
|
||||
3. **Judge picks opening order** -- most divergent proposals go first to maximize productive tension
|
||||
4. **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.
|
||||
</TabItem>
|
||||
<TabItem label="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.
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Agent Archetypes
|
||||
|
||||
10 character archetypes define HOW an agent argues. Combined with roles (defender/critic/strategist) to create unique debate personas.
|
||||
|
||||
<CardGrid>
|
||||
<Card title="Pragmatist" icon="check">
|
||||
Results-oriented, impatient with theory. "What actually works in production?" Cites real-world outcomes, dismisses hypotheticals.
|
||||
</Card>
|
||||
<Card title="Visionary" icon="star">
|
||||
Big-picture, future-oriented. "Where is this heading in 5 years?" Argues from trends, first principles, emerging patterns.
|
||||
</Card>
|
||||
<Card title="Skeptic" icon="search">
|
||||
Cautious, evidence-demanding. "Show me the data." Finds edge cases, stress-tests assumptions, demands proof.
|
||||
</Card>
|
||||
<Card title="Architect" icon="pencil">
|
||||
Systematic, pattern-focused. "How does this fit the bigger system?" Argues from design principles, consistency, modularity.
|
||||
</Card>
|
||||
<Card title="Operator" icon="wrench">
|
||||
Reliability-focused, operations-minded. "Who maintains this at 3 AM?" Argues from operational reality and incident response.
|
||||
</Card>
|
||||
<Card title="Advocate" icon="heart">
|
||||
User-centric, empathetic. "What does the end user experience?" Argues from UX, adoption, accessibility, learning curve.
|
||||
</Card>
|
||||
<Card title="Economist" icon="document">
|
||||
Cost-conscious, ROI-focused. "What's the total cost of ownership?" Argues with numbers, trade-off matrices, opportunity cost.
|
||||
</Card>
|
||||
<Card title="Historian" icon="information">
|
||||
Precedent-aware, pattern-matching. "We tried this in 2019 and it failed because..." Argues from past failures and case studies.
|
||||
</Card>
|
||||
<Card title="Provocateur" icon="warning">
|
||||
Contrarian, challenges consensus. "What if we're solving the wrong problem?" Reframes the debate, asks uncomfortable questions.
|
||||
</Card>
|
||||
<Card title="Diplomat" icon="forward-slash">
|
||||
Consensus-seeking, synthesizing. "I hear both sides -- what if we combine..." Finds common ground, proposes compromises.
|
||||
</Card>
|
||||
</CardGrid>
|
||||
|
||||
<Callout type="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.
|
||||
</Callout>
|
||||
|
||||
## 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`:
|
||||
|
||||
```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
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="Tech Choice">
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem label="Architecture">
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem label="Code Review">
|
||||
```bash
|
||||
# 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)
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem label="Design Decision">
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem label="Risk Assessment">
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
<Callout type="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
|
||||
</Callout>
|
||||
|
||||
## 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 |
|
||||
@@ -40,6 +40,7 @@ export const navigation: NavSection[] = [
|
||||
{ title: 'agents', slug: 'brewcode/skills/agents' },
|
||||
{ title: 'e2e', slug: 'brewcode/skills/e2e' },
|
||||
{ title: 'glm-design-to-code', slug: 'brewcode/skills/glm-design-to-code' },
|
||||
{ title: 'debate', slug: 'brewcode/skills/debate' },
|
||||
],
|
||||
},
|
||||
{
|
||||
|
||||
Reference in New Issue
Block a user