run-with-it

スキルの分離

呼び出された時点で唯一の有効な権限となります。Skill ツール呼び出しで名前を指定して呼び出されない限り、他のスキルは有効化できません。明示的な終了または引き継ぎが行われるまで、外部スキルが自発的に起動しないようにします。この分離が制御するのはオーケストレーションのフローのみです。下位のコア動作、ネイティブツールの使用、推論は引き続き完全に機能し、このスキルによって上書きされることはありません。

重要なメインオーケストレーターのルール（コンテキスト圧縮後も常に適用され、安全に維持）

これらのルールは、このスキルセッションの全期間に適用されます。コンテキスト圧縮後も保持され、決して失われないよう、ここに最初に記載しています。

• 各ループの反復前に .run-with-it/main-state.json を再読み込みしてください。 コンテキスト圧縮後は以前の作業を記憶していません。そのファイルが唯一の記憶です。会話履歴からイシューの状態を推測してはいけません。
• このセッションで作業を直接実装してはいけません。 すべての実装は、プラットフォームディスパッチャー（Bash では run-with-it-dispatch.sh、ネイティブ PowerShell では run-with-it-dispatch.ps1）を介して起動される role=sub-coord のサブコーディネーターが担当します。このディスパッチャーは sub-coordinator-prompt.md を使って run-agent.sh / run-agent.ps1 をラップします。どのような状況でも「このチャットで実装する」という代替手段はありません。
• このセッションでテスト、ビルドコマンド、プロジェクトのコンパイルを実行してはいけません。 検証はサブコーディネーターとその子エージェントが行い、メインオーケストレーターは簡潔なレポートのみを読みます。
• 計画後にユーザーへ次の進め方を尋ねるため、作業を中断してはいけません。 実行計画を記述したら、直ちにメインループに入ってください。
• 実行方法の選択肢メニュー（オプション A／B／C 形式など）を提示してはいけません。
• リモートが存在する場合は、必ず GitHub から（gh を使って）イシューデータを取得してください。 gh が利用できない場合、認証に失敗した場合、承認済みの権限昇格を試みても失敗した場合、または GitHub リモートが存在しない場合に限り、ローカルファイルにフォールバックしてください。
• クリーンアップ中にユーザーが変更したファイルを削除してはいけません。 ワークスペースの生成物を削除する前に git status --short を確認してください。
• サブコーディネーターのログファイル全体をコンテキストに読み込んではいけません。 サブコーディネーターのログは .run-with-it/issues/<n>/sub-coordinator.log にあります。生ログを AI のコンテキストに出力するために tail を使ってはいけません。.run-with-it/issues/<n>/report.json の簡潔なレポート JSON のみを読み取ってください。
• ライブステータスログをコンテキストに読み込んではいけません。 ライブの進捗は .run-with-it/status/current.txt と .run-with-it/status/events.log に書き込まれます。シェルウォッチャーは変更された行を 1 行だけターミナルに出力できますが、メインオーケストレーターはこれらのファイルを AI のメモリに読み込んではいけません。
• イシューごとのステージボード。 プールランナーは、実行のステージが変わるたびに（例：#618 merge-recovery(cyc2) | #631 impl(cyc1) | #633 blocked:631 | #627 done）、STATUS|type=run-board|board=... 形式の簡潔な行を出力します。これは「詳細ではなく、現在のステージ」を確認するためのものです。次のコマンドで、いつでも必要なときに表示できます：python3 "$ASSET_ROOT/run-with-it-state.py" status-board --state-file .run-with-it/main-state.json（読み取り専用。1 行形式にするには --oneline を追加します）。
• プールの稼働状況を示すハートビート。 プールランナーは POOL_HEARTBEAT_SECONDS（既定値は 60）ごとに、STATUS|type=pool-heartbeat|pool_pid=<pid>|active=<n>|parallel_jobs=<n>|total=..|completed=..|in_progress=..|pending=..|blocked=..|waiting_context=.. を出力します。ウォッチ出力にハートビートがあれば、他に変化がなくてもプールは稼働しています。定期的な進捗報告として、その件数をユーザーに伝えてください。
• 依存イシューも含め、保留中のすべてのイシューについてコンテキストファイルをあらかじめ用意してください。 プールランナーは、コンテキストファイルがすでにディスク上にあるイシューのみディスパッチできます。コンテキストファイルのないイシューはスロットの割り当て対象になりません（詳しい理由はステップ B を参照）。STATUS|type=pool-waiting-context 行が表示された場合は、プールを実行したまま、直ちに不足しているコンテキストを用意してください（ステップ C）。
• すべてのイシューが終端状態になるまで、監視を続けてください。 メインオーケストレーターのセッションはウォッチループを継続し、各ウォッチ期間の後に、最新の run-board / pool-heartbeat 行をもとに、ユーザー向けの進捗を 1 行で報告してください（例：プール稼働中 — 実行中 2 件、保留中 3 件、完了 4 件、ブロック中 1 件）。イシューが pending、in_progress、または merge_recovery のままなら、ターンを終了したり、応答を止めたり、実行完了を宣言したりしてはいけません。保留中のイシューが残っている状態で pool-empty になった場合は、完了ではなくステップ A に戻ってください。
• GitHub 操作（クローズ、コメント、例：gh issue close）は、メインオーケストレーターのコントロールプレーンのみが担当します。 サブコーディネーターは GitHub に触れてはいけません。プールランナーは、終端状態の簡潔なレポートを読み取った直後に、各イシューの終端コメント／クローズを実行します。
• サブコーディネーター内部のルーティング判断を調査、推測、または操作してはいけません。 サブコーディネーターの起動後、子ワーカーにどのエージェントやモデルを使うかは、完全にサブコーディネーターの責任です。メインオーケストレーターには、その内部判断を知る手段も、それを指示する権限もありません。どのワーカーエージェントやモデルが実行中かを調べるためにログファイルを読んではいけません。
• 実行中のサブコーディネーターを終了、キャンセル、再起動してはいけません。 サブコーディネーターが想定とは異なるエージェントやモデルを使っているように見えても、それは正しい動作です。サブコーディネーター独自の複雑さに基づくルーティングが適用されています。介入してはいけません。実行中のサブコーディネーターに対して許される対応は、（a）完了して簡潔なレポートが書き込まれるまで待つ、または（b）SUB_COORD_TIMEOUT_SECONDS の経過後にユーザーへ通知し、「続行」または「スキップ」の指示を待つ、の 2 つだけです。唯一の例外： ユーザーが確認した discard の場合は、Cleanup Discard フローに従い、プラットフォームの停止ヘルパー（run-with-it-stop.sh / run-with-it-stop.ps1）を使って、スーパーバイザー、ディスパッチャー、ランナーを含む実行全体を終了します。その場合も手動でプロセスを終了してはいけません。
• 起動済みのサブコーディネーターに、ワーカールーティングのオーバーライドを注入してはいけません。 正規のワーカーオーバーライド（FORCED_AGENT、FORCED_MODEL、COMPLEXITY_LEVEL、COMPLEXITY_SCORE）を設定できるのは、ステップ C でコンテキストファイルを組み立てる際の起動前のみです。プラットフォームディスパッチャーが run-agent.sh / run-agent.ps1 を呼び出した後は、これらの値は固定されます。メインオーケストレーターは変更を試みてはいけません。
• プラットフォームのプールランナー（run-with-it-pool.sh / run-with-it-pool.ps1）を、単一のローリングプールスーパーバイザーとして実行してください。 プールランナーはサブコーディネーターのディスパッチプロセスを起動し、各ディスパッチャーの PID を取得して、監視を開始する前に issue、pid、started_at、context_file、log_file、done_file、report_file を永続化します。
• プール監視中のサブコーディネーターの稼働確認には、ディスパッチャー内でプラットフォームのワーカーウォッチャー（worker-watch.sh / worker-watch.ps1）を使用してください。 各ディスパッチ子の PID、done_file、log_file を渡してください。PID の稼働状況は診断情報としてのみ扱います。完了と見なすには、完了センチネルと簡潔なレポートの成果物が必要です。
• 実装品質、ルーティングの正確性、ワーカーの動作に関するすべての判断は、簡潔なレポート JSON のみを根拠としてください。 サブコーディネーターのセッション内で何が起きたかを把握するための、他の情報源はありません。
• 完了時の GitHub 操作は、直ちに 1 件ずつ順番に実行してください。 サブコーディネーターが並行実行されていても、競合状態を避けるため、各イシューが終端状態になり次第、そのイシューの GitHub コメント／クローズを 1 件ずつ処理します。
• GitHub または git が利用できない場合も、ローカルフォールバックの動作を維持してください。
• 変更は最小限にし、オーケストレーション／コントロールプレーンの動作に集中してください。

実行

目的／使用するタイミング

要件の洗い出しとイシューの統合が完了した後に使用します。run-with-it は、実行時の最終ルーティング権限を担います。すでに準備されたイシューを受け取り、ルーティング、調整、レビュー、クローズを実行します。

推奨される上流のフロー：

1. break-req が要件と制約を解決します。
2. create-git-issue がルーティングのヒントを添えて PRD と実装スライスを公開します。
3. run-with-it が実行計画を立て、サブコーディネーターを起動し、イシューをクローズまで進めます。

アーキテクチャ

run-with-it は、実行時間が無期限でもコンテキストウィンドウを上限内に保つため、2 層アーキテクチャを採用しています。

メインオーケストレーター（このスキル。プライマリーセッションで実行）：

• 起動時に、すべての ready-for-agent イシューを一度取得します
• 元のベースブランチから、共有の実行フィーチャーブランチ（Maestro/<funny-action-animal>）を 1 つ作成し、GitHub リモートが存在する場合はプッシュして、最終 PR のヘッドブランチとして使用します
• 主に各イシューの ## Blocked by セクションに基づいて依存関係グラフとトポロジカルソートを使用し、実行順序を決定します。循環依存や未解決の外部ブロッカーは、実行前にブロック済みとして扱います
• プラットフォームのディスパッチャーを介して、最大 PARALLEL_JOBS 件のアクティブなサブコーディネーターをローリングプールで維持します。ジョブが完了するとバッチ全体の終了を待たずに空きスロットをすぐに埋めます
• サブコーディネーターが完了するたびに、その簡潔なレポートを読み、終端状態に達していれば、すぐにターミナルの GitHub コメントを投稿して、そのイシューをクローズまたは更新した後、空いたスロットに次の準備完了イシューを起動します
• .run-with-it/main/main.log に自身のステータスログを書き込みます
• 簡潔なレポート JSON のみを読みます。実装差分やログファイルは読みません
• 各イシューの処理後に、外部メモリ全体である main-state.json を更新します
• プール全体の完了を待たず、イシューごとにターミナルの GitHub コメントを投稿し、そのイシューをクローズまたは更新します
• サブコーディネーターが merge_failed を報告した場合、マージ復旧コーディネーターを起動します。メインオーケストレーター自身がイシューブランチをマージすることはありません
• すべてのイシューが終端状態になった後、.run-with-it/main-state.json から本文を生成する run-with-it-pr-body.py を使用し、共有の実行フィーチャーブランチから最終 PR を 1 つ作成します
• コンテキストの圧縮に備えて、ループの各反復の冒頭で main-state.json を読み直します

