adversarial-spec

A Claude Code plugin that iteratively refines product specifications through multi-model debate until consensus is reached.

Key insight: A single LLM reviewing a spec will miss things. Multiple LLMs debating a spec will catch gaps, challenge assumptions, and surface edge cases that any one model would overlook. The result is a document that has survived rigorous adversarial review.

Claude is an active participant, not just an orchestrator. Claude provides independent critiques, challenges opponent models, and contributes substantive improvements alongside external models.

Quick Start

# 1. Add the marketplace and install the plugin
claude plugin marketplace add zscole/adversarial-spec
claude plugin install adversarial-spec

# 2. Set at least one API key
export OPENAI_API_KEY="sk-..."
# Or use OpenRouter for access to multiple providers with one key
export OPENROUTER_API_KEY="sk-or-..."

# 3. Run it
/adversarial-spec "Build a rate limiter service with Redis backend"

How It Works

You describe product --> Claude drafts spec --> Multiple LLMs critique in parallel
        |                                              |
        |                                              v
        |                              Claude synthesizes + adds own critique
        |                                              |
        |                                              v
        |                              Revise and repeat until ALL agree
        |                                              |
        +--------------------------------------------->|
                                                       v
                                            User review period
                                                       |
                                                       v
                                            Final document output

1. Describe your product concept or provide an existing document
2. (Optional) Start with an in-depth interview to capture requirements
3. Claude drafts the initial document (PRD or tech spec)
4. Document is sent to opponent models (GPT, Gemini, Grok, etc.) for parallel critique
5. Claude provides independent critique alongside opponent feedback
6. Claude synthesizes all feedback and revises
7. Loop continues until ALL models AND Claude agree
8. User review period: request changes or run additional cycles
9. Final converged document is output

Requirements

• Python 3.10+
• litellm package: pip install litellm
• API key for at least one LLM provider

Supported Models

| Provider | Env Var | Example Models | |------------|------------------------|----------------------------------------------| | OpenAI | OPENAI_API_KEY | gpt-4o, gpt-4-turbo, o1 | | Anthropic | ANTHROPIC_API_KEY | claude-sonnet-4-20250514, claude-opus-4-20250514 | | Google | GEMINI_API_KEY | gemini/gemini-2.0-flash, gemini/gemini-pro | | xAI | XAI_API_KEY | xai/grok-3, xai/grok-beta | | Mistral | MISTRAL_API_KEY | mistral/mistral-large, mistral/codestral | | Groq | GROQ_API_KEY | groq/llama-3.3-70b-versatile | | OpenRouter | OPENROUTER_API_KEY | openrouter/openai/gpt-4o, openrouter/anthropic/claude-3.5-sonnet | | Codex CLI | ChatGPT subscription | codex/gpt-5.2-codex, codex/gpt-5.1-codex-max | | Gemini CLI | Google account | gemini-cli/gemini-3-pro-preview, gemini-cli/gemini-3-flash-preview | | Deepseek | DEEPSEEK_API_KEY | deepseek/deepseek-chat | | Zhipu | ZHIPUAI_API_KEY | zhipu/glm-4, zhipu/glm-4-plus |

Check which keys are configured:

python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" providers

AWS Bedrock Support

For enterprise users who need to route all model calls through AWS Bedrock (e.g., for security compliance or inference gateway requirements):

# Enable Bedrock mode
python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" bedrock enable --region us-east-1

# Add models enabled in your Bedrock account
python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" bedrock add-model claude-3-sonnet
python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" bedrock add-model claude-3-haiku

# Check configuration
python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" bedrock status

# Disable Bedrock mode
python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" bedrock disable

When Bedrock is enabled, all model calls route through Bedrock - no direct API calls are made. Use friendly names like claude-3-sonnet which are automatically mapped to Bedrock model IDs.

Configuration is stored at ~/.claude/adversarial-spec/config.json.

OpenRouter Support

OpenRouter provides unified access to multiple LLM providers through a single API. This is useful for:

• Accessing models from multiple providers with one API key
• Comparing models across different providers
• Automatic fallback and load balancing
• Cost optimization across providers

Setup:

# Get your API key from https://openrouter.ai/keys
export OPENROUTER_API_KEY="sk-or-..."

