--- id: sm-ralph name: "ralph" url: https://skills.yangsir.net/skill/sm-ralph author: supercent-io domain: ai-agent-core-development tags: ["ai-agents", "llm-orchestration", "prompt-engineering", "agent-frameworks", "ai-development"] install_count: 10700 rating: 4.50 (427 reviews) github: https://github.com/supercent-io/skills-template --- # ralph > 该技能倡导“规范优先”的AI开发模式，通过明确的规范而非提示词来指导AI，实现更精准、可控的AI系统构建。 **Stats**: 10,700 installs · 4.5/5 (427 reviews) ## Before / After 对比 ### Ralph 规范优先 AI 开发对比 | Metric | Before | After | Change | |---|---|---|---| | - | - | - | - | | - | - | - | - | | - | - | - | - | ## Readme # 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 ``` 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": "", "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": }) 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 # check lineage status ooo evolve --rewind # 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 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 /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 "" [--completion-promise=TEXT] [--max-iterations=N]` as a contract command - Parse completion signal inside XML: `VALUE` - 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:** ``` DONE ``` 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 ` 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 /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](https://github.com/Q00/ouroboros) — MIT License Weekly Installs10.4KRepository[supercent-io/sk…template](https://github.com/supercent-io/skills-template)GitHub Stars58First SeenFeb 20, 2026Security Audits[Gen Agent Trust HubWarn](/supercent-io/skills-template/ralph/security/agent-trust-hub)[SocketPass](/supercent-io/skills-template/ralph/security/socket)[SnykWarn](/supercent-io/skills-template/ralph/security/snyk)Installed oncodex10.4Kgemini-cli10.4Kopencode10.4Kcursor10.3Kgithub-copilot10.3Kkimi-cli10.3K --- *Source: https://skills.yangsir.net/skill/sm-ralph* *Markdown mirror: https://skills.yangsir.net/api/skill/sm-ralph/markdown*