start-implement

name	start-implement
description	計画書からタスクを選び、実装・レビュー・計画更新まで一貫して実行する。 トリガー: "実装開始", "タスク実行", "start implement"
user-invocable	true
argument-hint	<feature> [--task TASK-ID[,TASK-ID,...]] [-n N]
allowed-tools	Bash, Read, Write, Edit, Glob, Grep, Agent, Skill, AskUserQuestion

/forge:start-implement

計画書（{feature}_plan.yaml）からタスクを選択し、コンテキスト収集→実装→レビュー→計画書更新を実行する。

Goal

計画書から選択したタスクの実装・AIレビュー・計画書更新・完了案内まで完走すること。

フロー継続 [MANDATORY]

Phase 完了後は立ち止まらず次の Phase に自動で進む。不明点がある場合のみ AskUserQuestion で確認する。

---

コマンド構文

/forge:start-implement [feature] [--task TASK-ID[,TASK-ID,...]] [-n N]

引数	内容
feature	Feature 名（省略時は対話で確定）
--task	実行するタスクID（カンマ区切りで複数指定可。省略時は優先度順で自動選択）
-n	優先度順で選択するタスク数（省略時は1件。依存関係に基づいて並列/ウェーブ実行を自動決定する）

---

重要原則 [MANDATORY]

• 文書は省略しない — 関連する可能性のある文書は全て executor に渡す。「最小限」思考は禁止
• 具体的なファイルパスで指定 — glob 指定は禁止、セクション番号・行番号指定も禁止
• 計画書のチェックマーク更新はオーケストレーターの責務 — executor は更新しない
• executor の SUCCESS/FAILURE 報告に基づいて次の行動を決定 — 単一タスク実行時、FAILURE 時は Phase 5 をスキップ（複数タスク実行時の一部 FAILURE は Phase 5 をスキップしない。詳細は Phase 5 参照）

---

Phase 1: 事前確認 [MANDATORY]

1.1 Feature の確定と計画書の読み込み

対象 Feature を確定し、計画書を特定する。Feature が決まらないと、どの計画書のタスクを実行するかが決まらない。

• 引数あり → その Feature を使用
• 引数なし → AskUserQuestion で対象 Feature を確認

計画書のパスを解決する:

${CLAUDE_PLUGIN_ROOT}/skills/doc-structure/SKILL.md の「出力先ディレクトリの解決」手順に従い、 doc_type plan、feature {feature} でディレクトリを求め、その配下の {feature}_plan.yaml を 計画書パスとする。

1. ファイルが存在する → そのパスを使用
2. plan に対応するエントリが無い、またはファイルが存在しない → specs/{feature}/plan/{feature}_plan.yaml をデフォルトとする
3. それでも見つからない → AskUserQuestion で手動指定

計画書（YAML）を Read し、全タスクの状態を把握する。

1.2 要件定義書・設計書の更新確認

Issue やバグ修正など計画書外のタスクを追加する場合:

1. 要件定義書への反映確認 — その内容が要件定義書に追記・修正されているか
2. 設計書への反映確認 — 設計変更を伴う場合、設計書に反映されているか
3. 未反映の場合 — AskUserQuestion: 「要件定義書/設計書への反映が必要です。先に更新しますか？」

---

Phase 2: タスク選択

2.1 タスクの選択

--task 指定あり（単一）:

• 指定されたタスクを実行対象とする

--task 指定あり（複数: カンマ区切り）:

• 指定された全タスクを実行対象とする
• 例: --task TASK-001,TASK-003

-n N 指定あり:

1. tasks 配列を priority 降順でソート
2. status: pending のタスクから上位 N 件を選択する
3. グループの原子的選択 [MANDATORY]: 選択した N 件の中に group_id が非 null のタスクが含まれる場合、同じ正規化グループキー（通し番号 "(1/7)" 等を除去したもの。Phase 5.1 で使う group_review_batch.py の normalize_group_key と同一の正規化）を持つ status: pending の他タスクを、優先度に関わらず選択に追加する。グループは常に全メンバーが揃った状態で選択する（一部だけを選択しない）。これにより Phase 5.1 のグループ単位バッチレビューが確実に機能する（-n が優先度上位 N 件を選ぶだけだとグループの一部だけを選びがちで、バッチ化が機能しないため）
   • 追加分を含めた実際の選択件数は N を超えうる。追加後の件数を含めて 2.3 の並列実行確認に提示する
