Back to Details

ooo

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ooo — Ouroboros Specification-First Workflow

ooo — Ouroboros规范优先开发工作流

Stop prompting. Start specifying.
ooo
is the portable Ouroboros method for spec-first development:
text
Interview → Seed → Execute → Evaluate → Evolve
                     ↓
                 ooo ralph
             (persist until verified)
停止零散提示，开始规范定义。
ooo
是用于规范优先开发的可移植Ouroboros方法：
text
访谈 → 种子规范 → 执行 → 评估 → 迭代
                     ↓
                 ooo ralph
             (持续循环直至验证通过)

Installation

安装方式

Plugin (recommended for Claude Code)

插件（推荐用于Claude Code）

bash
claude plugin marketplace add Q00/ouroboros
bash
claude plugin marketplace add Q00/ouroboros

pip

pip安装

bash
pip install ouroboros-ai           # base
pip install ouroboros-ai[all]      # full: Claude, LiteLLM, MCP, TUI
bash
pip install ouroboros-ai           # 基础版
pip install ouroboros-ai[all]      # 完整版：包含Claude、LiteLLM、MCP、TUI

Skill (any platform)

Skill安装（支持任意平台）

bash
npx skills add https://github.com/akillness/oh-my-skills --skill ooo
bash
npx skills add https://github.com/akillness/oh-my-skills --skill ooo

Setup runtimes

运行时配置

bash
ouroboros setup                    # auto-detect Claude / Codex / OpenCode
ouroboros setup --runtime claude
ouroboros setup --runtime codex
ouroboros setup --runtime opencode --opencode-mode plugin
bash
ouroboros setup                    # 自动检测Claude / Codex / OpenCode
ouroboros setup --runtime claude
ouroboros setup --runtime codex
ouroboros setup --runtime opencode --opencode-mode plugin

When to use

适用场景

  • Vague request needs a Socratic interview before coding starts
  • Requirements should become an immutable seed/spec before implementation
  • Task needs a verify-before-done loop, not a one-shot answer
  • You want to keep going until completion is actually verified
  • Measure drift against the original contract
  • Repeated failures need structured unstuck step instead of blind retries
  • 需求模糊，需要在编码前进行苏格拉底式访谈
  • 需求需要在实现前固化为不可变的种子/规范
  • 任务需要验证通过再结束的循环，而非一次性输出结果
  • 需要持续循环直至完成状态被实际验证
  • 测量与原始契约的偏差
  • 重复失败时需要结构化的“脱困”步骤，而非盲目重试

Do not use when

不适用场景

  • Task is mainly platform setup or runtime commands → 
    omc
    / 
    omx
    / 
    ohmg
  • Task is mainly permission posture, sandbox, trust folders → (configure via 
    ouroboros setup
    )
  • Task needs integrated project ledgers + plan review + cleanup workflow → 
    jeo
  • Task is only pre-implementation landscape research → 
    survey
  • 任务以平台配置或运行时命令为主 → 使用
    omc
    / 
    omx
    / 
    ohmg
  • 任务以权限设置、沙箱、信任文件夹为主 →（通过
    ouroboros setup
    配置）
  • 任务需要集成项目台账+计划评审+清理工作流 → 使用
    jeo
  • 任务仅为实现前的技术调研 → 使用
    survey

Core commands

核心命令

Interview — clarify before coding

访谈 — 编码前澄清需求

bash
ouroboros init start "build a task management CLI"
ouroboros init start --resume <interview-id>
ouroboros init list
Ambiguity gate
  • Greenfield: Goal 40% + Constraints 30% + Success 30%
  • Brownfield: Goal 35% + Constraints 25% + Success 25% + Context 15%
  • Do not move to seed until Ambiguity ≤ 0.2
bash
ouroboros init start "构建任务管理CLI"
ouroboros init start --resume <访谈ID>
ouroboros init list
歧义门槛
  • 全新项目：目标40% + 约束30% + 验收标准30%
  • 存量项目：目标35% + 约束25% + 验收标准25% + 上下文15%
  • 只有当歧义值 ≤ 0.2时，才能进入种子规范阶段

Seed — freeze the spec

种子规范 — 固化需求

After interview completes, a 
seed.yaml
is generated in 
.ouroboros/seeds/
.
yaml
undefined
访谈完成后，会在
.ouroboros/seeds/
目录生成
seed.yaml
文件。
yaml
undefined

example seed.yaml

示例seed.yaml

goal: "Build a CLI task manager with SQLite persistence" constraints:
  • "Python 3.12+"
  • "No external HTTP dependencies" acceptance_criteria:
  • "CRUD operations work end-to-end"
  • "All unit tests pass"
undefined
goal: "构建基于SQLite持久化的CLI任务管理器" constraints:
  • "Python 3.12+"
  • "无外部HTTP依赖" acceptance_criteria:
  • "CRUD操作端到端可用"
  • "所有单元测试通过"
undefined

Run — execute against the seed

运行 — 依据种子规范执行

