implement-issues

Issue の実装

エージェントを使って未対応の Issue を実装し、Issue ごとに 1 つのプルリクエストを作成します。各 Issue は、人が対応する場合と同じ流れで進みます。

1. Issue をもとに Superpowers が仕様と計画を作成する
2. Superpowers が実装する
3. プルリクエストを作成し、コードレビューを行う

ただし、途中で質問に答える人はいません。エージェントがユーザーに代わって行った判断はすべて、そのプルリクエストに反映され、ユーザーが確認します。

各 Issue では 2 つのエージェントが作業します。プランナーが仕様と計画を作成します。ビルドリードが計画を実行し、レビューに回答します。計画の承認が有効な場合、ビルドリードが作業を始める前に、ユーザーはドラフトプルリクエスト上で仕様と計画を確認します。その後の実行で、承認済みの内容が引き継がれます。

実装したプルリクエストはドラフトとして作成されます。2 つ目のエージェントがそのプルリクエストに対して review-prs を実行し、ビルドリードが answer-pr-reviews でレビューに回答します。レビューへの回答が済み、チェックが通ると、プルリクエストはレビュー可能な状態になります。

あなたはディスパッチャーです。エージェントはそれぞれのワークツリーで作業します。あなたは各ブランチをプッシュし、プルリクエストを作成して、各エージェントの成果を判定します。自分でチェックの成功を確認するまで、レビュー可能な状態にはしません。

仕様、計画、実装は Superpowers が担当します。このスキルは、実行モード、使用するモデル、修正ラウンド数など、Superpowers が人に尋ねる内容について、ユーザーの設定に基づいて回答します。Superpowers 内部の動作を変更することはありません。

このスキルでは、「エージェントをディスパッチする」「モデルを選ぶ」などのアクション名を使います。ご利用のプラットフォームに相当する機能を使用してください。

要件

• Superpowers（brainstorming、writing-plans、subagent-driven-development、executing-plans、finishing-a-development-branch、verification-before-completion）に加えて、fetch-issues、superpowers-issue-bridge、review-prs、answer-pr-reviews の各スキルが必要です。いずれかが不足している場合は、その名前を示して停止してください。
• GitHub リポジトリと gh が必要です。また、gh auth status が成功する必要があります。Issue がどこにあるかにかかわらず、プルリクエストとレビューは GitHub 上で行います。

設定

実行を左右する設定は 3 つあります。リポジトリ内の docs/agents/delivery.md に保存済みの設定を記載します。形式は assets/delivery.md にあります。

• 作業量 — low、medium、high のいずれかです。次のうち最初に見つかった値を使用します。実行時の引数（/implement-issues low、「作業量は medium」）、ファイルの Effort 行、またはステージ 2 での質問です。作業量によって次のように決まります。

  	low	medium	high
  writing-plans の実行に関する質問への回答となるビルドモード	executing-plans を使う 1 エージェント	タスクごとに subagent-driven-development を使う	タスクごとに subagent-driven-development を使う
  タスクレビューあたりの修正ラウンド数	—	2	5
  review-prs によるコードレビュー	オフ	オフ	オン
  レビュー修正後にあなたが実行する全チェック	CI を証拠とし、プルリクエストに CI がない場合のみ実行	はい	はい
  finishing-a-development-branch が実行する独自のテストスイート	ステージ 5 以降 HEAD が変わっていなければスキップ	ステージ 5 以降 HEAD が変わっていなければスキップ	実行
  CI の修正試行回数	1	2	3
  計画の改訂ラウンド数	1	2	3

  どの作業量でも、ビルドの最後に Superpowers がブランチ全体をレビューします。最初のプッシュ前にあなたが全チェックを実行し、マージは行いません。

• 計画の承認 — オンまたはオフです。ファイルに指定がない場合はオフです。

