ralph (Ouroboros) — Specification-First AI Development

Stop prompting. Start specifying.

"The beginning is the end, and the end is the beginning."

The serpent doesn't repeat — it evolves.

When to use this skill

Before writing any code

— expose hidden assumptions with Socratic interviewing

Long-running tasks

that need autonomous iteration until verified

Vague requirements

— crystallize them into an immutable spec (Ambiguity ≤ 0.2)

Tasks requiring guaranteed completion

— loop until verification passes

When stuck

— 5 lateral thinking personas break through stagnation

Drift detection

— measure how far execution has deviated from original spec

Core Architecture: The Loop

Interview → Seed → Execute → Evaluate

↑ ↓

└──── Evolutionary Loop ────┘

Each cycle

evolves

, not repeats. Evaluation output feeds back as input for the next generation until the system converges.

Double Diamond

◇ Wonder ◇ Design

╱ (diverge) ╱ (diverge)

╱ explore ╱ create

╱ ╱

◆ ──────────── ◆ ──────────── ◆

╲ ╲

╲ define ╲ deliver

╲ (converge) ╲ (converge)

◇ Ontology ◇ Evaluation

The first diamond is

Socratic

diverge into questions, converge into ontological clarity.
The second diamond is
pragmatic: diverge into design options, converge into verified delivery. 1. Commands (Full Reference) Command Trigger Keywords What It Does ooo interview ooo interview , interview me , clarify requirements , socratic questioning Socratic questioning → expose hidden assumptions ooo seed ooo seed , crystallize , generate seed , freeze requirements Crystallize interview into immutable spec (Ambiguity ≤ 0.2) ooo run ooo run , execute seed , ouroboros run Execute via Double Diamond decomposition ooo evaluate ooo evaluate , 3-stage check , evaluate this , verify execution 3-stage gate: Mechanical → Semantic → Multi-Model Consensus ooo evolve ooo evolve , evolutionary loop , iterate until converged Evolutionary loop until ontology converges (similarity ≥ 0.95) ooo unstuck ooo unstuck , I'm stuck , think sideways , lateral thinking 5 lateral thinking personas when stuck ooo status ooo status , am I drifting? , drift check , session status Drift detection + session tracking ooo ralph ooo ralph , ralph , don't stop , must complete , keep going Persistent loop until verified — The boulder never stops ooo setup ooo setup Register MCP server (one-time) ooo help ooo help Full reference 2. Interview → Specification Flow Philosophy: From Wonder to Ontology Wonder → "How should I live?" → "What IS 'live'?" → Ontology — Socrates Wonder Ontology 💡 🔬 "What do I want?" → "What IS the thing I want?" "Build a task CLI" → "What IS a task? What IS priority?" "Fix the auth bug" → "Is this the root cause, or a symptom?" Step 1: Interview (expose hidden assumptions) ooo interview "I want to build a task management CLI" The Socratic Interviewer asks questions until Ambiguity ≤ 0.2 . Ambiguity formula: Ambiguity = 1 − Σ(clarityᵢ × weightᵢ) Greenfield: Goal(40%) + Constraint(30%) + Success(30%) Brownfield: Goal(35%) + Constraint(25%) + Success(25%) + Context(15%) Threshold: Ambiguity ≤ 0.2 → ready for Seed Example scoring: Goal: 0.9 × 0.4 = 0.36 Constraint: 0.8 × 0.3 = 0.24 Success: 0.7 × 0.3 = 0.21 ────── Clarity = 0.81 Ambiguity = 1 − 0.81 = 0.19 ≤ 0.2 → ✓ Ready for Seed Step 2: Seed (crystallize into immutable spec) ooo seed Generates YAML specification: goal : Build a CLI task management tool constraints : - Python 3.14+ - No external database - SQLite for persistence acceptance_criteria : - Tasks can be created - Tasks can be listed - Tasks can be marked complete ontology_schema : name : TaskManager fields : - name : tasks type : array - name : title type : string Step 3: Run (execute via Double Diamond) ooo run seed.yaml ooo run # uses seed from conversation context Step 4: Evaluate (3-stage verification) ooo evaluate Stage Cost What It Checks Mechanical $0 Lint, build, tests, coverage Semantic Standard AC compliance, goal alignment, drift score Consensus Frontier (optional) Multi-model vote, majority ratio Drift thresholds: 0.0 – 0.15 — Excellent: on track 0.15 – 0.30 — Acceptable: monitor closely 0.30+ — Exceeded: course correction needed 3. Ralph — Persistent Loop Until Verified ooo ralph "fix all failing tests" /ouroboros:ralph "fix all failing tests" "The boulder never stops." Each failure is data for the next attempt. Only complete success or max iterations stops it. How Ralph Works ┌─────────────────────────────────┐ │ 1. EXECUTE (parallel) │ │ Independent tasks │ │ concurrent scheduling │ ├─────────────────────────────────┤ │ 2. VERIFY │ │ Check completion │ │ Validate tests pass │ │ Measure drift vs seed │ ├─────────────────────────────────┤ │ 3. LOOP (if failed) │ │ Analyze failure │ │ Fix identified issues │ │ Repeat from step 1 │ ├─────────────────────────────────┤ │ 4. PERSIST (checkpoint) │ │ .omc/state/ralph-state.json │ │ Resume after interruption │ └─────────────────────────────────┘ State File Create .omc/state/ralph-state.json on start: { "mode" : "ralph" , "session_id" : "" , "request" : "" , "status" : "running" , "iteration" : 0 , "max_iterations" : 10 , "last_checkpoint" : null , "verification_history" : [ ] } Loop Logic while iteration < max_iterations: result = execute_parallel(request, context) verification = verify_result(result, acceptance_criteria) state.verification_history.append({ "iteration": iteration, "passed": verification.passed, "score": verification.score, "timestamp": }) if verification.passed: save_checkpoint("complete") break iteration += 1 save_checkpoint("iteration_{iteration}") Progress Report Format [Ralph Iteration 1/10] Executing in parallel... Verification: FAILED Score: 0.65 Issues: - 3 tests still failing - Type errors in src/api.py The boulder never stops. Continuing... [Ralph Iteration 3/10] Executing in parallel... Verification: PASSED Score: 1.0 Ralph COMPLETE ============== Request: Fix all failing tests Duration: 8m 32s Iterations: 3 Verification History: - Iteration 1: FAILED (0.65) - Iteration 2: FAILED (0.85) - Iteration 3: PASSED (1.0) Cancellation Action Command Save checkpoint & exit /ouroboros:cancel Force clear all state /ouroboros:cancel --force Resume after interruption ooo ralph continue or ralph continue 4. Evolutionary Loop (Evolve) ooo evolve "build a task management CLI" ooo evolve "build a task management CLI" --no-execute # ontology-only, fast mode Flow Gen 1: Interview → Seed(O₁) → Execute → Evaluate Gen 2: Wonder → Reflect → Seed(O₂) → Execute → Evaluate Gen 3: Wonder → Reflect → Seed(O₃) → Execute → Evaluate ...until ontology converges (similarity ≥ 0.95) or max 30 generations Convergence Formula Similarity = 0.5 × name_overlap + 0.3 × type_match + 0.2 × exact_match Threshold: Similarity ≥ 0.95 → CONVERGED Gen 1: {Task, Priority, Status} Gen 2: {Task, Priority, Status, DueDate} → similarity 0.78 → CONTINUE Gen 3: {Task, Priority, Status, DueDate} → similarity 1.00 → CONVERGED ✓ Stagnation Detection Signal Condition Meaning Stagnation Similarity ≥ 0.95 for 3 consecutive gens Ontology has stabilized Oscillation Gen N ≈ Gen N-2 (period-2 cycle) Stuck bouncing between two designs Repetitive feedback ≥ 70% question overlap across 3 gens Wonder asking the same things Hard cap 30 generations reached Safety valve Ralph in Evolve Mode Ralph Cycle 1: evolve_step(lineage, seed) → Gen 1 → action=CONTINUE Ralph Cycle 2: evolve_step(lineage) → Gen 2 → action=CONTINUE Ralph Cycle 3: evolve_step(lineage) → Gen 3 → action=CONVERGED ✓ └── Ralph stops. The ontology has stabilized. Rewind ooo evolve --status # check lineage status ooo evolve --rewind # roll back to generation N 5. The Nine Minds (Agents) Loaded on-demand — never preloaded: Agent Role Core Question Socratic Interviewer Questions-only. Never builds. "What are you assuming?" Ontologist Finds essence, not symptoms "What IS this, really?" Seed Architect Crystallizes specs from dialogue "Is this complete and unambiguous?" Evaluator 3-stage verification "Did we build the right thing?" Contrarian Challenges every assumption "What if the opposite were true?" Hacker Finds unconventional paths "What constraints are actually real?" Simplifier Removes complexity "What's the simplest thing that could work?" Researcher Stops coding, starts investigating "What evidence do we actually have?" Architect Identifies structural causes "If we started over, would we build it this way?" 6. Unstuck — Lateral Thinking When blocked after repeated failures, choose a persona: ooo unstuck # auto-select based on situation ooo unstuck simplifier # cut scope to MVP — "Start with exactly 2 tables" ooo unstuck hacker # make it work first, elegance later ooo unstuck contrarian # challenge all assumptions ooo unstuck researcher # stop coding, find missing information ooo unstuck architect # restructure the approach entirely When to use each: Repeated similar failures → contrarian (challenge assumptions) Too many options → simplifier (reduce scope) Missing information → researcher (seek data) Analysis paralysis → hacker (just make it work) Structural issues → architect (redesign) 7. Platform Installation & Usage Claude Code (Native Plugin — Full Mode)

