# Ouroboros

> Pins an acceptance spec and omits any verify command or expected output from the worker's contract

Ouroboros transforms vague ideas into verified, working codebases by replacing ad-hoc prompting with a structured workflow: interview, crystallize, execute, evaluate, evolve. It sits between the user and their AI runtime (Claude Code, Codex CLI, or others).

Note: this is `github.com/Q00/ouroboros`. A separate, unaffiliated open-source
project also named "Ouroboros" (`github.com/razzant/ouroboros`, by Anton
Razzhigaev) is a self-modifying, autonomous-memory agent that rewrites its own
architecture -- a different project with a different design, no shared code.

## Core Concepts

- Seed Spec: An immutable YAML specification generated from interview results or already-agreed requirements. Contains project description, acceptance criteria (AC) tree, constraints, and architecture decisions. The seed is the single source of truth for what should be built. In the host-skill flow, confirm the agreed goal, request `ooo seed`, and inspect the returned YAML before execution; interview completion alone does not establish that a Seed exists. The standalone CLI and Auto have separate generation flows. See `skills/seed/SKILL.md`; manual YAML authoring is an advanced workflow (see `docs/guides/seed-authoring.md`).
- Acceptance Criteria (AC) Tree: A hierarchical decomposition of requirements. Each AC has a status (pending, in_progress, passed, failed) and can contain children. The tree is the unit of progress tracking.
- Interview: A Socratic dialogue that extracts hidden assumptions and clarifies requirements. After its closure checks and user confirmation of the agreed goal, the host Interview skill suggests `ooo seed`; this does not itself produce a Seed artifact.
- Evaluation Pipeline: Three-stage verification (mechanical checks, LLM-based review, consensus gating) that determines whether acceptance criteria are met.
- Event Sourcing: All state changes are persisted as immutable events in a SQLite EventStore (~/.ouroboros/ouroboros.db). The system can reconstruct any past state from events.
- Evolution Loop: After evaluation, the system can evolve the spec and re-execute, creating an iterative refinement cycle.
- Drift Detection: Monitors whether execution is diverging from the original seed spec intent.
- Lineage: Tracks the causal chain of events and decisions through the workflow.

## Architecture Layers

- Plugin Layer: Skills (Claude Code slash commands via `ooo`) and agents that interface with the user. Skills map to `skills/*/SKILL.md`.
- Core Layer: Seed spec management, AC tree lifecycle, event sourcing, lineage tracking. Located in `src/ouroboros/core/`.
- Orchestrator: Coordinates execution strategy, manages level context, routes tasks to appropriate backends. Located in `src/ouroboros/orchestrator/`.
- Evaluation: Three-stage pipeline (mechanical, LLM, consensus), artifact collection, language-specific checks. Located in `src/ouroboros/evaluation/`.
- Execution: Subagent management for parallel AC execution. Located in `src/ouroboros/execution/`.
- Routing: PAL router — picks a model tier per unit of work and escalates it on retry (no complexity scoring, no downgrade). Located in `src/ouroboros/orchestrator/model_routing.py` and `src/ouroboros/orchestrator/route_escalation.py`.
- Persistence: SQLAlchemy-based event store with migration support. Located in `src/ouroboros/persistence/`.
- Presentation: Textual TUI (dashboard, execution, logs, debug, lineage screens) and Typer CLI. Located in `src/ouroboros/tui/` and `src/ouroboros/cli/`.
- MCP: Model Context Protocol server/client for tool integration. Located in `src/ouroboros/mcp/`.
- Observability: Drift detection and retrospective analysis. Located in `src/ouroboros/observability/`.
- Resilience: Retry and recovery strategies. Located in `src/ouroboros/resilience/`.

## Two CLI Paths

- `ooo` (Claude Code): Skills invoked inside a Claude Code session. Primary recommended path. Invoke setup explicitly with `/ouroboros:setup`; other commands include `ooo interview "idea"`, `ooo run`, `ooo evaluate`, `ooo evolve`, `ooo status`, `ooo unstuck`, `ooo cancel`.
- `ouroboros` (Typer CLI): Standalone CLI installed via `pip install ouroboros-ai`. Fallback path. Subcommands: `ouroboros interview`, `ouroboros run`, `ouroboros config`, `ouroboros status`, `ouroboros cancel`, `ouroboros setup`, `ouroboros tui`, `ouroboros mcp`.

## Commands / Skills

