# 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, 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 prompt gets a better answer.

## Performance + debugging (optional)

These apply to every MCP host, not just Claude Code:

- **Per-provider progress** - prefer `panel` + parallel `ask-one` (above) when you want
  to watch each model finish instead of waiting on one opaque `ask-all` call.
- **Orientation auto-attach** - set `"orientation": { "enabled": true }` in `config.json`
  to have the server automatically attach a small repo bundle (CLAUDE.md, AGENTS.md,
  README.md, and key entrypoints, up to `maxFiles` files, default 6) to file-blind
  providers (Grok, OpenRouter) when they carry no files of their own. This gives them the
  same repo grounding that Codex and Gemini get by walking the filesystem. OFF by default;
  enable when file-blind providers underperform on repo-wide questions.
- **Timeouts** - each provider ships its own ceiling (codex 600s, gemini 300s, grok 180s,
  OpenRouter 180s). Raise them all with `"providers": { "defaults": { "timeout": 600000 } }`;
  override one with `providers.<name>.timeout` (`providers.openrouter.defaults.timeout` for
  OpenRouter), and a pinned model's `models.<id>.timeout` beats both. Read at server start,
  so a change needs a restart. A result that errors with `errorKind: "timeout"` at almost
  exactly the ceiling hit the limit rather than the model stalling.
- **Retries** - a failed call is retried once, and only for `network`, `rate-limit` (waiting
  for the upstream's `Retry-After`), and `empty` (a provider that exited clean but returned a
  stub instead of an answer). `timeout` and auth/config errors are not retried.
- **Debug log** - set `"debug": { "enabled": true }` in `config.json` to append one JSON
  line per provider call and per consensus round to `<XDG cache>/deliberation/debug.jsonl`
  (override with `DELIBERATION_DEBUG_LOG`). It records latency, reasoning effort, HTTP
  token usage, and voting/approval outcomes - never prompts, responses, or issue text.
  OFF by default.
- **Live progress notifications** - the server declares the MCP `logging` capability and
  emits `notifications/message` per provider as it settles during a fan-out. Hosts that
  render server log notifications mid-call show this automatically (Claude Code does not -
  hence the `panel` + `ask-one` pattern there).

## When to delegate

- Reviewing a plan or an architecture decision before you commit to it.
- A security review of auth, untrusted input, or a new endpoint.
- A second opinion when you are unsure, or after a fix has failed twice.
- Cross-model consensus on a high-stakes or contested call.

Skip delegation for simple edits, the first attempt at a fix, and trivial
questions you can answer directly.

## Updating

If you run the standalone server via `npx -y @antonbabenko/deliberation-mcp`,
each fresh resolve picks up the latest published version. `npx` caches resolved
packages, so if you keep getting an old build, clear the cache
(`rm -rf ~/.npm/_npx`) or pin/refresh the version in your host's MCP config.
(The Claude Code plugin manifest is a separate mechanism and does not affect
non-Claude hosts.)