4. 選択した全件を依存関係に基づいてグループ化する（ここでの「グループ」は依存関係ベースの実行波であり、group_id によるレビュー用グループとは別概念）:
   • 実行可能グループ: 選択済みタスク内に未完了の depends_on がないもの → 並列実行候補
   • 待機グループ: 選択済みタスク内に未完了の depends_on があるもの → 前グループ完了後に実行

-n 未指定かつ --task 未指定:

1. tasks 配列を priority 降順でソート
2. status: pending のタスクから最高優先度のものを1つ選択

2.2 実行可能性の確認

選択した全タスクについて以下を確認:

• 依存関係チェック: depends_on 配列の全タスクが status: completed か確認。未完了の依存がある場合は AskUserQuestion で確認
• 設計書の存在: design_id が null でない場合は対応する設計書が存在するか確認
• タスクグループの確認: グループ内タスクはグループ先頭から順次実行。グループ途中からの実行は不可

2.3 複数タスク指定時の依存関係チェック [MANDATORY]

--task 複数指定時

タスク間の相互依存を検証する:

1. 指定されたタスク同士で依存関係がないか確認
2. 依存関係あり → エラー終了:「TASK-002 は TASK-001 に依存しているため並列実行できません。逐次実行してください。」
3. 依存関係なし → AskUserQuestion:「以下のタスクを並列実行します。よろしいですか？」とタスクリストを提示

-n N 指定時

依存関係に基づきウェーブ単位で実行する:

1. 実行可能グループ（選択済みタスク内に未完了の depends_on がないもの）を特定する
2. 実行可能グループ内で相互依存がないことを確認する → AskUserQuestion:「以下のタスクを並列実行します。よろしいですか？」とリストを提示
3. 実行可能グループを並列実行する（Phase 4 へ）
4. 完了後、待機グループのうち depends_on が全て完了したタスクを次の実行可能グループとして Phase 2.3 に戻る
5. 全グループの実行が完了したら完了処理へ進む

---

Phase 3: コンテキスト収集 [MANDATORY]

3.1 文書の特定

以下の手順でタスクに必要な文書を特定する:

3.1.1 設計書の特定

計画書の設計トレーサビリティマトリクスからタスクの設計IDに対応する設計書を特定する。

3.1.2 要件定義書の特定

設計トレーサビリティマトリクスの要件IDから関連する要件定義書を特定する。

3.1.3 実装ルールの収集

Agent ツール起動: 実装ルール収集
prompt:
  タスク "{タスクのタイトル}" (feature: {feature}) の実装に適用するプロジェクト固有ルール (レイヤー固有ルール等) を検索する。

  `/forge:query-db-rules {feature} {タスクのタイトル}` を呼ぶ。

  return value として以下の markdown 形式で返す:

  ## 実装ルール (N 件)
  - `path/to/rule.md` — 関連理由

3.1.4 既存コードの収集

Agent ツール起動: 既存コード収集
prompt:
  タスク "{タスクのタイトル}" (feature: {feature}) に関連する既存コード (類似実装、参照コード) を探索する。

  検索手順:
  - 機能名・コンポーネント名で `Grep` / `Glob: **/*{キーワード}*`
  - 同一ディレクトリ・import 元・類似命名・テストファイルを分類

  return value として以下の markdown 形式で返す:

  ## 既存コード (N 件)
  - `path/to/file.swift` — 関連理由

3.1.3 と 3.1.4 は Agent ツールで並列起動 する。エラー終了した場合は該当カテゴリなしで続行。各 agent の return value を main AI コンテキストに直接保持する。

3.1.5 計画書 required_reading フィールドの処理

