# Installing deliberation in OpenCode

[OpenCode](https://opencode.ai) (by SST) reads modular project artifacts from a
`.opencode/` directory and MCP servers from an `opencode.json` config. The
deliberation artifacts are generated by `scripts/sync-hosts.js` from the
canonical sources (`prompts/*.md`, plus the shared command/expert tables), and
ship as:

- `.opencode/commands/*.md` - one thin slash-command per fan-out / single-provider
  tool (`/ask-all`, `/consensus`, `/ask-gpt`, `/ask-gemini`, `/ask-grok`,
  `/ask-openrouter`). Each just calls the matching deliberation MCP tool.
- `.opencode/agents/*.md` - one subagent per expert persona (`architect`,
  `plan-reviewer`, `scope-analyst`, `code-reviewer`, `security-analyst`,
  `researcher`, `debugger`), each with `mode: subagent`.

The MCP server itself is registered in your `opencode.json` (see below).

## 1. Register the MCP server

OpenCode loads MCP servers from the `mcp` key in `opencode.json` (project root)
or `~/.config/opencode/opencode.json` (global). The config file does **not** live
inside `.opencode/`. Add a local (stdio) server:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "deliberation": {
      "type": "local",
      "command": ["npx", "-y", "@antonbabenko/deliberation-mcp"],
      "enabled": true,
      "environment": {}
    }
  }
}
```

Source: [opencode.ai/docs/mcp-servers](https://opencode.ai/docs/mcp-servers/).
`type: "local"` is a stdio server; `command` is the argv array; `environment` is
optional. The bridges read provider credentials from the process environment
OpenCode launches the server in, so an empty `environment` is fine - set keys in
your shell (or add them under `environment`).

## 2. Drop in the commands and agents

Copy the generated `.opencode/commands/` and `.opencode/agents/` directories into
your project (or into `~/.config/opencode/` for global use - OpenCode uses the
same plural subdirectory names in both locations). The filename becomes the
command / agent name (`ask-all.md` -> `/ask-all`, `architect.md` -> the
`architect` subagent).

Source: [opencode.ai/docs/commands](https://opencode.ai/docs/commands/),
[opencode.ai/docs/agents](https://opencode.ai/docs/agents/).

## Provider credentials

The MCP server (`npx -y @antonbabenko/deliberation-mcp`, stdio) reads provider
credentials from the host environment. Set whichever providers you use:

| Provider | How it authenticates |
|----------|----------------------|
| GPT (Codex) | OpenAI / Codex CLI auth (Codex login or `OPENAI_API_KEY`) |
| Gemini | The Antigravity CLI (`agy`) - sign in once with the CLI |
| Grok (xAI) | `XAI_API_KEY` |
| OpenRouter | `OPENROUTER_API_KEY` (advisory-only; declare models in `~/.config/deliberation/config.json`) |

You only need the providers you intend to call - missing keys just disable that
one provider.

## Optional npm plugin (not shipped)

A `.opencode/plugins/` JS plugin could add a proactive "consider delegating"
nudge, and `opencode.json` supports an npm plugin array:

```json
{ "plugin": ["@antonbabenko/opencode-deliberation"] }
```

The npm name `@antonbabenko/opencode-deliberation` is currently **unpublished and
available** (npm returns 404). It is reserved here but intentionally not shipped:
the verified plugin hook API (`event`, `tool.execute.before`, `tool.execute.after`,
`shell.env`, `experimental.session.compacting`) has no hook that injects a
proactive delegation hint into the system prompt, so a plugin would add a runtime
dependency for no verified behavior win. The subagents plus the command wrappers
already give OpenCode the native delegation surface. If a suitable hook is added
upstream, confirm the export shape at
[opencode.ai/docs/plugins](https://opencode.ai/docs/plugins/) before shipping.

## Distribution

- **npm** - reserve / publish `@antonbabenko/opencode-deliberation` if a plugin
  ever ships (the MCP server is already on npm as `@antonbabenko/deliberation-mcp`).
- **OpenCode ecosystem listing** - submit to the official ecosystem page at
  [opencode.ai/docs/ecosystem](https://opencode.ai/docs/ecosystem/).
  [unverified] Confirm the exact submission path / PR target there.
- **awesome-opencode** - open a PR to the community
  [awesome-opencode](https://github.com/sst/awesome-opencode) list.
  [unverified] Confirm the repo path and listing format.

## Notes / verified vs. unverified

Verified against the official docs (fetched live):

- Command files live in `.opencode/commands/` (**plural**); frontmatter keys
  `description`, `agent`, `model`, `subtask`; `$ARGUMENTS` / `$1`...`$N` for input.
  Source: [opencode.ai/docs/commands](https://opencode.ai/docs/commands/).
- Agent files live in `.opencode/agents/` (**plural**); subagent uses
  `mode: subagent`; frontmatter `description` (required), `mode`, `model`,
  `temperature`, `permission`.
  Source: [opencode.ai/docs/agents](https://opencode.ai/docs/agents/).
- MCP `mcp` key shape (`type: "local"`, `command` array, `enabled`,
  `environment`) and `$schema: "https://opencode.ai/config.json"`.
  Source: [opencode.ai/docs/mcp-servers](https://opencode.ai/docs/mcp-servers/).
- The docs state the `.opencode` and `~/.config/opencode` directories use plural
  subdirectory names (`agents/`, `commands/`, `plugins/`, ...); the config file
  `opencode.json` lives at the project root / global, not inside `.opencode/`.
  Source: [opencode.ai/docs/config](https://opencode.ai/docs/config/).
- Plugin directory is `.opencode/plugins/` (plural); a plugin is a named async
  export returning a hooks object. Source:
  [opencode.ai/docs/plugins](https://opencode.ai/docs/plugins/).
- `@antonbabenko/opencode-deliberation` is unpublished/available on npm (404).

Unverified (confirm at the linked doc before relying on it):

- The exact OpenCode ecosystem submission flow and awesome-opencode listing format.
- Whether OpenCode does `${VAR}` substitution inside `environment` (deliberation
  reads keys from the process env, so this is not needed).