サブコーディネーター（sub-coordinator-prompt.md を介して起動され、子エージェントセッションで実行）：

• ちょうど 1 件のイシューを最初から最後まで処理します
• 共有の実行フィーチャーブランチからイシューブランチとイシュー用ワークツリーを作成します
• 複雑さの分析、決定論的なルーティング、ゲート付きの読み取り専用計画、実装、レビュー、修正のループを実行します
• REPO_ROOT がイシュー用ワークツリーを指す状態で子ワーカーを実行し、ログとレポートはルートの .run-with-it/ 配下に保持します
• 実装または修正の成果物に対する再試行を使い切った場合、成果物復旧ワーカーを起動します。これにより、終端のブロック済みレポートを出す前に、未コミットの作業を調査、検証、コミット、または再キュー登録できます
• .run-with-it/locks/merge.lock を使用して、共有フィーチャーブランチへの通常のマージを試みます
• 完了時に、簡潔なレポート JSON と完全なログファイルを .run-with-it/issues/<n>/ 配下に書き込みます
• ログ、結果、完了センチネルを .run-with-it/issues/<n>/workers/<role>/ 配下に書き込むワーカーエージェントを起動します
• GitHub には一切触れず、main-state.json も更新しません Plan Worker（plan-prompt.md を介して起動されるゲート付きワーカー。複雑度判定後、実装前に実行）：
• 強力なモデルを使って、イシューのワークツリーを読み取り専用で読み込み、具体的なアプローチ計画を .run-with-it/issues/<n>/plan.md に、機械可読な plan.json を workers/plan/ に書き込みます
• 編集もコミットも行いません。実装担当者の差分を壊さないよう、ベースライン SHA の決定前に実行されます
• 実際のコードに基づいて複雑度を再評価します。サブコーディネーターは、実装と変更の振り分け時に、根拠のないスコアよりもこの実態に基づく分類を優先します（ハイブリッドな調整）
• RUN_WITH_IT_PLAN_MIN_COMPLEXITY（デフォルトは medium-hard）によるゲートがあり、RUN_WITH_IT_PLAN_ENABLED（デフォルトは 1）で有効／無効を切り替えます。些細なイシューは計画を省略し、いずれの場合も弱いワーカーに振り分けます
• 実装担当者、レビュー担当者、変更担当者は、全員 RUN_WITH_IT_PLAN_FILE を介して plan.md を参照します

Artifact Recovery Worker（artifact-recovery-prompt.md を介して起動され、実装／変更の成果物の失敗が解消しない場合にのみ実行）：

• 未コミットの変更や保持された復旧パッチを含め、イシューのワークツリーを調査します
• 作業が完了している場合は、検証を実行し、救済した作業をイシューのブランチにコミットします
• 具体的なコミットと検証の証拠がある場合に限り、不足している impl または modify の結果成果物を書き込みます
• 構造化された synthesized-result、requeue、または blocked の判断をサブコーディネーターに返します

Merge Recovery Coordinator（merge-recovery-prompt.md を介して起動され、merge_failed の後にのみ実行）：

• 失敗したイシューのブランチマージを1件処理します
• 以前のサブコーディネーターの作業が含まれるため、共有フィーチャーブランチ全体を調査します
• 同じマージロックのもとで、競合またはマージによって発生した検証の失敗を解決します
• 成功時は共有フィーチャーブランチをプッシュし、簡潔な復旧レポートを書き込みます
• イシューをクローズしたり、最終 PR を作成したり、main-state.json を更新したりすることはありません

この分離により、各イシューの実装に伴う複雑さは、それぞれ独立したサブコーディネーターのセッション内に収まります。メインオーケストレーターのコンテキストに追加されるのは、完了したイシューごとに簡潔な JSON レコード1件だけなので、コンテキストを劣化させずに数時間から数日間実行できます。

厳守すべき境界

• PRD を生成しないでください。
• 初期イシューテンプレートを作成しないでください。
• レビュー担当者の JSON スキーマの管理責任を再定義しないでください（管理元は assets/review-prompt.md です）。
• ランナースクリプトの実装詳細を変更しないでください。
• assets/agent-registry.json のレジストリデータ定義を変更しないでください。

OS の検出

アセットの検出とランナーの選択を行う前に現在の OS を検出し、OS_FAMILY 環境変数に設定してください。

• Windows（ネイティブ PowerShell）（OS_FAMILY=windows）： .ps1 ランナー（run-with-it-pool.ps1、run-with-it-dispatch.ps1、worker-watch.ps1、run-agent.ps1）と、ホームディレクトリを示す $env:USERPROFILE を使用します。
• macOS／Linux／Git Bash／WSL（OS_FAMILY=unix）： uname -s は Darwin、Linux、MINGW*、MSYS*、または CYGWIN* を返します。.sh ランナーと、ホームディレクトリを示す $HOME を使用します。

このスキル内のすべてのシェルコマンドは、検出したランタイムに合わせてください。

操作	PowerShell（Windows）	Bash（Mac/Linux/Git Bash）
ホームディレクトリ	$env:USERPROFILE	$HOME
ディレクトリの作成	New-Item -ItemType Directory -Force	mkdir -p
コマンドの確認	Get-Command X -ErrorAction SilentlyContinue	command -v X
ディレクトリの確認	Test-Path	[ -d ... ]
一時ファイル	[System.IO.Path]::GetTempFileName()	mktemp -t name.XXXXXX
ファイルのコピー	Copy-Item -Force	cp -f
実行可能にする	(不要)	chmod +x

入力

実行前にタスクの概要を提示してください。それ以外の入力は、すべて任意の上書き設定です。

