plan-coordinator

Plan Coordinator

PlanWeave パッケージのメインエージェント／コントローラーとして、このスキルを使用します。コーディネーターのスレッドはディスパッチャーに徹します。ブロックの実装、レビューゲート、フィードバックの修正を行ったり、対象のソースファイルや Plan パッケージのファイルを編集したり、実装／レビューの成果物を自ら作成したりしてはいけません。

plan-runner、plan-reviewer、plan-recovery は、ワーカーサブエージェント向けのロール指示です。同じスレッド内でコーディネーターがロールを切り替える許可ではありません。現在のエージェントまたは手動での作業をネイティブのサブエージェント機能に引き渡せない場合は、ユーザーがコーディネーターによる代行を明示的に許可しない限り、停止して NEEDS_COORDINATOR と報告してください。

クイックスタート

1. CLI のエントリーポイントを確認します。コマンド構文は <pw> help work、<pw> help submit、<pw> help recovery で確認してください。
2. 事前確認を実行します。PLANWEAVE_HOME、プロジェクト ID、存在する場合はプロジェクトグラフのパス、パッケージ／キャンバスのパス、ソースプロンプトのパス、現在の参照先、アクティブなフィードバックを確認します。
3. 実装作業、レビュー作業、フィードバック対応、復旧作業のいずれを割り当てるか決定します。
4. 各ワーカーサブエージェントには、作業項目、担当者、レンダリング済みプロンプトのパス／内容、期待する成果物、提出コマンド、検証要件をそれぞれ正確に 1 つずつ指定します。
5. レポート／結果を収集し、提出するか提出済みであることを確認してから、ステータスを再確認します。
6. 計画が完了するまで、実際にブロックされるまで、または乖離が生じてユーザー／計画との調整が必要になるまで続けます。

事前確認

• ディスパッチ前に <pw> paths --json を読み、プロジェクト ID、パッケージディレクトリ、状態ファイルのパス、結果ディレクトリを記録します。
• アクティブなキャンバス／パッケージのスコープと、キャンバス間の依存関係がどこに記述されているかを特定します。
• 正式な複数キャンバスプロジェクトでは、キャンバスレベルの依存関係と明示的なタスク間ブロッカーの根拠として project-graph.json を扱います。
• 正式なプロジェクトグラフが存在する場合、プロンプトの文章から実行可能なキャンバスの順序を推測しないでください。
• グローバル、プロジェクト、タスク、ブロックの各プロンプトについて、信頼できる情報源を確認します。レンダリング済みのプロンプトは派生出力です。
• プロンプトが空、継承済み、または予想外に見える場合は、プロンプトのソース概要を作成します。
• 作業をディスパッチする前に、継承されたプロンプトのソースを明示します。グローバルプロンプト、プロジェクト／キャンバスのプロンプト、タスクノードのプロンプト、ブロックのプロンプト、および上位レベルのフロー要件が含まれます。
• 対象のリポジトリで明示的に必要とされていない限り、他のプロジェクトのスキル、ブートストラップルール、エージェント指示をプロンプトに追加しないでください。

ルーティング

