| name | team-orchestration |
| description | Agent Team を活用した並列レビュー・実装の協調プロトコル。
チーム作成、フォールバック検出、スポーンプロンプト、
インサイトキャプチャ、Progress file 管理を定義する。
Use when:
- spec-review --auto のチームモード実行時
- 複数エージェントの並列レビューでチーム協調が必要な時
Trigger phrases: agent team, team mode, parallel review team
|
| allowed-tools | Read, Write, Glob, Grep, Task, TaskCreate, TaskUpdate, TaskList, TaskGet, SendMessage, TeamCreate, AskUserQuestion |
| model | sonnet |
| user-invocable | false |
Team Orchestration Protocol
Agent Team を活用した並列レビュー・実装の協調プロトコル。
既存の Task tool サブエージェントパターンを基盤とし、Agent Team を enhancement として活用する。
1. Agent Team 検出とフォールバック
検出手順
1. TeamCreate ツールの利用可能性を確認
2. 利用可能 → Agent Team パスで実行
3. 利用不可 → Task tool による並列サブエージェント実行にフォールバック
フォールバック通知テンプレート
Agent Team が利用できない場合、ユーザーに以下を通知:
Agent Team ツールは現在の環境で利用できません。
既存のサブエージェント並列実行モードで続行します。
機能的な差異:
- レビュアー間の相互議論は行われません
- 各レビュアーは独立して結果を返します
- 品質・精度に大きな差はありません
Agent Team が利用可能な場合:
Agent Team モードで実行します。
3名のレビュアーがチームとして相互検証を行います。
2. スポーンプロンプトテンプレート
Phase 1 対象: spec-review --auto の3ロール。
共通 Completion Protocol (L1 - MUST)
全チームメイトのスポーンプロンプトに以下を含める:
## Completion Protocol (L1 - MUST)
リーダーへの報告（SendMessage）前に必ず実行すること:
1. INSIGHT RECORDING: 予期しない発見があれば以下のマーカーを使用:
- PATTERN: [説明] (file:line)
- LEARNED: [説明] (file:line)
- INSIGHT: [説明] (file:line)
2. REFERENCE VERIFICATION: 全ての file:line 参照を Read ツールで
存在確認すること。未検証の参照には [UNVERIFIED] を付与。
3. RESULT FORMAT: subagent-contract フォーマットで報告:
## [ロール名] Result
### Status: SUCCESS / PARTIAL / FAILED
### Summary: [2-3文の要約]
### Findings: [構造化された発見事項]
### Key References: [file:line テーブル]
### Confidence: [0-100] with justification
security-auditor（概要）
- ツール制限 (L1): Write/Edit 禁止、Bash は読み取り専用監査コマンドのみ
- 分析対象: OWASP Top 10、認証/認可、入力バリデーション、データ露出
- チーム連携: qa-engineer とテスト可能性を相互確認、重大脆弱性はリーダーに即報告
- 完全なスポーンプロンプトは reference.md を参照
qa-engineer（概要）
- ツール制限 (L1): 全標準ツール利用可能（Write/Edit/Bash 含む）
- 分析対象: テストカバレッジギャップ、エッジケース、受入基準の検証可能性
- チーム連携: security-auditor の指摘のテスト可能性評価、品質ゲートをリーダーに報告
- 完全なスポーンプロンプトは reference.md を参照
system-architect（概要）
- ツール制限 (L1): Write/Edit/Bash 全て禁止、Read/Glob/Grep のみ
- 分析対象: アーキテクチャ整合性、スケーラビリティ、技術的負債の影響
- チーム連携: security-auditor の提案の技術的妥当性検証、実現可能性の懸念をリーダーに報告
- 完全なスポーンプロンプトは reference.md を参照
3. インサイトキャプチャプロトコル（リーダー側）
チームメイトの SendMessage からインサイトマーカーを抽出し保存する。
抽出手順
1. チームメイトの SendMessage を受信
2. PATTERN/LEARNED/INSIGHT/DECISION/ANTIPATTERN マーカーを検索
3. 各マーカーに対して:
a. 一意の insight ID を生成 (INS-YYYYMMDDHHMMSS-xxxxxxxx)
b. .claude/workspaces/{id}/insights/pending/ に JSON を書き出し:
{
"id": "INS-20260211-001",
"timestamp": "ISO-8601",
"category": "pattern|learned|insight|decision|antipattern",
"content": "[マーカーの内容]",
"source": "team-member-[role]",
"status": "pending",
"workspaceId": "[workspace-id]"
}
c. Write ツールで直接書き出す（Bash でスクリプト呼び出しはしない）
検証の連携
confidence >= 85 かつ参照の相互検証が必要な場合:
- verification-specialist をサブエージェント（Task tool）として起動
- SubagentStop hooks が自動発火し verify_references.py が参照を検証
4. Progress File Single Writer プロトコル
フロー
チームメイト リーダー ファイルシステム
| | |
|-- SendMessage --->| |
| "タスク開始" |-- Write ------------>|
| | claude-progress.json |
|-- SendMessage --->| |
| "発見事項報告" |-- Write ------------>|
| | insights/pending/ |
| |-- Write ------------>|
| | claude-progress.json |
teamContext フィールド（informational only）
claude-progress.json に追加するオプショナルフィールド:
{
"teamContext": {
"mode": "agent-team",
"startedAt": "ISO-8601"
}
}
- オプショナル: 非チームセッションでは省略
- informational only: resume や recovery には使用しない
- 既存フィールド (currentPhase, currentTask, log) はリーダーが従来通り更新
チーム内タスク管理との分離
| 管理対象 | ツール | 永続性 |
|---|
| チーム内タスク | TaskCreate/Update/List | チーム存続期間のみ |
| セッション横断進捗 | claude-progress.json | プロジェクト全体 |
| 実装タスクリスト | feature-list.json | spec-implement 全期間 |
5. AskUserQuestion 中継フロー
ユーザー対話プロトコル (L1)
チームメイトはユーザーと直接対話できない。以下のフローで中継する:
チームメイト: SendMessage → リーダー
"ユーザーに確認が必要: [質問内容]"
リーダー: AskUserQuestion → ユーザー
"[チームメイト名]からの確認事項: [質問内容]"
ユーザー: 回答
リーダー: SendMessage → チームメイト
"ユーザーからの回答: [回答内容]"
6. サーキットブレイカー（3段階判断モデル）
チームメイト障害時の判断を TeammateIdle イベント中心で行い、LLM の時間認識への依存を最小化する。
個別障害（1体無応答）- 3段階判断:
一次: TeammateIdle イベント受信を契機にタイムアウト判断
- 中間報告（SendMessage）受信済み → 正常完了の可能性あり、結果待機を継続
- 中間報告なし → ハングと判断、同ロールのサブエージェントを代替スポーン
二次: フォールバック固定タイムアウト（TeammateIdle 未受信の異常系）
- security-auditor: 7分、qa-engineer: 5分、system-architect: 5分
- 上限キャップ: 全ロール共通10分
→ 元チームメイトに shutdown_request
→ 残2体のチームはそのまま継続（2体でも相互検証は成立）
チーム障害（2体以上無応答）:
→ 全チームメイトに shutdown_request
→ 従来パターン（5体サブエージェント）にフォールバック
→ ログに team-fallback-full を記録
※ 1体のみ残存ではチーム協調の価値がないため全体ブレイク
API エラー（TeamCreate/SendMessage 失敗）:
→ 即時ブレイク → 従来パターンで実行
→ 同一セッション内はチームモードを再試行しない（open 状態維持）
3段階判断の根拠
- 一次（TeammateIdle）: ツール呼び出し有無をシステムレベルで検知する正確なシグナル。LLMの時間認識に依存しない
- 二次（固定タイムアウト）: TeammateIdle が来ない異常ケースのフォールバック。security-auditor は OWASP 全項目横断+相互検証で実作業中央値6分のため7分、qa-engineer/system-architect はフロア値3分の約1.7倍で5分
- 中間報告義務: チームメイトのスポーンプロンプトに中間報告（作業開始+主要発見）の送信を義務付け、リーダーの判断精度を向上
Rules (L1 - Hard)
Agent Team 運用の安全性と一貫性のために必須。
- MUST: TeamCreate 前に利用可能性を確認し、利用不可なら Task tool にフォールバック
- MUST: リーダーのみが claude-progress.json / feature-list.json に書き込む
- MUST: チームメイトはユーザーとの対話を SendMessage 経由でリーダーに中継
- MUST: 全チームメイトに Completion Protocol を含むスポーンプロンプトを使用
- MUST: チームメイト無応答時は3段階判断（TeammateIdle+中間報告→固定タイムアウト security-auditor: 7分/他: 5分→上限10分）で代替サブエージェントをスポーン
- NEVER: チームメイトが直接 AskUserQuestion を呼び出す
- NEVER: チームメイトが progress/feature ファイルに直接書き込む
- NEVER: リーダーがコード実装・テスト・セキュリティ分析を自分で行う（既存 orchestrator ルール）
- ALWAYS: Agent Team 利用不可時もユーザーへの通知を省略しない
Defaults (L2 - Soft)
品質向上のための推奨事項。合理的な理由があれば変更可。
- チームメイト間の相互検証を促進する（security-auditor と qa-engineer の発見を相互参照）
- インサイトマーカーの抽出はリーダーが Write ツールで直接行う
- チームメイト数は初期段階では最大3名に制限
- verification-specialist は SubagentStop hooks 活用のため Task tool で起動
Guidelines (L3)
状況に応じて判断する推奨事項。
- prefer: 長時間実行のチームメイトよりも短期タスク型を推奨（Context Rot 防止）
- consider: チームメイト間の議論が発生しない場合は Task tool フォールバックを検討
- consider: TeammateIdle hook が正常動作する場合は Layer 2 自動化として活用
