codex-issue-coordinator

Codex issue coordinator

1 つの Codex スレッドを使って、GitHub の複数の issue を調整します。対応中の各 issue には、それぞれ専用のワーカースレッド、worktree、ブランチ、プルリクエストを割り当てます。ワーカーは実装に関するコンテキストを保持します。依存関係の状態は GitHub で管理します。

/codex-issue-coordinator を明示的に指定するか、エージェントによるマージを明示的に許可した場合、以下のすべてのマージゲートを通過した後、対象範囲内のワーカーは自分のプルリクエストをマージできます。暗黙的にスキルが適用されても、マージ権限は付与されません。ユーザーの言葉で許可されていない場合は、マージなしモードで実行してください。 どちらのモードでも、デプロイ、リリースの公開、破壊的な操作、ブランチ保護の回避、指定されたバッチの範囲外の変更は許可されません。

このワークフローの指示として、必須スキルの SKILL.md ファイルを直接読んでください。クライアントがブロックするスキルコマンドを使ってスキルを実行しないでください。

前提条件

1. リポジトリの指示、親 issue、ネイティブなサブ issue、宣言された依存関係、プロジェクトボード、issue の状態、関連付けられたオープンまたはマージ済みのプルリクエストを確認してください。マージ済みのプルリクエストは、その issue をクローズするか明示的に参照しており、最終変更とその証拠が issue の範囲を満たしている場合に限り、完了の証拠として扱います。その issue とプロジェクトの状態を整合させ、再度ディスパッチしないでください。リンクだけから完了を推定しないでください。
2. Codex のスレッドツールを使用してください。表示されている Codex スレッドと Codex 管理の worktree を利用できない場合は、停止してください。ワーカーの代わりに、非表示のサブエージェントを使わないでください。
3. ディスパッチする前に、すべての issue を完全なタスクにしてください。動作、データ、セキュリティ、互換性、運用、コスト、または証拠に影響する製品上または技術上の決定が不足している場合は、その issue に人間の入力が必要であることを明記してください。
4. 依存関係グラフを作成してください。issue、プルリクエスト、レビュー、マージの状態を永続的に管理する情報源として GitHub を扱ってください。グラフに依存関係の循環が含まれている場合は、人間による修正を求めて停止してください。ローカルに別のトラッカーを作成しないでください。
5. アクティブなワーカーは 2 人をデフォルトとします。ユーザーからの要請がある場合、またはリポジトリでより厳しい上限が指定されている場合に限り、別の上限を使用してください。

コーディネーターのワークフロー

