orchestrate

Orchestrate（開発ループのドライバー）

1 つのオーケストレーターセッションで、事前確認、選択、1 つの仕様を最初から最後まで進行し、終了処理を行って報告します。また、仕様がクローズした区切りで、コンテキストに十分な余裕が実際にある場合は、任意で次の仕様に移ります。 役割は固定です。 このスキルを実行するあなた（どのハーネスで実行する場合でも）はドライバーです。作業を整理し、ゲートを通過させ、取り込み、プッシュし、すべてのトラッカーへの書き込みを担当します。 実装担当者は、常にハーネス固有のサブエージェント機構で実行する、新しいトークンゼロのセッションです。実行を進めるハーネスが担当者の実行を制御します。実行時に明示的なリクエストがあった場合に限り、外部ランナー経由で実行します（「The take」を参照）。 作業の整理と分解は、自分のハーネスの新しいサブエージェントに任せます。あるセッションで仕様をまとめ、別のセッションで仕様どおりに実装し、レビューは常にあなたが行います。

このループのセマンティクスは、このスキルの references/dev-loop-protocol.md にあります。プロジェクトにコピーせず、その場で読みます。 プロジェクトの契約は docs/agents/dev-loop.md です。ここには宣言のみを記載します（ポート、スクリプト、ゲートの証明、意図的な逸脱）。競合がある場合は契約を優先します。トラッカーの仕組みについては docs/agents/issue-tracker.md を参照してください。 最初の書き込みの前に、プロトコルと契約を読みます。契約ファイルがない場合は、推測せずに停止し、references/dev-loop-declarations.md を参照してひな形を作成するよう案内します。 トラッカーはループの唯一の記憶です。セッションはいつでも終了する可能性があり、次のセッションはトラッカーの状態だけをもとに再開します。

呼び出し

引数なしの形式が標準です。セッション開始手順を実行し、それによって選択されたものに着手します。 仕様の引数は、人間による上書き指定であり、許可された選択肢のみから選びます。ブロック中または担当者が割り当て済みの仕様は拒否します。また、未解決の fix-main チケットがあれば、そちらを優先します。 一度に扱う仕様は 1 つで、成果物が必ず完成するとは限りません。セッションでは、main を修正する、単独チケットを解決する、作業の整理だけを行う、またはチケットの区切りでボードの途中まで進めて終了する場合があります。 クローズした仕様は継続の区切りです。コンテキストに十分な余裕が実際に残っている場合、セッションは選択を再実行して次の仕様に進めることがあります。通常のセッションで扱う仕様は 1 つです。継続は、余裕がある場合に限る例外であり、ゲートを通過しきれない可能性のある仕様を開始することはありません。 継続する場合は、すべて報告に明記します（「Session end」を参照）。

セッションの開始

契約のセッション開始手順に従って、次の順に進めます。

1. ワークスペースの事前確認 - 作業ツリーに変更がある場合はセッションを即時停止し、確認した内容を報告します。特定できた作業だけを一時退避、コミット、または破棄できます。 次に、git fetch を実行して origin/main にリベースし、ブラウザツールの正常性を確認します。契約上のゲートを通過し、ポートを使用しているループ所有の古い開発サーバーを終了します。ループ外のポートはループ外の作業に属するため、触れてはいけません。また、古いテイク用ワークツリーとそのブランチを削除します（残っているものは、終了したセッションの残骸です）。 サーバーは一時的なものとして扱います。ゲートで必要になったときに起動し、ここでは起動しません。
2. 復旧確認 - 割り当て済みのオープン項目があれば、それは終了したセッションのものです（ループは同時に1件のみ処理します）。 契約の復旧表を適用します。in-progress のチケット → ready-for-agent に戻して割り当てを解除します。in-progress の仕様書 → 消去して再整備します（孤立したサブイシューを閉じ、状態を戻して割り当てを解除します）。その他の割り当て済みイシュー（チケットでも仕様書でもない、親項目、エピック、トラッキングイシュー） → 担当者の割り当てを解除し、ライフサイクルラベルがあれば削除して、担当権をクリアします。再整備はしません。
3. トラッカーの事前確認 - 契約で定められた main の最新コミットにおけるメインのヘルスシグナル（デプロイ状態、CI チェック）を確認します。契約にリモートシグナルの定義がない場合は、リベース後の最新コミットでチェックコマンドをローカル実行します。 1つでも失敗があれば、失敗したチェック名と SHA をタイトルに含め、証拠を本文に記載した、オープン状態の fix-main チケットを1件だけ探すか作成します。 すべて成功していて、古い fix-main がオープン状態なら、コメントを残して閉じます。
4. 次の優先順で選択します。オープン状態の fix-main チケット。該当しない場合、最も古い、ブロックされておらず、未割り当ての ready-for-agent チケット。該当しない場合、最初のオープン状態で、ブロックされておらず、未整備の ready-for-agent 仕様書。それもなければ、その旨を伝えて停止します。 needs-triage と needs-info の項目はループの対象外です。

