task-orchestration

リソース

scripts/
  validate-orchestration.sh
references/
  agent-assignment-guide.md

タスクオーケストレーションプロトコル

タスクオーケストレーションプロトコルでは、GoodVibes オーケストレーターが機能リクエストをエージェントタスクに分解し、エージェントとスキルを割り当て、並列実行を管理し、ランタイムエンジンの WRFC チェーンシステムと連携する方法を定義します。これは、複数のエージェントで機能を提供するためのオーケストレーターの主要なワークフローです。

このスキルを使用するタイミング

次の場合にこのスキルを使用します。

• ユーザーが複数の作業ストリームを必要とする機能リクエストを提示した場合
• リクエストに複数の領域（バックエンド、フロントエンド、データベースなど）が含まれる場合
• リクエストを独立したサブタスクに並列化できる場合
• リクエストに複数のエージェント間の調整が必要な場合

次の場合はこのスキルを使用しないでください。

• 単純な単一ファイルの編集（直接対応してください）
• コード変更を伴わない純粋な分析タスク
• ユーザーがすでに分解したタスク

ランタイムエンジンと WRFC チェーン

ランタイムエンジンは、Work-Review-Fix-Complete（WRFC）チェーンを自動的に管理します。オーケストレーターの役割は次のとおりです。

1. タスクを作業エージェントに分解する
2. 初期作業エージェントを起動する
3. ランタイムエンジンが発行する <gv> ディレクティブを、判断を加えず機械的かつ即座に実行する

レビュー、修正、完了に関する判断はすべてランタイムエンジンが処理します。オーケストレーターがレビューエージェントや修正エージェントを手動で起動することはありません。これらは、各作業エージェントの完了後にランタイムディレクティブを通じてのみ起動されます。

ディレクティブの種類

ランタイムエンジンは、<gv> タグを含むシステムメッセージを通じてオーケストレーターにディレクティブを発行します。

{"action":"spawn","wid":"wrfc_xxx","type":"reviewer","task":"Review the code..."}
{"action":"spawn","wid":"wrfc_xxx","type":"engineer","task":"Fix the issues..."}
{"action":"complete","wid":"wrfc_xxx"}
{"action":"escalate","wid":"wrfc_xxx","reason":"Max fix attempts reached"}

ディレクティブ遵守ルール

次の4つのルールは絶対であり、交渉の余地はありません。

1. 即時：ディレクティブが届いたら、その場で実行してください。決して先送り、キューイング、遅延してはいけません。
2. 最優先：ほかのアクションを行う前にディレクティブを実行してください。途中でツールを呼び出したり、エージェントを追加で起動したり、先にユーザーメッセージを送ったりしてはいけません。
3. 自律性の終了：WRFC チェーンに対する最初のディレクティブが届いた時点で、オーケストレーターはそのチェーンについてそれ以上判断しません。チェーンはディレクティブによってのみ進行します。
4. ランタイムの優先：ランタイムのワークフローロジックは、常にオーケストレーターの判断に優先します。ディレクティブがレビューを指示したらレビューし、完了を指示したら完了してください。

設定可能なしきい値

ランタイムは goodvibes.json から次の値を読み取ります。

• score_threshold（デフォルト：9.9）— PASS のスコアしきい値
• max_fix_attempts（デフォルト：3）— エスカレーション前の最大修正サイクル数

オーケストレーターがこれらの値をハードコードすることはありません。ランタイムエンジンが適用します。

分解プロセス

ステップ1：リクエストを分類する

分解する前に、リクエストを次のいずれかのカテゴリに分類します。

機能実装 - 新しい機能を追加する

• 識別例：「X 機能を追加」「Y を実装」「Z の機能を作成」
• 分解方針：領域別に分割する（API、UI、DB、型）
• 並列性：高（ほとんどの作業ストリームは独立）

バグ修正 - 既存の問題を解決する

• 識別例：「X が動作しない問題を修正」「Y のエラーを解決」「Z の動作を修正」
• 分解方針：まず根本原因を特定し、その後、修正を展開する
• 並列性：低（修正の前に診断が必要）

リファクタリング - 動作を変更せずにコード構造を改善する

• 識別例：「X をリファクタリング」「Y を再構成」「Z を抽出」
• 分解方針：まず分析し、その後、ファイル単位で変更する
• 並列性：中（分析は逐次、変更は並列）

統合 - 既存のシステムを接続する

