codex-delegate

Codex Delegate

あなたはオーケストレーターです。このスキルを使うと、範囲を限定したコーディングタスクを別の実装担当者である OpenAI Codex CLI に委任し、その成果をレビューして自分で取り込めます。ブリーフを作成し、判断の責任を持つのはあなたです。Codex は独自のサンドボックス内でコードを入力し、あなたが検証してコミットします。

ここに記載する内容は、特定のオーケストレーションエージェントに依存しません。この一連の作業に必要なのは、シェルコマンドを実行してファイルを読み取る機能だけなので、Claude Code、選択したモデルで動作する OpenCode、その他の同等のエージェントでも同じように機能します。（Claude Code 向けに設計され、Claude Code で実行されています。他のオーケストレーターについては、設計対象ではありますが、まだ実証されていないものとして扱ってください。）

使用しない場合

• タスクがインラインで実行できるほど小さい場合。委任のオーバーヘッドに見合いません。
• codex CLI がインストールされていない、または認証されていない場合（codex login を実行してください）。
• 自分でコードを書きたい場合、またはレビューだけが必要な場合（Codex 独自の review コマンドを使用してください）。

前提条件（初回に一度確認）

1. codex --version が成功すること。成功しない場合は、インストールして（npm i -g @openai/codex）、codex login を実行してください。
2. **PATH 上のどの codex が使われるか確認してください。**複数のインストールが存在することはよくあります（例：現在の npm/nvm 版と古い Homebrew 版）。command -v codex で有効なものを、codex --version でそのバージョンを確認できます。このスキルが依存するフラグ（codex exec --json、-o、exec resume）より古いバイナリもあります。リレーは実行したバージョンも result.json に記録するため、古いバイナリを後から確認できます。
3. 対象の Git リポジトリ内にいること（または --cd でそのリポジトリを指定すること）。

一連の作業

タスクごとに、以下の5つの手順を実行します。手順1、4、5ではあなたが判断し、手順2、3は機械的に進めます。

1. ブリーフを作成する

Codex が確認できるのは、あなたが送信したテキストだけです。リポジトリの記憶、チャット履歴、共有コンテキストはありません。タスクに必要な情報はすべてブリーフに含めてください。目標、現在の状態、変更する内容、変更せずに残す内容、プロジェクトで実際に使用するゲートコマンド（リポジトリの CLAUDE.md/AGENTS.md/Makefile から確認し、推測しないでください）、そして報告の要件を記載します。Codex はコミットしない（あなたがコミットする）ことも伝えてください。ブリーフ1つにつきタスクは1つにしてください。詳しいガイダンスとテンプレートについては、references/writing-the-brief.md を参照してください。

このスキルでは、Codex を実装担当者として使用します。Codex をオーケストレーターとして使うのは別の役割です。バックグラウンドでの待機には codex-background と、設定済みの MCP サーバーが必要です。codex-delegate をインストールしても、このサポートユーティリティが自動でインストールまたは設定されるわけではありません。codex-background のセットアップガイドを参照してください。

2. ディスパッチ

バックグラウンド作業を Codex でオーケストレーションする場合は、まず別個の codex-background サポートユーティリティをインストールして設定してください。MCP ツールまたはレジストリが見つからない場合は、セットアップが必要であることを報告して停止してください。モデル主導のポーリングに黙ってフォールバックしてはいけません。その後、以下のシェルの例の代わりに、登録済みの delegate_run MCP ツールを一度呼び出します。 構造化された共通引数、変更しないプロバイダーフラグ、および runId による再接続については、そのスキルに従ってください。完了するまでリクエストを保留し、その後、このスキルのレビューと反映の手順を続けます。その他のオーケストレーターでは、以下のシェルワークフローを使用してください。

