antonbabenko · antonbabenko · Jun 5, 2026 · Jun 5, 2026
diff --git a/.gitignore b/.gitignore
@@ -10,7 +10,8 @@ coverage/
 # Node (handled in subdirs but good to have at root)
 node_modules/
 
-docs/
+docs/superpowers/
+docs/plans/
 
 # Antigravity CLI project-local data (created by agy when run in a repo)
 .antigravitycli/

diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 Get a second opinion in Claude Code from GPT, Gemini, and Grok - plus 400+ more models through OpenRouter, including Qwen, Kimi, and DeepSeek. Seven domain experts (Architect, Code Reviewer, Security Analyst, and four more) review your plans, find bugs, and debate edge cases until they agree.
 
-[![Four chairs at the table: Claude, GPT, Gemini, Grok - one verdict you can ship](assets/agents.png)<br>One model is a guess. Three that agree is a plan. → read the blog post](https://builder.aws.com/content/3DtBiR4ua0qy7ybZMPzPmQ2SDMj/one-model-is-a-guess-three-that-agree-is-a-plan)
+![Four chairs at the table: Claude, GPT, Gemini, Grok - one verdict you can ship](assets/agents.png)<br>Recent blog post: [Meet Deliberation: 400+ models is easy, knowing which ones earn a place is hard.](https://builder.aws.com/content/3Eaq94hQW8HywInrVaQm9qNih1P/meet-deliberation-400-models-is-easy-knowing-which-ones-earn-a-place-is-hard)
 
 <details>
 <summary>📸 See a full <code>/consensus</code> run: round 1 disagreement to round 5 convergence</summary>
@@ -149,7 +149,7 @@ Beyond the raw MCP config above, deliberation ships **native plugin artifacts**
 
 Provider credentials work the same as the standalone server (GPT via the Codex CLI, Gemini via `agy`, `XAI_API_KEY` for Grok, `OPENROUTER_API_KEY` for OpenRouter) - set only the providers you use. The MCP server already injects each expert persona server-side, so these native files add the host's command/steering surface, not duplicated logic.
 
-**Full per-host install guides:** [`public-docs/hosts/`](public-docs/hosts/) - [Cursor](public-docs/hosts/cursor.md), [Codex CLI](public-docs/hosts/codex.md), [Kiro](public-docs/hosts/kiro.md), [OpenCode](public-docs/hosts/opencode.md).
+**Full per-host install guides:** [`docs/hosts/`](docs/hosts/) - [Cursor](docs/hosts/cursor.md), [Codex CLI](docs/hosts/codex.md), [Kiro](docs/hosts/kiro.md), [OpenCode](docs/hosts/opencode.md).
 
 ## Requirements
 

diff --git a/docs/hosts/README.md b/docs/hosts/README.md
@@ -0,0 +1,21 @@
+# Per-host install guides
+
+deliberation ships native plugin artifacts for non-Claude hosts, generated from
+the canonical sources by `scripts/sync-hosts.js` (drift-guarded in CI). Full
+install instructions per host:
+
+- [Cursor](cursor.md) - `.cursor/rules/deliberation.mdc` + the one-click MCP deeplink.
+- [OpenAI Codex CLI](codex.md) - native plugin at `plugins/deliberation/`, installed via `codex plugin marketplace add antonbabenko/deliberation`.
+- [Kiro](kiro.md) - a Kiro Power (`POWER.md` + `mcp.json` + `steering/`), installed via "Add power from GitHub".
+- [OpenCode](opencode.md) - `.opencode/commands/` + `.opencode/agents/` + an `opencode.json` MCP snippet.
+
+All four route the same MCP tools (`ask-all`, `consensus`, `ask-gpt` / `ask-gemini`
+/ `ask-grok` / `ask-openrouter`, plus `panel` + `ask-one` for per-provider progress)
+and the seven expert personas (`architect`, `plan-reviewer`, `scope-analyst`,
+`code-reviewer`, `security-analyst`, `researcher`, `debugger`). Every result carries
+`ms` + reasoning effort (HTTP providers add token usage), and an optional config-gated
+debug log records latency / tokens / votes - all server-side, so they apply on every
+host (see [AGENTS.md](../../AGENTS.md)). Provider credentials come from the host
+environment - set only the providers you use; missing keys just disable that one provider.
+
+For the Claude Code plugin itself, see the repo [README](../../README.md).
diff --git a/docs/hosts/codex.md b/docs/hosts/codex.md
@@ -0,0 +1,63 @@
+# Installing deliberation in the OpenAI Codex CLI
+
+[Codex](https://developers.openai.com/codex) installs reusable bundles as native
+**plugins**. The deliberation plugin lives in `plugins/deliberation/` in this repo
+and is discoverable through a repo-scoped marketplace, all generated by
+`scripts/sync-hosts.js` from the canonical sources (`AGENTS.md`, `prompts/*.md`).
+
+## Install
+
+```
+codex plugin marketplace add antonbabenko/deliberation
+```
+
+Then open the plugin directory with `/plugins` inside Codex and install
+**deliberation**. Codex reads the repo-scoped marketplace at
+`.agents/plugins/marketplace.json`, whose entry points at the plugin subdirectory
+`./plugins/deliberation` (a root `source.path` of `.` is rejected -
+openai/codex#17066 - so the plugin is shipped in a subdirectory).
+
+## What the plugin ships
+
+Plugin root: `plugins/deliberation/`
+
+- `.codex-plugin/plugin.json` - manifest. `interface` carries the required
+  `displayName`, `developerName`, `category`, and `capabilities` fields; `version`
+  is kept in sync with `version.json` by the release pipeline.
+- `.mcp.json` - registers the MCP server (`npx -y @antonbabenko/deliberation-mcp`,
+  stdio).
+- `skills/deliberation/SKILL.md` - "when to delegate" (from `AGENTS.md`).
+- `skills/<expert>/SKILL.md` - one skill per expert (`architect`, `plan-reviewer`,
+  `scope-analyst`, `code-reviewer`, `security-analyst`, `researcher`, `debugger`),
+  each carrying that expert's persona so Codex gets the same guidance natively.
+
+Once installed you get the deliberation MCP tools (`ask-all`, `consensus`,
+`ask-gpt` / `ask-gemini` / `ask-grok` / `ask-openrouter`, and the seven experts).
+
+## Provider credentials
+
+The MCP server reads credentials from the host environment. Set only the 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`) |
+
+Missing keys just disable that one provider.
+
+## Notes / verified vs unverified
+
+Verified against developers.openai.com/codex/plugins (+ the openai/codex plugin
+spec): the `.codex-plugin/plugin.json` manifest shape and required `interface`
+fields; `.mcp.json` and `skills/<name>/SKILL.md` at the plugin root; the
+repo-scoped `.agents/plugins/marketplace.json` and `codex plugin marketplace add
+owner/repo` install flow; the root-`source.path`-rejected requirement
+(openai/codex#17066).
+
+[unverified] The submission path for the curated "Codex Plugin Marketplace" (the
+`@plugin-creator` skill scaffolds entries; the public curation/submission flow is
+not yet pinned). Confirm at developers.openai.com/codex/plugins before claiming a
+curated-directory listing.
diff --git a/docs/hosts/cursor.md b/docs/hosts/cursor.md
@@ -0,0 +1,68 @@
+# Installing deliberation in Cursor
+
+[Cursor](https://cursor.com) connects to the deliberation MCP server and reads a
+project **rule** that tells the agent when to delegate. Both pieces are below.
+
+## 1. Add the MCP server
+
+Use the one-click button from the [README](../../README.md#install) ("Install in
+Cursor"), or add the server to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json`
+(project):
+
+```json
+{
+  "mcpServers": {
+    "deliberation": { "command": "npx", "args": ["-y", "@antonbabenko/deliberation-mcp"] }
+  }
+}
+```
+
+The one-click deeplink (`cursor://anysphere.cursor-deeplink/mcp/install?...`)
+cannot carry secrets - set provider keys in your environment (see below).
+
+## 2. Add the rule
+
+Copy the generated rule into your project so Cursor knows when to reach for the
+experts:
+
+```
+.cursor/rules/deliberation.mdc
+```
+
+It is generated by `scripts/sync-hosts.js` from `examples/cursor.md`. The
+frontmatter (`description`, `alwaysApply`) controls when Cursor loads it; the body
+routes plan/architecture/security reviews and second opinions to the right tool.
+The full surface (same as every host) is the fan-out / single-provider tools
+(`ask-all`, `consensus`, `ask-gpt` / `ask-gemini` / `ask-grok` / `ask-openrouter`)
+and the seven experts (`architect`, `plan-reviewer`, `scope-analyst`,
+`code-reviewer`, `security-analyst`, `researcher`, `debugger`).
+
+## Provider credentials
+
+The MCP server reads credentials from the host environment. Set only the 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`) |
+
+Missing keys just disable that one provider.
+
+## Distribution
+
+- **cursor.directory** - the community rules/MCP registry. Submit the rule via the
+  site's "Submit" flow / its GitHub repo.
+- [unverified] Whether the official Cursor Marketplace (cursor.com/marketplace)
+  accepts a self-serve third-party MCP+rules package - confirm with Cursor's
+  publisher docs before treating a Marketplace listing as available.
+
+## Notes / verified vs unverified
+
+Verified against cursor.com/docs + cursor.directory: project rules live in
+`.cursor/rules/*.mdc` (frontmatter `description` / `globs` / `alwaysApply`); MCP
+servers register under `mcpServers` in `~/.cursor/mcp.json` or `.cursor/mcp.json`;
+one-click install deeplink format
+`cursor://anysphere.cursor-deeplink/mcp/install?name=&config=<base64>`.
diff --git a/docs/hosts/kiro.md b/docs/hosts/kiro.md
@@ -0,0 +1,76 @@
+# Installing deliberation as a Kiro Power
+
+[Kiro](https://kiro.dev) (AWS) packages reusable tool + steering bundles as
+**Powers**. The deliberation Power ships a `POWER.md`, an `mcp.json`, and
+`steering/` files at the repo root, all generated by `scripts/sync-hosts.js` from
+the canonical sources (`AGENTS.md`, `rules/triggers.md`). A Power activates
+on-demand when its `keywords` match your task, so the MCP tools load only when a
+delegation is actually relevant.
+
+## Install
+
+In Kiro, use **Add power from GitHub** and paste this repository URL:
+
+```
+https://github.com/antonbabenko/deliberation
+```
+
+Kiro reads `POWER.md` (frontmatter + routing guidance), registers the MCP server
+from `mcp.json`, and loads the `steering/` files. Source:
+[kiro.dev/docs/powers/create](https://kiro.dev/docs/powers/create).
+
+## 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`) |
+
+`mcp.json` declares an empty `env: {}`; the bridges pick the keys up from the
+process environment Kiro launches the server in. You only need the providers you
+intend to call - missing keys just disable that one provider.
+
+## Activation keywords
+
+The Power loads when your task mentions any of its `keywords`:
+
+```
+architecture review, security review, second opinion, consensus,
+code review, plan review, debug, grok, openrouter, gpt, gemini, deliberation
+```
+
+Once loaded, the steering files tell Kiro when to call each tool (`ask-all`,
+`consensus`, `ask-gpt` / `ask-gemini` / `ask-grok` / `ask-openrouter`) and each
+expert persona (`architect`, `plan-reviewer`, `scope-analyst`, `code-reviewer`,
+`security-analyst`, `researcher`, `debugger`).
+
+## Submitting to the Kiro Powers registry
+
+This Power lives in a public GitHub repo, which is the only prerequisite for the
+official registry. Submit it at
+[kiro.dev/powers/submit](https://kiro.dev/powers/submit): fill in your name,
+email, a short use-case description, and the public repository URL. The Kiro team
+reviews submissions and contacts candidates about registry inclusion. The
+submission checklist requires that `POWER.md` carries License (SPDX), a Privacy
+Policy link, and a Support contact - the generated `## License and support`
+footer satisfies this.
+
+## Notes / unverified
+
+- The official docs (kiro.dev/docs/powers, /create, /powers/submit, /docs/steering)
+  confirm: `POWER.md` frontmatter fields (`name`, `displayName`, `description`,
+  `keywords`, `author`), the root-level `mcp.json` shape (no `type` field in
+  Kiro's examples), the `steering/` subdirectory, `inclusion: always` steering
+  frontmatter, the **Add power from GitHub** install flow, and the License /
+  Privacy / Support footer requirement.
+- [unverified] Whether Kiro reads per-server `env` substitution like
+  `${VAR}` inside a Power's `mcp.json` (Kiro's example shows `${SUPABASE_URL}`,
+  but deliberation reads keys straight from the process env, so we ship
+  `env: {}`). Confirm at
+  [kiro.dev/docs/powers/create](https://kiro.dev/docs/powers/create) if you want
+  to pin keys in `mcp.json` instead of the environment.
diff --git a/docs/hosts/opencode.md b/docs/hosts/opencode.md
@@ -0,0 +1,127 @@
+# 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).
diff --git a/public-docs/README.md b/public-docs/README.md
@@ -0,0 +1 @@
+This content has moved into docs/ and will be removed from public-docs/ as soon as blog posts references are updated.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		This content has moved into docs/ and will be removed from public-docs/ as soon as blog posts references are updated.