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 <session_id>

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": "<uuid>",

  "request": "<user 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": <now>

    })

    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 <lineage_id>          # check lineage status

ooo evolve --rewind <lineage_id> <gen_N>  # 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 "<task>" [--completion-promise=TEXT] [--max-iterations=N] as a contract command

• Parse completion signal inside XML: <promise>VALUE</promise>

• 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 <session_id>

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>/ralph/scripts/setup-codex-hook.sh

# Gemini CLI (extensions)

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

# All platforms via skills-template

npx skills add https://github.com/supercent-io/skills-template --skill ralph

Source: Q00/ouroboros — MIT License