orchestrate-implementation

実装のオーケストレーション

Worktree の分離パターンは、using-git-worktrees および David Ondrej の git-worktree を参考にしています。テストシームのパターンは、Matt Pocock の tdd、tests、mocking のガイダンスを参考にしています（いずれも MIT）。正確なバージョン指定は sources.json に記録されています。

共有書き込みの分離、最小限かつ安全な分割、子タスクのコンテキスト制限は、Cursor の poteto-mode（コミット 93b00b89ef425a9c1bac0d0b317dfc49c930ac99、MIT、Copyright (c) 2026 Cursor）を参考にしています。

所有権と権限

現在のセッションが親です。親はスコープ、判断、振り分け、調査結果の扱い、受け入れ、候補の組み立て、最終結論に責任を持ちます。子は範囲を限定したタスクを実装またはレビューします。子からの報告は根拠であり、受け入れや公開の権限ではありません。現在のリクエストまたは適用される指示で許可されている場合に限り、委任してください。ワーカー、修正担当、調査担当、レビュアー、アドバイザーを含む、すべての子の役割で Pi を使用します。ホストは配置とライフサイクルを管理します。Pi 内のモデルプロバイダーは、別のエージェントランタイムではありません。

安全を保てる範囲で、分割は最小限にします。範囲が限定された 1 つの課題は、1 人の書き込み担当者が担当できます。並行して書き込む場合は、それぞれが独立した担当範囲を持ち、別々の Worktree を使う必要があります。調査担当を立てるのは、コンテキスト収集に明確な目的がある場合に限ります。段階を埋めるだけのために、ワークフロー、専門担当、レビュー、チェックを追加しないでください。親が明示的に並列委任を許可しない限り、子がさらに委任することはありません。

モード

指定または設定されたモードを使用し、どちらもない場合は supervised とします。

• plan-only：入力を読み、タスクや概要をまとめます。ソースの編集、Worktree の作成、子の起動は行いません。
• supervised：使い捨ての候補の組み立てを含め、実装、検証、レビューを行います。対象への統合前に一時停止します。
• autonomous：安全に実行できる作業がある限り、同じループを進めます。このラベルも候補の組み立ても、対象への統合や公開の権限を与えるものではありません。

実行のリクエストは、分離された候補の準備を許可するものであり、ユーザーの対象ブランチの変更を許可するものではありません。ユーザーの明示的な制限がある場合は、こちらの既定の動作よりも優先されます。対象への統合、プッシュ、Issue へのコメントやクローズ、PR の作成やマージ、デプロイ、リリースには、それぞれ該当する権限が必要です。承認済みの統合は merge-worktree に引き継いでください。モードを公開の許可として扱わないでください。

1. 読み込みと承認

planning-contract（契約バージョン：1）を読み込みます。成果物の分類、承認、キャプチャチェックポイント、実行準備の判定は、これのみが担います。存在しない場合は、インストールを依頼し、ライターのディスパッチを拒否します。提示された計画、イシュー、リンク先の承認済み動作仕様を読み、別の計画形式を新たに作成せず、それらを保持します。承認済みで範囲が限定されたイシューは、別途仕様書や計画書がなくても契約を満たす場合があります。

GitHub の場合は、リポジトリを明示して該当するイシューを正確に取得します（例：gh issue view <number> --repo <owner/repo> --json number,url,title,body,updatedAt）。そのリポジトリとチェックアウト先を照合し、ソース URL／リビジョンとオーナーの承認を記録します。関連コメントはコンテキストであり、自動的にスコープや権限を変更するものではありません。プロジェクトが project/agents/issue-tracker.md（旧 docs/agents/issue-tracker.md）で Epiq を選択している場合は、そのワークフローを読み込み、epiq_* MCP ツールのみを使用します。ボードを暗黙的に初期化しないでください。

基準が競合する場合や、重要な決定が未解決の場合は停止します。動作仕様／承認の不足は shape-design に、分解の不足は write-implementation-plan に回します。重要なソース／インターフェース／スコープの変更によって影響を受けるタスクに限り、準備状況を再確認します。ファイルの場所やアシスタントが記述したステータスから、実行権限を推測してはなりません。

