Ouroboros: Policy-Bound Execution and Interview-Gated Agent Evolution

The Architecture of Spec-First Agent Execution

Autonomous coding agents frequently suffer from prompt drift and specification decay when left to iteratively modify codebases. Most agent failures stem from ambiguous human inputs rather than inherent model reasoning flaws. Ouroboros addresses this challenge by functioning as an Agent OS: a local-first runtime layer that transforms non-deterministic agent work into replayable, policy-bound execution contracts.

The Ouroboros ecosystem is organized into a three-tiered architecture detailed in the Ouroboros README:

OS Kernel (Q00/ouroboros): Provides core primitives, including Seed generation, execution Ledgers, Model Context Protocol (MCP) servers, and runtime safety boundaries.
Application Layer (Ouro-labs/ouroboros-plugins): Defines user-level plugin contracts for domain-specific workflows such as pull request management, ticket triaging, and automated incident releases.
Shell (Ouro-labs/ourocode): Delivers a unified terminal user interface (TUI) cockpit that aggregates MCP state, interactive interview prompts, and tool decision flows across underlying CLI tools.

By enforcing an immutable spec before code generation begins, the OS ensures that every executed step remains auditable and reproducible across multiple model backends.

Preventing Goodhart's Law via Hidden Grading Contracts

A common vulnerability in self-improving agents is metric gaming: when an agent gains access to unit tests or validation scripts, it often tailors code specifically to bypass the evaluator rather than solving the underlying engineering problem.

To eliminate metric gaming, Ouroboros implements an interview-gated, staged evaluation loop where the evaluation harness is explicitly decoupled from the agent's context window. As noted in the project repository, the actual grading command and expected test results are never included in the success contract provided to the execution agent.

The workflow proceeds through five structured stages:

Interview: A Socratic question-and-answer cycle identifies ambiguity and surfaces hidden assumptions.
Crystallization: The system locks intent into an immutable Seed specification document.
Execution: The target runtime (e.g., Claude Code, Codex CLI) generates code constrained by the Seed.
Staged Evaluation: Automated verification pipelines evaluate output quality without exposing assertion logic to the agent.
Budgeted Evolution: The agent iteratively refines solutions within defined resource constraints and policy limits.

Research published in arXiv:2608.08311 demonstrates that long-running persistent Ouroboros deployments (such as the Hope experiment) can continuously retain memory and modify their own implementations across multiple communication surfaces while using human interaction signals as advisory input rather than direct execution commands.

Multi-Runtime Adapter Architecture

Rather than binding developers to a single model provider or interface, Ouroboros functions as an abstraction layer across 13 distinct runtime environments. According to the Ouroboros repository metadata, supported runtimes include:

Claude Code
Codex CLI
GitHub Copilot CLI
OpenCode
Hermes (Discord/chat bots)
Gemini CLI
Kiro CLI
Pi CLI
Zcode
Goose
GJC
Antigravity CLI
Grok Build CLI

For DeepSeek models, Ouroboros supports two integration vectors documented in the README. Users can either set --llm-backend dsh to drive DeepSeek Harness via its ACP server, or install the dsh-ouroboros plugin directly within DeepSeek Harness to run ouroboros_interview and ouroboros_auto tools natively within chat sessions.

Setup and Multi-Host Environment Execution

Installing Ouroboros is handled via shell script or Python package managers (pip, uv, pipx). As specified in Platform Support documentation, core packages target Python 3.12 through 3.14 (with LiteLLM features scoped to Python 3.12–3.13).

To perform a standard installation:

curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.sh | OUROBOROS_INSTALL_REF=readme bash

Alternatively, users can install isolated binaries or plugins for specific hosts:

# Isolated MCP installation via pipx
pipx install 'ouroboros-ai[mcp]'

# Claude Code plugin registration
claude plugin marketplace add Q00/ouroboros && claude plugin install ouroboros@ouroboros

# Codex plugin registration
codex plugin marketplace add Q00/ouroboros && codex plugin add ouroboros@ouroboros

After installation, initiating workspace runtime alignment requires executing:

ooo setup

Running ooo setup auto-detects installed CLI runtimes and deploys appropriate host artifacts—such as rules for Codex, skills for Hermes, or MCP definitions for Kiro and Copilot. Users can then start a specification cycle using ooo interview "Build a task management CLI".

Empirical Performance on Terminal-Bench and OSWorld

When evaluated on standardized code synthesis and agent benchmarks in arXiv:2608.08311, Ouroboros demonstrated marked accuracy improvements over default harness configurations by reducing specification drift.

On Terminal-Bench 2.1 (evaluated across 89 tasks with 5 trials):

Ouroboros with Opus 5 (Audited): 86.74% accuracy
Ouroboros with Grok 4.5 (Audited): 84.94% accuracy
Ouroboros with GPT-5.5: 84.30% accuracy
Claude Code (Fable 5 baseline): 83.80% accuracy
Codex CLI (GPT-5.5 baseline): 83.10% accuracy
Cursor (Grok 4.5 baseline): 79.30% accuracy

On OSWorld-Verified (361 tasks, single rollout execution):

Ouroboros with Opus 5: 90.69% accuracy
Intelligence-Indeed baseline: 90.19% accuracy

The empirical findings demonstrate that wrapping underlying models in a spec-bound evaluation harness systematically outperforms direct execution in standard agent CLIs.

Operational Safety Boundaries and Deployment Tradeoffs

While Ouroboros provides strong guarantees around intent preservation, operational teams must consider several system boundaries:

Isolation Boundaries: Ouroboros relies on local environment isolation. Environment configurations such as ~/.kiro/settings/mcp.json are treated as trusted setup locations, whereas project-level .env files are treated as untrusted inputs to prevent unauthorized runtime parameter injection.
Package Matrix Isolation: Dependencies between MCP 1.x (used by the Claude Agent SDK) and MCP 2.x (used by the standalone MCP server) require strict Python environment separation. Combining [mcp] and [claude] within a single Python virtual environment is explicitly prohibited to prevent dependency conflicts.
Human Alignment Requirement: Socratic interviews require human interaction to resolve ambiguity before execution. For fully autonomous unattended batch execution, pre-crystallized Seed specs must be supplied directly.