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: 初期化

# 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 を更新:

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 時）:

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 に更新:

# 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 時）	ユーザーに警告し、続行するか確認