ouroboros-ai 0.27.2.dev2__tar.gz → 0.27.3.dev1__tar.gz

{ouroboros_ai-0.27.2.dev2 → ouroboros_ai-0.27.3.dev1}/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "ouroboros",
       "description": "Transform vague ideas into validated seed specifications through Socratic questioning and ontological analysis",
-      "version": "0.27.1",
+      "version": "0.27.2",
       "author": {
         "name": "Q00",
         "email": "jqyu.lee@gmail.com"

{ouroboros_ai-0.27.2.dev2 → ouroboros_ai-0.27.3.dev1}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ouroboros",
-  "version": "0.27.1",
+  "version": "0.27.2",
   "description": "Self-improving AI workflow system. Crystallize requirements before execution with Socratic interview, ambiguity scoring, and 3-stage evaluation.",
   "author": {
     "name": "Q00",

{ouroboros_ai-0.27.2.dev2 → ouroboros_ai-0.27.3.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.27.2.dev2
+Version: 0.27.3.dev1
 Summary: Specification-first workflow engine for AI coding agents. Works with Claude Code and Codex CLI.
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE

{ouroboros_ai-0.27.2.dev2 → ouroboros_ai-0.27.3.dev1}/docs/cli-reference.md

@@ -1,6 +1,6 @@
 <!--
 doc_metadata:
-  runtime_scope: [local, claude, codex]
+  runtime_scope: [local, claude, codex, opencode]
 -->
 
 # CLI Reference
@@ -56,7 +56,7 @@ ouroboros [OPTIONS] COMMAND [ARGS]...
 Detect available runtime backends and configure Ouroboros for your environment.
 
 Ouroboros supports multiple runtime backends via a pluggable `AgentRuntime` protocol. The `setup` command auto-detects
-which runtimes are available in your PATH (currently: Claude Code, Codex CLI) and
+which runtimes are available in your PATH (currently: Claude Code, Codex CLI, OpenCode) and
 configures `orchestrator.runtime_backend` accordingly. Additional runtimes can be registered
 by implementing the protocol — see [Architecture](architecture.md#how-to-add-a-new-runtime-adapter).
 
@@ -68,7 +68,7 @@ ouroboros setup [OPTIONS]
 
 | Option | Description |
 |--------|-------------|
-| `-r, --runtime TEXT` | Runtime backend to configure. Shipped values: `claude`, `codex`. Auto-detected if omitted |
+| `-r, --runtime TEXT` | Runtime backend to configure. Shipped values: `claude`, `codex`, `opencode`. Auto-detected if omitted |
 | `--non-interactive` | Skip interactive prompts (for scripted installs) |
 
 **Examples:**
@@ -97,11 +97,10 @@ ouroboros setup --non-interactive
 - For Codex CLI: installs managed Ouroboros rules into `~/.codex/rules/`
 - For Codex CLI: installs managed Ouroboros skills into `~/.codex/skills/`
 - For Codex CLI: registers the Ouroboros MCP/env block in `~/.codex/config.toml`
+- For OpenCode: registers the Ouroboros MCP server in OpenCode's configuration
 
 > **Codex config split:** put persistent Ouroboros per-role model overrides in `~/.ouroboros/config.yaml` (`clarification.default_model`, `llm.qa_model`, `evaluation.semantic_model`, `consensus.models`, `consensus.advocate_model`, `consensus.devil_model`, `consensus.judge_model`). `~/.codex/config.toml` is only the Codex MCP/env hookup file used by setup.
 
-> **`opencode` caveat:** `setup` detects the `opencode` binary in PATH but cannot configure it — if `opencode` is your only installed runtime, `setup` exits with `Error: Unsupported runtime: opencode`. The `opencode` runtime backend is **not yet implemented** (`runtime_factory.py` raises `NotImplementedError`). It is planned for a future release.
-
 ---
 
 ## `ouroboros init`
@@ -132,8 +131,8 @@ ouroboros init [start] [OPTIONS] [CONTEXT]
 | `-r, --resume TEXT` | Resume an existing interview by ID |
 | `--state-dir DIRECTORY` | Custom directory for interview state files |
 | `-o, --orchestrator` | Use Claude Code for the interview/seed flow; combine with `--runtime` to choose the workflow handoff backend |
-| `--runtime TEXT` | Agent runtime backend for the workflow execution step after seed generation. Shipped values: `claude`, `codex`. `opencode` appears in the CLI enum but is out of scope. Custom adapters registered in `runtime_factory.py` are also accepted. |
-| `--llm-backend TEXT` | LLM backend for interview, ambiguity scoring, and seed generation (`claude_code`, `litellm`, `codex`). `opencode` appears in the CLI enum but is out of scope |
+| `--runtime TEXT` | Agent runtime backend for the workflow execution step after seed generation. Shipped values: `claude`, `codex`, `opencode`. Custom adapters registered in `runtime_factory.py` are also accepted. |
+| `--llm-backend TEXT` | LLM backend for interview, ambiguity scoring, and seed generation (`claude_code`, `litellm`, `codex`, `opencode`) |
 | `-d, --debug` | Show verbose logs including debug messages |
 
 **Examples:**
@@ -209,7 +208,7 @@ ouroboros run [workflow] [OPTIONS] SEED_FILE
 | Option | Description |
 |--------|-------------|
 | `-o/-O, --orchestrator/--no-orchestrator` | Use the agent-runtime orchestrator for execution (default: enabled) |
-| `--runtime TEXT` | Agent runtime backend override (`claude`, `codex`). Uses configured default if omitted. (`opencode` is in the CLI enum but out of scope) |
+| `--runtime TEXT` | Agent runtime backend override (`claude`, `codex`, `opencode`). Uses configured default if omitted |
 | `-r, --resume TEXT` | Resume a previous orchestrator session by ID |
 | `--mcp-config PATH` | Path to MCP client configuration YAML file |
 | `--mcp-tool-prefix TEXT` | Prefix to add to all MCP tool names (e.g., `mcp_`) |
@@ -352,7 +351,7 @@ ouroboros config backend [BACKEND]
 
 | Argument | Description |
 |----------|-------------|
-| `BACKEND` | Backend to switch to: `claude` or `codex`. Omit to show current |
+| `BACKEND` | Backend to switch to: `claude` or `codex`. Omit to show current. For `opencode`, use `ouroboros setup` instead |
 
 **Examples:**
 
@@ -631,8 +630,8 @@ ouroboros mcp serve [OPTIONS]
 | `-p, --port INTEGER` | Port to bind to (default: 8080) |
 | `-t, --transport TEXT` | Transport type: `stdio` or `sse` (default: stdio) |
 | `--db TEXT` | Path to the EventStore database file |
-| `--runtime TEXT` | Runtime backend for orchestrator-driven tools (`claude`, `codex`). (`opencode` is in the CLI enum but out of scope) |
-| `--llm-backend TEXT` | LLM backend for interview/seed/evaluation tools (`claude_code`, `litellm`, `codex`). (`opencode` is in the CLI enum but out of scope) |
+| `--runtime TEXT` | Agent runtime backend for orchestrator-driven tools (`claude`, `codex`, `opencode`). Affects which tool variants are instantiated |
+| `--llm-backend TEXT` | LLM backend for interview/seed/evaluation tools (`claude_code`, `litellm`, `codex`, `opencode`). Affects which tool variants are instantiated |
 
 **Examples:**
 
@@ -689,7 +688,7 @@ If Ouroboros is installed directly (not via `uvx`), use:
 
 ```yaml
 orchestrator:
-  runtime_backend: claude   # or "codex"
+  runtime_backend: claude   # or "codex" or "opencode"
 ```
 
 Override per-session with the `OUROBOROS_AGENT_RUNTIME` environment variable if needed.
@@ -706,8 +705,8 @@ ouroboros mcp info [OPTIONS]
 
 | Option | Description |
 |--------|-------------|
-| `--runtime TEXT` | Agent runtime backend for orchestrator-driven tools (`claude`, `codex`). Affects which tool variants are instantiated |
-| `--llm-backend TEXT` | LLM backend for interview/seed/evaluation tools (`claude_code`, `litellm`, `codex`). Affects which tool variants are instantiated |
+| `--runtime TEXT` | Agent runtime backend for orchestrator-driven tools (`claude`, `codex`, `opencode`). Affects which tool variants are instantiated |
+| `--llm-backend TEXT` | LLM backend for interview/seed/evaluation tools (`claude_code`, `litellm`, `codex`, `opencode`). Affects which tool variants are instantiated |
 
 **Available Tools:**
 
@@ -722,7 +721,7 @@ ouroboros mcp info [OPTIONS]
 ## Typical Workflows
 
 > For first-time setup and the complete onboarding flow, see **[Getting Started](getting-started.md)**.
-> For runtime-specific configuration, see the [Claude Code](runtime-guides/claude-code.md) and [Codex CLI](runtime-guides/codex.md) runtime guides.
+> For runtime-specific configuration, see the [Claude Code](runtime-guides/claude-code.md), [Codex CLI](runtime-guides/codex.md), and [OpenCode](runtime-guides/opencode.md) runtime guides.
 
 ### Cancelling Stuck Executions
 
@@ -745,11 +744,12 @@ The table below covers the most commonly used variables. For the full list — i
 | `ANTHROPIC_API_KEY` | — | Anthropic API key for Claude models |
 | `OPENAI_API_KEY` | — | OpenAI API key for LiteLLM / Codex CLI |
 | `OPENROUTER_API_KEY` | — | OpenRouter API key for consensus and LiteLLM |
-| `OUROBOROS_AGENT_RUNTIME` | `orchestrator.runtime_backend` | Override the runtime backend (`claude`, `codex`) |
-| `OUROBOROS_AGENT_PERMISSION_MODE` | `orchestrator.permission_mode` | Permission mode for non-OpenCode runtimes |
+| `OUROBOROS_AGENT_RUNTIME` | `orchestrator.runtime_backend` | Override the runtime backend (`claude`, `codex`, `opencode`) |
+| `OUROBOROS_AGENT_PERMISSION_MODE` | `orchestrator.permission_mode` | Permission mode for Claude Code / Codex runtimes (no-op for OpenCode) |
 | `OUROBOROS_LLM_BACKEND` | `llm.backend` | Override the LLM-only flow backend |
 | `OUROBOROS_CLI_PATH` | `orchestrator.cli_path` | Path to the Claude CLI binary |
 | `OUROBOROS_CODEX_CLI_PATH` | `orchestrator.codex_cli_path` | Path to the Codex CLI binary |
+| `OUROBOROS_OPENCODE_CLI_PATH` | `orchestrator.opencode_cli_path` | Path to the OpenCode CLI binary |
 
 ---
 

{ouroboros_ai-0.27.2.dev2 → ouroboros_ai-0.27.3.dev1}/docs/config-reference.md

@@ -75,7 +75,7 @@ Controls how Ouroboros launches and communicates with the agent runtime backend.
 
 ```yaml
 orchestrator:
-  runtime_backend: claude       # "claude" | "codex" | "opencode" (opencode: not yet implemented)
+  runtime_backend: claude       # "claude" | "codex" | "opencode"
   permission_mode: acceptEdits  # "default" | "acceptEdits" | "bypassPermissions"
   opencode_permission_mode: bypassPermissions
   cli_path: null                # Path to Claude CLI binary; null = use SDK default
@@ -94,8 +94,6 @@ orchestrator:
 | `opencode_cli_path` | `string \| null` | `null` | Absolute path to the OpenCode CLI binary (`~` is expanded). When `null`, resolved from `PATH` at runtime. Overridable via `OUROBOROS_OPENCODE_CLI_PATH`. |
 | `default_max_turns` | `int >= 1` | `10` | Default maximum number of turns per agent execution task. |
 
-> **OpenCode scope note:** The `opencode` runtime backend is **not yet implemented** — setting `runtime_backend: opencode` will raise `NotImplementedError` at runtime. The `opencode_*` options are listed here for forward-compatibility; support is planned for a future release.
-
 ---
 
 ## `llm`

{ouroboros_ai-0.27.2.dev2 → ouroboros_ai-0.27.3.dev1}/docs/getting-started.md

@@ -35,7 +35,7 @@ That's it. `ooo interview` runs a Socratic interview that auto-generates a seed
 
 ### Alternative: Standalone CLI (`ouroboros`)
 
-Use this path if you prefer a standalone terminal workflow, or are using a non-Claude runtime (e.g., Codex CLI).
+Use this path if you prefer a standalone terminal workflow, or are using a non-Claude runtime (e.g., Codex CLI, OpenCode).
 
 **Requires Python >= 3.12.**
 
@@ -114,6 +114,7 @@ uv run ouroboros --version            # verify CLI
 | Claude Code (`ooo`) | Claude Code with plugin support |
 | Standalone CLI (`ouroboros`) | Python >= 3.12, API key (Anthropic or OpenAI) |
 | Codex CLI backend | Python >= 3.12, `npm install -g @openai/codex`, OpenAI API key with access to GPT-5.4 |
+| OpenCode backend | Python >= 3.12, `opencode` on PATH, API key for your configured provider |
 
 ---
 
@@ -137,7 +138,7 @@ export OPENAI_API_KEY="your-openai-key"
 
 ```yaml
 orchestrator:
-  runtime_backend: claude   # claude | codex
+  runtime_backend: claude   # claude | codex | opencode
 
 llm:
   backend: claude_code      # claude_code | codex | litellm
@@ -293,20 +294,21 @@ ooo run
 
 ## Choosing a Runtime Backend
 
-Ouroboros delegates code execution to a pluggable runtime backend. Two ship out of the box:
+Ouroboros delegates code execution to a pluggable runtime backend. Three ship out of the box:
 
-| | Claude Code | Codex CLI |
-|---|---|---|
-| **Best for** | Claude Code users; subscription billing | OpenAI ecosystem; pay-per-token billing |
-| **Install** | `pip install ouroboros-ai[claude]` | `pip install ouroboros-ai` + `npm install -g @openai/codex` |
-| **Skill shortcuts** | `ooo` inside Claude Code | `ooo` after `ouroboros setup --runtime codex` installs managed Codex skills |
-| **Config value** | `claude` | `codex` |
+| | Claude Code | Codex CLI | OpenCode |
+|---|---|---|---|
+| **Best for** | Claude Code users; subscription billing | OpenAI ecosystem; pay-per-token billing | Multi-provider flexibility; open-source tooling |
+| **Install** | `pip install ouroboros-ai[claude]` | `pip install ouroboros-ai` + `npm install -g @openai/codex` | `pip install ouroboros-ai` + `opencode` on PATH |
+| **Skill shortcuts** | `ooo` inside Claude Code | `ooo` after `ouroboros setup --runtime codex` installs managed Codex skills | `ooo` after `ouroboros setup --runtime opencode` |
+| **Config value** | `claude` | `codex` | `opencode` |
 
-Both backends run the same core workflow engine (seed execution, TUI). However, user-facing commands still differ: Claude Code has native in-session `ooo` workflows, while Codex CLI relies on `ouroboros setup --runtime codex` to install managed rules/skills plus the MCP hookup. The `ouroboros` CLI remains the most universal terminal path, and some advanced operations are still MCP/Claude-only.
+All three backends run the same core workflow engine (seed execution, TUI). However, user-facing commands still differ: Claude Code has native in-session `ooo` workflows, while Codex CLI and OpenCode rely on `ouroboros setup --runtime <backend>` to configure the integration. The `ouroboros` CLI remains the most universal terminal path, and some advanced operations are still MCP/Claude-only.
 
 For backend-specific configuration:
 - [Claude Code runtime guide](runtime-guides/claude-code.md)
 - [Codex CLI runtime guide](runtime-guides/codex.md)
+- [OpenCode runtime guide](runtime-guides/opencode.md)
 
 ---
 
@@ -405,5 +407,6 @@ ouroboros cancel execution <session_id>
 - [Configuration Reference](config-reference.md) -- all config keys and defaults
 - [Claude Code runtime guide](runtime-guides/claude-code.md) -- backend-specific setup
 - [Codex CLI runtime guide](runtime-guides/codex.md) -- backend-specific setup
+- [OpenCode runtime guide](runtime-guides/opencode.md) -- backend-specific setup
 
 Need help? Open an issue on [GitHub](https://github.com/Q00/ouroboros/issues).

{ouroboros_ai-0.27.2.dev2 → ouroboros_ai-0.27.3.dev1}/docs/runtime-capability-matrix.md

@@ -13,7 +13,7 @@ The runtime backend is selected via the `orchestrator.runtime_backend` config ke
 
 ```yaml
 orchestrator:
-  runtime_backend: claude   # Supported values: claude | codex
+  runtime_backend: claude   # Supported values: claude | codex | opencode
                             # The runtime abstraction layer also accepts custom
                             # adapters registered in runtime_factory.py
 ```
@@ -26,7 +26,7 @@ ouroboros run workflow --runtime codex seed.yaml
 
 You can also override the configured backend with the `OUROBOROS_AGENT_RUNTIME` environment variable.
 
-> **Extensibility:** Ouroboros uses a pluggable `AgentRuntime` protocol. Claude Code and Codex CLI are the two shipped backends; additional runtimes can be registered by implementing the protocol and extending `runtime_factory.py`. See [Architecture — How to add a new runtime adapter](architecture.md#how-to-add-a-new-runtime-adapter).
+> **Extensibility:** Ouroboros uses a pluggable `AgentRuntime` protocol. Claude Code, Codex CLI, and OpenCode are the three shipped backends; additional runtimes can be registered by implementing the protocol and extending `runtime_factory.py`. See [Architecture — How to add a new runtime adapter](architecture.md#how-to-add-a-new-runtime-adapter).
 
 ## Capability Matrix
 
@@ -34,39 +34,39 @@ You can also override the configured backend with the `OUROBOROS_AGENT_RUNTIME`
 
 These capabilities are part of the Ouroboros core engine and work the same way regardless of runtime backend.
 
-| Capability | Claude Code | Codex CLI | Notes |
-|------------|:-----------:|:---------:|-------|
-| Seed file parsing | Yes | Yes | Same YAML schema, same validation |
-| Acceptance criteria tree | Yes | Yes | Structured AC decomposition |
-| Evaluation principles | Yes | Yes | Weighted scoring against principles |
-| Exit conditions | Yes | Yes | Deterministic termination logic |
-| Event sourcing (SQLite) | Yes | Yes | Full event log, replay support |
-| Checkpoint / resume | Yes | Yes | `--resume <session_id>` |
-| TUI dashboard | Yes | Yes | Textual-based progress view |
-| Interview (Socratic seed creation) | Yes | Yes | `ouroboros init start ...` with the appropriate LLM backend |
-| Dry-run validation | Yes | Yes | `--dry-run` validates without executing |
+| Capability | Claude Code | Codex CLI | OpenCode | Notes |
+|------------|:-----------:|:---------:|:--------:|-------|
+| Seed file parsing | Yes | Yes | Yes | Same YAML schema, same validation |
+| Acceptance criteria tree | Yes | Yes | Yes | Structured AC decomposition |
+| Evaluation principles | Yes | Yes | Yes | Weighted scoring against principles |
+| Exit conditions | Yes | Yes | Yes | Deterministic termination logic |
+| Event sourcing (SQLite) | Yes | Yes | Yes | Full event log, replay support |
+| Checkpoint / resume | Yes | Yes | Yes | `--resume <session_id>` |
+| TUI dashboard | Yes | Yes | Yes | Textual-based progress view |
+| Interview (Socratic seed creation) | Yes | Yes | Yes | `ouroboros init start ...` with the appropriate LLM backend |
+| Dry-run validation | Yes | Yes | Yes | `--dry-run` validates without executing |
 
 ### Runtime Layer (differs by backend)
 
 These capabilities depend on the runtime backend's native features and execution model.
 
-| Capability | Claude Code | Codex CLI | Notes |
-|------------|:-----------:|:---------:|-------|
-| **Authentication** | Max Plan subscription | OpenAI API key | No API key needed for Claude Code |
-| **Underlying model** | Claude (Anthropic) | GPT-5.4+ (OpenAI) | Model choice follows the runtime |
-| **Tool surface** | Read, Write, Edit, Bash, Glob, Grep | Codex-native tool set | Different tool implementations; same task outcomes |
-| **Sandbox / permissions** | Claude Code permission system | Codex sandbox model | Each runtime manages its own safety boundaries |
-| **Cost model** | Included in Max Plan | Per-token API charges | See [OpenAI pricing](https://openai.com/pricing) for Codex costs |
+| Capability | Claude Code | Codex CLI | OpenCode | Notes |
+|------------|:-----------:|:---------:|:--------:|-------|
+| **Authentication** | Max Plan subscription | OpenAI API key | Provider API keys (configured in OpenCode) | No API key needed for Claude Code |
+| **Underlying model** | Claude (Anthropic) | GPT-5.4+ (OpenAI) | Provider-dependent (OpenCode supports multiple providers) | Model choice follows the runtime |
+| **Tool surface** | Read, Write, Edit, Bash, Glob, Grep | Codex-native tool set | Read, Write, Edit, Bash, Glob, Grep | Different tool implementations; same task outcomes |
+| **Sandbox / permissions** | Claude Code permission system | Codex sandbox model | OpenCode permission system | Each runtime manages its own safety boundaries |
+| **Cost model** | Included in Max Plan | Per-token API charges | Depends on configured provider | See [OpenAI pricing](https://openai.com/pricing) for Codex costs |
 
 ### Integration Surface (UX differences)
 
-| Aspect | Claude Code | Codex CLI |
-|--------|-------------|-----------|
-| **Primary UX** | In-session skills and MCP server | Session-oriented Ouroboros runtime over Codex CLI transport |
-| **Skill shortcuts (`ooo`)** | Yes -- skills loaded into Claude Code session | Yes -- after `ouroboros setup --runtime codex` installs managed skills into `~/.codex/skills/`, rules into `~/.codex/rules/`, and the MCP/env hookup into `~/.codex/config.toml`. Keep role-specific Ouroboros model overrides in `~/.ouroboros/config.yaml` |
-| **MCP integration** | Native MCP server support | Deterministic skill/MCP dispatch through the Ouroboros Codex adapter |
-| **Session context** | Shares Claude Code session context | Preserved via runtime handles, native session IDs, and resume support |
-| **Install extras** | `ouroboros-ai[claude]` | `ouroboros-ai` (base package) + `codex` on PATH |
+| Aspect | Claude Code | Codex CLI | OpenCode |
+|--------|-------------|-----------|----------|
+| **Primary UX** | In-session skills and MCP server | Session-oriented Ouroboros runtime over Codex CLI transport | MCP server integration |
+| **Skill shortcuts (`ooo`)** | Yes -- skills loaded into Claude Code session | Yes -- after `ouroboros setup --runtime codex` installs managed skills into `~/.codex/skills/`, rules into `~/.codex/rules/`, and the MCP/env hookup into `~/.codex/config.toml`. Keep role-specific Ouroboros model overrides in `~/.ouroboros/config.yaml` | Yes -- after `ouroboros setup --runtime opencode` |
+| **MCP integration** | Native MCP server support | Deterministic skill/MCP dispatch through the Ouroboros Codex adapter | Native MCP server support |
+| **Session context** | Shares Claude Code session context | Preserved via runtime handles, native session IDs, and resume support | Session IDs + resume via `--session` |
+| **Install extras** | `ouroboros-ai[claude]` | `ouroboros-ai` (base package) + `codex` on PATH | `ouroboros-ai` (base package) + `opencode` on PATH |
 
 ## What Stays the Same
 
@@ -97,15 +97,18 @@ The table below covers the two currently shipped backends. Because Ouroboros use
 |-----------|----------|
 | Have a Claude Code Max Plan and want zero API key setup | Claude Code (`runtime_backend: claude`) |
 | Want a Codex-backed Ouroboros session instead of a Claude Code session | Codex CLI (`runtime_backend: codex`) |
+| Want to use OpenCode with multiple model providers | OpenCode (`runtime_backend: opencode`) |
 | Want to use Anthropic's Claude models | Claude Code |
 | Want to use OpenAI's GPT models | Codex CLI |
-| Need MCP server integration | Claude Code |
-| Want minimal Python dependencies | Codex CLI (base package only) |
+| Want to use multiple providers via a single runtime | OpenCode |
+| Need MCP server integration | Claude Code or OpenCode |
+| Want minimal Python dependencies | Codex CLI or OpenCode (base package only) |
 | Want to integrate a custom or third-party AI coding agent | Implement the `AgentRuntime` protocol and register it in `runtime_factory.py` |
 
 ## Further Reading
 
 - [Claude Code runtime guide](runtime-guides/claude-code.md)
 - [Codex CLI runtime guide](runtime-guides/codex.md)
+- [OpenCode runtime guide](runtime-guides/opencode.md)
 - [Platform support matrix](platform-support.md) (OS and Python version compatibility)
 - [Architecture overview](architecture.md) — including [How to add a new runtime adapter](architecture.md#how-to-add-a-new-runtime-adapter)

ouroboros_ai-0.27.3.dev1/docs/runtime-guides/opencode.md

@@ -0,0 +1,165 @@
+<!--
+doc_metadata:
+  runtime_scope: [opencode]
+-->
+
+# Running Ouroboros with OpenCode
+
+> For installation and first-run onboarding, see [Getting Started](../getting-started.md).
+
+Ouroboros can use **OpenCode** as a runtime backend. [OpenCode](https://opencode.ai) is an open-source AI coding agent that supports multiple model providers (Anthropic, OpenAI, Google, and others). In Ouroboros, the OpenCode backend is presented as a **session-oriented runtime** with the same specification-first workflow harness (acceptance criteria, evaluation principles, deterministic exit conditions).
+
+No additional Python SDK is required beyond the base `ouroboros-ai` package.
+
+## Prerequisites
+
+- **OpenCode** installed and on your `PATH` (see [install steps](#installing-opencode) below)
+- An **API key** for your configured provider (e.g., `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`)
+- **Python >= 3.12**
+
+## Installing OpenCode
+
+OpenCode is distributed as a standalone binary. Install via the official script:
+
+```bash
+curl -fsSL https://opencode.ai/install | bash
+```
+
+Verify the installation:
+
+```bash
+opencode --version
+```
+
+For alternative install methods, see the [OpenCode documentation](https://opencode.ai/docs).
+
+## Configuration
+
+To select OpenCode as the runtime backend, set the following in your Ouroboros configuration:
+
+```yaml
+orchestrator:
+  runtime_backend: opencode
+```
+
+Or pass the backend on the command line:
+
+```bash
+uv run ouroboros run workflow --runtime opencode ~/.ouroboros/seeds/seed_abcd1234ef56.yaml
+```
+
+### Setup
+
+Run the setup command to auto-configure:
+
+```bash
+ouroboros setup --runtime opencode
+```
+
+This:
+
+- Detects the `opencode` binary on your `PATH`
+- Writes `orchestrator.runtime_backend: opencode` to `~/.ouroboros/config.yaml`
+- Registers the Ouroboros MCP server in OpenCode's configuration
+
+## How It Works
+
+```
++-----------------+     +------------------+     +-----------------+
+|   Seed YAML     | --> |   Orchestrator   | --> |    OpenCode     |
+|  (your task)    |     | (runtime_factory)|     |   (runtime)     |
++-----------------+     +------------------+     +-----------------+
+                                |
+                                v
+                        +------------------+
+                        |  Tools Available |
+                        |  - Read          |
+                        |  - Write         |
+                        |  - Edit          |
+                        |  - Bash          |
+                        |  - Glob          |
+                        |  - Grep          |
+                        +------------------+
+```
+
+The `OpenCodeRuntime` adapter launches `opencode run --format json` as a subprocess for each task execution. The orchestrator pipes the prompt via stdin and parses the structured JSON event stream from stdout.
+
+> For a side-by-side comparison of all runtime backends, see the [runtime capability matrix](../runtime-capability-matrix.md).
+
+## OpenCode-Specific Strengths
+
+- **Multi-provider support** -- use Anthropic, OpenAI, Google, or other providers through a single runtime
+- **Rich tool access** -- full suite of file, shell, and search tools (same surface as Claude Code)
+- **Native MCP integration** -- OpenCode has built-in MCP server support
+- **Open-source** -- fully open-source, allowing inspection and contribution
+
+## CLI Options
+
+### Workflow Commands
+
+```bash
+# Execute workflow (OpenCode runtime)
+uv run ouroboros run workflow --runtime opencode ~/.ouroboros/seeds/seed_abcd1234ef56.yaml
+
+# Debug output (show logs and agent output)
+uv run ouroboros run workflow --runtime opencode --debug ~/.ouroboros/seeds/seed_abcd1234ef56.yaml
+
+# Resume a previous session
+uv run ouroboros run workflow --runtime opencode --resume <session_id> ~/.ouroboros/seeds/seed_abcd1234ef56.yaml
+```
+
+## Known Limitations
+
+### Session pollution
+
+Each task execution via `opencode run` creates a visible session in OpenCode's session history. Long-running workflows with many orchestrator steps will accumulate sessions. A future phase will reparent these sessions under the caller to prevent polluting the session picker (see GitHub #164 Phase 2).
+
+### No interactive mode
+
+The adapter uses `opencode run --format json` (non-interactive). Features that require interactive OpenCode sessions (e.g., manual approval prompts) are not available during Ouroboros execution.
+
+## Troubleshooting
+
+### OpenCode not found
+
+Ensure `opencode` is installed and available on your `PATH`:
+
+```bash
+which opencode
+```
+
+If not installed:
+
+```bash
+curl -fsSL https://opencode.ai/install | bash
+```
+
+### API key errors
+
+Verify your provider API key is set:
+
+```bash
+# For Anthropic
+echo $ANTHROPIC_API_KEY
+
+# For OpenAI
+echo $OPENAI_API_KEY
+```
+
+### "Providers: warning" in health check
+
+This is normal when using the orchestrator runtime backends. The warning refers to LiteLLM providers, which are not used in orchestrator mode.
+
+### "EventStore not initialized"
+
+The database will be created automatically at `~/.ouroboros/ouroboros.db`.
+
+## Cost
+
+Using OpenCode as the runtime backend incurs API charges from your configured provider. Costs depend on:
+
+- Provider and model selected in OpenCode configuration
+- Task complexity and token usage
+- Number of tool calls and iterations
+
+Refer to your provider's pricing page for current rates.

{ouroboros_ai-0.27.2.dev2 → ouroboros_ai-0.27.3.dev1}/skills/setup/SKILL.md

@@ -246,7 +246,7 @@ A backup will be created: CLAUDE.md.bak
 **If "Preview first", show:**
 ````markdown
 <!-- ooo:START -->
-<!-- ooo:VERSION:0.27.1 -->
+<!-- ooo:VERSION:0.27.2 -->
 # Ouroboros — Specification-First AI Development
 
 > Before telling AI what to build, define what should be built.

{ouroboros_ai-0.27.2.dev2 → ouroboros_ai-0.27.3.dev1}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.27.2.dev2'
-__version_tuple__ = version_tuple = (0, 27, 2, 'dev2')
+__version__ = version = '0.27.3.dev1'
+__version_tuple__ = version_tuple = (0, 27, 3, 'dev1')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.27.2.dev2 → ouroboros_ai-0.27.3.dev1}/src/ouroboros/cli/commands/init.py

@@ -50,6 +50,7 @@ class AgentRuntimeBackend(str, Enum):  # noqa: UP042
 
     CLAUDE = "claude"
     CODEX = "codex"
+    OPENCODE = "opencode"
 
 
 class LLMBackend(str, Enum):  # noqa: UP042
@@ -58,6 +59,7 @@ class LLMBackend(str, Enum):  # noqa: UP042
     CLAUDE_CODE = "claude_code"
     LITELLM = "litellm"
     CODEX = "codex"
+    OPENCODE = "opencode"
 
 
 class _DefaultStartGroup(typer.core.TyperGroup):
@@ -669,7 +671,7 @@ def start(
             "--runtime",
             help=(
                 "Agent runtime backend for the workflow execution step after seed generation "
-                "(claude or codex)."
+                "(claude, codex, or opencode)."
             ),
             case_sensitive=False,
         ),
@@ -680,7 +682,7 @@ def start(
             "--llm-backend",
             help=(
                 "LLM backend for interview, ambiguity scoring, and seed generation "
-                "(claude_code, litellm, or codex)."
+                "(claude_code, litellm, codex, or opencode)."
             ),
             case_sensitive=False,
         ),

{ouroboros_ai-0.27.2.dev2 → ouroboros_ai-0.27.3.dev1}/src/ouroboros/cli/commands/mcp.py

@@ -29,6 +29,7 @@ class AgentRuntimeBackend(str, Enum):  # noqa: UP042
 
     CLAUDE = "claude"
     CODEX = "codex"
+    OPENCODE = "opencode"
 
 
 class LLMBackend(str, Enum):  # noqa: UP042
@@ -37,6 +38,7 @@ class LLMBackend(str, Enum):  # noqa: UP042
     CLAUDE_CODE = "claude_code"
     LITELLM = "litellm"
     CODEX = "codex"
+    OPENCODE = "opencode"
 
 
 def _write_pid_file() -> bool:
@@ -262,7 +264,7 @@ def serve(
         AgentRuntimeBackend | None,
         typer.Option(
             "--runtime",
-            help="Agent runtime backend for orchestrator-driven tools (claude or codex).",
+            help="Agent runtime backend for orchestrator-driven tools (claude, codex, or opencode).",
             case_sensitive=False,
         ),
     ] = None,
@@ -271,7 +273,7 @@ def serve(
         typer.Option(
             "--llm-backend",
             help=(
-                "LLM backend for interview/seed/evaluation tools (claude_code, litellm, or codex)."
+                "LLM backend for interview/seed/evaluation tools (claude_code, litellm, codex, or opencode)."
             ),
             case_sensitive=False,
         ),
@@ -296,8 +298,8 @@ def serve(
         # Start with SSE transport on custom port
         ouroboros mcp serve --transport sse --port 9000
 
-        # Start with Codex runtime for orchestrator-driven tools
-        ouroboros mcp serve --runtime codex
+        # Start with OpenCode runtime
+        ouroboros mcp serve --runtime opencode
 
         # Use Codex CLI for LLM-only tools as well
         ouroboros mcp serve --runtime codex --llm-backend codex
@@ -349,7 +351,7 @@ def info(
         AgentRuntimeBackend | None,
         typer.Option(
             "--runtime",
-            help="Agent runtime backend for orchestrator-driven tools (claude or codex).",
+            help="Agent runtime backend for orchestrator-driven tools (claude, codex, or opencode).",
             case_sensitive=False,
         ),
     ] = None,
@@ -358,7 +360,7 @@ def info(
         typer.Option(
             "--llm-backend",
             help=(
-                "LLM backend for interview/seed/evaluation tools (claude_code, litellm, or codex)."
+                "LLM backend for interview/seed/evaluation tools (claude_code, litellm, codex, or opencode)."
             ),
             case_sensitive=False,
         ),

{ouroboros_ai-0.27.2.dev2 → ouroboros_ai-0.27.3.dev1}/src/ouroboros/cli/commands/run.py

@@ -59,6 +59,7 @@ class AgentRuntimeBackend(str, Enum):  # noqa: UP042
 
     CLAUDE = "claude"
     CODEX = "codex"
+    OPENCODE = "opencode"
 
 
 def _derive_quality_bar(seed: "Seed") -> str:
@@ -418,7 +419,7 @@ def workflow(
         AgentRuntimeBackend | None,
         typer.Option(
             "--runtime",
-            help="Agent runtime backend for orchestrator mode (claude or codex).",
+            help="Agent runtime backend for orchestrator mode (claude, codex, or opencode).",
             case_sensitive=False,
         ),
     ] = None,