issue-flow

Issue Flow — AI ネイティブな Issue 駆動開発

GitHub Issue からマージ済み PR まで、開発サイクル全体を進行します。以下のフェーズに厳密に従ってください。主要な判断にはすべて人間の確認が必要です。

開始時にアナウンス: 「issue-flow スキルを使って、この GitHub Issue を実装します。」

初回リクエスト: $ARGUMENTS

---

Phase 0: 事前確認

目標: 環境を検証し、対象の Issue を特定します。

アクション:

1. 環境の確認: gh auth status を実行して、GitHub CLI が認証済みであることを確認します。失敗した場合は、ユーザーに gh auth login の実行を案内して終了します。

2. 引数の解析:

   • #123 または 123 → Issue 番号を抽出し、gh repo view --json nameWithOwner からリポジトリを特定します
   • https://github.com/org/repo/issues/123 → オーナー、リポジトリ、番号を抽出します
   • 空の場合 → gh issue list --state open --limit 20 を実行し、AskUserQuestion を使ってユーザーに Issue を選んでもらいます

3. Issue の詳細を取得:

   gh issue view <N> --json number,title,body,labels,comments,assignees,state
   

   保存する値: ISSUE_NUMBER、ISSUE_TITLE、ISSUE_BODY、ISSUE_LABELS。

4. 既存の作業を確認:

   • git branch -a --list '*issue/<N>*' でブランチ issue/<N>-* を検索します
   • 見つかった場合は、AskUserQuestion で既存のブランチを再開する／新しく開始する／キャンセルする、のいずれかを尋ねます

5. プロジェクトの機能を検出（後でチーム構成に使用）:

   • テストフレームワークがあるか（jest.config*、vitest.config*、pytest.ini、*test* ディレクトリを確認）
   • CI があるか（.github/workflows/、.gitlab-ci.yml などを確認）
   • リンターがあるか（.eslintrc*、biome.json、.prettierrc* を確認）
   • 主な言語（ファイル拡張子から判定）

---

Phase 1: Worktree のセットアップ

目標: 隔離されたワークスペースを作成します。

アクション:

1. EnterWorktree ツールを名前 issue-<N> で使用し、隔離された worktree を作成します。
2. ブランチ issue/<N>-<slugified-title> を作成して切り替えます:
   • スラッグ化: 小文字にし、スペースや特殊文字を - に置き換え、50 文字で切り詰めます
   • 例: Issue #42「Add OAuth2 Login Support」→ issue/42-add-oauth2-login-support
   • 実行: git checkout -b issue/<N>-<slug>

---

Phase 2: 技術計画

目標: コードベースを詳細に調査し、技術計画を作成して、ユーザーの承認を得ます。

Step 2a: コードベースの調査

Task ツール（subagent_type: code-explorer）を使って、2〜3 個の code-explorer エージェントを並行して起動します。各エージェントの調査内容は Issue に合わせて調整します。

• Agent 1: Issue の要件に直接関連する既存の実装やパターンを調査します。重要なファイルを 5〜10 個返します。
• Agent 2: 影響を受けるモジュールのアーキテクチャ、依存関係、拡張ポイントを分析します。重要なファイルを 5〜10 個返します。
• Agent 3（複雑な Issue の場合は任意）: テストのパターン、CI 設定、関連するツールチェーンを調査します。重要なファイルを 5〜10 個返します。

エージェントからの回答を受け取ったら、エージェントが特定した重要なファイルをすべて読み、深く理解します。

Step 2b: 技術計画の作成

調査結果に基づいて、以下を含む技術計画を作成します。

1. 概要: アプローチを 2〜3 文で説明
2. 変更・作成するファイル: 変更内容の簡単な説明を添えた一覧
3. 実装手順: 順序付けされた具体的な手順（各手順は 1 つの論理的な作業単位）
4. テスト戦略: テスト対象とテスト方法
5. リスク評価: 想定される問題とその緩和策

rules/plan-format.md に従って計画を作成します。

Step 2c: 計画を Issue に投稿

gh issue comment を使って、計画を Issue のコメントとして投稿します。

gh issue comment <N> --body "$(cat <<'EOF'
<plan content formatted per rules/plan-format.md>
EOF
)"

計画を識別して冪等に更新できるよう、先頭に HTML コメントマーカー `` を使用します。

Step 2d: ユーザーの確認

以下の選択肢を使って AskUserQuestion を実行します。

• Approve — 実装に進みます
• Modify — ユーザーからフィードバックを受け取り、Step 2b に戻ります
• Cancel — ワークフローを中止します

明示的な承認を得るまで、先に進まないでください。

---

Phase 3: チームでの実行

目標: 直接、またはエージェントチームを使って計画を実装します。

判断：直接実装かチーム実行か

次の条件をすべて満たす場合は、直接実装（チームなし）にします。

• 計画の対象が1～2ファイル
• 複雑なモジュール横断の変更がない
• 個別のテスト／レビュー／ドキュメント作業が不要

