flock-agents

flock-agents - バックログを自律的に実行

一晩中、人の手を介さずにバックログ全体のチケットを実装します。実装したいビルドチケットの仕様書（または親課題）を渡すと、設定済みの課題トラッカーからリンクされたチケットを取得し、コンテキストとして仕様書と完了済みのチケットを読み込み、未完了チケットを依存関係の順に並べ替えます。その後、チケットごとにエージェントを実行します。各エージェントは専用の git worktree で /implement スキルを使用し、チケットの難易度に合わせたモデル（下記のモデルマトリックスを参照）を高い推論負荷で動かします。そして朝には、選択した成果物を受け取れます。レビュー済みブランチのスタック、統合ブランチ、またはレビュー準備が整った PR です。

きちんと定義された、セッション内で完了できるビルドチケットが大量にあり、AFK で実装したい場合に使用します。これは、仕様書から /to-tickets が生成したトレーサーバレットチケットであり、wayfinder の意思決定チケットではありません。そのため、wayfinder 由来の取り組みで flock を使う場合は、マップそのものではなく、マップから /to-spec が生成した仕様書を指定してください。マップの子課題は HITL の意思決定であり、まだ決定が必要なチケットは、ここではなく、まずグリリングまたはプロトタイプセッションで扱う必要があります。

入力

指定されていない場合は、まず次の情報を尋ねます。

• SOURCE — 実装するビルドチケットの仕様書または親課題。課題番号または URL で指定します。ローカル Markdown トラッカーの場合、SOURCE は代わりに .scratch/<feature>/issues/ のバックログフォルダーです。

また、実行開始時に次の 3 項目も確定します。ユーザーがすでに指定していればその内容を使い、そうでなければ最初に一度だけ尋ねます（実行中には決して尋ねません。その時間には誰も起きていないためです）。

• MODEL POLICY — 自動（下記のマトリックスに基づく）またはチケットごと／ティアごとにユーザーが指定。デフォルト：自動。
• DELIVERABLE — 完了した作業の反映方法：（a）チケットごとのブランチスタック（デフォルト）、（b）依存関係の順に直列で cherry-pick して作成する単一の統合ブランチ。朝に一度にレビューする場合に最適な形式です。または（c）プッシュしたブランチと、コミットをチケットに対応付ける単一の PR。
• EXTERNAL WRITES — 許可する外部向けアクションを明確に指定します。完了したチケットをクローズするか、SOURCE にコメントするか、プッシュするか、PR を作成するか。デフォルト：なし（トラッカーは読み取り専用）。回答をすべてのエージェントプロンプトに組み込みます。

SOURCE をチケット一覧に変換する方法はトラッカーによって異なります。docs/agents/issue-tracker.md を読み、このリポジトリで仕様書の子課題／リンクされた課題をどう一覧表示するか、本文をどう読み取るか、ブロック関係のエッジをどう取得するかを確認してください。そのファイルがない場合は、/setup-matt-pocock-skills を実行します。

手順

1. コンテキストを収集します。 SOURCE の仕様書／親課題と、そこにリンクされた完了済み（クローズ済み）のチケットを読みます。確立されたパターンや規約を把握し、すでに完了している作業を記録します。これにより、エージェントが既存の作業に合わせ、クローズ済みのチケットをやり直さないようにします。

2. 作業を列挙します。 トラッカーから SOURCE にリンクされた未完了チケット（子課題／サブ課題、または SOURCE を参照している課題）を取得し、docs/agents/issue-tracker.md に従って ready-for-agent ラベルで絞り込みます。ローカルトラッカーの場合は、バックログフォルダー内の未完了チケットファイルを対象にします。クローズ済み、マージ済み、または依然として意思決定が必要と示されているチケットはスキップします。各チケットについて、受け入れ条件と、変更される可能性が高いファイルを記録します。品質を確認し、テスト可能な受け入れ条件がないチケットや、設計上の決定が未解決のチケットはエージェントの準備ができていません。エージェントに一晩推測させるのではなく、朝の報告用に取り分けます。

