ooo

ooo — Ouroboros 规范优先工作流

别再写提示词，开始编写规范。

ooo 是用于规范优先开发的可移植 Ouroboros 方法。访谈以实时 git 数据为依据，冻结后的种子由 spec-kit 渲染为执行计划，运行阶段则通过 cli-anything 原生支持 Agent 的 harness 执行：

git data (commits · churn · contributors)
        ↓ (regenerated every interview)
Interview → Seed → Plan (spec-kit) → Execute (cli-anything) → Evaluate → Evolve
                     ↓                                            ↑
                 ooo ralph                            --json artifact evidence
             (persist until verified)

三种绑定方式让这一理念落到实处：

1. Git 感知访谈 — 苏格拉底式访谈会根据 .ouroboros/interview-context.md 对棕地项目的 Context 权重进行评分。该文件源自仓库的当前提交记录、变更热点、贡献者和工作树状态，并会重新生成。访谈理念始终与更新后的 git 数据绑定，而非过时的聊天记忆。
2. spec-kit 执行计划 — 种子冻结后，GitHub spec-kit 的 /speckit.plan → /speckit.tasks 会根据种子生成可供审查的执行计划。种子仍是契约 SSOT；spec-kit 仅负责计划产物（方向：种子 → 计划）。
3. cli-anything 执行 harness — 运行阶段通过 CLI-Hub harness（cli-hub search → install → launch）驱动真实软件，而不是使用脆弱的 GUI 自动化或盲目猜测 shell 命令。每条 harness 命令都支持 --json；评估阶段接受这种结构化输出作为产物证据。在种子约束中注明 harness 名称，让工具漂移变得可衡量，从而反映出规范漂移。

安装

插件（推荐用于 Claude Code）

claude plugin marketplace add Q00/ouroboros

pip

pip install ouroboros-ai           # base
pip install 'ouroboros-ai[all]'    # full CLI: Claude SDK, LiteLLM, TUI (MCP SDK 1.x)
pip install 'ouroboros-ai[mcp]'    # MCP server (`ouroboros mcp serve` needs MCP SDK 2)

Skill + 集成（推荐，适用于任何平台）

npx skills add https://github.com/akillness/jeo-skills --skill ooo

# One-shot installer: skill + ouroboros-ai + git interview + spec-kit + cli-anything
bash scripts/install.sh
GLOBAL=1 AGENTS="claude-code,codex" bash scripts/install.sh

# Knobs (designate at install time):
#   OOO_GIT_INTERVIEW=0  — skip git-aware interview wiring   (default: on)
#   OOO_SPEC_KIT=0       — skip spec-kit/`specify-cli`        (default: on)
#   OOO_CLI_ANYTHING=0   — skip cli-anything/CLI-Hub          (default: on)
#   SPEC_KIT_REF=v0.0.10 — pin the spec-kit git ref
#   CLI_ANYTHING_HUB_SPEC="cli-anything-hub==0.2.0" — pin CLI-Hub
#   SKIP_PACKAGE=1 / SKIP_SKILL=1 / OOO_EXTRAS=mcp

设置运行时

ouroboros setup                    # auto-detect Claude / Codex / OpenCode
ouroboros setup --runtime claude
ouroboros setup --runtime codex
ouroboros setup --runtime opencode --opencode-mode plugin

适用场景

• 需求模糊，需要在开始编码前进行苏格拉底式访谈
• 访谈必须以更新后的 git 数据（提交记录、变更、贡献者）为依据，而不是聊天记忆
• 需求应在实施前转化为不可变的种子／规范
• 任务需要一个验证后再完成的循环，而非一次性回答
• 希望持续推进，直到真正验证完成
• 根据原始契约衡量漂移
• 反复失败时，需要结构化的脱困步骤，而非盲目重试
• 冻结的种子应在实施前转化为可供审查的 spec-kit 执行计划
• 执行必须通过原生支持 Agent 的 CLI harness 驱动真实软件，并提供 --json 产物证据

不适用场景

• 任务主要是平台设置或运行时命令 → oh-my-claudecode / oh-my-codex / oh-my-agent
• 任务主要涉及权限设置、沙箱、信任文件夹 →（通过 ouroboros setup 配置）
• 任务需要集成的项目台账 + 计划审查 + 清理工作流 → jeo
• 任务仅涉及实施前的全景调研 → survey
• 需要 spec-kit 编写规范本身（方向为规范 → 种子，文档作为 SSOT）→ 直接使用 spec-kit，然后将冻结的规范带回此处
• 仅需安装或生成 CLI harness，不需要种子／循环 → cli-anything