• モデル — 各担当に 1 つずつ指定します。各値には、このプラットフォーム用のファイル内の Tiers テーブルで参照されるティア（cheap、standard、strong）、session、正確なモデル名、または実装担当者の場合は by-task を指定できます。by-task は、subagent-driven-development 自身のルールに選択を委ねます。ファイルに指定がない担当には、次のフォールバックが適用されます。

  担当	ディスパッチ元	未設定時
  planner、build-lead、pr-reviewer	あなた	セッションモデル
  implementer	Superpowers	ステージ 2 で質問
  spec-check、task-reviewer、re-reviewer、escalation、final-reviewer	Superpowers	そのスキル独自のルール
  pr-code-reviewer	review-prs	そのスキル独自のルール

ステージ 1 — キューを作成する

1. fetch-issues でオープン中のイシューを取得します。ユーザーがイシュー（「#12 と #15」）を指定した場合は、そのイシューだけを残します。

2. docs/agents/issue-tracker.md の Linking セクションを読みます。各プルリクエストがイシューをクローズするために何を記述するかは、ここで決まります。 docs/agents/delivery.md が存在する場合は、それも読みます。

3. 各イシューに関連するオープン中のプルリクエストとブランチ（feat/42-*、 fix/42-*）を探します。本文に `` があるオープン中のプルリクエストは、このスキルの計画プルリクエストです。

   • plan-approved ラベルが付いている → ビルド；
   • 未回答のレビューコメントがある（未解決のスレッドで、最後のコメントが `` で終わっていない） → 計画を修正；
   • それ以外 → ユーザーの返答を待機。

   そのイシューに関連するその他のオープン中のプルリクエストまたはブランチは → スキップし、その理由を記録します。プルリクエストもブランチもない場合は → 計画。

4. イシューの本文で別のキュー内のイシューに言及している場合は、そのイシューに依存します。そのイシューのプルリクエストが ready とマークされた後に着手し、ベースブランチではなく、そのイシューのブランチから分岐して、その旨をプルリクエストに記載します。そのイシューが ready なプルリクエストなしで終了した場合は、こちらのイシューをスキップし、その理由を記録します。

5. ベースブランチ（リモートのデフォルトブランチ）を見つけて、フェッチします。

キュー（参照、タイトル、ブランチ、アクション（計画、計画を修正、ビルド）、依存関係）を表示し、その後に待機中とスキップ対象の一覧を表示します。

ステージ 2 — 設定を確定してから、実行方法を尋ねる

何かをディスパッチする前に尋ねます。

1. 設定。 努力量とその設定元、計画の承認設定、各担当のこのプラットフォームで解決されたモデルを表示します。解決された各モデルが、現在プラットフォームのディスパッチで受け付けられるものか（モデルの選択肢または起動許可リストを使って）確認します。受け付けられない値が1つでもあれば、実行を中止します。担当、値、設定元を示します。別のプラットフォームで使われる名前そのものや、このプラットフォーム用の列がないティアも対象です。

   ファイルで確定できない項目を尋ねます。実行時に引数が指定されていなかった場合は努力量、ファイルに設定行がない場合は計画の承認設定、ファイルで設定されていない場合は実装担当のモデルを尋ねます。モデルについては、他の場所で見かけた名前ではなく、ディスパッチで受け付けられるモデルを提示します。ディスパッチごとにモデルを設定できないプラットフォームの場合は、その旨を伝え、すべての担当にデフォルトを使用します。続けて、この実行でこれらの設定を使うか、いずれかを今回の実行に限って上書きするかを尋ねます。

   何かを尋ねた場合は、docs/agents/delivery.md への保存を提案します。ファイルの差分を表示し、ユーザーが同意した場合にのみ書き込みます。実行時の上書き設定は、ユーザーが保存を指示した場合にのみ保存します。

2. 逐次実行と並列実行のどちらにしますか？ 逐次実行では一度に1つのイシューを処理します。並列実行では最大 N 件を同時に処理するため、N を尋ねます。目安として 3 を提案します。プラットフォームで複数のディスパッチ済みエージェントを同時に実行できる場合にのみ、並列実行を提案します。どちらの場合も、イシューはディスパッチされてから、計画の承認待ち、ready とマーク、または終了のいずれかになるまで、処理枠を占有します。