同梱のヘルパーを使って、ブリーフを Codex に送ります。このヘルパーは codex exec をラップし、実行結果を取得して、構造化された result.json を書き出します。つまり、あなたの作業は「コマンドを実行して、ファイルを読む」だけです。（以下の <skill-dir> は、このスキルがインストールされているディレクトリ、つまり SKILL.md があるフォルダーであり、スキルを読み込んだディレクトリです。Claude Code ではスキルの読み込み時に「Base directory for this skill」として表示されます。他のオーケストレーターでも同じディレクトリを使用してください。保存場所がわからない場合は、find ~ -name relay.mjs -path '*codex-delegate*' を実行し、その直上のディレクトリを指定してください。）

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# read-only (review/diagnosis, no edits):   add --read-only
# isolated review (skip ambient MCP/user config): add --ignore-user-config
# subagent defaults:                        add --subagent-model <name> --subagent-effort <level>  (again on every resume)
# web search mode (disabled|cached|indexed|live): add --web-search live  (again on every resume)
# network inside the sandbox (gh, curl, installs): add --network-access  (on resume: --sandbox workspace-write --network-access)
# continue the exact Codex session:         add --session <threadId>  (from result.json; send only the delta brief)
# fallback when no thread id is available:  add --resume-last
# hard time limit (watchdog):               add --timeout 2h  (default: off; implementation runs routinely need 1-2h)
# see all options:                          node .../relay.mjs --help

このヘルパーは、デフォルトで書き込み可能な（workspace-write）サンドボックスを使用し、成果物を一時ディレクトリに書き込むため、レビュー対象のリポジトリはクリーンな状態に保たれます。コミットは決して行いません。手順 5 を参照してください。仕組み、フラグ、および result.json の形式については、references/dispatch-and-poll.md を参照してください。

3. 完了を待つ

codex-background を使用する Codex は、元の MCP リクエストを保留状態に保ちます。モデル主導のスリープ、ステータス確認、ログのポーリングは行いません。リクエストが中断された場合の再接続に限り、delegate_wait を使用してください。

ヘルパーは Codex が完了するまで処理をブロックするため、オーケストレーターで利用できる方法を使って実行し、戻ってきたら再開してください。

• Claude Code： run_in_background: true を指定して Bash 呼び出しを実行します。完了すると通知されます。
• 通常のシェル／その他のエージェント： 短いタスクはフォアグラウンドで実行し、それ以外はバックグラウンドで実行して結果ファイルをポーリングします。bash/zsh（Git Bash/WSL を含む）では … &、それ以外のシェルでは同等のコマンド（PowerShell では Start-Job、cmd では start /b）を使用します。result.json に status が書き込まれた時点で実行は完了です。（実行前の使用エラー（引数が不正、またはブリーフが空など）の場合は、コード 2 で終了して stderr メッセージを出力し、結果ファイルは書き込みません。そのため、終了コードも確認してください。codex バイナリが見つからない場合はコード 127 で終了しますが、ステータスが codex_unavailable の result.json は書き込みます。）

進捗トラッカーを実際の状態より信用しないでください。result.json が書き込まれ、プロセスが終了した時点で実行完了です。ステータス行ではなく、作業ツリーを確認してください。実装者からの完全な報告は result.json の finalMessage フィールドにあります（レポートマーカーの間に stdout にも全文が出力されます）。

4. レビュー — 自己申告を信用しない

Codex の result.json には、Codex 自身の要約とゲートの結果に関する申告が含まれています。そのまま受け入れず、必ず再検証してください。

• プロジェクトのゲートを自分で再実行します（手順 1 のテスト／lint／ビルドコマンド）。「ゲートに合格した」という申告を決して鵜呑みにしないでください。
• ブリーフと照らし合わせて差分を読みます。Codex は依頼どおりに、過不足なく実行しましたか（スコープの逸脱はありませんか）？結果内の touchedFiles を確認の出発点にしてください。
• 差分に関連するガードスキルがインストールされている場合は実行します（guard-skills の clean-code-guard、test-guard など）。このスキルが成果物を作り、それらのスキルが評価します。
• スキーマ／マイグレーションを変更した場合は往復テストを行い、削除を行った場合は参照が残っていないか grep で確認します。