核心命令

访谈 — 编码前先澄清

ouroboros init start "build a task management CLI"
ouroboros init start --resume <interview-id>
ouroboros init list

Git 感知上下文（棕地项目） — 每次访谈前都要重新生成，让 Context 评分反映仓库的当前状态：

bash scripts/git-interview-context.sh        # → .ouroboros/interview-context.md
OOO_GIT_WINDOW=30 OOO_GIT_TOP=10 bash scripts/git-interview-context.sh

生成的文件包含分支／HEAD、近期提交、变更热点、活跃贡献者和工作树状态。该文件是派生文件，应重新生成，切勿手动编辑。变更热点会成为访谈问题；工作树有未提交变更时，应提出问题，而不是擅自假设。

歧义门槛

• 绿地项目：目标 40% + 约束 30% + 成功标准 30%
• 棕地项目：目标 35% + 约束 25% + 成功标准 25% + Context 15% — 根据 .ouroboros/interview-context.md（实时 git 数据）评估 Context
• 在进入种子阶段之前，歧义度 ≤ 0.2

种子 — 冻结规范

访谈完成后，会在 .ouroboros/seeds/ 中生成 seed.yaml。

# example 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"

计划 — 渲染执行计划（spec-kit）

启用 OOO_SPEC_KIT=1（安装器默认值）后，冻结的种子会在循环开始前渲染为可供审查的执行计划：

specify init . --integration claude    # once per repo (or codex/gemini/...)
# then, inside the agent, from the frozen seed:
#   /speckit.plan   — technical strategy derived from seed goal + constraints
#   /speckit.tasks  — actionable task breakdown for the run stage

计划阶段规则：

• 方向是单向的：种子 → 计划。 种子始终是契约 SSOT；plan.md/tasks.md 是派生工件。如果需求发生变化，请先重新访谈并重新冻结种子，然后再重新渲染计划。
• /speckit.implement 是每项任务的可选辅助功能 — 完成与否仍由 ooo evaluate 循环决定，而不是任务复选框。
• 想要反向流程（由 spec-kit 编写规范，文档作为 SSOT）？这属于 spec-kit 编写规范的范畴，不属于此技能。

运行 — 根据种子执行

ouroboros run workflow <seed.yaml>
ouroboros run workflow <seed.yaml> --sequential
ouroboros run workflow <seed.yaml> --no-qa
ouroboros run resume [execution-id]

由 Harness 驱动的执行（cli-anything） — 启用 OOO_CLI_ANYTHING=1 （安装器默认值）后，运行阶段会通过适用于 Agent 的 CLI harness 驱动真实软件，而非使用 GUI 自动化或仅凭猜测执行 shell 命令：

cli-hub search <keyword>      # registry first — 40+ harnesses exist
cli-hub install <name>        # install harness (+ the upstream app)
cli-anything-<name> --json …  # structured output = evaluate-stage evidence

执行阶段规则：

• 先查注册表，再生成 — cli-hub search 只需几秒；仅当没有匹配项时，才生成新的 harness（/cli-anything <path-or-repo>）。
• 在种子约束中指定 harness 名称（例如“图像操作通过 cli-anything-gimp 执行”），这样工具偏移就能成为可衡量的规范偏移。
• --json 输出是 evaluate 阶段认可的证据 — 验证工件（魔数、结构、像素），不要只看退出代码。

选项

标记	用途
-o/-O	启用/禁用编排器（默认：开启）
--runtime	覆盖运行时后端
-s	按顺序执行验收标准
-n	试运行：验证但不执行
--no-qa	跳过执行后的 QA 评估

评估 — 完成前验证

三阶段关卡：

1. 机械检查 — lint、测试、构建、类型检查、覆盖率
2. 语义检查 — 验收标准与目标一致性
3. 共识检查 — 可选的多模型一致性审查

ouroboros status executions
ouroboros status execution <execution-id> --events

偏移阈值

范围	状态
0.00–0.15	优秀
0.15–0.30	可接受 — 密切关注
0.30+	继续前纠正方向

Ralph — 持续完成循环

# keyword: ooo ralph
ouroboros run workflow seed.yaml     # run → verify → adjust → repeat
ouroboros run resume                 # resume last paused execution

循环约定：

1. 执行
2. 验证（机械检查 + 语义检查）
3. 记录失败证据
4. 调整
5. 继续，直到验证通过或达到上限

演进 — 持续改进

