ralph

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
Thresho