{ "markdown": "
\n\n\"3-Surgeons\n\n\n# 3-Surgeons\n\n**Three-model code review consensus — disagreement is the value, not consensus.**\n\nThree independent AI models cross-examine your code. They challenge each other's blind spots, hunt for what the others missed, and surface every disagreement instead of burying it. Built on five Constitutional Physics invariants and a four-phase operating protocol. Provider-agnostic across OpenAI, DeepSeek, Anthropic, Ollama, LM Studio, vLLM, and MLX.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![Providers](https://img.shields.io/badge/providers-OpenAI%20%7C%20DeepSeek%20%7C%20Ollama%20%7C%20MLX-27aae1.svg)](#provider-compatibility)\n[![Claude Code](https://img.shields.io/badge/Claude_Code-plugin-7c3aed.svg)](https://claude.com/claude-code)\n[![Corrigibility](https://img.shields.io/badge/Corrigibility-invariant-success.svg)](#why-it-works-corrigibility)\n[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing)\n\n[**Quick Start**](#quick-start) · [**Constitutional Physics**](#constitutional-physics) · [**Install**](#install) · [**IDE Compatibility**](#ide-compatibility) · [**Pairs With**](#pairs-with-superpowers-plugin)\n\n
\n\n---\n\n> Would you wing a complicated surgery with one surgeon?\n>\n> Then why are you shipping code reviewed by one AI?\n\n## The Problem\n\nEvery AI coding tool has the same flaw: **one model, one perspective, one set of blind spots.** Claude confabulates confidently where GPT hedges. GPT over-engineers where a local model stays lean. A single AI reviewer is a single point of failure — and you'd never accept that in a real operating room.\n\n## The Solution\n\n3-Surgeons puts three independent AI models on the same operating table. They don't just review — they **cross-examine**, challenge assumptions, and hunt for what the others missed. Your code ships only when all three agree it's ready.\n\n| | Surgeon | Role | Default Model |\n|---|---------|------|---------------|\n| 🔪 | **Atlas (Head Surgeon / Judge)** | Synthesizes findings, weighs evidence, decides, implements — never overrides without grounds | Claude (your IDE session) |\n| 🩺 | **Cardiologist (External Skeptic)** | External-model perspective from a different training distribution. Surfaces what Atlas can't see | DeepSeek-chat (drop-in OpenAI also supported) |\n| 🧠 | **Neurologist (Local Devil's Advocate)** | Runs locally for privacy and corrigibility. Forces counter-position before consensus locks in | DeepSeek-chat via local proxy (Qwen3-4B legacy) |\n\n---\n\n## The Vision: Calibrated Correctness at Any Scale\n\n> A single AI reviewer is a single point of failure. Three reviewers, hunting independently, force the truth into the open.\n\n3-Surgeons is built on one belief: **the bottleneck in AI-assisted coding is no longer speed — it's calibration.** A confidently wrong answer ships faster than a careful right one. Three independent surgeons make confidence *earnable* — every claim survives cross-examination or it dies on the table.\n\n| Scale | What it unlocks |\n|-------|-----------------|\n| **1 model** | One opinion. Fast. Possibly wrong, but you wouldn't know. |\n| **2 models** | A check. Often agree. Disagreement = stop and look. |\n| **3 models** | Triangulation. Truth becomes recoverable. The blind spot of any one model is exposed by the other two. |\n| **5+ models** | A specialty board. Each surgeon brings a different training distribution. Convergence under independent attack is *evidence*, not opinion. |\n| **Continuous review** | Every diff cross-examined. Every claim audited. Every blind spot named. Calibration compounds across the codebase. |\n\nThe protocol scales linearly with the number of surgeons. The architecture is provider-agnostic. **The only ceiling is your tolerance for groupthink.**\n\n---\n\n## Constitutional Physics\n\nFive principles that govern every surgical operation. These are invariants — no tool call, no config flag, no shortcut overrides them.\n\n| # | Principle | What it means |\n|---|-----------|----------------|\n| 1 | **Preserve Determinism** | Same inputs must produce the same output. Non-deterministic paths trigger safe mode and are flagged before shipping. |\n| 2 | **No Discovery at Injection** | Retrieval only during context injection — no new reasoning, no live inference. Prevents hallucinations from contaminating shared state. |\n| 3 | **Respect SOP Integrity** | Standard Operating Procedures change only when backed by reproducible evidence from at least two surgeons. Opinion alone is not enough. |\n| 4 | **Evidence Over Confidence** | Outcomes are the ground truth. A confident answer that contradicts observed behavior is wrong. |\n| 5 | **Prefer Reversible Actions** | Checkpoint before risk. Every destructive or irreversible action requires explicit surgeon consensus and a rollback path. |\n\n## Why It Works: Corrigibility\n\nMost AI tools optimize for **confidence**. 3-Surgeons optimizes for **correctness**.\n\nThe core principle: **no surgeon can conclude an opinion until an objective test of the opposing view yields legitimate data — only then is the opinion merited.**\n\nThis isn't just \"get a second opinion.\" It's an iterative consensus loop:\n\n1. **Each surgeon hunts independently** — different prompts, different search strategies, different biases\n2. **Cross-examination** — each surgeon reviews the others' findings and challenges weak points\n3. **Open exploration** — \"What are we ALL blind to? What assumptions remain unchallenged?\"\n4. **Consensus only when saturated** — disagreements are preserved, not suppressed\n\nFeel the difference between code that was *generated* and code that **survived**.\n\n## The 4-Phase Operating Protocol\n\n```\n┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌───────────┐\n│ 1. TRIAGE │───▶│ 2. OPERATE │───▶│ 3. REVIEW │───▶│ 4. CLOSE │\n│ Assess risk │ │ Independent │ │ Cross-exam │ │ Consensus │\n│ Set gates │ │ analysis │ │ Challenge │ │ or dissent│\n└─────────────┘ └──────────────┘ └─────────────┘ └───────────┘\n```\n\n**Triage** — Sentinel scans your change for complexity vectors and calibrates review intensity.\n**Operate** — Each surgeon analyzes independently. No groupthink.\n**Review** — Cross-examination. Each surgeon attacks the others' blind spots.\n**Close** — Consensus with confidence scores. Disagreements surfaced, never hidden.\n\n## Blast Radius Calibration\n\nNot every change needs a full surgery. 3-Surgeons adapts review intensity to risk:\n\n| Risk Level | Gate Intensity | When | Time |\n|------------|---------------|------|------|\n| **Light** | Sentinel scan only | Docs, config, cosmetic changes | <30s |\n| **Standard** | Sentinel + cross-exam + gains-gate | Feature work, refactors | <120s |\n| **Full** | All gates + counter-position + A/B | Architecture, security, schema, API changes | <300s |\n\nRisk is measured across blast radius, reversibility, security exposure, data impact, and external coupling. The highest-risk dimension determines the gate.\n\n## Prerequisites\n\n**Python 3.10+** is required for the MCP server (cross-examination tools in your IDE).\n\n```bash\n# Check your version\npython3 --version\n\n# If below 3.10, install via Homebrew (macOS)\nbrew install python@3.12\n\n# Or via pyenv (any platform)\npyenv install 3.12\npyenv global 3.12\n```\n\nThe `3s init` wizard will check your Python version and guide you if it's too old.\n\n## Quick Start\n\n```bash\n# 1. Install (Claude Code)\n/plugin marketplace add supportersimulator/3-surgeons\n/plugin install 3-surgeons@supportersimulator/3-surgeons\n\n# 2. Run the setup wizard\n3s init\n\n# 3. Set your API key(s)\nexport OPENAI_API_KEY=sk-...\n\n# 4. Verify all surgeons are reachable\n3s probe\n\n# 5. Your first cross-examination\n3s cross-exam \"Should we use Redis or PostgreSQL for session storage?\"\n```\n\n## Install\n\n### Claude Code (Marketplace)\n\n```bash\n/plugin marketplace add supportersimulator/3-surgeons\n/plugin install 3-surgeons@supportersimulator/3-surgeons\n```\n\n### VS Code (Agent Plugin — requires 1.110+)\n\n> **Important:** This uses VS Code's Agent Plugin system (Chat panel), NOT the traditional Extension Marketplace. You will NOT find it by searching in the Extensions sidebar.\n\n**Step 1: Install GitHub Copilot Chat**\n\nInstall the **GitHub Copilot Chat** extension from the VS Code Marketplace (not the legacy \"GitHub Copilot\" extension). Sign into GitHub with a Copilot-entitled account.\n\n**Step 2: Enable plugins and add the marketplace**\n\nOpen Settings (`Cmd+,` / `Ctrl+,`) and add these to your `settings.json`:\n\n```json\n{\n \"chat.plugins.enabled\": true,\n \"chat.plugins.marketplaces\": [\"supportersimulator/3-surgeons\"]\n}\n```\n\n**Step 3: Reload and verify**\n\n1. Reload window (`Cmd+Shift+P` → \"Developer: Reload Window\")\n2. Open the **Chat panel** (not Extensions sidebar)\n3. Type `@agentPlugins` to verify the plugin appears\n\n**Step 4: Set up the Python runtime**\n\nThe MCP tools need Python 3.10+ with the package installed:\n\n```bash\ngit clone https://github.com/supportersimulator/3-surgeons.git ~/3-surgeons\ncd ~/3-surgeons\npython3 -m venv .venv && .venv/bin/pip install -e '.[mcp]'\n```\n\n**Local path fallback** (if marketplace discovery doesn't resolve):\n\nAdd the cloned path directly in `settings.json`:\n\n```json\n{\n \"chat.plugins.paths\": {\n \"/Users/you/3-surgeons\": true\n }\n}\n```\n\n### Cursor\n\n```bash\ncursor plugin add supportersimulator/3-surgeons\n```\n\n### Codex CLI / Codex IDE Extension\n\n```bash\ngit clone https://github.com/supportersimulator/3-surgeons.git ~/.3surgeons/plugin\ncd ~/.3surgeons/plugin\npython3 -m venv .venv && .venv/bin/pip install -e '.[mcp]'\ncodex mcp add 3-surgeons -- ~/.3surgeons/plugin/bin/3surgeons-mcp\n```\n\nSee [CODEX.md](CODEX.md) for full setup, config options, and troubleshooting.\n\n### Gemini CLI\n\n```bash\ngemini extensions install https://github.com/supportersimulator/3-surgeons\n```\n\nSee [GEMINI.md](GEMINI.md) for full setup, backend configuration, and troubleshooting.\n\n### Manual (any IDE)\n\n```bash\ngit clone https://github.com/supportersimulator/3-surgeons.git ~/.claude/plugins/3-surgeons\ncd ~/.claude/plugins/3-surgeons\npython3 -m venv .venv && .venv/bin/pip install -e '.[mcp]'\n```\n\n## IDE Compatibility\n\n| IDE | Transport | Status |\n|-----|-----------|--------|\n| Claude Code | MCP (native) | ✅ Full support |\n| Cursor | HTTP bridge | ✅ Full support |\n| VS Code | HTTP bridge | ✅ Full support |\n| Windsurf | HTTP bridge | ✅ Full support |\n| Zed | HTTP bridge | ✅ Full support |\n| OpenCode | HTTP bridge | ✅ Full support |\n| Codex CLI / IDE | MCP (native) | ✅ Full support — see [CODEX.md](CODEX.md) |\n| Gemini CLI | MCP (extension) | ✅ Full support — see [GEMINI.md](GEMINI.md) |\n\nAll tools available via `3s serve` HTTP bridge. See `three_surgeons/config/ide-adapters/` for per-IDE configuration.\n\n## Three Modes\n\n| Mode | Cardiologist | Neurologist | Needs | Cost |\n|------|-------------|-------------|-------|------|\n| **Hybrid** (default) | OpenAI GPT-4.1-mini | Local Ollama qwen3:4b | 1 API key + Ollama | ~$0.003/query |\n| **API-Only** | OpenAI GPT-4.1-mini | DeepSeek deepseek-chat | 2 API keys | ~$0.005/query |\n| **Local-Only** | Ollama mistral:7b | Ollama qwen3:4b | Ollama installed | $0 |\n\nRun `3s init` to pick a mode, or copy a preset directly:\n\n```bash\ncp config/presets/api-only.yaml ~/.3surgeons/config.yaml\n```\n\n## Provider Compatibility\n\nAny endpoint implementing OpenAI's `/v1/chat/completions` API works with zero code changes:\n\n**Cloud:** OpenAI, DeepSeek, Groq, Grok (xAI), Mistral\n\n**Local:** Ollama, LM Studio, vLLM, MLX\n\nSee the [full provider matrix](skills/using-3-surgeons/SKILL.md#supported-providers) for endpoints, models, and pricing.\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `/probe` | Health check all three surgeons |\n| `/cross-exam` | Full 3-phase cross-examination |\n| `/sentinel` | Scan for complexity risk vectors |\n| `/gains-gate` | Infrastructure health gate |\n| `/challenge` | Neurologist corrigibility skeptic |\n\n## CLI\n\n```bash\n3s probe # Health check\n3s cross-exam \"topic\" # Full cross-examination\n3s consult \"topic\" # Quick parallel query\n3s consensus \"claim\" # Confidence-weighted vote\n3s sentinel \"content\" # Complexity vector scan\n3s gains-gate # Infrastructure health gate\n3s neurologist-challenge \"topic\" # Corrigibility skeptic\n3s ask-local \"prompt\" # Direct neurologist query\n3s ask-remote \"prompt\" # Direct cardiologist query\n3s research \"topic\" # Self-directed research\n3s ab-propose PARAM A B \"hyp\" # Propose A/B test\n```\n\n## Orchestration Chains\n\nCompose surgical operations into named, replayable chains:\n\n```bash\n3s chain run full-review # Run a named chain preset\n3s chain list # Show available presets\n3s chain show full-review # Inspect chain segments\n```\n\nBuilt-in presets: `full-review`, `quick-check`, `deep-audit`, `pre-merge`, `security-scan`. Chains are capability-adaptive — segments that require unavailable surgeons gracefully degrade or skip.\n\n## Configuration\n\nConfig lives in `~/.3surgeons/config.yaml` (user-level) or `.3surgeons.yaml` (project-level).\n\nRun `3s init` for guided setup, or copy a preset from `config/presets/`.\n\nSee `config/3surgeons.example.yaml` for the full schema.\n\n### Cardiologist Provider (OpenAI | DeepSeek)\n\nThe Cardiologist defaults to **OpenAI `gpt-4.1-mini`**. DeepSeek is a drop-in alternative — it speaks the same OpenAI-compatible `/v1/chat/completions` wire protocol, so no adapter changes are required.\n\n**Per-invocation CLI flag** (preserves backward-compat defaults):\n\n```bash\n3s --cardio-provider=deepseek cross-exam \"your topic\"\n3s --cardio-provider=openai probe # explicit default\n```\n\nWhen `--cardio-provider=deepseek` is set, the Cardiologist routes to `https://api.deepseek.com/v1` with model `deepseek-chat`. Common OpenAI model strings auto-translate:\n\n| OpenAI model | DeepSeek equivalent |\n|---|---|\n| `gpt-4.1-mini`, `gpt-4o-mini`, `gpt-4.1-nano`, `gpt-4.1` | `deepseek-chat` |\n| `o1-mini`, `o3-mini`, `o4-mini` | `deepseek-reasoner` |\n\n**Persistent YAML config:**\n\n```yaml\nsurgeons:\n cardiologist:\n provider: deepseek\n endpoint: https://api.deepseek.com/v1\n model: deepseek-chat # or deepseek-reasoner for o1-style reasoning\n api_key_env: Context_DNA_Deepseek\n```\n\nOr copy the ready-made preset:\n\n```bash\ncp config/presets/cardio-deepseek.yaml ~/.3surgeons/config.yaml\n```\n\n**API key resolution order (DeepSeek):**\n\n1. The env var named in `api_key_env` (default `Context_DNA_Deepseek`)\n2. `DEEPSEEK_API_KEY` (fallback — matches `/ersim/prod/backend/DEEPSEEK_API_KEY` in AWS Secrets Manager and `.env.example`)\n3. macOS Keychain via the 3-Surgeons MCP launcher (`3surgeons-mcp`)\n\nIf none are set and `--cardio-provider=deepseek` requires a live call, the CLI fails fast with an actionable message naming both env vars.\n\n**Status reporting:** `cap_status` / `3s status` surfaces the active provider under `surgeons.cardiologist.provider`, so IDE dashboards can render `Cardiologist: OK [deepseek]` vs `[openai]`.\n\n**Default unchanged:** omitting `--cardio-provider` and leaving `surgeons.cardiologist.provider` at its default preserves the original OpenAI `gpt-4.1-mini` behavior — no migration required.\n\n## Security\n\n- **All API keys are loaded from environment variables** — never hardcoded, never committed\n- **Local-Only mode**: zero data leaves your machine. The Neurologist runs entirely on your hardware\n- `.gitignore` excludes all secret files, config files, and databases\n- See `.env.example` for the full list of supported environment variables\n\n## Pairs With: Superpowers Plugin\n\n3-Surgeons provides the **epistemological layer** (truth calibration through multi-model consensus). The [Superpowers](https://github.com/supportersimulator/superpowers) plugin provides the **process layer** (workflow discipline, TDD, debugging, planning skills). Together they form a complete surgical operating environment — rigorous process AND rigorous truth-testing.\n\n## Pairs With: Multi-Fleet\n\n3-Surgeons is the *quality* dimension. [**Multi-Fleet**](https://github.com/supportersimulator/multi-fleet) is the *scale* dimension. Run 3-Surgeons on a single machine and you get calibrated correctness. Run it across a Multi-Fleet of N machines and every surgeon-trio shares findings via NATS — disagreements surface fleet-wide, consensus compounds across nodes. **Correctness × scale = a coding board of directors that never sleeps.**\n\n---\n\n## ContextDNA: The Full Operating Theater\n\n3-Surgeons works standalone. But it was built to be the scalpel in a much larger operating theater.\n\n**ContextDNA** adds persistent memory, a priority-scheduled local LLM (your Neurologist on steroids), adaptive webhook injection, and a butler subconscious that learns your codebase across sessions. Think of it as upgrading from a field hospital to a world-class surgical suite.\n\n*3-Surgeons adapts to the sophistication of your codebase.*\n\nWhen you're ready:\n\n```python\nfrom context_dna.adapters import priority_queue_adapter\nprovider = LLMProvider(config, query_adapter=priority_queue_adapter)\n```\n\nSee [docs/CONTEXTDNA-IDE-UPGRADE.md](docs/CONTEXTDNA-IDE-UPGRADE.md) for the full migration guide.\n\n## Five Invariance Skills\n\nThese are the load-bearing protocols. Each is a hard-gate — no surgeon can bypass them, no shortcut overrides them.\n\n| Skill | When to invoke | What it protects against |\n|-------|----------------|--------------------------|\n| **architectural-gate** | Before any architecture decision | Locking in a design before the other two surgeons have argued the opposite |\n| **counter-position** | Before any opinion is concluded | Confirmation bias — forces a steelman of the opposing view before signing off |\n| **pre-implementation-review** | After plan, before code | Building the wrong thing perfectly. Catches scope drift and missed requirements |\n| **post-implementation-verification** | After code, before merge | \"Looks done\" claims that don't survive contact with reality. Demands evidence, not confidence |\n| **invariance-health** | Continuously | Surgeon drift, stale API keys, model deprecations, silent provider degradation |\n\nThe skills compose. A high-risk change runs all five. A docs typo runs none. Risk tier (Light / Standard / Full) determines which fire automatically.\n\n## Showcase: A Real Disagreement\n\nA recent change proposed flipping the Cardiologist default from OpenAI to DeepSeek. Atlas (Claude) called it a clean swap — same wire protocol, lower cost. Cross-examination surfaced what the head surgeon missed:\n\n```\nAtlas (Head Surgeon):\n \"Drop-in. DeepSeek implements /v1/chat/completions. Ship it.\"\n Confidence: 0.92\n\nCardiologist (External Skeptic):\n \"Wire-compatible, yes. But o1-style reasoning models translate differently.\n Add an auto-translation table (gpt-4.1-mini -> deepseek-chat,\n o1-mini -> deepseek-reasoner) or downstream callers silently get the\n wrong model.\"\n Confidence: 0.78 — DISAGREES\n\nNeurologist (Local Devil's Advocate):\n \"API key resolution will silently fall through to the wrong env var.\n Add fallback chain: Context_DNA_Deepseek -> DEEPSEEK_API_KEY ->\n macOS Keychain -> fail-fast with an actionable message.\"\n Confidence: 0.81 — DISAGREES\n\nAtlas (synthesis):\n \"Both objections valid. Adding model translation table + keychain fallback\n before merging. New confidence: 0.96.\"\n```\n\nThe shipped commit (`93b01c8`) includes both safeguards. Without the two dissenting surgeons, the rollout would have produced silent 401s and wrong-model responses. **Disagreement was the value, not the consensus.**\n\n## Why Disagreements = Value\n\nWhen all three surgeons agree immediately, that is a weak signal — it may mean groupthink, not correctness. When they disagree, that is the system working.\n\nA disagreement surfaces:\n- An assumption one model holds that the others don't\n- A risk one model has been trained to weight differently\n- A blind spot in the majority view\n\n3-Surgeons never suppresses disagreements. Confidence scores in the final consensus output show exactly where the surgeons diverged and why. The human (or orchestrating agent) decides what to do with that signal — but they decide with full information.\n\n**The goal is not fast consensus. The goal is calibrated confidence.**\n\n## Contributing\n\n1. Fork the repo\n2. Create a feature branch\n3. Run tests: `python -m pytest tests/ -v`\n4. Submit a PR\n\n## Status\n\n3-Surgeons is **production-tested at small scale**. It powers the daily review loop on a 4-node ContextDNA fleet (mac1, mac2, mac3, cloud) — every commit, every cross-examination, every consensus claim ships through the protocol. It has survived provider outages, model deprecations, and partial-network partitions without dropping a verdict.\n\nIt is **deliberately scoped**: 3-Surgeons does cross-examination, nothing else. Process discipline pairs with [Superpowers](https://github.com/supportersimulator/superpowers); fleet scale pairs with [Multi-Fleet](https://github.com/supportersimulator/multi-fleet); orchestration pairs with whatever IDE you live in.\n\nWe invite you to test it at your scale.\n\n---\n\n## License\n\nMIT — do anything you want, just keep the copyright notice. See [LICENSE](LICENSE).\n\n---\n\n
\n\n**Built for engineers who don't ship code reviewed by a single model.**\n\n⭐ Star this repo if you've ever shipped a bug all three would have caught.\n\n
\n", "bytes": 21801, "sha": "fbea62476fea5e5eac430bad60a82e2ed3a585fbafc7fac469c575112a45db5b", "repo_slug": "supportersimulator/3-surgeons", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_supportersimulator_3_surgeons_eba6b68f/readme" }