setup

/ouroboros:setup

Claude Code セッション内で Ouroboros のセットアップをガイドします。

その他のランタイム（Codex、Copilot、OpenCode など）では、代わりに CLI から設定します。たとえば、ouroboros setup --runtime codex または ouroboros setup --runtime copilot を実行します。はじめにを参照してください。

使用方法

ooo setup
/ouroboros:setup
/ouroboros:setup --uninstall

Claude のセットアップでは、ランタイムプロファイル（MCP 1.x 上の Claude Agent SDK）を確認し、必要に応じてプロジェクトの CLAUDE.md に Ouroboros の参照ブロックを追加します。マーケットプレイスのプラグイン設定がこのファイルを管理するため、~/.claude/mcp.json は意図的に変更しません。[claude] と明示的な別名 [claude-sdk] は MCP 1.x を使用します。プラグインは、依存関係のない [claude-cli] ワーカーを使い、別の MCP 2 プロセスで [mcp] を起動します。

セットアップウィザードのフロー

各ステップで別途指定がない限り、現在のランタイムの ask_user 機能を使って質問してください。

Python ランタイム（必須）

以下のスニペットを実行する前に、同じシェル内でこのリゾルバーを定義してください。Python 3.12 以降のみを受け入れ（python3、次に python、最後に uv の順）、引数と標準入力を保持します。ouroboros_python に渡すすべての引数を引用符で囲んでください。

ouroboros_python() {
  if command -v python3 >/dev/null 2>&1 &&
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command python3 -c 'import sys; raise SystemExit(sys.version_info < (3, 12))') >/dev/null 2>&1
  then
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command python3 "$@")
    return
  fi
  if command -v python >/dev/null 2>&1 &&
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command python -c 'import sys; raise SystemExit(sys.version_info < (3, 12))') >/dev/null 2>&1
  then
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command python "$@")
    return
  fi
  if command -v uv >/dev/null 2>&1; then
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command uv run --no-project --quiet --python '>=3.12' python "$@")
    return
  fi
  printf '%s\n' 'Ouroboros skills require Python >= 3.12 or uv on PATH.' >&2
  return 127
}

ステップ 0.5：コミュニティへの支援

~/.ouroboros/prefs.json の star_asked が true でない場合は、「Ouroboros は無料のオープンソースです。GitHub でスターを付けると、ほかの開発者が見つけやすくなります。リポジトリにスターを付けますか？」と尋ね、GitHub でスターを付ける（gh api -X PUT /user/starred/Q00/ouroboros を実行）と今回はスキップを選択肢として提示します。回答後、既存のキーを保持したまま、設定ファイルに star_asked: true をマージします。

ouroboros_python - <<'PY'
import json, os
path = os.path.expanduser('~/.ouroboros/prefs.json')
os.makedirs(os.path.dirname(path), exist_ok=True)
try:
    with open(path, encoding='utf-8') as f:
        prefs = json.load(f)
    if not isinstance(prefs, dict):
        prefs = {}
except Exception:
    prefs = {}
prefs['star_asked'] = True
with open(path, 'w', encoding='utf-8') as f:
    json.dump(prefs, f, indent=2)
    f.write('\n')
PY

ステップ 1：環境の検出

ouroboros_python --version
which uvx 2>/dev/null && uvx --version 2>/dev/null
which claude 2>/dev/null
uv python list 2>/dev/null | grep "cpython-3.1[2-9]"

このリゾルバーはすでに Python 3.12 未満を拒否し、uv で管理されるインタープリターにフォールバックします。ただし、これによって [claude-sdk] と MCP 2 のプロファイルがインポート互換になるわけではありません。検出結果を報告したうえで、次のように対応してください。

環境	対応
Python >= 3.12 + Claude CLI	準備完了：[claude] SDK/MCP 1 とスキルを設定
uvx + Python >= 3.12	ほかの環境では MCP を利用可能：分離された ouroboros-ai[mcp] 用に、サポート対象の CLI ベースのランタイムセットアップを使用
Python < 3.12 のみ	uv python install 3.12 を実行してから、ooo setup を再実行
パッケージランナーも Ouroboros パッケージもない	uv をインストール（以下を参照）してから、ooo setup を再実行