bash
ouroboros run workflow <seed.yaml>
ouroboros run workflow <seed.yaml> --sequential
ouroboros run workflow <seed.yaml> --no-qa
ouroboros run resume [execution-id]
Options
FlagPurpose
-o/-O
Enable/disable orchestrator (default: on)
--runtime
Override runtime backend
-s
Execute acceptance criteria sequentially
-n
Dry-run: validate without executing
--no-qa
Skip post-execution QA evaluation
bash
ouroboros run workflow <seed.yaml>
ouroboros run workflow <seed.yaml> --sequential
ouroboros run workflow <seed.yaml> --no-qa
ouroboros run resume [执行ID]
可选参数
参数用途
-o/-O
启用/禁用编排器（默认：启用）
--runtime
覆盖默认运行时后端
-s
按顺序执行验收标准
-n
试运行：仅验证不执行
--no-qa
跳过执行后的QA评估

Evaluate — verify before done

评估 — 验证通过再结束

Three-stage gate:
  1. Mechanical — lint, tests, build, typecheck, coverage
  2. Semantic — acceptance criteria and goal alignment
  3. Consensus — optional multi-model agreement
bash
ouroboros status executions
ouroboros status execution <execution-id> --events
Drift thresholds
RangeStatus
0.00–0.15Excellent
0.15–0.30Acceptable — watch closely
0.30+Correct course before continuing
三阶段验证：
  1. 机械验证 — 代码检查、测试、构建、类型校验、覆盖率
  2. 语义验证 — 验收标准与目标一致性
  3. 共识验证 — 可选的多模型一致性确认
bash
ouroboros status executions
ouroboros status execution <执行ID> --events
偏差阈值
范围状态
0.00–0.15优秀
0.15–0.30可接受 — 需密切关注
0.30+调整方向后再继续

Ralph — persistent completion loop

Ralph — 持续完成循环

bash
undefined
bash
undefined

keyword: ooo ralph

关键词: ooo ralph

ouroboros run workflow seed.yaml # run → verify → adjust → repeat ouroboros run resume # resume last paused execution

Loop contract:
1. execute
2. verify (mechanical + semantic)
3. record failure evidence
4. adjust
5. continue until verified or capped
ouroboros run workflow seed.yaml # 运行 → 验证 → 调整 → 重复 ouroboros run resume # 恢复上次暂停的执行

循环契约：
1. 执行
2. 验证（机械+语义）
3. 记录失败证据
4. 调整
5. 持续循环直至验证通过或达到上限

Evolve — continuous refinement

迭代 — 持续优化

Runs when the ontology or solution shape is still changing.
bash
ouroboros run workflow seed.yaml    # evolve loop runs automatically
Stop condition: convergence similarity ≥ 0.95
适用于本体或解决方案形态仍在变化的场景。
bash
ouroboros run workflow seed.yaml    # 迭代循环自动运行
停止条件：收敛相似度 ≥ 0.95

Cancel

取消执行

bash
ouroboros cancel execution <id>
ouroboros cancel execution --all
ouroboros cancel execution --reason "requirements changed"
bash
ouroboros cancel execution <ID>
ouroboros cancel execution --all
ouroboros cancel execution --reason "需求变更"

Config

配置管理

bash
ouroboros config show
ouroboros config show orchestrator
ouroboros config backend claude
ouroboros config backend codex
ouroboros config set orchestrator.permission_mode allowedTools
ouroboros config validate
bash
ouroboros config show
ouroboros config show orchestrator
ouroboros config backend claude
ouroboros config backend codex
ouroboros config set orchestrator.permission_mode allowedTools
ouroboros config validate

Status & TUI

状态查看与TUI

bash
ouroboros status health
ouroboros status executions -n 20
ouroboros tui monitor              # Textual TUI (Python)
ouroboros tui monitor --backend slt  # native Rust TUI
TUI keyboard shortcuts
KeyScreen
1
Dashboard — phase progress, drift meter, cost
2
Execution — details, timeline, phase outputs
3
Logs — filterable log viewer
4
Debug — state inspector, raw events
s
Session selector
e
Lineage view
p/r
Pause / resume
q
Quit
bash
ouroboros status health
ouroboros status executions -n 20
ouroboros tui monitor              # Python文本界面(TUI)
ouroboros tui monitor --backend slt  # Rust原生TUI
TUI快捷键
按键界面
1
仪表盘 — 阶段进度、偏差计量、成本
2
执行详情 — 细节、时间线、阶段输出
3
日志 — 可过滤的日志查看器
4
调试 — 状态检查器、原始事件
s
会话选择器
e
lineage视图
p/r
暂停 / 恢复
q
退出

Unstuck mode

脱困模式