完全なチェックリストについては、references/review-and-land.md を参照してください。

5. コミットする

Codex のサンドボックスは .git への書き込みを確実に行えないため（バージョン、OS、パスによって異なります）、**コミットはオーケストレーターが行います。**ゲートを通過し、差分に問題がないことを確認してから：

• 検証済みの作業を、明確なメッセージを付けて自分でコミットします。
• 変更が必要な場合は、前回の result.json にある --session <threadId> を使って差分の概要を送り（スレッド ID がない場合に限り --resume-last を使用）、もう一度レビューします。

読み取り専用のセカンドオピニオン

リレーは、書き込みリスクなしに、敵対的な視点からセカンドオピニオンを得るための確実な方法としても使えます。合意した点と、双方の立場を示した各争点を列挙した概要を添えて --read-only を指定してディスパッチし、Codex に各点について主張を擁護するか、譲歩するかを尋ねます。成果物は最終メッセージで提示され、ファイルには触れません。実装者が読み取り専用モードを提供する委任スキルなら、同じように利用できます。ただし、まずそのモードの保証がどれほど強いかを確認してください。Codex のサンドボックスは読み取り専用を強制しますが、Grok の保証はベストエフォートで、事後にのみフラグ（readOnlyViolation）が付きます。そのため、こうした実装者では、編集されていないと決めつけず、touchedFiles が空で返されたことを確認してください。

承認モデル

委任は、人間が選択して行うものです。人間が「このキューを実行して」「続行して」と承認した時点で、検証済みかつゲートを通過した作業をコミットすることが合意事項となります。それこそが委任の目的です。この権限には、2 つの制限があります。隠さずに報告する（Codex による設計上の判断、正当化はできても依頼されていない方向転換、ブロッキングではない細かな指摘を、黙って受け入れるのではなく報告する）ことと、スコープの変更時には停止する（正しく完了するために概要の範囲を超える必要がある場合は、独断で権限を拡大せず、確認を求める）ことです。詳しくは references/review-and-land.md をご覧ください。

openai-codex プラグインを使用している場合

公式の openai-codex Claude Code プラグインは優れており、併用できます。codex-delegate は同じ codex CLI を基盤としており、プラグインに置き換わるものではありません。それぞれ役割が異なります。

• プラグインの codex:codex-rescue エージェントは転送役です。1 つのタスクを Codex に渡して、出力を返します。意図的にポーリング、レビュー、コミットは行いません。
• プラグインのレビューコマンドと停止時のレビューゲートは、逆方向に動作します。Codex があなたの作業をレビューします。
• codex-delegate は反対方向のオーケストレーションループです。1 つのタスク、またはキューにわたって、あなたが Codex に実装を進めさせ、各結果をあなたがレビューしてコミットします。このループ、つまり概要の作成 → ディスパッチ → ポーリング → レビュー → コミットという流れで、コミットはオーケストレーターが行います。プラグインではあなたに任されているこの流れを、このスキルが定めています。

プラグインをインストールしている場合、付属の CLI をディスパッチ用バックエンドの代替手段として任意で使用できます。デフォルトは同梱の relay.mjs です。codex バイナリ以外に独自のインストールが不要だからです（Node と git はリレーにも必要であり、ここにあるすべてのスキルの前提条件です）。

参考資料

• references/writing-the-brief.md — Codex が指示を見ずに実行できる概要の書き方：構成、XML ブロック、報告の契約、実際のゲートコマンドの埋め込み方。
• references/dispatch-and-poll.md — relay.mjs のフラグ、result.json の契約、オーケストレーターごとのバックグラウンド実行、実行に問題が起きた場合の復旧方法。
• references/review-and-land.md — レビューチェックリスト、コミットの境界、同一セッションでの正確な手直しサイクル。
• references/multi-task-queues.md — 順次キューの実行方法：制約の引き継ぎ、進捗の追跡、実行終了時の整合性チェック。