Install

claude plugin marketplace add Q00/ouroboros claude plugin install ouroboros@ouroboros

One-time setup

ooo setup

Use

ooo interview "I want to build a task CLI" ooo seed ooo run ooo evaluate < session_id

ooo ralph "fix all failing tests" All ooo commands work natively. Hooks auto-activate: UserPromptSubmit → keyword-detector.mjs detects triggers PostToolUse(Write|Edit) → drift-monitor.mjs tracks deviation SessionStart → session initialization Claude Code hooks.json (installed at ${CLAUDE_PLUGIN_ROOT}/hooks/hooks.json ): { "hooks" : { "SessionStart" : [ { "matcher" : "" , "hooks" : [ { "type" : "command" , "command" : "node \"${CLAUDE_PLUGIN_ROOT}/scripts/session-start.mjs\"" , "timeout" : 5 } ] } ] , "UserPromptSubmit" : [ { "matcher" : "" , "hooks" : [ { "type" : "command" , "command" : "node \"${CLAUDE_PLUGIN_ROOT}/scripts/keyword-detector.mjs\"" , "timeout" : 5 } ] } ] , "PostToolUse" : [ { "matcher" : "Write|Edit" , "hooks" : [ { "type" : "command" , "command" : "node \"${CLAUDE_PLUGIN_ROOT}/scripts/drift-monitor.mjs\"" , "timeout" : 3 } ] } ] } } Codex CLI (Adapted Mode — bash loop) Codex CLI has no native AfterAgent hooks. Use the setup script to configure:

