Versus for Claude

IACDM (Iterative Adversarial Convergence Development Methodology) orchestrator for Claude Code.

An original methodology created by Jasmine Moreira that transforms LLMs from reactive code generators into disciplined agents following a structured 8-phase process — from problem discovery to delivery with tests and post-review.

Why?

AI coding tools (Lovable, Cursor, Claude Code, ChatGPT) all share the same fundamental limitation: zero internal verification capability. They generate statistically plausible output without distinguishing correct code from incorrect code. The METR study (2025) showed experienced developers using AI tools were actually 19% slower — despite believing they were 20% faster.

The real distinction isn't between tools — it's between process and no process.

Versus implements the AG/AV (Generative Agent / Verification Agent) model: the AI generates, external agents (automated tests + human operator) verify at discrete gates. Errors are caught at the earliest possible phase, not in production.

Features

• 8 sequential phases with verifiable exit criteria — no skipping steps
• 8 safeguards (S0-S7) that prevent common AI agent errors (premature convergence, scope creep, reimplementation)
• Convergence score (0-100) that gates advancement until the problem is truly understood
• 15 MCP tools for state management, decision recording, phase transitions, and meta-iteration (v1→v2)
• 3 Claude Code hooks — context injection, edit blocking in early phases, loop detection
• Persistent decision registry that survives context switches
• Gateway guard that detects when models skip loading context
• Adversarial critique with 7 universal + 8 conditional specialized lenses
• VS Code sidebar showing methodology state in real time
• Multi-session testing protocol for Phase 6 continuity across sessions

How It Works

Phase 0: Problem Discovery    → HSA 5-level exploration (score >= 90 to advance)
Phase 1: Architecture         → Define modules, interfaces, patterns
Phase 2: Adversarial Critique → Attack the architecture with specialized lenses
Phase 3: Simplification       → Address criticals, simplify (loops with Phase 2)
Phase 4: Convergence Gate     → Validate all exit criteria + safeguards
Phase 5: Implementation       → Code the final architecture
Phase 6: Tests                → 100% passing + exploratory testing
Phase 7: Post-Review          → Double-loop learning: evaluate product AND process

Phase 0: Hierarchical Semantic Analysis (HSA)

The most distinctive contribution. Structures problem exploration in 5 levels, each building on the previous:

Context Efficiency

The methodology maximizes E = I₀/C (relevant information / total context consumed) through granularization: each session focuses on one module with just its interface signatures, keeping context efficiency near 1.0 instead of degrading to 0.3+ in monolithic sessions.

Quick Start

1. Install the extension
2. Open the Command Palette (Ctrl+Shift+P) and run Versus Claude: Initialize Project
3. Enter a project name and description when prompted
4. Open a new Claude Code conversation (the extension configures hooks and MCP on initialization)
5. Type start — Claude will automatically load the methodology state and begin Phase 0

Important: After initializing, always start a new conversation so Claude picks up the MCP server and hooks. If Claude doesn't use MCP tools, run "Developer: Reload Window" from the Command Palette.

Claude Code Hooks

The 8 Safeguards

The AG/AV Model

F₀ → G₀ → F₁ → G₁ → ... → Fₙ → Gₙ → delivery
      ↑              ↑                    ↑
  AV evaluates   AV evaluates        AV evaluates

• AG (Generative Agent): The LLM. Produces artifacts without verification capability.
• AV-automatic: Tests, linters, compilers — binary verdict on formalizable properties.
• AV-human: The operator — evaluates semantic adequacy, usability, domain correctness.
• Gate (Gₖ): Discrete point where progression requires AV approval. Rejection feeds concrete error information back to AG.

LLM Compatibility

The IACDM methodology demands strict instruction following, reliable MCP tool calling, and sustained reasoning across long contexts. Not all models meet these requirements equally.

Selection Criteria

Model Tier Classification

Recommended Strategy (LLM Switch Point)

The methodology includes a natural LLM Switch Point at Phase 4. The architecture is fully validated and persisted in state.json + specs/, so no context is lost when switching models.

Rule of thumb: The cost of architectural error (detected in Phase 5-6) is 10-100x the cost of using a more capable model in Phases 0-4. Invest in reasoning where reasoning matters.

Built-in Protections for Weaker Models

Requirements

Node.js is mandatory. Without it, the MCP server cannot start and Claude will ignore the methodology entirely. Install from nodejs.org.

Companion Extension

Use Versus for Copilot for GitHub Copilot Agent Mode integration. Both extensions share the same .versus/state.json format.

License

MIT - Created by Jasmine Moreira.