タスクの required_reading 配列が空配列 [] でない場合、記載された各ファイルパスを追加の必読文書として executor に渡す。required_reading は YAML のタスクフィールドであり、Markdown table の「列」ではない点に注意する。

{feature}_strategy.md が required_reading に含まれている場合は、戦略書として分類して executor に渡す。含まれていない場合でも、計画書と同じディレクトリに {feature}_strategy.md が存在するなら追加の必読文書として executor に渡す。executor は全体戦略・フェーズ意図・リスク対策を理解したうえで、指定された単一タスクだけを実装する。

3.2 統合・表示

全 agent 完了後、agent の return value (実装ルール / 既存コード) と直接特定した文書 (設計書 / 要件定義書) を統合して表示する:

### ✅ コンテキスト収集完了

**設計書**
- `specs/{feature}/design/xxx.md` — 対象設計書

**要件定義書**
- `specs/{feature}/requirements/xxx.md` — 関連要件

**rules (N件)**
- `rules/xxx.md` — 実装ルール

**code (N件)**
- `src/xxx/YYY.ts` — 既存実装

**戦略書**
- `specs/{feature}/plan/{feature}_strategy.md` — 実装戦略

**追加必読文書**
- `specs/{feature}/rules/extra_context.md` — 計画書 required_reading（戦略書以外）

5件以下は全件表示、6件以上は先頭3件+省略。

---

Phase 4: タスク実行 [MANDATORY]

4.1 検証要件の判定 [MANDATORY]

オーケストレーターが計画書（{feature}_plan.yaml）を読み、タスクの YAML フィールド値から検証要件を判定する:

build_check フィールドの値による検証要件（build_check の値が最優先）:

値 (plan_format.md の値域)	検証要件
per_task（デフォルト）	タスク完了時にビルド確認必須
skip	ビルド確認スキップ（代替検証推奨）
on_group_complete	グループ最終タスクでビルド確認必須

acceptance_criteria フィールドが null でない場合:

• 記載された基準を検証要件として executor に渡す

4.2 パラメータの構築 [MANDATORY]

以下のテンプレートで executor への指示を構築する:

以下のタスクを実装してください。

## 実行ガイド

${CLAUDE_PLUGIN_ROOT}/docs/task_execution_spec.md を Read して手順に従うこと。

## タスク情報

- タスクID: {タスクID}
- タスク名: {タイトル}
- 優先度: {数値}
- 実装内容:
  {やるべき内容の箇条書き}

## 必読文書（全文読み込み必須）

- 設計書:
  - {設計書ファイルパス}
- 要件定義書:
  - {関連する全ての要件定義書}
- 戦略書:
  - {feature_strategy.md のパス}
- ルール文書:
  - {関連する全てのルール文書}
- 参照コード:
  - {関連する全ての既存実装}
- 追加必読文書:
  - {required_reading に含まれる戦略書以外の文書}

## 実装指示

{タスク固有の実装指示}

## 検証要件

- ビルド確認: {必須 | スキップ}
- テスト実行: {必須 | 任意 | スキップ}
- スキップ理由: {理由 | -}

パラメータは AskUserQuestion で人間に確認してから実行する [MANDATORY]

4.3 executor 起動

Agent(subagent_type: general-purpose, prompt: {構築したパラメータ})

並列実行時: 独立タスクごとに別の executor を Agent ツールで同時起動する。

4.4 executor の結果受領 [MANDATORY]

単一タスク実行時

executor は以下のステータスで報告する:

ステータス	意味	次のアクション
SUCCESS	実装完了	Phase 5（AI レビュー）へ
FAILURE	実装失敗	Phase 6.5（エラー対応）へ

複数タスク並列実行時

executor は計画書や共有リソースに直接書き込まない。 各 executor は結果を return value として JSON で返す。orchestrator が全 executor 完了後に return value を収集して一括処理する。

各 executor の return value JSON:

{
  "task_id": "TASK-001",
  "status": "SUCCESS",
  "files_modified": ["src/foo.py", "src/bar.py"],
  "summary": "実装の要約"
}

