pipeline-handoff

エージェント選択

ユーザーリクエスト	エージェント	ショートカット許可
新機能またはエンハンスメント	product-requirements-expert	いいえ — フルパイプライン必須
機能アイデアの検討または探索	product-requirements-expert	はい — 単一エージェント
要件の明確化	product-requirements-expert	はい — 単一エージェント
アーキテクチャに関する質問	system-design-expert	はい — 単一エージェント
バグ修正（原因が既知）	feature-implementer	はい — PRD/設計をスキップ
コードレビューリクエスト	4 人全員のレビュアー	はい — 並列呼び出し

エージェントをスキップする場合: git 操作、質問への回答、コマンド実行、既に完了した変更のレビュー。

ハンドオフ条件

すべての遷移は、.scratch/handoff.jsonl 内の (req_id, type) ごとの最新レコードでゲートされます。以下の検証ゲートセクションで、各ゲートの構造チェックを定義しています。

現在のエージェント	トリガー	次のエージェント
product-requirements-expert	最新の prd-entry レコードが検証ゲートを通過	system-design-expert
system-design-expert	最新の design-block レコードが verdict: "approved" または "revised" で、検証ゲートを通過	feature-implementer
feature-implementer	最新の build-pass レコードが存在し、同じ req_id の build-failure より後の日時	全レビュアー（並列）
feature-implementer	最新の build-failure レコードが retry < 3	feature-implementer（エラーコンテキスト付きで再試行）
feature-implementer	最新の build-failure レコードが retry == 3	system-design-expert（エスカレーション）
4 人全員のレビュアー	各レビュアーの最新 review-feedback レコードが verdict: "approved"	機能完成
いずれかのレビュアー	最新の review-feedback レコードが verdict: "changes_requested" または "blocked" で、空でない findings	feature-implementer（findings を処理）

検証ゲート

各エージェント遷移は、次の専門家をディスパッチする前に、インバウンドレコードをスキーマに対して検証します。形式が正しくないか見つからないレコードは、Sonnet/Opus ディスパッチを消費することなく、上流エージェントに戻されます。詳細は ADR 2026-05-08-append-only-jsonl-handoffs を参照してください。

共通手順

1. .scratch/handoff.jsonl を読み込みます。レコードが必要な場合にファイルが見つからないか空であれば、ゲートは失敗します — 上流エージェントにルーティングします。
2. req_id と type でレコードをフィルタリングします。各 (req_id, type) の最新レコードがアクティブな状態です。
3. スキーマごとに、必須フィールド、型、およびパターン制約をチェックします。
4. すべてのチェックに合格した場合: 次のエージェントをディスパッチします。いずれかのチェックに失敗した場合: 失敗した具体的なチェックを名付けた Blocked 推奨事項とともに上流にルーティングします。

ゲート 1: PRE → SDE (prd-entry)

スキーマ: schemas/scratch/prd-entry.schema.json。必須チェック:

• type == "prd-entry"、author == "product-requirements-expert"。
• req_id が ^REQ-[A-Z]+-[0-9]{3}$ と一致。ts は空でない ISO 8601 文字列。
• title、summary は空でない文字列。
• acceptance_criteria、file_targets、test_names は空でない文字列の空でない配列。
• 各 test_names エントリが ^Test[A-Z] と一致。

ゲート 2: SDE → implementer (design-block)

スキーマ: schemas/scratch/design-block.schema.json。必須チェック:

• type == "design-block"、author == "system-design-expert"、有効な req_id と ts。
• verdict は以下のいずれか: approved、needs_changes、blocked、revised、escalated。
• architectural_fit は空でなく、primary_paths は空でない文字列の空でない配列。
• verdict == "escalated" の場合: escalations 配列が存在し、空でない。
• verdict == "revised" の場合: supersedes_record_at が存在し、ファイル内の先行 design-block レコード行を指す。

ルーティング:

• approved または revised → feature-implementer をディスパッチ。(revised はその req_id のビルド失敗再試行カウンタをリセット)
• needs_changes または blocked → 戻す。PRE が改善を要するか、SDE が再実行を要する可能性。
• escalated → パイプラインを停止。人間が判断。

ゲート 3: implementer → reviewers (build-pass)

スキーマ: schemas/scratch/build-pass.schema.json。必須チェック:

• req_id の最新 build-* レコードが type == "build-pass"。
• author == "feature-implementer"、有効な req_id と ts。

最新が build-failure の場合は、代わりにビルド失敗復旧を適用します。

ゲート 4: reviewers → implementer または完成 (review-feedback)

スキーマ: schemas/scratch/review-feedback.schema.json。4 人のレビュアー author 値それぞれについて、最新の build-pass 以降のアクティブな req_id の最新レコードをチェック:

• verdict は以下のいずれか: approved、changes_requested、blocked。
• findings は配列。各 finding に tag、location、description。tag: "clarify" は clarify_target が必須。
• 4 人全員のレビュアーの最新 verdict が "approved" → 機能完成（feature-eval スキルを読み込み）。
• いずれかのレビュアーの最新 verdict が "changes_requested" または "blocked" → 構造化された findings とともに feature-implementer をディスパッチ。修正後、新たな build-failure/build-pass を追加し、レビュアーを再度呼び出し。

ブロッキング

ゲートが失敗した場合、または任意のレコードが verdict: "blocked" または "escalated" を持つ場合、パイプラインを停止し、継続前に解決します。

ビルド失敗復旧

feature-implementer が品質ゲートを実行して失敗した場合（ビルドエラー、テスト失敗、lint 失敗）、implementer は .scratch/handoff.jsonl に build-failure レコードをエラー出力と再試行カウントとともに追加し、終了します。スキーマ: schemas/scratch/build-failure.schema.json。

コーディネータの再試行ロジック

1. .scratch/handoff.jsonl を読み込みます。アクティブな req_id の最新 build-failure レコードを取得します。
2. retry < 3 の場合、このプロンプトコンテキストとともに feature-implementer にルーティング:
   • 最新の build-failure レコード（エラー出力）。
   • 最新の design-block レコード（元の設計）。
   • .scratch/implementation-plan.md（計画内容）。
   • 指示: 「最新の build-failure レコードに記載されているビルド失敗を修正してください。これは 3 回中の N 番目の再試行です。」
3. retry == 3 の場合、このプロンプトコンテキストとともに system-design-expert にエスカレート:
   • 最新の design-block 以降のアクティブな req_id のすべての build-failure レコード（失敗の追跡）。
   • 最新の design-block レコード。
   • 指示: 「implementer は 3 回失敗しました。設計の修正が必要かどうか確認してください。」
   • 設計専門家は verdict: "revised"（および supersedes_record_at）または verdict: "escalated" の新しい design-block レコードを追加。
4. 設計修正後（verdict: "revised"）、再試行カウンタがリセット — 次の build-failure レコードは retry: 1 から開始。

再試行ルール

• implementer は各新しい build-failure レコードで retry をインクリメント（1、2、3）。次の値は、最新の design-block 行の後に追加されたアクティブな req_id の build-failure レコード数をカウントし、retry = count + 1 を設定することで計算します。新鮮な design-block 後の最初の失敗（verdict: "approved" または "revised" のいずれか）は retry: 1。追記のみ — 先行するレコードは編集しません。
• 成功時、implementer は build-pass レコードを追加。先行する build-failure レコードは診断再試行追跡としてファイルに残ります。
• コーディネータはレコードを決して変更しません — ルーティング決定のためにのみ読みます。
• 設計サイクルあたり最大 3 回の再試行。verdict: "revised" の新しい design-block は新しいサイクルを開始。

実装中フィードバック