仕様書の進行

• 仕様書を選択した場合 → 整備し（後述）、その新しいボードに沿って進めます。
• チケットを選択した場合 → 対応し（後述）、仕様書に属するチケットであれば、その仕様書のボードに沿って続行します。
• ボードの最前線にあるチケット、つまり最も古い、オープン状態で、ブロックされておらず、未割り当てのチケットを、1件ずつ順に対応します。
• チケットの境界が終了ポイントです。 各境界で自分のコンテキストの逼迫度を確認し、ゲートできない可能性のあるテイクを始めるくらいなら停止します。テイクのコミットはローカルにあり、セッションの終了とともに失われます。 次のセッションに必要な情報は、該当チケットへのコメントとして残します。トラッカーだけが引き継ぎ先です。 再開するには、このスキルをもう一度実行するだけです。
• すべてのサブイシューを閉じたら、仕様書を閉じます。閉じた仕様書は、依存する仕様書のブロックを解除する永続的な完了マーカーであり、クローズ時のコメントが仕様書のレポートになります。 その後、継続確認を行います。十分なコンテキストの余裕が実際に残っていれば、もう一度選択して次の仕様書に取り組んでも構いません。そうでなければ、後片付けをして終了します。

仕様のグルーミング

先回りしてグルーミングしてはいけません。仕様をグルーミングできるのは、ブロッキング仕様がクローズされている場合だけです。これにより、想定上のコードベースではなく、実際に反映されるコードベースに基づいてチケットを作成できます。

1. 仕様を引き受ける：ほかの作業を始める前に、ready-for-agent を in-progress に切り替え、自分を割り当てます。
2. 新しいサブエージェントを起動する：リポジトリの to-tickets スキルをチケット案の作成手順まで実行するよう指示します（コンテキストを集め、現時点のコードベースを調べ、ブロッキングの依存関係を含む垂直トレーサーバレット形式のスライス案を作成する）。分解案を報告させます。スキルのクイズ手順は以下のあなたとのやり取りで行い、公開手順はあなたが担当します。 報告には、チケットごとにタイトル、本文全体（受け入れ条件を含む）、ブロッキングの依存関係を記載します。
3. 分解案を吟味する。 to-tickets のクイズにはあなたが回答します。人間が判断するように評価してください。
   • 粒度 - 各スライスが単独でデモ可能で、新しいコンテキストウィンドウひとつに収まること。
   • 依存関係 - 本当に必要なゲートだけにし、慎重さを理由に順序を固定しないこと。
   • 網羅性 - 仕様のすべての要件が、いずれかのチケットに含まれていること。
   • 現実との整合性 - 「すでに存在するため、チケットは不要」という主張があれば、受け入れる前に自分でコードを確認すること。 参照リポジトリや環境に関する主張（「Xにはすでにこれがあるので、コピーする」など）も同様に扱います。グルーミング時点の実際のリポジトリの状態を確認してください。仕様やイシュー本文の記述をそのまま引き継いではいけません。古くなった主張をチケットに取り込むと、グルーマーの権威を伴ってしまいますが、ゲートでは概要ではなく差分がチェックされます。 このマシンから参照先にアクセスできない場合、その主張は明示的に未検証の前提として記載し、採用前に担当者が確認する必要があります。確立された事実として扱ってはいけません。 ハーネスで再開できる場合は、同じサブエージェントとのやり取りを続けて反復します。再開できない場合は、前回の分解案とあなたの異議を引き継いだ新しいサブエージェントを起動します。
