Ooo

ooo — Ouroboros Specification-First Workflow

Stop prompting. Start specifying.

ooo is the portable Ouroboros method for spec-first development:

Interview → Seed → Execute → Evaluate → Evolve
                     ↓
                 ooo ralph
             (persist until verified)

Installation

Plugin (recommended for Claude Code)

claude plugin marketplace add Q00/ouroboros

pip

pip install ouroboros-ai           # base
pip install ouroboros-ai[all]      # full: Claude, LiteLLM, MCP, TUI

Skill (any platform)

npx skills add https://github.com/akillness/jeo-skills --skill ooo

Setup runtimes

ouroboros setup                    # auto-detect Claude / Codex / OpenCode
ouroboros setup --runtime claude
ouroboros setup --runtime codex
ouroboros setup --runtime opencode --opencode-mode plugin

When to use

• Vague request needs a Socratic interview before coding starts
• Requirements should become an immutable seed/spec before implementation
• Task needs a verify-before-done loop, not a one-shot answer
• You want to keep going until completion is actually verified
• Measure drift against the original contract
• Repeated failures need structured unstuck step instead of blind retries

Do not use when

• Task is mainly platform setup or runtime commands → omc / omx / ohmg
• Task is mainly permission posture, sandbox, trust folders → (configure via ouroboros setup)
• Task needs integrated project ledgers + plan review + cleanup workflow → jeo
• Task is only pre-implementation landscape research → survey

Core commands

Interview — clarify before coding

ouroboros init start "build a task management CLI"
ouroboros init start --resume <interview-id>
ouroboros init list

Ambiguity gate

• Greenfield: Goal 40% + Constraints 30% + Success 30%
• Brownfield: Goal 35% + Constraints 25% + Success 25% + Context 15%
• Do not move to seed until Ambiguity ≤ 0.2

Seed — freeze the spec

After interview completes, a seed.yaml is generated in .ouroboros/seeds/.

# example seed.yaml
goal: "Build a CLI task manager with SQLite persistence"
constraints:
  - "Python 3.12+"
  - "No external HTTP dependencies"
acceptance_criteria:
  - "CRUD operations work end-to-end"
  - "All unit tests pass"

Run — execute against the seed

ouroboros run workflow <seed.yaml>
ouroboros run workflow <seed.yaml> --sequential
ouroboros run workflow <seed.yaml> --no-qa
ouroboros run resume [execution-id]

Options

Evaluate — verify before done

Three-stage gate: 1. Mechanical — lint, tests, build, typecheck, coverage 2. Semantic — acceptance criteria and goal alignment 3. Consensus — optional multi-model agreement

ouroboros status executions
ouroboros status execution <execution-id> --events

Drift thresholds

Ralph — persistent completion loop

# keyword: ooo ralph
ouroboros run workflow seed.yaml     # run → verify → adjust → repeat
ouroboros run resume                 # resume last paused execution

Loop contract: 1. execute 2. verify (mechanical + semantic) 3. record failure evidence 4. adjust 5. continue until verified or capped

Evolve — continuous refinement

Runs when the ontology or solution shape is still changing.

ouroboros run workflow seed.yaml    # evolve loop runs automatically

Stop condition: convergence similarity ≥ 0.95

Cancel

ouroboros cancel execution <id>
ouroboros cancel execution --all
ouroboros cancel execution --reason "requirements changed"

Config

ouroboros config show
ouroboros config show orchestrator
ouroboros config backend claude
ouroboros config backend codex
ouroboros config set orchestrator.permission_mode allowedTools
ouroboros config validate

Status & TUI

ouroboros status health
ouroboros status executions -n 20
ouroboros tui monitor              # Textual TUI (Python)
ouroboros tui monitor --backend slt  # native Rust TUI

TUI keyboard shortcuts

Unstuck mode

When repeated attempts fail, choose a deliberate persona instead of retrying blindly.

Nine agents in the pool: Socratic Interviewer, Ontologist, Seed Architect, Seed Closer, Semantic Evaluator, Consensus Reviewer, Evaluator, QA Judge, plus domain-specific specialists.

MCP server

ouroboros mcp serve                           # stdio transport (default)
ouroboros mcp serve --transport sse --port 8080
ouroboros mcp info

# Claude Desktop integration
claude mcp add ouroboros -- uvx --from ouroboros-ai[mcp] ouroboros mcp serve

Available MCP tools

• ouroboros_execute_seed — execute a seed specification
• ouroboros_session_status — get session status
• ouroboros_query_events — query event history

Environment variables

Configuration files

Operating rules

1. Clarify before coding — do not move to seed until ambiguity ≤ 0.2 2. Freeze the seed — do not rewrite the contract mid-run 3. Measure drift against the original seed, not latest chat rationale 4. Verify before done — tests, checks, and acceptance criteria matter more than confidence 5. Treat failure as data — every failed loop feeds the next attempt 6. Keep runtime ownership separate — platform hooks belong in omc / omx / ohmg

Examples

# Full spec-first flow
ouroboros init start "build a REST API with auth"
ouroboros run workflow .ouroboros/seeds/seed_<hash>.yaml
ouroboros status executions

# Persistent verified loop (ooo ralph)
ouroboros run workflow seed.yaml
ouroboros run resume

# Monitor progress
ouroboros tui monitor

# Uninstall
ouroboros uninstall --keep-data

Source: Q00/ouroboros v0.29.0 — MIT License