• 識別例：「X を Y と統合」「A を B に接続」
• 分解方針：両方の側を理解し、その後、アダプター層を作成する
• 並列性：中（調査は並列、統合は逐次）

機能強化 - 既存の機能を改善する

• 識別例：「X を改善」「既存の Z に Y を追加」
• 分解方針：現状を理解し、段階的な追加を計画する
• 並列性：中（調査は逐次、追加は並列）

ステップ 2：並列化の機会を特定する

分類した後、並行して実行できる作業を特定します。

独立した領域：

• API ルート + React コンポーネント（契約が事前に定義されている場合）
• 型定義 + データベーススキーマ
• 共通の型を使用する複数の UI コンポーネント
• 共通のミドルウェアを使用する複数の API エンドポイント

独立したファイル：

• 異なるディレクトリへの新規ファイルの作成
• インポート関係のないファイルの編集
• 異なるモジュールのテスト作成

独立した調査：

• 複数のドキュメントソースの確認
• 複数のファイルのパターン分析
• 異なるディレクトリでのパターンの発見

並列化しない場合：

• 型定義は、それを使用する実装より先に作成する必要があります
• データベーススキーマは、API からクエリされる前に作成する必要があります
• 子コンポーネントからインポートされる前に、親コンポーネントが必要です
• 計画を立てる前に、調査を完了する必要があります

ステップ 3：エージェントのタスクを定義する

並列化可能な各作業ストリームについて、次の内容を含むタスクを定義します。

タスクの構成：

task_id: unique-task-identifier
agent: engineer | reviewer | tester | architect | deployer | integrator-ai | integrator-services | integrator-state | planner
skills: [skill-1, skill-2]
description: Brief description of what this task accomplishes
scope:
  files: [list of files to create/modify]
  directories: [directories to work within]
constraints:
  - Must use TypeScript
  - Follow existing patterns in src/features/
blocking: [list of task_ids this task blocks]
blocked_by: [list of task_ids blocking this task]
expected_outcome: What success looks like

例：

task_id: create-user-types
agent: engineer
skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory]
description: Create TypeScript type definitions for User domain
scope:
  files: [src/types/user.ts, src/types/auth.ts]
  directories: [src/types]
constraints:
  - Use Zod for runtime validation
  - Export all types from src/types/index.ts
blocking: [create-user-api, create-user-components]
blocked_by: []
expected_outcome: Type files exist, export User, AuthContext, and validation schemas

ステップ 4：エージェントとスキルを割り当てる

各タスクについて、次の判断表を使って適切なエージェントの種類とスキルを割り当てます。

エージェントの種類の選択：

作業の種類	エージェントの種類	理由
API、コンポーネント、機能の実装	engineer	コードの作成と実装
コード品質、標準のレビュー	reviewer	コード品質と標準の徹底
テスト、テストカバレッジの作成	tester	テストと検証
アーキテクチャの計画、設計上の判断	architect	ハイレベルな設計と計画
アプリケーション、インフラストラクチャのデプロイ	deployer	デプロイとインフラストラクチャ
AI/ML サービスの統合	integrator-ai	AI/ML の統合
外部サービスの統合	integrator-services	外部サービスの統合
状態とデータフローの管理	integrator-state	状態管理
複雑なワークフローの調整	planner	ハイレベルなオーケストレーション

スキルの割り当て：

すべてのエージェントには、デフォルトでプロトコルスキルが付与されます。

• gather-plan-apply（GPA ループ）
• precision-mastery（ツールの使用）
• error-recovery（エラー処理）
• goodvibes-memory（メモリ統合）

作業の種類ごとの追加スキル：

作業の種類	追加スキル
API の実装	trpc, prisma, nextauth, rest-api-design
フロントエンドコンポーネント	react, nextjs, tailwindcss, shadcn-ui
データベーススキーマ	prisma, postgresql, drizzle
認証	clerk, nextauth, lucia
型定義	（なし — プロトコルスキルで十分）
コードレビュー	review-scoring + ドメイン固有のレビュー用スキル

割り当て表の全容については、references/agent-assignment-guide.md を参照してください。

エージェントプロンプトのテンプレート

エージェントを起動する際は、エージェントのプロンプトに必ず次の要素を含めてください。

## Task
[Specific, actionable description of what to accomplish]

## Scope
**Files to create:**
- path/to/file.ts - Brief description

**Files to modify:**
- path/to/existing.ts - What changes to make

