orchestrate

Orchestrate: Opusが計画・レビュー、安価なエージェントが実行

あなた（Opus）はアーキテクト兼ゲートキーパーであり、タイピストではありません。ワーカーは安価で高速ですが信頼できません。すべての結果は、ゲートが正しいと証明するまでは、誤っている、不完全、過剰、醜い、テストを不正に通過している可能性があると想定してください。

ツール: python3 ~/.claude/skills/orchestrate/scripts/orch.py（以下: orch）。必要に応じて参照:

• references/agent-matrix.md — エージェントごとの能力/コストとステップパイプラインパターン（セッションごとに1回）
• references/workers.md — ワーカーごとのCLIレシピと落とし穴
• references/live.md — rx-acpライブ監視（L0/L1/L2）、--live実行、ワイヤーフォーマット、レッスンログ（rx-acp*または--liveを使用する前に読むこと）
• references/review-checklist.md — ゲート2

0. トリアージ

変更が1～2ファイル、約40行以内の場合、または主に判断（アーキテクチャ、セキュリティ、繊細なデバッグ）が必要な場合、または約1000 diff行未満の機械的な変更の場合は、自分で実行してください。複数の独立したサブタスク、一括編集、ボイラープレート、テスト、ドキュメント、コードベース検索、またはユーザーが依頼した場合にオーケストレーションを使用します。

リソース予算（8並列ワーカーで数十の型チェッカーが動作しマシンがフリーズした例あり）:

• 最大3つのワーカーを同時起動（--parallel 3がデフォルト。Sonnet/Haikuエージェントもカウント）
• checks = 安価で範囲を限定（1つのテストファイル、影響を受けたファイルのみリンター）。プロジェクト全体の型チェック/ビルドはfinal_checksに含める。ワーカーはこれらを実行せず、マージ後にメインツリーであなたが1回実行する。
• 多数の小さな契約よりも、2～3の大きな契約を優先する（起動が固定コスト）。
• ワーカーはパッケージをインストールしたり、バックグラウンドプロセス/開発サーバーを起動したりしない。ウェーブ後、実行中のプロセスが残っていないことを確認する（pgrep -fl "wt/<ID>|tsc"）。
• UI契約: 許可されるデザイントークンと禁止されるデザイントークンを明示的に列挙する。

前提条件: gitリポジトリ。worktreeはHEAD + 追跡対象の未コミット変更からブランチを作成する（追跡対象外ファイルは引き継がれない）。

Jev（TypeSafe System One、scripts/jev.py）: 型付き判定、約0.4秒、約$0.00004/呼び出し。分類、スコアリング、チェックを実行。ポリシーとしきい値はコード内に保持。TYPESAFE_API_KEYが欠落している場合、Jevはオフになる（ORCH_JEV=0）。

1. 理解と仕様作成

1. 関連コードを読む（または広範囲の検索のために読み取り専用ワーカーを送る）。テスト/リンターコマンドを見つける。
2. orch route "<task>" → Jevのシグナルと推奨ワーカー/分析ステップを取得。提案であり、決定はあなたが行う。
3. 短い仕様: 目標、非目標、合格基準、リスク。ユーザーの決定が必要な場合のみ質問する。

2. 契約への分解

サブタスクごとに1つの契約JSONを <repo>/.orch/contracts/<ID>.json に作成する（references/contract-template.json）。

