setup-opencode-ralph-rlm

OpenCode Ralph RLM のセットアップ

このスキルは、Ralph RLM を対象リポジトリにインストールし、OpenCode から ralph-rlm/supervisor モデルとして使えるようにするためのものです。

ワークフロー

1. 対象リポジトリを調査します。

   • 作業ディレクトリがプロジェクトルートであることを確認します。
   • ロックファイルと package.json の scripts から、パッケージマネージャーとテストコマンドを特定します。
   • 既存の opencode.json、.opencode/ralph.json、.opencode/plugins/ があるか確認します。
   • リポジトリにすでに OpenCode または Ralph の設定がある場合は、編集する前に references/config-files.md を読んでください。

2. プロジェクトが dev 依存関係を受け入れられる場合は、Ralph パッケージをインストールします。

   • リポジトリですでに使用されているパッケージマネージャーを優先してください。
   • パッケージ名: @doeixd/opencode-ralph-rlm。
   • ユーザーが一度きりのセットアップのみを希望する場合は、代わりに npx @doeixd/opencode-ralph-rlm setup を使用してください。
   • エンドユーザーに Bun を要求しないでください。公開されている CLI は Node バイナリです。

3. プロジェクトルートからセットアップを実行します。

   npx @doeixd/opencode-ralph-rlm setup --worktree .
   

   リポジトリにすでに OpenCode の設定がある場合は、まず --dry-run を使用してください。--force は、ユーザーが生成された Ralph ファイルの上書きを明示的に希望する場合にのみ使用してください。 コマンドフラグと想定される出力については、references/cli.md を参照してください。

4. 生成されたファイルを確認します。

   • .opencode/plugins/ralph-worker.ts は @doeixd/opencode-ralph-rlm/worker-plugin を再エクスポートする必要があります。
   • .opencode/plugins/ralph-session-bridge.ts は x-opencode-session-id と directory を挿入する必要があります。
   • .opencode/plugins/ralph-autostart.ts は、OpenCode の読み込み時にプロバイダーを自動的に起動します (ユーザーが手動で serve を実行する必要はありません)。setup --no-autostart を使用した場合はスキップされます。実行時に無効化するには RALPH_AUTOSTART=0 を設定します。
   • .opencode/ralph.json には、現実的な verify.command が含まれている必要があります。
   • .opencode/ralph.json には plans: { dir: ".ralph-rlm/plans", active: "default" } が含まれます — これは名前付きプランのレイアウトです。プロトコルファイル (PLAN.md、RLM_INSTRUCTIONS.md、…) はリポジトリルートではなく、.ralph-rlm/plans/<name>/ の下に配置されます。opencode-ralph-rlm plan-path は、アクティブなプランの PLAN.md の場所を出力します。
   • .opencode/ralph.json には fff.enabled と fff.scanTimeoutMs が含まれる場合があります。プロジェクトがオプションのネイティブ依存関係を読み込めない場合を除き、デフォルトのままにしてください。
   • opencode.json は既存のプロバイダーを保持し、provider["ralph-rlm"] を含める必要があります。

5. 自動検出の推測が不適切だった場合は、verify.command を調整します。

   • Bun プロジェクトでは通常、["bun", "run", "test"] または ["bun", "run", "verify"] を使用します。
   • npm プロジェクトでは通常、["npm", "test"] を使用します。
   • Rust プロジェクトでは通常、["cargo", "test"] を使用します。
   • Python プロジェクトでは通常、["python", "-m", "pytest"] を使用します。

6. プロジェクトのエージェント指示に Ralph のガイダンスを追加するかどうかを確認します。

   • .opencode/ralph.json の agentMdPath、次に AGENT.md、次に AGENTS.md を探します。
   • ガイダンスファイルを作成または編集する前に、ユーザーに確認してください。
   • 同意した場合は、短い Ralph セクションを追記します。文言については references/agent-guidance.md を使用してください。

7. 診断を実行します。

   npx @doeixd/opencode-ralph-rlm doctor --worktree .
   

   プロバイダーが実行されるまでは、プロバイダーの警告が表示されるのは想定内です。 失敗した場合は、references/troubleshooting.md を読んでください。