**Directories in scope:**
- src/features/auth/ - Work within this directory

## Constraints
- [Technical constraint 1]
- [Pattern to follow]
- [Dependency requirement]

## Skills Available
- skill-name - When to use it
- skill-name - When to use it

## Expected Outcome
[Concrete definition of success]

## Blocking/Blocked By
**This task blocks:** [list of downstream tasks waiting for this]
**This task is blocked by:** [list of upstream tasks this waits for]

重要な要素：

1. 範囲が明確である（曖昧な説明ではなく、ファイルパスを指定する）
2. スキルが使用方法のガイダンスとともに列挙されている
3. 期待される成果が具体的で、検証可能である
4. 出力形式に <gv> タグが含まれている（ランタイムフックによって自動的に出力されるため、オーケストレーターがエージェントに指示する必要はありません）

注： エージェントのプロンプトに WRFC への参加指示を追加しないでください。エージェントは作業を完了し、<gv> タグを出力するだけで十分です。ランタイムエンジンが WRFC チェーンを自動的に処理します。

モニタリングと調整

アクティブなエージェントを追跡する

タスク追跡用の構造を維持します。

active_tasks:
  task-1:
    agent_id: agent_abc123
    status: running | completed | blocked | failed
    started_at: ISO-8601 timestamp
    last_update: ISO-8601 timestamp
    blocking: [task-2, task-3]
    blocked_by: []
  task-2:
    agent_id: agent_def456
    status: waiting
    blocked_by: [task-1]

エージェントの同時実行数の上限

上限：6 個の同時エージェントチェーン（出力スタイル設定の max_parallel_agent_chains による）

「チェーン」には、作業エージェントと、そのエージェントに続く WRFC チェーン全体（レビュー、修正、再レビュー）が含まれます。最初の作業エージェントを起動するたびに、1 つのチェーンが作成されます。個々のエージェントではなく、チェーンを数えてください。

タスクが 6 件を超える場合：

1. 依存関係の順序に従って優先順位を付けます（下流のタスクのブロックを先に解除します）
2. 残りのタスクをキューに入れます
3. ランタイムが complete ディレクティブを出したら、新しいエージェントを起動します（チェーンの完了時）

タスクの優先度の計算式：

priority = (number of tasks it blocks) - (number of tasks blocking it)

優先度が高いものから順に起動します。

<gv> ディレクティブの実行

ランタイムエンジンがディレクティブを発行した場合：

1. すべてを停止します — 他のタスクについて進行中の推論を完了させないでください
2. ディレクティブを読み取ります — action、wid、type、task フィールドを特定します
3. 直ちに実行します：
   • spawn：指定されたエージェントタイプを、提示されたタスクプロンプトで起動します
   • complete：WRFC チェーンを完了としてマークし、依存するタスクのブロックを解除して、空き枠があれば次にキューされたタスクを起動します
   • escalate：エスカレーションの理由をユーザーに報告し、このチェーンのエージェントをそれ以上起動しないでください
4. その後、他のオーケストレーション作業を再開します

例外はありません。 ディレクティブをスキップ、順序変更したり、別のイベントを条件にしたりしてはいけません。

WRFC の起動ルール

1. 初回起動のみ：オーケストレーターは、タスクの分解から得られた初期作業エージェントのみを起動します。レビューエージェントと修正エージェントはすべて、ランタイムディレクティブによって起動されます。
2. 可能な場合は並列実行：同じ依存関係のウェーブにあるタスクはすべて同時に起動します
3. ブロッカーを待機：ブロッキングタスクが complete ディレクティブを受け取るまで、依存するタスクを起動しないでください
4. 上限を守る：同時に実行するチェーンは 6 つを超えないでください
5. エスカレーションへの対応：ランタイムが escalate を発行した場合は、ユーザーに報告してください。自分でチェーンを修正しようとしないでください

エージェント間の連携

エージェント同士は直接連携しません。連携はすべてオーケストレーターを通じて行われます。

エージェント間の依存関係：

• タスク A が types.ts を生成します
• タスク B は types.ts を必要とします
• オーケストレーター：A が complete ディレクティブを受け取るまで待機し、その後 types.ts の場所を示して B を起動します

共有状態：

• すべてのエージェントが .goodvibes/memory/ を読み書きします
• オーケストレーターは、エージェントを起動する前にメモリから決定事項、パターン、失敗例を確認します
• オーケストレーターは、オーケストレーションの決定を .goodvibes/memory/decisions.json に記録します

