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.

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)

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>

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

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

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:

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:

1. Treat /ralph "<task>" [--completion-promise=TEXT] [--max-iterations=N] as a contract command
2. Parse completion signal inside XML: <promise>VALUE</promise>
3. If promise missing and iteration < max-iterations → continue immediately with same original command
4. 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

9. Quick Reference

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