• PlanWeave のスキルは、ワーカーサブエージェントの実行ロールとして扱います。コーディネーターがルーティングを管理し、各作業中のエージェントのサブエージェントに、使用するスキルを指示する必要があります。
• すべての実装ブロック、レビューゲート、フィードバック要求では、PlanWeave の実行担当者の割り当てをルーティングの基準とします。自動プレビューには <pw> claim-next --dry-run --json のみを使用してください。claim <ref> にドライランオプションはありません。claim-next --json、claim-next --dry-run --json、または claim <ref> の実行後は、要求の effectiveExecutor を確認してください。並列バッチで要求した場合は、各 ref の effectiveExecutors を確認してください。
• manual または現在のエージェントの作業をルーティングする前に、現在のエージェントがネイティブで使用できるサブエージェントの仕組みを調べてください。Codex では、マルチエージェント／サブエージェント用ツールを検索し、サブエージェント用パケットを渡して、範囲を限定したワーカーを起動してください。
• effectiveExecutor が manual の場合は、planweave run --executor manual ではなく、現在のエージェントのネイティブなサブエージェントワークフローを使って項目を割り当ててください。
• effectiveExecutor が現在のエージェントを示している場合は、PlanWeave の設定済みランナーを通じて同じエージェントを呼び出すのではなく、現在のエージェントのネイティブなサブエージェントワークフローを使って項目を割り当ててください。
• effectiveExecutor が別のエージェントを示している場合は、PlanWeave ランタイムを使ってその ref を実行し、設定済みランナー（CLI または ACP）に作業を担当させてください。Plan Package の割り当てを意図的に上書きする場合を除き、--executor <name> を追加しないでください。
• フィードバック要求でも、フィードバック要求の effectiveExecutor に同じルールを適用してください。値が manual または現在のエージェントの場合は、現在のエージェントのワーカーサブエージェントに割り当て、それ以外の場合は PlanWeave ランタイムを使用してください。
• PlanWeave ランタイムで現在のエージェント以外の実行担当者への委任に失敗した場合、ユーザーが実行担当者の上書きまたはフォールバックを明示的に許可しない限り、現在のエージェントで同じ ref を完了したり提出したりしないでください。ブロッカーを保持し、run-status／最新レコード／ログを確認してから、plan-recovery に割り当てるか、実行担当者の設定を修正して再試行してください。
• effectiveExecutor が manual または現在のエージェントである場合に限り、1 つの実装ブロックに対して plan-runner をワーカーサブエージェントに割り当ててください。
• effectiveExecutor が manual または現在のエージェントである場合に限り、1 つのレビューゲートに対して plan-reviewer をワーカーサブエージェントに割り当ててください。レビュー項目がタスクまたはパッケージのデフォルト設定を引き継いで opencode、claude-code、pi、またはその他の現在のエージェント以外の実行担当者になっている場合は、ローカルでレビューせず、PlanWeave ランタイムを通じて割り当ててください。
• plan-recovery をワーカーサブエージェントに割り当てるか、自分で復旧コマンドを実行するのは、doctor の検出結果、古い現在の ref、孤立した結果、状態／インデックスの不整合、ブロックまたは分岐した作業、あるいは提出の再試行に関する混乱がある場合に限ります。復旧に実装作業やレビュー作業を含めないでください。
• manual または現在のエージェントの作業にネイティブなサブエージェントツールを使用できない場合は、そこで停止して NEEDS_COORDINATOR と報告してください。コーディネーターのスレッドで plan-runner や plan-reviewer を直接実行しないでください。
• レビューゲートを、現在のエージェントの実装サブエージェントに割り当てないでください。ただし、これによって PlanWeave の実行担当者の割り当てが無効になるわけではありません。Plan Package がレビューゲートを現在のエージェント以外のランナープロファイルに割り当てている場合は、ランタイムからそのプロファイルに処理を振り分けてください。
• 復旧作業を通常の実装エージェントに割り当てないでください。

コーディネーターループ

1. 作業を割り当てる前に、現在の状態とステータスを確認します。
2. 既知の ref を割り当てる場合は明示的な claim を優先し、PlanWeave に選択させる場合にのみ自動 claim を使用します。
3. 自動スケジューリングをプレビューするには <pw> claim-next --dry-run --json を使用します。並列バッチをプレビューするには <pw> claim-next --parallel --dry-run --json を使用し、その後、各 ref の effectiveExecutors エントリに従ってバッチを分割します。
4. 割り当てる項目ごとに、ref、タスク、ブロックの種類、有効な実行者、プロンプトの参照元、submit コマンド、エージェントの担当者を記録します。ネイティブな現在のエージェントによる作業では、担当者はコーディネータースレッドではなく、サブエージェントの ID または名前でなければなりません。
5. 実行中のサブエージェントは、作業中のものだけにします。レポートの提出後、完了したエージェントを終了します。
6. アクティブなツールでサブエージェントの終了、アーカイブ、または停止を操作できる場合は、レポートを取得した後、完了、失敗、またはアイドル状態のサブエージェントを終了します。
7. 終了、アーカイブ、または停止の API がない場合は、非アクティブなエージェントのポーリングを停止し、終了したライフサイクル状態を記録します。終了したと示唆する表現は避けます。
8. submit のたびに、次の作業を割り当てる前に status/current を再実行します。
9. none の場合は、プランがアイドル状態だと判断する前に、並列と逐次の claim 可能性を比較します。
10. blocked、diverged、古い状態、または不整合がある場合は、依存する作業の割り当てを停止し、復旧対応に回します。

