/deliberation

name: "deliberation"
description: "When and how to delegate to GPT, Gemini, Grok, and OpenRouter expert subagents via the deliberation MCP tools."

<!-- GENERATED by scripts/sync-hosts.js - edit the source under prompts/, AGENTS.md, or examples/, then regenerate. -->

Deliberation

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, 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`). Two lenses reported side by side - timing and agreement are NOT joined. Needs `debug.enabled` for the timing lens. Writes nothing.

Every result carries `provider`, `model`, `text`, `ms` (wall time), and the effective `reasoningEffort` (real value for HTTP providers; `null` for the Codex/Gemini CLIs). HTTP providers (Grok, OpenRouter) also include token `usage`.

Expert personas (pass as the tool, or via the `expert` argument on the fan-out tools to apply one persona to every delegate):

• `architect` - system design, tradeoffs, complex decisions.
• `plan-reviewer` - check a plan is executable before work starts.
• `scope-analyst` - catch ambiguities and hidden requirements before planning.
• `code-reviewer` - bugs, security holes, maintainability on a diff or file.
• `security-analyst` - threat modeling and vulnerability assessment.
• `researcher` - external libraries, APIs, and best practices, with evidence.
• `debugger` - ranked root-cause hypotheses and the smallest safe fix.

Session tools (only useful when `sessions.persist` is enabled in config; they report "persistence disabled" otherwise). When on, `consensus`, the host-driven `consensus-step` loop (on a terminal converged/unresolved transition), and `ask-all` return a `sessionId`. By default the record stores the question + verdict/issue summaries only; set `sessions.captureText: true` to also persist each provider's response body (secret-scrubbed plus a best-effort PII pass). The metrics-only debug log never stores body text either way:

• `session-get { sessionId }` - fetch a recorded run (opinions, verdict, annotations).
• `session-revisit { sessionId }` - re-run the recorded question with the current

providers/config and save a linked child record. A `consensus` record replays its mode (the loop, or a synthesize pass).

• `session-annotate { sessionId, note }` - append a note to a run's audit trail.

There is no list tool: get the `sessionId` from the original run's result, or browse the store dir (`~/.cache/deliberation/sessions/`). See TECHNICAL.md "Session persistence" for a worked example.

Every fan-out, single-provider, and expert tool takes a `prompt`. Give it full context: the goal, the relevant code or paths, and any prior attempts. The experts do not share your session, so a self-contained pro