1. 呼び出し元のスレッドをコーディネーターとして維持します。バッチに親イシューがある場合は、スレッド名を #<parent> Coordinator にします。新しいコーディネーター実行を開始するとき、または再開するときは、ワーカーの調査や割り当てを行う前に、set_thread_pinned を使ってスレッドをピン留めします。
2. 同じイシューに対応するアクティブなワーカーがすでにいる場合は、そのワーカーを再利用します。状況が不明瞭なワーカーや中断されたワーカーがいる場合は、新しいワーカーを作成する前にそのワーカーの状況を確認します。イシューに未完了のプルリクエストがすでにある場合は、そのプルリクエストの正確なヘッドブランチでワーカーを作成または再開し、ブランチとプルリクエストの URL をプロンプトに含めます。それ以外の場合は、最新のリモートデフォルトブランチから、管理対象のワークツリー内に Codex プロジェクトスレッドを作成し、必要な新しいブランチ名を含めます。
3. すべてのワーカーの名前を #<issue-number> <short title> にします。
4. 前提条件がマージ済みのイシューのみを開始します。独立したイシューは、ワーカー数の上限まで同時に進められます。このワークフローでは、依存するブランチを積み重ねないでください。
5. ワーカーに、イシューの完全な URL、依存関係の状態、リポジトリの場所、確定したブランチとプルリクエストの状態、および以下のワーカー契約を伝えます。/task-to-pr を使うよう指示し、コーディネーターが明示したマージモードまたは非マージモードを指定します。マージモードで認められるのは、そのワーカーが担当するイシューに対する権限のみです。
6. wait_threads の簡潔なスナップショットを使ってワーカーを監視します。ワーカーに支援が必要な場合に限り、read_thread を使います。判断や修正後の範囲は send_message_to_thread で伝え、コーディネーター側でワーカーのファイルを編集しないでください。
7. あるイシューがブロックされても、独立した作業は続けます。同じチェックまたはレビュー指摘に対して3回失敗したら、そのイシューを一時停止し、証拠を GitHub に記録して、人間の判断を求めます。
8. マージモードでは、ワーカーが完了を報告したら、プルリクエストがマージ済みであると GitHub に表示されること、イシューに最終的な証拠が含まれていること、そしてイシューがクローズされていることを確認します。マージ済みのプルリクエストによってイシューがクローズされていない場合は、明示的にクローズします。その後、プロジェクトが対応していればイシューを Done にし、ワーカースレッドをアーカイブします。非マージモードでは、プルリクエストのエージェントが完了可能なゲートがすべて通過した時点でワーカーを停止し、イシューを Review の状態に保ち、人間による承認またはマージ待ちをブロッカーとして記録し、スレッドは利用可能なままにします。
9. マージのたびに依存関係グラフを更新し、更新後のリモートデフォルトブランチから新たに着手可能になったイシューを割り当てます。非マージモードで、依存するイシューが、前提となるプルリクエストのマージ待ちだけで進められない場合は、人間によるマージ待ちをブロッカーとして記録します。無期限に待ったり、未マージのブランチから依存するイシューを割り当てたりしないでください。
10. マージモードでは、対象範囲内のすべてのイシューがマージ済み、クローズ済みであり、プロジェクトが対応していれば Done になっている場合、または未完了のすべてのイシューに人間の対応が必要なブロッカーが記録されている場合にのみ完了とします。非マージモードでは、対象範囲内のすべてのイシューに、エージェントが完了可能なゲートがすべて通過した準備完了のプルリクエストがあるか、人間による対応が必要なブロッカーが記録されている場合に完了とします。

ワーカーの契約

各ワーカーは1つの課題を担当し、次の順序で進めます。

1. 課題、リポジトリの指示、関連する仕様、コード、テスト、依存関係に関するプルリクエストを確認します。可能であれば、課題を「進行中」に移動します。
2. Codex が管理するワークツリーを使用します。課題にオープンなプルリクエストがある場合は、その正確なヘッドブランチとプルリクエストを再利用します。ない場合は、更新済みのデフォルトブランチから、リポジトリで必須の課題リンク付きブランチを作成します。
3. 課題の範囲内だけを実装します。すべての受け入れ基準、影響を受ける障害経路、回帰リスク、明示されたエッジケースについて、テストを追加または更新します。
4. /test を使用します。ブラウザーに関わる作業では、影響を受ける成功フローと失敗フロー、レスポンシブ幅、キーボード操作、コンソールエラー、関連する場合は失敗したリクエストについて、実際のブラウザーで確認します。
5. テスト済みの変更をコミットしてプッシュします。まだオープンなプルリクエストがない場合は、ドラフトプルリクエストを作成します。簡潔な概要と最新の証拠を含めます。
6. プルリクエストをレビュー可能にし、課題を「レビュー」に移動します。独立したレビューを依頼する前、または GitHub レビューを待つ前に行います。
7. 実装を担当していない新しいサブエージェントを使って /review を実行します。必須の CI と自動レビューを待ちます。マージモードでは、リポジトリで必須の承認もすべて待ちます。マージしないモードでは、人間からのフィードバックを無期限に待たず、保留中の必須承認を人間による対応が必要なブロッカーとして記録します。
8. スコープ内の有効な指摘にはすべて対応します。レビューのスレッドには、修正内容、または変更しない判断の根拠を返信します。完全に対応した場合に限り、スレッドを解決します。
9. コード変更後は、影響を受ける /test の証拠確認と、新たな /review を繰り返し、コミットしてプッシュし、プルリクエストの証拠を更新して、CI と自動レビューを再度待ちます。モードのゲートを通過するまで反復します。不要なラウンドを作ったり、任意の人間によるフィードバックを無期限に待ったりしないでください。
10. マージモードでは、すべてのマージゲートを通過した後、リポジトリで推奨される方法でプルリクエストをマージします。管理者によるバイパスは絶対に使用しないでください。GitHub でプルリクエストのマージが報告されるまで待ち、最終的な証拠を記録して、課題がクローズされていることを確認します。プルリクエストのマージで課題がクローズされなかった場合は、明示的にクローズします。マージしないモードでは、合格したプルリクエストを人間がマージできるようにオープンのままにします。最終状態をコーディネーターに報告します。