3. フェーズに分けて順序を決めます。 依存関係ごとにチケットをグループ化します。主な判断材料はトラッカー標準のブロック関係エッジです（ブロッカーがクローズするまで、そのチケットには着手できません）。加えて、ファイルの重複も考慮します。共有ファイルを変更するチケットや、別のチケットの成果物に依存するチケットを、同じ並列バッチで実行してはいけません。独立したチケットは並行して実行し、依存するチケットは後続のフェーズで実行します。

4. 作業ツリーを1つ事前準備します。 新しい作業ツリーでは、gitignore 対象のものはすべて存在しません。node_modules、生成ファイル、環境設定、シンボリックリンクの連鎖などが該当します。何かを起動する前に、作業ツリーを1つ作成して環境を整え、チケットで必要とされるチェックが実際にそこで通ること（最低限、型チェック）を確認します。その結果は、各レーンで再利用する冪等なセットアップスクリプトとして残します。これを省略することが、夜間の実行が失敗する最大の原因です。すべてのエージェントが同じ壊れたツールチェーンで足止めされるか、さらに悪いことに、それが引き起こした架空のエラーを「修正」してしまいます。

5. モデルの選び方を決めます — MODEL POLICY の入力に基づいて決定します（実行中に確認すると、起動後に介入しない実行が妨げられます）。

   • 自動（推奨） — オーケストレーターであるあなたが、以下のマトリックスを使って、各チケットの受け入れ条件と想定される影響範囲（ステップ2で記録）を判断し、チケットごとにモデルのティアを選びます。
   • ユーザー指定 — ユーザーがモデルを指定します。すべてのチケットに同じモデルを使うか、ティア別／チケット別に割り当てます。実装エージェントには指定どおりに適用し、マトリックスは使用しません。

   マトリックス（自動選択の場合）。 特定のモデル名ではなく、能力のティアに合わせます。これは使用するランタイム（Claude Code、OpenAI Codex など）を問わず機能します。各ティアには、ランタイムで利用できる最適なモデルを割り当ててください。最も難しいチケットには、利用可能な中で最も高性能なモデルを使い、作業が機械的になるにつれて、より高速で低コストのティアに切り替えます。2つのティアのどちらにするか迷った場合は、より高性能なほうを選びます。夜間実行の失敗は、トークンの差額よりも大きなコストがかかります。

   チケットの特性	モデルのティア	判断材料
   最難関：UI/UX 作業、広範囲に及ぶ変更やアーキテクチャの変更、曖昧な仕様、多数のファイルに及ぶ変更	利用可能な中で最も高性能なモデル	「再設計」「全体にわたるリファクタリング」、ビジュアル／レイアウトに関する受け入れ条件、共有フレームワークまたは5つ以上のファイルへの変更
   通常の実装チケット（デフォルト）	バランスの取れた中位モデル	1つの機能または修正、明確な受け入れ条件、数個のファイル、踏襲できる既存のパターン
   軽微な作業：フォーマット変更、名前変更、設定／ドキュメントの調整、機械的な単一ファイルの変更	高速／低コストのモデル	設計上の判断が不要で、差分がチケットの文章だけから予測できる

   検証エージェントは、差分を受け入れ条件と照らし合わせて確認します。見落としを検出するには最も優れた判断能力が役立つため、実装に使ったモデルにかかわらず、ユーザーの指定がない限り、利用可能な中で最も高性能なモデルを使います。

6. エージェント群を起動します。 夜間も動作し、中断後に再開できるよう、バックグラウンドの動的ワークフローとして起動します。まず、中断された以前の実行の残りがないか確認します（既存のエージェント群の作業ツリー／ブランチ、未検証のコミットがあるチケットなど）。残っている作業はやり直すのではなく、引き継いでください。リベースし、受け入れ条件に照らして監査し、レビューして修正します。各チケットについて、エージェントを1つ起動します。

   • 独自の Git 作業ツリー内で（ブランチを分離して衝突を防ぎます）。
   • ステップ5で選んだモデルを高の推論レベルで使います。
   • 以下のエージェントごとの指示に従います。

   フェーズは順番に実行し、各フェーズ内ではエージェントを並列実行します。ブランチ準備の各手順は冪等にします。エージェントが強制終了されると、作業ツリーには変更が残り、ブランチが作成途中の状態になることがあります。再実行時に無条件で checkout -b を実行すると失敗するため、残った変更はスタッシュし、既存のブランチは再利用し、安全な場合に限ってリセットします。

