llms.txt · git:20261113.3310935 · 2026-11-13 · sha256 e11f0920336377a2

llms.txt git:20261113.3310935A

Immutable. This exact content never changes and is served at /api/v1/blob/e11f0920336377a2.

# 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`. Every skill is listed under Commands / Skills below.
- `ouroboros` (Typer CLI): Standalone CLI installed via `pip install ouroboros-ai`. Fallback path. Subcommands: see CLI Commands below.

## CLI Commands

Every top-level command `ouroboros --help` lists; `ouroboros <command> --help` shows its options. Rendered from the CLI registry by `scripts/gen-llms-catalog.py`.

<!-- generated:cli-commands begin -->
- `ouroboros artifacts`: Fetch, replay, and conservatively prune Disposable Memory artifacts.
- `ouroboros auto`: Run bounded full-quality ooo auto pipeline.
- `ouroboros cancel`: Cancel stuck or orphaned executions.
- `ouroboros cleanup`: Prune leftover auto-session worktrees, branches, locks, and state files.
- `ouroboros codex`: Manage Ouroboros Codex CLI integration artifacts.
- `ouroboros config`: Manage Ouroboros configuration.
- `ouroboros detect`: Generate .ouroboros/mechanical.toml via one AI call.
- `ouroboros doctor`: Run read-only diagnostics for Ouroboros installations.
- `ouroboros harness`: Inspect A2 interview traces (list/show/trace/diff/frontier).
- `ouroboros init`: Start interactive interview to refine requirements.
- `ouroboros interview`: Alias of `ouroboros init`.
- `ouroboros job`: Inspect background Ouroboros jobs.
- `ouroboros mcp`: MCP (Model Context Protocol) server commands.
- `ouroboros plugin`: Manage UserLevel plugins (#725).
- `ouroboros pm`: Generate a Product Requirements Document through guided interview.
- `ouroboros qa`: General-purpose QA verdict for any artifact.
- `ouroboros resume`: List in-flight sessions and re-attach after MCP disconnect.
- `ouroboros run`: Execute Ouroboros workflows.
- `ouroboros seed`: Generate a Seed YAML specification from an interview.
- `ouroboros setup`: Set up Ouroboros for your environment.
- `ouroboros status`: Check Ouroboros system status.
- `ouroboros tui`: Interactive TUI monitor for Ouroboros workflows.
- `ouroboros uninstall`: Cleanly remove Ouroboros from your system.
- `ouroboros update`: Update Ouroboros to the latest version.
- `ouroboros workflow-ir`: Inspect read-only Workflow IR projections.
- `ouroboros zcode`: Convenience commands that use Zcode automatically.
<!-- generated:cli-commands end -->

## Commands / Skills

A skill runs as `ooo <name>` (or `/ouroboros:<name>`), and an alias works the same way; a skill marked "invoke as `/ouroboros:<name>`" runs only when that command is typed explicitly. Rendered from `skills/*/SKILL.md` by `scripts/gen-llms-catalog.py`.

<!-- generated:skills begin -->
- `auto`: Use when the work spans several files or replaces a framework, language, auth, storage, or API layer (rewrites and migrations included), and the user wants it to end up working and tested. Asks only what is missing, writes a spec with acceptance criteria, then runs and verifies it in the background. Not for questions, small edits, or an existing Seed (use run).
- `brownfield`: Scan and manage brownfield repository/worktree defaults for interviews
- `cancel` (aliases: `kill`, `abort`): Cancel stuck or orphaned executions
- `config` (aliases: `ouroboros-config`): Open or drive the Ouroboros settings GUI (browser, TUI, or conversational fallback)
- `evaluate` (aliases: `eval`): Use when the user wants proof that finished work meets its acceptance criteria, not just that tests pass: 'verify it is actually done', 'check it against the spec', 'evaluate the run'. Runs mechanical checks, a semantic review per criterion, and multi-model consensus when uncertain. With execution.auto_evolve on (the default), a rejected result with a Seed continues into a Ralph fix loop; pass auto_evolve: false to verify only.
- `evolve`: Start or monitor an evolutionary development loop
- `help` (aliases: `ouroboros-help`): Ouroboros command reference and troubleshooting guidance for installation, MCP, status, and recovery
- `idk` (aliases: `dont-know`, `calibrate`): Calibrate interview explanations from the user's stated understanding
- `interview` (aliases: `socratic`): Use when the user wants to build or change something but the request is vague or open-ended: 'help me figure out what to build', 'I'm not sure what it should do', 'add X' with no details, or no clear definition of done. Runs a short Socratic interview that turns the idea into goals, constraints, and acceptance criteria before any code is written. Not for simple questions, small clear edits, or an existing Seed.
- `ooo`: Start Ouroboros onboarding. Use when the user sends bare `ooo`, asks to start Ouroboros, or is using Ouroboros for the first time.
- `pm`: Use when the user wants product requirements rather than code: 'write a PRD', 'product requirements', 'spec this feature for the team', 'ooo pm'. Runs a PM-focused interview with automatic question classification and produces a PRD/PM document. Not for implementation requests.
- `publish`: Publish Seed specification as GitHub Issues for team-based project management
- `qa`: General-purpose QA verdict for any artifact type
- `ralph`: MCP-owned Ralph loop around background evolve_step jobs
- `resume-session`: List in-flight Ouroboros sessions and show the commands needed to re-attach after MCP disconnect
- `run` (aliases: `ouroboros-run`, `execute`): Use when an Ouroboros Seed (a spec file with a goal and acceptance criteria, such as *.seed.yaml) already exists and the user wants it executed: 'run the seed', 'execute this spec', 'ooo run'. Executes it and verifies every acceptance criterion. Not for raw requests without a Seed (use interview or auto).
- `seed` (aliases: `crystallize`): Use when goal, constraints, and success criteria are already settled and the user wants them frozen into a formal spec an agent can execute and verify: 'turn this into a spec', 'write it up as a Seed', or right after an interview. Returns an immutable Seed with acceptance criteria. Not for vague requests (use interview first).
- `setup` (invoke as `/ouroboros:setup`): Guided onboarding wizard for Ouroboros setup
- `status` (aliases: `ouroboros-status`, `drift`): Check session status and measure goal drift
- `tutorial` (invoke as `/ouroboros:tutorial`): Interactive tutorial teaching Ouroboros hands-on
- `unstuck` (aliases: `stuck`, `lateral`): Use when the user is stuck or going in circles: the same fix failed twice or more, 'nothing works', 'I've tried everything', or a consequential choice with no clear winner that is hard to undo or splits the team (which database, which architecture). Brings hacker, researcher, simplifier, architect, and contrarian perspectives and converges on one recommendation. Not for a first error or normal progress.
- `update`: Check for updates and upgrade Ouroboros to the latest version
- `welcome` (invoke as `/ouroboros:welcome`): First-touch experience for new Ouroboros users
<!-- generated:skills end -->

## Key File Structure

```
ouroboros/
  skills/             # Skill implementations (*/SKILL.md)
  src/ouroboros/
    cli/              # Typer CLI entry point and command groups
      main.py         # App definition; registers every command under CLI Commands
      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/`