Claim の所有権

• コーディネーターがすでに ref を claim している場合、引き継ぎには already claimed と記載します。サブエージェントは claim または claim-next を実行してはいけません。
• サブエージェントが最初に claim する必要がある場合は、引き継ぎに claim required と記載し、正確な ref またはタスクを明示します。
• サブエージェントが割り当てとは異なる ref を claim した場合は、作業を停止し、実行前に調整します。

並列ディスパッチ

• 1 つのキャンバス内では、実行時に報告された ready、claimable、dispatchable の結果をスケジューリングの基準として使用します。コーディネーター側でスケジューラーのルールを再現しないでください。
• parallel.sharedResources は、ワーカーへの引き継ぎや重複に関する警告のための、ブロック要因にならない調整情報として扱います。これは、準備状況、claim 可能性、バッチ選択、または同時実行容量を変えるものではありません。
• 異なるキャンバスが自動的に並列になるわけではありません。キャンバス間の依存関係は、正式なプロジェクトグラフのキャンバスエッジと、project-graph.json が存在する場合は明示的な crossTaskEdges に基づく必要があります。
• 正式なプロジェクトグラフがない場合は、キャンバス間の並列実行を想定しないでください。キャンバスをまたいで作業を割り当てる前に、ユーザーまたはパッケージからの明示的な指示を求めます。
• 上流キャンバスのブロッカー、または明示的なクロスタスクブロッカーが未完了の間は、下流キャンバスの作業を割り当てないでください。
• status --json、claim-next --dry-run --json、または claim-next --parallel --dry-run --json を使用して次のバッチを作成し、その後 ref を明示的に割り当てます。
• プランで別途明示されていない限り、レビューゲートは逐次的な制御ポイントです。

サブエージェントへの引き継ぎパケット

サブエージェントへの引き継ぎには、必ず次の内容を含めます。

• 明示的な指示：Use skill: plan-runner、Use skill: plan-reviewer、または Use skill: plan-recovery。
• ブロック ref またはフィードバック ID、および claim の所有権：already claimed または claim required。
• ブロックの種類と必要なスキル：plan-runner、plan-reviewer、または plan-recovery。
• 有効な実行者、および他の PlanWeave 実行者ではなくこのエージェントに作業を割り当てる理由。
• レンダリング済みプロンプトのパスまたは内容、および関連する場合はソースプロンプトのパス。
• 必要なレポートまたは成果物の正確な指定。
• submit コマンド、または成果物をコーディネーターに返す指示。
• 検証コマンド、または客観的に確認可能な完了条件。
• 作業範囲と変更禁止のファイル。
• プラン更新の引き継ぎでは、CLI が返すワークスペースのパス、変更が必要な意味上のファイルの正確な指定、ならびにプロジェクトグラフの依存関係が変わる可能性がある場合の、キャンバス単位およびプロジェクト単位の検証コマンド。

ワーカーから成果物を受け取った後、コーディネーターがその成果物を submit することはできます。ただし、実装レポート、フィードバックレポート、またはレビュー結果の JSON を作成してはいけません。

Executor Run Monitoring

