Herdrマルチエージェント：並列コーディングエージェントワークフロー

--- name: herdr-multiagent description: Run several coding agents in parallel under Herdr: stage decomposition, one git worktree, isolated env, pane and file brief per agent, state monitoring, review, merge. Child kind is read from `herdr pane current` (.result.pane.agent) and matches the orchestrator (omp, opencode, claude, codex, kimi, ...). Requires HERDR_ENV=1. --- # Herdrによるマルチエージェント作業 プレイブック: プロジェクトのタスクを独立したステージに分解し、各ステージに個別のエージェントを自身のgit worktreeとherdrペインに配置し、ファイルブリーフを渡し、監視して結果を受け入れる。 スキルはエージェント非依存: 子のkind = オーケストレーターのkind。opencodeからスキルを起動した場合、子はopencodeになる。ompからはomp、claudeからはclaude。オーケストレーターのkindを記憶から推測したり、「一般的な」kindを選んだりしないこと。 ## 0. 前提条件 ```bash test "${HERDR_ENV:-}" = 1 # これがない場合は停止、Herdr内ではない ``` チェックが失敗した場合、ユーザーにセッションがHerdr配下ではないことを伝え、停止する。外部から他人のHerdrを操作しないこと。 ペイン/エージェントの基本コマンドは標準のHerdrスキル(`herdr --skill`)に記載。インストール済みバイナリが構文の権威であり、疑わしい場合は`herdr agent`、`herdr pane`、`herdr integration`を読むこと。推測しないこと。 ## 1. 自身のkindを特定する - いかなる行動の前に ```bash herdr pane current --current ``` `.result.pane.agent`フィールドがオーケストレーターのkindであり、子の`--kind`の値でもある: ```bash KIND=$(herdr pane current --current | jq -r '.result.pane.agent') # jqなしの場合: KIND=$(herdr pane current --current | sed -E 's/.*"agent":"([^"]+)".*/\1/' | head -1) echo "$KIND" ``` 空または`unknown`の場合、ユーザーに子をどのkindで起動するか尋ねる。以降のテキストで`$KIND`は取得した値であり、リテラルではない。 Herdr ↔ このkindの統合を確認する(これにより`agent list/wait/prompt`が提供される): ```bash herdr integration status | grep -i "$KIND" ``` - `current` - OK。 - `not installed` - `herdr integration install "$KIND"`。統合は**新しい**セッションのみで有効になるため、子の起動**前**にインストールすること。オーケストレーター自体は`agent list`に表示されない - これは正常であり、監視する必要はない。 - kindが`herdr integration install`のリストにない場合(例: `amp`、`cline`、`kiro`、`maki`) - 構造的監視は行われない。§7のフォールバック(`pane read` + git)で作業する。これはブロッカーではない。 ユーザーに確定して宣言する: 「子のkind = $KIND」。 ## 2. 分解 - 最重要ステップ、急がないこと - プロジェクトの計画/スペックと現在の状態(`git log`、テスト、`git worktree list`)を読む。 - 残りの作業を**ファイル領域が重複しない**ステージに分割する。1つのパッケージに2つのエージェントを配置するのは、意図的かつ明示的な順序がある場合のみ(並列ではなく、後続)。 - 共通ファイル(config、lock)への追加的な編集は許容 - ブリーフに「追加のみ、シグネチャ変更なし」と記載する。マージ競合はオーケストレーターが解決する。 - 「ステージ → 触ってよい/いけないファイル」のマトリクスを確定する。 起動前に: mainの完成済みのものはすべてコミット済み、ツリーはクリーン。 ## 3. Worktree + エージェントごとの分離環境 ```bash git worktree add ../<proj>-s<N> -b stage-<N>-<name> ``` Pythonプロジェクトの罠: 共有venvは**他人の**コードをインポートする(メインリポジトリのeditable install)。各worktreeに独自のvenv: ```bash cd ../<proj>-s<N> && python -m venv .venv \ && ./.venv/Scripts/python.exe -m pip install -q -e "./api[dev]" ``` 複数のvenvは1つのバックグラウンドコマンドで順次インストールする(pipキャッシュは共有)。JSスタック: 各worktreeに独自の`node_modules`(`npm ci`)。 オーケストレーターにコマンドラッパーフック(rtkなど)がある場合: ブリーフ内の相対パス(`../.venv/Scripts/python.exe`)はそのようなフックでは解決されない(「command not found」)。ブリーフとプロンプトでは、該当worktreeのpython/npmへの**絶対パス**のみを使用する。 ## 4. ブリーフ - コマンドラインではなくファイルで `<repo>/.briefs/stage-<N>.md`(untracked)。ブリーフの構造: - **コンテキスト**: 最初に読むべきもの(スペック、コントラクト、主要ファイル)、既に完了していること。 - **タスク**: スペックの項目への参照付きの具体的な要件。 - **境界**: ファイルの可否、「worktreeから出ない」、「pushしない」。 - **受け入れ**: 正確なテスト/リンターコマンド(worktreeのインタープリターへの絶対パス付き)、「既存テストはグリーンのまま」、自分のブランチへのコミット、最終レポート。 ブリーフは特定のエージェントkindを前提としないこと: 「omp/skill/...を起動」と書かず、目的、境界、受け入れコマンドを書く。子は自身のツールでどう実行するかを自分で決める。 エージェントへのプロンプトは短く: 「ファイル<ブリーフ>を読んで、最後まで実行してください」。 ## 5. ペイン: 作成、**すぐに**命名 推奨レイアウト - main-left: オーケストレーターペインを左に全高、すべての子を右に縦に並べる。ユーザーがmain-left向けのレイアウトプラグインを設定している場合、他のスキームは彼の視界を壊す。ユーザーが明示的に別のレイアウトを要求した場合は、それに従う。 最初の子 - `split --current --direction right`、残り - `split --pane <前の子> --direction down`を右カラム**内**で。オーケストレーターペインを分割したり、エージェントペインを右に分割したりしない - 右カラム内のdownチェーンのみ。 ```bash herdr pane split --current --direction right --cwd "<worktree1>" --no-focus herdr pane split --pane <agent1-pane> --direction down --cwd "<worktree2>" --no-focus ``` 新しいペインのIDはJSON `.result.pane.pane_id`から。ユーザーのフォーカスは触らない(`--no-focus`)。子の名前はステップ6で`agent start`により付けられ、視認性のため`herdr pane rename <pane_id> "s<N>-<name>"`も実行。 ## 6. 自身のkindの子を起動 標準的な方法は`agent start`で、ペインで期待通りのエージェントが起動したことを検証する: ```bash herdr agent start s1-<name> --kind "$KIND" --pane <pane_id> -- <自律性フラグ> ``` 名前は`[a-z][a-z0-9_-]{0,31}`に一致し、生存中のエージェント間で一意であること。 ### 自律性フラグ 子は人間なしで動作する。そうでなければ承認で停止する。フラグはHerdrではなくCLIに依存する。確認済み: | kind | 起動 | |---|---| | `omp` | `-- --yolo` | | `claude` | `-- --dangerously-skip-permissions` (または `--permission-mode bypassPermissions`) | | `opencode` | `-- --auto` | 他のkind(codex、gemini、kimi、cursor、copilot、droid、kilo、grok、hermes、qodercli、mastracode、piなど)の場合 - フラグをでっち上げない。canonical実行ファイルを特定し、そのヘルプを読む: ```bash herdr agent start --help # --kindの説明にcanonical executableが記載 <executable> --help | grep -iE "permission|approve|yolo|auto|dangerous|allow" ``` フラグが見つからない場合 → CLI設定に自律モードがあるか確認し(例: `~/.omp/agent/config.yml: tools.approvalMode: yolo`、`~/.claude/settings.json: permissions`、`opencode.json: permission`)、子が承認で停止する可能性があることをユーザーに警告する - それらは`blocked`状態として見える(§7)。 ### `agent start`がタイムアウトで失敗した場合 WindowsのPowerShellペインで既知のバグ: `agent start`が壊れた`Start-Process`を送信 → タイムアウト。回避策 - ペインで直接CLIを起動: ```bash herdr pane run <pane_id> "<executable> <自律性フラグ>" sleep 3 && herdr pane read <pane_id> --lines 15 # CLIプロンプトを期待 herdr agent rename <pane_id> s1-<name> # herdrがエージェントを認識した場合 ``` その後`herdr agent explain <pane_id>`が認識されたエージェントを返さない場合 - このペインの構造的監視は利用不可。§7のフォールバックで作業する。 ### ブリーフの配布 `pane run`経由**ではない**: TUIが挿入をレンダリングしている間、Enterは飲み込まれる。2ステップで一時停止: ```bash herdr pane send-text <pane_id> "ファイル<ブリーフへの絶対パス>を読んでください - これがあなたのブリーフです。最後まで完全に実行してください(コード、テスト、リンター、自分のブランチへのコミット)、その後最終レポートを提供してください。" sleep 5 && herdr pane send-keys <pane_id> Enter ``` 統合がインストールされ`agent start`が成功した場合の標準的な代替: ```bash herdr agent prompt s1-<name> "ファイル<ブリーフ>を読んで、最後まで実行してください" --wait --timeout 300000 ``` `pane read`でブリーフが**送信された**ことを確認: inputが空、エージェントが動作中。 ## 7. 監視 - cronではなく統合経由 ```bash herdr agent list # すべての子のステータス herdr agent wait s1-<name> --until idle --timeout 1800000 herdr agent prompt s1-<name> "<テキスト>" # 作業中のエージェントに指示を追加 herdr agent read s1-<name> --lines 40 ``` 状態の意味: `idle` - 入力を受け付け可能で、そのタブがUIで見られた。`done` - 見えないバックグラウンド作業後の同じidle(CLI経由の読み取りはタブを見られたとマークしない)。`blocked` - herdrが承認/質問UIを認識し、子が人間を**待っている**。`unknown` - エージェントは存在するが分類がない。これは完了の兆候ではない。 オーケストレーターのループ: `agent wait`を順番またはイベントベースで → 受け入れ(§8)。`blocked` → `agent read`で質問を理解し、`agent prompt`で回答するかユーザーに尋ねる。不審な沈黙 → `pane read <pane_id>`。 `wait`のタイムアウトは適度に保つ(~30分)し、発火したら再設定する: 非常に大きな値は「timed out」になる。 `$KIND`の統合が利用不可、または`agent explain`が子を認識しない場合のフォールバック: 定期的な`herdr pane read <pane_id> --lines 60` + worktree内の`git log/status`。Cronは最後の手段のみで、完了時に必ず削除する。 子セッションの切断: worktree内の作業は保持される。再起動は同じCLIとその継続フラグで(`--help`で確認): `omp --resume`、`claude --continue`、`opencode --continue`。その後プロンプト: 「セッションが中断されました。git statusを確認し、ブリーフ<ファイル>を最後まで完了させてください」。 ## 8. 受け入れとマージ - 各ブランチ: そのworktreeでテスト + リンター、`git diff main...<branch> --stat`のレビュー。 - 子の最終レポートを鵜呑みにしない - 受け入れコマンドを自分で検証する。 - mainへのマージはユーザーの確認がある場合のみ。追加的な競合は手動で解決する。 - マージ後: `git worktree remove`。ブランチはユーザーとの合意による。 - 子のペインを解放し、ユーザーのペインには触れない。