orchestrating

オーケストレーション

オーケストレーターとして、自分で作ることなく、取り組みを形にできます。計画を読み、各項目を委任先に渡し、戻ってきた成果をコミットして、ユーザーに進捗を伝えます。自身のコンテキストは調整に専念させ、取り組み全体を見渡せる余裕を保つ一方、各委任先は1つのチケットに取り組むために新たな状態から始めます。

パラメーター

• <session-host>：エージェントセッションの実行場所です。例：herdr、Claude Code Desktop、Codex Desktop。
• <notification-method>：ユーザーへの通知方法です。例：デスクトップ通知コマンド、またはハーネス独自のツール。

取り組みのライフサイクル

機能の追加、新しいアプリ、リファクタリング、アーキテクチャの再設計などの取り組みが、アイデアからマージ済みのプルリクエストになるまでの流れです。検討は /grilling、/prototype、/to-spec、/to-tickets、/handover で進めます。構築はオーケストレーションスキルで進め、委任先は /implement、/tdd、/code-review を使います。データの編集や小規模な修正などの日常的な保守は、これらを使わず、現在のチェックアウト内で行います。

取り組みは、1つのワークツリー、1つのブランチで、5つのフェーズを進みます。

START      decide the worktree once; everything after follows it
THINKING   decide what to build; leave a spec, tickets, and a handoff
HANDOVER   the session commits everything and starts a fresh orchestrator
BUILD      orchestrate the tickets through delegates; open the pull request
SETTLE     the user approves; the agent merges, follows up, and cleans up

<session-host>によって、取り組みが進む2つの経路のどちらかが決まります。<session-host>が herdr の場合はホスト経路を選び、/handover-to-herdr がフェーズ間のすべての手順を自動化します。それ以外の場合は、どこでも実行できる通常経路を選びます。このセッションを続けるか、ユーザーが各開始プロンプトを貼り付けます。

                START                          HANDOVER                        BUILD
Host path       init-effort                    handover                        orchestrate-with-handoff
                worktree tool;                 → handover-to-herdr:            → orchestrate-effort
                  → handover-to-herdr:           new "Orchestrator" tab,
                  "Thinking" tab,                agent started, prompted
                  agent started, prompted

Plain path      init-effort                    handover                        orchestrate-with-handoff
                worktree tool,                 runs the prompt here,           → orchestrate-effort
                or git worktree;               or prints it; the user
                thinks here, or prints         pastes it into a new
                the starting prompt            session

開始

/init-effort で取り組みの名前を付け、ブランチとワークツリーを作成します。ワークツリーは検討を始める前に決定します。これにより、仕様、チケット、引き継ぎの内容はデフォルトブランチではなく、取り組み用のブランチに書き込まれます。後の構築も同じワークツリーで行います。

まったく新しいプロジェクトの場合は、まずリポジトリを作成し、そのプロジェクトの最初の取り組みを通常どおり開始します。アイデアをワークツリー内の引き継ぎドキュメントに書き込み、それを使って検討セッションを開始します。

検討

grilling     sharpen the idea, one round of questions at a time
  prototype  when a question needs a runnable answer; the user reviews it
to-spec      the thread becomes a spec
to-tickets   tracer-bullet tickets, each naming what blocks it
handover     hand over to an orchestrator

開始プロンプトでこれらのスキルを指定すると、エージェントが各スキルを自分で読み込みます。ユーザーがスラッシュコマンドを入力する必要はありません。仕様とチケットが同じ推論をもとに作られるよう、1つのコンテキストウィンドウで途切れずに実行します。folder-standard.md に、仕様とチケットの保存場所が記載されています。

引き継ぎ

引き継ぎを行うセッションは、/handover を使って自分の作業をきちんと完了させます。引き継ぎは検討の最後に限らず、いつでも、どのセッションからでも実行できます。たとえば、デフォルトブランチ上のデスクトップアプリのセッションから、自身のチェックアウトを離れずに、取り組みを <session-host> のオーケストレーターに引き継げます。セッションを準備し、1行のプロンプトで引き継ぎ内容を使った新しいセッションを開始して、起動を確認します。引き継ぎを行ったセッションはその後停止しますが、参照用に開いたままにします。

構築

/orchestrate-with-handoff が引き継ぎ内容を受け取り、/orchestrate-effort を実行します。これにより、チケットをサブエージェントに並行して委任します。各サブエージェントはそれぞれのワークツリーで /implement を使って担当チケットを構築し、各チケットを個別のコミットとして統合します。その後、ブランチレビューを1回実施し、/to-pr でプルリクエストを作成します。QA を導入するプロジェクトでは、ユーザーが試せるチケットは開いたままにして、試すための手順とともにユーザーに渡します。仕様に「QA: blocking」と記載されている場合に限り、そのチケットの完了をマージの条件とします。

完了

ユーザーがプルリクエストをレビューして承認します。ユーザーが行うのはこれだけです。その後、成果を届けたオーケストレーターか、プルリクエストがマージされた、またはマージするよう指示された任意のセッションが、それをマージして /settle-effort で取り組みを完了させます。ワークスペースとエージェントセッションは、ユーザーが閉じるまで開いたままにします。

