orchestrate-effort

Orchestrate Effort

オーケストレーターとして、/orchestrating に従い、仕様とチケットから 1 つのエフォートを構築します。現在のチェックアウトで作業します。エフォートの作業ツリーとブランチは、開始時に選択されています。設計は確定済みとして扱います。仕様、引き継ぎ資料、またはチケットに未解決の問いがある場合は、設計を変更するのではなく、その範囲内で自分で判断してください。デフォルトではチケットを並行して進め、マシンが許す限り、実際のアプリで検証してください。

パラメーター

• <worktree-tool>：treehouse や通常の git worktrees など、作業ツリーを作成・解放するツール。
• <session-host>：herdr、Claude Code Desktop、Codex Desktop など、エージェントセッションを実行する場所。

手順

1. エフォートを読む。 引数がエフォートフォルダー、または仕様とチケットを指しています。仕様、引き継ぎ資料、すべてのチケットを最後まで読み、各チケットのブロッカー、受け入れ基準、ユーザーからしか得られない入力を確認します。

   • 引数がない場合： 引数を求めます。
   • チケットがない場合： その旨をユーザーに伝えて停止します。チケットは、ユーザーが実行するか依頼するセッションの /to-tickets から作成されます。

2. クリーンな作業ツリーから開始する。 未コミットの変更をそれぞれ個別のコミットにまとめてプッシュし、委任先が触れてはいけないファイルを見つけて回避する必要がない状態にします。

3. /show-me で計画をツリー形式で示します。 まずブロッカーを示し、並行して進めるチケット、ユーザーからの入力を使うチケット、各チケットのレビューの深さを明記します。返信を待たずに続行します。計画はユーザーへの情報提供を目的としており、質問はしません。

   • インストール済みアプリ、単一の実 UI、ポート、データベースなど、共有リソースを使うステップだけを直列化し、チケット全体は直列化しません。ファイルが重複していても、直列化する理由にはなりません。統合時に簡単に解決できる競合です。
   • 大規模またはリスクの高いチケットには、個別に /code-review を実施します。小規模でリスクの低いチケットには実施しません。納品時にブランチ全体を 1 回レビューするためです。

4. ブロックされていないチケットごとに、独自の git 作業ツリーで /implement を使ってサブエージェントに委任します。 サブエージェントはコミットを 1 つ作成し、プッシュはしません。依頼内容には以下を含めます。

   • チケット、仕様、引き継ぎ資料のパス
   • チケットのレビューの深さ
   • サブエージェントに任せず、自分が対応する共有リソース
   • 返してほしい報告内容：コミット、変更したファイル、各受け入れ基準の証拠、一時的な検証コードが残っていないことの証明、実行中のもの、未解決の問い

   リポジトリに記載済みの手順や規約（コミット規則を含む）は依頼に含めません。委任先はリポジトリを読んで確認します。オフスクリーンのレンダリングは時間がかかり、実画面での確認なら見つけられるバグを見逃すため、実際のスクリーンショットとクリックを使って、実際のアプリで検証するよう委任先に依頼してください。 UI を確認するすべての brief に、最終レビューやウォークスルーも含め、確認方法を記載し、自分で実際のアプリを確認するときにも従ってください。

   • ツール： エージェント自身が実行するヘッドレスブラウザーで確認します。たとえば、プロジェクト独自の Playwright テストや、実際の開発サーバーに対する npx playwright を使い、スクリーンショットをファイルに保存します。そこで実際にクリックすれば、実際のアプリでの操作として扱えます。
   • ユーザーの Chrome： 現在のタスクでユーザーから求められた場合に限り、Claude in Chrome 拡張機能を通じて使用します。ユーザーが作業中のブラウザーを占有するためです。ハーネスではこの拡張機能が告知されるため、brief でツールを指定しないと、この拡張機能が使われてしまいます。
   • ユーザーの画面とクリップボード： これらには触れず、ページがクリップボードに書き込む内容はページ内で読み取ります。これにより、Finder のウィンドウを開いたり、open でファイルを開いたり、System Events でアプリをスクリプト操作したりすることを避けられます。System Events にはユーザーが許可しないアクセシビリティ権限が必要です。また、pbcopy や pbpaste も使用しません。
   • 実際のアプリが共有リソースの場合： 委任先にワークツリーで可能な範囲の確認をしてもらい、統合時にバッチごとに一度、自分で実際のアプリを確認します。