フィールド	説明
task_id	タスクID
status	SUCCESS / FAILURE
files_modified	変更したファイルパス一覧
summary	実装の要約（1-2行）
error	FAILURE 時のエラー内容（任意）

全 executor 完了後、orchestrator が return value を集めて Phase 5-6 を逐次処理する。

---

Phase 5: AI レビュー

単一タスク実行時、executor が FAILURE を報告した場合は本 Phase をスキップし Phase 6.5 へ進む。複数タスク実行時に一部が FAILURE の場合はスキップしない（5.1 のグループ判定に FAILURE 結果も必要なため）。

5.1 レビュー対象のグルーピング [MANDATORY]

タスク数 = レビュー起動回数ではない。計画書 ({feature}_plan.yaml) の group_id が同一のタスク群は 1 回のレビューにまとめる（グループ単位バッチレビュー）。1 タスク = 1 レビュー起動だと、機械的に同型の編集をファイル数分繰り返すだけのグループ（例: 同一パターンの置換を N ファイルに適用する GROUP）でもレビュー往復が N 回発生し、タスク数に比例して所要時間が伸びるため。

group_id は通し番号付き（"GROUP-001 (1/7)" 等）で記録されるため、単純な文字列一致では同一グループの各タスクが別グループとして扱われてしまう。この正規化・グループ完全性判定・部分失敗時の保留・ファイル順序の決定は決定論的な処理であり、SKILL.md にインライン記述せず専用スクリプトに委譲する（docs/rules/implementation_guidelines.md「SKILL.md にインラインスクリプトを書かない」）:

echo '<input_json>' | python3 ${CLAUDE_SKILL_DIR}/scripts/group_review_batch.py

<input_json> は以下の 2 フィールドを持つ。tasks は計画書 tasks[] 全件から task_id/group_id のみを抽出したもの（Phase 1 で計画書を読み込み済みのため抽出は容易）、results は今回の実行で得た 全 executor 結果（SUCCESS/FAILURE 問わず）:

{
  "tasks": [{ "task_id": "TASK-001", "group_id": "GROUP-001 (1/7)" }, "..."],
  "results": [
    { "task_id": "TASK-001", "status": "SUCCESS", "files_modified": ["..."] },
    "..."
  ]
}

出力:

{
  "status": "ok",
  "review_batches": [
    { "kind": "individual", "task_ids": ["TASK-010"], "files": ["..."] },
    {
      "kind": "group",
      "group_key": "GROUP-001",
      "task_ids": ["TASK-001", "..."],
      "files": ["..."]
    }
  ],
  "held_groups": [
    {
      "group_key": "GROUP-002",
      "task_ids": ["..."],
      "failed_task_ids": ["..."],
      "reason": "partial_failure"
    }
  ]
}

判定ロジックの要点（詳細はスクリプト実装を正とする）:

• group_id: null（独立タスク）: 常に kind: "individual"（1 タスク = 1 レビュー、従来通り）
• グループの全メンバーが今回の実行結果に揃っており、かつ全て SUCCESS: kind: "group" として 1 回に合算（ファイルは重複除去・計画書順で決定論的に整列）
• グループの一部メンバーしか今回の結果に含まれない（過去の別起動で分割実行された、または --task で意図的に一部だけ指定した等）: 揃っていない分は kind: "individual" にフォールバックする（累積グループ差分の追跡は複雑さに見合わないためスコープ外）。-n N 指定時は Phase 2.1「グループの原子的選択」により通常このケースは発生しない（グループが選択されれば必ず全メンバーが揃う）。発生しうるのは --task で明示的に一部タスクのみを指定した場合のみ
• グループの全メンバーが揃っているが 1 件以上 FAILURE: グループ全体を held_groups へ回し、SUCCESS した同グループの他タスクも含めてレビュー対象にしない（中間状態の壊れたグループを合算レビューしたり、成功した一部だけを完了扱いにしたりしない）

5.2 レビューの実施

review_batches[] を順に処理する（グループ内部・グループ間ともに並列化しない。/forge:review 自体が内部で並列 agent を使用するため、レビューを更に並列化するとリソース競合が発生する）:

• kind: "individual" → 該当 files に対して Skill ツールで /forge:review code --files {files} --auto を実行する
• kind: "group" → 該当 files（グループ全メンバー合算・重複除去済み）に対して /forge:review code --files {files} --auto を 1 回だけ 実行する
  • 合算ファイル数が実用上限（3〜5 件、目安）を大きく超える場合は /forge:review 側の絞り込みフロー（Phase 2 Step 3）に従う。1 回のレビュー呼び出しに固執せず、絞り込みの結果として複数回に分割されることを許容する

# Skill ツールで起動する（kind 問わず同一構文）
/forge:review code --files {ファイル一覧(カンマ区切り)} --auto

held_groups[] は Phase 6.5（エラー対応）で扱う: グループ内の一部タスクが FAILURE の場合、SUCCESS した同グループの他タスクも含めてレビュー・完了マークを保留し、失敗タスクの解決後に同グループ全体を再実行・再レビューする。

/forge:review が利用できない場合は git diff で変更差分を人間に提示し、手動レビューを依頼する。

5.3 レビュー完了

レビュー+自動修正が完了したら Phase 6 へ進む。

---

完了処理

6.1 結果判定

executor のステータスに基づいて分岐:

• SUCCESS → 6.2 へ
• FAILURE → 6.5 へ

複数タスク並列実行時

各 executor の return value JSON を収集し、SUCCESS / FAILURE を分類する:

• SUCCESS タスク → 6.2 で一括更新。ただし Phase 5.1 の held_groups[] に含まれる task_id は除外する（レビューが保留されており、まだ completed にしてはならない）
• FAILURE タスク → 6.5 で個別対応
• held_groups[] に含まれる task_id（SUCCESS だが同グループの他タスクが FAILURE のため保留） → 6.5 で扱う（グループ全体として、失敗タスクの解決を待ってから再実行・再レビューする対象。status は pending/in_progress のまま据え置く）

6.2 計画書の更新 [MANDATORY]

レビュー完了後、計画書（YAML）を更新する:

1. タスクのステータス: status: pending → status: completed（held_groups[] の task_id は対象外。レビュー未実施のため completed にしない）
2. 要件トレーサビリティ: 関連する要件の全タスクが completed なら status: completed に更新

複数タスク並列実行時: held_groups[] を除いた全 SUCCESS タスクのステータスを1回の計画書更新で一括変更する。個別に更新しない。held_groups[] に含まれるタスクは実装（コード変更）自体は完了しているが、レビュー未実施のため今回の更新対象に含めない。

6.3 commit/push 確認

commit/push の確認フローを担うスキル（例: anvil:commit）が available-skills にあれば呼び出す。無ければ git add → git commit の手順を案内する（Issue #159）。

6.4 次タスク判定

次タスクの判定:

• 同一 Feature に未完了タスクがある → AskUserQuestion:「次のタスクに進みますか？」
  • 進む → Phase 2 に戻る
  • 終了 → 「完了案内（未完了タスクあり）」を表示
• 同一 Feature に未完了タスクがない → 6.4.1 の完了処理へ

6.4.1 全タスク完了時の後処理 [MANDATORY]

全タスク完了時、計画書（および追加開発の場合は feature 仕様一式）の扱いをユーザーに確認する。 自動削除や自動統合は禁止。必ず AskUserQuestion で確認する。

Step 1: 追加開発か基本仕様修正かを文脈から判定

機械的な名前一致では判定しない。AI が以下の観点で文脈判定する:

1. 計画書 {plan_path} から {plan_dir}（plan ファイルの親）を取り、その親 {candidate_dir} を見る
2. {candidate_dir} が {requirements,design,plan} を含むディレクトリであり、さらに その親（仕様棚）に他の兄弟仕様（別 feature ディレクトリや別の {requirements,design,plan} セット）が存在する → 追加開発の可能性が高い
3. 仕様棚に他の仕様が見当たらず、{candidate_dir} のみ → 基本仕様の修正である可能性が高い
4. 判定が不確実な場合は AskUserQuestion で確認:
   • 質問:「これは追加開発（後で merge-specs で本体仕様 DIR に統合する）ですか、それとも基本仕様の修正ですか？」
   • 選択肢: 追加開発 / 基本仕様の修正