表示したキューに対する回答は、実行全体へのユーザーの許可となります。各イシューについて、ブランチをプッシュすること、ドラフト計画プルリクエストを開き、不足していれば plan-approved ラベルを作成すること、コメントへの返信を添えて計画の修正をプッシュすること、ドラフトプルリクエストを開くか変換すること、そのプルリクエストにレビューを投稿すること、そのレビューへの修正をコメントへの返信とともにプッシュすること、失敗した CI チェックへの修正をプッシュすること、そして ready とマークすることが許可されます。

ステージ 3 — 計画

計画する各イシューについて、ブランチとワークツリーを作成してから、プランナーを割り当てます。

• ブランチ： バグのラベルが付いたイシューには fix/<ref>-<slug>、それ以外には feat/<ref>-<slug> を使います。<ref> は # を除いたイシューの参照番号（42、 PROJ-123）です。<slug> はタイトルを小文字にし、a-z0-9 以外の文字が連続する箇所を - に置き換え、40 文字で切り詰めます。

• ワークツリー： .worktrees/<ref>-<slug> をベースブランチ、または依存先のブランチから git で作成します。.worktrees/ がコミットに含まれないようにします。 git check-ignore -q .worktrees が失敗する場合は、.git/info/exclude に追加します。

  git worktree add -b "<branch>" ".worktrees/<ref>-<slug>" "origin/<base>"
  

• プランナー： assets/planner-brief.md に記入します。計画プルリクエストは作成せず、 プランナーの担当枠でバックグラウンドエージェントとして割り当てます。

改訂する各計画について、イシューのワークツリーがクリーンであれば再利用します。 そうでなければ、プッシュ済みのブランチから git worktree add ".worktrees/<ref>-<slug>" "<branch>" で作成します。すでに行った改訂回数を数えます。会話コメントが計画プルリクエストに保持する ``。作業量の上限に達したら、待機状態のままにし、その理由を記録します。それ以外の場合は、 assets/planner-brief.md を使ってプランナーを割り当て、計画プルリクエストを指定します。

プランナーから報告があったら、次のように対応します。

1. BLOCKED または NEEDS_DESIGN_SESSION の報告、あるいはブランチにコミットがない場合は、プルリクエストを作成しません。ワークツリーを残し、理由を記録します。
2. 改訂の場合： プッシュと返信を確認してから、計画プルリクエストに会話コメントを投稿します — Plan revision <n> of <cap>. — その後、待機状態のままにします。
3. 計画承認が有効な場合： ブランチをプッシュし、下書きの計画プルリクエストを作成します — gh pr create --draft、タイトルは plan: <issue title> (<reference>)、本文は assets/plan-pr-body.md の内容、ベースはベースブランチまたは依存先のブランチにします。 gh label list に plan-approved が表示されない場合は、先にそのラベルを作成します。 イシューは待機状態のままにします。
4. 計画承認が無効な場合： プランナーの仕様と計画を使って、そのままステージ 4 に進みます。

ステージ 4 — ビルド

ビルドする各イシューについて、ワークツリーがクリーンであれば再利用するか、プッシュ済みのブランチから作成します。assets/build-brief.md に記入し、ビルドリードの担当枠でバックグラウンドエージェントとして割り当てます。順次実行の場合は、一度に 1 件ずつ対応します。並列実行の場合は、一度に最大 N 件まで対応し、1 件が終わるたびに次の 1 件を開始します。各ビルドリードの識別情報を維持します。ステージ 5 と 8 では、そのビルドリードにメッセージを送ることがあります。

ステージ 5 — ビルドした各イシューを検証

ビルドリードから報告があったら、次のように対応します。