uv のインストールには、パッケージマネージャーを優先してください：pipx install uv、pip install --user uv、または brew install uv。ベンダー提供のワンライナー curl -LsSf https://astral.sh/uv/install.sh | sh は最終手段です。

重要：[mcp,claude]、[mcp,claude-sdk]、または [all,mcp] を同時にインストールしないでください。また、ouroboros や python -m ouroboros を直接使う MCP フォールバックも記述しないでください。MCP 2 のランチャーには、分離された uvx --isolated --python '>=3.12' --from 'ouroboros-ai[mcp]' ... または pipx run --spec 'ouroboros-ai[mcp]' ... プロセスを使用する必要があります。サポートされているのは [mcp,claude-cli] のみです。CLI ワーカーは別プロセスで実行されるためです。~/.claude/mcp.json に Ouroboros のエントリーを記述しないでください。その登録はプラグインが管理します。

ステップ 1.5：ランタイム設定

Claude のランタイム選択を ~/.ouroboros/config.yaml に書き込みます。ウェルカムゲートと CLI がこれを読み取ります。このウィザード内でこれを書き込むのはここだけです。このステップでは ~/.claude/mcp.json には一切触れません。

以下の各コマンドと同じシェルで ouroboros_cli を定義します（シェルの状態はコマンド間で保持されません）。

ouroboros_cli() {
  if command -v ouroboros >/dev/null 2>&1; then
    command ouroboros "$@"
  else
    uvx --isolated --python '>=3.12' --from 'ouroboros-ai' ouroboros "$@"
  fi
}
ouroboros_cli config show orchestrator
ouroboros_cli config show llm

ウェルカムゲートの準備が完了するのは、orchestrator.runtime_backend が claude または claude_mcp で、かつ llm.backend が claude の場合のみです。ファイルまたはセクションが存在しない場合は、未設定として扱います。

• 両方の条件を満たす場合：設定済みです。ステップ 2 に進みます。
• runtime_backend が claude_mcp で、llm.backend が claude ではない場合：ouroboros_cli setup --runtime claude-cli --non-interactive を実行します（CLI トランスポートを維持します）。
• runtime_backend が別のランタイム（たとえば codex）の場合：デフォルトのランタイムを Claude に切り替えるかユーザーに確認します。切り替えない場合は、既存の設定を維持してステップ 2 に進みます。
• それ以外の場合（runtime_backend が別の llm.backend と組み合わせた claude、設定なし、orchestrator セクションなし）、またはユーザーが切り替えに同意した場合は、次を実行します。

ouroboros_cli setup --runtime claude --non-interactive

どちらのセットアップコマンドも llm.backend: claude を設定します。--runtime claude は orchestrator.runtime_backend: claude を設定し、--runtime claude-cli は claude_mcp を設定します。失敗した場合はエラーを表示してウィザードを続行します。ステップ 4 では、ランタイムは未設定として報告されます。

ステップ 2：MCP プロファイルの境界

ユーザーに次のことを伝えます。デフォルトの Claude SDK プロファイルは MCP 1.x のままで、プラグイン所有の MCP サーバーは [claude-cli] ワーカーを使って MCP 2 を別途実行します。**~/.claude/mcp.json の作成、更新、削除は行わないでください。**既存のエントリーはユーザーが管理しているか、別の互換性のあるランタイムに属している可能性があります。高度な MCP ワークフローには、ホストが管理する分離された [mcp] ランチャーが必要です。これは Claude マーケットプレイスプラグインまたは他のサポート対象ホスト設定が所有します。

ステップ 3：CLAUDE.md との統合（任意）

この約 40 行のリファレンスブロック（パイプライン、コマンド表、エージェントカタログ）をプロジェクトの CLAUDE.md に追加するため、統合する / スキップ / 先にプレビューを提示します。先にプレビューを選んだ場合は、次を表示します。

# Ouroboros — Specification-First AI Development

> Before telling AI what to build, define what should be built.
> As Socrates asked 2,500 years ago — "What do you truly know?"
> Ouroboros turns that question into an evolutionary AI workflow engine.

Most AI coding fails at the input, not the output. Ouroboros fixes this by
**exposing hidden assumptions before any code is written**.

