Deliberationv4.6.1

Contributing to Deliberation

Contributions welcome. This document covers how to contribute effectively.


Quick Start

bash
# Clone the repo
git clone https://github.com/antonbabenko/deliberation
cd deliberation

# Run every check (typecheck + all test suites)
npm run check

# Claude Code: load the plugin from this checkout without reinstalling
claude --plugin-dir /path/to/deliberation

# Any other MCP host (Codex, Cursor, Kiro, Antigravity, OpenCode, ...):
# point its MCP config at the server in this checkout
node /path/to/deliberation/server/mcp/index.js

Agent instructions for working on this repo (any coding agent) are in AGENTS.md (external).


What to Contribute

Area Examples
New Providers Mistral, other local model integrations
Role Prompts New roles for prompts/, improved existing prompts
Rules Better delegation triggers, model selection logic
Bug Fixes Command issues, error messages
Documentation README improvements, examples, troubleshooting

Project Structure

text
deliberation/
├── core/                   # Host-neutral engine: providers, orchestration, consensus loop
├── server/                 # MCP server (server/mcp), provider bridges, local dashboard
├── prompts/                # Expert personas
├── rules/                  # Delegation rules (installed to ~/.claude/rules/ by the Claude Code plugin)
├── commands/               # Claude Code slash commands
├── config/                 # Config schema + defaults
├── scripts/                # sync-hosts.js (generates per-host files) and helpers
├── docs/                   # Tool guide, per-host docs, developer docs (docs/dev/)
├── site/                   # Website (Astro), built from the Markdown above; not released
├── .claude-plugin/         # Claude Code plugin manifest
├── AGENTS.md               # Instructions for coding agents working on this repo
└── README.md               # User-facing docs

Details: docs/dev/architecture.md (external).


Pull Request Process

Before Submitting

  1. Test your changes - npm run check, then try the change through a real MCP host
  2. Update docs - If you change behavior, update relevant docs
  3. Check the website - If you add or change a feature, host, provider, command, install step or config key, update the site's hand-written pages too. Doc pages are generated from the Markdown, but the home page, the features page and the install steps are not (list in AGENTS.md (external))
  4. Keep commits atomic - One logical change per commit

PR Guidelines

Do Don't
Focus on one change Bundle unrelated changes
Write clear commit messages Leave vague descriptions
Test with actual MCP calls Assume it works
Update docs (see the checklist in AGENTS.md) Ignore developer docs

Commit Message Format

text
type: short description

Longer explanation if needed.
Prefix Version bump
feat!: or BREAKING CHANGE: Major
feat: Minor
fix: Patch
docs, refactor, build, chore, style, test, ci, perf None

Only feat:, fix: and breaking changes cut a release. A push that contains only the other types produces an empty changelog and is skipped; those commits ship with the next release.

Examples:

  • feat: add Ollama provider support
  • fix: handle Codex timeout correctly
  • docs: add troubleshooting for auth issues

Release Process

Releases are automated from Conventional Commits (external). You never bump versions by hand.

  1. Merge a PR to master.
  2. The release workflow reads the commits since the last release and computes the next version (feat: -> minor, fix: -> patch, feat!: / BREAKING CHANGE: -> major).
  3. It opens a chore(release): vX.Y.Z PR that updates version.json, CHANGELOG.md, and the synced manifests, then auto-merges it once the validate check passes.
  4. On merge, a second workflow tags vX.Y.Z and publishes the GitHub Release.
  5. The antonbabenko/agent-plugins marketplace then re-pins deliberation to the new release (immediately if its dispatch token is set, otherwise within a day via cron).

version.json is the single source of truth. .claude-plugin/plugin.json, .claude-plugin/marketplace.json, package.json, server.json (both version lines), server/mcp/package.json, plugins/deliberation/.codex-plugin/plugin.json, gemini-extension.json, the root plugin.json (Kiro), and the serverInfo.version literal in server/mcp/index.js are kept in sync by CI (.github/release/pre-commit.js). Do not edit those version fields by hand - the validate check fails if they drift.

The website is not released