Setup

bash < your-agent-skills

/ralph/scripts/setup-codex-hook.sh

Restart Codex, then use:

/prompts:ralph

load ralph loop context

/prompts:ouroboros

load full ouroboros context

Use ooo commands in conversation:

ooo interview "build a REST API" ooo ralph "fix all TypeScript errors" Codex ralph loop contract: Treat /ralph "" [--completion-promise=TEXT] [--max-iterations=N] as a contract command Parse completion signal inside XML: VALUE If promise missing and iteration < max-iterations → continue immediately with same original command If promise found or max-iterations reached → finish with status report Completion promise syntax: < promise

DONE </ promise

Manual state management for Codex: Create .omc/state/ralph-state.json at loop start Update iteration counter each cycle Set status: "complete" when promise found Default completion promise: DONE | Default max iterations: 10 Gemini CLI (AfterAgent Hook Mode)

Install via extensions

gemini extensions install https://github.com/Q00/ouroboros

OR install skills-template

gemini extensions install https://github.com/supercent-io/skills-template Required in ~/.gemini/settings.json : { "hooksConfig" : { "enabled" : true } , "context" : { "includeDirectories" : [ "~/.gemini/extensions/ralph" ] } } AfterAgent hook for loop continuation (add to ~/.gemini/settings.json ): { "hooks" : { "AfterAgent" : [ { "matcher" : "*" , "hooks" : [ { "type" : "command" , "command" : "bash ~/.gemini/hooks/ralph-check.sh" , "timeout" : 10 } ] } ] } } Run in sandbox + YOLO mode to prevent constant confirmation prompts: gemini -s -y Then use ooo commands directly: ooo interview "build a task CLI" ooo ralph "fix all tests" ⚠️ Gemini v0.30.0 bug : stop_hook_active always false in hook JSON. Workaround: check .omc/state/ralph-state.json directly instead of relying on the hook field. 8. Platform Support Matrix Platform Native Support Mechanism ooo Commands Loop Claude Code ✅ Full Plugin + hooks All ooo commands Auto via hooks Codex CLI 🔧 Adapted bash + /prompts:ralph Via conversation Manual state file Gemini CLI ✅ Native AfterAgent hook All ooo commands Auto via hook OpenCode ✅ Native Skills system All ooo commands Auto via loop 9. Quick Reference Action Command Socratic interview ooo interview "topic" Generate spec ooo seed Execute spec ooo run [seed.yaml] 3-stage evaluate ooo evaluate Evolve until converged ooo evolve "topic" Persistent loop ooo ralph "task" Break stagnation ooo unstuck [persona] Check drift ooo status [session_id] First-time setup ooo setup Cancel /ouroboros:cancel Force cancel + clear /ouroboros:cancel --force Resume ooo ralph continue Cancel (Gemini/Codex) /ralph:cancel 10. Installation

Claude Code

claude plugin marketplace add Q00/ouroboros claude plugin install ouroboros@ouroboros ooo setup

Codex CLI

bash < skills