herdr-orchestration

herdr オーケストレーション

トップレベルのエージェントはコントローラー（Codex、Claude、Fable など）です。コントローラーは、証拠を集め、範囲を限定したパッチを作成し、テストを実行して報告するワーカー TUI に作業を委任します。割り当て、状態管理、競合制御、検証、統合、およびユーザー向けの最終回答は、コントローラーが担当します。herdr は基盤です。各ワーカー TUI は名前付きタブを所有し、ソケット CLI（herdr …）により、コントローラーは配置、入力、画面の読み取り、およびネイティブなエージェント状態の待機を行えます。

ワーカーごとに名前付きタブを1つ

各ワーカーには専用のタブを割り当て、作成時に tab create --label でラベルを付けます。タブバーはコントローラーのダッシュボードです。ラベル付きタブを見れば、どのモデルがどの作業範囲を担当しているかがわかり、稼働中のワーカーが何人いても読みやすい状態が保たれます。

タブは画面領域も消費しません。分割ペインでは呼び出し元の画面をすべてのワーカーと分け合うため、ノート PC では3人目のワーカーを追加すると、どのペインも狭くなりすぎて読めなくなります。ユーザーから、呼び出し元の横でワーカーを表示するよう明示的に求められた場合にのみ、ペインを分割してください。

ワーカーには起動時に2つの名前が必要です。

• タブラベル — <model>: <slice>。例：opus: fix loops、 codex: audit auth。自由入力ですが、タブバーでは省略表示されるため、短くしてください。
• エージェント名 — 作業範囲をスラッグにしたもの。例：fix-loops。[a-z][a-z0-9_-]{0,31} に一致し、稼働中のエージェント間で一意である必要があります。すべての agent … 動詞では、ペイン ID の代わりにこの名前を使用できます。

ワーカーは TUI です — ヘッドレスランナーは使用しないでください

ワーカーは対話型 TUI（claude または codex）です。herdr agent start で起動すると、エージェントの識別情報が検証され、herdr が入力可能な状態になったことを確認してから戻ります。herdr のエージェント状態統合はこれらの TUI に接続するため、agent wait、agent list、およびブロック中／完了の検出は、実際の TUI が画面上にある場合にのみ機能します。

claude -p、codex exec、ペインに JSON イベントをストリーミングするものなどのヘッドレスランナーは状態を報告しないため、待機は完了せず、委任は何も通知されずに失敗します。ワーカーのタブに生の JSON イベント行が流れ続ける場合、委任に問題があります。中断して（rtk herdr pane send-keys <pane_id> ctrl+c）、agent start から起動し直してください。

不変条件

• ユーザーが別の対象を指定しない限り、すべての操作は呼び出し元のワークスペース内に限定してください。
• フォーカス中のウィンドウへのフォールバックより先に、すべての herdr ペインに挿入される HERDR_WORKSPACE_ID、HERDR_TAB_ID、HERDR_PANE_ID から呼び出し元のコンテキストを特定してください。
• コマンド JSON から解析した ID でワーカーを指定してください。agent … 動詞ではエージェント名、タブおよびペインの動詞では w2:t3／w2:p4 を使い、位置を推測して指定してはいけません。
• 作成を行うすべての動詞（tab create、workspace create、worktree create、pane split）には --no-focus を渡してください。フォーカス動詞はユーザーが求めた場合にのみ使用してください。
• 担当作業と予定されている統合後のフォローアップが完了したら、起動したワーカーをすべて終了してください（「ワーカーの終了」を参照）。

事前確認

デーモン、統合、および呼び出し元のコンテキストを確認します。

rtk herdr status                 # server running + socket path
rtk herdr integration status     # selected worker runtime must show `current`
rtk herdr pane current --current # caller pane / tab / workspace ids
rtk herdr agent list             # agents already running

選択した各ランタイムについて、その統合のみを確認またはインストールしてください。デーモンと統合に変更がなければ、同じワークスペース内ではこの事前確認を再利用できます。新しいパケットがあるだけなら、繰り返す必要はありません。

ワーカーの起動

ユーザーから別のモデルを指定されない限り、各ワーカーのランタイムで設定されているモデルを使用してください。起動には2つのコマンドが必要です。名前付きタブを作成し、そのタブのルートペインで TUI を起動します。

# 1. named tab — returns .result.tab.tab_id and .result.root_pane.pane_id
rtk herdr tab create --workspace "$HERDR_WORKSPACE_ID" --cwd "$PWD" \
  --label "opus: fix loops" --no-focus

# 2. worker TUI in that tab's root pane; native flags follow `--`
rtk herdr agent start fix-loops --kind claude --pane <root_pane_id> -- \
  --dangerously-skip-permissions "<packet>"

rtk herdr agent start audit-auth --kind codex --pane <root_pane_id> -- \
  --yolo

tab_id、pane_id、エージェント名をレジストリに記録してください。終了処理と画面の読み取りには、この3つすべてが必要です。

Claude は必ず --dangerously-skip-permissions を指定して起動し、Codex は必ず --yolo を指定して起動してください。ワーカーは無人で実行されるため、権限プロンプトで停止してはいけません。計画を先に立てる実行では、Claude に --permission-mode plan を追加します。これらのフラグは併用できます（「計画を先に立てる委任」を参照）。

