ralph
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chineseralph (Ouroboros) — Specification-First AI Development
ralph (Ouroboros) — 规约优先的AI开发
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.
停止写提示词。开始制定规约。"起点即是终点,终点亦是起点。" 衔尾蛇不会重复——它会进化。大多数AI编码的失败根源在于输入而非输出。Ouroboros解决的是人的问题,而非机器的问题。
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
- 编写任何代码之前 — 通过苏格拉底式访谈暴露隐藏的假设(要求歧义度≤0.2)
- 需求模糊 — 动手敲代码前先具象化为不可变的YAML种子规约
- 需要自主迭代直到验证完成的长期运行任务
- 要求保证完成的任务 — Ralph循环可跨会话持久运行直到验证通过
- 遇到阻塞时 — 九心智横向思考角色可打破停滞状态
- 漂移检测 — 衡量与原始种子规约的偏差,在问题失控前修正路线
- 本体收敛 — 进化循环持续运行直到连续代际相似度≥0.95
Core Architecture: The Ouroboros Loop
核心架构:Ouroboros循环
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.
Interview → Seed → Execute → Evaluate
↑ ↓
└──── Evolutionary Loop ────┘每个周期是进化而非重复。评估输出会作为下一代的输入反馈,直到系统收敛。
Double Diamond
Double Diamond
◇ Wonder ◇ Design
╱ (diverge) ╱ (diverge)
╱ explore ╱ create
╱ ╱
◆ ──────────── ◆ ──────────── ◆
╲ ╲
╲ define ╲ deliver
╲ (converge) ╲ (converge)
◇ Ontology ◇ EvaluationFirst 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.
◇ Wonder ◇ Design
╱ (diverge) ╱ (diverge)
╱ explore ╱ create
╱ ╱
◆ ──────────── ◆ ──────────── ◆
╲ ╲
╲ define ╲ deliver
╲ (converge) ╲ (converge)
◇ Ontology ◇ Evaluation第一个钻石(苏格拉底阶段): 发散提问 → 收敛到本体清晰度。
第二个钻石(务实阶段): 发散设计选项 → 收敛到验证过的交付产物。
你无法设计你还没理解的东西。第一个钻石是第二个的前置条件。
Commands
命令
| Command | Triggers | What It Does |
|---|---|---|
| | Socratic questioning until Ambiguity ≤ 0.2 |
| | Crystallize into immutable YAML spec |
| | Execute via Double Diamond |
| | 3-stage gate: Mechanical → Semantic → Consensus |
| | Evolutionary loop until Similarity ≥ 0.95 |
| | Nine Minds lateral thinking personas |
| | Drift detection + session tracking |
| | Persistent loop until verified |
| | Register MCP server (one-time) |
| | Save checkpoint and exit |
| 命令 | 触发词 | 功能 |
|---|---|---|
| | 苏格拉底式提问直到歧义度≤0.2 |
| | 具象化为不可变的YAML规约 |
| | 通过Double Diamond流程执行 |
| | 三阶段门控:机械检查 → 语义检查 → 共识检查 |
| | 进化循环直到相似度≥0.95 |
| | 九心智横向思考角色介入 |
| | 漂移检测 + 会话追踪 |
| | 持久循环直到验证通过 |
| | 注册MCP服务器(仅需一次) |
| | 保存检查点并退出 |
Phase 1: Interview — From Wonder to Ontology
阶段1:访谈 — 从好奇到本体清晰
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"好奇 → "我该如何生活?" → "什么才是'生活'?" → 本体 — 苏格拉底
苏格拉底访谈者会持续提问直到歧义度≤0.2。这是模糊需求和可执行规约之间的关卡。
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 SeedExample 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 SeedWhy 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.
Ambiguity = 1 − Σ(clarityᵢ × weightᵢ)
Greenfield: Goal(40%) + Constraint(30%) + Success(30%)
Brownfield: Goal(35%) + Constraint(25%) + Success(25%) + Context(15%)
阈值: 歧义度 ≤ 0.2 → 可进入种子阶段评分示例:
目标: 0.9 × 0.4 = 0.36 # "构建CLI任务管理器" — 清晰
约束: 0.8 × 0.3 = 0.24 # "仅支持Python 3.14+、SQLite" — 已定义
成功标准: 0.7 × 0.3 = 0.21 # "支持任务创建/列表/完成" — 可衡量
──────
总清晰度 = 0.81
歧义度 = 1 − 0.81 = 0.19 ≤ 0.2 → ✓ 可进入种子阶段为什么是0.2?当加权清晰度达到80%时,剩余的未知项足够小,可以在代码层面决策解决。高于这个阈值的话,你依然是在猜测架构。
Phase 2: Seed — Immutable Specification
阶段2:种子 — 不可变规约
ooo seedGenerates YAML spec locked from interview answers:
yaml
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.
ooo seed根据访谈答案生成锁定的YAML规约:
yaml
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]种子规约是不可变的。 一旦生成,它就是事实基准。所有漂移都会以它为参照衡量。
Phase 3: Execute — Double Diamond Run
阶段3:执行 — Double Diamond运行
ooo run seed.yaml
ooo run # uses seed from conversation contextExecutes the four phases:
- Discover — research existing patterns, constraints, precedents
- Define — ontological clarity, edge cases, decision boundaries
- Design — architecture, component breakdown, interface contracts
- Deliver — implementation, tests, documentation
ooo run seed.yaml
ooo run # 使用会话上下文里的种子规约执行四个阶段:
- 探索 — 调研现有模式、约束、先例
- 定义 — 本体清晰度、边界情况、决策边界
- 设计 — 架构、组件拆分、接口契约
- 交付 — 实现、测试、文档
Phase 4: Evaluate — 3-Stage Verification Gate
阶段4:评估 — 三阶段验证门控
ooo evaluate <session_id>| Stage | Cost | What It Checks |
|---|---|---|
| Mechanical | Free | Lint, build, tests, coverage, type checks |
| Semantic | Standard | AC compliance, goal alignment, drift score |
| Consensus | Frontier (optional) | Multi-model vote, majority ratio |
ooo evaluate <session_id>| 阶段 | 成本 | 检查内容 |
|---|---|---|
| 机械检查 | 免费 | Lint、构建、测试、覆盖率、类型检查 |
| 语义检查 | 标准 | 验收标准合规性、目标对齐度、漂移得分 |
| 共识检查 | 前沿(可选) | 多模型投票,多数决 |
Drift Thresholds
漂移阈值
| Score | Status | Action |
|---|---|---|
| Excellent | On track |
| Acceptable | Monitor closely |
| Exceeded | Course correction required |
Drift = weighted deviation from seed across three axes: Goal(50%) + Constraint(30%) + Ontology(20%).
| 得分 | 状态 | 操作 |
|---|---|---|
| 优秀 | 正常推进 |
| 可接受 | 密切监控 |
| 超出阈值 | 需要修正路线 |
漂移 = 三个维度相对于种子规约的加权偏差:目标(50%) + 约束(30%) + 本体(20%)。
Phase 5: Evolve — Ontological Convergence
阶段5:进化 — 本体收敛
ooo evolve "build a task management CLI"
ooo evolve "topic" --no-execute # ontology-only fast modeooo evolve "build a task management CLI"
ooo evolve "topic" --no-execute # 仅本体快速模式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第1代: 访谈 → 种子(O₁) → 执行 → 评估
第2代: 好奇 → 反思 → 种子(O₂) → 执行 → 评估
第3代: 好奇 → 反思 → 种子(O₃) → 执行 → 评估
...直到相似度≥0.95或达到30代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 ✓相似度 = 0.5 × 名称重叠度 + 0.3 × 类型匹配度 + 0.2 × 完全匹配度
阈值: 相似度 ≥ 0.95 → 已收敛
第1代: {Task, Priority, Status} → 基准
第2代: {Task, Priority, Status, DueDate} → 相似度 0.78 → 继续
第3代: {Task, Priority, Status, DueDate} → 相似度 1.00 → 已收敛 ✓Stagnation Detection
停滞检测
| Signal | Condition | Response |
|---|---|---|
| Stagnation | Similarity ≥ 0.95 for 3 consecutive gens | Stop — converged |
| Oscillation | Gen N ≈ Gen N-2 (period-2 cycle) | Invoke |
| Repetitive feedback | ≥ 70% question overlap across 3 gens | Invoke |
| Hard cap | 30 generations reached | Stop — safety valve |
| 信号 | 条件 | 响应 |
|---|---|---|
| 停滞 | 连续3代相似度≥0.95 | 停止 — 已收敛 |
| 振荡 | 第N代 ≈ 第N-2代(周期为2的循环) | 调用 |
| 重复反馈 | 3代之间问题重叠度≥70% | 调用 |
| 硬上限 | 达到30代 | 停止 — 安全阀门 |
Ralph — Persistent Loop Until Verified
Ralph — 持久循环直到验证通过
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.
ooo ralph "fix all failing tests"
ooo ralph "implement the payment module""巨石永不停歇。"
每一次失败都是下一次尝试的数据。只有验证通过的成功或者达到最大迭代次数才会停止。
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 │
└─────────────────────────────────────┘┌─────────────────────────────────────┐
│ 1. 执行(并行Agents) │
│ 通过Agent工具并发触发独立子任务 │
├─────────────────────────────────────┤
│ 2. 验证 │
│ 检查验收标准 │
│ 运行测试、Lint、类型检查 │
│ 衡量相对于种子规约的漂移 │
├─────────────────────────────────────┤
│ 3. 循环(如果失败) │
│ 分析失败证据 │
│ 修复识别到的问题 │
│ 递增迭代计数器 │
│ 回到步骤1重复 │
├─────────────────────────────────────┤
│ 4. 持久化(每次迭代) │
│ .omc/state/ralph-ooo-state.json │
│ 中断后可恢复 │
└─────────────────────────────────────┘State File Schema
状态文件Schema
Create on start:
.omc/state/ralph-ooo-state.jsonjson
{
"mode": "ralph-ooo",
"session_id": "<uuid>",
"request": "<user request>",
"status": "running",
"iteration": 0,
"max_iterations": 10,
"last_checkpoint": null,
"seed_path": null,
"verification_history": []
}启动时创建:
.omc/state/ralph-ooo-state.jsonjson
{
"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)
循环逻辑(伪代码)
python
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 += 1python
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 += 1Progress 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)[Ralph-OOO 迭代 1/10]
并行执行中...
验证: 失败
得分: 0.65
问题:
- 3个测试仍失败
- src/api.py:42存在类型错误
巨石永不停歇。继续运行...
[Ralph-OOO 迭代 3/10]
验证: 通过 ✓
得分: 1.0
Ralph-OOO 执行完成
==================
请求: 修复所有失败的测试
耗时: 8分32秒
迭代次数: 3
验证历史:
- 迭代1: 失败 (0.65)
- 迭代2: 失败 (0.85)
- 迭代3: 通过 (1.0)Completion Promise (Codex / Gemini)
完成承诺(Codex / Gemini)
xml
<promise>DONE</promise>Default promise: | Default max iterations:
DONE10xml
<promise>DONE</promise>默认承诺: | 默认最大迭代次数:
DONE10Cancellation
取消
| Action | Command |
|---|---|
| Save checkpoint & exit | |
| Force clear all state | |
| Resume after interruption | |
| 操作 | 命令 |
|---|---|
| 保存检查点并退出 | |
| 强制清空所有状态 | |
| 中断后恢复 | |
The Nine Minds
九心智
Loaded on-demand — never preloaded. Each mind has a single core question it cannot stop asking.
| 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?" |
See references/nine-minds.md for full agent profiles.
按需加载 — 从不预加载。每个心智都有一个它无法停止追问的核心问题。
| Agent | 角色 | 核心问题 |
|---|---|---|
| 苏格拉底访谈者 | 只提问,从不构建。 | "你在假设什么?" |
| 本体论专家 | 找到本质,而非症状 | "这到底是什么?" |
| 种子架构师 | 从对话中具象化规约 | "这是完整且无歧义的吗?" |
| 评估者 | 三阶段验证 | "我们构建的是正确的东西吗?" |
| 唱反调者 | 挑战所有假设 | "如果反过来才是对的呢?" |
| 黑客 | 找到非常规路径 | "哪些约束是真的存在的?" |
| 简化者 | 移除复杂度 | "能运行的最简单方案是什么?" |
| 研究者 | 停止编码,开始调研 | "我们实际掌握的证据是什么?" |
| 架构师 | 识别结构性原因 | "如果我们从头开始,还会这么构建吗?" |
查看references/nine-minds.md获取完整Agent档案。
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 entirelyDecision guide:
- Repeated similar failures → (challenge assumptions)
contrarian - Too many options / paralysis → (reduce scope)
simplifier - Missing information / unclear root cause → (seek evidence)
researcher - Analysis paralysis / need momentum → (just make it work)
hacker - Structural issues / wrong foundation → (redesign)
architect
反复失败后遇到阻塞时:
ooo unstuck # 根据上下文自动选择
ooo unstuck simplifier # 缩减范围到MVP
ooo unstuck hacker # 先跑通,再考虑优雅性
ooo unstuck contrarian # 挑战所有假设
ooo unstuck researcher # 停止编码,查找缺失信息
ooo unstuck architect # 彻底重构方案决策指南:
- 反复出现相似失败 → (挑战假设)
contrarian - 选项太多/ paralysis → (缩减范围)
simplifier - 信息缺失/根本原因不明确 → (寻找证据)
researcher - 分析瘫痪/需要推进动力 → (先跑通再说)
hacker - 结构性问题/基础错误 → (重新设计)
architect
Quick Reference
快速参考
| Action | Command |
|---|---|
| Socratic interview | |
| Generate spec | |
| Execute spec | |
| 3-stage evaluate | |
| Evolve until converged | |
| Persistent loop | |
| Break stagnation | |
| Check drift | |
| First-time setup | |
| Cancel | |
| Force cancel | |
| Resume | |
| 操作 | 命令 |
|---|---|
| 苏格拉底式访谈 | |
| 生成规约 | |
| 执行规约 | |
| 三阶段评估 | |
| 进化直到收敛 | |
| 持久循环 | |
| 打破停滞 | |
| 检查漂移 | |
| 首次设置 | |
| 取消 | |
| 强制取消 | |
| 恢复 | |
Available Scripts
可用脚本
Run from the skill directory:
| Script | Purpose |
|---|---|
| Configure Codex CLI for ralph-ooo (developer_instructions + prompts) |
| Configure Gemini CLI AfterAgent hook for loop continuation |
| Manage |
在技能目录下运行:
| 脚本 | 用途 |
|---|---|
| 为ralph-ooo配置Codex CLI(开发者说明 + 提示词) |
| 配置Gemini CLI AfterAgent钩子以支持循环继续 |
| 管理 |
Platform Support Matrix
平台支持矩阵
| Platform | Support | Mechanism | ooo Commands | Auto Loop |
|---|---|---|---|---|
| Claude Code | Full | Skills system + hooks | All | Via hooks |
| Codex CLI | Adapted | bash loop + | Via conversation | Manual state file |
| Gemini CLI | Native | AfterAgent hook | All | Via hook |
| OpenCode | Native | Skills system | All | Via loop |
| 平台 | 支持程度 | 实现机制 | ooo命令支持 | 自动循环 |
|---|---|---|---|---|
| Claude Code | 完全支持 | 技能系统 + 钩子 | 所有 | 通过钩子 |
| Codex CLI | 适配支持 | bash循环 + | 通过会话 | 手动状态文件 |
| Gemini CLI | 原生支持 | AfterAgent钩子 | 所有 | 通过钩子 |
| OpenCode | 原生支持 | 技能系统 | 所有 | 通过循环 |
Installation
安装
bash
undefinedbash
undefinedClaude Code (via oh-my-skills)
Claude Code (通过oh-my-skills)
npx skills add https://github.com/akillness/oh-my-skills --skill ralph-ooo
npx skills add https://github.com/akillness/oh-my-skills --skill ralph-ooo
Codex CLI setup
Codex CLI设置
bash .agent-skills/ralph-ooo/scripts/setup-codex-hook.sh
bash .agent-skills/ralph-ooo/scripts/setup-codex-hook.sh
Gemini CLI setup
Gemini CLI设置
bash .agent-skills/ralph-ooo/scripts/setup-gemini-hook.sh
bash .agent-skills/ralph-ooo/scripts/setup-gemini-hook.sh
Ouroboros native plugin
Ouroboros原生插件
claude plugin marketplace add Q00/ouroboros
claude plugin install ouroboros@ouroboros
ooo setup
---claude plugin marketplace add Q00/ouroboros
claude plugin install ouroboros@ouroboros
ooo setup
---References
参考资料
Detailed documentation in :
references/| File | Contents |
|---|---|
| Full ooo command syntax, parameters, output formats, state schemas |
| All 9 agent profiles, core questions, when to invoke, unstuck guide |
| Per-platform setup, hooks.json, AfterAgent config, Gemini bug workarounds |
Source: Q00/ouroboros — MIT License
references/| 文件 | 内容 |
|---|---|
| 完整ooo命令语法、参数、输出格式、状态Schema |
| 全部9个Agent档案、核心问题、调用时机、解困指南 |
| 各平台设置、hooks.json、AfterAgent配置、Gemini bug workaround |
源码: Q00/ouroboros — MIT License