次の条件のいずれかに該当する場合は、チーム実行にします。

• 計画の対象が複数のモジュールにまたがる3ファイル以上
• テストの作成または更新が必要
• セキュリティに関わる変更
• ドキュメントの更新が必要
• フロントエンドとバックエンドの両方に変更がある

パス A：直接実装

1. 計画に沿って、手順を一つずつ実装します
2. 利用可能な場合は、既存のテストを実行します
3. フェーズ 4 に進みます

パス B：チーム実行

1. チームを作成：TeamCreate を使用し、名前を issue-<N> にします。

2. チーム構成を決定：Issue の特性に基づいて、rules/team-roles.md で定義されている候補から役割を選択します。次の点を考慮します。

   • Issue のラベル（例：frontend、security、docs）
   • 計画内のファイル形式（.tsx → フロントエンド、.sql → バックエンドなど）
   • テストが存在し、更新が必要かどうか
   • 変更のリスクレベル

3. チームメイトを起動：各役割に対し、team_name パラメーターを指定して Task ツールを使用します。各チームメイトに次の内容を伝えます。

   • 技術計画
   • 各自の具体的なタスク
   • フェーズ 2 で確認したコードベースのパターンに関するコンテキスト

4. タスクを作成：計画の各実装手順に対して TaskCreate を使用します。手順に依存関係がある場合は、addBlockedBy を設定します。

5. 割り当てと調整：TaskUpdate を使ってタスクをチームメイトに割り当てます。進捗を監視し、ブロッカーを解消して、チームメイト間の調整を行います。

6. 反復回数の上限：各タスクの修正は最大2回です。2回の修正後もタスクが失敗する場合は、次の対応を行います。

   • 問題を記録する
   • AskUserQuestion で、手動で修正／スキップ／中止を尋ねる

7. チームを終了：すべてのタスクが完了したら、各チームメイトに shutdown_request を送信し、その後 TeamDelete を実行します。

---

フェーズ 4：PR と CI

目標：コミット、プッシュ、PR の作成、CI への対応を行います。

ステップ 4a：コミットとプッシュ

1. すべての変更をステージングします：git status と git diff で確認します
2. Issue を参照する、内容が分かりやすいメッセージでコミットします。

   feat: <summary from plan> (#<N>)
   

3. ブランチをプッシュします。

   git push -u origin issue/<N>-<slug>
   

ステップ 4b：PR を作成

rules/pr-template.md のテンプレートを使用し、gh pr create で PR を作成します。

gh pr create --title "<title>" --body "$(cat <<'EOF'
<PR body per rules/pr-template.md, includes Closes #N>
EOF
)"

ステップ 4c：実装の概要を Issue に投稿

実装した内容をまとめたコメントを Issue に追加します。

gh issue comment <N> --body "$(cat <<'EOF'

## Implementation Complete

- PR: #<PR_NUMBER>
- <brief summary of changes>
EOF
)"

ステップ 4d：CI を確認

1. 少し待ってから、CI のステータスを確認します。

   gh pr checks <PR_NUMBER> --watch --fail-fast
   

2. CI が失敗した場合：次の選択肢を提示して AskUserQuestion を実行します。

   • 自動修正 — CI の失敗を診断して修正を試みる（最大2回）
   • 手動 — ユーザーが手動で修正する
   • 中止 — PR をクローズする

3. CI が成功した場合（または CI が設定されていない場合）：次の選択肢を提示して AskUserQuestion を実行します。

   • マージ — PR を今すぐマージする
   • オープンのままにする — 人によるレビューのため PR をオープンのままにする
   • レビューを依頼 — gh pr edit --add-reviewer でレビュアーを割り当てる

---

フェーズ 5：クリーンアップ

目標：マージ後にリソースをクリーンアップします。

実行内容（PR がマージされた場合のみ）：

1. Issue のステータスを確認：Closes #N によって Issue が自動的にクローズされたかを確認します。クローズされていない場合：

   gh issue close <N> --comment "Closed via PR #<PR_NUMBER>"
   

2. 報告：完了の概要を出力します。

   ## Issue Flow Complete
   
   - Issue: #<N> <title>
   - Branch: issue/<N>-<slug>
   - PR: #<PR_NUMBER> (merged)
   - Files changed: <count>
   - Implementation: <1-2 sentence summary>
   

---

エラーからの復旧

ワークフローが途中で中断された場合、ユーザーは /issue-flow #<N> を再実行して再開できます。詳しい復旧シナリオについては、references/recovery-guide.md を参照してください。

主な原則

• Human-in-the-loop：計画の承認、マージ、CI 失敗への対応など、重要な判断にはすべてユーザーの明示的な確認が必要です
• べき等なコメント：Issue のコメントには HTML マーカー（, ）を使用するため、再実行時に重複せず、既存のコメントが更新されます
• 分離：すべての作業は worktree 内で行います。マージされるまでメインブランチには手を加えません
• 変更規模に応じた対応：単純な変更ではチーム編成の負担を省き、複雑な変更ではチーム全体で調整します