agent start は、herdr がエージェントの準備完了を検出した後にのみ成功を返します。そのため、ゼロ以外の終了コードは起動失敗を意味します。再試行する前に、タブのルートペインを読み取ってください（rtk herdr pane read <pane_id> --source visible）。rtk herdr tab list --workspace "$HERDR_WORKSPACE_ID" でラベルが保持されていることを確認してください。タブにデフォルトのラベルが表示されている場合は、次のように元に戻します。

rtk herdr tab rename <tab_id> "opus: fix loops"

実行中の TUI にプロンプトを送信する

初期パケットは起動時の argv として渡す方法を優先してください（上記参照）。セッションがすぐに動作を開始し、TUI の準備完了を待つ競合を回避できます。例外は Codex のプランファースト起動で、何も指定せずに起動します（「プランファーストの委任」を参照）。

以降の指示には agent prompt を使用してください。テキストと Enter をまとめて送信し、ペインの現在のブラケット付きペーストモードに従います。また、--wait を指定するとワーカーが処理を終えるまで待機します。

rtk herdr agent prompt fix-loops "<follow-up prompt>" --wait --timeout 300000

pane send-text の末尾に \n を付けても送信されません。TUI ではソフト改行として表示され、プロンプトは未送信のままです。確認されていない送信は配信されません。--wait が agent_prompt_stalled を返した場合、ワーカーの状態は変化していません。画面を読み取って再送信してください。

プランファーストの委任（オプトイン）

プランファーストが実行されるのは、ユーザーが明示的に有効にした場合のみです。「plan first」や「plan mode」といった明示的な依頼、または呼び出し時の --plan-mode フラグで有効になります。デフォルトの委任方法は直接実行です。起動したら、そのまま作業を進めます。調査が複雑というだけでは、計画の承認手順は追加されません。

有効にすると、ワーカーが計画を立て、コントローラーが確認して承認した後、そのまま作業を進めます。起動フラグ、Shift+Tab の操作手順、ステータス確認、承認メニューは、TUI ごとに異なり、厳密に指定されています。プランファーストのワーカーを起動する前に、references/plan-mode.md を最後まで読んでください。

委任パケット

各ワーカーのプロンプトは、単独で完結する契約として送信してください。以下を含めます。

• リポジトリのパスと具体的な目標
• ワーカーの役割とモデル
• 実行モード：直接実行（デフォルト）またはプランファースト（ユーザーが有効にした場合）
• 対象となるファイル、パッケージ、または領域
• 明示的に対象外とするファイルと動作
• 競合を避けるための、担当ファイルまたは作業範囲
• 依存関係と、ワーカーが前提としてよい現在のインターフェース／契約
• この作業の完了を示すために必要な証拠：変更したファイル、結果と確認済みの入力を含むコマンド、関連する成果物、残っている不確実性
• 検証の担当範囲：ワーカーによる確認、コントローラーによる統合確認、外側のワークフローが担当する最終納品時の確認
• 停止条件：予期しないコードの構造、コマンドの繰り返しの失敗、認証／モデルの障害、または対象外の編集が必要な場合

独立して進められる、一貫性のある成果を割り当ててください。利用側が未確定のインターフェースに依存する場合は、まずそのインターフェースを確定するか、提供側と利用側を同じ担当者に任せてください。ファイル数だけを理由に作業を分割してはいけません。ワーカーには、コードベースを共有していること、他の変更を維持する必要があること、依存する作業を進める前にインターフェースの変更を報告する必要があることを伝えてください。関連する統合作業の修正には同じワーカーを再利用し、新たな調査を割り当てるのではなく、変更後の契約と残りの作業を伝えてください。

ワークツリーの分離

ワーカーが並行して重複するファイルを編集する必要がある場合は、それぞれに分離したワークツリーを割り当ててください。herdr は、独自のラベル付きワークスペースとして、ネイティブにワークツリーを管理します。

rtk herdr worktree create --workspace "$HERDR_WORKSPACE_ID" \
  --branch <slug> --label "<slug>" --no-focus --json

ワーカーのタブはそのワークスペース内に作成してください（tab create --workspace <worktree_workspace_id>）。そうすると、そのタブの cwd は分離されたチェックアウトになります。

ワーカーを追跡する

オーケストレーションは長時間にわたります。ワーカーの作業は数分から数時間かかり、待機時間が切れたからといってワーカーを放置することはありません。画面をポーリングする代わりに、herdr のネイティブなエージェントステータスを、チェックイン間隔（作業の規模に応じて設定し、重い作業ほど長くする）の3～5分ごとに確認して待機します。

rtk herdr agent wait fix-loops --until done --timeout 300000     # completion check-in
rtk herdr agent wait fix-loops --until blocked --timeout 300000  # question or menu
rtk herdr pane wait-output <pane_id> --match "<text>" --timeout 300000

