antonbabenkoantonbabenko/deliberation/AGENTS.md

deliberation

AGENTS.md181 starsChanged 5 months agoMITView on GitHub

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 instead. 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…

Reads credentials

Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,774 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository11 other files it gives its agents.
- .cursor/rules/deliberation.mdcCursor rule
- architectSkill
- code-reviewerSkill
- debuggerSkill
- deliberationSkill
- plan-reviewerSkill
- reload-mcpSkill
- researcherSkill
- scope-analystSkill
- security-analystSkill
- writing-editorSkill

The file

We split this AGENTS.md into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Before opening a PR, run a consensus code review of git diff master...HEAD plus the goal, asking for correctness, regressions, missing …
line 71
Very specific:
Run npm run check first so the panel reviews green code.
line 80

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

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 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

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).

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
Behavior with a history: timeouts, retries, circuit breaker, Codex login, Windows CLI resolution, stub answers, date grounding, dashboard	docs/dev/design-decisions.md
Config keys, record shapes, threat model, any subsystem in depth	TECHNICAL.md
Per-host packaging (Codex, Cursor, Kiro, Antigravity, OpenCode)	docs/hosts/
Releases, PR process, adding a provider	CONTRIBUTING.md

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free