Skip to content
Back to search

adversarial-spec

MarketplaceWorks with Claude CodeGitHub

A Claude Code plugin that iteratively refines product specifications by debating between multiple LLMs until all models reach consensus.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zscole-adversarial-spec/badge.svg)](/listings/zscole-adversarial-spec)

HTML

<a href="/listings/zscole-adversarial-spec"><img src="/api/listings/zscole-adversarial-spec/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 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"

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 19 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "adversarial-spec",
  3. "owner": {
  4. "name": "zscole"
  5. },
  6. "metadata": {
  7. "description": "Adversarial spec development through multi-model debate",
  8. "version": "1.0.0"
  9. },
  10. "plugins": [
  11. {
  12. "name": "adversarial-spec",
  13. "description": "Iteratively refine product specs through multi-model debate until consensus",
  14. "source": "./",
  15. "keywords": ["spec", "prd", "technical-specification", "llm", "debate", "consensus"],
  16. "skills": ["./skills/adversarial-spec"]
  17. }
  18. ]
  19. }
README.md · README · 576 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # adversarial-spec
  2. A Claude Code plugin that iteratively refines product specifications through multi-model debate until consensus is reached.
  3. **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.
  4. **Claude is an active participant**, not just an orchestrator. Claude provides independent critiques, challenges opponent models, and contributes substantive improvements alongside external models.
  5. ## Quick Start
  6. ```bash
  7. # 1. Add the marketplace and install the plugin
  8. claude plugin marketplace add zscole/adversarial-spec
  9. claude plugin install adversarial-spec
  10. # 2. Set at least one API key
  11. export OPENAI_API_KEY="sk-..."
  12. # Or use OpenRouter for access to multiple providers with one key
  13. export OPENROUTER_API_KEY="sk-or-..."
  14. # 3. Run it
  15. /adversarial-spec "Build a rate limiter service with Redis backend"
  16. ```
  17. ## How It Works
  18. ```
  19. You describe product --> Claude drafts spec --> Multiple LLMs critique in parallel
  20. | |
  21. | v
  22. | Claude synthesizes + adds own critique
  23. | |
  24. | v
  25. | Revise and repeat until ALL agree
  26. | |
  27. +--------------------------------------------->|
  28. v
  29. User review period
  30. |
  31. v
  32. Final document output
  33. ```
  34. 1. Describe your product concept or provide an existing document
  35. 2. (Optional) Start with an in-depth interview to capture requirements
  36. 3. Claude drafts the initial document (PRD or tech spec)
  37. 4. Document is sent to opponent models (GPT, Gemini, Grok, etc.) for parallel critique
  38. 5. Claude provides independent critique alongside opponent feedback
  39. 6. Claude synthesizes all feedback and revises
  40. 7. Loop continues until ALL models AND Claude agree
  41. 8. User review period: request changes or run additional cycles
  42. 9. Final converged document is output
  43. ## Requirements
  44. - Python 3.10+
  45. - `litellm` package: `pip install litellm`
  46. - API key for at least one LLM provider
  47. ## Supported Models
  48. | Provider | Env Var | Example Models |
  49. |------------|------------------------|----------------------------------------------|
  50. | OpenAI | `OPENAI_API_KEY` | `gpt-4o`, `gpt-4-turbo`, `o1` |
  51. | Anthropic | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514`, `claude-opus-4-20250514` |
  52. | Google | `GEMINI_API_KEY` | `gemini/gemini-2.0-flash`, `gemini/gemini-pro` |
  53. | xAI | `XAI_API_KEY` | `xai/grok-3`, `xai/grok-beta` |
  54. | Mistral | `MISTRAL_API_KEY` | `mistral/mistral-large`, `mistral/codestral` |
  55. | Groq | `GROQ_API_KEY` | `groq/llama-3.3-70b-versatile` |
  56. | OpenRouter | `OPENROUTER_API_KEY` | `openrouter/openai/gpt-4o`, `openrouter/anthropic/claude-3.5-sonnet` |
  57. | Codex CLI | ChatGPT subscription | `codex/gpt-5.2-codex`, `codex/gpt-5.1-codex-max` |
  58. | Gemini CLI | Google account | `gemini-cli/gemini-3-pro-preview`, `gemini-cli/gemini-3-flash-preview` |
  59. | Deepseek | `DEEPSEEK_API_KEY` | `deepseek/deepseek-chat` |
  60. | Zhipu | `ZHIPUAI_API_KEY` | `zhipu/glm-4`, `zhipu/glm-4-plus` |
  61. Check which keys are configured:
  62. ```bash
  63. python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" providers
  64. ```
  65. ## AWS Bedrock Support
  66. For enterprise users who need to route all model calls through AWS Bedrock (e.g., for security compliance or inference gateway requirements):
  67. ```bash
  68. # Enable Bedrock mode
  69. python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" bedrock enable --region us-east-1
  70. # Add models enabled in your Bedrock account
  71. python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" bedrock add-model claude-3-sonnet
  72. python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" bedrock add-model claude-3-haiku
  73. # Check configuration
  74. python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" bedrock status
  75. # Disable Bedrock mode
  76. python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" bedrock disable
  77. ```
  78. 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.
  79. Configuration is stored at `~/.claude/adversarial-spec/config.json`.
  80. ## OpenRouter Support
  81. [OpenRouter](https://openrouter.ai) provides unified access to multiple LLM providers through a single API. This is useful for:
  82. - Accessing models from multiple providers with one API key
  83. - Comparing models across different providers
  84. - Automatic fallback and load balancing
  85. - Cost optimization across providers
  86. **Setup:**
  87. ```bash
  88. # Get your API key from https://openrouter.ai/keys
  89. export OPENROUTER_API_KEY="sk-or-..."
  90. # Use OpenRouter models (prefix with openrouter/)
  91. python3 debate.py critique --models openrouter/openai/gpt-4o,openrouter/anthropic/claude-3.5-sonnet < spec.md
  92. ```
  93. **Popular OpenRouter models:**
  94. - `openrouter/openai/gpt-4o` - GPT-4o via OpenRouter
  95. - `openrouter/anthropic/claude-3.5-sonnet` - Claude 3.5 Sonnet
  96. - `openrouter/google/gemini-2.0-flash` - Gemini 2.0 Flash
  97. - `openrouter/meta-llama/llama-3.3-70b-instruct` - Llama 3.3 70B
  98. - `openrouter/qwen/qwen-2.5-72b-instruct` - Qwen 2.5 72B
  99. See the full model list at [openrouter.ai/models](https://openrouter.ai/models).
  100. ## Codex CLI Support
  101. [Codex CLI](https://github.com/openai/codex) allows ChatGPT Pro subscribers to use OpenAI models without separate API credits. Models prefixed with `codex/` are routed through the Codex CLI.
  102. **Setup:**
  103. ```bash
  104. # Install Codex CLI (requires ChatGPT Pro subscription)
  105. npm install -g @openai/codex
  106. # Use Codex models (prefix with codex/)
  107. python3 debate.py critique --models codex/gpt-5.2-codex,gemini/gemini-2.0-flash < spec.md
  108. ```
  109. **Reasoning effort:**
  110. Control how much thinking time the model uses with `--codex-reasoning`:
  111. ```bash
  112. # Available levels: low, medium, high, xhigh (default: xhigh)
  113. python3 debate.py critique --models codex/gpt-5.2-codex --codex-reasoning high < spec.md
  114. ```
  115. Higher reasoning effort produces more thorough analysis but uses more tokens.
  116. **Available Codex models:**
  117. - `codex/gpt-5.2-codex` - GPT-5.2 via Codex CLI
  118. - `codex/gpt-5.1-codex-max` - GPT-5.1 Max via Codex CLI
  119. Check Codex CLI installation status:
  120. ```bash
  121. python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" providers
  122. ```
  123. ## Gemini CLI Support
  124. [Gemini CLI](https://github.com/google-gemini/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.
  125. **Setup:**
  126. ```bash
  127. # Install Gemini CLI
  128. npm install -g @google/gemini-cli && gemini auth
  129. # Use Gemini CLI models (prefix with gemini-cli/)
  130. python3 debate.py critique --models gemini-cli/gemini-3-pro-preview < spec.md
  131. ```
  132. **Available Gemini CLI models:**
  133. - `gemini-cli/gemini-3-pro-preview` - Gemini 3 Pro via CLI
  134. - `gemini-cli/gemini-3-flash-preview` - Gemini 3 Flash via CLI
  135. Check Gemini CLI installation status:
  136. ```bash
  137. python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" providers
  138. ```
  139. ## OpenAI-Compatible Endpoints
  140. For models that expose an OpenAI-compatible API (local LLMs, self-hosted models, alternative providers), set `OPENAI_API_BASE`:
  141. ```bash
  142. # Point to a custom endpoint
  143. export OPENAI_API_KEY="your-key"
  144. export OPENAI_API_BASE="https://your-endpoint.com/v1"
  145. # Use with any model name
  146. python3 debate.py critique --models gpt-4o < spec.md
  147. ```
  148. This works with:
  149. - Local LLM servers (Ollama, vLLM, text-generation-webui)
  150. - OpenAI-compatible providers
  151. - Self-hosted inference endpoints
  152. ## Usage
  153. **Start from scratch:**
  154. ```
  155. /adversarial-spec "Build a rate limiter service with Redis backend"
  156. ```
  157. **Refine an existing document:**
  158. ```
  159. /adversarial-spec ./docs/my-spec.md
  160. ```
  161. You will be prompted for:
  162. 1. **Document type**: PRD (business/product focus) or tech spec (engineering focus)
  163. 2. **Interview mode**: Optional in-depth requirements gathering session
  164. 3. **Opponent models**: Comma-separated list (e.g., `gpt-4o,gemini/gemini-2.0-flash,xai/grok-3`)
  165. More models = more perspectives = stricter convergence.
  166. ## Document Types
  167. ### PRD (Product Requirements Document)
  168. For stakeholders, PMs, and designers.
  169. **Sections:** Executive Summary, Problem Statement, Target Users/Personas, User Stories, Functional Requirements, Non-Functional Requirements, Success Metrics, Scope (In/Out), Dependencies, Risks
  170. **Critique focuses on:** Clear problem definition, well-defined personas, measurable success criteria, explicit scope boundaries, no technical implementation details
  171. ### Technical Specification
  172. For developers and architects.
  173. **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
  174. **Critique focuses on:** Complete API contracts, data model coverage, security threat mitigation, error handling, specific performance targets, no ambiguity for engineers
  175. ## Core Features
  176. ### Interview Mode
  177. Before the debate begins, opt into an in-depth interview session to capture requirements upfront.
  178. **Covers:** Problem context, users/stakeholders, functional requirements, technical constraints, UI/UX, tradeoffs, risks, success criteria
  179. The interview uses probing follow-up questions and challenges assumptions. After completion, Claude synthesizes answers into a complete spec before starting the adversarial debate.
  180. ### Claude's Active Participation
  181. Each round, Claude:
  182. 1. Reviews opponent critiques for validity
  183. 2. Provides independent critique (what did opponents miss?)
  184. 3. States agreement/disagreement with specific points
  185. 4. Synthesizes all feedback into revisions
  186. Display format:
  187. ```
  188. --- Round N ---
  189. Opponent Models:
  190. - [GPT-4o]: critiqued: missing rate limit config
  191. - [Gemini]: agreed
  192. Claude's Critique:
  193. Security section lacks input validation strategy. Adding OWASP top 10 coverage.
  194. Synthesis:
  195. - Accepted from GPT-4o: rate limit configuration
  196. - Added by Claude: input validation, OWASP coverage
  197. - Rejected: none
  198. ```
  199. ### Early Agreement Verification
  200. If a model agrees within the first 2 rounds, Claude is skeptical. The model is pressed to:
  201. - Confirm it read the entire document
  202. - List specific sections reviewed
  203. - Explain why it agrees
  204. - Identify any remaining concerns
  205. This prevents false convergence from models that rubber-stamp without thorough review.
  206. ### User Review Period
  207. After all models agree, you enter a review period with three options:
  208. 1. **Accept as-is**: Document is complete
  209. 2. **Request changes**: Claude updates the spec, you iterate without a full debate cycle
  210. 3. **Run another cycle**: Send the updated spec through another adversarial debate
  211. ### Additional Review Cycles
  212. Run multiple cycles with different strategies:
  213. - First cycle with fast models (gpt-4o), second with stronger models (o1)
  214. - First cycle for structure/completeness, second for security focus
  215. - Fresh perspective after user-requested changes
  216. ### PRD to Tech Spec Flow
  217. When a PRD reaches consensus, you're offered the option to continue directly into a Technical Specification based on the PRD. This creates a complete documentation pair in a single session.
  218. ## Advanced Features
  219. ### Critique Focus Modes
  220. Direct models to prioritize specific concerns:
  221. ```bash
  222. --focus security # Auth, input validation, encryption, vulnerabilities
  223. --focus scalability # Horizontal scaling, sharding, caching, capacity
  224. --focus performance # Latency targets, throughput, query optimization
  225. --focus ux # User journeys, error states, accessibility
  226. --focus reliability # Failure modes, circuit breakers, disaster recovery
  227. --focus cost # Infrastructure costs, resource efficiency
  228. ```
  229. ### Model Personas
  230. Have models critique from specific professional perspectives:
  231. ```bash
  232. --persona security-engineer # Thinks like an attacker
  233. --persona oncall-engineer # Cares about debugging at 3am
  234. --persona junior-developer # Flags ambiguity and tribal knowledge
  235. --persona qa-engineer # Missing test scenarios
  236. --persona site-reliability # Deployment, monitoring, incidents
  237. --persona product-manager # User value, success metrics
  238. --persona data-engineer # Data models, ETL implications
  239. --persona mobile-developer # API design for mobile
  240. --persona accessibility-specialist # WCAG, screen readers
  241. --persona legal-compliance # GDPR, CCPA, regulatory
  242. ```
  243. Custom personas also work: `--persona "fintech compliance officer"`
  244. ### Context Injection
  245. Include existing documents for models to consider:
  246. ```bash
  247. --context ./existing-api.md --context ./schema.sql
  248. ```
  249. Use cases:
  250. - Existing API documentation the new spec must integrate with
  251. - Database schemas the spec must work with
  252. - Design documents or prior specs for consistency
  253. - Compliance requirements documents
  254. ### Session Persistence and Resume
  255. Long debates can crash or need to pause. Sessions save state automatically:
  256. ```bash
  257. # Start a named session
  258. echo "spec" | python3 debate.py critique --models gpt-4o --session my-feature-spec
  259. # Resume where you left off
  260. python3 debate.py critique --resume my-feature-spec
  261. # List all sessions
  262. python3 debate.py sessions
  263. ```
  264. Sessions save:
  265. - Current spec state
  266. - Round number
  267. - All configuration (models, focus, persona, etc.)
  268. - History of previous rounds
  269. Sessions are stored in `~/.config/adversarial-spec/sessions/`.
  270. ### Auto-Checkpointing
  271. When using sessions, each round's spec is saved to `.adversarial-spec-checkpoints/`:
  272. ```
  273. .adversarial-spec-checkpoints/
  274. ├── my-feature-spec-round-1.md
  275. ├── my-feature-spec-round-2.md
  276. └── my-feature-spec-round-3.md
  277. ```
  278. Use these to rollback if a revision makes things worse.
  279. ### Preserve Intent Mode
  280. Convergence can sand off novel ideas when models interpret "unusual" as "wrong". The `--preserve-intent` flag makes removal expensive:
  281. ```bash
  282. --preserve-intent
  283. ```
  284. When enabled, models must:
  285. 1. **Quote exactly** what they want to remove or substantially change
  286. 2. **Justify the harm** - not just "unnecessary" but what concrete problem it causes
  287. 3. **Distinguish error from preference** - only remove things that are factually wrong, contradictory, or risky
  288. 4. **Ask before removing** unusual but functional choices: "Was this intentional?"
  289. This shifts the default from "sand off anything unusual" to "add protective detail while preserving distinctive choices."
  290. Use when:
  291. - Your spec contains intentional unconventional choices
  292. - You want models to challenge your ideas, not homogenize them
  293. - Previous rounds removed things you wanted to keep
  294. ### Cost Tracking
  295. Every critique round displays token usage and estimated cost:
  296. ```
  297. === Cost Summary ===
  298. Total tokens: 12,543 in / 3,221 out
  299. Total cost: $0.0847
  300. By model:
  301. gpt-4o: $0.0523 (8,234 in / 2,100 out)
  302. gemini/gemini-2.0-flash: $0.0324 (4,309 in / 1,121 out)
  303. ```
  304. ### Saved Profiles
  305. Save frequently used configurations:
  306. ```bash
  307. # Create a profile
  308. python3 debate.py save-profile strict-security \
  309. --models gpt-4o,gemini/gemini-2.0-flash \
  310. --focus security \
  311. --doc-type tech
  312. # Use a profile
  313. python3 debate.py critique --profile strict-security < spec.md
  314. # List profiles
  315. python3 debate.py profiles
  316. ```
  317. Profiles are stored in `~/.config/adversarial-spec/profiles/`.
  318. ### Diff Between Rounds
  319. See exactly what changed between spec versions:
  320. ```bash
  321. python3 debate.py diff --previous round1.md --current round2.md
  322. ```
  323. ### Export to Task List
  324. Extract actionable tasks from a finalized spec:
  325. ```bash
  326. cat spec-output.md | python3 debate.py export-tasks --models gpt-4o --doc-type prd
  327. ```
  328. Output includes title, type, priority, description, and acceptance criteria.
  329. Use `--json` for structured output suitable for importing into issue trackers.
  330. ## Telegram Integration (Optional)
  331. Get notified on your phone and inject feedback during the debate.
  332. **Setup:**
  333. 1. Message @BotFather on Telegram, send `/newbot`, follow prompts
  334. 2. Copy the bot token
  335. 3. Run: `python3 "$(find ~/.claude -name telegram_bot.py -path '*adversarial-spec*' 2>/dev/null | head -1)" setup`
  336. 4. Message your bot, run setup again to get your chat ID
  337. 5. Set environment variables:
  338. ```bash
  339. export TELEGRAM_BOT_TOKEN="..."
  340. export TELEGRAM_CHAT_ID="..."
  341. ```
  342. **Features:**
  343. - Async notifications when rounds complete (includes cost)
  344. - 60-second window to reply with feedback (incorporated into next round)
  345. - Final document sent to Telegram when debate concludes
  346. ## Output
  347. Final document is:
  348. - Complete, following full structure for document type
  349. - Vetted by all models until unanimous agreement
  350. - Ready for stakeholders without further editing
  351. Output locations:
  352. - Printed to terminal
  353. - Written to `spec-output.md` (PRD) or `tech-spec-output.md` (tech spec)
  354. - Sent to Telegram (if enabled)
  355. Debate summary includes rounds completed, cycles run, models involved, Claude's contributions, cost, and key refinements made.
  356. ## CLI Reference
  357. ```bash
  358. # Core commands
  359. debate.py critique --models MODEL_LIST --doc-type TYPE [OPTIONS] < spec.md
  360. debate.py critique --resume SESSION_ID
  361. debate.py diff --previous OLD.md --current NEW.md
  362. debate.py export-tasks --models MODEL --doc-type TYPE [--json] < spec.md
  363. # Info commands
  364. debate.py providers # List providers and API key status
  365. debate.py focus-areas # List focus areas
  366. debate.py personas # List personas
  367. debate.py profiles # List saved profiles
  368. debate.py sessions # List saved sessions
  369. # Profile management
  370. debate.py save-profile NAME --models ... [--focus ...] [--persona ...]
  371. # Bedrock management
  372. debate.py bedrock status # Show Bedrock configuration
  373. debate.py bedrock enable --region REGION # Enable Bedrock mode
  374. debate.py bedrock disable # Disable Bedrock mode
  375. debate.py bedrock add-model MODEL # Add model to available list
  376. debate.py bedrock remove-model MODEL # Remove model from list
  377. debate.py bedrock list-models # List built-in model mappings
  378. ```
  379. **Options:**
  380. - `--models, -m` - Comma-separated model list (auto-detects from available API keys if not specified)
  381. - `--doc-type, -d` - prd or tech
  382. - `--codex-reasoning` - Reasoning effort for Codex models (low, medium, high, xhigh; default: xhigh)
  383. - `--focus, -f` - Focus area (security, scalability, performance, ux, reliability, cost)
  384. - `--persona` - Professional persona
  385. - `--context, -c` - Context file (repeatable)
  386. - `--profile` - Load saved profile
  387. - `--preserve-intent` - Require justification for removals
  388. - `--session, -s` - Session ID for persistence and checkpointing
  389. - `--resume` - Resume a previous session
  390. - `--press, -p` - Anti-laziness check
  391. - `--telegram, -t` - Enable Telegram
  392. - `--json, -j` - JSON output
  393. ## File Structure
  394. ```
  395. adversarial-spec/
  396. ├── .claude-plugin/
  397. │ └── plugin.json # Plugin metadata
  398. ├── README.md
  399. ├── LICENSE
  400. └── skills/
  401. └── adversarial-spec/
  402. ├── SKILL.md # Skill definition and process
  403. └── scripts/
  404. ├── debate.py # Multi-model debate orchestration
  405. └── telegram_bot.py # Telegram notifications
  406. ```
  407. ## License
  408. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.