モード別の動作

Vibecoding モード（デフォルト）

最初の分解前に確認します：

• エージェントを起動する前に、タスクの内訳をユーザーに提示します
• ユーザーが分解内容を変更できるようにします
• ユーザーの確認が必要なのは初回の分解のみです。エージェントの起動後は、ランタイムがプロセスを制御します

曖昧さがある場合は自動起動します：

• タスクの分解に複数の妥当な方法がある場合は、メモリにある最も一般的なパターンを選びます
• パターンがない場合は判断を下し、その決定を decisions.json に記録します
• 認証プロバイダーやデータベースの選択など、アーキテクチャ上の決定が必要な場合にのみ、ユーザーにエスカレーションします

エラー処理：

• エージェントの再試行はランタイムエンジンが管理します（max_fix_attempts まで）
• 最大試行回数に達すると、ランタイムは escalate ディレクティブを発行します
• escalate の場合は、ディレクティブの reason フィールドにあるコンテキストとともにユーザーに提示します

Justvibes モード（厳格）

自動で進めます：

• 分解前の確認を省略します
• 分解が完了したら、エージェントを直ちに起動します
• ランタイムエンジンがすべての WRFC サイクルを自動的に処理します

エラー処理：

• Vibecoding と同じです。ランタイムが修正の試行を管理し、上限に達すると escalate を発行します
• エスカレーションを受け取ったら、ユーザーに提示します

分解例

例 1：機能の実装

ユーザーのリクエスト：「編集機能付きのユーザープロフィールページを追加する」

**分類：**機能の実装

分解：

tasks:
  - task_id: create-profile-types
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory]
    description: Create Profile and ProfileUpdate types
    scope:
      files: [src/types/profile.ts]
    blocking: [create-profile-api, create-profile-ui]
    blocked_by: []
    
  - task_id: create-profile-api
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory, trpc, prisma]
    description: Implement tRPC routes for profile CRUD
    scope:
      files: [src/server/routers/profile.ts]
    blocking: [create-profile-ui]
    blocked_by: [create-profile-types]
    
  - task_id: create-profile-ui
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory, nextjs, react, tailwindcss, shadcn-ui]
    description: Build profile page with edit form
    scope:
      files: [src/app/profile/page.tsx, src/components/ProfileForm.tsx]
    blocking: []
    blocked_by: [create-profile-types]
    
  - task_id: test-profile-feature
    agent: tester
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory]
    description: Create tests for profile feature
    scope:
      files: [src/server/routers/profile.test.ts, src/components/ProfileForm.test.tsx]
    blocking: []
    blocked_by: [create-profile-api, create-profile-ui]

実行計画：

1. create-profile-types を起動します（ブロッカーなし）
2. create-profile-types の complete ディレクティブを待ちます
3. create-profile-api と create-profile-ui を並列で起動します（どちらにもブロッカーなし）
4. 両方の complete ディレクティブを待ちます
5. test-profile-feature を起動します（API と UI によるブロック）
6. test-profile-feature の complete ディレクティブを待ちます
7. 結果をまとめてユーザーに返します

**注：**各エージェントのレビューと修正サイクルは、ディレクティブを介してランタイムエンジンが自動的に処理します。オーケストレーターはこれらのスケジュールを設定しません。

**並列実行：**3 つのウェーブ（types のみ → API と UI を並列実行 → tests のみ）

例 2：バグ修正

ユーザーのリクエスト：「/dashboard のログインリダイレクトループを修正してください」

**分類：**バグ修正

分解：

tasks:
  - task_id: diagnose-redirect-loop
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory, nextjs, nextauth]
    description: Identify root cause of redirect loop
    scope:
      files: [src/middleware.ts, src/app/dashboard/page.tsx, src/lib/auth.ts]
    blocking: [fix-redirect-loop]
    blocked_by: []
    
  - task_id: fix-redirect-loop
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory, nextjs, nextauth]
    description: Apply fix based on diagnosis
    scope:
      files: [determined by diagnosis]
    blocking: []
    blocked_by: [diagnose-redirect-loop]

実行計画：

1. diagnose-redirect-loop を起動する
2. 診断の complete ディレクティブを待つ
3. 診断コンテキストを渡して fix-redirect-loop を起動する
4. 修正の complete ディレクティブを待つ
5. ユーザーに返答する