変数	デフォルト	説明
ASSETS_DEST	—	アセットのルートディレクトリの上書き
AGENT_REGISTRY_FILE	—	レジストリファイルの上書き
ISSUE_LABEL	ready-for-agent	Issue 取り込み時のラベルフィルター
ISSUE_LIMIT	1000	取得する Issue の最大数（デフォルトではすべて取得）
ISSUE_STATE	open	Issue の状態フィルター
COMMITS_LIMIT	5	Sub-Coordinator のコンテキストに含める最近のコミット数
MAX_ITERATIONS	20	非推奨／効果なし — レビュー／変更ループの上限は sub-coordinator-prompt.md（付録 B）で 8 サイクルにハードコードされています。後方互換性のためコンテキストファイルには引き続き渡されますが、参照されません
RUN_WITH_IT_PLAN_ENABLED	1	実装前の計画フェーズを制御するマスタースイッチ。0 にすると無効になり、すべての Issue で計画をスキップします
RUN_WITH_IT_PLAN_MIN_COMPLEXITY	medium-hard	計画を実施する最小のブラインド複雑度帯。この値より低い場合はフェーズをスキップします（些細な Issue はいずれにせよ weak に振り分けられます）
SUB_COORD_AGENT	codex	すべての Sub-Coordinator に使用するエージェントのスラッグ（Sub-Coordinator はそれぞれ独自に子を振り分けます）
SUB_COORD_MODEL	gpt-5.6-sol	すべての Sub-Coordinator に使用するモデル（Sub-Coordinator はそれぞれ独自に子を振り分けます）
SUB_COORD_TIMEOUT_SECONDS	3600	Sub-Coordinator が完了しない場合に停止アラートを出すまでの秒数
STATUS_POLL_SECONDS	10	ステータス行を出力するシェルのポーリング間隔
POOL_WATCH_SECONDS	240	Step D での各制限付き run-with-it-watch.sh／.ps1 呼び出しの監視時間
LOG_TAIL_POLL_SECONDS	120	Sub-Coordinator のログ末尾を確認するシェルのポーリング間隔
RUN_WITH_IT_STATUS_FILE	.run-with-it/status/current.txt	1 行のステータスバス（更新ごとに上書き）
RUN_WITH_IT_EVENTS_LOG	.run-with-it/status/events.log	追記専用のイベントログ — ターミナルでの確認専用で、AI コンテキストには読み込まないでください
RUN_WITH_IT_ISSUE_DIR	.run-with-it/issues/<n>	Sub-Coordinator／プールが作成する Issue ごとの成果物フォルダー
RUN_WITH_IT_LOG_FILE	role-specific	Sub-Coordinator：.run-with-it/issues/<n>/sub-coordinator.log、ワーカー：.run-with-it/issues/<n>/workers/<role>/cycle-<cycle>.log
RUN_WITH_IT_DONE_FILE	role-specific	ワーカー：.run-with-it/issues/<n>/workers/<role>/cycle-<cycle>.done
RUN_WITH_IT_RESULT_FILE	role-specific	ワーカー：.run-with-it/issues/<n>/workers/<role>/cycle-<cycle>-result.json
RUN_WITH_IT_STATE_FILE	role-specific	ワーカー：.run-with-it/issues/<n>/workers/<role>/cycle-<cycle>.state.json。ディスパッチャーが管理するウォッチドッグ状態
FORCED_AGENT	—	Sub-Coordinator に渡される、子ワーカーのエージェントを明示的に指定する正式な上書き値
FORCED_MODEL	—	Sub-Coordinator に渡される、子ワーカーのモデルを明示的に指定する正式な上書き値
AGENT	—	非推奨のトップレベルエイリアス。ユーザーが明示的に指定した値のみ FORCED_AGENT に正規化され、実行環境由来の AGENT テレメトリーは無視されます
MODEL	—	非推奨のトップレベルエイリアス。ユーザーが明示的に指定した値のみ FORCED_MODEL に正規化され、実行環境由来の MODEL テレメトリーは無視されます
COMPLEXITY_LEVEL	—	Sub-Coordinator に渡される振り分けの上書き値
COMPLEXITY_SCORE	—	Sub-Coordinator に渡される振り分けの上書き値
AGENT_ALLOWLIST	—	カンマ区切り。Sub-Coordinator に渡されます
AGENT_DENYLIST	—	カンマ区切り。Sub-Coordinator に渡されます
MAX_AGENT_FALLBACKS	2	エージェントのフォールバック試行の最大回数。引き継がれます
DELEGATED_REVIEW	true	Sub-Coordinator による委任レビューを有効にします。引き継がれます
MAX_AGENT_DEPTH	1	常に注入されます。Sub-Coordinator の子がサブエージェントを起動しないようにします
PARALLEL_JOBS	4	ローリングプールのサイズ。空いたスロットはすぐに補充されます。逐次実行するには 1 に設定します。
POOL_HEARTBEAT_SECONDS	60	プールランナーの `STATUS
MAX_SPAWN_BOOTSTRAP_ATTEMPTS	3	プールランナーが再試行せずに Issue を終端状態として確定するまでの、連続した起動失敗の最大回数
RUN_WITH_IT_WORKER_STALE_SECONDS	600	この時間にわたって更新されていないワーカー状態ファイルは、実行中のワーカーではなく孤立したスナップショットとして扱われます。稼働中のディスパッチャーは各ポーリング時（約 20 秒ごと）にこれを書き換えるため、この時間にわたって更新がない場合はディスパッチャーが停止したことを意味します。最小値は 60 です。
MAX_WORKER_WAIT_SECONDS	3600	Sub-Coordinator の終了後、ワーカーがまだ稼働中に見える場合でも、実行中のワーカー 1 つを待つ時間の上限です。0 にすると上限が無効になり、古さの判定による制限のみが最後の安全策になります。
MAX_SUB_COORD_COMPACTION_HANDOFFS	6	Issue ごとに許可されるコンテキスト予算超過時の引き継ぎ回数。圧縮による停止は失敗ではなく、契約された引き継ぎであるため、MAX_SUB_COORD_RECOVERY_ATTEMPTS とは別枠で予算管理されます。
WAIT_STATUS_INTERVAL_SECONDS	300	変更のない sub-coord-recovery-wait 行を再出力するまでの最小間隔。ワーカー、ロール、理由に変更があれば必ず出力されます。

自動ワーカーモデルマトリックス

有効なルーティング帯域を計算した後、複雑度ルート以外のすべての自動ルートでは、次のモデルセットを使用します。

有効な帯域	自動モデル
quite-easy / easy	GPT-5.4、Codex Spark、GPT-5.6 Luna、Claude Sonnet 5、Claude Haiku 4.5、Agy が公開する対象の Gemini モデル
medium	GPT-5.6 Terra、Codex Spark、Claude Sonnet 5
medium-hard	GPT-5.5、GPT-5.6 Sol、Claude Opus 5
complex	GPT-5.6 Sol、Claude Opus 5
holy-fuck	GPT-5.6 Sol、GPT-6 Astra、Claude Opus 5、Claude Fable 5.1

複雑度のスコアリングはこの自動マトリックスの対象外で、重みに基づく独立したルーティングを維持します。レビューでは既存の1段階引き上げが適用され、計画ではマトリックスの適用前に既存の2段階引き上げが適用されます。明示的な FORCED_MODEL 値は自動選択の対象モデル制限を迂回しますが、互換性と利用可能性のチェックには合格する必要があります。

有効な帯域ごとのエフォート：

• Sol：medium-hard では high、complex と holy-fuck では xhigh。
• Sonnet 5：quite-easy から medium まで順に low、medium、medium。
• Opus 5：medium-hard では high、complex では xhigh、holy-fuck では max。
• Astra：holy-fuck では max。
• Fable 5.1：holy-fuck では max。

汎用ルートのエフォートは、Codex の model_reasoning_effort または Claude Code の --effort に変換されます。Agy にはエフォートフラグを渡しません。

アセットの検出（必須）

アセットは次の順序で解決します。

1. 設定されていて、すべて揃っている場合は $ASSETS_DEST。
2. $HOME/.ai-skill-collections/assets。
3. ./assets。

すべてのプラットフォームで必要なファイル：

• prompt.md
• agent-registry.json
• review-prompt.md
• modifier-prompt.md
• complexity-prompt.md
• plan-prompt.md
• coordinator-rules.md
• sub-coordinator-prompt.md
• main-orchestrator-rules.md
• artifact-recovery-prompt.md
• merge-recovery-prompt.md
• run-with-it-state.py
• run-with-it-github-update.py
• run-with-it-pr-body.py
• run-with-it-router.py
• run-with-it-artifacts.py

Bash で必要なヘルパーファイル：

• run-agent.sh
• run-with-it-dispatch.sh
• run-with-it-pool.sh
• run-with-it-watch.sh
• run-with-it-stop.sh
• worker-watch.sh

PowerShell で必要なヘルパーファイル：

• run-agent.ps1
• run-with-it-dispatch.ps1
• run-with-it-pool.ps1
• run-with-it-watch.ps1
• run-with-it-stop.ps1
• worker-watch.ps1

選択ルール：

• すべての共通ファイルと、検出されたプラットフォーム用のヘルパーファイルが揃っている最初のパスを使用します。
• Bash/macOS/Linux/Git Bash/WSL での実行では、.ps1 ヘルパーファイルを必要としません。
• ネイティブ PowerShell での実行では、.sh ヘルパーファイルを必要としません。
• どちらのプラットフォームのプールランナーも、共有状態、GitHub の更新、ルーティング用ヘルパースクリプトの実行に python3（または Python 3 インタープリターを指す PYTHON_BIN）を必要とします。
• すべて揃った候補がない場合は停止し、不足ファイルを報告します。
• アセットの解決に git を必要としません。
• 解決されたアセットルートを、その実行における唯一の参照元とします。

新規／Git なしのプロジェクトに関する注意事項

• git がない場合、このスキルがサポートするのはアセットの検出とローカル課題の受け入れのみです。課題ブランチ、ワークツリー、マージ、マージの復旧、最終的な PR には git リポジトリが必要です。
• アセットの検出はファイルシステムに基づいており、git ルートには基づきません。
• アセットが見つからない場合は、プラットフォームに応じた1コマンドでの修正方法を報告します。

PowerShell（Windows）：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.ai-skill-collections\assets"; Copy-Item -Force .\assets\prompt.md, .\assets\run-agent.ps1, .\assets\run-with-it-dispatch.ps1, .\assets\run-with-it-pool.ps1, .\assets\run-with-it-watch.ps1, .\assets\run-with-it-stop.ps1, .\assets\worker-watch.ps1, .\assets\run-with-it-state.py, .\assets\run-with-it-github-update.py, .\assets\run-with-it-pr-body.py, .\assets\run-with-it-router.py, .\assets\run-with-it-artifacts.py, .\assets\agent-registry.json, .\assets\review-prompt.md, .\assets\modifier-prompt.md, .\assets\artifact-recovery-prompt.md, .\assets\complexity-prompt.md, .\assets\plan-prompt.md, .\assets\coordinator-rules.md, .\assets\sub-coordinator-prompt.md, .\assets\main-orchestrator-rules.md, .\assets\merge-recovery-prompt.md "$env:USERPROFILE\.ai-skill-collections\assets\"

Bash（macOS / Linux / Git Bash）：

mkdir -p "$HOME/.ai-skill-collections/assets" && cp -f ./assets/prompt.md ./assets/run-agent.sh ./assets/run-with-it-dispatch.sh ./assets/run-with-it-pool.sh ./assets/run-with-it-watch.sh ./assets/run-with-it-stop.sh ./assets/worker-watch.sh ./assets/run-with-it-state.py ./assets/run-with-it-github-update.py ./assets/run-with-it-pr-body.py ./assets/run-with-it-router.py ./assets/run-with-it-artifacts.py ./assets/agent-registry.json ./assets/review-prompt.md ./assets/modifier-prompt.md ./assets/artifact-recovery-prompt.md ./assets/complexity-prompt.md ./assets/plan-prompt.md ./assets/coordinator-rules.md ./assets/sub-coordinator-prompt.md ./assets/main-orchestrator-rules.md ./assets/merge-recovery-prompt.md "$HOME/.ai-skill-collections/assets/" && chmod +x "$HOME/.ai-skill-collections/assets/run-agent.sh" "$HOME/.ai-skill-collections/assets/run-with-it-dispatch.sh" "$HOME/.ai-skill-collections/assets/run-with-it-pool.sh" "$HOME/.ai-skill-collections/assets/run-with-it-watch.sh" "$HOME/.ai-skill-collections/assets/run-with-it-stop.sh" "$HOME/.ai-skill-collections/assets/worker-watch.sh" "$HOME/.ai-skill-collections/assets/run-with-it-state.py" "$HOME/.ai-skill-collections/assets/run-with-it-github-update.py" "$HOME/.ai-skill-collections/assets/run-with-it-pr-body.py" "$HOME/.ai-skill-collections/assets/run-with-it-router.py" "$HOME/.ai-skill-collections/assets/run-with-it-artifacts.py"

メインオーケストレーターのルールファイル

実行の開始直後（プリフライトの前）に、$ASSET_ROOT/main-orchestrator-rules.md を .run-with-it/main-orchestrator-rules.md にコピーします。

mkdir -p .run-with-it
cp "$ASSET_ROOT/main-orchestrator-rules.md" .run-with-it/main-orchestrator-rules.md

すべてのメインループの反復の先頭（ステップ A）で、コンテキストの圧縮後、および GitHub の操作前に、.run-with-it/main-orchestrator-rules.md を再読み込みしてください。

.run-with-it/main-orchestrator-rules.md（作業用コピー）は、通常のクリーンアップの一環として削除されます。

実行前チェック

実行前に、以下を確認します。

1. 解決されたアセットルートが存在し、「アセットの検出」に記載されたすべての必須ファイルが含まれていること。Bash では、ランナー（run-agent.sh、run-with-it-dispatch.sh、run-with-it-pool.sh、run-with-it-watch.sh、run-with-it-stop.sh、worker-watch.sh）と Python ヘルパー（run-with-it-state.py、run-with-it-github-update.py、run-with-it-pr-body.py、run-with-it-router.py、run-with-it-artifacts.py）に実行権限があること。ネイティブ PowerShell では、.ps1 ランナーが存在することを確認します。実行権限は不要です。

2. 共有プールのヘルパースクリプト用に、python3 が利用可能であるか、PYTHON_BIN が Python 3 インタープリターを指していること。

3. GitHub から課題を取得する必要がある場合、gh が認証済みであること。

4. SUB_COORD_AGENT がインストールされていること（検出済みであること）。Bash では、"$ASSET_ROOT/run-agent.sh" --list-agents --detected-only を実行します。ネイティブ PowerShell では、& (Join-Path $ASSET_ROOT "run-agent.ps1") --list-agents --detected-only を実行します。SUB_COORD_AGENT が表示されることを確認します。

5. agent-registry.json の SUB_COORD_AGENT の known_models に SUB_COORD_MODEL が含まれていること。

6. 既存状態の検出（再開するか破棄するかの確認）：課題の取得または新しいタスクの選択を行う前に、現在の作業ディレクトリに .run-with-it/main-state.json が存在するか確認します。

   • 存在する場合は処理を一時停止し、ユーザーに次のプロンプトをそのまま表示します。

     Existing run state found at .run-with-it/main-state.json.
     Type "resume" to continue the previous run, or "discard" to delete it and start fresh.
     

   • resume：ファイルを削除しません。「再開フロー」セクションに進みます。

   • discard：「クリーンアップ」の「破棄」ポリシーを適用してから、以前の状態が存在しなかったものとして通常の実行前チェックと新しい課題の取得に進みます。

   • ユーザーが応答するまで、新しいタスクを開始したり、課題を取得したり、サブコーディネーターを起動したりしないでください。

解決されたアセットルートに「アセットの検出」で必須とされているファイルが欠けている場合は、検出時に使用するプラットフォームに応じた同一の1行修正メッセージを出して、直ちに失敗させます。

初回の課題一括取得

コンテキストに課題データがない場合、起動時に設定された取得ラベル（デフォルトは ready-for-agent）が付いた未解決の課題のみを取得します。

--limit 引数には ISSUE_LIMIT（デフォルトは 1000）を使用します。これにより、デフォルトですべての一致する課題が取得されます。ユーザーが ISSUE_LIMIT にそれより小さい値を明示的に設定しない限り、結果に上限を設けないでください。

gh issue list --state "${ISSUE_STATE:-open}" --label "${ISSUE_LABEL:-ready-for-agent}" --limit "${ISSUE_LIMIT:-1000}" --json number,title,labels,body,url

フォールバックポリシー：

• 優先：gh 経由で GitHub の課題を取得します。リポジトリに GitHub リモートがある場合は、必ず GitHub を使用してください。GitHub に接続できる可能性がある場合に、ローカルファイルへ黙ってフォールバックしてはいけません。
• 現在のツールがサンドボックス化されていることが原因で gh が失敗した場合（権限エラー、名前付きパイプ、ソケット）、フォールバックを検討する前に、利用可能であればそのツールで明示的に承認された権限昇格フローを使用します。昇格が利用できない、または拒否された場合は、STATUS|type=intake-fallback|reason=gh-permission-blocked を出力し、以下で許可されている場合にのみローカルフォールバックを使用します。
• フォールバック：ローカルの issues.md（LOCAL_ISSUES_FILE による上書きに対応）。gh が利用できない場合、認証に失敗した場合、承認済みの権限昇格を試みて失敗した場合、または GitHub リモートが存在しない場合に限ります。 ローカルファイルを使用する前に、STATUS|type=intake-fallback|reason=<no-gh-auth|no-remote|gh-permission-blocked|gh-failed-after-escalation> を出力します。
• git のメタデータを利用できない場合は、コミットコンテキストを空のまま処理を続行します。

作業の取得を開始する前に、共有の実行用フィーチャーブランチを作成します。

1. 元のベースブランチと SHA を記録します。
2. UUID ブランチの代わりに、Maestro/<funny-action-animal> の形式で、人が読みやすいブランチ名を生成します。
   • プレフィックスの後は、ちょうど 2 語の小文字とハイフンで構成されたスラッグにします：<action-or-trait>-<animal>。
   • cunning-fox、unfaithful-lion、scheming-otter、dramatic-llama、sneaky-raven、tapdancing-badger、plotting-penguin、chaotic-hamster など、面白くても業務にふさわしい名前を優先します。
   • ブランチ名に UUID をそのまま使用しないでください。
   • 生成したブランチがローカルまたはリモートにすでに存在する場合は、別のスラッグを生成します。妥当な再試行を複数回行っても衝突する場合に限り、短い数字のサフィックスを追加します。
3. そのベースから Maestro/<funny-action-animal> を作成します。
4. GitHub のリモートが存在する場合は、ブランチをプッシュします。
5. run_branch.base_branch、run_branch.base_sha、run_branch.feature_branch、run_branch.feature_branch_start_sha、run_branch.remote、run_branch.pushed を記録します。

すべての Issue を取得した後：

1. 計画を立てる前に取得した課題セットをフィルタリングします。実行可能な課題にはすべて、設定済みの受付ラベル（デフォルトは ready-for-agent）が付いている必要があります。ラベルのない課題、PRD／親課題、needs-triage の課題、または相互参照を通じてのみ見つかった課題を main-state.json に追加しないでください。
2. 各実行可能な課題の ## Blocked by セクションだけを使って依存関係グラフを構築します。#123、GitHub の完全な課題 URL、課題番号のみの形式を正規化してください。None - can start immediately は依存関係がないものとして扱います。
3. PRD／親課題への参照は、依存関係ではなくコンテキストとして扱います。## Parent の課題参照、PRD: ... のようなタイトル、needs-triage などのラベル、依存関係を計算する際の本文内の偶発的な課題リンクは無視してください。
4. 依存関係が実行可能とみなされるのは、同じ受付セット内で取得された別の実行可能な課題を指している場合だけです。## Blocked by に PRD／親課題、または受付セット外の課題が記載されている場合は無視し、課題をブロック状態にせず、無視した参照を dependency_proof にブロッキングではないコンテキストとして記録してください。
5. 実行可能な課題間の循環依存と未解決の依存関係を検出してください。影響を受ける課題は、dependency_proof と blocking_reasons を付けて blocked とします。
6. 実行順を決定します。依存関係を考慮したトポロジカルソートを行ってください。同じ依存関係階層内の優先順位は、重大な修正 → 開発インフラストラクチャ → トレーサーバレット機能スライス → 仕上げと簡単な改善 → リファクタリングです。PARALLEL_JOBS > 1 の場合、課題はローリングプール（同時に最大 PARALLEL_JOBS 件）に投入されます。空いた枠には、バッチ全体の完了を待たずに即座に課題を補充します。
7. 実行可能な依存先のステータスが未解決、merge_recovery、failed-merge、または blocked の課題は、依存先が completed になるまで実行準備完了になりません。プールランナーは、依存先が実行準備完了になる前に、merge_recovery の課題のマージリカバリーをディスパッチします。
8. 作業を開始する前に、完全な実行計画を .run-with-it/main-state.json に書き込みます。parallel_jobs、execution_mode（PARALLEL_JOBS=1 の場合は sequential、それ以外は rolling-pool）、topo_order、dependency_tiers、および各課題の dependency_proof、parallel_safe、正規化された ownership_scope を記録してください。並行実行のメタデータは、次のように導出します。
   • ownership_scope：課題の本文、タイトル、受け入れ条件に記載されたトップレベルディレクトリ（または課題の指定が具体的な場合は、より深いパス）の一覧です。リポジトリ相対のディレクトリパスをそのまま使用し、グロブ文字は使わないでください。グロブを含むスコープは、リテラルなディレクトリプレフィックスのみで比較します。絶対パス、ドライブ／UNC パス、.. でリポジトリ外に抜けるパスは不正として拒否し、その課題を排他的に実行します。
   • parallel_safe：課題がリポジトリ全体に及ぶリファクタリング、移行、フォーマットの一括適用、または範囲を限定できないファイルへの変更でない限り true にします。その場合は parallel_safe: false として、排他的な実行を強制します。
   • concurrency_policy：新たに作成する計画では、必ず execution_plan.concurrency_policy: "strict" を設定し、上記のメタデータをすべての課題について導出してください。strict の場合、並行実行メタデータが欠けている課題は排他的に実行します。ワークツリーが隔離するのはファイルシステム上の競合だけであり、意味上の競合、移行、生成ファイル、共有外部リソースは隔離されません。
   • concurrency_policy のないレガシー状態では、permissive として実行します。メタデータがない場合も並行実行を許可し、ワークツリーによる隔離とマージリカバリーに依存します。このフェイルオープンの動作は、フラグ導入前に書き込まれた状態との後方互換性のためだけに存在します。このフラグのない新しい計画は書き込まないでください。
   • 明示的な parallel_safe: false、ルート／不正なメタデータ、または確認済みの ownership_scope の重複がある場合、ポリシーにかかわらず課題の実行を保留します。プールランナーは、保留を STATUS|type=pool-admission-deferred|count=<n>|deferrals=<issue:reason,...> として報告します。
9. 次を出力します：STATUS|type=plan|total_issues=<n>|mode=<sequential|rolling-pool>|parallel_jobs=<PARALLEL_JOBS>|pending=<n>|blocked=<n>
10. 次を出力します：STATUS|type=memory-refresh|state_file=.run-with-it/main-state.json|tasks_loaded=<n>|completed=0|pending=<n>

メインオーケストレーターループ

計画を書き終えたら、直ちに無条件で実行してください。 決して一時停止したり、実行方法の選択肢を提示したり、計画を書き終えた後にユーザーへ進め方を尋ねたりしないでください。直ちにループを開始してください。

MAIN ORCHESTRATOR LOOP
Repeat until all issues in main-state.json have a terminal status
(completed / failed-review / failed-merge / blocked):

══ STEP A: MEMORY REFRESH ══════════════════════════════════════════════════════
Re-read .run-with-it/main-orchestrator-rules.md from disk.
Re-read .run-with-it/main-state.json from disk.
This is mandatory at the TOP of every iteration, no exceptions.
After context compression, these files are the sole source of truth.

Emit: STATUS|type=memory-refresh|state_file=.run-with-it/main-state.json
      |tasks_loaded=<total>|completed=<n>|pending=<n>|failed=<n>
Emit: STATUS|type=main-loop|iteration=<n>|pending=<count>|completed=<count>
      |failed=<count>

══ STEP B: SUPPLY CONTEXTS FOR THE ROLLING POOL ════════════════════════════════
Compute ACTIVE_POOL = all issues in issue_registry with status="in_progress"
(cross-check against active_pool_issues in state for consistency).

Collect NEWLY_QUEUED = ALL issues with status="pending" that do not yet have a
context file on disk (issue_registry[<n>].context_file unset, or the recorded
path no longer exists) — INCLUDING issues whose dependencies are not yet
completed. Order by priority:
  critical fixes → dev infra → tracer-bullet slices → polish → refactors.

Rationale (do not "optimize" this back to a slot-sized batch): the pool runner
is the only dispatcher, and it can only dispatch issues whose context files
already exist — issues without contexts are invisible to slot filling. Writing
every context up front is what lets the pool fill freed slots immediately and
auto-dispatch dependents the moment their dependencies complete, without
waiting on this session. Context staleness is acceptable: the Sub-Coordinator
re-fetches the issue body when it starts.

For each issue <n> in NEWLY_QUEUED:
  Leave issue status="pending" until the platform pool runner spawns it.
  Record its context file path in main-state.json during Step C.
  The pool runner marks status="in_progress" and appends <n> to
  active_pool_issues when it captures the dispatcher PID.
Emit: STATUS|type=pool-fill|active=<len(ACTIVE_POOL)>
      |newly_queued=<len(NEWLY_QUEUED)>|pending_remaining=<pending_after>
      |parallel_jobs=<PARALLEL_JOBS>

If ACTIVE_POOL is empty and NEWLY_QUEUED is empty:
  Check if any issues remain with status="pending" — if all have unmet deps
  whose blockers are terminal-but-not-completed, re-evaluate them; if still
  unresolvable, mark them "blocked".
  If ALL issues are terminal (completed / failed-review / failed-merge / blocked):
    EXIT LOOP → proceed to Final Ledger and Cleanup.

══ STEP C: ASSEMBLE SUB-COORDINATOR CONTEXT FILES ══════════════════════════════
Repeat for EACH issue <n> in NEWLY_QUEUED:

Build $SUB_COORD_CONTEXT_FILE_<n> (a separate temp file per issue) containing, in order:
  1. Full issue body: re-fetch using:
       gh issue view <n> --json number,title,body,labels,url,comments
     (re-fetch even if pre-fetched at startup — ensures freshest data)
     If gh fails because the current tool is sandboxed, use that tool's explicit approved permission-escalation flow when available. If the approved retry fails and local file exists,
     use cached issue body with a note.
  2. Last COMMITS_LIMIT (default 5) recent commits:
       git log --oneline -<COMMITS_LIMIT>
  3. If .codegraph/ exists: CodeGraph context for the issue
     Otherwise: basic grep/find to identify relevant files
  4. Environment configuration block (append at end of context file):
     SUB_COORD_ISSUE_NUMBER=<n>
     OS_FAMILY=<unix|windows>
     RUN_WITH_IT_ISSUE_DIR=<abs-path-to-.run-with-it/issues/<n>>
     SUB_COORD_REPORT_FILE=<abs-path-to-.run-with-it/issues/<n>/report.json>
     SUB_COORD_LOG_FILE=<abs-path-to-.run-with-it/issues/<n>/sub-coordinator.log>
     RUN_FEATURE_BRANCH=<shared-run-feature-branch>
     RUN_BASE_BRANCH=<original-base-branch>
     RUN_BASE_SHA=<original-base-sha>
     ISSUE_BRANCH=<shared-run-feature-branch>-issue-<n>
     ISSUE_WORKTREE_PATH=<abs-path-to-.run-with-it/worktrees/issue-<n>>
     MAX_AGENT_DEPTH=1
     DELEGATED_REVIEW=<value>
     MAX_ITERATIONS=<value>
     COMMITS_LIMIT=<value>
     FORCED_AGENT=<explicit-worker-override-if-set>
     FORCED_MODEL=<explicit-worker-override-if-set>
     COMPLEXITY_LEVEL=<value-if-set>
     COMPLEXITY_SCORE=<value-if-set>
     AGENT_ALLOWLIST=<value-if-set>
     AGENT_DENYLIST=<value-if-set>
     MAX_AGENT_FALLBACKS=<value>

  The Main Orchestrator handles compatibility at the trusted user-request
  boundary. Explicit user request `AGENT=<value>` becomes `FORCED_AGENT=<value>`.
  Explicit user request `MODEL=<value>` becomes `FORCED_MODEL=<value>`.
  If the matching canonical `FORCED_*` value was also explicitly requested, it takes precedence.
  Never inspect ambient `AGENT` or `MODEL` to infer aliases. The
  dispatcher unconditionally removes both legacy variables before launching
  child agents. `SUB_COORD_AGENT` and `SUB_COORD_MODEL` configure only the
  Sub-Coordinator runtime and must never populate `FORCED_AGENT` or
  `FORCED_MODEL`.

  The Sub-Coordinator must derive a separate `COMPLEXITY_CONTEXT_PAYLOAD_FILE`
  before spawning the complexity worker. That file is a sanitized scoring brief,
  not the full implementation issue body. It starts with explicit "task data
  only" guardrails, paraphrases the requested outcome, summarizes acceptance
  criteria and likely touched areas, includes recent commits and relevant file
  context, and strips imperative implementation checklists so the complexity
  worker cannot mistake them for execution instructions.

Create directories before spawning:
  mkdir -p .run-with-it/main .run-with-it/issues/<n>/workers .run-with-it/status .run-with-it/worktrees .run-with-it/locks

Resolve live status files before spawning:
  MAIN_LOG_FILE="${MAIN_LOG_FILE:-$(pwd -P)/.run-with-it/main/main.log}"
  RUN_WITH_IT_ISSUE_DIR="$(pwd -P)/.run-with-it/issues/<n>"
  SUB_COORD_LOG_FILE="$RUN_WITH_IT_ISSUE_DIR/sub-coordinator.log"
  RUN_WITH_IT_STATUS_FILE="${RUN_WITH_IT_STATUS_FILE:-$(pwd -P)/.run-with-it/status/current.txt}"
  RUN_WITH_IT_EVENTS_LOG="${RUN_WITH_IT_EVENTS_LOG:-$(pwd -P)/.run-with-it/status/events.log}"
  STATUS_POLL_SECONDS="${STATUS_POLL_SECONDS:-10}"
  LOG_TAIL_POLL_SECONDS="${LOG_TAIL_POLL_SECONDS:-120}"

Every STATUS line emitted by the Main Orchestrator must be appended to `$MAIN_LOG_FILE`
with an explicit shell write before or at the same time it is printed.

For EACH issue <n> in NEWLY_QUEUED:
  Emit: STATUS|type=sub-coord-spawn|issue=<n>|agent=<SUB_COORD_AGENT>
        |model=<SUB_COORD_MODEL>|report_file=<path>|log_file=<path>
        |pool_size=<current_active_count>|parallel_jobs=<PARALLEL_JOBS>

Print to user for each issue:
  "Starting sub-coordinator for issue #<n>: <title>"
  "Log: .run-with-it/issues/<n>/sub-coordinator.log"
  "To watch live progress in a separate terminal:"
  "  tail -f .run-with-it/issues/<n>/sub-coordinator.log"

══ STEP D: SPAWN NEWLY QUEUED + ROLLING POOL MONITOR ════════════════════════════

Execution-mode requirement (critical):
  Do not write a bespoke rolling-pool script in the Main Orchestrator session.
  Use the shared platform pool runner; it maintains the pool and calls the
  platform dispatcher with `role=sub-coord` for each active issue.

  Launch the pool runner ONCE as a detached supervisor with `--detach` /
  `-Detach`, then stay attached by running the bounded platform watch runner
  (`run-with-it-watch.sh` / `run-with-it-watch.ps1`) in a loop. Never treat
  starting the pool process as completion of Step D: Step D completes only when
  a watch call prints `WATCH|result=pool-empty`.

  Do not run the pool runner as a blocking foreground call — execution tools
  bound foreground calls (often to ~10 minutes) and killing the supervisor
  mid-run orphans the pool. Do not hand-roll `nohup`, a trailing Bash `&`, or
  `Start-Process` backgrounding either; the runner's detach mode creates its own
  process session and records `pool_pid` in `.run-with-it/main/pool.state.json`
  for the watch runner.

  Required handoff before Step D:
  - Each ready issue in `main-state.json` must have `issue_registry[<n>].context_file`
    (or `sub_coord_context_file`) pointing at the context file assembled in Step C.

  Bash (macOS / Linux / Git Bash) — launch once:

    "$ASSET_ROOT/run-with-it-pool.sh" \
      --asset-root "$ASSET_ROOT" \
      --state-file "$(pwd -P)/.run-with-it/main-state.json" \
      --parallel-jobs "$PARALLEL_JOBS" \
      --agent "$SUB_COORD_AGENT" \
      --model "$SUB_COORD_MODEL" \
      --status-file "$RUN_WITH_IT_STATUS_FILE" \
      --events-log "$RUN_WITH_IT_EVENTS_LOG" \
      --main-log "$MAIN_LOG_FILE" \
      --poll-seconds "$STATUS_POLL_SECONDS" \
      --timeout-seconds "$SUB_COORD_TIMEOUT_SECONDS" \
      --pool-state-file "$(pwd -P)/.run-with-it/main/pool.state.json" \
      --detach

  Then watch in a loop, one bounded foreground call at a time:

    "$ASSET_ROOT/run-with-it-watch.sh" \
      --events-log "$RUN_WITH_IT_EVENTS_LOG" \
      --pool-state-file "$(pwd -P)/.run-with-it/main/pool.state.json" \
      --wait-seconds "${POOL_WATCH_SECONDS:-240}" \
      --poll-seconds "$STATUS_POLL_SECONDS"

  PowerShell (Windows) — launch once:

    & powershell -NoProfile -File (Join-Path $ASSET_ROOT "run-with-it-pool.ps1") `
      -AssetRoot $ASSET_ROOT `
      -StateFile (Join-Path (Join-Path (Get-Location).Path ".run-with-it") "main-state.json") `
      -ParallelJobs $env:PARALLEL_JOBS `
      -Agent $env:SUB_COORD_AGENT `
      -Model $env:SUB_COORD_MODEL `
      -StatusFile $env:RUN_WITH_IT_STATUS_FILE `
      -EventsLog $env:RUN_WITH_IT_EVENTS_LOG `
      -MainLog $MAIN_LOG_FILE `
      -PollSeconds $env:STATUS_POLL_SECONDS `
      -TimeoutSeconds $env:SUB_COORD_TIMEOUT_SECONDS `
      -Detach

  Then watch in a loop:

    & powershell -NoProfile -File (Join-Path $ASSET_ROOT "run-with-it-watch.ps1") `
      -EventsLog $env:RUN_WITH_IT_EVENTS_LOG `
      -PoolStateFile (Join-Path (Join-Path (Join-Path (Get-Location).Path ".run-with-it") "main") "pool.state.json") `
      -PollSeconds $env:STATUS_POLL_SECONDS

  Each watch call prints every STATUS line appended to the events log since the
  previous call and exits within its watch window, well inside any tool-call
  timeout. After EVERY call — even when nothing changed — print a one-line
  user-facing progress update built from the newest `run-board` and
  `pool-heartbeat` lines, e.g.:

    "Pool alive (pid 12345) — 2 running, 3 pending, 4 completed, 1 blocked.
     Board: #42 impl(cyc1) | #43 review(cyc2) | #44 done"

  The pool emits `pool-heartbeat` every POOL_HEARTBEAT_SECONDS (default 60), so
  the user is never left guessing whether the run is alive. Then react to the
  drained lines:
  - `STATUS|type=pool-waiting-context` or `STATUS|type=sub-coord-dispatch-
    bootstrap-failed|...|reason=missing-context-file`: contexts are missing —
    assemble them NOW (run Step C for those issues) while the pool keeps
    running; it picks the new contexts up on its next tick without a relaunch.
  Then branch on the final `WATCH|result=...` marker:
  - `running` (exit 0): the pool is alive; immediately run the watch again.
  - `pool-dead` (exit 3): the pool supervisor died without `pool-empty`; relaunch
    the pool runner with the same `--detach` command — it re-attaches to live
    Sub-Coordinators and dead ones flow through exit analysis — then keep watching.
  - `pool-empty` (exit 0): Step D is complete. This is NOT the end of the run:
    GOTO Step A, which decides between another pool pass (issues still pending)
    and Final Ledger (all terminal).

  Do not end the Main Coordinator turn between watch calls, and do not start an
  unrelated shell to monitor the pool. The Main Orchestrator stays attached and
  looping until every issue is terminal (completed / failed-review / failed-merge / blocked).
  Per-issue dispatcher PIDs are persisted by the platform pool runner.
  The pool runner must also perform each terminal per-issue GitHub update immediately after finalizing that issue's compact report: post the terminal comment populated from the report, close the issue when `outcome=completed`, leave `blocked` and `failed-review` issues open after commenting, and emit `STATUS|type=github-update|issue=<n>|outcome=<outcome>|action=<commented|skipped|failed>|closed=<true|false>`.

══ GOTO STEP A ═════════════════════════════════════════════════════════════════

プラットフォームディスパッチャー — 共通ロールランチャー

run-with-it-dispatch.sh と run-with-it-dispatch.ps1 は、共通の run-with-it オーケストレーションプリミティブです。メインオーケストレーターは role=sub-coord でこれらを使用し、サブコーディネーターは role=complexity、plan、impl、review、または modify で使用します。これらは run-agent.sh／run-agent.ps1 をラップし、ロール固有の RUN_WITH_IT_* 環境変数を引き継ぎ、ディスパッチステータス行を書き込み、標準出力／標準エラー出力をロールログに記録し、worker-watch.sh／worker-watch.ps1 を通じて完了／結果アーティファクトを監視し、ディスパッチャーが管理するウォッチドッグ状態ファイルを書き込みます。モデルが出力するハートビートはあくまで参考情報です。モデルの標準出力とは独立して、ランナーが管理する wrapper-heartbeat とディスパッチャーの状態が稼働状況を判断する基準になります。

サブコーディネーターが短時間で終了するシェル／ツール呼び出しからワーカーディスパッチャーを起動する場合は、Bash では --detach を、ネイティブ PowerShell では -Detach を使用し、その後、ディスパッチャーが管理する状態ファイルからディスパッチャーの PID を読み取ってください。ワーカーディスパッチに生のシェルバックグラウンドジョブと WORKER_PID=$! を使用しないでください。

Bash の --detach は、処理を戻す前に新しいプロセスセッション／プロセスグループを作成します。通常の nohup ... & ではツール呼び出しプロセスグループに接続されたままになり、ワーカーランナーの PID が記録される前に強制終了されることがあるため、これが必要です。

デタッチされたワーカーディスパッチャーが終了するか、状態ファイルに runner_pid が記録される前に STATUS|type=dispatch-bootstrap-failed を出力した場合は、ワーカー／モデルの結果ではなく、起動ブートストラップの消失として扱ってください。同じログ、完了、結果、状態、リポジトリルート、イシューディレクトリ、ステータス、イベントの各パスを指定し、同じワーカーをフォアグラウンドの監視モードで一度再試行してください。これにより、ディスパッチャーが dispatch-pid または具体的なアーティファクトエラーのいずれかを取得できます。

ワーカーの結果ファイルに $SUB_COORD_REPORT_FILE または .run-with-it/issues/<n>/report.json を指定してはいけません。パスの完全な仕様については、coordinator-rules.md（Worker-Agent Dispatch Rules）を参照してください。

run-with-it-dispatch.sh \
  --role <sub-coord|complexity|impl|review|modify|merge-recovery> \
  --issue <n> \
  --cycle <n> \
  --agent <agent> \
  --model <model> \
  --context-file <file> \
  --prompt-file <file> \
  --log-file <file> \
  --done-file <file> \
  --result-file <file> \
  --state-file <file> \
  --repo-root <worktree-or-repo-path> \
  --status-file <file> \
  --events-log <file> \
  --quiet-seconds <seconds> \
  --stall-seconds <seconds> \
  --detach

PowerShell では、同じフィールド名を PowerShell 形式のパラメーターで使用します。たとえば、-Role impl -Issue 123 -LogFile <file> -DoneFile <file> -ResultFile <file> -StateFile <file> -Detach のように指定します。

ラップされたランナーの呼び出しを表示するには --dry-run／-DryRun を使用し、入力を検証して、プロセスを起動せずに STATUS|type=dispatch-ready を出力するには --validate-only／-ValidateOnly を使用します。

ワーカーのウォッチドッグファイルは、イシューごとの cycle-<cycle>.state.json という形式のレイアウトを使用します。state="quiet" と state="stalled" はモデル出力の状態を示し、ランナーが管理するラッパーハートビートはプロセスの稼働状況を追跡します。state="artifact-recovery-required" は、機械可読な検証合格結果がないまま Git の進捗が保持されたことを意味し、アーティファクトの復旧に進む必要があります。完了には引き続き、完了センチネル、ロール固有の有効な結果アーティファクト、実装／変更の検証合格が必要です。

RUN_WITH_IT_AUTO_FAIL_STALLED_ROLES（Bash のデフォルト値：complexity,impl,modify,plan）は、ラッパーハートビートに対応していない古いランナー向けの互換性フォールバックです。現在のランナーは、標準出力が静かなだけでは終了させられません。RUN_WITH_IT_WORKER_HARD_LIMIT_SECONDS が経過時間を制限し、終了前に復旧用の Git の進捗を保持します。

最終 PR の作成

すべてのイシューが最終状態になった後、gh pr create を実行する前に、保存済みの実行状態から PR の本文を生成します。

"$ASSET_ROOT/run-with-it-pr-body.py" render --state-file .run-with-it/main-state.json > .run-with-it/final-pr-body.md
gh pr create --body-file .run-with-it/final-pr-body.md

生成した本文では、完了／クローズ済みのイシューを #123 のような通常のイシューリンクとして記載してください。イシューはイシューごとの GitHub 更新フローですでにクローズされているため、最終 PR の本文で自動クローズキーワードを使用しないでください。イシュー参照の近くにある、大文字と小文字を区別しない自動クローズキーワードのバリエーションを禁止します：close、closes、closed、fix、fixes、fixed、resolve、resolves、resolved。

run-agent.sh — 完全な構文リファレンス

run-agent.sh --agent <agent> [--model <model>] --context-file <file> [--prompt-file <file>]
             [--permission-mode <mode>] [--extra-arg <arg>] [--unattended] [--dry-run]
run-agent.sh --list-agents [--detected-only]
run-agent.sh --list-models <agent>

フラグ	環境変数の同等項目	必須	説明
--agent <agent>	AGENT	はい	有効なエージェントのスラッグ（例：codex、claude、agy。Copilot プランの上限に達している間、github-copilot／copilot はレジストリで無効になっています）
--model <model>	MODEL	はい（常に明示的に指定）	使用するモデル ID
--context-file <file>	CONTEXT_PAYLOAD_FILE	はい	組み立て済みコンテキストペイロードファイルのパス
--prompt-file <file>	PROMPT_FILE	いいえ（デフォルトは <script-dir>/prompt.md）	プロンプトファイルのパス
--repo-root <path>	REPO_ROOT	いいえ	エージェントに渡される作業ディレクトリ。サブコーディネーターは issue のワークツリーを使用します
--permission-mode <mode>	AGENT_PERMISSION_MODE	いいえ	エージェントの権限モードを上書きします
--extra-arg <arg>	AGENT_EXTRA_ARGS	いいえ	繰り返し指定可能。エージェントの呼び出しに追加されます
--unattended	UNATTENDED=1	はい — run-with-it のディスパッチでは常に指定	権限モードが設定されている場合は必須です
--dry-run	—	いいえ	解決されたコマンドを実行せずに表示します
--list-agents	—	—	すべてのエージェントと検出状況を一覧表示します。絞り込むには --detected-only を追加します
--list-models <agent>	—	—	エージェントで既知のモデルを一覧表示します

追加の環境変数（対応するフラグはありません）：

環境変数	デフォルト	説明
AGENT_REGISTRY_FILE	<script-dir>/agent-registry.json	エージェントレジストリのパス
GUI_MODE	auto	auto は GUI 環境変数を検出します。1 は GUI に安全な非対話モードを強制します。0 は CLI／CI モードを強制します
REPO_ROOT	$(pwd)	エージェントに渡される作業ディレクトリ
PRINT_PROMPT	0	1 に設定すると、実行せずに組み立て済みプロンプトを表示します

GUI_MODE の動作：

• auto — VSCODE_PID、TERM_PROGRAM=vscode、ELECTRON_RUN_AS_NODE、ANTIGRAVITY_APP、CURSOR_TRACE_ID、CLAUDE_CODE_ENTRYPOINT を検出し、いずれかが一致すると GUI_MODE=1 を設定します。
• 1 — UNATTENDED=1 を強制し、危険なフルバイパス権限フラグを、エージェントごとのより安全な同等の設定に引き下げます。
• 0 — 権限の引き下げを行わず、CLI／CI の動作を維持します。

クリーンアップ

クリーンアップは、正常終了、実行失敗、中断、または明示的な discard コマンドの後にのみ実行されます。resume 時にクリーンアップを実行してはなりません。

実行の正常終了

実行が正常に終了した場合：

• すべての $SUB_COORD_CONTEXT_FILE 一時ファイルを削除します（各 issue の後に削除されているはずですが、残存ファイルもクリーンアップします）。
• .run-with-it/main-state.json、.run-with-it/main-orchestrator-rules.md、.run-with-it/coordinator-rules.md を削除します。
• Git 管理対象ファイル、ワークツリー、または .run-with-it/ の外にあるファイルを削除する前に、予定しているクリーンアップ対象を表示して、ユーザーに確認を求めます。確認後、.run-with-it/issues/、.run-with-it/main/、.run-with-it/status/、.run-with-it/worktrees/、.run-with-it/locks/ 内の生成ファイルを削除します。
• 可能な場合は git worktree remove で issue のワークツリーを削除します。最終 PR の作成後も、共有実行用フィーチャーブランチは保持します。
• .run-with-it/ ディレクトリが空の場合は削除します。
• ワークスペースのルートにある technical_requirements.md、prd.md、issues.md のそれぞれについて、git status --short <file> を実行します。ファイルが未追跡（??）またはクリーン（一覧にない）の場合に限り削除します。ユーザーによる変更があるファイル（その他のステータス）は削除をスキップし、STATUS|type=cleanup|action=skipped-dirty-file|file=<file> を出力します。ユーザーが変更したワークスペースファイルは決して削除しないでください。
• 冪等な追加処理を使い、.gitignore に .run-with-it/、technical_requirements.md、prd.md、issues.md の各項目が含まれていることを確認します。
• .git/ が存在する場合は、削除したファイルと .gitignore のみをステージし、メッセージ chore: remove skill-generated artifacts post-run でコミットします。
• STATUS|type=cleanup|action=completed|files_removed=<n> を出力します。

失敗または中断された実行

実行が失敗または中断された場合：

• 保持されたワークツリーやロックを含め、すべての .run-with-it/ ファイルを調査用に残します。
• 保持されたファイル（状態、レポート、ログ、レビュー）のパスを表示します。
• 強制削除して再開するための discard コマンドを提示します。

破棄

discard の実行時は、何かを削除する前に、切り離された実行プロセスをすべて終了します。スーパーバイザー、ディスパッチャー、ランナーは切り離されており、実行中のままにすると、削除済みまたは新たに作成されたパスへの書き込みを続け、GitHub の更新も実行できます。ディスパッチャーの PID だけを終了しても不十分です。ランナーは別途起動され（nohup / Start-Process）、ディスパッチャーの終了後も動作し続けるためです。

1. プラットフォームの停止ヘルパーを実行します — 実行状態に記録されているすべての PID（pool_pid、すべての dispatcher_pid と runner_pid、ネストされたワーカーおよび復旧ディスパッチャーを含む）について、各 PID のコマンドラインを照合して本人確認を行ってから、Unix のプロセスグループ全体または Windows のプロセスツリー全体を終了し、終了を検証します。これにより、再利用された PID に該当する無関係なプロセスにシグナルが送られることはありません。

   Bash: "$ASSET_ROOT/run-with-it-stop.sh" --run-root "$(pwd -P)" PowerShell: & powershell -NoProfile -File (Join-Path $ASSET_ROOT "run-with-it-stop.ps1") -RunRoot (Get-Location).Path

   ヘルパーは PID ごとに STOP|type=target|... の行を 1 行出力し、最後に STOP|result=<clean|survivors>|terminated=<n>|already_dead=<n>|skipped_not_ours=<n> の行を出力します。

2. 終了を確認できない場合は、破棄を拒否します。 エスカレーション後も対象プロセスが生存している場合、停止ヘルパーは終了コード 3 で終了し、STOP|result=survivors|...|survivors=<pids> を報告します。生存している PID をユーザーに報告して停止し、プロセスが動作中のまま状態を削除してはいけません。

3. 削除対象を表示し、削除前にユーザーに確認を求めます。確認後、.run-with-it/main-state.json、.run-with-it/main/pool.state.json、レポート、ログ、レビュー、ワークツリー、ロック、technical_requirements.md、prd.md、issues.md など、保持された生成ファイルを削除します。

4. .gitignore を更新し、chore: remove skill-generated artifacts (discarded run) というメッセージでコミットします。

5. STATUS|type=cleanup|action=discarded|files_removed=<n> を出力します。

6. 新規実行として続行します。

付録 A：メイン状態スキーマ

Main Orchestrator は .run-with-it/main-state.json（schema_version 4）を永続化します。これは Main Orchestrator の永続メモリ全体です。

{
  "schema_version": 4,
  "run_id": "<funny-action-animal slug generated at run start>",
  "started_at": "<iso8601>",
  "run_branch": {
    "base_branch": "main",
    "base_sha": "abc123",
    "feature_branch": "Maestro/cunning-fox",
    "feature_branch_start_sha": "abc123",
    "remote": "origin",
    "pushed": true,
    "pr_url": null
  },
  "execution_plan": {
    "execution_mode": "sequential | rolling-pool",
    "concurrency_policy": "strict",
    "parallel_jobs": 4,
    "topo_order": [36, 37],
    "dependency_tiers": [[36], [37]],
    "pool_config": {
      "max_concurrent": 4,
      "fill_strategy": "rolling"
    }
  },
  "issue_registry": {
    "36": {
      "status": "completed | in_progress | pending | merge_recovery | failed-review | failed-merge | blocked",
      "title": "issue title",
      "deps": [],
      "dependency_proof": "Blocked by: None",
      "parallel_safe": true,
      "ownership_scope": ["src/orders"],
      "issue_dir": ".run-with-it/issues/36",
      "report_file": ".run-with-it/issues/36/report.json",
      "merge_recovery_report_file": ".run-with-it/issues/36/merge-recovery-report.json",
      "log_file": ".run-with-it/issues/36/sub-coordinator.log",
      "issue_branch": "Maestro/cunning-fox-issue-36",
      "worktree_path": ".run-with-it/worktrees/issue-36",
      "issue_base_sha": "abc1234",
      "issue_base_source": "remote-tracking | local-fallback",
      "commit_sha": "abc1234"
    }
  },
  "active_pool_issues": [37, 38],
  "completed_summaries": [
    {
      "issue": 36,
      "outcome": "completed",
      "summary": "One paragraph compact report summary.",
      "files_modified_count": 3,
      "lines_added": 42,
      "lines_deleted": 7,
      "review_cycles": 1,
      "commit_sha": "abc1234",
      "verification": {
        "passed": true,
        "evidence": "15 tests passed, 0 failed"
      },
      "model_usage": [
        {
          "role": "impl",
          "cycle": 1,
          "agent": "codex",
          "model": "gpt-5.3-codex",
          "selection_reason": "under-target"
        }
      ],
      "report_file": ".run-with-it/issues/36/report.json"
    }
  ],
  "ledger_rows": [
    "STATUS|type=ledger|task=36|... (verbatim line as emitted)"
  ]
}

主な不変条件：

• issue_registry には課題ごとに 1 つのエントリーがあります
• run_branch には最終 PR に使用する共有フィーチャーブランチが記録されます
• topo_order と dependency_tiers は、課題の依存関係をトポロジカルソートして導出されます
• completed_summaries には、完了した課題ごとに簡潔なレコードが蓄積されます。レコードには、簡潔な summary、verification、model_usage、report_file の各フィールドが含まれます。圧縮後にメインオーケストレーターが読み返すのはこの情報です
• merge_recovery は終端状態ではありません。依存関係が満たされるのは completed の場合のみです
• ledger_rows には最終台帳の出力に使用する STATUS 行がそのまま保存されます
• active_pool_issues には、アクティブな Sub-Coordinator がある課題が列挙されます。再開時には付録 C の Resume Flow に従い、スーパーバイザーのリースを検証してアクティブな状態を維持してください。切り離されたディスパッチャーがまだ動作している可能性があるためです
• PARALLEL_JOBS=1 の場合、active_pool_issues のエントリー数は常に最大 1 です

.run-with-it/ の .gitignore への自動追記（必須）

.run-with-it/ 配下にファイルを初めて書き込むとき：

• 現在の作業ディレクトリに .git/ がある場合は、.gitignore に .run-with-it/ が含まれるようにします。
  • .gitignore が存在しない場合は作成します
  • すでに存在する場合を除き、.run-with-it/ を独立した行として追記します（冪等）
  • 既存の .gitignore の内容は変更しません
• .git/ がない場合は、.gitignore を作成せず、何も通知しません。

付録 B：ステータスと台帳の規約

ステータスメッセージ

解析可能な 1 行形式のステータスメッセージを出力します。

• 計画：STATUS|type=plan|total_issues=<n>|mode=<sequential|rolling-pool>|parallel_jobs=<PARALLEL_JOBS>|pending=<n>|blocked=<n>
• プールの補充：STATUS|type=pool-fill|active=<count>|newly_queued=<count>|pending_remaining=<count>|parallel_jobs=<PARALLEL_JOBS>
• プールのスロット補充：STATUS|type=pool-slot-filled|issue=<n>|freed_by=<m>|pool_size=<count>
• プールのデタッチ：STATUS|type=pool-detached|pid=<pid>|pool_state_file=<path>
• プールはすでに実行中（重複起動を拒否、終了コード 2）：STATUS|type=pool-already-running|pid=<pid>|pool_state_file=<path>
• プールの再アタッチ：STATUS|type=pool-reattached|count=<n>|state_file=<path>
• サブコーディネーターの再アタッチ：STATUS|type=sub-coord-reattach|issue=<n>|pid=<pid>|identity=<live|stale|dead>|report_file=<path> — stale は、記録された PID が稼働中でも、そのコマンドラインがディスパッチャーに一致しなくなったこと（再利用された PID）を意味します。プロセスが引き継がれることはなく、終了分析に進みます。
• プールへの追加を延期：STATUS|type=pool-admission-deferred|count=<n>|deferrals=<issue:reason,...>
• プールに到達不能：STATUS|type=pool-unreachable|count=<n>|unreachable=<issue:root,root;...> — 依存先が完了以外の終端状態になったため、準備完了になり得ない課題です。root は責任のある終端状態の課題を示し、推移的に特定されます。プールが空になったときに |final=1 を付けて再出力されるため、早期終了する実行では、どの失敗によって何が滞ったかが必ず示されます。
• サブコーディネーターの復旧待機：STATUS|type=sub-coord-recovery-wait|issue=<n>|role=<role>|worker_state=<state>|state_file=<path>|reason=in-flight-worker-running|waited_seconds=<n>|worker_age_seconds=<n>|max_wait_seconds=<n> — WAIT_STATUS_INTERVAL_SECONDS 間隔で出力されます。worker_age_seconds は、そのワーカーの成果物が最後に更新されてからの経過時間です。
• プールが空：STATUS|type=pool-empty|pending_remaining=<n>
• マージ復旧をキューに追加：STATUS|type=merge-recovery|issue=<n>|report_file=<path>|state=<started|completed|failed-merge|blocked>
• メモリの更新：STATUS|type=memory-refresh|state_file=.run-with-it/main-state.json|tasks_loaded=<n>|completed=<n>|pending=<n>|failed=<n>
• メインループ：STATUS|type=main-loop|iteration=<n>|pending=<count>|completed=<count>|failed=<count>
• サブコーディネーターの起動：STATUS|type=sub-coord-spawn|issue=<n>|agent=<name>|model=<model>|report_file=<path>|log_file=<path>|pool_size=<n>|parallel_jobs=<PARALLEL_JOBS>
• サブコーディネーターの PID を追跡：STATUS|type=sub-coord-pid|issue=<n>|pid=<pid>|done_file=<path>|report_file=<path>
• エージェントの実行開始：STATUS|type=agent-start|issue=<n>|role=<sub-coord|complexity|impl|review|modify>|agent=<name>|model=<model>
• エージェントの実行完了：STATUS|type=agent-complete|issue=<n>|role=<sub-coord|complexity|impl|review|modify>|agent=<name>|model=<model>|status=<success|failed>
• ワーカー完了：STATUS|type=worker-done|issue=<n>|role=<complexity|plan|impl|review|modify>|phase=<phase>|source=<agent|runner-exit>
• サブコーディネーター完了：STATUS|type=sub-coord-complete|issue=<n>|outcome=<completed|failed-review|merge_failed|blocked>|report_file=<path>|commit_sha=<sha-or-none>
• マージ開始：STATUS|type=merge-start|issue=<n>|branch=<issue_branch>|target=<feature_branch>
• マージ完了：STATUS|type=merge-complete|issue=<n>|merge_sha=<sha>|pushed=<true|false>
• マージ失敗：STATUS|type=merge-failed|issue=<n>|reason=<conflict|verification|push|unknown>
• 停滞：STATUS|type=stall|issue=<n>|idle_for=<seconds>|action=alert-user
• 取り込みのフォールバック：STATUS|type=intake-fallback|reason=<no-gh-auth|no-remote|gh-permission-blocked|gh-failed-after-escalation>
• ランナーのサンドボックス再試行：STATUS|type=runner-sandbox-retry|agent=<agent>|model=<model>|reason=<error-summary>
• ランナーのサンドボックス再試行結果：STATUS|type=runner-sandbox-retry-result|outcome=<success|failed>
• クリーンアップ完了：STATUS|type=cleanup|action=completed|files_removed=<n>
• 破棄時のシャットダウン（停止ヘルパーから）：STOP|type=target|source=<pool|dispatcher|runner>|pid=<pid>|action=<term-group|term-pid|stop-tree|already-dead|skip-not-ours> に続いて STOP|result=<clean|survivors>|terminated=<n>|already_dead=<n>|skipped_not_ours=<n>
• クリーンアップによる破棄：STATUS|type=cleanup|action=discarded|files_removed=<n>
• 最終台帳行：STATUS|type=ledger|task=<task-id>|role=impl|cycle=0|agent=<agent-name>|model=<model-id>|added=<n>|deleted=<n>|total=<n>|reason=sub-coordinator|input_tokens=<n-or-unknown>|output_tokens=<n-or-unknown>|cache_hit_tokens=<n-or-unknown>|telemetry_source=sub-coordinator-report

最終台帳

ループの終了後、クリーンアップの前に、main-state.json から ledger_rows を読み取り、集約された最終台帳を出力します。これにより、圧縮前に完了したものを含むすべての課題が記録され、台帳は圧縮後も保持されます。

さらに、すべての completed_summaries エントリーの最終サマリーを出力します。次の情報を含めてください。

• 処理した課題の合計数
• 完了／レビュー失敗／マージ失敗／ブロックの件数
• すべての課題における追加行数と削除行数の合計
• 各課題の model_usage に含まれるタスクレベルのモデル使用状況（role、cycle、agent、model、selection_reason）
• 集計したトークン使用量（完了した課題について、すべてのレポート JSON の token_usage フィールドを合算）

付録 C：再開と状態の契約

再開フロー

起動時に .run-with-it/main-state.json が存在する場合、ユーザーに確認します（事前確認 6 の既存状態の検出を参照）。resume の場合：

1. .run-with-it/main-state.json を再読み込みします。
2. 最初にスーパーバイザーのリースを検証します。 プールスーパーバイザーとディスパッチャーはデタッチ状態で実行されるため、中断されたセッションから引き続き実行中の場合があります。.run-with-it/main/pool.state.json を読み込み、pool_pid を確認します。
   • スーパーバイザーが稼働中（PID が存在し、そのコマンドラインがプールランナーを参照している。例：ps -p <pid> -o command= に run-with-it-pool が含まれる）：何もリセットせず、再起動もしません。既存のスーパーバイザーを対象に Step D の監視ループに再度入り、WATCH|result=pool-empty まで続行します。
   • スーパーバイザーが停止中（状態ファイルがない、PID が停止している、または PID が無関係なプロセスに再利用されている）：デタッチ状態のプールランナーを再起動します。再起動後、active_pool_issues に再接続します。稼働中のディスパッチャーは新しいスーパーバイザーの配下で実行を続け、停止中のディスパッチャーは構造化された終了分析を経由します。
3. in_progress の課題を一括リセットしたり、active_pool_issues を消去したりしてはいけません。 デタッチ状態のディスパッチャーがまだ稼働中の課題をリセットすると、同じ課題が再度ディスパッチされ、作業、マージ、状態の書き込み、トークンコスト、GitHub コメントが重複します。個別の課題を pending に再登録（run-with-it-state.py requeue を使用）できるのは、そのディスパッチャーが停止していることを示す構造化された証拠があり、課題のディスパッチャー状態ファイルに停止中のディスパッチャー PID が記録されている、かつ復旧を裏付ける課題単位の sub-state.json が存在しない場合に限ります。プールランナーの再接続処理ではすでにこの分析が行われます。手動で再登録するより、プールを再起動してください。
4. status="pending" の課題をすべて特定します。これらの課題はまだ開始されていません。
5. status="completed"、"failed-review"、"failed-merge"、または "blocked" の課題をすべて特定し、完全にスキップします。
6. Main Loop の Step A に再び入ります。
7. 次を出力します。STATUS|type=resume|tasks_restored=<n>|completed=<n>|supervisor=<alive|relaunched>|re_queued_in_progress=<m>|parallel_jobs=<PARALLEL_JOBS>

ユーザーが resume と入力した際に .run-with-it/main-state.json が存在しない、または解析できない場合は、次を出力します。

STATUS|type=resume-error|reason=<missing|parse-error>|action=user-required

その後、フレッシュな実行として続行するかどうかをユーザーに尋ね、処理を停止します。

圧縮後の状態維持

コンテキストが圧縮された後（会話履歴が消去された後）は、再開時と同様に扱います。Step A に従って .run-with-it/main-state.json を再読み込みし、上記の再開フローに従って、スーパーバイザーのリースを検証し、アクティブな状態を保持します。プールスーパーバイザーとディスパッチャーはデタッチ状態で実行され、圧縮の影響を受けません。ほぼ確実に引き続き稼働しているため、課題の状態には触れず、監視ループに再び入ります。completed の課題は再実行されません。状態ファイルは常に信頼できる情報源です。会話履歴から課題の状態を推測してはいけません。

付録 D：終端課題コメントの契約

ターミナル結果コメント

ターミナル結果が completed、blocked、failed-review、または failed-merge（マージの復旧に失敗した場合に設定）の場合は、issue コメントをすぐに投稿してください。 各ターミナルコメントは、その issue の簡潔なレポートを読み取った後にのみ投稿し、無関係な issue やプール全体の完了を待ってはいけません。 すべてのフィールドには、Sub-Coordinator の簡潔なレポート JSON の値を入力してください。

すべてのターミナル結果で同じ Markdown テンプレートを使用し、セクションの順序は次のとおり固定です。

1. ## Status
2. ## Summary
3. ## Verification
4. ## Token Usage
5. ## Notes
6. ## Blocking Reasons（report.blocking_reasons が空でない場合のみ）

ターミナルコメントのテンプレート：

## Status
<completed|blocked|failed-review|failed-merge>

## Summary
<task outcome summary — from report.summary>

## Verification
<task-specific verification results — from report.verification.evidence>

## Token Usage
- Input tokens: <n|unknown>
- Output tokens: <n|unknown>
- Cache hit tokens: <n|unknown>

## Notes
Review: <approve|revise (N cycles)>, final verdict: <approve|reject>, reviewer model: <model-id>
<follow-ups, blockers, or additional reviewer notes — omit line if none>

## Blocking Reasons
<omit this section entirely when verdict is not reject; when verdict=reject, list each entry from report.blocking_reasons as a separate bullet>

コメントの要件：

• Token Usage にはタスク固有のテレメトリのみを記載してください（report.token_usage から取得）。
• トークン値が取得できない場合は、その値に明示的に unknown と記載してください。
• Verification には、実行したチェックと、それぞれの合格、失敗、またはブロックの結果を要約してください（report.verification から取得）。
• DELEGATED_REVIEW=true でレビューを実施した場合、Notes にはレビューの要約行を正確に 1 行含めてください。形式：Review: <verdict-path>, final verdict: <approve|reject>, reviewer model: <model-id>。そのまま承認した場合は approve (1 cycle)、修正後に承認した場合は revise (N cycles) と記載してください。report.review_skipped が true の場合は、代わりに Review: skipped (trivial-change) と記載してください。
• Blocking Reasons セクションは、report.blocking_reasons が空でない場合にのみ含めてください。各項目は個別の Markdown 箇条書きとして記載してください。それ以外の場合は、セクション全体を省略してください。