2. Pi ホストの選択

ロール／レーンごとの明示的な選択、次に要求または設定された実行時の既定値、最後に検証済みの現在のホストの順に解決します。T3 では子エージェントを起動できる Pi インスタンスを使用します。エージェントスコープの Paseo セッションではその Pi プロバイダーを使用し、Herdr では新しい Pi ペインを使用します。それ以外では利用可能なネイティブ Pi サブエージェントを使用します。ツールの存在だけでホストを判定してはなりません。選択したホストと、要求されたロールを実行できることを示す根拠を記録します。不明確な場合は確認します。検出または選択されたホストに必要な機能がない場合、そのロールはブロックされます。ホストやランタイムを黙って切り替える許可にはなりません。

ディスパッチの前に、選択したアダプターと、インストール済みランタイムのガイダンスのみを読み込みます。

• Native Pi dispatch：pi-subagents、ネイティブ Pi 子エージェントのみ。
• Herdr dispatch：herdr-pane、新規の可視 Pi セッション。
• Paseo dispatch：paseo、Pi プロバイダーと明示的にバインドされたワークスペース。
• T3 dispatch：t3-delegate、Pi ドライバー。現在は、対応済みの分離された変更配置機能がないため、読み取り専用です。

各ロールのモデルと思考レベルのフィールドは個別に解決します。明示的な実行／レーン → プロジェクト → グローバル → 仕様の既定値の順です。inherit はそのフィールドのオーバーライドを解除し、親セッションではなくグローバルまたは仕様の既定値から解決します。プロジェクトのプロファイルオブジェクトがグローバルのオブジェクトを上書きする場合も含め、解決後の完全な組み合わせを明示的に渡します。ロールを照合する前に、Pi 用のプロファイルに絞り込みます。エージェントを作成する前に、正確なモデル／思考レベルと子ツールの依存関係を確認します。エイリアスを推測したり、思考レベルを省略したり、ダウングレードしたり、前提条件をインストールしたり、ホストを黙って切り替えたりしないでください。各値とその出典、バックエンドで有効な組み合わせ、ブロッカーを既存の実行状態に記録します。

3. 所有権と検証を準備する

変更には Git が必要です。正規リポジトリ、承認済みのクリーンなベース、および選択したホストのワークツリー対応状況を確認します。マニフェストと概要を使用して、小規模な実行状態を記録します。既存のホスト／ミッション成果物の内容を重複させず、リンクしてください。書き込み担当者を割り当てる前に、Git の引き継ぎを読みます。サポート対象の名前付きベースを固定し、破棄可能なワークスペースが消える前にコミット済みの結果を保持してください。

新たに割り当てるすべてのワーカー／修正用、親のレビュー／再構築用、および候補用ワークツリーには、共有状態ルート ${XDG_STATE_HOME:-$HOME/.local/state}/worktrees/ を使用します。割り当てホスト上で一度だけ解決し、その絶対的な正規パスを記録してください。状態ディレクトリが絶対パスでない場合、またはホスト側のパスを利用できない場合は、処理をブロックします。アロケーターがサポートするサブディレクトリは許可してください。ネイティブ Pi ではリポジトリのベース名と実行 ID が追加され、Paseo ではチェックアウトハッシュとワークスペーススラッグが追加されます。親が作成するチェックアウトには、衝突確認済みのソースチェックアウト ID と、実行／レーン／役割／試行の命名を使用します。これにより、無関係なリポジトリや同名のクローンが同じパスを再利用できなくなります。実際のリポジトリ／共通 Git ディレクトリとパスマッピングを記録してください。共有ルートだからといって、所有権も共有されるわけではありません。