4. 自分で公開する - トラッカーへの書き込みはすべてドライバーが行い、to-tickets の公開手順を実行します。スライスごとにイシューテンプレートを使ってチケットをひとつ作成し、依存順（ブロッカーを先に作成し、依存関係では実在する ID を参照できるようにする）に並べます。各チケットは仕様のネイティブなサブイシューとし、兄弟チケット間にネイティブなブロッキング依存関係を設定して、ready-for-agent を付けます。 公開内容を検証します。サブイシューを列挙し、依存関係を抜き取りで確認してください。
5. 仕様の引き受けを解除する：in-progress を外し、割り当てを解除します。これが「ボードが公開状態になった」ことを確定するアトミックな切り替えです。 サブイシューがあるのに in-progress のままの仕様は、公開が完了していないボードであり、決して選択可能にしてはいけません。

チケットを完了する

1 件のチケット → セッション内で完結するクローズドなアトミック作業：着手 → ゲート → 反映。 チケットを反映するブランチ上で、クリーンな作業ツリーから開始します。着手作業は専用の worktree で実行するため、ゲートで確認する差分は着手作業の差分そのものです。

1. 担当する：作業を始める前に、ready-for-agent を in-progress に変更し、自分を担当者に設定します。
2. 着手する：「着手作業」を参照し、専用の worktree で新しい着手セッションを起動します。各試行が 1 回の着手です。着手ごとにコミットするため、イシューのタイムラインに試行履歴がすべて記録されます。
3. ゲート：「ゲート」を参照します。合格ならステップ 5 に進み、不合格ならステップ 4 に進みます。
4. 差し戻す：レビューで見つかった問題を監査可能な記録としてイシューにコメントし、その後、同じ契約のもと、指摘内容と修正への期待を伝えて同じ着手セッションを続行します。ステップ 3 に戻ってゲートを再実行します。 着手の上限は3 回です。3 回目でも解決しない場合はエスカレーションします。needs-human ラベルを付け、in-progress を外し、担当を解除して、コミットとコメントは記録として残します。 ドライバーはコードに手を出しません。引き継ぎではなく、エスカレーションします。
5. 反映してクローズする：プッシュする前に、着手の各コミットメッセージを確認します。すべてに、曖昧さがなく正確な #<N> の言及が含まれ、クローズキーワードと衝突しないことを確認します。言及がない、誤っている、または衝突するメッセージは修正します（プロンプトにルールがあっても、着手ではこの言及が省かれることがよくあります。そのため、記録の根拠となる言及はこの確認時に追加します）。その後、着手ブランチを反映先ブランチに反映します。これは 2 か所で行う手順です。反映先ブランチが進んでいる場合は、worktree 内で着手ブランチをリベースします（git ではそのブランチがそこでチェックアウトされています）。次に、メインのチェックアウトからファストフォワードしてプッシュします（着手の worktree 内から ff-merge すると、HEAD が着手ブランチそのものであるため、何も起きずに「Already up to date」と表示されます。問題が表面化するのは、その後のプッシュや反映の失敗時だけです）。反映内容をコメントし（「記録」を参照）、イシューをクローズします。クローズすると、依存する項目のブロックが解除されます。 ゲート合格時のみプッシュ：不合格の着手はリモートに反映しません。多くのセットアップでは、main へのプッシュで本番環境にデプロイされます。
6. 後片付け：ゲートで起動した開発サーバーやブラウザーセッションを停止し、続いて、着手作業が残したバックグラウンドプロセスを、記録されたハンドル（契約に記載された停止コマンド、または記録された pid のプロセスグループ）を使って停止します。パターン一致による kill では、リトライの合間にスリープしている親プロセスを見逃すことがあります。そのため、パターン指定で停止したものは、何も起きていない時間を置いてから再確認し、再起動していないことを確かめます。 着手の worktree とブランチを削除する前に、worktree のパスを保持しているプロセスがないことを確認します（lsof -a -d '^mem' +D <worktree>）。プロセスが残っていると削除済みのパスで動き続け、クォータを消費し、次の着手が責任を問われるゴミを残します。 pnpm プロジェクトでは ^mem の除外が重要です。node_modules はストアにハードリンクされているため、別のチェックアウトで行われたビルドでも同じネイティブモジュールファイルがマップされ、通常の lsof +D では worktree のパス配下にあるものとして報告されます。保持しているプロセスを示すのは、cwd、txt、オープン中のファイルディスクリプターだけです。 agent-browser close はブラウザーセッションを閉じますが、デーモンは停止しません。最初の呼び出しが worktree から実行されたデーモンは、そこを cwd として保持するため、削除前に pid を指定して停止してください。 着地時、エスカレーション時、また着手を早期に停止した場合（スコープ変更、中断）にも、同じ後片付けを実行します。記録となるのはトラッカー上のコメントであり、残った worktree ではありません。