1. **Socratic Clarity** — Question until ambiguity ≤ 0.2
2. **Ontological Precision** — Solve the root problem, not symptoms
3. **Evolutionary Loops** — Each evaluation cycle feeds back into better specs

```
Interview → Seed → Execute → Evaluate
    ↑                           ↓
    └─── Evolutionary Loop ─────┘
```

## ooo Commands

Each command loads its agent/MCP on-demand. Details in each skill file.

| Command | Loads |
|---------|-------|
| `ooo` | — |
| `ooo interview` | `ouroboros:socratic-interviewer` |
| `ooo seed` | `ouroboros:seed-architect` |
| `ooo run` | MCP required |
| `ooo evolve` | MCP: `evolve_step` |
| `ooo evaluate` | `ouroboros:evaluator` |
| `ooo unstuck` | `ouroboros:{persona}` |
| `ooo status` | MCP: `session_status` |
| `ooo setup` | — |
| `ooo help` | — |

## Agents

Loaded on-demand — not preloaded.

**Core**: socratic-interviewer, ontologist, seed-architect, evaluator,
advocate, contrarian, judge
**Support**: hacker, simplifier, researcher, architect

統合するを選んだ場合：CLAUDE.md を CLAUDE.md.bak にバックアップし、ブロックを追記して確認します。

ステップ 4：検証

ステップ 1.5 の config show コマンドを使って、保存された Ouroboros 設定が MCP 1.x 上のデフォルトの Claude Agent SDK ランタイムを選択していること、およびこのセットアップで ~/.claude/mcp.json が変更されていないことを確認します。依存関係不要の Claude CLI ワーカーは、分離された MCP 2 プロセス向けの、明示的に選択する [claude-cli] として引き続き利用できます。

ステップ 5：成功の概要

Ouroboros Setup Complete!

Mode:                     Claude Agent SDK (MCP 1.x)
MCP Server:               Host-owned (config not mutated)
CLAUDE.md:                <integrated | skipped>

Next: ooo interview "your project idea" | ooo tutorial | ooo help

ステップ 5.1：モデルの選択（Claude Code）

任意のモデル制御を提示します。「설정이 완료됐어요. 기본 모델 설정으로 바로 시작할 수 있고, 모델은 언제든 나중에 바꿀 수 있어요.」（ヘッダー 모델 설정）と尋ねます。

• 바로 시작하기 (권장)：デフォルトのモデル設定ですぐに作業を開始します。ステップ 5.5 に進みます。
• 직접 모델 설정하기：段階的にモデルを変更するか、一覧にないモデル ID を入力して固定します。../config/SKILL.md を読み、その指示に従います。ローカルの Claude Code ハーネスでは、ユーザーのブラウザーで一時的な localhost アドレスの設定 UI が開きます。いつでも ooo config で再度開けます。この選択によってモデルが永続的に固定されることはありません。

ステップ 5.5：既存リポジトリのスキャン

既存の git リポジトリとリンクされた worktree を Ouroboros DB に登録し、インタビューでそれらを既存コードベースのコンテキストとして利用できるようにします。CLI や Python スクリプトではなく、MCP ツールのみを使用してください。

MCP ツールの読み込み（スキーマ遅延への対処）

Ouroboros のツールは遅延読み込みされる場合があり、あるターンで読み込まれたスキーマが次のターンまでにアンロードされることがあります。各 ouroboros_* 呼び出しの直前に、実行中のランタイムのツール検出機能を使って読み込んでください。ouroboros_brownfield の場合は "+ouroboros brownfield" を指定します（スキャン時と後続の set_defaults 呼び出しの両方）。スキーマが読み込まれていない状態で呼び出すと、「Invalid tool parameters」で失敗します。ツールがすでに呼び出し可能な場合、検出は何も行わず、空の結果が返ることが想定されます。ツールが本当に存在しない場合は、この手順を省略してステップ 6 に進みます。

1. スキャンして登録します：

   Tool: ouroboros_brownfield
   Arguments: { "action": "scan" }
   

   探索は scan_root（デフォルト：ユーザーのホームディレクトリ）から始まり、 最大で 2 ディレクトリ階層まで進みます。ドットで始まるディレクトリや node_modules のような不要なディレクトリはスキップされます。探索で見つかった 通常のリポジトリ（.git ディレクトリ）とリンクされたワークツリー（.git ファイル）は、 それぞれ単独で登録されます。Git ワークツリーのファミリーは展開されません。 リモートがないリポジトリや、リモート名を問わず、対象になります。 既存のデフォルト設定は保持されます。

