llms.txt · git:20261112.456cca4 · 2026-11-12 · sha256 5b55ea45df21bab8
llms.txt git:20261112.456cca4A
Immutable. This exact content never changes and is served at /api/v1/blob/5b55ea45df21bab8.
# 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: Complexity analysis, task routing, model escalation/downgrade. Located in `src/ouroboros/routing/`.
- 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/`