着手作業

各着手は、トークンゼロから始まる新しいセッションで、着手ブランチ上の専用 worktreeで作業します。共有の作業コピーは使いません。これにより、並行するセッションが互いの未コミットの作業をコミットに取り込んだり、ゲートを通していない相手のコミットをプッシュしたりするのを防ぎます。 ハーネスにネイティブの worktree 分離機能がある場合はそれを使い、ない場合は通常の git worktree add で作成します。着手開始前に、契約の worktree セットアップ行に従って環境を整えます（追跡対象外の環境ファイル、依存関係のインストール）。 着手は、ハーネスのネイティブなサブエージェントの仕組みで起動します。起動時に明示的な要求がある場合のみ、外部ランナー経由で実行します。

• ネイティブサブエージェント - ハーネスのネイティブなサブエージェント機能を使ってテイクを起動します。 バウンス後も、ハーネスで再開できる場合は同じテイクセッションを続行します。新規セッションより低コストで、テイクのコンテキストも維持されます。再開できない場合は、元の契約文を一字一句そのまま、前のテイクのレポート、バウンスで見つかった内容とともにプロンプトへ含めて、新しいサブエージェントを起動します。
• 外部ランナー（明示的なリクエストがある場合のみ） - 呼び出し時に、このスキルのrunners/フォルダー内にあるランナーファイルを指定します。起動、再開、テイクの計測には、そのファイルの指示に従います。 runners/codex.mdでは、テイクをcodex execセッションとして実行します。

どちらの場合も、バウンス後の続行は3テイクの予算に含まれます。 ハーネスが対応している場合、長時間のテイクはバックグラウンドで実行します。30分未満の静かな実行はそのまま続けてください。 コンテキストに取り込むのはテイクの最終レポートのみです。テイクのトランスクリプト、差分、ファイルのダンプをドライバーセッションに取り込んではいけません。ゲートはレポートではなく、gitから差分を読み取ります。

プロンプトの契約。 テイクは、仕様スレッド、ドライバーとの会話、ハーネスが注入するもの以外の独自ルールを一切持たない状態で開始します。 テイクの成否は仕様の品質で決まります。 すべてのテイクのプロンプトには、次の内容を含めます。

