A local-first Agent OS runtime for reproducible, specification-first AI coding workflows, restructuring AI coding through Socratic interviews, immutable seed specs, and a 3-stage evaluation gate.
Positioning & Philosophy#
Ouroboros is positioned as an Agent OS advocating "Stop prompting. Start specifying." It does not generate code directly, but serves as a runtime layer above AI coding tools (Claude Code, Codex CLI, OpenCode, Hermes), enforcing a specification-first workflow to solve the "rework trap" where vague ideas lead directly to code generation and defects surface only during PR review.
Core Mechanisms#
Requirement Refinement & Specification#
- Socratic Interview: Exposes implicit assumptions through active questioning, transforming vague ideas into structured requirements.
- Immutable Seed Spec: Crystallizes interview results into specification files containing acceptance criteria, ontology, and constraints.
- Ambiguity Score: Hard threshold of ≤ 0.2 prevents premature coding when assumptions are insufficiently exposed.
Execution & Verification#
- Double Diamond Execution: Strictly follows Discover → Define → Design → Deliver stages.
- 3-Stage Evaluation Gate: Mechanical (free) → Semantic → Multi-Model Consensus, progressively increasing verification rigor.
Evolution & Continuous Optimization#
- Evolutionary Loop: Feeds evaluation outputs back as next-generation seed specs for continuous iteration.
- Ralph Persistent Loop:
ooo ralphruns continuously across sessions, reconstructing full lineage via EventStore until verification passes. - Ontology Convergence: Ontology similarity ≥ 0.95 serves as the convergence stop condition.
Intelligent Assistance#
- Nine Minds: On-demand loading of 9 thinking modes: Socratic Interviewer, Ontologist, Seed Architect, Evaluator, Contrarian, Hacker, Simplifier, Researcher, Architect.
- Lateral Thinking:
ooo unstuckprovides 5 lateral thinking personas to break through blockers.
Collaboration & Engineering#
ooo publishpublishes Seeds as GitHub Epic/Task issues for team collaboration.ooo pmprovides PM-perspective interviews and PRD generation.ooo qadelivers universal quality assessment for any artifact.ooo brownfieldscans existing repositories for quick workflow integration.
Architecture Overview#
- Python Core: Business logic in
src/ouroboros/, managed viapyproject.toml, requires Python >= 3.12, uses uv package manager. - Rust TUI:
crates/ouroboros-tui/contains Rust-built terminal UI with Double Diamond visualization. - MCP Server Integration: Registers Ouroboros as a Model Context Protocol tool server via
.mcp.json. - Runtime Plugins: Supports Claude Code, Codex CLI, OpenCode, Hermes backends.
- EventStore: Stateless architecture using event sourcing for cross-session lineage reconstruction.
- Skills & Commands:
skills/for loadable skill definitions,commands/for agent command mappings,hooks/for runtime lifecycle hooks.
Installation & Quick Start#
One-click install (auto-detects AI coding tools and registers MCP server):
curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.sh | bash
Build from source:
git clone https://github.com/Q00/ouroboros
cd ouroboros
uv sync --all-groups && uv run pytest
Quick usage (in AI coding tool session):
> ooo interview "I want to build a task management CLI"
Key Commands#
| Command | Function |
|---|---|
ooo setup | Register runtime and configure project |
ooo interview | Start Socratic interview |
ooo seed | Crystallize into immutable spec |
ooo run | Start Double Diamond execution from spec |
ooo evaluate | Trigger 3-stage evaluation gate |
ooo evolve | Start evolutionary loop until convergence |
ooo ralph | Persistent loop until verification passes |
ooo unstuck | Lateral thinking to break through blockers |
ooo pm | PM interview and PRD generation |
ooo qa | Universal QA assessment |
ooo brownfield | Scan existing repository |
ooo publish | Publish as GitHub Epic/Task |
ooo status | Session tracking and drift detection |
ooo tutorial | Interactive learning tutorial |