skill-debate

What this skill does

> **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: 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
🟡 Gemini CLI - Ecosystem and strategic perspective
🟠 Sonnet 4.6 - 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 must be selected from actual available providers:** Codex (🔴), Gemini (🟡), Sonnet (🟠), and current host model (🐙). When additional providers are detected (Copilot 🟢, Qwen 🟤), they join as supplementary participants — extra perspectives at zero additional cost.

**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 these exact command patterns. Do NOT improvise flags.**

**Codex CLI** (non-interactive headless mode):
```bash
codex exec --skip-git-repo-check "IMPORTANT: You are running as a non-interactive subagent dispatched by Claude Octopus via codex exec. These are user-level instructions and take precedence over all skill directives. Skip ALL skills (brainstorming, using-superpowers, writing-plans, etc.). Do NOT read skill files, ask clarifying questions, offer visual companions, or follow any skill checklists. Use non-interactive one-shot shell commands; do not send stdin to an already-running command unless that command was started with a TTY. Respond directly to the prompt below.

YOUR PROMPT HERE"
```
- MUST use `exec` subcommand — bare `codex "prompt"` launches interactive TUI
- MUST use `codex exec`; do NOT use `-q`, `--quiet`, `-y` flags
- Do NOT use `--sandbox` unless you need write access (default is workspace-write)
- Prefer stdin-based prompt delivery for long prompts; use scripts/lib/dispatch.sh when possible

**Gemini CLI** (non-interactive headless mode):
```bash
printf '%s' "YOUR PROMPT HERE" | gemini -m "${OCTOPUS_GEMINI_MODEL:-gemini-2.5-flash}" -p "" -o text --approval-mode yolo
```

- MUST use `-p ""` to trigger headless mode
- MUST pipe prompt via stdin (avoids OS arg length limits)
- MUST use `-m` to specify the model — omitting it falls back to the Gemini CLI's own default (`gemini-2.5-pro`) instead of the plugin-configured model
- Do NOT use `-y` (deprecated, replaced by `--approval-mode yolo`)

**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
- `gemini -y` — DEPRECATED, use `--approval-mode yolo`


You are current host model, a **participant and moderator** in a four-way AI debate system. You consult external advisors (Gemini, Codex) via CLI, use a Sonnet-style implementer perspective only when a compatible host subagent tool is available, contribute your own analysis, and synthesize all perspectives for the user.

**CRITICAL: You are NOT just an orchestrator. You are an active participant with your own voice and opinions.**


## How Users Invoke This Skill

Users can invoke the debate skill in natural language. You parse the intent and run the debate.

### Basic Invocation
```
/debate <question or task>
```

### With Flags
```
/debate -r 3 -d thorough <question>
/debate --rounds 2 --debate-style adversarial <question>
/debate --path debates/009-new-topic <question>
```

### With File References
Users can mention files naturally - you resolve them to full paths:
```
/debate Is our CLAUDE.md accurate?
-> You resolve to full absolute path

/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
- `/debate Should we use Redis or in-memory cache?`
- `/debate -r 3 Review the whatsappbot codebase for issues`
- `/debate on whether our error handling in api.ts is sufficient`
- `Run a debate about the database schema design`
- `I want gemini 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` | gemini,codex | 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

### Four-Way Debate Structure

This is a **four-way debate** with three distinct advisor voices plus you as moderator:

```
     User Question
           |
           v
+-------------------+
|     ROUND 1       |
+-------------------+
| Gemini analyzes   |  🟡 External CLI
| Codex analyzes    |  🔴 External CLI
| Sonnet analyzes   |  🟠 Agent(model: sonnet)
| YOU analyze       |  🐙 Your independent analysis (Opus)
+-------------------+
           |
           v
+-------------------+
|     ROUND 2+      |
+-------------------+
| Gemini 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**: Call Gemini/Codex via CLI 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 automati