7. 各結果を検証します。 エージェントがコミットした後、別の検証エージェントが、そのチケットの受け入れ条件に照らして差分を評価します。反証を試み、主張よりも証拠を重視してください。実装者の報告を信用するのではなく、チェックを自ら再実行し、新しいテストが必要な動作を実際に保証していること（変更がなくても通るテストスイートは無意味です）を確認し、コミットの品質もチェックします。失敗した場合は、失敗の内容を記録してチケットを一度だけ担当エージェントに差し戻します。それでも失敗する場合は停止して報告します。夜間に無制限のループを回してはいけません。

8. DELIVERABLE に従って統合します。 ブランチスタックモード：検証済みのブランチをそのまま残します。統合ブランチモード：一度に実行するマージエージェントは 1 つだけとし、厳密に直列で処理します。各検証済みチケットを依存関係の順に統合ブランチへ cherry-pick します。競合した生成アーティファクト（宣言の集約ファイル、API レポート、生成されたクライアント）は、手動でマージせず、ソースから再生成します。その後、チケット横断の最終統合ゲートを実行します（リポジトリの型チェックと、変更したすべてのパッケージ／アプリの完全なチェック）。チケットごとの成功が、全体としての成功につながるとは限りません。PR モード：ゲート通過後、プッシュして PR を 1 つ作成し、その説明でコミット → チケット → 仕様の基準を対応付けます。どのモードでも、強制プッシュは禁止し、デフォルトブランチには何もマージしません。

9. 報告します。 ユーザーがコーヒーを飲みながら読める実行ログを、ワークツリーの隣にあるファイル（ローカルトラッカー上、またはバックログフォルダー内）に記録します。各チケットのステータス（done / failed / needs-decision）、ブランチまたは PR、コミット SHA、検証の証拠、人間が解決する必要のある事項を記載します。EXTERNAL WRITES によって許可されている場合に限り、SOURCE にコメントするか、完了したチケットをクローズします。残りは朝のレビュー用に残し、自動マージはしません。

エージェントごとの指示

各実装エージェントには、必ず次の形式で指示します。

• 担当するチケットは 1 件だけです：<ticket> — トラッカーから取得し、すべて読んでください。
• 仕様と、規約の参考となる完了済みチケットを読み取り専用で参照します：<pointers>。既存のパターンに合わせ、完了済みの作業をやり直さないでください。
• このチケットだけに /implement スキルを使用します。可能な場合は、事前に合意した境界で TDD を行い、型チェックと単一のテストファイルの実行を定期的に行い、最後にテストをすべて実行します。
• 次にコードレビューを実行し、作業用ワークツリーのブランチにコミットします。
• 妨げとなる問題や実際の判断が必要になった場合は、そこで停止して理由を書いてください。推測で進めないでください。

実行前の準備（無人実行の安全対策）

• エージェントが必要とするシェルコマンド（テストランナー、型チェック、git、パッケージマネージャー、チケットの読み取りやステータスの投稿に使うトラッカー CLI（例：gh））を、事前に許可リストに登録します。無人実行のエージェントはファイル編集を自動承認しますが、許可リストにないコマンドに遭遇すると、確認する人がいないため処理が停止します。
• 外部への書き込みを明示的に許可します（EXTERNAL WRITES 入力）。権限判定では、ユーザーの依頼内容から意図を判断します。ユーザーが依頼していない gh issue close や git push を無人エージェントが実行しようとすると、実行中に拒否され、承認できる人も起きていません。起動時に許可を取得し、その内容をプロンプトに一字一句そのまま記載します。
• 動的ワークフローを有効にする必要があります（Max／Team／Enterprise ではデフォルトで有効です。Pro ユーザーは /config の Dynamic workflows の行で有効にします）。
• 非対話型の実行で作成されたワークツリーは自動でクリーンアップされません。マージ後に git worktree remove を実行することを想定してください。
• エージェントを並行実行すると、トークン使用量が増え、レート制限の上限に達しやすくなります（ワークフローの上限：同時実行エージェント 16、1 回の実行につき 1000）。計画に合うよう、バッチの規模を調整してください。