agentic-workflow-orchestration

🎭 エージェント型ワークフローオーケストレーションスキル

目的

調整、委任、並列実行を通じて、複雑な問題に取り組む複数のエージェント型ワークフローをオーケストレーションするためのガイダンスです。/plan による分解、タスクの抽出、エージェントの積み重ねによる調整など、Agent Factory（100 以上のワークフロー、500 件以上のマージ済み PR）で実証されたパターンを含みます。

使用するタイミング

次のような場合にこのスキルを適用します。

• 複雑な自動化を、連携するワークフローに分解する場合
• オーケストレーターとワーカーのパターンを実装する場合
• /plan コマンドを使って課題を分解する場合
• パイプラインまたはマップリデュースのパターンを構築する場合
• 異なる専門分野を持つ複数の AI エージェントを調整する場合

ルール

オーケストレーションの基本

必須：

• オーケストレーターは実行ではなく調整を行うよう設計します
• 単一の責任に特化したワーカーを作成します
• オーケストレーターとワーカーの通信にはワークフローのディスパッチを使用します
• オーケストレーターとワーカー間に明確な契約を定めます
• オーケストレーターでワーカーの失敗を適切に処理します
• ワーカーの結果を集約し、検証します
• オーケストレーションにおける判断と結果を記録します

禁止：

• オーケストレーションのロジックと実行ロジックを混在させないでください
• 過度に複雑なオーケストレーション階層を作成しないでください
• ワーカーの失敗を無視しないでください
• ワークフロー間に循環依存を作成しないでください
• ワーカーの結果の検証を省略しないでください

オーケストレーターの設計

必須：

• 可能な限りオーケストレーターをステートレスに保ちます
• GitHub API を使ってワーカーのステータスを追跡します
• 失敗したワーカー向けの再試行ロジックを実装します
• 成功と失敗の基準を明確にします
• オーケストレーションした作業の概要レポートを生成します
• ワーカーは垂直方向ではなく水平方向にスケールします
• オーケストレーションのロジックを明確に文書化します

禁止：

• ワーカー名や設定をハードコードしないでください
• ワーカーが常に成功すると想定しないでください
• 長時間実行されるオーケストレーターを作成しないでください（代わりに定期チェックを使用します）
• オーケストレーターを特定のワーカー実装に密結合しないでください

ワーカーの設計

必須：

• 各ワーカーを、明確に定義された単一のタスクに特化させます
• ワーカーを個別にテストできるようにします
• 成功または失敗のステータスを明確に報告します
• オーケストレーターが利用できる詳細な出力を提供します
• エッジケースをローカルで処理します
• 適切なタイムアウトを実装します
• 一貫性のある出力形式を使用します

禁止：

• 複数の責任を持つワーカーを作成しないでください
• 他のワーカーに直接依存しないでください（オーケストレーターを使用します）
• オーケストレーターのコンテキストを前提にしないでください
• 終了しないワーカーを作成しないでください
• エラー報告を省略しないでください

通信パターン

必須：

• オーケストレーターからワーカーへの通信には、入力を指定した workflow_dispatch を使用します
• ワーカーからオーケストレーターへの通信には、issue、コメント、またはプルリクエストを使用します
• ワークフロー間通信には構造化データ形式（JSON、YAML）を実装します
• 通信プロトコルをバージョン管理します
• ワークフロー間のすべてのメッセージを検証します
• 通信の契約を文書化します

禁止：

• ワークフロー間通信にファイルシステムを使用しないでください
• 他のワークフローからの未検証データを信頼しないでください
• 隠れた通信チャネルを作成しないでください
• メッセージの検証を省略しないでください

並列実行

必須：

• 独立したワーカーを並列でディスパッチします
• 適切な同時実行数の上限を設定します
• 並列ワーカーのタイムアウト処理を実装します
• すべてのワーカーから結果を収集し、検証します
• 部分的な成功の状況を処理します
• 実行メトリクス（所要時間、成功率）を追跡します

禁止：

• 並列実行が可能なときに、ワーカーを順番に待たないでください
• 上限のない並列実行を作成しないでください
• 部分的な失敗を無視しないでください
• ワーカーが特定の順序で完了すると想定しないでください

エラー処理とレジリエンス

必須：

• 失敗するワーカーにサーキットブレーカーを実装します
• 再試行には指数バックオフを使用します
• 再試行の上限を設定します
• すべての失敗をコンテキストとともに記録します
• 継続的な失敗を人間にエスカレーションします
• グレースフルデグラデーションを実装します
• オーケストレーションにおける判断の監査証跡を維持します

禁止：

