work-on-issues

Issue への対応

GitHub／GitLab の Issue を取得してトリアージし、順番に実装（メイン Issue を一度に 1 件）して、find-mismatch によるレビューを実行し、クローズします。

1. トラッカーの設定

git remote -v でホストを判別します。$TRACKER に gh または glab を設定します。 用語：

• GitHub：pr ／ comment
• GitLab：mr ／ note

---

2. フェーズ 1：取得とトリアージ

1. オープンな Issue の一覧表示：gh issue list --state open --json number,title,labels または glab issue list -O json を使用します。
2. フィルタリング：メイン Issue（タイトルが PRD: または feat: で始まるもの）のみを残します。その他は自動実行／バッチ実行ではスキップします（明示的に選択された場合は対応可能です）。
3. 選択：ユーザーが Issue 番号またはオンワードモードを選択します。
4. 事前確認：
   • オープン状態であることを確認します（クローズ済みの場合はスキップします）。
   • ラベルが PRD、またはタイトルが PRD: で始まる場合は PRD／Epic と判定します。実装をスキップし、自動クローズ確認用に $PRD_TRACKER に追加します。
5. 詳細の読み込み：Issue の詳細とコメントをすべて取得します（gh issue view --comments ／ glab issue view --comments）。
6. 割り当てとラベル付け：対応中に設定し、needs-triage を削除します。

---

3. 依存関係とリンク

Issue 本文の ## Blocked by を解析し（#42 または Issue の完全な URL に一致）、DEPS[issue] = [blockers] を構築します。 可能であれば、トラッカーのネイティブリンクを作成します（例：GitLab API の /links で is_blocked_by を使用、または GitHub のサブ Issue API で blocked_by=true を使用）。できない場合は、テキストで参照します。

---

4. フェーズ 2：実装（メイン Issue を一度に 1 件）

1. Worktree の作成：

   git worktree add .claude/worktrees/issue-<number> -b work-on-issue-<number>
   

2. .env ファイルのコピー：.env および .env.* ファイルを Worktree ディレクトリにコピーします。
3. サブエージェントの実行（.claude/worktrees/issue-<number> 内で subagent_type: "full-stack-engineer"）： プロンプト仕様：

   Implement issue #<number>: <title>.
   Acceptance Criteria: <AC>
   Branch/Worktree: work-on-issue-<number> in .claude/worktrees/issue-<number>
   API/best-practices: Search via `context7` or web.
   Compile/Lint errors: If 3+ consecutive failures, check Reference Directories (<RefDirs>) to align configurations.
   Parallel subtasks: Decompose & dispatch sub-agents if tasks are independent (no shared files/dirs).
   Post-implementation: Run `find-mismatch` skill on modified files only. Auto-apply confirmed fixes without prompting. Re-run tests.
   Output: Summary, find-mismatch fixes, tests run, and commit hash.
   Commit format: `fix: resolve #<number> — <short description>`
   

4. 検証：出力と diff を確認し、テストを実行します。
5. コミット：Worktree 内で変更がコミットされていることを確認します（fix: resolve #<number> — <desc>）。

---

5. フェーズ 3：提出とクローズ

1. PR／MR の作成：「Closes #」を使用して Issue にリンクします。
2. 自動マージ：直ちにマージします（squash してブランチを削除）。
3. コメント：実装の概要を投稿します。
4. クローズ：トリアージ／進捗ラベルを削除し、ai-agent-closed を追加して、Issue をクローズします。
5. .env ファイルの反映：Worktree を削除する前に、変更された env ファイルをメインの作業ディレクトリにコピーします：

   WT=.claude/worktrees/issue-<number>
   for wtf in "$WT"/.env "$WT"/.env.*; do
     [ -f "$wtf" ] || continue
     base=$(basename "$wtf")
     if [ ! -f "$base" ] || ! cmp -s "$base" "$wtf"; then
       cp "$wtf" "$base" && echo "Propagated $base back"
     fi
   done
   

6. クリーンアップ：

   git worktree remove .claude/worktrees/issue-<number>
   git branch -d work-on-issue-<number>
   

---

6. PRD の自動クローズ

サブ Issue をクローズした後、PRD_TRACKER 内のすべての PRD を確認します。PRD の説明とリンクを読み込みます。参照されているすべてのサブ Issue（#42 など）がクローズ済みの場合、PRD をクローズし、PRD_TRACKER から削除します。

---

7. サブタスクの並列化

次の条件を満たす場合、メイン Issue をサブタスクに分解します：

• 重複しないファイル／フォルダーを変更する。
• 独立した成果物である（順序への依存がない）。 ファイルを共有する場合、厳密な処理順序への依存がある場合、または先に設定が必要な場合は、順次実行します。

サブタスクのプロンプト仕様：

Implement subtask for issue #<number>: <title>.
Subtask: <details>
Working Directory: .claude/worktrees/issue-<number>
Scope: Modify <MAY_MODIFY>, DO NOT modify <MUST_NOT_MODIFY>.
Compile/Lint errors: If 3+ consecutive failures, check Reference Directories (<RefDirs>).
Post-implementation: Run `find-mismatch` on modified files, auto-fix.
Verification: Run relevant tests. Return summary, modified files, test results.

---

8. 実行モード

バッチモードとオンワードモード

1. オープンな Issue をすべて取得し、メイン Issue（PRD:、feat:）に絞り込みます。
2. Issue 本文から DEPS マップを解析し、正式なリンクを設定します。
3. 進捗テーブルを表示します：| Issue | Title | Type | Blocked By | Agent | Status | PR/MR |
4. ループ：
   • 未解決のブロッカーがない次の Issue を選択します。クローズ済みまたは PRD の Issue はスキップします。
   • Worktree でサブエージェントを実行します。
   • 検証 → PR／MR のマージ → クローズ → env の反映 → クリーンアップ → PRD の確認を実行します。
   • 依存関係を再評価します。繰り返します。
5. 完了後、オープンな Issue をすべて再取得して（外側のループ）、新しいメイン Issue を確認します。オープンなメイン Issue がなくなるか、ユーザーが中断するまで終了しません。

単一 Issue モード

選択された Issue のみを実行します。依存関係グラフの処理はスキップします。

---

9. ラベルとヘルパー

ラベル	意味	色
PRD	親の追跡用 Issue	#0075CA
in-progress	対応中	#E4E669
ready-for-agent	エージェントの対応準備完了	#0E8A16
ai-agent-closed	AI によるクローズ	#5319E7

ラベルを適用するには、まず直接更新を試します。見つからない場合はラベルを作成してから再試行します（例：in-progress の色は #E4E669）。

---

10. エッジケース

• CLI がない場合：API を直接使用するか、ユーザーに gh／glab のインストールを依頼します。
• 競合／循環：循環依存を報告し、影響を受ける課題をスキップします。
• 外部のブロッカー：未解決のブロッカーとして、オープン状態の外部課題を扱います。
• API リンクの失敗：テキストによる参照に切り替えます。
• メインの課題がない場合：ユーザーにその旨を伝え、メイン以外の課題を処理するか尋ねます。
• 環境ファイルが Git で無視される場合：実行間で内容を保持するには、worktree を削除する前に環境ファイルを元に戻す必要があります。シークレットはコミットしないでください。