• 実行の runnerKind、機能、セッション ID、記録メタデータに基づいて、監視方法を選択します。
• <pw> run --once --scope block --block <ref> で現在のエージェント以外のエージェントに処理を委任した後、<pw> run-status --json と <pw> run-session <session-id> --json を確認します。継続するかどうかを判断する前に、実際のエグゼキューター、エージェント ID、ランナーの種類、順序付きランナー進捗、保留中の対話に関する診断情報、終了フェーズ／理由、最新の記録パスを検証します。
• 順序付きのランナー進捗をリアルタイムで確認するには、run-status --follow --json を使用します。
• 選択したランナーのトランスポートで実行を継続します。認証、クォータ、プロバイダー、権限、情報提供要求の境界は、その実行について返される機能と診断情報を通じて処理します。
• 実行時間に上限を設けて無人実行する場合は、run に明示的な正の値を持つ --timeout <ms> を指定します。タイムアウトと Ctrl-C は、選択したランナーのキャンセル／クリーンアップチェーンに到達する必要があります。
• すべてのトランスポートで、正規化されたランナーイベント、セッション状態、診断情報、記録成果物を主な証拠として使用します。
• ACP の実行では、順序付きランナーイベントを追跡し、ランタイムが提供する対話 ID と機能を使用して権限または情報提供の要求を解決します。
• CLI の実行では、実行記録に含まれるターミナル監視、アタッチコマンド、取得済み出力の成果物を使用します。
• 結果は、終了状態、メタデータ、診断情報、レポート／レビュー結果、成果物、送信状態に基づいて判断します。
• エグゼキューターの失敗、タイムアウト、古い現在の参照、レポートの欠落、送信状態の不整合がある場合は、依存するディスパッチを停止し、plan-recovery に振り分けます。

Remote Agent CLI Execution

CLI を使用して Remote Agent を選択し、呼び出します。

• <pw> agent-endpoints list --canvas <canvas-id> --connection-profile <profile-id> --json で利用可能な Agent を一覧表示します。
• <pw> run --once --target remote --scope block --block <ref> --agent-endpoint <endpoint-id> --connection-profile <profile-id> --event-format execution-v1 で 1 つのブロックを実行します。未公開のオーナーキャンバスでは、両方のコマンドに --authority owner_canvas を追加します。Workspace キャンバスでは、デフォルトの権限を使用します。
• 返されたセッションを <pw> run-session <session-id> --json で確認し、<pw> run-session <session-id> --follow --event-format execution-v1 --connection-profile <profile-id> で進捗を追跡します。中断後は同じセッションを続行し、最新の操作に置き換えてはいけません。
• 対話が保留中の場合は、<pw> interaction list --session <session-id> --connection-profile <profile-id> --json を使用し、続いて <pw> interaction respond --help に記載された応答引数を指定して <pw> interaction respond --session <session-id> を実行します。
• オプションについては、<pw> agent-endpoints list --help、<pw> run --help、<pw> run-session --help を参照してください。続行する前に認証または認可の失敗を解決してください。ユーザーの許可なく、それらを回避したりローカル実行に切り替えたりしてはいけません。

Review And Feedback

• レビューゲートは、順番に進む制御ポイントです。
• needs_changes のレビューでは、ランタイムのフィードバック作業が発生します。フィードバックへの対応を意図的に振り分けてから、レビューに戻ります。
• 実装への確信だけを根拠に、レビューを合格としてはいけません。
• 解決済みのフィードバックを、現在の作業として再送信してはいけません。
• レビューサイクルを使い切った場合や、内容に矛盾がある場合は、続行する前に plan-recovery に振り分けます。

復旧の境界

• ランタイム修復コマンドの実行、状態／結果の変更、または Plan Package の調整を行う前に、plan-recovery を使用してください。
• プランの不備と PlanWeave ツールチェーンの不備は分けて扱ってください。
• doctor は状態／結果の整合性を調べるプローブとして扱い、汎用的なプラン修復ツールとして使用しないでください。
• 依存関係の不備、並列化の誤り、プロンプトの欠落、またはレビュ​​ーゲートの設計上の問題がある場合は、依存するディスパッチを停止し、doctor --repair ではなく Plan Package の更新を引き継いでください。
• コーディネーターは project-graph.json、キャンバスの manifest.json、またはソースのプロンプト Markdown を直接編集してはいけません。作業者への引き継ぎには、対象パスと検証コマンドを含めてください。
• 部分的な成功、重複実行、古い current refs、または孤立した成果物を隠してはいけません。
• 差異の解消にパッケージの変更が必要な場合は、パッケージの調整が完了するまで、依存する実行を一時停止してください。

完了レポート

停止する際は、以下を報告してください。

• 完了した refs と提出済みの成果物。
• 未完了の refs、ブロッカー、または差異。
• 実行した検証。
• 実施した復旧アクション。
• 次のアクションが claim、review、recovery、プランのインポート／更新、またはユーザーの判断のいずれであるか。