• 無期限に再試行しないでください
• オーケストレーターに失敗を隠さないでください
• 抑制措置なしに失敗を連鎖させないでください
• エラー発生状況の記録を省略しないでください

オーケストレーションパターン

パターン 1：シンプルなオーケストレーター／ワーカー

構成：

• 1 つのオーケストレーションワークフロー
• N 個の同種のワーカーワークフロー
• ワーカーは異なる入力に対して同一のタスクを実行します

ユースケース：

• バッチ処理（すべての未解決の issue を分析）
• 並列検証（複数の構成をテスト）
• 分散スキャン（リポジトリ全体のセキュリティ監査）

パターン 2：階層型オーケストレーション

構成：

• トップレベルのオーケストレーター
• 中間レベルの専門化されたオーケストレーター
• 最下層の実行ワーカー

ユースケース：

• 複雑な複数フェーズの操作
• フェーズごとに異なるオーケストレーション戦略
• 入れ子になったタスクの分解

パターン 3：パイプラインオーケストレーション

構成：

• オーケストレーターが順次実行されるステージを管理します
• 各ステージに専門化されたワーカーがあります
• あるステージの出力が次のステージに渡されます

ユースケース：

• CI/CD パイプライン
• データ処理パイプライン
• 複数ステップの検証ワークフロー

パターン 4：ルーター／ディスパッチャー

構成：

• ルーターが入力を分析して適切なワーカーを選択します
• 異なる機能を持つ異種ワーカー
• コンテキストに基づく動的なワーカー選択

ユースケース：

• issue のトリアージ（専門のハンドラーに振り分け）
• コンテンツモデレーション（コンテンツの種類に応じて振り分け）
• 多言語サポート（言語に応じて振り分け）

パターン 5：Map-Reduce

構成：

• Map フェーズ：オーケストレーターが入力ごとにワーカーを起動します
• Reduce フェーズ：オーケストレーターがワーカーの結果を集約します
• 最終レポートの生成

ユースケース：

• 複数のリポジトリにわたるリポジトリ分析
• 結果を集約する並列テスト
• 分散データの収集と統合

パターン 6：リフレクション（自己改善）

構成：

• 生成ワークフローが出力を生成します
• 批評ワークフローがレビューし、フィードバックを提供します
• コーディネーターが、品質のしきい値に達するまで反復を調整します

ユースケース：

• 品質レビューを伴うドキュメント生成
• セキュリティレビューを伴うコード生成
• スタイル検証を伴うコンテンツ作成

例

例 1：シンプルなオーケストレーター／ワーカーパターン

オーケストレーター（daily-orchestrator.md）：

---
on: daily
permissions: read-all
tools:
  github:
safe-outputs:
  create-issue:
    max: 1
---

# Daily Repository Orchestrator

Coordinate daily analysis across all open issues:

1. List all open issues in repository
2. For each issue, dispatch `issue-analyzer` worker workflow with issue number
3. Wait for all workers to complete (check workflow run statuses)
4. Collect results from worker comments
5. Generate summary report issue titled "Daily Analysis Report - [DATE]"

Include:
- Total issues analyzed
- Critical issues found
- Recommendations summary
- Links to worker analysis comments

ワーカー（issue-analyzer.md）：

---
on:
  workflow_dispatch:
    inputs:
      issue_number:
        required: true
        type: number
permissions: read-all
tools:
  github:
safe-outputs:
  create-comment:
    max: 1
---

# Issue Analyzer Worker

Analyze issue #${{ inputs.issue_number }}:

1. Read issue title, body, labels, and comments
2. Check for duplicates
3. Assess clarity and completeness
4. Identify missing information
5. Suggest appropriate labels

Post analysis as comment on the issue.
Use structured format:
- Status: [Clear/Unclear/Duplicate]
- Suggested Labels: [label1, label2]
- Action: [what should happen next]

例 2：階層型オーケストレーション

トップレベルのオーケストレーター（repo-health-orchestrator.md）：

---
on: weekly on monday
permissions: read-all
tools:
  github:
safe-outputs:
  create-issue:
    max: 1
---

# Repository Health Orchestrator

Coordinate comprehensive repository health check:

Phase 1: Dispatch specialized orchestrators
1. Dispatch `issue-health-orchestrator`
2. Dispatch `pr-health-orchestrator`
3. Dispatch `code-health-orchestrator`

Phase 2: Wait and collect
1. Wait for all phase 1 orchestrators to complete
2. Collect results from each orchestrator issue

Phase 3: Synthesize
1. Combine results into master health report
2. Generate action items by priority
3. Create issue with complete repository health status

中間レベルのオーケストレーター（issue-health-orchestrator.md）：

