by zscole
A Claude Code plugin that iteratively refines product specifications by debating between multiple LLMs until all models reach consensus.
# Add to your Claude Code skills
git clone https://github.com/zscole/adversarial-specA 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.
# 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"
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
No comments yet. Be the first to share your thoughts!
litellm package: pip install litellm| 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
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 provides unified access to multiple LLM providers through a single API. This is useful for:
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 OpenRouteropenrouter/anthropic/claude-3.5-sonnet - Claude 3.5 Sonnetopenrouter/google/gemini-2.0-flash - Gemini 2.0 Flashopenrouter/meta-llama/llama-3.3-70b-instruct - Llama 3.3 70Bopenrouter/qwen/qwen-2.5-72b-instruct - Qwen 2.5 72BSee the full model list at openrouter.ai/models.
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 CLIcodex/gpt-5.1-codex-max - GPT-5.1 Max via Codex CLICheck Codex CLI installation status:
python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" providers
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 CLIgemini-cli/gemini-3-flash-preview - Gemini 3 Flash via CLICheck Gemini CLI installation status:
python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" providers
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:
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:
gpt-4o,gemini/gemini-2.0-flash,xai/grok-3)More models = more perspectives = stricter convergence.
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
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
Befor