ooo

ooo — Ouroboros 仕様ファーストワークフロー

プロンプトをやめて、仕様を書き始めましょう。

ooo は、仕様ファースト開発のためのポータブルな Ouroboros メソッドです。 インタビューはライブの git データに基づき、凍結したシードは spec-kitによって実行計画に変換され、実行ステージでは cli-anythingのエージェントネイティブなハーネスを通じて実行されます。

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)

この理念を具体化するのは、次の 3 つのバインディングです。

1. Git 対応インタビュー — ソクラテス式インタビューでは、リポジトリの現在のコミット、変更頻度の高い箇所、コントリビューター、作業ツリーの状態から再生成される派生ファイル .ouroboros/interview-context.md に照らして、ブラウンフィールドのコンテキストの重み付けを評価します。インタビューの理念は、古いチャットの記憶ではなく、更新された git データに常に結び付けられます。
2. spec-kit による実行計画 — シードを凍結した後、GitHub spec-kit の /speckit.plan → /speckit.tasks により、シードからレビュー可能な実行計画を生成します。シードが契約の SSOT であり続け、spec-kit が所有するのは計画アーティファクトのみです（方向：シード → 計画）。
3. cli-anything の実行ハーネス — 実行ステージでは、脆弱な GUI 自動化や推測に頼ったシェル操作ではなく、CLI-Hub ハーネス（cli-hub search → install → launch）を通じて実際のソフトウェアを操作します。すべてのハーネスコマンドは --json に対応しており、構造化された出力は評価ステージで受け入れられるアーティファクトの証拠になります。シードの制約にハーネスの名前を指定することで、ツールの変化を仕様のずれとして測定可能にします。

インストール

プラグイン（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)

スキル + インテグレーション（任意のプラットフォームに推奨）

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 実行計画にする必要がある
• --json によるアーティファクトの証拠を伴うエージェントネイティブな CLI ハーネスを通じて、実際のソフトウェアを操作する必要がある

使用しない場面

• 主な作業がプラットフォームのセットアップやランタイムコマンドである → oh-my-claudecode / oh-my-codex / oh-my-agent
• 主な作業が権限設定、サンドボックス、信頼するフォルダーである →（ouroboros setup で設定）
• プロジェクト台帳、計画レビュー、クリーンアップのワークフローを統合する必要がある → jeo
• 実装前の全体調査のみが必要である → survey
• spec-kit に仕様自体を作成させる必要がある（仕様 → シードの方向、ドキュメントを SSOT とする）→ spec-kit を直接使用し、その後、凍結した仕様をここに持ち込む
• シードやループを伴わず、CLI ハーネスのインストールまたは生成のみを行う → 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% + コンテキスト 15% — Context は .ouroboros/interview-context.md（ライブの git データ）に照らして評価します
• 曖昧さ ≤ 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"

Plan — 実行計画をレンダリングする（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 の作成領域です。

Run — シードに基づいて実行する

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

ハーネス主導の実行（cli-anything） — OOO_CLI_ANYTHING=1 （インストーラーのデフォルト）の場合、実行ステージでは、GUI の自動化や素のシェルでの推測ではなく、エージェントネイティブな CLI ハーネスを通じて実際のソフトウェアを操作します。

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 は数秒で完了します。一致するものがない場合に限り、新しいハーネス（/cli-anything <path-or-repo>）を生成します。
• シードの制約にハーネス名を記載します（例：「画像操作には cli-anything-gimp を使用する」）。これにより、ツールの逸脱を測定可能な仕様の逸脱として検出できます。
• --json の出力は、評価ステージが受け入れる証拠です。終了コードではなく、成果物（マジックバイト、構造、ピクセル）を検証します。

オプション

フラグ	用途
-o/-O	オーケストレーターを有効化／無効化（デフォルト：有効）
--runtime	ランタイムバックエンドを上書き
-s	受け入れ基準を順番に実行
-n	ドライラン：実行せずに検証
--no-qa	実行後の QA 評価をスキップ

Evaluate — 完了前に検証する

3 段階のゲート：

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. 検証が完了するか、上限に達するまで続行

Evolve — 継続的な改善

オントロジーまたはソリューションの形がまだ変化している場合に実行します。

ouroboros run workflow seed.yaml    # evolve loop runs automatically

停止条件：収束類似度 ≥ 0.95

Cancel

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

Config

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

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	基盤が間違っている場合

プールには 9 つのエージェントがあります：Socratic Interviewer、Ontologist、Seed Architect、Seed Closer、Semantic Evaluator、Consensus Reviewer、Evaluator、QA Judge、およびドメイン固有のスペシャリストです。

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 出力を evaluate ステージの証拠として扱う
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 ライセンス