---
on:
  workflow_dispatch:
permissions: read-all
tools:
  github:
safe-outputs:
  create-issue:
    max: 1
---

# Issue Health Orchestrator

Coordinate issue-specific analysis:

1. Dispatch workers for:
   - Stale issue detection
   - Issue categorization
   - Response time analysis
   - Label consistency check

2. Collect worker results
3. Generate issue health report
4. Create issue with findings

例 3：パイプラインオーケストレーション

パイプラインオーケストレーター（deployment-pipeline.md）：

---
on: workflow_dispatch
permissions: read-all
tools:
  github:
safe-outputs:
  create-comment:
    max: 5
---

# Deployment Pipeline Orchestrator

Coordinate deployment pipeline stages:

Stage 1: Validation
1. Dispatch `security-validator` worker
2. Dispatch `test-validator` worker
3. Wait for both, check results
4. If any failures, stop and report

Stage 2: Staging Deployment
1. Dispatch `staging-deployer` worker
2. Wait for completion
3. Dispatch `staging-validator` worker
4. If validation fails, rollback and stop

Stage 3: Production Deployment
1. Require manual approval (create approval issue)
2. After approval, dispatch `production-deployer` worker
3. Dispatch `production-validator` worker
4. Generate deployment report

Post progress comments at each stage.

例 4：ルーター／ディスパッチャーパターン

ルーター（issue-router.md）：

---
on: issues
permissions: read-all
tools:
  github:
---

# Issue Router

Route new issues to specialized handlers:

1. Analyze issue labels and content
2. Determine issue type:
   - Bug → dispatch `bug-triage-worker`
   - Feature Request → dispatch `feature-triage-worker`
   - Security → dispatch `security-triage-worker`
   - Documentation → dispatch `docs-triage-worker`
   - General → dispatch `general-triage-worker`

3. Dispatch appropriate worker with issue number
4. Post comment indicating routing decision

例 5：Map-Reduce パターン

Map-Reduce オーケストレーター（security-audit-orchestrator.md）：

---
on: workflow_dispatch
permissions: read-all
tools:
  github:
safe-outputs:
  create-issue:
    max: 1
  create-code-scanning-alert:
    max: 1
---

# Security Audit Orchestrator (Map-Reduce)

Coordinate security audit across entire codebase:

MAP PHASE:
1. List all repositories in organization
2. For each repository, dispatch `security-scanner` worker
3. Track dispatched workers

REDUCE PHASE:
1. Wait for all scanners to complete
2. Collect SARIF reports from each worker
3. Aggregate findings:
   - Total vulnerabilities by severity
   - Top vulnerability types
   - Repositories with most issues
4. Generate consolidated SARIF report
5. Create master security issue with summary

例 6：リフレクションパターン

リフレクションオーケストレーター（doc-generator-orchestrator.md）：

---
on: workflow_dispatch
permissions: read-all
tools:
  github:
safe-outputs:
  create-pull-request:
    max: 1
---

# Documentation Generator with Reflection

Use reflection pattern for high-quality docs:

Iteration Loop (max 3 iterations):
1. Dispatch `doc-generator` worker to create documentation
2. Dispatch `doc-critic` worker to review generated docs
3. Collect critique feedback
4. If quality score >= 8/10, proceed to next step
5. If quality score < 8/10, regenerate with critique feedback

Final Step:
1. Create pull request with approved documentation
2. Include quality metrics in PR description
3. Link to critic reviews

例 7：サーキットブレーカーパターン

サーキットブレーカーを備えたオーケストレーター（resilient-orchestrator.md）：

---
on: schedule
permissions: read-all
tools:
  github:
safe-outputs:
  create-issue:
    max: 1
---

# Resilient Orchestrator with Circuit Breaker

Coordinate workers with failure protection:

For each task in task_list:
  1. Check circuit breaker state for worker type
  2. If OPEN (too many recent failures), skip and log
  3. If CLOSED, dispatch worker
  4. Track worker success/failure
  5. Update circuit breaker state:
     - 3 consecutive failures → OPEN circuit
     - 1 success after OPEN → HALF-OPEN
     - 3 successes in HALF-OPEN → CLOSED

Generate report with:
- Tasks completed successfully
- Tasks skipped (circuit open)
- Circuit breaker states
- Recommended actions

例 8：動的ワーカープール

動的プールオーケストレーター（scalable-orchestrator.md）：

---
on: workflow_dispatch
permissions: read-all
tools:
  github:
safe-outputs:
  create-issue:
    max: 1
---

# Dynamic Worker Pool Orchestrator

Scale workers based on workload:

1. Assess workload size (e.g., count of items to process)
2. Calculate optimal worker count (workload / items_per_worker)
3. Respect concurrency limits (max 10 concurrent workers)
4. Batch items for each worker
5. Dispatch workers with batch assignments
6. Monitor worker progress
7. If workers fail, redistribute work to new workers
8. Aggregate results when all batches complete
9. Generate completion report with metrics:
   - Items processed
   - Workers used
   - Success rate
   - Processing time

ベストプラクティス

オーケストレーターの設計

• オーケストレーションロジックをシンプルで直線的に保ちます
• 無限に待機するのを防ぐため、タイムアウトを使用します
• 長時間実行される調整処理にはヘルスチェックを実装します
• すべてのオーケストレーションの判断をログに記録します
• 人が読みやすい要約レポートを生成します

ワーカーの設計

• ワーカーを冪等にし、安全に再試行できるようにします
• 追跡可能性を確保するため、出力にワーカー ID を含めます
• 長時間実行されるワーカーの進捗を報告します
• 成功／失敗のシグナルを一貫させます
• 外部依存関係を最小限に抑えます

通信

• ワークフロー間のすべてのデータに構造化データ（JSON/YAML）を使用します
• 通信プロトコルにバージョンを付与します
• 他のワークフローからのすべての入力を検証します
• 通信の契約を明確に文書化します

テスト

• オーケストレーションの前にワーカーを個別にテストします
• モックのワーカー応答を使ってオーケストレーターをテストします
• 失敗シナリオ（タイムアウト、エラー）をテストします
• 部分的な成功のシナリオをテストします
• 現実的なワークロードで負荷テストを行います

モニタリング

• オーケストレーションの実行時間を追跡します
• ワーカーの成功率を監視します
• オーケストレーションの失敗時にアラートを出します
• エンドツーエンドのレイテンシーを測定します
• 主要なメトリクスをダッシュボードに表示します

トラブルシューティング

ワーカーが完了しない

• ワーカーのタイムアウト設定を確認します
• ワーカーログでエラーを確認します
• ワーカーのディスパッチが成功したことを確認します
• GitHub Actions のキューの状態を確認します
• ワーカーのヘルスチェックを実装します

オーケストレーションが停止する

• オーケストレーターのタイムアウトロジックを確認します
• 循環依存がないか確認します
• ワーカーの状態をポーリングするロジックを確認します
• 失敗ケースが処理されることを確認します

結果に一貫性がない

• ワーカーの冪等性を確認します
• 競合状態がないか確認します
• 結果の集約ロジックを確認します
• ワーカー間の通信形式を検証します

パフォーマンスの問題

• ワーカーのバッチサイズを最適化します
• 可能であれば並列度を高めます
• オーケストレーターのポーリング頻度を確認します
• ワーカーのキャッシュ戦略を検討します

関連する ISMS ポリシー

このスキルは、以下のポリシーに準拠しています。

• Secure Development Policy - 安全なオーケストレーションの実践
• Change Management Policy - デプロイメントの調整パターン
• Information Security Policy - 全体的なセキュリティフレームワーク

関連スキル

• GitHub Agentic Workflows - ワークフローの基本
• Agentic Workflow Security - オーケストレーションされたワークフローのセキュリティ
• Agentic Workflow Development - 開発とテスト
• Copilot Agent Patterns - カスタムエージェントのパターン

関連ドキュメント

• Agent Factory Workflows
• Orchestration Guide
• GitHub Actions Reusable Workflows

コンプライアンス対応

ISO 27001:2022

• A.8.25 セキュアな開発ライフサイクル
• A.8.32 変更管理
• A.5.37 文書化された運用手順

NIST Cybersecurity Framework 2.0

• PR.IP-02: システム開発ライフサイクルが実装されている
• PR.MA-01: 保守が実施されている
• DE.AE-03: イベントデータが収集され、相関付けられている

CIS Controls v8.1

• Control 16: アプリケーションソフトウェアのセキュリティ
  • 16.1 セキュアな開発プロセスを確立する
  • 16.14 修復プロセスを確立する

適用

オーケストレーションパターンへの違反：

• Critical: 循環依存、無限ループ - デプロイメントをブロックします
• High: エラー処理の欠如、タイムアウトなし - 修正を必須とします
• Medium: 最適でないパターン、監視の欠如 - 改善チケットを作成します
• Low: ドキュメントの不足、最適化の機会 - 任意の改善

バージョン履歴

• 2026-04-02: Agent Factory で実証済みのパターン（/plan、タスクマイニング）と実際のマージ率データを追加して更新
• 2026-02-11: スキルを初回作成