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
   ```bash
   unset ANTHROPIC_API_KEY
   # Or remove from ~/.bashrc, ~/.zshrc, etc.
   ```

2. **To use API key**: Sign out of claude.ai
   ```bash
   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):

```bash
# 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`:

```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
-