当本体或解决方案形态仍在变化时运行。

ouroboros run workflow seed.yaml    # evolve loop runs automatically

停止条件：收敛相似度 ≥ 0.95

取消

ouroboros cancel execution <id>
ouroboros cancel execution --all
ouroboros cancel execution --reason "requirements changed"

配置

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

状态与 TUI

ouroboros status health
ouroboros status executions -n 20
ouroboros tui monitor              # Textual TUI (Python)
ouroboros tui monitor --backend slt  # native Rust TUI

TUI 键盘快捷键

按键	屏幕
1	仪表板 — 阶段进度、偏移仪表、成本
2	执行 — 详情、时间线、阶段输出
3	日志 — 可筛选的日志查看器
4	调试 — 状态检查器、原始事件
s	会话选择器
e	谱系视图
p/r	暂停 / 恢复
q	退出

脱困模式

多次尝试失败时，请选择有明确目标的角色，而不是盲目重试。

角色	适用情况
contrarian	多次出现类似失败
simplifier	选项过多 / 犹豫不决
researcher	缺少证据
hacker	需要推进势头
architect	基础方向错误

Agent 池中有九个 Agent：苏格拉底式访谈员、本体论专家、种子架构师、种子定稿员、语义评估员、共识审查员、评估员、QA 评审员，以及面向特定领域的专家。

MCP 服务

ouroboros mcp serve                           # stdio transport (default); needs the [mcp] extra
ouroboros mcp serve --transport sse --port 8080
ouroboros mcp info

# Claude Code integration, registered as `ooo` like setup-all-skills-prompt.md does
# (skip it if an `ooo` or `ouroboros` server already exists). --isolated keeps uvx from
# reusing an installed ouroboros-ai tool environment such as [all], which pins MCP SDK 1.x.
claude mcp add ooo -s user -- uvx --isolated --from 'ouroboros-ai[mcp]' ouroboros mcp serve

可用的 MCP 工具

• ouroboros_execute_seed — 执行种子规范
• ouroboros_session_status — 获取会话状态
• ouroboros_query_events — 查询事件历史

环境变量

变量	用途
ANTHROPIC_API_KEY	Claude 后端
OPENAI_API_KEY	LiteLLM / Codex
OPENROUTER_API_KEY	OpenRouter
OUROBOROS_AGENT_RUNTIME	覆盖运行时
OUROBOROS_LLM_BACKEND	覆盖 LLM 后端
OUROBOROS_AGENT_PERMISSION_MODE	权限模式

配置文件

文件	位置
config.yaml	~/.ouroboros/
credentials.yaml	~/.ouroboros/（chmod 600）
ouroboros.db	~/.ouroboros/ — SQLite 事件存储
ouroboros.log	~/.ouroboros/logs/

操作规则

1. 编码前先澄清 — 在歧义 ≤ 0.2 之前，不要进入 seed 阶段
2. 以实时 git 数据为访谈依据 — 每次访谈前重新生成 .ouroboros/interview-context.md；变更热点和工作树状态都应作为问题，而非假设
3. 冻结 seed — 不要在运行过程中重写契约
4. 根据 seed 单向制定计划 — spec-kit 根据冻结的 seed 生成 plan.md/tasks.md；需求变更应先更新 seed，再重新生成
5. 根据原始 seed 衡量偏差，而不是依据最新的聊天理由
6. 完成前验证 — 测试、检查和验收标准比信心更重要
7. 将失败视为数据 — 每次失败的循环都为下一次尝试提供依据
8. 通过约定的执行框架执行 — 先查注册表 （cli-hub search），在 seed 约束中指定执行框架，并将执行框架的 --json 输出作为评估阶段的证据
9. 保持运行时归属分离 — 平台钩子应归属 oh-my-claudecode / oh-my-codex / oh-my-agent

示例

# Full spec-first flow (git interview → seed → spec-kit plan → harness run)
bash scripts/git-interview-context.sh          # refresh live git context
ouroboros init start "build a REST API with auth"
# after seed freeze: /speckit.plan → /speckit.tasks (spec-kit, from the seed)
cli-hub search api && cli-hub install <name>   # arm execute-stage harnesses
ouroboros run workflow .ouroboros/seeds/seed_<hash>.yaml
ouroboros status executions

# Persistent verified loop (ooo ralph)
ouroboros run workflow seed.yaml
ouroboros run resume

# Monitor progress
ouroboros tui monitor

# Uninstall
ouroboros uninstall --keep-data

来源：Q00/ouroboros v0.29.0 — MIT License