DOCSEARCHbyAlgolia
Submit Docs

Ouroboros Agent OS

repository·main·Indexed 26 days ago

https://github.com/q00/ouroboros

A specification-first workflow engine for AI coding agents that transforms non-deterministic work into replayable, observable, and policy-bound execution contracts. It features a six-phase architecture, a tiered LLM economic model, and a local-first runtime layer. Ouroboros integrates with Claude Code, Codex CLI, GitHub Copilot CLI, and other runtimes via MCP. It includes a TUI monitor (ouroboros-tui) and specialized agents for Socratic interviewing, ontology mapping, and verification.

Tokens
182.4K
Snippets
312
Records
932
Agent score
90%

What's inside ouroboros-ai

  1. Overview of Ouroboros Architecture

    main

    Ouroboros is a specification-first AI workflow engine designed to transform vague ideas into validated specifications before execution. It utilizes event sourcing and provides a rich TUI (Textual) interface for complete lifecycle management, from initial requirements to final evaluation.

    Architectural Layers

    The system is organized into several functional layers:

    1. UserLevel Programs Layer: High-level installable plugins (e.g., github-pr-ops, jira-sync, release-coordinator) and first-party programs (e.g., ooo auto, ooo run, ooo pm).
    2. Skills & Agents Registry: Manages available Skills and Agents.
    3. Core Layer: Handles the immutable Seed Spec and the Acceptance Criteria Tree.
    4. Execution Layer: Manages the 7 Execution Modes and the Model Router.
    5. State Layer: Uses a SQLite-based Event Store and a Checkpoint Store.
    6. Orchestration Layer: Manages the 6-Phase Pipeline and the PAL Router (optimized for cost).
    7. Presentation Layer: Provides the TUI Dashboard (Textual) and the CLI Interface (Typer).

  2. Understand the MCP Mesh wire format and Coordinator handshake

    main

    The MCP Mesh provides an IPC-style channel that allows various harnesses (such as Claude Code, Codex CLI, OpenCode, Gemini CLI, Hermes, and LiteLLM) to attach to a single in-process Coordinator. It uses a unified envelope shape, polling discipline, and ordering rule to facilitate communication between the Agent OS and external runtimes.

    Key Design Principles

    • Local-first cooperative trust: The Mesh operates without a daemon or SaaS, meaning there are no cross-tenant boundaries. It assumes a local environment where runtimes are trusted.
    • 4-verb filter: Every Mesh decision must specifically strengthen one of the following four capabilities: replay, explain, steer, or compose.
    • Additive-only schemas: To maintain compatibility, all envelope fields must follow the event_version rule from [#436], ensuring schemas are additive-only.

  3. Understand the Ouroboros Frugality Control Loop

    main

    Frugality in Ouroboros is designed to minimize 'waste'—tokens that do not advance a verified acceptance criterion (AC)—without reducing the achieved outcome or increasing rework risk. It operates as a control loop consisting of three main components:

    1. Spend Attribution (The Sensor): Aggregates cost/token signals with AC outcomes to identify avoidable costs like rework, dead_escalation, and stagnation.
    2. Reflective Guardrail Loop (The Learning Layer): An advisory mechanism that proposes project-scoped guardrails (stored in .ouroboros/) to adjust methodology (e.g., pruning assurance on low-risk ACs) or execution (e.g., routing to cheaper backends).
    3. User-held Assurance Dial (The Policy Input): A manual lever for the user to trade off cost vs. assurance (e.g., consensus on every AC vs. only risky ones). This is the only mechanism that allows for intentional cost/assurance trade-offs; automated guardrails are advisory only in v1.

    Core Invariants:

    • Never reduce the achieved outcome.
    • Never increase rework risk.

  4. Understand Ouroboros Runtime Capabilities

    main

    Ouroboros uses a runtime abstraction layer that allows different LLM backends (runtimes) to execute tasks. Capabilities are split into two layers:

    1. Workflow Layer: Core engine capabilities that are identical across all runtimes (e.g., Seed file parsing, Acceptance criteria tree, Evaluation principles, Event sourcing, TUI dashboard, and Dry-run validation).
    2. Runtime Layer: Backend-specific capabilities that depend on the underlying model and execution model (e.g., Authentication methods, Tool surfaces, Sandbox/permission models, and Cost models).

    For newer backends like Antigravity (agy), Grok (grok), or Zcode (zcode), refer to their specific runtime guides as they use newer runtime surfaces.

  5. Understand the Ouroboros Six-Phase Architecture

    main

    Ouroboros operates through six distinct phases to transform requirements into executable specifications:

    1. Big Bang (Phase 0): Uses Socratic and ontological questioning to crystallize requirements into a Seed (target ambiguity score $\le 0.2$).
    2. PAL Router (Phase 1): Progressive Adaptive LLM selection (Frugal $\rightarrow$ Standard $\rightarrow$ Frontier).
    3. Double Diamond (Phase 2): Recursive decomposition through Discover, Define, Design, and Deliver.
    4. Resilience (Phase 3): Detects stagnation and applies lateral thinking via persona rotation.
    5. Evaluation (Phase 4): Three-stage verification (Mechanical, Semantic, and Consensus).
    6. Secondary Loop (Phase 5): Manages the TODO registry and batch processing.

  6. Understand the ooo auto execution lifecycle

    main

    The ooo auto pipeline follows these steps:

    1. Session Start: Initiates an auto session.
    2. Socratic Interview: Runs bounded interview rounds with source-tagged answers to refine the goal.
    3. Seed Generation: Generates a Seed based on the interview.
    4. Review & Repair: Iteratively reviews and repairs the Seed until it reaches 'A-grade' status or is blocked.
    5. Execution: Starts execution only after an A-grade Seed is achieved.
    6. Product Completion (Optional): If complete_product=true is set, the pipeline chains RUN → RALPH_HANDOFF and waits for a terminal Ralph status.

    Failure Modes & Blocking: If the pipeline is blocked during the complete_product phase, the session will report a stop_reason in last_error. Common failure modes include:

    • iteration_timeout
    • wall_clock_exhausted
    • oscillation_detected
    • grade_regressing
    • max_generations reached

  7. Understand Project Identity and Authority Boundaries

    main

    In Ouroboros, project identity (comprising project_id, project_root, and workspace_path) serves strictly as an indexing and attribution contract. It is not a security mechanism.

    Key Constraints:

    • Source of Truth: The EventStore is the sole source of truth. ProjectRecord objects are reconstructed from events and are never written back as execution state.
    • No Authentication: A project_id does not authenticate a caller or authorize provider effects.
    • No Authorization: The Project Map cannot bypass the Final Gate, which remains the sole authority for acceptance.
    • Conflict Handling: Workspace filtering cannot hide identity conflicts. If top-level and nested identities conflict, the system must fail the complete project query rather than returning a partial map.

  8. Understand the Ouroboros Core Components

    main

    Ouroboros is structured into seven distinct layers that manage everything from low-level data models to high-level user workflows:

    1. Skills & Agents Registry: An in-process registry of bundled core skills (e.g., interview, seed, run, evaluate) and specialized agents. These are discovered using the /ouroboros: magic prefix.
    2. Core Layer: Contains immutable data models (like the Seed Pydantic model), Acceptance Criteria Trees, and ontology schemas.
    3. Execution Layer: Handles evolutionary execution with feedback loops, dependency-aware parallel execution, and self-referential persistence.
    4. State Layer: An event-sourcing layer using a SQLite event store for append-only writes, full replay capability, and checkpoints.
    5. Orchestration Layer: A 5-phase pipeline (Big Bang, PAL Router, Double Diamond, Resilience, and Evaluation) that ensures comprehensive execution.
    6. Presentation Layer: A Textual-based TUI dashboard providing real-time visibility into agent activity, AC tree progress, and cost tracking.
    7. UserLevel Programs Layer: High-level workflows composed via a manifest contract (e.g., ooo auto, ooo run).

  9. Understand Ouroboros Synapse SessionSignal delivery

    main

    Ouroboros Synapse is a subsystem designed to deliver bounded intent signals (SessionSignal) from a main conductor to an Active Conductor (AC) runtime attempt. It provides a way to record the lifecycle of a signal across provider boundaries, ensuring deterministic state transitions and preventing unauthorized execution jumps.

    The Signal Flow: AC runtime <── SessionSignal <── Synapse <── main conductor

    Key Concepts:

    • SessionSignal: The directed unit of communication.
    • Modes: Defines how the signal is applied (e.g., inform, after_turn, redirect, replace).
    • Sources: The priority of the signal (user > conductor > worker). A lower-priority signal cannot supersede an unapplied higher-priority signal for the same session attempt.

  10. Understand the Unified Runtime Timeout Contract

    main

    Ouroboros uses a unified timeout contract to ensure that timeout decisions (retries, blocks, cancellations, or early returns) are authoritative and durable. Instead of relying on local exceptions or state mutations, migrated timeout surfaces must emit a control.directive.emitted event via create_control_directive_emitted_event from src/ouroboros/events/control.py.

    Key concepts:

    • Authoritative Signal: The emitted event is the sole signal for timeout-driven control actions.
    • Directive Journal: Consumers should derive timeout control decisions from the directive journal rather than local implementation details.
    • emitted_by: A field used to distinguish which surface (e.g., mcp.tool_timeout, auto.interview) triggered the directive.
    • directive: The specific action taken (e.g., Directive.CANCEL, Directive.WAIT, Directive.RETRY).
    • Target Types: Decisions are mapped to canonical targets like session, execution, lineage, or agent_process.

  11. Understand the Spend Actuator controls

    main

    The Ouroboros execution engine uses two distinct, non-overlapping controls to manage resource consumption and quality:

    1. Assessment-controlled (AC) investment assessment: Acts on reasoning effort. It uses investment metadata to adjust the effort level.
    2. Trust-controlled model tier: Acts on the model tier. It uses decomposition trust to authorize the use of cheaper models for sub-tasks.

    Crucial Rule: These controls do not cross-authorize. An assessment cannot lower the model tier, and decomposition trust cannot lower the reasoning effort.

  12. Key Concepts of the Evolutionary Loop

    main

    Understanding the core mechanics of the evolve skill:

    • Wonder: The process of examining evaluation results to identify ontological gaps and hidden assumptions.
    • Reflect: Proposing specific mutations to fields, acceptance criteria, and constraints to evolve the ontology.
    • Convergence: The loop terminates when ontology similarity is ≥ 0.95 between consecutive generations, or after 30 generations.
    • evolve_step: Executes exactly one generation per call. This allows for state reconstruction between calls.
    • execute flag: When true, runs the full Execute→Evaluate pipeline. When false, skips execution to focus on fast ontology exploration.
    • QA Verdict: When execute=true, the response includes a QA score to track quality progression. Use skip_qa: true to disable this.