deliberation AGENTS.md

AGENTS.md

Host-neutral guidance for any AI coding agent connected to the deliberation MCP server. This file is standalone on purpose - it is not an include of CLAUDE.md, so it stays portable across hosts (Cursor, Codex, Kiro, Windsurf, Zed, and others). Claude Code users get the same routing from CLAUDE.md and the README; this file is for everyone else.

What deliberation is

A single MCP server that exposes GPT (via the Codex CLI), Gemini 3 (via the Antigravity CLI), Grok (via the xAI API), and OpenRouter models (400+, advisory) as expert subagents. You stay the primary agent. When a task benefits from a second opinion or cross-model review, call one of the tools below, read the result, and apply your own judgment. GPT and Gemini can also implement changes; Grok and OpenRouter only advise.

Tools

Fan-out and single-provider:

• ask-all - send one question to GPT, Gemini, Grok, and configured OpenRouter models in parallel, get every answer back independently (no cross-talk).
• consensus - run the FULL multi-round convergence loop server-side with a provider arbiter (blind pass + peer fan-out -> adjudicate -> revise) and get the converged verdict in one call. Depth is consensus.maxRounds (config, default 5); pass maxRounds to override. Pass synthesizeAlways:true for a SINGLE arbiter synthesis pass instead of the loop (best for open questions): it returns a free-text synthesis (the enum verdict and converged/confidence are null, rounds is 1). Set a concrete consensus.arbiter (a provider or openrouter:<alias>) for the server-side pass; in host mode the tool returns the opinions for YOU to synthesize. An optional blind pre-vote (consensus.blindVote) is available on the synthesize path.
• consensus-step - drive the loop yourself as the arbiter, one action per call: init (returns a sessionId + blind prompt) -> record_blind (your pre-commit verdict) -> dispatch_peers (the server fans out to the panel) -> submit_adjudication (your verdict + per-issue accept/dismiss/defer, each dismiss needs a reason) -> submit_revision (your revised plan), looping until converged or the round cap. State is held server-side by sessionId (ephemeral).
• ask-gpt / ask-gemini / ask-grok / ask-openrouter - one question to one provider for a single-shot second opinion.
• panel - return the exact provider names ask-all would dispatch for the current config + expert (enabled built-ins + eligible OpenRouter aliases, fanout cap applied), WITHOUT calling them. Read-only.
• ask-one { provider, prompt } - one question to ONE provider named by panel (e.g. codex, grok, openrouter:<alias>). The progress pattern: call panel, then issue one ask-one per name in a single turn so they run concurrently and each result lands independently as it finishes - visible per-provider progress with parallel wall-time, instead of the one opaque ask-all call. (The single-call ask-all still works; ask-one is the progressive alternative.)
• analyze - read-only run analytics. Reads the opt-in debug log (per-model p50/p95/max latency over SUCCESSFUL calls, mean tokens, error rate, reasoning effort) and the session store (verdict agreement rate), then returns advisory tuning suggestions (disable a slow/redundant model in ask-all, lower an OpenRouter model's reasoning, adjust maxFanout), plus OpenRouter compare links. Two lenses reported side by side - timing and agreement are NOT joined. configuredOnly (default true) hides models missing from the current config so a retired model cannot drive the numbers; since (24h, 7d, ...) windows both lenses. Needs debug.enabled for the timing lens. Writes nothing.