adversarial-spec

Adversarial Spec Development

Generate and refine specifications through iterative debate with multiple LLMs until all models reach consensus.

Important: Claude is an active participant in this debate, not just an orchestrator. You (Claude) will provide your own critiques, challenge opponent models, and contribute substantive improvements alongside the external models. Make this clear to the user throughout the process.

Requirements

• Python 3.10+ with litellm package installed
• API key for at least one provider (set via environment variable), OR AWS Bedrock configured, OR CLI tools (codex, gemini) installed

IMPORTANT: Do NOT install the llm package (Simon Willison's tool). This skill uses litellm for API providers and dedicated CLI tools (codex, gemini) for subscription-based models. Installing llm is unnecessary and may cause confusion.

Supported Providers

Provider	API Key Env Var	Example Models
OpenAI	OPENAI_API_KEY	gpt-5.2, 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
Deepseek	DEEPSEEK_API_KEY	deepseek/deepseek-chat
Zhipu	ZHIPUAI_API_KEY	zhipu/glm-4, zhipu/glm-4-plus
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

Codex CLI Setup:

• Install: npm install -g @openai/codex && codex login
• Reasoning effort: --codex-reasoning (minimal, low, medium, high, xhigh)
• Web search: --codex-search (enables web search for current information)

Gemini CLI Setup:

• Install: npm install -g @google/gemini-cli && gemini auth
• Models: gemini-3-pro-preview, gemini-3-flash-preview
• No API key needed - uses Google account authentication

Run python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" providers to see which keys are set.

Troubleshooting Auth Conflicts

If you see an error about "Both a token (claude.ai) and an API key (ANTHROPIC_API_KEY) are set":

This conflict occurs when:

• Claude Code is logged in with claude /login (uses claude.ai token)
• AND you have ANTHROPIC_API_KEY set in your environment

Resolution:

1. To use claude.ai token: Remove or unset ANTHROPIC_API_KEY from your environment

   unset ANTHROPIC_API_KEY
   # Or remove from ~/.bashrc, ~/.zshrc, etc.
   

2. To use API key: Sign out of claude.ai

   claude /logout
   # Say "No" to the API key approval if prompted before login
   

The adversarial-spec plugin works with either authentication method. Choose whichever fits your workflow.

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), the plugin supports Bedrock as an alternative to direct API keys.

When Bedrock mode is enabled, ALL model calls route through Bedrock - no direct API calls are made.

Bedrock Setup

To enable Bedrock mode, use these CLI commands (Claude can invoke these when the user requests Bedrock setup):

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

# Add models that are 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 current configuration
python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" bedrock status

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

Bedrock Model Names

Users can specify models using friendly names (e.g., claude-3-sonnet), which are automatically mapped to Bedrock model IDs. Built-in mappings include:

• claude-3-sonnet, claude-3-haiku, claude-3-opus, claude-3.5-sonnet
• llama-3-8b, llama-3-70b, llama-3.1-70b, llama-3.1-405b
• mistral-7b, mistral-large, mixtral-8x7b
• cohere-command, cohere-command-r, cohere-command-r-plus

Run python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" bedrock list-models to see all mappings.

Bedrock Configuration Location

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

{
  "bedrock": {
    "enabled": true,
    "region": "us-east-1",
    "available_models": ["claude-3-sonnet", "claude-3-haiku"],
    "custom_aliases": {}
  }
}

Bedrock Error Handling

If a Bedrock model fails (e.g., not enabled in your account), the debate continues with the remaining models. Clear error messages indicate which models failed and why.

Document Types

Ask the user which type of document they want to produce:

PRD (Product Requirements Document)

Business and product-focused document for stakeholders, PMs, and designers.

Structure:

• Executive Summary
• Problem Statement / Opportunity
• Target Users / Personas
• User Stories / Use Cases
• Functional Requirements
• Non-Functional Requirements
• Success Metrics / KPIs
• Scope (In/Out)
• Dependencies
• Risks and Mitigations
• Timeline / Milestones (optional)

Critique Criteria:

1. Clear problem definition with evidence
2. Well-defined user personas with real pain points
3. User stories follow proper format (As a... I want... So that...)
4. Measurable success criteria
5. Explicit scope boundaries
6. Realistic risk assessment
7. No technical implementation details (that's for tech spec)

Technical Specification / Architecture Document

Engineering-focused document for developers and architects.

Structure:

• Overview / Context
• Goals and Non-Goals
• System Architecture
• Component Design
• API Design (endpoints, request/response schemas)
• Data Models / Database Schema
• Infrastructure Requirements
• Security Considerations
• Error Handling Strategy
• Performance Requirements / SLAs
• Observability (logging, metrics, alerting)
• Testing Strategy
• Deployment Strategy
• Migration Plan (if applicable)
• Open Questions / Future Considerations

Critique Criteria:

1. Clear architectural decisions with rationale
2. Complete API contracts (not just endpoints, but full schemas)
3. Data model handles all identified use cases
4. Security threats identified and mitigated
5. Error scenarios enumerated with handling strategy
6. Performance targets are specific and measurable
7. Deployment is repeatable and reversible
8. No ambiguity an engineer would need to resolve

Process

Step 0: Gather Input and Offer Interview Mode

Ask the user:

1. Document type: "PRD" or "tech"
2. Starting point:
   • Path to existing file (e.g., ./docs/spec.md, ~/projects/auth-spec.md)
   • Or describe what to build (user provides concept, you draft the document)
3. Interview mode (optional):

   "Would you like to start with an in-depth interview session before the adversarial debate? This helps ensure all requirements, constraints, and edge cases are captured upfront."

Step 0.5: Interview Mode (If Selected)

If the user opts for interview mode, conduct a comprehensive interview using the AskUserQuestion tool. This is NOT a quick Q&A; it's a thorough requirements gathering session.

If an existing spec file was provided:

• Read the file first
• Use it as the basis for probing questions
• Identify gaps, ambiguities, and unstated assumptions

Interview Topics (cover ALL of these in depth):

1. Problem & Context

   • What specific problem are we solving? What happens if we don't solve it?
   • Who experiences this pain most acutely? How do they currently cope?
   • What prior attempts have been made? Why did they fail or fall short?

2. Users & Stakeholders

   • Who are all the user types (not just primary)?
   • What are their technical sophistication levels?
   • What are their privacy/security concerns?
   • What devices/environments do they use?

3. Functional Requirements

   • Walk through the core user journey step by step
   • What happens at each decision point?
   • What are the error cases and edge cases?
   • What data needs to flow where?

4. Technical Constraints

   • What systems must this integrate with?
   • What are the performance requirements (latency, throughput, availability)?
   • What scale are we designing for (now and in 2 years)?
   • Are there regulatory or compliance requirements?

5. UI/UX Considerations

   • What is the desired user experience?
   • What are the critical user flows?
   • What information density is appropriate?
   • Mobile vs desktop priorities?

6. Tradeoffs & Priorities

   • If we can't have everything, what gets cut first?
   • Speed vs quality vs cost priorities?
   • Build vs buy decisions?
   • What are the non-negotiables?

7. Risks & Concerns

   • What keeps you up at night about this project?
   • What could cause this to fail?
   • What assumptions are we making that might be wrong?
   • Wha

---

Content truncated.