--- name: AI Debate Hub slug: ai-debate-hub category: AI Engineering description: AI Debate Hub runs structured multi-provider AI debates with Claude and available advisors to help make critical decisions. Use it when you want multiple AI perspectives synthesized before choosing a technical or strategic direction. github: "https://github.com/nyldn/claude-octopus/tree/main/skills/skill-debate" language: Shell stars: 3971 forks: 374 install: "npx degit https://github.com/nyldn/claude-octopus/tree/main/skills/skill-debate ~/.claude/skills/skill-debate" installs_to: ~/.claude/skills/skill-debate source_path: skills/skill-debate/SKILL.md collection_size: 25 category_size: 2451 collection_url: "https://dirskills.com/collections/nyldn/claude-octopus" added: 2026-08-16T07:01:35.058Z last_synced: 2026-08-16T07:01:35.058Z canonical_url: "https://dirskills.com/skills/ai-debate-hub" --- # AI Debate Hub AI Debate Hub runs structured multi-provider AI debates with Claude and available advisors to help make critical decisions. Use it when you want multiple AI perspectives synthesized before choosing a technical or strategic direction. **Install:** ```bash npx degit https://github.com/nyldn/claude-octopus/tree/main/skills/skill-debate ~/.claude/skills/skill-debate ``` ## README > **Host: Codex CLI** — This skill was designed for Claude Code and adapted for Codex. > Cross-reference commands use installed skill names in Codex rather than `/octo:*` slash commands. > Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it. > For host tool equivalents, see `skills/blocks/codex-host-adapter.md`. # AI Debate Hub Skill v4.8 ## MANDATORY COMPLIANCE — DO NOT SKIP **When this skill is invoked, you MUST dispatch the debate advisors through `orchestrate.sh` and synthesize their positions. You are PROHIBITED from:** - Simulating advisor responses yourself instead of dispatching real providers via `orchestrate.sh` - Deciding the question is "too simple" and answering single-model without the multi-provider debate - Skipping the provider availability check or the structured rounds - Dropping an available advisor (including `agy`) from the roster without telling the user - Rationalizing that one model's view is sufficient — the user invoked a debate for multiple perspectives ## ⚠️ MANDATORY: Visual Indicators Protocol **BEFORE starting ANY debate, you MUST output this banner:** ``` 🐙 **CLAUDE OCTOPUS ACTIVATED** - AI Debate Hub 🐙 Debate: [Topic/question being debated] Participants: 🔴 Codex CLI - Technical implementation perspective 🟡 Antigravity CLI - Ecosystem and strategic perspective 🟠 Sonnet 5 - Pragmatic implementer perspective if host subagents are available 🐙 current host model - Moderator and synthesis 🟢 Copilot CLI - GitHub-native perspective (if available) 🟤 Qwen CLI - Alternative model perspective (if available) ``` **Core participants are selected from available providers.** Codex (🔴), Antigravity (🧭), Sonnet (🟠), current host model (🐙), and other detected providers can participate based on routing and availability. **This is NOT optional.** Users need to see which AI providers are active. External API calls (🔴 🟡) use provider API keys. Sonnet (🟠), Copilot (🟢), and Qwen (🟤) are included with existing subscriptions. ## CRITICAL: External CLI Syntax (v0.101.0+) **You MUST use this exact command pattern. Do NOT improvise provider flags.** For debate rounds, dispatch every external advisor through Octopus routing: ```bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" spawn "$advisor" "$prompt" ``` Do not call provider CLIs directly from the debate workflow. The router applies provider-specific flags for Codex, Antigravity, and other advisors. - Provider-specific syntax lives in `scripts/lib/dispatch.sh` and helper scripts. - Do not copy direct provider CLI invocations into debate steps. - Always pass the selected advisor name to `orchestrate.sh spawn`; the router chooses the correct command. **Flags that DO NOT EXIST (will cause errors):** - `codex --approval-mode full-auto` — no `--approval-mode` flag in Codex 0.130.0 - `codex --full-auto` — deprecated/removed for current non-interactive dispatch - `codex -q` / `codex --quiet` — REMOVED in v0.101.0 - `codex -y` / `codex --yes` — NEVER EXISTED - `codex "prompt"` without `exec` — launches interactive TUI, hangs You are current host model, a **participant and moderator** in a multi-provider AI debate system. You consult external advisors (Codex, Antigravity, and other available providers) via CLI, contribute your own analysis, and synthesize all perspectives for the user. If the host exposes subagents, include Sonnet as an independent analyst. **CRITICAL: You are NOT just an orchestrator. You are an active participant with your own voice and opinions.** ## How Users Invoke This Skill Users invoke this skill explicitly from the slash menu. Parse the supplied intent and run the debate. ### Basic Invocation ``` /octo:debate ``` ### With Flags ``` /octo:debate -r 3 -d thorough /octo:debate --rounds 2 --debate-style adversarial /octo:debate --path debates/009-new-topic ``` ### With File References Users can mention files naturally - you resolve them to full paths: ``` /octo:debate Is our CLAUDE.md accurate? -> You resolve to full absolute path /octo:debate Review the auth flow in src/auth.ts -> You find src/auth.ts relative to cwd and pass full path to advisors ``` ### Examples Users Might Say - `/octo:debate Should we use Redis or in-memory cache?` - `/octo:debate -r 3 Review the whatsappbot codebase for issues` - `/octo:debate on whether our error handling in api.ts is sufficient` - `Run a debate about the database schema design` - `I want Antigravity and Codex to review this PR` ## Flags | Flag | Short | Default | Description | |------|-------|---------|-------------| | `--rounds N` | `-r N` | 1 | Number of debate rounds (1-10) | | `--debate-style STYLE` | `-d STYLE` | quick | Style: `quick`, `thorough`, `adversarial`, `collaborative` | | `--moderator-style MODE` | `-m MODE` | guided | Mode: `transparent`, `guided`, `authoritative` | | `--advisors LIST` | `-a LIST` | auto | Comma-separated list | | `--out-dir PATH` | `-o PATH` | `debates/` | Output directory (relative to cwd) | | `--path PATH` | `-p PATH` | none | Debate folder path (skips cd requirement) | | `--context-file FILE` | `-c FILE` | none | File to include as context | | `--max-words N` | `-w N` | 300 | Word limit per response | | `--topic NAME` | `-t NAME` | auto | Topic slug for folder naming | | `--synthesize` | `-s` | off | Generate a deliverable (markdown file, diff, or plan) from consensus | ### Flag Precedence Rules **`--rounds` vs `--debate-style`:** - `--rounds` explicitly set: ALWAYS takes precedence over style defaults - `--debate-style quick` implies 1 round UNLESS `--rounds` is also specified - Error if conflicting: `--debate-style quick --rounds 5` -> warn user, use `--rounds` value **Style round defaults (when --rounds not specified):** | Style | Default Rounds | |-------|---------------| | quick | 1 | | thorough | 3 | | adversarial | 3 | | collaborative | 2 | **Validation:** - `--rounds` must be 1-10 - Error on `--rounds 0` or `--rounds 11+` ## Your Role: Participant + Moderator ### Multi-Provider Debate Structure This is a **provider debate** with selected advisor voices plus you as moderator: ``` User Question | v +-------------------+ | ROUND 1 | +-------------------+ | Antigravity analyzes | 🧭 External CLI | Codex analyzes | 🔴 External CLI | Sonnet analyzes | 🟠 Agent(model: sonnet) | YOU analyze | 🐙 Your independent analysis (Opus) +-------------------+ | v +-------------------+ | ROUND 2+ | +-------------------+ | Antigravity responds | 🧭 Sees prior round | Codex responds | 🔴 Sees prior round | Sonnet responds | 🟠 Sees prior round | YOU respond | 🐙 Your independent response +-------------------+ | v +-------------------+ | FINAL SYNTHESIS | +-------------------+ | YOU synthesize all four perspectives | and recommend a path forward +-------------------+ ``` **Key responsibilities:** 1. **Set up the debate**: Create folder structure, write context.md 2. **Consult external advisors**: Dispatch Antigravity/Codex through Octopus routing for each round 3. **Launch optional host subagent**: Dispatch Sonnet via host subagent tool (background execution) for each round 4. **Contribute your analysis**: Write your own perspective to rounds/r00N_claude.md 5. **Moderate**: Ensure advisors stay on topic, follow word limits 6. **Synthesize**: Combine all four perspectives into actionable recommendations ## Claude-Octopus Enhancements When running debates in claude-octopus, the following enhancements are automatically applied: ### 1. Session-Aware Storage **Enhanced behavior** (when `CLAUDE_CODE_SESSION` is set): ``` ~/.claude-octopus/debates/${SESSION_ID}/ └── NNN-topic-slug/ ├── context.md ├── state.json ├── synthesis.md └── rounds/ ``` **Benefits**: - Debates organized by Claude Code session - Easy to find debates from specific conversations - Automatic cleanup when sessions expire - Integration with claude-octopus analytics ### 2. Quality Gates for Debate Responses **Enhancement**: Evaluate each advisor response for quality before proceeding to next round. **Quality Metrics**: | Metric | Weight | Criteria | |--------|--------|----------| | **Length** | 25 pts | 50-1000 words (substantive but concise) | | **Citations** | 25 pts | References, links, or sources present | | **Code Examples** | 25 pts | Technical examples or code snippets | | **Engagement** | 25 pts | Addresses other advisors' specific points | **Quality Thresholds**: - **Score >= 75**: Proceed (high quality) - **Score 50-74**: Proceed with warning (flag in synthesis) - **Score < 50**: Re-prompt advisor for elaboration ### 3. Cost Tracking & Analytics Track token usage and cost for each debate, integrated with claude-octopus analytics. ### 4. Document Export Export debates to professional formats via the document-delivery skill: - PPTX presentations - DOCX reports - PDF documents ## Implementation Steps When the user invokes `/octo:debate`: ### Step 1: Check Provider Availability & Display Banner **MANDATORY: You MUST use the native shell command tool to run this provider check BEFORE displaying the banner. Do NOT skip it. Do NOT assume availability.** For provider checks, never use `grep -P`; use portable `grep -E`/`case` checks and capture the exit code so missing optional CLIs do not fail open or abort the command. ```bash bash "${HOME}/.claude-octopus/plugin/scripts/helpers/check-providers.sh" ``` **Use the ACTUAL results below. PROHIBITED: Showing only "🔵 Claude: Available ✓" without listing all providers.** Then display the banner with real provider status: ``` 🐙 **CLAUDE OCTOPUS ACTIVATED** - AI Debate Hub 🐙 Debate: [Topic/question being debated] Provider Availability: 🔴 Codex CLI: [Available ✓ / Not installed ✗] 🟡 Antigravity CLI: [Available ✓ / Not installed ✗] 🧭 Antigravity CLI: [Available ✓ / Not installed ✗] 🤖 Grok CLI (xAI): [Available ✓ / Not installed ✗] 🟠 Sonnet 5: available only when this Codex session exposes a compatible host subagent tool 🐙 current host model: Available ✓ (Moderator and participant) ``` > **🧭 Antigravity availability:** Antigravity CLI = the `agy` binary; judge availability only via `command -v agy` (as `check-providers.sh` does), never from the `antigravity` desktop shortcut. **If providers are missing:** - If all external providers are unavailable: Inform user that debate requires at least one external provider and suggest running `/octo:setup` to configure them - If one or more providers are unavailable: Note which providers are missing and proceed with available provider(s) and Claude ### Step 2: Ask Clarifying Questions **Use the AskUserQuestion tool to gather context before starting the debate:** Ask 4 clarifying questions to ensure high-quality debate: ```javascript AskUserQuestion({ questions: [ { question: "What's your primary goal for this debate?", header: "Goal", multiSelect: false, options: [ {label: "Make a technical decision", description: "I need to choose between options"}, {label: "Identify risks/concerns", description: "I want to surface potential issues"}, {label: "Understand trade-offs", description: "I want to see pros/cons of approaches"}, {label: "Get diverse perspectives", description: "I want multiple viewpoints"} ] }, { question: "How should the AI models evaluate the topic?", header: "Evaluation", multiSelect: false, options: [ {label: "Cross-critique (Recommended)", description: "Models challenge each other's proposals directly — deeper analysis but may anchor on first responses"}, {label: "Independent evaluation", description: "Models evaluate independently without seeing others' work — prevents groupthink and anchoring bias"} ] }, { question: "What's the most important factor in your decision?", header: "Priority", multiSelect: false, options: [ {label: "Performance", description: "Speed and efficiency are critical"}, {label: "Security", description: "Security and safety are paramount"}, {label: "Maintainability", description: "Long-term maintenance and clarity"}, {label: "Cost/Resources", description: "Budget and resource constraints"} ] }, { question: "Do you have existing context or constraints the debate should consider?", header: "Context", multiSelect: true, options: [ {label: "Existing codebase patterns", description: "Must align with current architecture"}, {label: "Team expertise", description: "Team skill set is a constraint"}, {label: "Deadline pressure", description: "Time-to-market is critical"}, {label: "Compliance requirements", description: "Regulatory or policy constraints"} ] } ] }) ``` **After receiving answers:** - If user selected "Cross-critique": use `--mode cross-critique` (default ACH falsification) - If user selected "Independent evaluation": use `--mode blinded` (no cross-contamination) - Incorporate all other answers into the debate context. ### Step 3: Parse Arguments & Build Debate Fleet ```bash # Extract question and flags QUESTION="Should we use Redis or in-memory cache?" ROUNDS=3 STYLE="thorough" # Dynamic advisor selection — use build-fleet.sh for model family diversity DEBATE_FLEET=$("${HOME}/.claude-octopus/plugin/scripts/helpers/build-fleet.sh" debate standard "${QUESTION}" 2>/dev/null) # Extract debater agent types (exclude claude-sonnet Moderator) ADVISORS=$(echo "$DEBATE_FLEET" | grep '|Debater|' | cut -d'|' -f1 | paste -sd',' -) # Fallback if build-fleet.sh unavailable: use installed providers, including agy. if [[ -z "$ADVISORS" ]]; then fallback_advisors=() command -v codex >/dev/null 2>&1 && fallback_advisors+=(codex) command -v agy >/dev/null 2>&1 && fallback_advisors+=(agy) ADVISORS=$(IFS=,; echo "${fallback_advisors[*]}") fi ``` **The `build-fleet.sh debate` command** selects up to 3 debaters from different model families (for example, codex/OpenAI, agy/Google Antigravity, and copilot/Microsoft) to maximize training-bias diversity. Do not hardcode provider pairs; use the runtime `ADVISORS` list. ### Step 4: Setup Debate Folder ```bash # Create debate directory structure DEBATE_BASE_DIR="${HOME}/.claude-octopus/debates/${CLAUDE_CODE_SESSION:-./debates}" DEBATE_ID="042-redis-vs-memcached" DEBATE_DIR="${DEBATE_BASE_DIR}/${DEBATE_ID}" mkdir -p "${DEBATE_DIR}/rounds" # Write context.md cat > "${DEBATE_DIR}/context.md" < "${DEBATE_DIR}/state.json" < "${DEBATE_DIR}/rounds/r001_${safe_advisor}.md" & done wait ``` #### 5.2: Launch optional host subagent (Pragmatic Implementer) Dispatch Sonnet via the host subagent tool with `model: "sonnet"` and `background execution: true` when the host exposes subagents. Sonnet runs **in parallel** with the external advisor calls — no additional latency. ``` Agent( model: "sonnet", background execution: true, description: "Sonnet: debate round 1", prompt: "You are a PRAGMATIC IMPLEMENTER participating in a structured AI debate. YOUR ROLE: You are the person who would actually have to BUILD this. You care about what ships, what works, and what you'll be debugging at 2am. Ground your analysis in the actual code and real implementation constraints. DEBATE QUESTION: ${QUESTION} ${CONTEXT} Write your analysis (${MAX_WORDS} words) to: ${DEBATE_DIR}/rounds/r001_sonnet.md Cover: implementation feasibility, hidden gotchas, concrete effort estimates, and what the other approaches miss from a builder's perspective." ) ``` **WHY Sonnet and not just more Opus?** Sonnet is a distinct model with different strengths — faster, more concise, catches implementation details that Opus's broader reasoning sometimes overlooks. Using a different model prevents groupthink within the Claude model family. **Timing**: Launch optional host subagent BEFORE or IN PARALLEL with the external advisor calls. By the time the CLI calls return, Sonnet is usually done too. Check for completion before proceeding to 5.3. #### 5.3: Write Your Analysis (Opus) Use the Read tool to read all advisor responses, then write your independent analysis: ```bash # Read what all advisors said for response_file in "${DEBATE_DIR}"/rounds/r001_*.md; do printf '\n## %s\n' "$(basename "$response_file" .md)" cat "$response_file" done # Write your analysis as moderator cat > "${DEBATE_DIR}/rounds/r001_claude.md" <= 50 && word_count <= 1000 )) && (( score += 25 )) (( has_citations > 0 )) && (( score += 25 )) (( has_code > 0 )) && (( score += 25 )) (( addresses_others > 0 )) && (( score += 25 )) echo "$score" } for response_file in "${DEBATE_DIR}"/rounds/r001_*.md; do advisor=$(basename "$response_file" .md | sed 's/^r001_//') quality_score=$(evaluate_response_quality "$response_file" "$advisor") if (( quality_score < 50 )); then echo "Low quality response from ${advisor} (score: $quality_score). Re-prompting..." # Re-prompt for more detail fi done ``` ### Step 6: Final Synthesis After all rounds complete, write a comprehensive synthesis: ```bash cat > "${DEBATE_DIR}/synthesis.md" <