- setup: Guided onboarding wizard. Configures runtime backend and project settings.
- interview (aliases: socratic): Clarify vague requirements through Socratic questioning. After closure checks and goal confirmation, the host skill suggests `ooo seed`.
- seed (aliases: crystallize): Generate a Seed from interview results or already-agreed context. Request `ooo seed` in the host-skill flow and inspect the returned YAML. Calling the skill is distinct from manually authoring YAML, which is an advanced workflow.
- ouroboros-run (invoked as `ooo run`, alias: execute): Execute a seed specification through the workflow engine. Decomposes ACs into tasks and runs them via the configured backend.
- evaluate (aliases: eval): Three-stage verification pipeline. Runs mechanical checks, LLM review, and consensus gating against acceptance criteria.
- evolve: Start or monitor an evolutionary development loop. Iterates on evaluation findings.
- ouroboros-status (invoked as `ooo status`, alias: drift): Check session status and measure goal drift against the seed spec.
- unstuck (aliases: stuck, lateral): Break through stagnation with lateral thinking personas.
- cancel (aliases: kill, abort): Cancel stuck or orphaned executions.
- ouroboros-config (invoked as `ooo config`): Open the Ouroboros settings UI.
- ouroboros-help (invoked as `ooo help`): Show available commands and usage.
- welcome: First-run welcome message and orientation.
- tutorial: Interactive tutorial walkthrough.

## Key File Structure

```
ouroboros/
  skills/             # Skill implementations (*/SKILL.md)
  src/ouroboros/
    cli/              # Typer CLI entry point and command groups
      main.py         # App definition, registers: init, run, config, status, cancel, mcp, setup, tui
      commands/       # CLI command implementations
      formatters/     # Rich console output (tables, panels, progress)
    core/             # Seed spec, lineage, file locking, text utilities
    orchestrator/     # Execution strategy, level context, MCP config
    evaluation/       # Pipeline, trigger, models, artifact collector, mechanical checks
    execution/        # Subagent management
    events/           # Event definitions (decomposition, evaluation, interview, ontology, lineage)
    persistence/      # SQLAlchemy event store, migrations
    routing/          # Complexity analysis, router, escalation, downgrade
    tui/              # Textual TUI application
      screens/        # Dashboard v2/v3, execution, logs, debug, lineage, confirm-rewind
      widgets/        # AC tree, cost tracker, phase progress, drift meter, parallel graph
      components/     # Event log, progress, token tracker, agents panel
    mcp/              # Model Context Protocol integration
      server/         # MCP server with security
      client/         # MCP client manager, protocol, adapter
      tools/          # Tool registry, dashboard tools
      resources/      # Resource handlers
    observability/    # Drift detection, retrospective
    resilience/       # Retry and recovery
    config/           # Configuration models
    agents/           # Agent prompt package (src/ouroboros/agents)
    plugin/           # Plugin system (skills, agents, orchestration)
    providers/        # Runtime backend providers
    evolution/        # Regression detection, projector
    verification/     # Verifier models
    strategies/       # Execution strategies
    bigbang/          # Project bootstrapping
    codex/            # Codex CLI integration
  docs/
    getting-started.md        # Single onboarding source of truth
    architecture.md           # System design and component overview
    config-reference.md       # Configuration keys and defaults
    platform-support.md       # Supported platforms and runtimes
    runtime-capability-matrix.md  # Feature comparison across backends
    guides/                   # User guides (seed authoring, TUI, evaluation)
    runtime-guides/           # Backend-specific configuration (claude-code, codex)
    api/                      # API reference (core, MCP)
    contributing/             # Contributor guides (architecture, testing, patterns)
  tests/              # Test suite
  examples/           # Example projects
  pyproject.toml      # Package metadata: ouroboros-ai, requires Python >=3.12
```

## Runtime Backends

Ouroboros supports multiple AI runtime backends configured via `orchestrator.runtime_backend`:
- Claude Code: Primary recommended backend. Uses Claude Code sessions with MCP tool integration.
- Codex CLI: OpenAI Codex CLI as an alternative backend.
- Additional backends can be integrated via the provider system.

## Event Model

All workflow state is event-sourced. Key event categories:
- Decomposition events: AC tree creation and updates
- Evaluation events: Stage results, consensus outcomes
- Interview events: Question-answer pairs, crystallization
- Ontology events: Concept and relationship tracking
- Lineage events: Causal chain tracking

## Documentation

- Onboarding: `docs/getting-started.md`
- Architecture: `docs/architecture.md`
- API Reference: `docs/api/core.md`, `docs/api/mcp.md`
- Runtime Guides: `docs/runtime-guides/claude-code.md`, `docs/runtime-guides/codex.md`
- Contributing: `docs/contributing/`