ディレクトリ名（main 等）の固定形式は存在しないため、名前一致や深さの機械的ルールには依存しない。

Step 2A: 追加開発の場合

AskUserQuestion:「追加開発の全タスクが完了しました。/forge:merge-specs を実行して本体仕様 DIR に統合しますか？（実行時は基本 DIR と追加 DIR の 2 引数が必要）」

• 統合する → /forge:merge-specs <base> {feature} を実行（<base> は本体仕様 DIR の短縮名 / 相対パス）→ 完了案内（merge 実行パターン）
• 後で実行する → 計画書はそのまま残す → 完了案内（plan 残しパターン）

Step 2B: 基本仕様修正の場合

AskUserQuestion:「全タスクが完了しました。計画書（plan）を削除しますか？」

• 削除する → rm {plan_path} → 完了案内（plan 削除パターン）
• 残す → 計画書はそのまま残す → 完了案内（plan 残しパターン）

6.5 エラー対応（FAILURE パス）

executor が FAILURE を報告した場合:

1. エラー内容を人間に提示（AskUserQuestion）
2. 人間の判断に基づいて対応:
   • executor 再実行 → 前回の失敗情報を追加指示として含め、Phase 4 から再実行
   • 手動で修正 → オーケストレーターまたは人間が直接修正後、Phase 5 へ
   • タスクをスキップ → 計画書は更新せず、Phase 6.4 へ

再実行上限: 1回（初回 + 再実行1回 = 最大2回）。上限に達した場合は人間にエスカレーションして終了する。

held_groups（グループの部分失敗）への対応

Phase 5.1 が held_groups[] を返した場合、FAILURE したタスクを 6.5 の通常フローで対応した後、同グループ全体を Phase 4 から再実行する（SUCCESS 済みメンバーも含めて再実行対象とする。差分がなければ executor は素通りで再度 SUCCESS を返す想定）。個別タスクの再実行上限（1回）とは別に、グループ再実行はグループ内 FAILURE タスクの再実行上限に従う。再実行後、Phase 5.1 のグループ判定を再度通し、全メンバー SUCCESS になった時点で初めてグループ合算レビューを実施する。

---

完了案内（未完了タスクあり）

タスク実行が完了しました:
  → {タスクID}: {タイトル} ☑

残タスク: {未完了タスク数} / {全タスク数}
次のタスク候補: {次の最高優先度タスクID} — {タイトル}

次のステップ:
  /forge:start-implement {feature}                              # 次のタスクを実行
  /forge:start-implement {feature} -n 3                         # 優先度順で3件を選択して実行
  /forge:start-implement {feature} --task {TASK-ID}             # 特定タスクを実行
  /forge:start-implement {feature} --task {ID1},{ID2},{ID3}     # 複数タスクを並列実行

全タスク完了案内

全タスク完了時、6.4.1 の選択結果に応じて以下のいずれかを表示する。

merge 実行パターン（追加開発 → 統合実行）

{feature} の全タスクが完了し、本体仕様への統合を実行しました。
  完了タスク: {完了タスク数} / {全タスク数}
  統合: /forge:merge-specs <base> {feature} 完了

plan 削除パターン（基本仕様修正 → plan 削除）

{feature} の全タスクが完了し、計画書を削除しました。
  完了タスク: {完了タスク数} / {全タスク数}
  削除: {plan_path}

plan 残しパターン（merge 後回し / 削除しない選択）

{feature} の全タスクが完了しました。計画書は残しています。
  完了タスク: {完了タスク数} / {全タスク数}
  計画書: {plan_path}

追加開発で merge を後回しにした場合、必要なタイミングで /forge:merge-specs <base> {feature} を実行する（<base> は本体仕様 DIR の短縮名 / 相対パス）。