feature-implementer は、TDD サイクル中にテストが要件ギャップまたは設計ニーズを明らかにした際に、product-requirements-expert または system-design-expert を呼び出すことができます。これらはハンドオフではありません。implementer は待機中の他のサイクルを続行します。

レビューフィードバックアクション

フィードバックタグ定義とレビュープロセスについては、review-checklist スキルを参照してください。

状態ファイル

ファイル	作成者	使用者
.scratch/handoff.jsonl (prd-entry レコード)	product-requirements-expert	system-design-expert、feature-implementer
.scratch/handoff.jsonl (design-block レコード)	system-design-expert	feature-implementer、コーディネータ
.scratch/handoff.jsonl (build-failure / build-pass レコード)	feature-implementer	コーディネータ、system-design-expert（エスカレーション）
.scratch/handoff.jsonl (review-feedback レコード)	レビュアーエージェント	feature-implementer、コーディネータ
.scratch/implementation-plan.md	feature-implementer	feature-implementer（自己追跡）
.scratch/escalations.md	feature-implementer	人間
.scratch/eval-*.md	コーディネータ（feature-eval スキル経由）	人間

人間のチェックポイント

人間は以下のポイントで承認します:

1. PRD 更新後 — 要件が意図をキャプチャしていることを確認。
2. 設計ノート後 — アーキテクチャアプローチを確認。
3. エスカレーション後 — [ESCALATE] アイテムについて判断。
4. 機能完成後 — マージ前の最終承認。

コーディネータ出力形式

パイプラインコーディネータは構造化された推奨事項で応答します:

## Pipeline State
[.scratch/ ファイルに基づく現在の状態]

## Recommendation
**Action:** Invoke [agent-name]
**Prompt:** "[エージェント用の推奨プロンプト]"
**Shortcut:** Yes/No
**Reason:** [このエージェントが次である理由]

ブロックされた場合:

## Pipeline State
[現在の状態]

## Blocked
**Blocker:** [説明]
**Resolution:** [発生する必要があること]

コーディネータルール

1. 新機能のパイプラインステージを決してスキップしません。
2. ショートカットは上のエージェント選択テーブルに従った場合のみ許可されます。
3. .scratch/ に前の機能からの古い状態が含まれている場合、最初にそれをクリアすることをお勧めします。
4. すべての verdict: "escalated" レコードと tag: "escalate" findings を報告します。
5. アクティブな req_id の最新 build-* レコードが build-failure の場合、「ビルド失敗復旧」セクションの再試行ロジックを適用します。
6. 4 人全員のレビュアーの最新 review-feedback verdict が "approved" になった後、feature-eval スキルを読み込み、評価スコアカードを作成します。

パイプラインフロー

User Request
    |
    v
Pipeline Coordinator (リクエストを分類し、最新の handoff.jsonl レコードを検証)
    |
    +--- 新機能 ------> product-requirements-expert
    |                              | (prd-entry レコードを追加)
    |                              v
    |                        system-design-expert
    |                              | (design-block を追加、verdict: approved | revised)
    |                              v
    |                        feature-implementer
    |                              | (build-failure または build-pass を追加)
    |                     +--------+--------+
    |                     |                 |
    |                     v (build-pass)    v (build-failure, retry < 3)
    |               全レビュアー      feature-implementer
    |                  (並列)         (エラーコンテキスト付きで再試行)
    |                     |                 |
    |                     |                 v (build-failure, retry == 3)
    |                     |           system-design-expert
    |                     |           (verdict: revised または escalated)
    |                     |                 |
    |                     |                 v (verdict: revised, 再試行リセット)
    |                     |           feature-implementer
    |                     |
    |                     v (全 4 つの review-feedback verdict: approved)
    |               Feature eval → .scratch/eval-<name>.md
    |                     |
    |                     v
    |               機能完成
    |
    +--- バグ修正（既知） --> feature-implementer（ショートカット）
    +--- アーキテクチャ Q --> system-design-expert（単一エージェント）
    +--- コードレビュー -----> 全レビュアー（並列）