The website in site/ is built from this repo's Markdown and deployed to GitHub Pages by .github/workflows/site.yml. It never cuts a release:

  • A push to master that changes only site/** or .github/workflows/site.yml does not run the release workflow (paths-ignore in automated-release.yml).
  • Site work uses a type that does not release: docs(site):, chore(site): or ci(site):. These types add nothing to the changelog, so a site commit merged next to a feat: or fix: does not change the version bump or the release notes. Never use feat, fix, perf, revert or a ! for site work. Because PRs are squash-merged, this applies to the PR title.
  • Doc pages the site renders (README.md, SETUP.md, docs/...) keep their usual commit types. The site rebuilds on any change to them.

Fresh-machine check

Before you merge a release that touches setup, init, providers or the README quickstart, check that a new user with one API key still gets a first verdict in under two minutes. Use an empty home directory, an empty npm cache, and a PATH that holds only node, npm and npx, so no logged-in CLI or other key on your machine joins the panel:

bash
F=$(mktemp -d); mkdir -p "$F/home" "$F/cache" "$F/bin"
for b in node npm npx; do ln -s "$(command -v $b)" "$F/bin/$b"; done
time env -i HOME="$F/home" PATH="$F/bin:/usr/bin:/bin" npm_config_cache="$F/cache" \
  OPENROUTER_API_KEY="$OPENROUTER_API_KEY" npx -y @antonbabenko/deliberation-mcp@latest init --yes

Pass when the command exits 0, prints found: OpenRouter, a demo verdict: line and the install lines, prints no part of the key, and the real time is under two minutes. Run it a second time: it should change nothing and skip the demo. Delete $F afterwards; it holds a config file that names your providers.


Adding a New Provider

First decide whether you need code at all.

OpenAI-compatible endpoint: config only

Ollama and LM Studio already have their own provider blocks (providers.ollama, providers.lmstudio; see SETUP.md). Any other endpoint that serves POST /chat/completions (Mistral, DeepSeek, a self-hosted vLLM, ...) runs through the OpenRouter transport with no code change. OpenRouter is off by default, so enable it and declare a model record in ~/.config/deliberation/config.json:

json
{
  "providers": {
    "openrouter": { "enabled": true, "apiBase": "http://127.0.0.1:8000/v1" }
  },
  "models": {
    "local-qwen": { "provider": "openrouter", "model": "Qwen/Qwen2.5-Coder-32B-Instruct", "askAll": true }
  }
}

Where the endpoint comes from depends on the server:

  • The unified deliberation server (every non-Claude host, and ask-all / consensus) uses ONE endpoint for every record: providers.openrouter.apiBase, read at startup (restart the server after changing it). It always reads the key from OPENROUTER_API_KEY.
  • The standalone deliberation-openrouter bridge (Claude Code's /ask-openrouter) also honours a per-record apiBase and providers.openrouter.apiKeyEnv.

Either way the key is sent to that endpoint whenever the variable is set (an Authorization header is added only when it is), so point apiBase only at endpoints you trust with it. Record fields: config/config.schema.json (modelRecord) and TECHNICAL.md.

New transport: a built-in provider

Use this when the provider needs its own CLI, protocol, or file handling. Codex (core/providers/codex.js, spawns a CLI), Grok (core/providers/grok.js + server/grok/, HTTP bridge) and Gemini (core/providers/gemini.js, which picks the API key path on the shared OpenAI-compatible client or the opt-in agy CLI in core/providers/antigravity.js + server/gemini/) are the working examples. None of the tests need a real agy or a Gemini key: they use fixture CLIs and local mock servers. Read docs/dev/architecture.md (external) first, and the matching entries in docs/dev/design-decisions.md (external) (timeouts, retries, stub answers, CLI resolution).

  1. Adapter - core/providers/<name>.js returns a Provider (core/types.js): name, capabilities (canImplement: false unless it can write behind both implement locks), health() and ask(req). health() is stat-only and side-effect-free: report a missing CLI or key as { ok: false, reason } so the panel skips the peer. ask() returns a DelegationResult and never throws; turn failures into results with toErrorResult (core/provider.js) and a correct errorKind, because callProvider retries network, rate-limit, upstream and empty once, and the circuit breaker counts every error. Core never reads config or a bridge directly: take both through opts.

  2. Shared rules every adapter or bridge applies - prepend groundingNote() (core/grounding.js) to the prompt; clamp every ceiling with clampToHostBudget (core/host-budget.js) and honour req.hostBudgetRemainingMs; reject preamble-only replies with stubReason (core/answer-floor.js); resolve a CLI with core/resolve-bin.js, never shell: true.

  3. Bridge (HTTP or a CLI that needs its own MCP server) - server/<name>/index.js, zero dependencies. Register it in .claude-plugin/plugin.json mcpServers only if it should also run as a standalone server, with the same timeout and MCP_TOOL_TIMEOUT pair the other entries carry (test/plugin-manifest.test.js checks them).

  4. Wire it in - construct it in makeRuntime in server/mcp/index.js (read providers.<name> config there), then add the name to:

    • BUILTINS in core/registry.js (panel selection)
    • BUILTIN_NAMES, ASK_PROVIDER and ASK_AUTH in server/mcp/index.js (plus an ask-<name> tool if it gets one)
    • KNOWN_PROVIDERS and, if it can arbitrate, BUILTIN_ARBITERS in server/openrouter/config.js (timeout ladder and arbiter validation)
    • core/settings.js and core/analyze.js defaults, the provider lists in core/config-history.js (config provenance), and FIXED_KEY_ENVS in server/dashboard/server.js if it reads a fixed key env

    rg -n '"grok"' core server --glob '!**/dist/**' finds every list a built-in appears in; a new one belongs in each.

  5. Config - add providers.<name> to config/config.schema.json AND config/config.default.json. State any threat model (where keys or files go) in the schema description.

  6. Tests - an adapter test like test/core-grok.test.js (inject a fake bridge or CLI via CODEX_BIN/AGY_BIN-style overrides; no network) and a registry case in test/core-registry.test.js. npm run check must pass.

  7. Host surfaces and docs - commands/setup.md and commands/doctor.md (detect the CLI or key), an /ask-<name> command if it gets a tool, the docs checklist in AGENTS.md (external), then npm run sync.


Code Style

Markdown (Rules/Prompts)

  • Use tables for structured data
  • Keep prompts concise and actionable
  • Test with a real MCP host

JavaScript

  • Plain CommonJS on Node, no runtime dependencies (esbuild is a build-time devDep for the npm bundle only)
  • core/** and server/mcp/** are type-checked (tsconfig.json, strict checkJs): give exported functions JSDoc parameter and return types
  • No any without explicit justification; no @ts-ignore or @ts-expect-error

Testing

Manual Testing

After changes, verify with actual MCP calls:

  1. Load this checkout in an MCP host (see Quick Start)
  2. Claude Code only: run /deliberation:setup
  3. Verify the tools are listed (ask-gpt, ask-all, consensus, ...)
  4. Call a few tools, including an expert (architect, code-reviewer)
  5. Verify responses are properly synthesized
  6. Test error cases (timeout, missing CLI)

Questions?

Open an issue for:

  • Feature requests
  • Bug reports
  • Documentation gaps
  • Architecture discussions

Rendered from CONTRIBUTING.md in the repository.

Type to search the site.