ralph（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. *Most AI coding fails at the input, not the output. Ouroboros fixes the human, not the machine.*

When to use this skill

• Before writing any code — expose hidden assumptions with Socratic interviewing (Ambiguity ≤ 0.2 required)
• Vague requirements — crystallize into an immutable YAML seed spec before touching the keyboard
• Long-running tasks needing autonomous iteration until verified completion
• Guaranteed completion tasks — Ralph loop persists across session boundaries until verification passes
• When stuck — Nine Minds lateral thinking personas break through stagnation
• Drift detection — measure deviation from original seed and course-correct before it's too late
• Ontology convergence — evolutionary loop runs until consecutive generations are ≥ 0.95 similar

Quick Start

ooo interview "design a Unity quest system with testable save-state behavior"
ooo seed
ooo ralph "implement the accepted Unity quest system and verify playmode tests"

Instructions

1. Use ooo interview first when the Unity task is vague or spans gameplay, tooling, and verification.
2. Freeze the clarified contract with ooo seed before long-running execution.
3. Run ooo ralph only after acceptance criteria and verification targets are explicit.

Examples

ooo interview "add a Unity inventory system without breaking save compatibility"

ooo ralph "fix all failing editmode tests in the combat package"

Core Architecture: The Ouroboros 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

First diamond (Socratic): diverge into questions → converge into ontological clarity. Second diamond (Pragmatic): diverge into design options → converge into verified delivery.

You cannot design what you haven't understood. The first diamond is a prerequisite for the second.

Commands

Phase 1: Interview — From Wonder to Ontology

*Wonder → "How should I live?" → "What IS 'live'?" → Ontology* — Socrates

The Socratic Interviewer asks questions until Ambiguity ≤ 0.2. This is the gate between vague desire and executable spec.

ooo interview "I want to build a task management CLI"

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   # "Build a CLI task manager" — clear
Constraint: 0.8 × 0.3 = 0.24   # "Python 3.14+, SQLite only" — defined
Success:    0.7 × 0.3 = 0.21   # "Tasks create/list/complete" — measurable
                      ──────
Clarity             = 0.81
Ambiguity = 1 − 0.81 = 0.19 ≤ 0.2 → ✓ Ready for Seed

Why 0.2? At 80% weighted clarity, remaining unknowns are small enough for code-level decisions to resolve. Above that threshold, you're still guessing at architecture.

Phase 2: Seed — Immutable Specification

ooo seed

Generates YAML spec locked from interview answers:

goal: Build a CLI task management tool
constraints:
  - Python 3.14+
  - No external database
  - SQLite for persistence
acceptance_criteria:
  - Tasks can be created with title and priority
  - Tasks can be listed with status filter
  - Tasks can be marked complete
ontology_schema:
  name: TaskManager
  fields:
    - name: tasks
      type: array
    - name: title
      type: string
    - name: priority
      type: enum[low, medium, high]
    - name: status
      type: enum[open, done]

The seed is immutable. Once generated, it is the ground truth. Drift is measured against it.

Phase 3: Execute — Double Diamond Run

ooo run seed.yaml
ooo run   # uses seed from conversation context

Executes the four phases:

1. Discover — research existing patterns, constraints, precedents
2. Define — ontological clarity, edge cases, decision boundaries
3. Design — architecture, component breakdown, interface contracts
4. Deliver — implementation, tests, documentation

Phase 4: Evaluate — 3-Stage Verification Gate

ooo evaluate <session_id>

Drift Thresholds

Drift = weighted deviation from seed across three axes: Goal(50%) + Constraint(30%) + Ontology(20%).

Phase 5: Evolve — Ontological Convergence

ooo evolve "build a task management CLI"
ooo evolve "topic" --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 Similarity ≥ 0.95 or 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}                     → baseline
Gen 2: {Task, Priority, Status, DueDate}            → similarity 0.78 → CONTINUE
Gen 3: {Task, Priority, Status, DueDate}            → similarity 1.00 → CONVERGED ✓

Stagnation Detection

Ralph — Persistent Loop Until Verified

ooo ralph "fix all failing tests"
ooo ralph "implement the payment module"

"The boulder never stops." Each failure is data for the next attempt. Only verified success or max iterations stops it.

Loop Architecture

┌─────────────────────────────────────┐
│  1. EXECUTE (parallel agents)       │
│     Fire independent sub-tasks      │
│     concurrently via Agent tool     │
├─────────────────────────────────────┤
│  2. VERIFY                          │
│     Check acceptance criteria       │
│     Run tests, lint, typecheck      │
│     Measure drift vs seed           │
├─────────────────────────────────────┤
│  3. LOOP (if failed)                │
│     Analyze failure evidence        │
│     Fix identified issues           │
│     Increment iteration counter     │
│     Repeat from step 1              │
├─────────────────────────────────────┤
│  4. PERSIST (each iteration)        │
│     .omc/state/ralph-ooo-state.json │
│     Resume after interruption       │
└─────────────────────────────────────┘

State File Schema

Create .omc/state/ralph-ooo-state.json on start:

{
  "mode": "ralph-ooo",
  "session_id": "<uuid>",
  "request": "<user request>",
  "status": "running",
  "iteration": 0,
  "max_iterations": 10,
  "last_checkpoint": null,
  "seed_path": null,
  "verification_history": []
}

Loop Logic (Pseudocode)

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()
    })
    save_checkpoint(f"iteration_{iteration}")
    if verification.passed:
        save_checkpoint("complete")
        break
    iteration += 1

Progress Report Format

[Ralph-OOO Iteration 1/10]
Executing in parallel...

Verification: FAILED
Score: 0.65
Issues:
  - 3 tests still failing
  - Type error in src/api.py:42

The boulder never stops. Continuing...

[Ralph-OOO Iteration 3/10]
Verification: PASSED ✓
Score: 1.0

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

Completion Promise (Codex / Gemini)

<promise>DONE</promise>

Default promise: DONE | Default max iterations: 10

Cancellation

The Nine Minds

Loaded on-demand — never preloaded. Each mind has a single core question it cannot stop asking.

See references/nine-minds.md for full agent profiles.

Unstuck — Lateral Thinking

When blocked after repeated failures:

ooo unstuck                  # auto-select based on context
ooo unstuck simplifier       # cut scope to MVP
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

Decision guide:

• Repeated similar failures → contrarian (challenge assumptions)
• Too many options / paralysis → simplifier (reduce scope)
• Missing information / unclear root cause → researcher (seek evidence)
• Analysis paralysis / need momentum → hacker (just make it work)
• Structural issues / wrong foundation → architect (redesign)

Quick Reference

Available Scripts

Run from the skill directory:

Platform Support Matrix

Installation

# Claude Code (via oh-my-skills)
npx skills add https://github.com/akillness/oh-my-skills --skill ralph-ooo

# Codex CLI setup
bash .agent-skills/ralph-ooo/scripts/setup-codex-hook.sh

# Gemini CLI setup
bash .agent-skills/ralph-ooo/scripts/setup-gemini-hook.sh

# Ouroboros native plugin
claude plugin marketplace add Q00/ouroboros
claude plugin install ouroboros@ouroboros
ooo setup

References

Detailed documentation in references/:

Source: Q00/ouroboros — MIT License