When repeated attempts fail, choose a deliberate persona instead of retrying blindly.
PersonaWhen
contrarian
Repeated similar failures
simplifier
Too many options / paralysis
researcher
Missing evidence
hacker
Need momentum
architect
Wrong foundation
Nine agents in the pool: Socratic Interviewer, Ontologist, Seed Architect, Seed Closer, Semantic Evaluator, Consensus Reviewer, Evaluator, QA Judge, plus domain-specific specialists.
当重复尝试失败时，选择特定角色而非盲目重试。
角色适用场景
contrarian
重复出现相似失败
simplifier
选项过多导致决策瘫痪
researcher
缺少关键证据
hacker
需要快速推进获得动力
architect
基础架构存在问题
内置9个Agent：苏格拉底访谈者、本体论者、种子架构师、种子固化师、语义评估师、共识评审员、评估师、QA裁判，以及领域专家。

MCP server

MCP服务器

bash
ouroboros mcp serve                           # stdio transport (default)
ouroboros mcp serve --transport sse --port 8080
ouroboros mcp info
bash
ouroboros mcp serve                           # 标准输入输出传输（默认）
ouroboros mcp serve --transport sse --port 8080
ouroboros mcp info

Claude Desktop integration

Claude Desktop集成

claude mcp add ouroboros -- uvx --from ouroboros-ai[mcp] ouroboros mcp serve

**Available MCP tools**
- `ouroboros_execute_seed` — execute a seed specification
- `ouroboros_session_status` — get session status
- `ouroboros_query_events` — query event history
claude mcp add ouroboros -- uvx --from ouroboros-ai[mcp] ouroboros mcp serve

**可用MCP工具**
- `ouroboros_execute_seed` — 执行种子规范
- `ouroboros_session_status` — 获取会话状态
- `ouroboros_query_events` — 查询事件历史

Environment variables

环境变量

VariablePurpose
ANTHROPIC_API_KEY
Claude backend
OPENAI_API_KEY
LiteLLM / Codex
OPENROUTER_API_KEY
OpenRouter
OUROBOROS_AGENT_RUNTIME
Override runtime
OUROBOROS_LLM_BACKEND
Override LLM backend
OUROBOROS_AGENT_PERMISSION_MODE
Permission mode
变量用途
ANTHROPIC_API_KEY
Claude后端密钥
OPENAI_API_KEY
LiteLLM / Codex密钥
OPENROUTER_API_KEY
OpenRouter密钥
OUROBOROS_AGENT_RUNTIME
覆盖默认运行时
OUROBOROS_LLM_BACKEND
覆盖默认LLM后端
OUROBOROS_AGENT_PERMISSION_MODE
权限模式

Configuration files

配置文件

FileLocation
config.yaml
~/.ouroboros/
credentials.yaml
~/.ouroboros/
(chmod 600)
ouroboros.db
~/.ouroboros/
— SQLite event store
ouroboros.log
~/.ouroboros/logs/
文件位置
config.yaml
~/.ouroboros/
credentials.yaml
~/.ouroboros/
(需设置权限chmod 600)
ouroboros.db
~/.ouroboros/
— SQLite事件存储
ouroboros.log
~/.ouroboros/logs/

Operating rules

操作规则

  1. Clarify before coding — do not move to seed until ambiguity ≤ 0.2
  2. Freeze the seed — do not rewrite the contract mid-run
  3. Measure drift against the original seed, not latest chat rationale
  4. Verify before done — tests, checks, and acceptance criteria matter more than confidence
  5. Treat failure as data — every failed loop feeds the next attempt
  6. Keep runtime ownership separate — platform hooks belong in 
    omc
    / 
    omx
    / 
    ohmg
  1. 编码前先澄清 — 只有当歧义值 ≤ 0.2时，才能进入种子规范阶段
  2. 固化种子规范 — 执行过程中不得修改契约
  3. 测量与原始种子的偏差 — 而非基于最新聊天记录
  4. 验证通过再结束 — 测试、检查和验收标准比主观信心更重要
  5. 将失败视为数据 — 每次失败都为下一次尝试提供参考
  6. 独立管理运行时 — 平台钩子应放在
    omc
    / 
    omx
    / 
    ohmg
    中

Examples

使用示例

bash
undefined
bash
undefined

Full spec-first flow

完整规范优先流程

ouroboros init start "build a REST API with auth" ouroboros run workflow .ouroboros/seeds/seed_<hash>.yaml ouroboros status executions
ouroboros init start "构建带认证的REST API" ouroboros run workflow .ouroboros/seeds/seed_<hash>.yaml ouroboros status executions

Persistent verified loop (ooo ralph)

持续验证循环（ooo ralph）

ouroboros run workflow seed.yaml ouroboros run resume
ouroboros run workflow seed.yaml ouroboros run resume

Monitor progress

监控进度

ouroboros tui monitor
ouroboros tui monitor

Uninstall

卸载

ouroboros uninstall --keep-data

Source: [Q00/ouroboros v0.29.0](https://github.com/Q00/ouroboros/tree/v0.29.0) — MIT License
ouroboros uninstall --keep-data

来源: [Q00/ouroboros v0.29.0](https://github.com/Q00/ouroboros/tree/v0.29.0) — MIT许可协议