2. スキャン結果の text には、デフォルトを示すマーカー付きの番号リストがすでに含まれています。リポジトリの一覧表示や問い合わせのために、追加の MCP 呼び出しを行わないでください。 すべてのリポジトリを、コードブロック内のプレーンテキストの 2 列グリッド（Markdown の表ではありません）で表示し、* のデフォルトマーカーは返されたとおりに正確に維持してください：

   Scan complete. 8 repositories registered.
   
    1. repo-alpha                   5. repo-epsilon
    2. repo-bravo *                 6. repo-foxtrot
   

   リポジトリが見つからなかった場合は、ステップ 6 に進みます。

3. この選択に、実行中のランタイムの ask_user ダイアログを使わないでください。 ツール呼び出しの間に出力されたテキストは表示されるとは限らないため、リストが表示されないままダイアログが表示されることがあります。また、選択肢のプレビューでは長いリストが省略されます。代わりに、リポジトリのグリッドを最終メッセージとして表示してターンを終了し、その後に次のプロンプトを続けます：

   • デフォルトがある場合：Current defaults: <names> (numbers <numbers>) と表示してから、 Reply with repo numbers to change defaults (e.g. "6, 18, 19"), "keep" to keep the current defaults, or "none" to clear them.
   • デフォルトがない場合：No defaults set. Reply with repo numbers to set defaults (e.g. "6, 18, 19"), or "none" to run interviews in greenfield mode.

4. 次のターンでは、番号（区切り文字は問いません）で該当する ID を選択します。「keep」の場合は MCP 呼び出しを省略し、デフォルト設定を変更しません。「none」の場合はすべてクリアします。それ以外の入力にはプロンプトを再表示します（決して推測しないでください）。その後、すべてのデフォルトを置き換える呼び出しを 1 回だけ行います（none の場合は "indices": "" を指定します）：

   Tool: ouroboros_brownfield
   Arguments: { "action": "set_defaults", "indices": "<comma-separated IDs>" }
   

   設定後のデフォルトを確認するか、インタビューがグリーンフィールドモードで実行されることを伝えます。また、後から ooo setup または ooo brownfield で変更できることも伝えます。

ステップ 6：最初のプロジェクトへの提案

ooo interview "Build a CLI tool for [something you need]" または ooo tutorial を提案します。

アンインストール

--uninstall が指定された場合は、確認を求めます。その際、CLAUDE.md から Ouroboros ブロックのみを削除し、プラグインファイル、シード、プロジェクトデータは削除しないことを説明します。確認された場合：

1. ~/.claude/mcp.json は変更しません
2. CLAUDE.md に から のブロックが存在する場合は削除します
3. 次のとおり確認します："Ouroboros plugin configuration removed. To remove plugin files, run: claude plugin uninstall ouroboros"

セットアップのトラブルシューティング

• 「No compatible Python found」：PATH に uv があれば、プラグインモードはグローバル Python がなくても動作します。そうでない場合は、Python 3.12 をインストールしてください（brew install [email protected]、sudo apt install python3.12、または python.org/downloads）。
• 「uvx: command not found」：uvx は推奨されていますが、必須ではありません。デフォルトの Claude SDK ランタイムでは、pip install 'ouroboros-ai[claude]' （[claude-sdk] は明示的なエイリアス）を使います。分離された MCP 2 サーバーワーカーでのみ [claude-cli] を使用してください。[claude]、[claude-sdk]、または [all] を [mcp] と組み合わせないでください。

RFC #1392 状態通知フッター

最終回答の末尾を、◆ <current state> → next: <recommended action> の形式の行 1 行だけにしてください。利用可能な場合は ouroboros_session_status で現在のセッション状態を取得し、そうでない場合はこのスキルで実際に得られた結果から状態を判断してください。直線的な Step N of M 形式のフッターは使用しないでください。次のステップが実際の選択肢である場合は、2～3 個の選択肢を列挙してください。