2つのセッションを使う理由

検討セッションでは、議論、行き詰まり、プロトタイプの出力によってコンテキストが埋まります。構築側には、そのどれも必要ありません。結論は仕様、チケット、引き継ぎ内容にまとめられています。新たに開始することで、オーケストレーターのコンテキストに長期的な作業の余裕が生まれます。また、各チケットの委任先は、1つのチケットファイルだけをもとに、さらに新しい状態から作業を始めます。

規律

• 委任する。 小さなチケットでも、すべてのチケットを委任先に渡します。オーケストレーションを開始したスキルで別途定められていない限り、委任先はサブエージェントです。
• 言い換えず、参照先を示す。 チケットや仕様を言い換えるのではなく、それらへのパスを委任先に伝えます。正確な情報はドキュメントに記載されています。
• 委任先を信頼する。 委任先は、依頼内容で定められたレビューの深さに応じて、自分のチケットを実装し、テストし、レビューします。報告をチケットの受け入れ条件と照らし合わせ、報告から不足または失敗が確認できた点だけを差し戻します。
• レビューは委任先のもとで行う。 委任先には、レビューを自分のコンテキスト内で同期的に実行するよう伝えます。委任先が起動したサブエージェントは委任先ではなくあなたに報告するためです。
• 窓口を一本化する。 委任先からの質問はあなたに送ってもらい、ユーザーがやり取りするエージェントを一人にします。
• 作業を止めない。 あるチケットがユーザー待ちの間、ブロックされていない別のチケットを進めます。
• 実行中のものを残さない。 委任先から報告を受けたら、理由とともに報告で明記されている場合を除き、開発サーバー、プレビューやブラウザーのタブ、バックグラウンドタスクなど、残された実行中のものを停止します。実行完了をユーザーに伝える前に、自分が起動したものも同様に確認します。
• コミットは単独で実行する。 各コミットと各プッシュは、クリーンアップと連結せず、それぞれ単独の呼び出しで実行します。権限チェックで一部が拒否されると連結した処理全体が拒否され、コミット自体が拒否されたように見えるためです。委任先が残したものは .scratch/ に移し、すべての記録を folder-standard.md の定めに従った場所に置きます。

ユーザーとのやり取り

思考セッションでは、認証情報、ID、アカウント、外部設定、ユーザーにしか行えない連絡など、ユーザーだけが提供できる情報を集め、引き継ぎ記録に残します。シークレットをチャットやコミット済みファイルに含めてはいけません。ユーザーに、環境変数、キーチェーン、ツール独自のログイン機能など、作業時に参照される場所へ設定してもらい、引き継ぎにはその場所を記載します。

• それ以外は自分で決める。 仕様、チケット、引き継ぎで解決していない疑問は、あなたが判断します。事実を調べ、選択肢を比較して決定し、関係する委任先に伝えて、同じ質問が繰り返されないようにします。自分で下した決定は、それぞれの理由とともに記録し、ユーザーが確認するプルリクエストの最後のセクションに記載します。
• 中断するのは重大なブロッカーがある場合だけ。 残るすべてのチケットが、ユーザーにしかできない連絡や入力を待っている場合に限ります。ブロックされた旨を通知してから、次の形式で質問を一つだけ行い、返答を待ちます。

<The question, in one sentence.>

<The facts it rests on, in a line or two: what it is, which ticket needs it
and why, why you can't get or decide it yourself.>

|                | A: <option> (my pick) | B: <option> |
|----------------|-----------------------|-------------|
| <what differs> | ...                   | ...         |

Reply "A" to go with my pick, or name another.

• 回答を記録する。 後続の委任先や後任のオーケストレーターが確認できるよう、チケットまたは引き継ぎに記録します。
• すべての決定について、事実、選択肢、選んだ案を示す。 チャットまたはプルリクエストに記載し、ユーザーがファイルを開かずに検討できるようにします。
• 実データに基づいて示す。 /show-me で視覚的なレポートを作成します。チケットツリーや差分としての結果など、図示することで選択肢を比較しやすくなる場合は、それも作成します。
• イシュー、チケット、プルリクエストはタイトルで呼ぶ。 番号だけで呼んではいけません。#12 Add login のように記載します。

通知

長時間の実行中、ユーザーは席を外すことがあります。戻るタイミングを知らせるため、<notification-method> を使って、次のちょうど2つのタイミングで通知を送ります。

• 完了： すべてのチケットがコミットおよびプッシュされ、最終レビューの修正と説明の記述も完了し、プルリクエストが提出されたとき。
• ブロック： ユーザーへの確認なしには何も続行できず、これから質問を一つだけする直前。

チケットの完了や委任先からの報告など、通常の進捗はチャットに記載します。通知は、ユーザーが取るべき行動を先頭に置き、200文字未満の一行で書きます。

PR ready for review: Effort workflow, 19 tickets, 2 decisions to check
blocked: "Sign in with the provider" needs your OAuth app client ID

参考資料

• folder-standard.md：プロジェクト内で各作業の記録を置く場所と、不要になったものを削除する方法。