1. BLOCKED または NEEDS_DESIGN_SESSION の報告、あるいはブランチに新しいコミットがない場合は、プルリクエストを作成しません。ワークツリーを残し、理由を記録します。
2. ワークツリー内で自分で確認します。git log origin/<base>..HEAD と差分を読み、プロジェクトのテスト、lint、型チェックのコマンドを実行します（AGENTS.md またはプロジェクトのマニフェストを参照）。各コマンドの出力をワークツリーの git ディレクトリ内のログファイルに書き込み、終了コード、サマリー、失敗時の末尾部分を読み返します。ログ全体を読む必要はありません。エージェントの「テストに合格しました」という報告は主張であり、証拠ではありません。
3. チェックに失敗した場合は、同じビルドリードに失敗内容を 1 通のメッセージで送り、再度検証します。それでも失敗する場合は、プルリクエストを作成せず、失敗を記録します。

ステージ 6 — ドラフトのプルリクエストを開く

検証済みの各ブランチを finishing-a-development-branch を通じて取り込みます。メニューの回答はすでに済んでいます。プッシュしてドラフトとしてプルリクエストを作成するので、待つ必要はありません。高エフォート未満では、HEAD が動いていない場合、ステージ 5 のチェック実行がステップ 1 です。

• タイトル： 課題の参照番号で終わる Conventional Commit 形式にします。例：feat: confirm waitlist emails (#42)。
• 本文： assets/pr-body.md に記入します。リンク行には、トラッカーの Linking セクションの内容を使います。まず、レポートで未完了とされた各項目を自分で判断します。このリポジトリへの変更では対応できない項目はフォローアップとして扱い、フォローアップによって作業が部分的なものになることはありません。ほかに未完了の項目がなければ、完了を示す参照（GitHub では Closes #42）を記入します。未完了の項目があれば、部分対応を示す参照（Relates to #42）に続けて、残っている内容を記入します。トラッカーの Finishing PR が None の場合、完了を示す参照はありません。部分対応を示す参照を記入し、作業で課題が完全に解決するかどうかを伝えます。これは、無人実行における superpowers-issue-bridge のルールです。
• ベース： ベースブランチ、または依存する課題の場合は依存先のブランチです。
• 承認済みの計画プルリクエスト がこの課題のプルリクエストです。そのブランチにプッシュしてから、上記のタイトルと本文を指定して gh pr edit <number> --title <title> --body-file <file> を実行します。ドラフトのままにします。

プルリクエストが開いた後も、各ワークツリーを残してください。レビューへの修正はそこで行います。

ステージ 7 — プルリクエストをレビューする

pr-reviewer の席で新しいエージェントを起動して、<owner/repo> に対して review-prs #<number> を実行させます。プランナーやビルドリードは決して使わないでください。次の点を伝えます。

• 今回の実行についてユーザーから得た許可には、レビューの投稿も含まれます。
• 高エフォート未満では、ビルド全体のブランチレビューでコードを確認済みのため、コードパスはオフにします。

エージェントはプルリクエストにコメントとして指摘事項を投稿し、レビューの URL を報告します。レビューによってローカルの状態は変わらないため、ほかの課題のビルドと並行して実行できます。

レビューが投稿されなかった場合は、プルリクエストをドラフトのままにして、その理由を記録します。指摘事項のないレビューの場合は、ステージ 8 のステップ 3 に進みます。

ステージ 8 — レビューに回答し、準備完了にする

1. ビルドリードにメッセージを送ります。メッセージを送れなくなっている場合は、ビルドリードの席で新しいエージェントを起動し、同じワークツリーに配置します。そこで <owner/repo> に対して answer-pr-reviews #<number> を実行させ、今回の実行についてユーザーから得た許可には、修正のプッシュと各コメントへの返信も含まれることを伝えます。
2. 中エフォートと高エフォートでは、verification-before-completion を使ってプッシュ済みの HEAD を検証し、ステージ 5 のチェックを自分で実行します。失敗した場合は、その失敗をビルドリードに一度だけ送り、その後もう一度チェックします。低エフォートでは、レビュー修正の根拠は CI です。プルリクエストに CI がない場合に限り、ステージ 5 のチェックを実行します。
3. プッシュ済みの HEAD に対するプルリクエストの CI チェックを待ちます。gh pr checks <number> --watch を実行します。チェックがないと報告された場合は、待つものはありません。ローカルでの合格は CI での合格を意味しません。別のランタイムや不足している変数、プロジェクトのローカルコマンドが省略する手順でのみ失敗するチェックもあります。失敗した場合は、失敗したチェックの名前とログ（gh run view <run-id> --log-failed）をビルドリードに送り、このブランチを修正してコミットし、プッシュするよう依頼します。強制プッシュは決して行いません。その後、ステップ 2 を再度実行し、エフォートごとの CI 修正試行回数の上限まで、再び CI を待ちます。
4. チェックが合格し、すべてのレビューコメントに返信したら、gh pr ready <number> でプルリクエストを準備完了にします。チェックがまだ失敗している場合や、妥当な指摘が未修正のまま残っている場合は、ドラフトのままにして、その理由を記録します。

ステージ 9 — レポート

1 つの表に、課題、ブランチ、プルリクエストの URL またはプルリクエストがない理由、状態（計画の承認待ち、準備完了、またはドラフトとその理由）、ローカルおよび CI でのチェック結果、重要度別のレビュー指摘と修正件数、エージェントが下した判断の件数を記載します。その上に、実行にかかった労力と計画の承認状況を記載します。その下には、各担当で実行したモデルと、プラットフォームで報告される場合はエージェントごとのトークン使用量または所要時間を記載します。次に、ステージ 1 で対応待ちまたはスキップしたすべての課題と、その理由を列挙します。

部分参照を含むプルリクエストは、マージされても課題をオープンのままにします。未完了の作業が残ったものについては、その作業を明示してユーザーに一度だけ確認します。その作業で課題を完全に解決しますか。はいの場合は、そのリンク行を完了参照（gh pr edit <number> --body-file <file>）に差し替え、残った作業はフォローアップとして記載します。

完了参照のないトラッカー（ローカルの Markdown や、連携機能でクローズされない Jira または Trello のボードなど）では、差し替えるリンク行はありません。課題を完全に解決する各プルリクエストについて、上記の質問に「はい」と回答したものも含め、マージ後に一度実行するトラッカーの手動クローズ手順をユーザーに伝えます。

してはいけないこと

• プルリクエストをマージ、自動マージの有効化、または承認しないでください。準備完了にすると作業がユーザーに引き渡され、ユーザーがその作業を受け入れます。
• ベースブランチをプッシュしたり、強制プッシュしたりしないでください。
• エージェントの報告を証拠として扱わないでください。どの作業量でも、最初のプッシュ前に自分でチェックを実行してください。
• すでにプルリクエストがある課題について、承認済みの計画プルリクエストを変換する場合を除き、新たなプルリクエストを作成しないでください。
• plan-approved ラベルがない計画プルリクエストから作業を開始しないでください。また、そのラベルを自分で追加しないでください。承認するのはユーザーです。
• プラットフォームのディスパッチが受け付けないモデルを提示またはディスパッチしたり、黙って別のモデルに切り替えたりしないでください。
• このスキルやそのアセットにモデル名を書かないでください。モデル名は、ユーザーの選択として docs/agents/delivery.md にのみ記載します。
• 差分を提示してユーザーから「はい」を得ることなく、設定を docs/agents/delivery.md に保存しないでください。
• ユーザーがステージ 9 でプルリクエストによって課題が完全に解決すると明言しない限り、このリポジトリで対応可能な作業が残っている間は完了参照を書かないでください。フォローアップだけのために部分参照を書かないでください。
• Decisions セクションがない、または曖昧なプルリクエストを作成しないでください。エージェントがユーザーに代わって行った選択をユーザーが確認できる唯一の場所です。
• プランナーまたはビルドリードに、自身のプルリクエストをレビューさせないでください。
• レビューコメントへの未回答がある場合や、プッシュした HEAD でローカルまたは CI のチェックが失敗している場合は、プルリクエストを準備完了にしないでください。