マージゲート

次の条件をすべて満たす場合に限り、ワーカーはマージできます。

• プルリクエストがドラフトではなく、レビュー可能な状態である。
• 課題の全範囲と受け入れ基準について、証拠が記録されている。
• 最終コミットで、対象を絞ったテストと必須の広範なテストが合格している。
• 最終コードに対する新たな /review の判定が Approve である。
• 必須の GitHub チェックがすべて合格している。
• 対応が必要な自動レビューまたは人間によるレビューのスレッドがすべて解決されている。
• リポジトリで必須の承認がすべて揃っている。
• プルリクエストがマージ可能で、必須のベースブランチと最新の状態にある。
• セキュリティ、データ損失、互換性、運用、製品の判断に関する未解決事項がない。
• プルリクエストの変更範囲が、そのワーカーの課題だけに限られている。

ゲートを通過できない場合は、マージしないでください。ブロッカーを記録し、独立した作業を続けてください。

ワーカープロンプト

次の形式を使い、すべてのプレースホルダーを置き換えてください。

Use /task-to-pr to complete <issue URL> in this Codex-managed worktree.

Your thread owns only this issue, branch, worktree, and pull request.
Branch state: <reuse PR head branch and PR URL, or create new branch name>.
Delivery mode: <merge after all gates pass, or leave the passing PR open>.
Read the issue and repository instructions as the source of truth.
Implement the smallest complete change and prove acceptance criteria, edge
cases, failure paths, and regressions.

After local proof passes, commit, push, open or update the pull request, and
mark it ready for review. Only then run fresh independent /review and wait for
CI and GitHub review. Address valid findings and repeat test and review after
every code change.

<If merge mode: The user explicitly authorized this /codex-issue-coordinator run to
merge this issue's pull request after every merge gate passes. Wait until
GitHub reports the merge, update and close the issue, and return the result.>
<If no-merge mode: Leave the passing pull request open for human merge and
return its URL and proof.>
Do not deploy, publish a release, bypass repository rules, or change unrelated
work.

返却内容

各課題について、担当ワーカー、プルリクエスト、ゲートの状態、ブロッカーを報告してください。完了した課題と、人間の対応が必要な課題を明記してください。結果に影響しないワーカーのログは繰り返さないでください。

境界

• ワーカーには、表示されている Codex スレッドを使用します。新しいサブエージェントを使用できるのは、ワーカー内で独立した /review を行う場合のみです。
• 1 つの課題に対して 2 人のワーカーを割り当てたり、2 人のワーカーに同じ作業ツリーを共有させたりしてはいけません。
• その課題に対する既存のプルリクエストを置き換えたり、重複して作成したりしてはいけません。再開してください。
• すでにマージされたプルリクエストやクローズされた課題については、その変更と証明が課題の範囲を満たしている場合に限り、割り当てる前に調整してください。
• このワークフローでは、未マージのプルリクエストを起点に、依存する作業を開始してはいけません。
• バッチの妨げになるという理由だけで、無関係なプルリクエストをマージしてはいけません。
• マージ権限から、デプロイやリリースの権限を推測してはいけません。
• マージと最終的な課題の状態を確認するまで、ワーカーをアーカイブしてはいけません。