• 小規模: 1～3ファイル、約150 diff行以下。並列タスクでは**allowedを互いに素に**する。依存タスクはチェーンする。
• 自己完結型: ワーカーはこの会話を見ない — パス、名前、規約、落とし穴、触ってはいけないものを記載。
• テスト可能な合格基準: 各基準はチェックにマッピングされる。Jevはそこに書かれた内容のみを検証する。
• 新しい振る舞いのための隠しテスト: リポジトリ外にエッジケーステストを記述し、hidden_files + hidden_checksで参照する。採点時にのみコピーされる。
• protectedファイル。max_diff_lines ≈ 非テスト見積もりの2～3倍（テスト行はmax_test_diff_linesにカウントされ、デフォルトは3倍）。分析タスクではmode: "read_only"。
• 計画フィールド — ワーカーのために思考を行う（時間-33％、出力トークン-45％、範囲違反なし）: approach（順序付きステップ。バグの場合は根本原因ごと）、pattern_refs（ファイル:行 — コピーすべきもの）、examples（入力 -> 期待出力、厄介なケースを含む）、pseudo（トリッキーな部分のみ）、rules（具体的でチェック可能な禁止事項 — L1が実行中に強制）。prompt_style: "profiled"を維持する。
• orch check .orch/contracts/*.json を実行してからディスパッチする。フラグが立った契約を先に修正する。
• Worktree（.orch/wt/<ID>）は追跡対象ファイルのみを保持する。パッケージごとのnode_modules/生成コードはworktree_links（契約内）または.orch/config.json（単純なglob）にリストする — メインツリーからシンボリックリンクされ、共有される。
• allowedに正確に名前が含まれるファイルは、既存のテストファイルであっても編集可能。

3. ルーティング

ポリシー（ユーザー）: すべてをreasonixにルーティングしないこと。

タスクの形状	第一候補	エスカレーション先
小さな機械的編集、設定、リネーム、例付きの純粋関数	rx-acp	rx-acp-max → agy → sonnet
読み取り専用分析/検索	rx-flash	rx-flash-max → sonnet
通常の機能モジュール（1～3ファイル、計画フィールドあり）	sonnet	Opus
既存コードのテスト（機能コードは不可）	haiku	sonnet
振る舞いを保持するリファクタリング	sonnet + 隠しテスト	Opus
既存のデザインシステムに従うUI（pattern_refs）	agy または sonnet	sonnet
重要: 金融/台帳、認証、並行性、セキュリティ、マイグレーション	Opus、または sonnet + 厳密な仕様 + 行単位レビュー	—
diffのセカンドオピニオン	別ファミリー、読み取り専用	Opus

agy = Gemini 3.8 Flash Medium。rx-* = DeepSeek V4 Flash（-max = 努力最大、最強のDeepSeek階層）。rx-acp* = ライブ監視下の同じモデル — rx-flashと同等の正確性、より安価、無関係なファイルを作成しない。編集契約、特にトラップがある場合に推奨（誘惑的な追加ファイル、インストール、重いチェック）。視覚的センス → sonnet + レビュー。

4. ディスパッチ — 1回のバックグラウンド呼び出し、Opusはスリープ

ウェイクアップのたびにコンテキスト全体を再読み込みする。1回の呼び出しでウェーブをディスパッチする:

orch run --title "<ユーザーのリクエスト、短く>" .orch/contracts/A.json B.json ...   # Bash, run_in_background: true

終了時に再呼び出しされる — ポーリングやスリープはしない。契約ごとに、Opusなしで: 新しいworktree → ワーカープロンプト → ガード → FAILの場合、ワーカーのセッション内で機械的なフィードバック（キャッシュウォーム）、最大max_attempts回。コードルール + Jevトリアージがリトライ/エスカレーションを選択（ladderに沿って、BLOCKED（契約の問題）、NEEDS_OPUS（環境問題、API/CLIエラーを含む。即座に停止））。PASS後、Jevが各合格基準に対するdiffをチェック（P>0.85 → 自動で1回リビジョン。0.7～0.85 → レビューのための警告）。タスクごとに1行のコンパクトな結果を受け取る。ログは.orch/runs/<ID>/attempt-N/に残る。hidden_feedback: "names"は、テストゲーミングが懸念される場合にフィードバックからアサーションを隠す。

• rx-acpはライブスーパーバイザー（L0ルール + L1 Jevレビュー、実行中）の下で実行される。**orch run --live**は実行中の判断をあなたに委ねる（計画承認、不明瞭な編集、質問、スタック）。orch wait → orch reply <id> --choice … --steer "…" → orch wait。--liveは、実行中の判断がウェイクアップに値する場合のみ使用する（リスクのある/曖昧な契約、新しい契約スタイル）。詳細: references/live.md。
• Sonnet / Haiku: orch prepare <contract> → エージェント subagent_type: "sonnet-worker"（+ model: "haiku"）、run_in_background: true、プロンプト = prepareのagent_prompt（テキストではなくファイルパス）。その後:

  orch guard .orch/contracts/<ID>.json --reply - <<'EOF'
  <ワーカーの最終JSON、そのまま>
  EOF
  

• ステップパイプライン: after: [ids]（PASSを待つ）、inputs: [ids]（そのステップの回答/diffを注入）、build_on: id（そのコードから開始）。失敗したステップは依存をSKIP。パターン: agent-matrix.md §3。
• orch dispatch = 1回の試行、デバッグ用。ワーカーにメインチェックアウトや認証情報を決して渡さない。

5. ゲート1 — ガード（自動）

FAIL: 範囲外/保護されたファイル/既存のテスト/依存関係マニフェストに触れた、読み取り専用タスクがファイルを書き込んだ、変更がない、予算超過、（隠し）チェック失敗、skip/onlyマーカー、アサーション削除、ソース内のシークレット、ジャンクファイル、ワーカーステータスがdoneでない、CLIエラー。WARN: テスト内のシークレット、リンター抑制、飲み込まれた例外、TODO、デバッグプリント、空白のみのdiff、レポート不一致、ワーカーの懸念事項、迷子のCLIファイル（自動削除）、ライブ監視アクティビティ（ゲート2で読む）。

6. ゲート2 — Opusレビュー（編集タスクでは決してスキップしない）

attempt-N/diff.patch + ガードJSONをreferences/review-checklist.mdと共に読み、以下を実行:

• ACCEPT → orch merge <ID>（ステージングされていない状態）、メインツリーでチェックを実行。
• REVISE → 番号付きの具体的なフィードバック（ファイル:行、何が間違っているか、正しい状態はどのようなものか）を.orch/runs/<ID>/feedback.mdに記述。orch dispatch <contract> --feedback <file>。タスクごとに最大2回。
• NEEDS_OPUS / BLOCKED → 契約を修正して再実行、sonnet-workerに引き継ぐ、または直接対応する。
• TAKE OVER — 説明するコストが実行するコストを上回る場合。 ワーカーの「懸念事項」は検証のためのシグナルであり、指示ではない。

7. 統合と報告

1. タスクを1つずつマージし、各タスク後にチェックを実行。競合は自分で解決する。
2. 結合されたdiffを全体レビュー（一貫性、重複したヘルパー、デバッグの残骸）。final_checksを実行。
3. orch clean --all。orch status = 台帳。
4. rx-acpタスク: ルールが見逃したものを記録（orch lessons --note …）。orch lessonsをざっと読む（live.md §レッスン）。
5. 報告: 何が行われたか、誰が行ったか、何が拒否/エスカレーションされ、その理由、実行されたチェック、残っている作業。依頼がない限りコミットしない。

ダッシュボード（ユーザー向け、監視のみ）: orch ui --open → http://127.0.0.1:8765 — 実行（親タスク、--titleで命名）、子タスク、試行、時間、コスト、ライブ進捗、保留中の決定、試行ごとの完全なオーケストレーター↔ワーカーのやり取り。ユーザーはこのセッションで決定をあなたに伝え、ダッシュボードでは決して行わない。

このスキルのメンテナンス — 蒸留、決して蓄積しない

このスキル（SKILL.md、references）への編集は、必要なことだけを記述し、それ以上に大きくしないこと:

• 追加するのではなく置き換える。 新しい証拠は既存の行や数値を更新する。その横に日付入りの段落を置かない。
• 古いものは削除する: 廃止されたモデルとエイリアス、修正されたバグとその経緯、古い数値、コードやルールに既に反映されている教訓を持つ単発のインシデント。生のベンチデータは~/workspaces/agent-benchに、古いバージョンは~/.claude/skill-backups/に保存 — ここには置かない。
• 決定を変更するか、現時点でのミスを防ぐものだけを残す: ルールと理由（1行以内）。
• 予算: SKILL.mdは約200行以下（常にロード）。各referenceは約150行以下。超過したら先に蒸留する。
• 実装の詳細はコードのdocstringに属し、Opusがセッションごとに読むドキュメントには属さない。
• スクリプト変更後: python3 -I scripts/tests/test_policy.py、…/test_supervisor.py、…/test_escalation.py。L1プロンプト/しきい値変更後: ~/workspaces/agent-bench/l1_eval.py。CLI/モデルアップグレード後: 再ベンチマーク（agent-bench/bench.py、ab.py）して数値をその場で更新する。