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:

yaml

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:

json

{
  "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)

bash

# 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

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:

bash

# 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:

xml

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

bash

# 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

json

{
  "hooksConfig": { "enabled": true },
  "context": {
    "includeDirectories": ["~/.gemini/extensions/ralph"]
  }
}

AfterAgent hook for loop continuation (add to

~/.gemini/settings.json

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:

bash

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

bash

# 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

ralph

NPX Install

Tags

SKILL.md Content

ralph (Ouroboros) — Specification-First AI Development

When to use this skill

Core Architecture: The Loop

Double Diamond

1. Commands (Full Reference)

2. Interview → Specification Flow

Philosophy: From Wonder to Ontology

Step 1: Interview (expose hidden assumptions)

Step 2: Seed (crystallize into immutable spec)

Step 3: Run (execute via Double Diamond)

Step 4: Evaluate (3-stage verification)

3. Ralph — Persistent Loop Until Verified

How Ralph Works

State File

Loop Logic

Progress Report Format

Cancellation

4. Evolutionary Loop (Evolve)

Flow

Convergence Formula

Stagnation Detection

Ralph in Evolve Mode

Rewind

5. The Nine Minds (Agents)

6. Unstuck — Lateral Thinking

7. Platform Installation & Usage

Claude Code (Native Plugin — Full Mode)

Codex CLI (Adapted Mode — bash loop)

Gemini CLI (AfterAgent Hook Mode)

8. Platform Support Matrix

9. Quick Reference

10. Installation