コントローラーによる読み取りではタブが既読にならないため、フォーカスされていないワーカーは idle ではなく done に落ち着きます。done を待機してください。--timeout はチェックイン間隔であり、ワーカーの期限ではありません。タイムアウトしたら、画面を読み取り（rtk herdr agent read fix-loops --source recent-unwrapped --lines 120）、再び待機します。ワーカーが終端状態になるか、質問するか、停止条件が発生するまでループしてください。報告されたステータスがおかしい場合は、rtk herdr agent explain <pane_id> --json で検出をデバッグします。

既存のタスクメモまたは引き継ぎに、簡潔なレジストリを維持してください。コントローラーの識別情報、ワーカーのエージェント名・タブラベル・役割・モデル、ワークスペース／タブ／ペインの ID、送信した目標と開始時刻、ステータス（starting、planning、plan-review、plan-accepted、running、blocked、reported、verified、retired）、担当ファイルまたは作業範囲、ワーカーが報告したコマンドと結果、コントローラーが実施した検証、最終処置（accepted、rejected、superseded、blocked）を記録します。

作業範囲が変わったらタブラベルを最新の状態に保ち、フォーカスを奪わずにマイルストーンを通知します。

rtk herdr tab rename <tab_id> "opus: fix loops (verifying)"
rtk herdr notification show "Workers done" --body "2/2 verified" --sound done

ワーカーの出力を検証する

検証が済むまでは、ワーカーの出力を信頼できないものとして扱います。フォーカスを変えずに監視し、検証してください。

• ワーカーのタブを読み取り専用で読み取ります（agent read <name> --source recent-unwrapped --lines 200）。出力が不明瞭な場合は、簡潔なステータスの要約をワーカーに依頼します。
• 影響の大きい指摘については、引用されたファイルをローカルで再度開いて検証します。視覚的な出力の場合は、納品された画像と、名前が挙げられた視覚的な参照資料を並べて開きます。ファイル数、寸法、ワーカーの判断だけでは、視覚的な適合性は確認できません。コストのかかる生成バッチを拡大する前に、代表的な画像を1つ確認します。
• コマンドの結果、終了ステータス、確認済みの入力、証拠のパスを調べます。入力に変更がない場合は、信頼できるワーカーの証拠を再利用します。不足している、古い、矛盾している、または検証できないチェックは再実行します。ワーカーが実施していない統合チェックと、プロジェクトポリシーで求められるチェックは、コントローラーが実行します。ワーカーからの引き継ぎだけを理由に、証拠が無効になったり、テスト一式を再度実行する必要が生じたりすることはありません。
• ワーカーのパッチを受け入れる前に、最終差分を確認します。
• ワーカーが担当範囲外を編集した場合は、統合作業を一時停止し、受け入れるか、ユーザー承認のもとでのクリーンアップを依頼するか、コントローラーによる編集で置き換えるかを判断します。

完了した応答で --lines を増やしても追加の内容が表示されなくなった場合、TUI はターミナルの代替画面にあり、それらの行は失われています。ワーカーにレポート全体を一時ディレクトリに Markdown として書き込み、そのパスを返信するよう依頼し、ファイルを読み取ってください。

ワーカーを終了する

委任はワーカーを終了した時点で完了します。つまり、タブを閉じます。関連する後続作業が見込まれる場合は、結果のレビューや統合の間、報告済みのワーカーを利用できる状態にしておきます。最終処置を記録し、作業が済んだら終了してください。

rtk herdr tab close <tab_id>

タブを閉じるとTUIセッションとスクロールバックが終了するため、まずレジストリに必要な情報を記録します。レポート本文、引用された行番号、コマンド出力などです。ファイル、差分、ワークツリーはディスク上に残ります。

実行中、ブロック中、予定されている統合後のフォローアップを待機中、画面が未解決の失敗の証拠となっている場合、またはユーザーが確認を求めている場合は、ワーカーを開いたままにします。その理由をレジストリに記録してください。rtk herdr agent list でこのコントローラーの実行中のワーカーがいないことを確認できたときにのみ、オーケストレーションは完了です。すべてのワーカーが終了しているか、開いたままのタブについてレジストリに理由が記録されている必要があります。

停止条件

次の場合は、推測で進めずに停止して報告してください。

• herdr が有効なワークスペース、タブ、またはペインの参照を拒否する場合、または rtk herdr status に実行中のサーバーが表示されない場合。
• ワーカーの TUI がモデルエイリアス、認証状態、作業ディレクトリ、または起動フラグを拒否する場合は、問題の内容を正確に報告し、モデルのダウングレードやツールの切り替えを行う前にユーザーの承認を得てください。
• 認証によって TUI の利用が妨げられる場合。
• 出力がスクロールしている間、ワーカーのステータスが unknown のままで、agent explain に一致するルールが表示されない場合。検出機能に不具合があるか、ペインでヘッドレスプロセスが実行されています。
• agent read または pane wait-output でプランモードのステータス行や選択メニューを確認できない場合、または再計画後もワーカーのプランがスコープ外のままである場合。
• ワーカー間で重複する編集が必要で、コントローラーが安全に統合できない場合。
• ユーザーが承認していない、フォーカスを変更する herdr の動詞がタスクで必要になる場合。