orchestrator

# Orchestrator スキル (Claude Code) パイプラインをワンコマンドで自動実行するオーケストレーター。 5 ステージの直列パイプラインを実行し、各ステージ後に Review Gate（Requirements / Contract / Test / Code / Doc）で品質を担保する。 ## 仕様参照 本スキルのワークフローは `core/orchestrator.md` に定義。 各ステージの詳細仕様: - Stage 0: `core/requirements.md` - Stage 1: `core/spec.md` - Stage 2: `core/test-from-contract.md` - Stage 3: `core/implement.md` - Stage 4: `core/generate-docs.md` Review Swarm プロンプト: `{baseDir}/references/review-prompts/` Contract スキーマ: `core/contract-schema.md` レビュー基準: `core/review-criteria.md` ## 前提条件 | 条件 | 必須 | 説明 | |------|------|------| | Git リポジトリ | ○ | git root でプロジェクトルートを検出 | | テストフレームワーク | △ | 未検出時は Stage 2 でユーザーに確認 | | `.blueprint/` | × | なくても Stage 1 から開始可能 | ## コマンドオプション | オプション | 説明 | |-----------|------| | `/blueprint` | パイプライン実行（Smart Skip 適用） | | `/blueprint --resume` | 中断点から再開 | | `/blueprint --force` | 全ステージ強制実行（Smart Skip 無視） | ## ツール | ツール | 用途 | |--------|------| | Bash | git root 検出、テスト実行（resume 時の GREEN チェック） | | Glob | Contract/テスト/docs ファイルスキャン | | Read | Contract YAML、設定ファイル、パイプライン状態読み込み | | Write | テスト/docs ファイル書き出し、パイプライン状態保存 | | Agent | Review Gate（3〜4 エージェント並列起動） | ## ワークフロー（Claude Code 固有部分） `core/orchestrator.md` のパイプラインに従う。以下は Claude Code 固有の実行詳細: ### Step 0: 初期化 ```bash # git root を検出 git rev-parse --show-toplevel ``` ``` # パイプライン状態を確認 Read(".blueprint/pipeline-state.yaml") ``` **--resume モード判定**: - ユーザーが `--resume` を指定 → `.blueprint/pipeline-state.yaml` を読み込み、中断点から再開。 詳細な status 組み合わせ → 再開ステップのマッピングは `core/orchestrator.md` の「--resume フロー」を参照。 代表的なパターン: - `stage_3_implement` completed → テスト GREEN チェック → Code Review Gate → Stage 4 へ - `code_review_gate.status: revising` → Code Review Gate から再実行 - `contract_review_gate.status: revising` → Contract Review Gate から再実行（Stage 1 完了後） - 各ステージが `pending`/`in_progress` → 該当ステージの最初から再実行 - `final_status: completed` → 「完了済み。--force で再実行してください」 - `--force` を指定 → 新規パイプラインとして全ステージ実行 - 指定なし → Smart Skip を適用して実行 ### Step 1: Smart Skip 判定 各ステージの Smart Skip 条件をチェック: ``` # Stage 0 スキップ判定 Glob("docs/requirements/user-stories.md") → user-stories.md が存在 → ユーザーに確認: 「既存の要件定義が見つかりました。これを使いますか？ 新規作成しますか？」 # Stage 1 スキップ判定 Glob(".blueprint/contracts/**/*.contract.yaml") → active/draft Contract ≥1 → ユーザーに確認: 「既存の Contract が N 件見つかりました。これを使いますか？ 新機能を追加しますか？」 # Stage 2 スキップ判定 Grep("@generated by /test-from-contract", "tests/contracts/**") → マーカー付きテスト ≥1 → ユーザーに確認: 「既存のテストファイルが見つかりました。これを使いますか？ 再生成しますか？」 # Stage 4 スキップ判定 Glob("docs/03_architecture/**") → 設計書 ≥1 → ユーザーに確認: 「既存のドキュメントが見つかりました。これを使いますか？ 再生成しますか？」 ``` ### Step 2: Stage 0 — Requirements 実行 `core/requirements.md` の 6 ステップワークフローを実行する。 1. コンテキスト読み込み + モード判定（greenfield/brownfield） 2. インタビュー（Double Diamond パターン、最大 10 質問） 3. 構造化（Epic → Story 階層化、ユーザー承認必須） 4. ユーザーストーリー生成（EARS 記法 + Gherkin AC） 5. 品質チェック + 自動補正 6. サマリー出力 ### Step 3: Requirements Review Gate 3 つの Agent を**並列**起動: ``` # 並列起動（3 Agent） Agent(subagent_type: "general-purpose", prompt: "{requirements-reviewer.md の Agent 1: Completeness Checker プロンプト}") Agent(subagent_type: "general-purpose", prompt: "{requirements-reviewer.md の Agent 2: Quality Auditor プロンプト}") Agent(subagent_type: "general-purpose", prompt: "{requirements-reviewer.md の Agent 3: Traceability Checker プロンプト}") ``` **入力**: `docs/requirements/user-stories.md` + `core/id-system.md` + `core/review-criteria.md` + `skills/requirements/references/quality_rules.md` の内容 **Gate 判定**: 1. 3 エージェントの findings を集約 2. 重複正規化（同一 target + field をマージ、最高 severity を採用、message は連結保持） 3. P0=0 かつ P1≤1 → PASS → Step 4 へ 4. P0≥1 or P1≥2 → REVISE → findings をもとに修正 → Step 3 再実行（最大 3 サイクル） 5. 3 サイクル超過 → ユーザーに介入要請 ### Step 4: Stage 1 — Spec 実行 `core/spec.md` の 7 ステップワークフローを直接実行する。 > `docs/requirements/user-stories.md` が存在する場合、Step 2（スコープ確認）で自動読み込みし、ブレストの初期入力にする。 1. `.blueprint/` コンテキスト読み込み 2. スコープ確認（ユーザー対話 + user-stories.md ベース） 3. ブレインストーミング（ユーザー対話） 4. Contract 一覧合意（ユーザー承認必須） 5. Contract YAML 生成 6. 副産物生成 7. サマリー出力 ### Step 5: Contract Review Gate 3 つの Agent を**並列**起動: ``` # 並列起動（3 Agent） Agent(subagent_type: "general-purpose", prompt: "{contract-reviewer.md の Agent 1 プロンプト}") Agent(subagent_type: "general-purpose", prompt: "{contract-reviewer.md の Agent 2 プロンプト}") Agent(subagent_type: "general-purpose", prompt: "{contract-reviewer.md の Agent 3 プロンプト}") ``` **入力**: Contract YAML ファイルパスリスト + contract-schema.md + review-criteria.md の内容 **Gate 判定**: Step 3 と同じプロトコル ### Step 6: Stage 2 — Test Generation 実行 `core/test-from-contract.md` の 6 ステップワークフローを実行する。 **オーケストレーターモード自動化**: - Contract 選択: ユーザー確認を省略、active + draft 全件を自動選択 - テスト環境: 自動検出成功時は確認を省略 1. コンテキスト読み込み 2. Contract 選択（自動: 全件） 3. テスト環境確認（自動検出、未検出時のみユーザー確認） 4. Level 1 テスト生成 5. Level 2 テスト生成 6. サマリー出力 ### Step 7: Test Review Gate 3 つの Agent を**並列**起動: ``` Agent(subagent_type: "general-purpose", prompt: "{test-reviewer.md の Agent 1 プロンプト}") Agent(subagent_type: "general-purpose", prompt: "{test-reviewer.md の Agent 2 プロンプト}") Agent(subagent_type: "general-purpose", prompt: "{test-reviewer.md の Agent 3 プロンプト}") ``` **入力**: テストファイルパスリスト + Contract YAML + test-from-contract.md + review-criteria.md **Gate 判定**: Step 3 と同じプロトコル ### Step 8: Stage 3 — Implementation implement スキル（`core/implement.md`）のワークフローを実行する。 ``` # Step 1-2: コンテキスト + 実装計画 + 承認 + deps インストール Read(".blueprint/config.yaml") # → トポロジカルソート → ユーザー承認 → パッケージインストール # Phase A: Implementers（Agent ツールで並列起動） # depends_on のトポロジカルソート順に、グループごとに並列実行 Agent(subagent_type: "general-purpose", prompt: "Contract CON-xxx を実装...") Agent(subagent_type: "general-purpose", prompt: "Contract CON-yyy を実装...") # → 各 Contract の RED→GREEN（business_rules は TDD） # Phase B: Integrator（メインエージェント自身） # → app entry 結線 + 全テスト一括実行 # Phase C: Refactorer（Agent ツール、コンテキスト非共有） Agent(subagent_type: "general-purpose", prompt: "構造リファクタリング...") # → 重複排除、共通化、命名統一 # /simplify 実行 Skill("simplify") # → [承認] ``` **pipeline-state の stage_3_implement を更新**: ```yaml stage_3_implement: status: completed | partial | failed implementers: total_contracts: N completed: N blocked: [] integrator: test_results: { pass: N, fail: N } circular_imports: N duplicate_code_warnings: N plan_approval: accepted # 実装計画承認 final_approval: accepted # 実装完了承認 ``` ### Step 9: Code Review Gate（Contract↔実装の乖離検出）— 必須 **重要**: テスト GREEN チェック（Step 8）は「動作の正しさ」を確認するだけ。 Code Review Gate は「Contract の宣言がコードに反映されているか（宣言の一致）」+「コード品質」を検証する。 テストが GREEN でも、バリデーションスキーマに制約が欠落していればここで検出される。 **テスト GREEN だけで Code Review Gate をスキップしてはならない。** 4 つの Agent を**並列**起動: ``` Agent(subagent_type: "general-purpose", prompt: "{code-reviewer.md の Agent 1: Schema Compliance Checker プロンプト}") Agent(subagent_type: "general-purpose", prompt: "{code-reviewer.md の Agent 2: Route & Handler Checker プロンプト}") Agent(subagent_type: "general-purpose", prompt: "{code-reviewer.md の Agent 3: Business Logic Checker プロンプト}") Agent(subagent_type: "general-purpose", prompt: "{code-reviewer.md の Agent 4: Code Quality Checker プロンプト}") ``` **入力**: Contract YAML + ソースコード（src/, app/, routes/）+ バリデーションスキーマ + tests/ui/（screen Contract がある場合）+ config.yaml + core/defaults/ + review-criteria.md **Gate 判定**: Step 3 と同じプロトコル - PASS → pipeline-state.yaml の `code_review_gate` を更新して Stage 4 へ - REVISE → ユーザーに乖離リストを提示、修正後に再実行 **pipeline-state.yaml 更新例（Code Review Gate PASS 時）**: ```yaml code_review_gate: status: passed cycles: 1 final_counts: { p0: 0, p1: 0, p2: 2 } code_review_items: [] notes: "Schema/Route/Business/Quality 4-agent 検証完了" ``` ### Step 10: Stage 4 — Doc Generation 実行 `core/generate-docs.md` の 5 ステップワークフローを実行する。 1. プロジェクト分析 2. 自動抽出フェーズ（グループ A → B） 3. 補足入力フェーズ（グループ C） 4. トレーサビリティ検証 5. レビュー + サマリー ### Step 11: Doc Review Gate 3 つの Agent を**並列**起動: ``` Agent(subagent_type: "general-purpose", prompt: "{doc-reviewer.md の Agent 1 プロンプト}") Agent(subagent_type: "general-purpose", prompt: "{doc-reviewer.md の Agent 2 プロンプト}") Agent(subagent_type: "general-purpose", prompt: "{doc-reviewer.md の Agent 3 プロンプト}") ``` **入力**: docs/ ファイルリスト + .blueprint/ + ソースコード + review-criteria.md **Gate 判定**: Step 3 と同じプロトコル ### Step 12: 最終サマリー出力 ``` ## パイプライン完了 ### ステージ結果 | ステージ | 結果 | 成果物 | |---------|------|--------| | Stage 0: Requirements | {PASS|skipped} | user-stories.md | | Stage 1: Spec | {PASS|skipped} | N Contracts | | Stage 2: Test Gen | {PASS|skipped} | X Level 1 + Y Level 2 (+ Z UI テスト) | | Stage 3: Impl | completed | 全テスト GREEN | | Stage 4: Doc Gen | {PASS|skipped} | Z ファイル | ### Review Gate サマリー | Gate | P0 | P1 | P2 | 判定 | サイクル | |------|----|----|----|----- |---------| | Requirements | 0 | N | N | PASS | 1 | | Contract | 0 | 0 | N | PASS | 1 | | Test | 0 | N | N | PASS | 1 | | Code | 0 | N | N | PASS | 1 | | Doc | 0 | N | N | PASS | 1 | ### P2 要対応リスト - [対象] 問題の説明 ### 次のステップ - P2 要対応リストの項目を手動で修正 - 設計書を git commit ``` パイプライン状態を `completed` に更新: ```yaml # Write(".blueprint/pipeline-state.yaml") — 既存の内容を更新 completed_at: "{now()}" final_status: completed # 各 stages と review gate の status はそれぞれの完了時に更新済み ``` ## 原則 | 原則 | 説明 | |------|------| | Contract が唯一の真実源 | テストも設計書も Contract から導出される | | Review Swarm で品質担保 | 各ステージ後に 3 並列レビューで多角的に検証 | | Smart Skip で効率化 | 既存成果物を検出して不要なステージをスキップ | | 状態永続化 | .blueprint/pipeline-state.yaml でパイプライン進捗を保持 | | 段階的品質向上 | REVISE サイクルで findings を修正し品質を上げる | ## エラーハンドリング | エラー | 対応 | |--------|------| | `.blueprint/` なし + `/blueprint` | Stage 1 から開始（正常フロー） | | `--resume` で .blueprint/pipeline-state.yaml なし | `/blueprint` で最初から実行するよう案内 | | Review Gate で REVISE 3 回超過 | findings リストを提示してユーザーに介入要請 | | テストフレームワーク未検出 | ユーザーに確認（デフォルト: Vitest） | | Stage 途中でエラー | 成功分は保持、.blueprint/pipeline-state.yaml に現在のステージを記録して停止 | | テスト実行失敗（--resume 時） | ユーザーに警告し、続行するか確認 |