割り当ての前に、物理パスの各要素／シンボリックリンク、権限、衝突、およびアクティブなチェックアウトと Pi 拡張機能の自動検出対象からの除外を検証し、検証済みのルートのみを作成します。設定済みのアロケーターを維持してください。互換性のないルートを使用するには、所有者が承認した別個の設定変更が必要です。ディスパッチ中の再設定やルート外への再試行は決して行わないでください。この方針変更の一環として、既存のワークツリーを移行してはいけません。記録済みの場所とライフサイクルの所有権を維持してください。安全でない、またはサポートされていないルートでは、新たな割り当てをブロックします。

分離され、登録済みの各ワークツリーには書き込み担当者を1人だけ割り当てます。書き込みを許可する前に、返された正規パスが共有ルート配下にあり、期待されたリポジトリ／ベースに属し、所有権が排他的であることを確認してください。プロンプトにパスを記載しても、ワークスペースの配置が保証されるわけではありません。書き込みを行わない事前確認で、実際の子プロセスの cwd／リポジトリ／ブランチと、有効なモデル／思考設定を確認してください。一致しない場合は変更をブロックします。

最小限かつ有用なベースラインを実行するか、記録します。既存の失敗とタスク上の要件を区別してください。ベースラインが失敗している場合は、実装前に所有者の判断が必要です。各チェックボックスではなく、一貫性のある単位ごとに焦点を絞った検証を割り当てます。

• existing-check：既存のテストで、名前が明示された変更対象の動作を検証できます。冗長なテストを追加せずに実行します。
• new-test：名前が明示された再現可能な失敗にテストがありません。承認済みの基準、または独立したオラクルから期待値を導き、焦点を絞ったテストを1つ追加します。実装の出力をそのままコピーしてはいけません。バグの再現テストは修正前に失敗する必要があります。動作に影響するリファクタリングでは、変更前に現在の動作を固定します。明確に異なる重大な失敗モードがある場合に限り、テストを追加します。
• no-new-test：ドキュメント、メタデータ、または機械的な作業／動作に影響しない作業です。意味のある解析、ビルド、スモーク、または差分チェックを使用します。

名前が明示された失敗を検出できる、最も低コストで安定した接点を選びます。テスト対象のユニットをモックしてはいけません。また、テストを通すためにアサーションを緩めてはいけません。関連するコード、テスト、入力、環境が引き続き一致する場合に限り、検証済みの焦点を絞ったチェックの証拠を再利用します。同一のツリーは十分な条件の一例ですが、それだけが条件ではありません。また、親による再実行で、合格済みの結果を重複させてはいけません。再実行には、関連する差分または具体的な仮説が必要です。ワーカーが合格したと主張しただけでは、検証済みの証拠になりません。利用可能なコマンドをすべて実行するのではなく、リポジトリで必要なチェックと、影響を受ける受け入れチェックを実行します。

各ワーカーには、検証範囲と予算を正確に伝えます。これには、名前が明示された失敗、独立したオラクル、焦点を絞ったチェック1つ、または該当する再利用判断、および無効化する差分を含めます。この内容は、修正と再開の概要、およびレビュアーのコンテキストにも変更せず引き継いでください。子プロセスは割り当てられた検証範囲を広げてはいけません。失敗が起きた場合は、名前が明示された失敗の調査にとどめます。それを理由に、より広範なテストスイートを実行したり、期待値を緩めたりしてはいけません。

4. ディスパッチと収集

新しい子エージェントには、マニフェストとブリーフにある、範囲を限定したブリーフとインラインの役割契約を渡します。1つのタスクには直接の子エージェントを使い、スクリプトは有用な順序付け、ファンアウト、または分岐がある場合に使用します。プロジェクトの状態を変更しないのであれば、読み取り専用の子エージェントは安定したチェックアウトを共有できます。レビュアーにはチャット履歴全体ではなく、差分の正確な始点と終点、および実際の使用状況を伝えます。

非同期のホスト完了通知を優先します。安全に進められる独立した作業は継続し、残りが子エージェントだけになったら制御を戻します。タイムアウト、アイドル状態のターン、メッセージの受信、注意喚起シグナルは、いずれもターミナルでの成功を意味しません。別の書き込み担当者を割り当てる前に、ホストのステータス／制御 API を使って所有権を確認します。キャンセルすると実行が停止し、利用可能な作業結果は保持されます。クリーンアップは別途判断します。