# Use OpenRouter models (prefix with openrouter/)
python3 debate.py critique --models openrouter/openai/gpt-4o,openrouter/anthropic/claude-3.5-sonnet < spec.md

Popular OpenRouter models:

• openrouter/openai/gpt-4o - GPT-4o via OpenRouter
• openrouter/anthropic/claude-3.5-sonnet - Claude 3.5 Sonnet
• openrouter/google/gemini-2.0-flash - Gemini 2.0 Flash
• openrouter/meta-llama/llama-3.3-70b-instruct - Llama 3.3 70B
• openrouter/qwen/qwen-2.5-72b-instruct - Qwen 2.5 72B

See the full model list at openrouter.ai/models.

Codex CLI Support

Codex CLI allows ChatGPT Pro subscribers to use OpenAI models without separate API credits. Models prefixed with codex/ are routed through the Codex CLI.

Setup:

# Install Codex CLI (requires ChatGPT Pro subscription)
npm install -g @openai/codex

# Use Codex models (prefix with codex/)
python3 debate.py critique --models codex/gpt-5.2-codex,gemini/gemini-2.0-flash < spec.md

Reasoning effort:

Control how much thinking time the model uses with --codex-reasoning:

# Available levels: low, medium, high, xhigh (default: xhigh)
python3 debate.py critique --models codex/gpt-5.2-codex --codex-reasoning high < spec.md

Higher reasoning effort produces more thorough analysis but uses more tokens.

Available Codex models:

• codex/gpt-5.2-codex - GPT-5.2 via Codex CLI
• codex/gpt-5.1-codex-max - GPT-5.1 Max via Codex CLI

Check Codex CLI installation status:

python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" providers

Gemini CLI Support

Gemini CLI allows Google account holders to use Gemini models without separate API credits. Models prefixed with gemini-cli/ are routed through the Gemini CLI.

Setup:

# Install Gemini CLI
npm install -g @google/gemini-cli && gemini auth

# Use Gemini CLI models (prefix with gemini-cli/)
python3 debate.py critique --models gemini-cli/gemini-3-pro-preview < spec.md

Available Gemini CLI models:

• gemini-cli/gemini-3-pro-preview - Gemini 3 Pro via CLI
• gemini-cli/gemini-3-flash-preview - Gemini 3 Flash via CLI

Check Gemini CLI installation status:

python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" providers

OpenAI-Compatible Endpoints

For models that expose an OpenAI-compatible API (local LLMs, self-hosted models, alternative providers), set OPENAI_API_BASE:

# Point to a custom endpoint
export OPENAI_API_KEY="your-key"
export OPENAI_API_BASE="https://your-endpoint.com/v1"

# Use with any model name
python3 debate.py critique --models gpt-4o < spec.md

This works with:

• Local LLM servers (Ollama, vLLM, text-generation-webui)
• OpenAI-compatible providers
• Self-hosted inference endpoints

Usage

Start from scratch:

/adversarial-spec "Build a rate limiter service with Redis backend"

Refine an existing document:

/adversarial-spec ./docs/my-spec.md

You will be prompted for:

1. Document type: PRD (business/product focus) or tech spec (engineering focus)
2. Interview mode: Optional in-depth requirements gathering session
3. Opponent models: Comma-separated list (e.g., gpt-4o,gemini/gemini-2.0-flash,xai/grok-3)

More models = more perspectives = stricter convergence.

Document Types

PRD (Product Requirements Document)

For stakeholders, PMs, and designers.

Sections: Executive Summary, Problem Statement, Target Users/Personas, User Stories, Functional Requirements, Non-Functional Requirements, Success Metrics, Scope (In/Out), Dependencies, Risks

Critique focuses on: Clear problem definition, well-defined personas, measurable success criteria, explicit scope boundaries, no technical implementation details

Technical Specification

For developers and architects.

Sections: Overview, Goals/Non-Goals, System Architecture, Component Design, API Design (full schemas), Data Models, Infrastructure, Security, Error Handling, Performance/SLAs, Observability, Testing Strategy, Deployment Strategy

Critique focuses on: Complete API contracts, data model coverage, security threat mitigation, error handling, specific performance targets, no ambiguity for engineers

Core Features

Interview Mode

Befor