5. 各バッチの報告を統合します。

   • 所要時間： 各委任先にかかった時間を記録します。他より大幅に時間がかかったチケットは、プルリクエストの説明に記載し、実行のどこで時間を要したかユーザーに伝えます。
   • コミット： 各委任先のコミットを --no-commit を付けて作業ブランチにチェリーピックし、報告に証拠が示されている各基準にチェックを入れ、チケット固有のコミットとしてコミットします。
   • 確認： バッチ全体に対して、テスト、インストール、実際のアプリでの確認を一度ずつ実行してから、プッシュします。
   • リリース： プッシュ後、統合済みの委任先のワークツリーは、<worktree-tool> の最新の識別情報、占有状況、リースの確認を経た場合に限り解放します。<worktree-tool> が treehouse の場合は /treehouse を使用します。占有中または状態が不明なワークツリーは保持し、その理由を報告します。また、すべての <session-host> トポロジーは開いたままにします。解放に失敗した場合や状態が不明な場合は、再試行する前に状態を調べます。
   • ブランチの削除： 統合の証明を委任先ブランチの先端に結び付け、解放とブランチ削除の直前に再確認します。先端が変わっていたら、新しい先端が反映されたことを証明するか、対象を保持します。委任先のブランチは、そのワークツリーの解放に成功した後にのみ削除します。プッシュ済みの作業ブランチにあるチケットのコミットが、作業が反映された証拠です。チェック済みの基準を含むチェリーピックはパッチが委任先のコミットと一致しなくなるため、git では委任先のブランチがマージ済みであることを示せません。
   • 報告： 反映された内容を一文でユーザーに伝えます。
   • ローカルトラッカーの場合： チェック済みの項目とステータスを、チケット固有のコミットに記録します。ステータスは、完了した場合はコード、チケットをユーザーに渡す場合はユーザーの QA 待ちです。
   • ホスト型トラッカーの場合： コミットをプッシュした後、同様にイシューのチェックリストにチェックを入れ、すべての項目にチェックが入ったらイシューをクローズします。ユーザーに QA を依頼するチケットはオープンのままにします。
   • チェックアウト外でしか基準を確認できない場合： ブランチのコピー、別の環境、インストール後などの場合は、チェックを入れず、どこで確認できたか、何がそれを裏付けるかを一行で記します。確認されるまでチケットはオープンのままにします。
   • 権限の確認によって削除が拒否された場合： そのワークツリーまたはブランチは /settle-effort に引き継ぎます。

6. ユーザーの QA に使えるチケットをユーザーに渡すのは、プロジェクトの指示で QA が明示的に許可され、ビルドをユーザーに届ける方法が記載されている場合に限ります。 最初のチケットを渡す前に user-qa.md を読みます。マージは QA を待ちません。

   • 仕様に「QA: blocking」とある場合： ユーザーが各 QA チケットをクローズするまで、プルリクエストは保留します。その旨をプルリクエストに記載します。 すべてのチケットがコミットおよびプッシュされ、各チケットの受け入れ基準にチェックが付くか記録されるか、ユーザーによって延期されるまで、手順 4〜6 を繰り返します。

7. 納品します。 サブエージェントに最終レビューを委任します。ブランチ全体をベースブランチと比較して、すべてのチェックと /code-review を実施します。見つかった問題の修正も同じ方法で委任し、その後コミットします。/to-pr でプルリクエストを作成し、その説明に、これまでの決定事項と、委任先から報告された予想外の事柄や省略されたチェックをまとめて記載します。差分以外に、説明はユーザーが読む唯一のレポートです。学んだことを書かなければ、このセッションに埋もれたままになります。作業ツリーをクリーンな状態にします。git status にまだ表示されている作業の成果はコミットしてプッシュするか、意図的にファイルを作業対象から外してください。

8. 報告します。 プルリクエスト、各チケットのコミット、延期した事項、ユーザーによる QA 待ちのチケットと、それらを待たずにマージするかどうか、そして git status の結果を報告します。結果がクリーンであるか、作業対象から外した各ファイルとその理由を記載します。QA 以外でユーザーが行うのは、プルリクエストのレビューと承認だけです。指示を受けた後に行う作業を、独立した手順として列挙します。プルリクエストのマージ、インストールや更新などの作業に伴うマージ後のフォローアップ、マージ後にしか試せないことの確認と結果の報告、そして /settle-effort による作業の完了です。

参考資料

• user-qa.md：チケットをユーザーによる QA に回す方法と、「Ready for you to try」コメントに記載する内容です。