Herdr の登録、進捗、質問、および明示的に指定された Pi ピアとの連絡には、pi-intercom を使用します。Paseo/T3 の Pi セッションでも、両方のエンドポイントに接続済みのツールがあり、同じブローカーに接続できる場合は、これを使用できます。ネイティブの子エージェントは、デフォルトでスーパーバイザーチャネルを使用します。Intercom はメッセージングの手段であり、ワークスペースの配置、ライフサイクルの決定権、完了の証明にはなりません。リモートホストには、ローカルパスやブローカー接続が引き継がれません。

5. 検証、レビュー、修正

コミット済みの結果を検証し、実際の差分を確認します。利用者が必要としている間は、その参照先を固定します。書き込み所有権が解放されていれば、残っているワークツリーを直接確認できます。パッチのみの引き渡ししか利用できない場合は、レビューと復旧を読み、ダイジェスト／ツリー／クリーン状態のチェックを行いながら、固定されたベースに対して再構成します。すでに検証済みのコミット済み結果について、パッチの再構成を必須にしてはいけません。

親による確認は、すべての結果に適用されます。リスクの高い変更や契約は、依存する書き込み担当者が利用する前に、独立してレビューします。それ以外の場合は、組み立てた候補を一度レビューします（低リスクの作業のみであれば、プロジェクト／ユーザーのルールで独立レビューが求められていない限り、親による確認で十分です）。候補の準備では、独立レビューを保留している、検証済みかつ親の確認済みのレーンを利用できます。ただし、そのレビューに合格するまでは受け入れ済みになりません。候補レビューでは、未レビューの変更と統合による影響を確認し、確定済みの指摘を再度取り上げません。

修正前に指摘への対応方針を決めます。エビデンスのゲートに失敗したものは一行で却下し、範囲内の小規模な修正は承認し、大規模または範囲外の修正は人間に引き継ぎ、未検証の基準については確認を求めます。インラインのレビュアー契約をすべて使用します。修正は1回、差分の再確認も1回までとし、候補の組み立て時に3回目のラウンドや予算のリセットを行いません。固定された結果に対する修正コミットを優先し、前の結果から修正までの差分と、影響を受ける動作のみをレビューします。パッチ置換による復旧にも同じ予算を適用します。

6. 提出とクリーンアップ

依存関係の順序に従って、隔離された候補作業ツリーで組み立てます。依存するレーンのベースには、受け入れ済みの上流候補コミットを使用します。ソース／結果の参照を保持し、候補のベースとヘッドを記録します。組み合わせた動作を検証します。関連するコード、テスト、入力、環境が引き続き一致する場合は、以前のエビデンスを再利用し、どのエビデンスを再利用したか記録します。競合や依存関係ベースの変更が生じた場合は、調整のために一時停止します。別の作業者を立てたり、対象範囲を自動的に拡大したりしないでください。

受け入れ前に、最終差分とエビデンスそのものを確認し、重要な基準をすべて解決して、各子項目が終端状態またはブロック状態であり、次のアクションが示されていることを確認します。承認済みタスクを改めて述べ、結果と照合して、accept / fix / hand back / ask のいずれかを選びます。追加のアイデアは1行にとどめ、コードにはしません。省略したチェックと残存リスクを報告します。レビュー担当者の判定は、ターゲットへの統合や公開を許可するものではありません。

作業者の所有権が解放され、引き継ぎが確実に記録され、利用者が作業を終え、クリーンアップが許可された後に限り、自身が所有するリソースのみを削除します。失敗した作業や不確かな作業、および参照を保持します。強制削除を行わず、表示中のペインを閉じず、共有ワークスペースやアドバイザーワークスペースを暗黙にアーカイブしないでください。ネイティブの自動ファイナライズはアダプターが所有し、文書化された引き継ぎを残す必要があります。監督付きの提出は、レビュー済み候補とその merge-worktree 引き継ぎを用意した状態で一時停止します。候補レビューより前に一時停止することはありません。