• 目標：課題番号、タイトル、本文全文（受け入れ基準を含む）を一字一句そのまま記載し、親仕様への参照も含めます。このチケットで実装する箇所については、仕様書独自の表現をそのまま埋め込みます
• 手順の参照先：プロジェクトに implement スキル（.agents/skills/implement/）がある場合は、それに従います
• 根拠の参照先：リポジトリのドメイン用語集（CONTEXT.md）、リポジトリに含まれる生成済みのスタックガイドライン（学習済みの知識より優先）、および課題に UI が含まれる場合はデザイン方針のドキュメント
• 課題から引き継ぐ制約と対象外事項
• 求められる証明：プロジェクト指定の正確なチェックコマンドに加え、差分によって契約の「Gate proofs」セクションに基づき実行されるすべてのデプロイ相当の証明。実行担当もこれらを実行するため、失敗しても手戻りのコストは小さく済みます
• 実行時のルール：実行担当がアプリの起動を必要とする場合は、開発サーバースクリプトを使い、契約で指定されたポートを取得して、自身のワークツリー内から独自の一時サーバーを起動し、終了時に停止します。起動するその他の長時間実行プロセスは、ハンドルを使って停止できなければなりません。契約で宣言されたライフサイクルスクリプトを通じて起動するか、PID を記録した専用のプロセスグループ内で起動し、終了時に停止するか、レポートに記載します。実行担当がハンドルのないデタッチ済みプロセスを残すことはありません。破壊的なシェルコマンド（rm、既存パスへの mv、git clean）では、ワークツリーまたはスクラッチディレクトリ内の絶対パスを指定します（例：rm -rf "$WORKTREE/.probe"。cd "$WORKTREE" && rm -f .probe/* は不可）。cd の後に指定した相対パスは、セッションのメインチェックアウトディレクトリを基準に解決されます。そのため、ハーネスは確認のために無人実行を停止します
• 検証状態：差分によって並べ替え、フィルタリング、レイアウトが変わる場合、実行担当はデフォルト以外の状態も操作します。ほかの並べ替えキー、ほかのフィルター状態、折りたたんだ状態と展開した状態の UI、デザイン方針で指定されたすべてのビューポートを対象とし、実施した状態をレポートに記載します。変更の対象として設計された状態しか確認していない証明は、証明とはみなされません
• デプロイのルール：デプロイ側の状態（開発環境やプレビュー環境の環境変数、リモート設定）はドライバーが管理します。変更が必要な実行担当は、その必要性をレポートに記載し、ローカルにとどめます。契約で実行担当にデプロイ環境へのアクセスが明示的に認められている場合は、2 つの義務が追加されます。値は元の形式で復元します（dotenv ファイルからコピーした値に付いている引用符は文字列として扱われるため、取り除きます）。また、変更したすべての変数をレポートに記載します
• レビュールール：implement スキルの最後にはコードレビューの手順があり、その指示では並行して動作するレビュー用サブエージェントを起動します。実行担当はこれに従わず、2 つのレビュー観点を自身のコンテキスト内で順番に確認します。さらに、実行担当はサブエージェントを起動せず、エージェントからのメッセージや通知を待って処理を止めることもありません。サブエージェントの返信が実行担当に届く保証はなく、サブエージェントを起動できない実行環境もあります。待機中の結果が届かない場合は、ディスク上にある情報を基に作業を進め、その旨をレポートに記載します
• コミットのルール：#<N> を通常のメンションとして含め、ローカルでコミットします。このメンションは、GitHub のクローズキーワード（fix、fixes、fixed、close、closes、closed、resolve、resolves、resolved）の直後に置いてはいけません。通常の文章中でも同様です。ゲートの実行前に GitHub が課題を自動クローズしてしまうためです。必要に応じて文を書き換えます。プッシュは絶対にしません
• 出力形式：簡潔なレポートのみ。実装した内容、証明の結果（成功／失敗）、変更したファイル、コミット SHA、発生したブロッカーを記載します

ゲート

レビューを委任したり、省略したりすることはありません。

まず差分を確認します。 git status -sb を実行し、次に差分全体を読み、コントリビューターからの PR と同じように、次の 4 つの観点で評価します。

• 仕様への忠実度 - すべての受け入れ条件を満たしており、課題の範囲を超えるものを含めていないこと。
• リポジトリの規約 - 用語集の語彙、確立されたパターン（関数ビルダー、テストの差し替えポイント、フィクスチャ）、生成されたスタックのガイドラインに沿っていること。新しいコードが周囲のコードに自然になじんでいること。
• デザインの方向性 - UI の差分をリポジトリの既定のデザインドキュメントと照らし合わせること。好みでスタイルを変更するのではなく、逸脱を指摘します。
• 洗練度 - 差分の規模に見合う価値があること。再発明より再利用を優先し、不要な抽象化を避け、テストでは実装の詳細ではなく、定まった接点での動作を検証すること。

次に事実を確認します。 報告は主張にすぎません。事実は、依存関係がインストールされ、差分がチェックアウトされたテイクの作業ツリーで、自分自身が再実行して確かめます。 プロジェクトのチェックコマンドを自分で実行し、課題に実行時の影響がある場合は、アプリをエンドツーエンドで検証します（リポジトリに verify スキルがあれば、それを使用します）。その際は、作業ツリー上で独自の一時的な開発サーバーを起動し、契約で定められたゲートポートを使用します。オフループポートには触れません。 報告にデプロイ環境の変更が記載されている場合も、同じように検証します。デプロイ環境の現在の値を自分で読み、期待値と照合してください。「復元して検証済み」はあくまで主張です。dotenv ファイルから復元した値には、余計なリテラルの引用符が含まれていることがあります。

デプロイ相当の検証。 ローカルのチェックチェーンでは構造上検出できないデプロイ専用の障害があります。そのため、ゲートでは本番環境で実行されるものを実行します。 契約の Gate proofs セクションでは、差分の種類とリポジトリの検証コマンドが対応付けられています（スキーマ変更、破壊的なデータ変更、本番ビルドでのみ発生するエラーなど）。差分が該当する検証はすべて実行してください。

参考シグナル。 同じセクションには、対象の領域ごとにリポジトリのレビュースキルとアナライザーも記載されています（UI ガイドライン、スタックアナライザー、コピーのレビュー）。差分が関係するものを実行し、その結果は規約と洗練度の観点からレビューの参考情報として評価してください。合否を決めるゲート手順として扱ってはいけません。

記録

トラッカーのコメントは、後続のセッションや複数プロジェクトにまたがる調査が参照する記録です。

チケットごと - 完了コメントには次の情報を記載します。

• 提供した内容とコミットの SHA
• 使用したテイク。各リトライについて、ゲートで検出した不具合を引用して記載
• ドライバーセッションの ID と、各テイクのセッション ID またはサブエージェント ID

セッション終了時

終了の仕方にかかわらず、すべてのセッションで以下を行います。

• 後片付け - ループが起動した開発サーバーとブラウザーセッションを停止します。
• 報告 - 作業を進めた各仕様につき、仕様レベルのコメントを 1 件投稿します。仕様が完了した場合はクローズコメント、それ以外の場合は状況コメントです。 仕様に触れなかったセッションでは、最後に対応したチケットに同じ報告を投稿します。 報告には、提供したチケットと使用したテイクおよびリトライ、エスカレーション、コミット、作業中に発生した環境やツールの問題、登録した所見、セッション ID（ドライバーと各テイク）を記載します。ドライバーセッション ID は「このセッション」のような表現ではなく、文字列そのものを記載してください。また、セッションで複数の仕様を進めた場合は、そのセッション内での仕様の順序（「このセッションで 2 つ目の仕様、#63 の後」など）も記載し、事後の集計で記録を仕様ごとに区切れるようにします。 続けて、短い振り返りを記載します。それぞれ 1、2 行で、セッションで最も難しかった判断と却下した代替案、自信のない箇所とその前提、対象範囲がもっと広ければ何を変えていたかを記します。 最後に、ループのブロッカーとして、未解決の needs-human 項目と、対応可能な仕様が残っているかどうかを記載します。
• 所見 - ツールの不具合、ゲートの見落とし、スキルの不足など、対応可能なものはそれぞれ needs-triage ラベルを付けた独立した課題にします。文脈は報告の「所見」セクションに記載します。