8. モデルをセットアップします — まずユーザーがすでに持っているものを検出してください。使用可能なものが見つからない場合にのみ確認してください。

   モデルの決定事項は 2 つあります:

   • スーパーバイザー — プロバイダーがオーケストレーション (プランニングインタビュー、ツールルーティング、ステータス) のために呼び出す LLM。信頼性の高い関数呼び出し/ツール呼び出しが必要です。
   • ワーカー — 生成された OpenCode セッションがコードを書くために使用するモデル。ワーカーは OpenCode を 通して 実行されるため、すでに OpenCode のプロバイダー/認証を使用します。

   何かを設定する前に、既存の認証情報/モデルを検出してください:

   • opencode auth list — どのプロバイダーが認証済みか。
   • opencode models — 利用可能なモデル ID (例: opencode/deepseek-v4-flash-free、anthropic/claude-*)。 スーパーバイザー: ユーザーが OpenCode でキー設定済みのプロバイダー（例: Google、OpenCode Zen）を認証している場合、プロバイダーはそれを自動検出します — 別途キーは不要です。そのため通常ここで行うことはありません。ユーザーが特定のプロバイダー/モデルを希望する場合、またはキー設定済みのプロバイダーが認証されていない場合にのみ、RALPH_SUPERVISOR_API_KEY（+ RALPH_SUPERVISOR_MODEL / RALPH_SUPERVISOR_BASE_URL）または .opencode/ralph-provider.json の supervisor を設定してください。

   ワーカー: 未設定のままで問題ありません — ワーカーは OpenCode に設定されたデフォルトモデルを使用します。無料モデルでコーディングを実行するには、.opencode/ralph-provider.json の worker.providerID + worker.modelID を opencode / deepseek-v4-flash-free などの無料の OpenCode モデルに設定することを推奨します（強制はしないでください）。書き込む前にユーザーに確認してください。

   使用可能なものが見つからない場合（認証済みプロバイダーもキーもない場合）: 起動前にユーザーへ認証するよう案内してください。例えば:

   opencode auth login
   

   または RALPH_SUPERVISOR_API_KEY を設定してください。少なくとも 1 つの認証情報の経路が存在するまで、スーパーバイザーが動作することを期待してプロバイダーを起動しないでください。詳しくは references/config-files.md を参照してください。

9. OpenCode を再度開く — プロバイダーは自動起動します。その後、スーパーバイザーが準備完了であることを確認してください。

   • 自動起動プラグインがインストールされている場合（デフォルト）、プロバイダーは OpenCode の読み込み時に自動的に起動します — 手動での serve は不要です。OpenCode はプロバイダーとプラグインを起動時に読み込むため、ralph-rlm/supervisor モデル + プラグインを有効にするには OpenCode TUI を終了して再度開いてください。
   • 準備完了の確認: curl http://127.0.0.1:8787/api/health — supervisor.ready が true になっているはずです（解決された model、source（例: opencode-auth:google）、プロバイダーの version が表示されます）。到達できない場合、プロバイダーがまだ起動中である（少し待ってください）か、自動起動が無効になっている可能性があります — その場合は手動で起動してください:

     npx @doeixd/opencode-ralph-rlm serve --worktree .
     

   • Ralph をちょうど更新した場合、 新しいバージョンが読み込まれるように再起動してください。プロバイダーは冪等です（ポートごとに 1 インスタンス、再利用されます）。また serve の事前チェックは重複した起動を拒否します — 異なるバージョンの既存プロバイダーが報告された場合は、先に古いものを停止してください。
   • その後、ralph-rlm/supervisor モデルを選択してください。

10. 最初のループの前に計画を立てることを提案してください。

• ループは PLAN.md の質を超えることはできません。一行の目標をぶっつけで委任するのではなく、スーパーバイザーとともに目標を計画する（start_loop の前にインタビューを実行します）か、interview-and-create-plan スキルを通じて計画することを推奨してください。

注意事項

• セットアップコマンドは意図的に保守的です: --force が渡されない限り、既存の管理対象ファイルはスキップします。
• npx @doeixd/opencode-ralph-rlm ... はポータブルなコマンドです。このパッケージでインストールされるバイナリの名前は opencode-ralph-rlm です。
• ワーカー検索は、利用可能な場合にオプションの @ff-labs/fff-node による高速化を使用します。利用できない場合、rlm_grep は自動的にフォールバックします。ネイティブ検索がローカルで問題を引き起こす場合にのみ RALPH_FFF_DISABLED=1 を設定してください。
• Node は最近のバージョンで一部の .ts ファイルを直接実行できますが、Node は node_modules 配下の TypeScript ファイルを拒否します。npm パッケージは CLI 用にコンパイル済みの JavaScript を同梱すべきです。
• レガシー v0.1 プラグインを手動でコピーしたり、ユーザーに ralph_spawn_worker を呼び出すよう指示したりしないでください。
• スーパーバイザーの LLM 認証情報には、まず環境変数を優先してください:
  • RALPH_SUPERVISOR_API_KEY
  • RALPH_SUPERVISOR_MODEL
• .opencode/ralph-provider.json は、リポジトリローカルのスーパーバイザー/ワーカーのデフォルトが必要な場合にのみ使用してください。