AGENTS.md git:20261027.bb6611eA

Immutable. This exact content never changes and is served at /api/v1/blob/5de8dc25fd7d2990.

# AGENTS.md

Instructions for any coding agent (Claude Code, Codex, Cursor, Gemini, Kiro, OpenCode, ...)
working on this repository. For how to USE deliberation as an MCP server, read
[docs/tool-guide.md](docs/tool-guide.md) instead.

## What this repo is

deliberation gives a host agent GPT (Codex CLI), Gemini 3 (Antigravity CLI `agy`), Grok
(xAI API) and OpenRouter models as expert reviewers over MCP. It ships as a Claude Code
plugin, as native plugins/skills for other hosts, and as one standalone MCP server
(`@antonbabenko/deliberation-mcp`). Eight expert personas live in `prompts/`. Every provider
is advisory except Gemini, which can also implement (`workspace-write`).

Plain Node (18+; CI runs 20), no runtime dependencies, no build step for development. `core/` is
host-neutral and strict-typed (`checkJs`); `server/mcp/` is the MCP server over it;
`server/{gemini,grok,openrouter}/` are the provider bridges; `server/dashboard/` is the
local read-only dashboard.

## Commands

```bash
npm run check                 # typecheck + every test suite; must pass before any PR
npm run test:contracts        # hermetic multi-host contract suite
npm run sync                  # regenerate every generated file (personas, host files, command fallbacks)
npm run sync:check            # fail if any generated file is stale (CI runs the same check)
node server/mcp/index.js      # run the MCP server from this checkout (any host)
claude --plugin-dir .         # Claude Code: load the plugin from this checkout
```

Some bridge tests listen on `127.0.0.1` and `npm run sync` writes `.mcp.json` files; an
agent sandbox may block both, so rerun outside it when you see `EPERM`.

## Rules for every change

**Docs ship in the same PR.** A tool, config key, flag, default, persisted shape, or any
user-visible behavior is not done until every surface it touches is current:

- `README.md` - feature list and config summaries
- `TECHNICAL.md` - deep reference: config tables, shapes, threat-model notes
- `SETUP.md` - user config walkthrough and examples
- `docs/tool-guide.md` - host-neutral tool and behavior surface
- `docs/dev/architecture.md` and `docs/dev/design-decisions.md` - when structure changes or
  you make a choice a future reader would question
- `config/config.schema.json` AND `config/config.default.json` - every new key needs both
  (state any threat model in the schema description); the `validate` check fails on drift
- `commands/` and skill prose, when the behavior they describe changed

**Generated files.** `npm run sync` writes three kinds of output. Edit the source, regenerate,
and commit both:

- `scripts/sync-prompts.js`: `prompts/*.md` -> `core/prompts/index.js`
- `scripts/sync-fallbacks.js`: `prompts/*.md` -> the fallback block at the end of
  `commands/ask-*.md` (everything else in those commands is hand-written)
- `scripts/sync-hosts.js`: `docs/tool-guide.md`, `prompts/`, `rules/`, `examples/` ->
  `POWER.md`, `steering/`, `.cursor/rules/`, `plugins/deliberation/` (skills,
  `.codex-plugin/`, `.mcp.json`), `.agents/`, `.gemini/`, `.opencode/`, `mcp.json`, `.mcp.json`

Markdown outputs carry a `GENERATED by scripts/...` banner; JSON outputs cannot, so trust the
list above and `npm run sync:check`, which fails on any stale output.

**Release files.** `CHANGELOG.md`, `version.json` and every synced version field belong to
the release automation. Commits follow Conventional Commits; only `feat:`, `fix:` and
breaking changes cut a release ([CONTRIBUTING.md](CONTRIBUTING.md#release-process)).

**Done means:** `npm run check` and `npm run sync:check` pass, and `git grep` for any old name or flag finds no
stale reference in docs.

## Pre-PR cross-model review

Before opening a PR, run a consensus code review of `git diff master...HEAD` plus the goal,
asking for correctness, regressions, missing tests and doc drift. Your host needs this
checkout's MCP server (`node server/mcp/index.js`) and at least one working provider
(a logged-in `codex` or `agy` CLI, or `XAI_API_KEY` / `OPENROUTER_API_KEY`):

- Claude Code: `/consensus` (you arbitrate, driven by `commands/consensus.md`).
- Any other host: call the `consensus-step` MCP tool and arbitrate per
  `commands/consensus.md`, or call `consensus` for a server-side provider arbiter.

Run `npm run check` first so the panel reviews green code. Fix every accepted CRITICAL
issue and rerun until it converges; put the reason for each dismissed issue in the PR
description. Skip only for `chore(release):` commits and doc-only typo fixes.

## Where to read next

| Working on | Read |
|------------|------|
| `core/`, `server/`, the consensus loop, providers, repo layout | [docs/dev/architecture.md](docs/dev/architecture.md) |
| Behavior with a history: timeouts, retries, circuit breaker, Codex login, Windows CLI resolution, stub answers, date grounding, dashboard | [docs/dev/design-decisions.md](docs/dev/design-decisions.md) |
| Config keys, record shapes, threat model, any subsystem in depth | [TECHNICAL.md](TECHNICAL.md) |
| Per-host packaging (Codex, Cursor, Kiro, Antigravity, OpenCode) | [docs/hosts/](docs/hosts/) |
| Releases, PR process, adding a provider | [CONTRIBUTING.md](CONTRIBUTING.md) |