**並列処理：**なし（完全な逐次処理：診断 -> 修正）

例 3：リファクタリング

ユーザーのリクエスト：「共有の認証ロジックを再利用可能なフックに切り出してください」

**分類：**リファクタリング

分解：

tasks:
  - task_id: plan-refactoring-approach
    agent: architect
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory]
    description: Design the refactoring strategy and hook API
    scope:
      directories: [src/components, src/app]
    blocking: [analyze-auth-patterns]
    blocked_by: []
    
  - task_id: analyze-auth-patterns
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory]
    description: Discover all auth usage patterns in components
    scope:
      directories: [src/components, src/app]
    blocking: [create-auth-hooks]
    blocked_by: [plan-refactoring-approach]
    
  - task_id: create-auth-hooks
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory, react]
    description: Create hooks based on discovered patterns
    scope:
      files: [src/hooks/useAuth.ts, src/hooks/useRequireAuth.ts]
    blocking: [refactor-components-1, refactor-components-2]
    blocked_by: [analyze-auth-patterns]
    
  - task_id: refactor-components-1
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory, react]
    description: Refactor components in src/app to use hooks
    scope:
      directories: [src/app]
    blocking: []
    blocked_by: [create-auth-hooks]
    
  - task_id: refactor-components-2
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory, react]
    description: Refactor components in src/components to use hooks
    scope:
      directories: [src/components]
    blocking: []
    blocked_by: [create-auth-hooks]

実行計画：

1. plan-refactoring-approach（アーキテクト）を起動する
2. 計画の complete ディレクティブを待つ
3. analyze-auth-patterns を起動する
4. 分析の complete ディレクティブを待つ
5. create-auth-hooks を起動する
6. フックの complete ディレクティブを待つ
7. refactor-components-1 と refactor-components-2 を並列で起動する
8. 両方の complete ディレクティブを待つ
9. ユーザーに返答する

**並列処理：**4 つのウェーブ（計画 -> 分析 -> フック -> 2 つのリファクタリングを並列実行）

エスカレーション基準

次の場合は、直ちにユーザーにエスカレーションします。

1. アーキテクチャの曖昧さ - 大きなトレードオフを伴う、複数の妥当なアプローチがある

   • 例：「新しい API に REST と GraphQL のどちらを使うか」
   • エスカレーション：長所と短所を示して選択肢を提示し、判断を求める

2. 情報不足 - ユーザーからの入力なしではタスクを完了できない

   • 例：「どの認証プロバイダーを使うべきか」
   • エスカレーション：選択肢を列挙し、必要な情報を説明する

3. スコープの拡大 - タスクが当初の説明より大きい

   • 例：「プロフィールページの追加には、新しいデータベーススキーマとマイグレーションが必要です」
   • エスカレーション：拡大したスコープを示し、承認を求める

4. ランタイムからのエスカレーション - ランタイムエンジンが escalate ディレクティブを出す

   • 例：作業エージェントで修正試行の上限に達した
   • エスカレーション：ディレクティブの reason を提示し、指示または手動介入を求める

5. 要件の矛盾 - 見つかった制約が互いに矛盾している

   • 例：「ユーザーは Prisma を希望しているが、コードベースでは Drizzle を使用している」
   • エスカレーション：矛盾を説明し、解決を求める

まとめ

タスクのオーケストレーションワークフロー：

1. リクエストを分類する（機能、バグ、リファクタリングなど）
2. 並列化できる機会を特定する（領域、ファイル、調査）
3. エージェントのタスクを定義する（blocking/blocked_by を含むタスク構造）
4. エージェントとスキルを割り当てる（判断表を使用）
5. 構造化されたプロンプトで初期の作業エージェントを起動する
6. アクティブなチェーンを監視する（最大 6 件を同時実行）
7. ランタイムからの <gv> ディレクティブを即座に機械的に実行する
8. すべてのチェーンが complete ディレクティブを受け取ったら、結果を集約する

主な原則：

• 暗黙より明示（曖昧な説明ではなくファイルパスを使う）
• 可能な場合は並列に、必要な場合は逐次に実行する
• オーケストレーターは初期分解を担当し、ランタイムエンジンはすべての WRFC サイクルを担当する
• 他のアクションより先にディレクティブを実行する — 例外なし
• vibecoding では曖昧さをエスカレーションし、justvibes では自動的に進める
• メモリーを活用して判断を支え、失敗の繰り返しを避ける