team

チームスキル

Claude Code の暗黙的なエージェントチームを使用して、N 人の連携するエージェントを起動し、共有タスクリストに取り組ませます。Claude Code 2.1.178+ ではネイティブの TeamCreate／TeamDelete が削除されました。CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 を設定すると、各セッションに暗黙的なチームが 1 つ割り当てられ、Agent／Task ツールを使って異なる name 値を指定し、チームメイトを直接起動できます。このスキルでは、文書化されている OMC の従来型 tmux／CLI ワーカーオーケストレーション（omc team／/omc-teams）も引き続き利用できます。暗黙的なチームと omc team は結果を共有しません。一方が完了しても、もう一方の成功にはなりません。

swarm 互換エイリアスは #1131 で削除されました。

使用方法

/oh-my-claudecode:team N:agent-type "task description"
/oh-my-claudecode:team "task description"
/oh-my-claudecode:team ralph "task description"

パラメーター

• N - チームメイトとなるエージェントの数（1～20）です。省略可能です。デフォルトでは、タスクの分解に基づいて自動的に決定されます。
• agent-type - team-exec ステージで起動する OMC エージェントです（例：executor、debugger、designer、codex、gemini、antigravity）。省略可能です。デフォルトでは、ステージに応じてルーティングされます。Codex CLI ワーカーを起動するには codex、Gemini CLI ワーカー（エンタープライズ／API キーのティア）には gemini、Antigravity CLI（agy）ワーカーには antigravity を使用します（Antigravity は Gemini CLI の後継であり、それぞれの CLI のインストールが必要です）。「ステージエージェントのルーティング」を参照してください。
• task - 分解してチームメイトに割り振る、高レベルのタスクです。
• ralph - 省略可能な修飾子です。指定すると、Ralph の永続化ループ（失敗時の再試行、完了前のアーキテクトによる検証）でチームのパイプラインをラップします。「Team と Ralph の組み合わせ」を参照してください。

例

/team 5:executor "fix all TypeScript errors across the project"
/team 3:debugger "fix build errors in src/"
/team 4:designer "implement responsive layouts for all page components"
/team "refactor the auth module with security review"
/team ralph "build a complete REST API for user management"
# With Codex CLI workers (requires: npm install -g @openai/codex)
/team 2:codex "review architecture and suggest improvements"
# With Gemini CLI workers (requires: npm install -g @google/gemini-cli)
/team 2:gemini "redesign the UI components"
# With Antigravity CLI workers (requires: install per https://antigravity.google)
/team 2:antigravity "redesign the UI components"
# Mixed: Codex for backend analysis, Gemini/Antigravity for frontend (delegate per-task with /oh-my-claudecode:ask)

アーキテクチャ

User: "/team 3:executor fix all TypeScript errors"
              |
              v
      [TEAM ORCHESTRATOR (Lead)]
              |
              +-- Use the session's implicit Claude Code team
              |       -> no TeamCreate call; lead remains current session
              |
              +-- Analyze & decompose task into subtasks
              |       -> explore/architect produces subtask list
              |
              +-- Create task list entries from the implementation plan
              |       -> TODO/task entries #1, #2, #3 with dependencies
              |
              +-- Update task-list entries (pre-assign owners)
              |       -> task #1 owner=worker-1, etc.
              |
              +-- Task(name="worker-1") x 3
              |       -> spawns teammates into the team
              |
              +-- Monitor loop
              |       <- teammate messages (auto-delivered by the active team surface)
              |       -> task-list/TodoWrite review for progress
              |       -> message teammates through the active team surface to unblock/coordinate
              |
              +-- Completion
                      -> request shutdown from each teammate through the active team surface
                      <- shutdown acknowledgement from teammates
                      -> state_clear(mode="team", session_id="<current_session_id>")
                      -> preserve shared/legacy state for explicit --all cleanup

ネイティブ Claude Code チームモデル（2.1.178+）：

- No per-team ~/.claude/teams/<name>/ directory is created by this skill.
- No TeamCreate/TeamDelete calls are available.
- `team_name` is accepted by native Claude Code only as ignored legacy metadata; do not rely on it for routing.
- Spawn teammates directly via Agent/Task with `name="worker-N"`.

Goal ワークフローとの関係

Team は、並列かつ段階的な実行における OMC の権限元です。非決定的な警告処理ではなく、決定論的な競合ポリシー refuse、adopt_existing、artifact_only を使用してください。タスクに Claude Code の /goal、Ralph、またはアーティファクトのみの Ultragoal が含まれている場合、リーダーが明示的に引き継ぎを指示しない限り、Team を主要なループの権限元としてください。/goal は、文書化されたネイティブ Claude Code の引き継ぎ先、またはリードセッションから確認できる証拠としてのみ使用してください。/goal の評価機能が独自にコマンドを実行したり、ファイルを読み取ったり、team-verify／team-fix を置き換えたりすると主張してはいけません。アーティファクトのみの Ultragoal に関する記述は、それ自体がワーカーの実行を意味するものではなく、永続的なゴール台帳／チェックポイント／証拠のアーティファクトとして扱ってください。

段階的パイプライン（正規のチームランタイム）

チームの実行は、次の段階的なパイプラインに従います。

team-plan -> team-prd -> team-exec -> team-verify -> team-fix (loop)

ステージ別エージェントの割り当て

各パイプラインステージでは、単なる実行担当者ではなく、専門エージェントを使用します。リードが、ステージとタスクの特性に基づいてエージェントを選択します。

ステージ	必須エージェント	任意エージェント	選択基準
team-plan	explore (haiku), planner (opus)	analyst (opus), architect (opus)	要件が不明確な場合は analyst を使用します。境界が複雑なシステムには architect を使用します。
team-prd	analyst (opus)	critic (opus)	スコープを検証するには critic を使用します。
team-exec	executor (sonnet)	executor (opus), debugger (sonnet), designer (sonnet), writer (haiku), test-engineer (sonnet)	サブタスクの種類に応じてエージェントを選びます。複雑で自律的な作業には executor (model=opus)、UI 作業には designer、コンパイルの問題には debugger、ドキュメント作成には writer、テスト作成には test-engineer を使用します。
team-verify	verifier (sonnet)	test-engineer (sonnet), security-reviewer (sonnet), code-reviewer (opus)	必ず verifier を実行します。認証／暗号化の変更には security-reviewer を追加します。ファイル数が 20 を超える場合、またはアーキテクチャに関わる変更には code-reviewer を追加します。code-reviewer はスタイル／フォーマットのチェックも担当します。
team-fix	executor (sonnet)	debugger (sonnet), executor (opus)	型やビルドのエラー、リグレッションの切り分けには debugger を使用します。複雑で複数ファイルにまたがる修正には executor (model=opus) を使用します。

割り当てルール：

1. 各ステージのエージェントを選ぶのはリードであり、ユーザーではありません。 ユーザーの N:agent-type パラメーターが上書きするのは team-exec ステージのワーカータイプのみです。それ以外のステージでは、各ステージに適した専門エージェントを使用します。
2. 専門エージェントは実行エージェントを補完します。 分析／レビューは architect／critic の Claude エージェントに、UI 作業は designer エージェントに割り当てます。Tmux CLI ワーカーは Claude のネイティブなチームメッセージングには参加しません。
3. コストモードはモデルのティアに影響します。 ダウングレード時は、品質を維持できる範囲で opus エージェントを sonnet に、sonnet を haiku に変更します。team-verify では常に少なくとも sonnet を使用します。
4. リスクレベルに応じてレビューを強化します。 セキュリティ上重要な変更、または 20 ファイルを超える変更では、team-verify に security-reviewer と code-reviewer (opus) を含める必要があります。

ステージの開始・終了条件

• team-plan
  • 開始条件：チーム呼び出しが解析され、オーケストレーションが開始します。
  • エージェント：explore がコードベースをスキャンし、planner がタスクグラフを作成します。複雑なタスクでは、必要に応じて analyst／architect も参加します。
  • 終了条件：分解が完了し、実行可能なタスクグラフが準備されます。
• team-prd
  • 開始条件：スコープが曖昧、または受け入れ基準が不足しています。
  • エージェント：analyst が要件を抽出し、必要に応じて critic も参加します。
  • 終了条件：受け入れ基準と境界が明確になります。
• team-exec
  • 開始条件：タスクリストの割り当てとワーカーの起動が完了しています。
  • エージェント：各サブタスクに応じた適切な専門家タイプのワーカーを起動します（ルーティング表を参照）。
  • 終了条件：今回の実行パスにおける実行タスクが終端状態に到達します。
• team-verify
  • 開始条件：実行パスが完了します。
  • エージェント：verifier と、タスクに適したレビュアー（ルーティング表を参照）。
  • 終了条件（成功）：必須のフォローアップなしで検証ゲートを通過します。
  • 終了条件（失敗）：修正タスクが生成され、制御が team-fix に移ります。
• team-fix
  • 開始条件：検証で欠陥／リグレッション／未達の基準が見つかります。
  • エージェント：欠陥の種類に応じて executor／debugger が対応します。
  • 終了条件：修正が完了し、フローが team-exec に戻ってから team-verify に進みます。

検証・修正ループと停止条件

次のいずれかに該当するまで、team-exec -> team-verify -> team-fix を続けます。

1. 検証に合格し、必須の修正タスクが残っていない、または
2. 証拠を伴う明示的な終端のブロック／失敗状態に到達する。

team-fix の試行回数には上限があります。修正の試行回数が設定された上限を超えた場合、終端状態の failed に遷移します（無限ループにはなりません）。

実行終了時の処理（いずれの終端状態でも）。 /oh-my-claudecode:cancel による状態のクリーンアップの前に、.omc/notepads/team/problems.md に事実に基づく記述を最大3行追加します（ブロッカーは .omc/notepads/team/issues.md にも記載します）。何が壊れたか（修正ラウンド後も残った欠陥、3回失敗による停止）、何が遅延を招いたか（ワーカー環境の摩擦、不足しているチェック、アクセスできない情報）を記録します。既存の記述は保持してください。追記のみとし、共有ファイルを置き換えてはいけません。記録事項がなければ何も追記しません。終了時に何も書かないのは有効です。「学びはありません」とは書かないでください。記録するのは観察事項のみです。それをリポジトリ上の成果物に反映するのは refit の役割であり、ユーザーの承認が必要です。終端状態が failed の場合は、失敗の特徴、証拠への参照、再開手順を含むインシデント作業項目も作成し、ローカルの .omc/notepads/team/issues.md に追記します。トラッカーへの登録は、ユーザーまたはモードの呼び出しでその外部アクションが明示的に許可されている場合に限ります。

ステージ間の引き継ぎ規約

ステージ間の遷移時には、決定事項、却下した代替案、特定したリスクなどの重要なコンテキストが、リードの会話履歴にのみ残ります。リードのコンテキストが圧縮されたり、エージェントが再起動されたりすると、こうした知識は失われます。

完了する各ステージは、遷移前に必ず引き継ぎドキュメントを作成する必要があります。

リードは .omc/handoffs/<stage-name>.md に引き継ぎ内容を書き込みます。

引き継ぎフォーマット

## Handoff: <current-stage> → <next-stage>

- **Decided**: [key decisions made in this stage]
- **Rejected**: [alternatives considered and why they were rejected]
- **Risks**: [identified risks for the next stage]
- **Files**: [key files created or modified]
- **Remaining**: [items left for the next stage to handle]

引き継ぎルール

1. リードは、次のステージのエージェントを起動する前に、前の引き継ぎ内容を読みます。 エージェントが完全なコンテキストを持って開始できるよう、引き継ぎ内容を次のステージのエージェント起動プロンプトに含めます。
2. 引き継ぎ内容は累積されます。 verify ステージでは、決定の履歴をすべて把握するために、それ以前のすべての引き継ぎ（plan → prd → exec）を参照できます。
3. チームのキャンセル後も、引き継ぎ内容は保持されます。 セッションを再開するために .omc/handoffs/ に残ります。Claude Code のネイティブなチームクリーンアップでは削除されません。Claude Code 2.1.178+ には TeamDelete 呼び出しが存在しません。
4. 引き継ぎ内容は簡潔にします。 最大10～20行です。仕様全体（それらは DESIGN.md などの成果物ファイルにあります）ではなく、決定事項とその理由を記録します。

例

## Handoff: team-plan → team-exec

- **Decided**: Microservice architecture with 3 services (auth, api, worker). PostgreSQL for persistence. JWT for auth tokens.
- **Rejected**: Monolith (scaling concerns), MongoDB (team expertise is SQL), session cookies (API-first design).
- **Risks**: Worker service needs Redis for job queue — not yet provisioned. Auth service has no rate limiting in initial design.
- **Files**: DESIGN.md, TEST_STRATEGY.md
- **Remaining**: Database migration scripts, CI/CD pipeline config, Redis provisioning.

再開とキャンセルの仕様

• 再開: 保存済みのステージ状態とライブのタスクステータスを使い、最後の非終端ステージから再開します。.omc/handoffs/ を読み取り、ステージ遷移のコンテキストを復元します。
• キャンセル: 正式なフローは skills/cancel/SKILL.md を使用してください。フラグ、スコープ、状態クリーンアップのルールはここに重複して記載しないでください。.omc/handoffs/ のハンドオフファイルは、再開のために保持されます。
• 終端状態は complete、failed、cancelled です。

Windows の psmux (tmux 互換) ゲート

ネイティブ Windows では、実際の tmux 互換バイナリを確認するまで、/team に WSL が必要であることや、tmux が利用できないことをユーザーに伝えないでください。ネイティブの psmux は tmux 互換コマンド（多くの場合 tmux / tmux.cmd）をインストールし、サポートされている Team のマルチプレクサーです。

Windows でブロックしたり、フォールバックしたりする前に、次を行ってください。

1. tmux -V を確認します（または where tmux に続けて tmux -V を実行するなど、プラットフォームに応じた同等の方法を使用します）。
2. psmux を介した tmux -V が成功した場合は、tmux が利用可能とみなします。
3. psmux/tmux が利用可能であれば、通常の Team フローを続行します。WSL が必要であるという案内は出力しないでください。
4. tmux 互換バイナリが利用できない場合にのみ、ネイティブ Windows をサポートするために psmux をインストールするか、代替手段として WSL2 を使用するようユーザーに伝えてください。

ワークフロー

再開チェック（初期化の前）

Team の状態に触れる前に、呼び出しコンテキストから現在のセッション ID を特定してください。CLI のコンテキストでは OMC_SESSION_ID が正となり、フックのコンテキストではペイロードの session_id が正となります。ID が利用可能な場合は、それを明示的かつ一貫して渡してください。

state_read(mode="team", session_id="<current_session_id>")

session_id を指定しない state_read は、レガシーまたは集約された状態を読み取り、他のセッションを含む可能性があります。集約レスポンスから、スコープが指定されていない Team を選択したり再開したりしないでください。利用可能な ID がない場合は、明示的に識別されたレガシー状態のみを使用し、集約レスポンス内のセッションエントリから所有者を推測しないでください。

slug の導出、作業の分解、状態の書き込みや初期化を行う前に、既存のセッション状態を読み取ってください。active=true かつ current_phase が非終端である場合は、その Team の既存のハンドオフとタスクリストの状態を使用して、記録されたステージを再開してください。team_name、current_phase、fix_loop_count、max_fix_loops、stage_history、ならびにワーカー・タスク・起動試行の記録を含む、既存の Team 状態のフィールドはすべて保持してください。以降のすべての state_write と state_clear では同じ session_id を使用し、既存の状態ロックの下で部分的な更新のみを適用してください。以下の新規 Team の初期化は実行しないでください。代替の slug を導出したり、重複したタスクを作成したり、重複したワーカーを起動したり、起動試行を繰り返したりしないでください。

状態が不正、読み取り不能、またはその他の理由で破損している場合は、診断情報を報告し、元のバイト列を保持してください。置き換え、クリア、初期化、または新しい実行として扱わないでください。

以下の初期化フェーズは、アクティブでもスコープ付きでもない状態しか存在しない新規の実行にのみ適用されます。

フェーズ 1: 入力の解析

• N（エージェント数）を抽出し、1〜20 の範囲で検証します
• agent-type を抽出し、既知の OMC サブエージェントに対応していることを検証します
• task の説明を抽出します

フェーズ 2: 分析と分解

explore または architect（MCP またはエージェント経由）を使用してコードベースを分析し、タスクを N 個のサブタスクに分解します。

• 競合を避けるため、各サブタスクはファイル単位またはモジュール単位のスコープにしてください
• サブタスクは互いに独立しているか、明確な依存順序を持つ必要があります
• 各サブタスクには、簡潔な subject と詳細な description が必要です
• サブタスク間の依存関係を特定してください（例:「共有型は、利用側より先に確定している必要がある」）

フェーズ 3：チームの状態を初期化する

セッションに暗黙的に割り当てられた Claude Code チームを使用します。TeamCreate は呼び出さないでください。Claude Code 2.1.178+ ではこのツールが削除されており、CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 が有効な場合、セッションには暗黙的なチームが自動的に割り当てられます。

OMC の状態、プロンプトラベル、引き継ぎ、人が読むためのレポートにのみ、fix-ts-errors のようなスラッグを生成します。ネイティブの Claude Code では、レガシーメタデータとして team_name を受け付ける場合がありますが、ルーティングには無視されます。

セッションスコープで適切に永続化するため、state_write MCP ツールを使用して OMC の状態を書き込みます。

これ以降のすべての Team 状態呼び出しでは、Resume Check と同じ解決済みの session_id を使用してください。ID が利用できない場合は、上記で明示的に示したレガシー状態のみを使用してください。

state_write(mode="team", session_id="<current_session_id>", active=true, current_phase="team-plan", state={
  "team_name": "fix-ts-errors",
  "agent_count": 3,
  "agent_types": "executor",
  "task": "fix all TypeScript errors",
  "fix_loop_count": 0,
  "max_fix_loops": 3,
  "linked_ralph": false,
  "stage_history": "team-plan"
})

注： MCP の state_write ツールでは、すべての値が文字列として送信されます。状態を読み取る際、利用側は agent_count、fix_loop_count、max_fix_loops を数値に、linked_ralph をブール値に変換する必要があります。

状態スキーマのフィールド：

フィールド	型	説明
active	boolean	チームモードがアクティブかどうか
current_phase	string	現在のパイプライン段階：team-plan、team-prd、team-exec、team-verify、team-fix
team_name	string	状態、引き継ぎ、レポートに使用する OMC スラッグ。ネイティブの Claude Code のルーティングでは無視されます
agent_count	number	ワーカーエージェントの数
agent_types	string	team-exec で使用するエージェントタイプをカンマ区切りで指定した値
task	string	元のタスクの説明
fix_loop_count	number	現在の修正反復回数
max_fix_loops	number	失敗と判定されるまでの最大修正反復回数（デフォルト：3）
linked_ralph	boolean	チームが ralph の永続化ループにリンクされているかどうか
stage_history	string	タイムスタンプ付きの段階遷移履歴をカンマ区切りで指定した値

段階が遷移するたびに状態を更新します：

state_write(mode="team", session_id="<current_session_id>", current_phase="team-exec", state={
  "stage_history": "team-plan:2026-02-07T12:00:00Z,team-prd:2026-02-07T12:01:00Z,team-exec:2026-02-07T12:02:00Z"
})

フェーズ 4：タスクを作成する

TodoWrite またはアクティブなタスクリストの画面を使用して、各サブタスクのタスクリスト項目を作成します。タスクリストツールは追跡専用であり、ネイティブのチームを作成するものではありません。

// Task-list entry for subtask 1
{
  "subject": "Fix type errors in src/auth/",
  "description": "Fix all TypeScript errors in src/auth/login.ts, src/auth/session.ts, and src/auth/types.ts. Run tsc --noEmit to verify.",
  "activeForm": "Fixing auth type errors"
}

応答にタスクファイル（例：1.json）が格納されます：

{
  "id": "1",
  "subject": "Fix type errors in src/auth/",
  "description": "Fix all TypeScript errors in src/auth/login.ts...",
  "activeForm": "Fixing auth type errors",
  "owner": "",
  "status": "pending",
  "blocks": [],
  "blockedBy": []
}

依存関係のあるタスクについては、作成後にアクティブなタスクリスト項目を更新します：

// Task #3 depends on task #1 (shared types must be fixed first)
{
  "taskId": "3",
  "addBlockedBy": ["1"]
}

競合状態を避けるため、リードが事前に担当者を割り当てます（アトミックなタスク取得はありません）：

// Assign task #1 to worker-1
{
  "taskId": "1",
  "owner": "worker-1"
}

フェーズ 5：チームメイトを起動する

Agent/Task ツールを使用し、異なる name 値を指定して N 人のチームメイトを直接起動します。各チームメイトには、チームワーカー用の前置き（後述）と個別の担当内容を渡します。TeamCreate は呼び出さず、team_name にも依存しないでください。Claude Code 2.1.178+ では、ネイティブのルーティングにおいてこれが無視されます。

{
  "subagent_type": "oh-my-claudecode:executor",
  "name": "worker-1",
  "prompt": "<worker-preamble + assigned tasks>"
}

応答：

{
  "agent_id": "worker-1",
  "name": "worker-1"
}

副作用：

• チームメイトがセッションの暗黙的な Claude Code チームに起動されます
• エージェントのライフサイクルを追跡する内部タスクが自動的に作成されます（metadata._internal: true）
• 内部タスクがタスクリストの出力に表示される場合があります。実際のタスク数を数える際は除外してください

重要： すべてのチームメイトを並行して起動してください（チームメイトはバックグラウンドエージェントです）。次のチームメイトを起動する前に、先に起動したチームメイトの完了を待たないでください。

フェーズ 6：監視

リードオーケストレーターは、次の 2 つのチャネルを通じて進捗を監視します。

1. 受信メッセージ -- タスクを完了したときや、支援が必要なとき、チームメイトは team-lead にメッセージを送ります。これらは、アクティブなチーム／会話の画面を通じて届きます。

2. タスクリストのポーリング／確認 -- TodoWrite またはアクティブなタスクリストの画面を定期的に確認し、全体の進捗を把握します。

   #1 [completed] Fix type errors in src/auth/ (worker-1)
   #3 [in_progress] Fix type errors in src/api/ (worker-2)
   #5 [pending] Fix type errors in src/utils/ (worker-3)
   

   形式：#ID [status] subject (owner)

リードが実行できる調整アクション：

• チームメイトのブロックを解除する： アクティブなチーム画面を通じて、ガイダンスや不足しているコンテキストをメッセージで送信します
• 作業を再割り当てする： チームメイトが早く作業を終えた場合、タスクリストの項目を更新して保留中の作業を割り当て、アクティブなチーム画面を通じて通知します
• 失敗に対処する： チームメイトから失敗の報告があった場合、タスクを再割り当てするか、代わりのメンバーを起動します

タスクの監視ポリシー

停止中または失敗したチームメイトを監視します。

• 進行中タスクの最長時間： タスクが in_progress のままメッセージなしで 5 分を超えた場合、状況を確認します
• ワーカー停止の疑い： メッセージがなく、タスクが 10 分以上停止している場合 → 別のワーカーにタスクを再割り当てします
• 再割り当てのしきい値： ワーカーが 2 件以上のタスクに失敗した場合、そのワーカーに新しいタスクを割り当てるのをやめます

フェーズ 6.5：ステージの移行（状態の永続化）

ステージが移行するたびに、OMC の状態を更新します。

// Entering team-exec after planning
state_write(mode="team", session_id="<current_session_id>", current_phase="team-exec", state={
  "stage_history": "team-plan:T1,team-prd:T2,team-exec:T3"
})

// Entering team-verify after execution
state_write(mode="team", session_id="<current_session_id>", current_phase="team-verify")

// Entering team-fix after verify failure
state_write(mode="team", session_id="<current_session_id>", current_phase="team-fix", state={
  "fix_loop_count": 1
})

これにより、次のことが可能になります。

• 再開： リードがクラッシュした場合、state_read(mode="team", session_id="<current_session_id>") で最後のステージとチーム名を確認して復旧できます
• キャンセル： キャンセルスキルは current_phase を読み取り、必要なクリーンアップを判断します
• Ralph との連携： Ralph はチームの状態を読み取り、パイプラインが完了したか失敗したかを確認できます

フェーズ 7：完了

すべての実タスク（内部タスク以外）が完了または失敗したら、次の手順を実行します。

1. 結果を確認する -- TodoWrite またはアクティブなタスクリストの画面で、すべての実タスク（内部タスク以外）が completed としてマークされていることを確認します
2. チームメイトをシャットダウンする -- アクティブなチーム画面を通じて、各アクティブなチームメイトに shutdown_request を送信します。

   {
     "type": "shutdown_request",
     "recipient": "worker-1",
     "content": "All work complete, shutting down team"
   }
   

3. 応答を待つ -- 各チームメイトは shutdown_response(approve: true) で応答し、終了します
4. クリーンアップする -- 正常なシャットダウン処理の後、選択したセッションとリンクされた Ralph に対して、 skills/cancel/SKILL.md の Team フローに従います。 ネイティブの Claude Code 2.1.178+ には TeamDelete がありません。
5. 概要を報告する -- ユーザーに結果を提示します

エージェントの前置き

チームメイトを起動する際は、作業プロトコルを確立するため、この前置きをプロンプトに含めます。各チームメイトの具体的なタスクに合わせて調整してください。

You are a TEAM WORKER in OMC team "{team_name}". Your name is "{worker_name}".
You report to the team lead ("team-lead").
You are not the leader and must not perform leader orchestration actions.

== WORK PROTOCOL ==

1. CLAIM: Check TodoWrite or the active task-list surface for tasks assigned to you (owner = "{worker_name}").
   Pick the first task with status "pending" that is assigned to you.
   Mark it `in_progress` using the active task-list surface:
   {"taskId": "ID", "status": "in_progress", "owner": "{worker_name}"}

2. WORK: Execute the task using your tools (Read, Write, Edit, Bash).
   Do NOT spawn sub-agents. Do NOT delegate. Work directly.

3. COMPLETE: When done, mark the task completed:
   {"taskId": "ID", "status": "completed"}

4. REPORT: Notify the lead through the active team/conversation surface:
   {"type": "message", "recipient": "team-lead", "content": "Completed task #ID: <summary of what was done>", "summary": "Task #ID complete"}

5. NEXT: Check TodoWrite or the active task-list surface for more assigned tasks. If you have more pending tasks, go to step 1.
   If no more tasks are assigned to you, notify the lead through the active team/conversation surface:
   {"type": "message", "recipient": "team-lead", "content": "All assigned tasks complete. Standing by.", "summary": "All tasks done, standing by"}

6. SHUTDOWN: When you receive a shutdown_request, respond with:
   {"type": "shutdown_response", "request_id": "<from the request>", "approve": true}

== BLOCKED TASKS ==
If a task has blockedBy dependencies, skip it until those tasks are completed.
Check TodoWrite or the active task-list surface periodically to see if blockers have been resolved.

== ERRORS ==
If you cannot complete a task, report the failure to the lead:
{"type": "message", "recipient": "team-lead", "content": "FAILED task #ID: <reason>", "summary": "Task #ID failed"}
Do NOT mark the task as completed. Leave it in_progress so the lead can reassign.

== RULES ==
- NEVER spawn sub-agents or use the Task tool
- NEVER run tmux pane/session orchestration commands (for example `tmux split-window`, `tmux new-session`)
- NEVER run team spawning/orchestration skills or commands (for example `$team`, `$autopilot`, `$ralph`, `omc team ...`, `omx team ...`)
- ALWAYS use absolute file paths
- ALWAYS report progress to "team-lead" through the active team/conversation surface
- Use direct team/conversation messages with type "message" only -- never "broadcast"

エージェントタイプ別のプロンプト追加事項（ワーカー固有）

チームメイトのプロンプトを作成する際は、ワーカーのタイプに応じた短い追加事項を付け加えます。

• claude_worker：TodoWrite／タスクリストの厳密な更新、アクティブなチーム／会話でのメッセージ、およびオーケストレーションコマンドを使用しないことを強調します。
• codex_worker：CLI API のライフサイクル（omc team api ... --json）と、stderr を含む明示的な失敗 ACK を強調します。
• gemini_worker：担当ファイルの範囲を限定すること、および完了した各サブステップの後にマイルストーン ACK を送ることを強調します。
• antigravity_worker：gemini_worker と同じ要件を適用し、担当ファイルの範囲を限定すること、および完了した各サブステップの後にマイルストーン ACK を送ることを強調します。

この追加事項によって、次の基本ルールが損なわれないようにします。ワーカーは実行役のみであり、リーダー／オーケストレーターにはなりません。

コミュニケーションパターン

チームメイトからリードへ（タスク完了の報告）

{
  "type": "message",
  "recipient": "team-lead",
  "content": "Completed task #1: Fixed 3 type errors in src/auth/login.ts and 2 in src/auth/session.ts. All files pass tsc --noEmit.",
  "summary": "Task #1 complete"
}

リードからチームメイトへ（再割り当てまたはガイダンス）

{
  "type": "message",
  "recipient": "worker-2",
  "content": "Task #3 is now unblocked. Also pick up task #5 which was originally assigned to worker-1.",
  "summary": "New task assignment"
}

一斉送信（控えめに使用してください -- N 件の個別メッセージを送信します）

{
  "type": "broadcast",
  "content": "STOP: shared types in src/types/index.ts have changed. Pull latest before continuing.",
  "summary": "Shared types changed"
}

シャットダウンプロトコル（ブロッキング）

グレースフルな終了パスでは必須です： 以下の手順を順番に実行してください。シャットダウンが確認されるかタイムアウトする前に、OMC チームの状態を消去しないでください。--force と --force --all は、明示的に待機を省略するパスです。これらも標準の保護されたセッション単位のクリアを使用し、ロックと所有権を尊重して、失敗を報告します。--force だけでは対象範囲は広がりません。

手順 1：完了を確認する

Verify via TodoWrite or the active task-list surface — all real tasks (non-internal) are completed or failed.

手順 2：各チームメイトにシャットダウンを要求する

リードが送信：

{
  "type": "shutdown_request",
  "recipient": "worker-1",
  "content": "All work complete, shutting down team"
}

手順 3：応答を待つ（ブロッキング）

• 標準のキャンセルフローに従い、各チームメイトの shutdown_response を最大 15 秒待ってから、さらに 5 秒かけて照合します
• 確認したチームメイトとタイムアウトしたチームメイトを記録します
• その待機後もチームメイトから応答がない場合は、警告を記録し、応答なしとしてマークします

チームメイトが受信して応答：

{
  "type": "shutdown_response",
  "request_id": "shutdown-1770428632375@worker-1",
  "approve": true
}

承認後、チームメイトは終了するか、新しい作業の受け付けを停止します。Claude Code 2.1.178+ では、チームごとの設定メンバーシップや TeamDelete によるクリーンアップは公開されないため、OMC の状態／レポートで承認を追跡してください。

手順 4：保護されたクリーンアップを完了する

グレースフルな処理の後、skills/cancel/SKILL.md の Team キャンセルフローに従ってください。選択したセッションをクリアし、関連付けられた Ralph を処理します。Claude Code 2.1.178+ には TeamDelete がありません。

手順 5：OMC の tmux／CLI ワーカーのみを対象に孤立プロセスをスキャンする

従来の OMC tmux／CLI ワーカーの実行（omc team ／ /omc-teams）では、クリーンアップ後も残っているワーカープロセスがないか確認します。

node "${CLAUDE_PLUGIN_ROOT}/scripts/cleanup-orphans.mjs" --team-name fix-ts-errors

チーム名に一致する OMC ワーカープロセスをスキャンし、古い孤立プロセスを終了します（SIGTERM → 5s 待機 → SIGKILL）。調査には --dry-run を使用できます。

グレースフルなクリアには、すべてのチームメイトが確認（approve: true を含む shutdown_response）するか、タイムアウトする必要があります。request_id はリクエストから取得し、チームメイトはそれを返す必要があります。決して捏造しないでください。

CLI ワーカー（Codex と Gemini）

チームスキルは、Claude エージェントのチームメイトと外部 CLI ワーカー（Codex CLI と Gemini CLI）を組み合わせたハイブリッド実行に対応しています。どちらもコードを変更できますが、機能とコストは異なります。これらはスタンドアロンの CLI ツールであり、MCP サーバーではありません。

実行モード

タスクは、分解時に実行モードでタグ付けされます。

実行モード	プロバイダー	機能
claude_worker	Claude エージェント	Claude Code のすべてのツール（Read/Write/Edit/Bash/Task）を使用できます。Claude の推論と反復的なツール使用が必要なタスクに最適です。
codex_worker	Codex CLI（tmux ペイン）	working_directory 内のファイルシステムに完全にアクセスできます。tmux ペインで自律的に実行されます。コードレビュー、セキュリティ分析、リファクタリング、アーキテクチャに最適です。npm install -g @openai/codex が必要です。
gemini_worker	Gemini CLI（tmux ペイン）	working_directory 内のファイルシステムに完全にアクセスできます。tmux ペインで自律的に実行されます。UI／デザイン作業、ドキュメント、大規模なコンテキストを扱うタスクに最適です。npm install -g @google/gemini-cli が必要です（エンタープライズ／API キーのプラン）。
antigravity_worker	Antigravity CLI（tmux ペイン）	working_directory 内のファイルシステムに完全にアクセスできます。tmux ペインで自律的に実行されます。Gemini CLI と同様の強みを持ち、Google による Gemini CLI の後継です。公式の手順に従ってインストールしてください（agy バイナリ）。

CLI ワーカーの動作

Tmux CLI ワーカーは、ファイルシステムにアクセスできる専用の tmux ペインで動作します。単なる分析者ではなく、自律的な実行者です。

1. リードがタスクの指示をプロンプトファイルに書き込みます
2. リードが working_directory をプロジェクトのルートに設定して、tmux CLI ワーカーを起動します
3. ワーカーは作業ディレクトリ内でファイルを読み取り、変更を加え、コマンドを実行します
4. 結果と要約が出力ファイルに書き込まれます
5. リードが出力を読み取り、タスクを完了としてマークし、結果を依存するタスクに渡します

Claude のチームメイトとの主な違い：

• CLI ワーカーは tmux 経由で動作し、Claude Code のツールシステムは使いません
• Claude Code のネイティブなタスクリストやチームメッセージ機能は使えません
• Codex、Gemini、Grok、Antigravity、Claude の CLI ワーカーは、割り当てられたタスクの最終状態を記録して終了します
• Cursor ワーカーは対話型セッションにとどまり、メールボックスのメッセージを待ち、明示的なシャットダウン指示がある場合にのみ終了します。Cursor のレビュアータスクの状態遷移はリードが管理します
• リードがワーカーのライフサイクル（起動、監視、結果の収集）を管理します

Cursor/Codex の起動証拠のタイムアウト

v2 ランタイムは、現在の試行におけるタスク／ステータスの証拠を最大 30 秒間待ちます。証拠がない場合、読み取り専用のペイン稼働状況プローブにより、稼働中の Cursor/Codex ワーカーに追加で 30 秒の証拠待機時間を与えることがあります。アイドル状態、停止状態、または未確認のペインには、通常の最終再確認として 1 秒だけ与えます。トリガーは再送されず、ペインの活動だけでは起動成功とは見なされません。稼働中のペインで現在の試行に関する証拠が依然として得られない場合は、worker_startup_evidence_missing_pane_busy として失敗します。それ以外の証拠不足はすべて worker_startup_evidence_missing のままです。この起動失敗では、所有するペインを一度読み取り、折り返された tmux の行を結合し、キャプチャにタスク取得エラーの行が含まれている場合はその行を保持します。この行は起動の証拠ではありません。また、それ以外の証拠不足ではペインを読み取りません。

したがって、稼働中ワーカーのデフォルトの証拠待機時間は 60 秒に、プローブと証拠読み取りにかかる時間（およそ 1 分であり、厳密な 61 秒の実時間制限ではありません）を加えたものです。ペインの作成、準備完了、クリーンアップには別途時間がかかります。起動は直列で行われるため、これらの待ち時間はワーカーごとに累積することがあります。OMC_TEAM_ENGAGED_PANE_RECHECK_MS は追加待機時間をミリ秒単位で上書きします。正の値は最大 120000 に制限され、無効な値または 0 以下の値ではデフォルトが適用されます。

タスクのルーティング先

タスクの種類	最適なルート	理由
反復的な複数ステップの作業	Claude のチームメイト	ツールを介した反復作業とチーム内コミュニケーションが必要
コードレビュー／セキュリティ監査	CLI ワーカーまたは専門エージェント	自律的に実行でき、構造化された分析に適している
アーキテクチャ分析／計画	architect Claude エージェント	コードベースにアクセスでき、強力な分析的推論が可能
リファクタリング（範囲が明確なもの）	CLI ワーカーまたは実行エージェント	自律的に実行でき、構造化された変換に適している
UI／フロントエンドの実装	designer Claude エージェント	デザインの専門知識とフレームワークの慣習を備えている
大規模なドキュメント作成	writer Claude エージェント	執筆の専門知識と、一貫性を保つための大きなコンテキスト
ビルド／テストの反復サイクル	Claude のチームメイト	Bash ツールと反復的な修正サイクルが必要
チーム内の調整が必要なタスク	Claude のチームメイト	チーム／会話のステータス更新が必要

例：CLI ワーカーを使ったハイブリッドチーム

/team 3:executor "refactor auth module with security review"

Task decomposition:
#1 [codex_worker] Security review of current auth code -> output to .omc/research/auth-security.md
#2 [codex_worker] Refactor auth/login.ts and auth/session.ts (uses #1 findings)
#3 [claude_worker:designer] Redesign auth UI components (login form, session indicator)
#4 [claude_worker] Update auth tests + fix integration issues
#5 [gemini_worker] Final code review of all changes

リードはまず #1（Codex によるセキュリティ分析）を実行し、次に #2 と #3 を並行して実行します（Codex がバックエンドをリファクタリングし、designer エージェントがフロントエンドを再設計します）。続いて #4（Claude のチームメイトがテストの反復作業を担当）を実行し、最後に #5（Gemini による最終レビュー）を実行します。

事前分析（任意）

大規模で曖昧なタスクの場合は、チーム作成前に分析を実行します。

1. タスクの説明とコードベースのコンテキストを指定して、Task(subagent_type="oh-my-claudecode:planner", ...) を起動します
2. 分析を活用して、より適切なタスク分割を作成します
3. コンテキストを充実させたうえで、チームとタスクを作成します

タスクの範囲が不明確で、具体的な分割を決める前に外部の推論を役立てられる場合に特に有効です。

モニターの強化：アウトボックスの自動取り込み

リードはアウトボックスリーダーユーティリティを使用して CLI ワーカーからのメッセージを先回りして取り込むことができ、ネイティブなチーム／会話経由の配信と並行して、イベント駆動型のモニタリングを実現できます。

アウトボックスリーダー関数

readNewOutboxMessages(teamName, workerName) -- バイトオフセットカーソルを使用して、単一のワーカーの新しいアウトボックスメッセージを読み取ります。呼び出すたびにカーソルが進むため、以降の呼び出しでは前回の読み取り以降に書き込まれたメッセージのみが返されます。readNewInboxMessages() の受信トレイカーソルのパターンに対応しています。

readAllTeamOutboxMessages(teamName) -- チーム内の全ワーカーから新しいアウトボックスメッセージを読み取ります。{ workerName, messages } エントリの配列を返し、新しいメッセージがないワーカーはスキップします。モニターループでの一括ポーリングに便利です。

resetOutboxCursor(teamName, workerName) -- ワーカーのアウトボックスカーソルをバイト 0 にリセットします。リードの再起動後に過去のメッセージを再読み込みする場合や、デバッグに便利です。

モニターフェーズでの getTeamStatus() の使用

getTeamStatus(teamName, workingDirectory, heartbeatMaxAgeMs?) 関数は、以下を組み合わせた統合スナップショットを提供します。

• ワーカー登録 -- 登録されている MCP ワーカー（シャドーレジストリ／config.json から取得）
• ハートビートの鮮度 -- ハートビートの経過時間に基づく各ワーカーの稼働状況
• タスクの進捗状況 -- ワーカーごとおよびチーム全体のタスク数（pending、in_progress、completed）
• 現在のタスク -- 各ワーカーが現在実行しているタスク
• 最近のアウトボックスメッセージ -- 前回のステータス確認以降の新しいメッセージ

モニターループでの使用例：

const status = getTeamStatus("fix-ts-errors", workingDirectory);

for (const worker of status.workers) {
  if (!worker.isAlive) {
    // Worker is dead -- reassign its in-progress tasks
  }
  for (const msg of worker.recentMessages) {
    if (msg.type === "task_complete") {
      // Mark task complete, unblock dependents
    } else if (msg.type === "task_failed") {
      // Handle failure, possibly retry or reassign
    } else if (msg.type === "error") {
      // Log error, check if worker needs intervention
    }
  }
}

if (status.taskSummary.pending === 0 && status.taskSummary.inProgress === 0) {
  // All work done -- proceed to shutdown
}

アウトボックスメッセージに基づくイベントアクション

メッセージタイプ	アクション
task_complete	タスクを完了としてマークし、ブロックされていたタスクが実行可能になったか確認して、依存するワーカーに通知します
task_failed	失敗サイドカーを増分し、再試行、再割り当て、スキップのいずれにするかを判断します
idle	ワーカーに割り当てられたタスクがありません -- 保留中の作業を割り当てるか、シャットダウンを開始します
error	エラーを記録し、隔離しきい値に達していないか、ハートビート内の consecutiveErrors を確認します
shutdown_ack	ワーカーがシャットダウンを確認しました -- チームから安全に削除できます
heartbeat	稼働状況の追跡情報を更新します（ハートビートファイルと重複しますが、遅延のモニタリングに役立ちます）

この方法は、Claude Code のチームメッセージングツールを使用できない MCP ワーカー向けに、プル型の仕組みを提供することで、ネイティブなチーム／会話メッセージングを補完します。

エラー処理

チームメイトがタスクに失敗した場合

1. チームメイトが、現在有効なチーム／会話の経路を通じてリードに失敗を報告します
2. リードが再試行（同じタスクを同じワーカーまたは別のワーカーに再割り当て）するか、スキップするかを判断します
3. 再割り当てするには、現在有効なタスクリストのエントリで新しい担当者を設定し、現在有効なチームの経路を通じて新しい担当者にメッセージを送信します

チームメイトが応答しなくなった場合（メッセージなし）

1. リードが TodoWrite または現在有効なタスクリストの経路を通じて検知します -- タスクが長時間 in_progress のままです
2. リードが現在有効なチームの経路を通じて、チームメイトに状況を尋ねるメッセージを送ります
3. 応答がない場合は、チームメイトが停止したと判断します
4. 現在有効なタスクリストの経路を通じて、タスクを別のワーカーに再割り当てします

依存関係によるブロック

1. ブロックしているタスクが失敗した場合、リードは次のいずれかを判断する必要があります。
   • ブロッカーを再試行する
   • アクティブなタスクリスト項目の blockedBy メタデータを更新して依存関係を解除する
   • ブロックされたタスクを完全にスキップする
2. アクティブなチームの連絡手段を通じて、影響を受けるチームメイトに判断を伝えます

チームメイトのクラッシュ

1. そのチームメイトの内部トラッキングに、予期しないステータスが表示されます
2. リードは残りのワーカーに孤立したタスクを再割り当てします
3. 必要に応じて、Task(name="worker-N", subagent_type="...") で代わりのチームメイトを起動します

Team + Ralph の連携

ユーザーが /team ralph を呼び出す、「team ralph」と言う、または両方のキーワードを組み合わせると、チームモードは Ralph の永続化ループ内で動作します。これにより、次の機能が提供されます。

• チームのオーケストレーション -- ステージごとに専門エージェントを配置したマルチエージェントの段階的なパイプライン
• Ralph の永続化 -- 失敗時の再試行、完了前のアーキテクトによる検証、イテレーションの追跡

有効化

Team+Ralph は、次の場合に有効になります。

1. ユーザーが /team ralph "task" または /oh-my-claudecode:team ralph "task" を呼び出す
2. キーワード検出器がプロンプト内の team と ralph の両方を検出する
3. フックがチームのコンテキストとともに MAGIC KEYWORD: RALPH を検出する

状態の連携

両方のモードは、相互参照を含むそれぞれの状態ファイルに書き込みます。

// Team state (via state_write)
state_write(mode="team", session_id="<current_session_id>", active=true, current_phase="team-plan", state={
  "team_name": "build-rest-api",
  "linked_ralph": true,
  "task": "build a complete REST API"
})

// Ralph state (via state_write)
state_write(mode="ralph", session_id="<current_session_id>", active=true, iteration=1, max_iterations=10, current_phase="execution", state={
  "linked_team": true,
  "team_name": "build-rest-api"
})

実行フロー

1. Ralph の外側のループが開始します（イテレーション 1）
2. チームのパイプラインが実行されます：team-plan -> team-prd -> team-exec -> team-verify
3. team-verify が成功した場合：Ralph がアーキテクトによる検証を実行します（最低でも STANDARD ティア）
4. アーキテクトが承認した場合：両方のモードが完了し、/oh-my-claudecode:cancel を実行します
5. team-verify が失敗する、またはアーキテクトが却下した場合：チームは team-fix に入り、その後 team-exec -> team-verify に戻ります
6. 修正ループが max_fix_loops を超えた場合：Ralph がイテレーションを増やし、パイプライン全体を再試行します
7. Ralph が max_iterations を超えた場合：最終状態は failed になります

冪等な復旧

リードが実行途中でクラッシュした場合、チームスキルは既存の OMC 状態を検出して再開します。

1. state_read(mode="team", session_id="<current_session_id>") を読み取り、アクティブな OMC チームのスラッグ、フェーズ、ワーカーのラベルを確認します
2. OMC のハンドオフとタスクリスト／TodoWrite の状態を使って、現在の進捗を確認します
3. チームメイトを重複して起動する代わりに、モニターモードを再開します
4. 最後に記録されたステージから続行します

これにより、ワーカーの重複起動を防ぎ、リードの障害からスムーズに復旧できます。

比較：Team と Legacy Swarm

項目	Team（ネイティブ Claude Code 2.1.178 以降）	Swarm（レガシー SQLite）
ストレージ	OMC の状態／引き継ぎに加え、Claude Code の現行タスクリスト機能	.omc/state/swarm.db 内の SQLite
依存関係	better-sqlite3 は不要	better-sqlite3 npm パッケージが必要
タスクの割り当て	リードがタスクリスト／TodoWrite の状態を通じて名前付きワーカーを事前に割り当てます	SQLite IMMEDIATE トランザクション — アトミック
競合状態	2 つのエージェントが同じタスクを割り当てる可能性があります（事前割り当てで軽減）	なし（SQLite トランザクション）
コミュニケーション	ネイティブな暗黙のチームメッセージ／会話ターン	なし（応答を待たないエージェント）
タスクの依存関係	リードがタスクリスト／TodoWrite の状態で依存関係を管理します	非対応
ハートビート	メッセージ／ステータスの欠落によってリードが検知します	手動のハートビートテーブルとポーリング
シャットダウン	グレースフルなリクエスト／レスポンスプロトコルに加え、OMC の状態をクリア	シグナルによる終了
エージェントのライフサイクル	名前付き Agent／Task の起動と OMC の状態で追跡します	ハートビートテーブルを使った手動追跡
進捗の可視性	名前付きワーカーの担当が分かるタスクリスト／TodoWrite の状態	tasks テーブルへの SQL クエリ
競合の防止	担当者ラベル（リードが割り当て）	タイムアウト付きのリースベースの割り当て
クラッシュからの復旧	メッセージの欠落を検知したリードが再割り当てします	5 分のリースタイムアウト後に自動解放
状態のクリーンアップ	チームメイトのシャットダウン後に OMC のチーム状態をクリアします	SQLite データベースを手動で rm

Swarm より Team を使う場合： 新しいネイティブ Claude Code の作業には、常に /team を優先してください。Claude Code の暗黙のエージェントチームを使用し、外部依存関係は不要で、エージェント間の連携とタスクの依存関係管理に対応しています。

キャンセル

Team のキャンセルは、skills/cancel/SKILL.md に定義されたフローのみで行います。このフローでは、フラグの組み合わせ、ID とフェイルクローズのルール、グレースフルおよび強制終了の待機、セッションスコープの保護されたクリア、Team を優先する連携 Ralph の処理、全セッションへの認可、未解決セッションのゲートを管理します。引き継ぎはキャンセル後も維持され、捕捉されていない Team のルートは引き続き保護されます。

連携モードのキャンセル（Team + Ralph）

Ralph との連携に関する依存関係も、同じ標準フローで扱います。ここで別のセッション操作手順を重ねて記載しないでください。

Runtime V2（イベント駆動型）

デフォルトでは、チームランタイムはレガシーの done.json ポーリングウォッチドッグではなく、イベント駆動型アーキテクチャを使用します。

• done.json は不要：タスクの完了は CLI API のライフサイクル遷移（claim-task、transition-task-status）で検知します
• スナップショットベースの監視：各ポーリングサイクルでタスクとワーカーの時点スナップショットを取得し、差分を計算してイベントを出力します
• イベントログ：すべてのチームイベントは .omc/state/team/{teamName}/events.jsonl に追記されます
• ワーカーステータスファイル：ワーカーはステータスを .omc/state/team/{teamName}/workers/{name}/status.json に書き込みます
• 維持される機能：センチネルゲート（早すぎる完了を防止）、サーキットブレーカー（停止したワーカーを検知）、障害サイドカー

ネイティブ CLI のチームジョブには、インスタンスにバインドされた v2 ランタイムが必要です。ジョブを開始する前に、無効化を指定する OMC_RUNTIME_V2 の値（0、false、no、または off）を解除してください。ペインのみを対象とするレガシーのクリーンアップへのフォールバックはありません。シャットダウンには --force を指定した場合でも、一致するインスタンスとワーカー起動の証拠が必要です。セッションの state_clear はネイティブランタイムのツリーを削除せず、ネイティブチームのシャットダウンの代わりにもなりません。

動的スケーリング

OMC_TEAM_SCALING_ENABLED=1 が設定されている場合、チームはセッション中のスケーリングに対応します。

• scale_up：実行中のチームにワーカーを追加します（max_workers の上限を遵守します）
• scale_down：アイドル状態のワーカーをグレースフルにドレインして削除します（ワーカーは削除前に現在のタスクを完了します）
• ファイルベースのスケーリングロックにより、スケーリング操作の同時実行を防ぎます
• 単調増加するワーカーインデックスカウンターにより、スケーリングイベントをまたいでもワーカー名の一意性を確保します

設定

任意の設定は .claude/omc.jsonc（プロジェクト）または ~/.config/claude-omc/config.jsonc（ユーザー）に記述します。プロジェクトの値はユーザーの値より優先され、OMC_TEAM_ROLE_OVERRIDES（環境変数の JSON）はその両方より優先されます。

{
  "team": {
    "ops": {
      "maxAgents": 20,
      "defaultAgentType": "claude",
      "monitorIntervalMs": 30000,
      "shutdownTimeoutMs": 15000,
    },
  },
}

• ops.maxAgents - チームメイトの最大数（デフォルト：20）
• ops.defaultAgentType - /team の呼び出しで指定されていない場合に使用する CLI プロバイダー（claude | codex | gemini | antigravity | grok | cursor、デフォルト：claude）
• ops.monitorIntervalMs - TodoWrite またはアクティブなタスクリストの表示を確認する頻度（デフォルト：30s）
• ops.shutdownTimeoutMs - シャットダウン応答を待つ時間（デフォルト：15s）

注： ネイティブの Claude Code チームメイトには、ハードコードされたモデルのデフォルトはありません。各チームメイトは、ロールごとに上書きされない限り、リードセッションで設定されたモデルを継承します。OMC のレガシー CLI ワーカーは別プロセスであり、そのプロバイダーとモデルはネイティブのチームメイトからの継承ではなく、OMC のチームルーティングによって決まります。

ネスト（Claude Code 2.1.217+）： Claude チームメイトは、セッションの暗黙的なチームに属する、独立した完全な Claude Code セッションです（フェーズ 5 を参照）。チームメイトがネストされたサブエージェントを起動できる、またはできないと決めつけないでください。Claude Code 2.1.217～2.1.218 では CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH のデフォルトは 1 でしたが、2.1.219+ では 3 であり、現在の設定がメインの会話より下のサブエージェント階層を制御します。ネストした委任が意図的で、実行中のランタイムでサポートされている場合を除き、各チームメイトを作業を行う単位として計画してください。OMC CLI ワーカー（ops.defaultAgentType による claude、codex、gemini、grok、cursor、antigravity）は Claude Code のサブエージェントではなく、別プロセスのため、Claude のサブエージェント深度設定の影響を受けません。

同時実行： 現在の OMC チーム CLI はワーカーの並列起動数を 20（MAX_WORKER_COUNT）に制限しています。設定スキーマには ops.maxAgents がありますが、現在のランチャーはこれを参照しません。Claude Code の CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS もデフォルトは 20 ですが、この上限が適用されるのは Agent が起動するサブエージェントです。Claude Code のドキュメントでは、エージェントチームのチームメイトには独自の上限が適用されるとされています。この 2 つの値を共通の上限として扱ったり、最大規模の OMC チームを編成すると通常のサブエージェント用の余裕がちょうどなくなると想定したりしないでください。リードが Agent による作業も必要とする場合は、OMC チームの規模を控えめに設定してください。

ロールごとのプロバイダーとモデルのルーティング

適用範囲： /team のみが対象です。タスクベースの委任では delegationRouting を使用します（別のドキュメントを参照）。この 2 つのシステムは意図的に併存しています。

各標準ロールで使用するプロバイダー（claude、codex、gemini、antigravity、grok、cursor）とモデルティアを指定します。ルーティングはチーム作成時に一度だけ解決され、TeamConfig.resolved_routing に保存されます。スポーン、スケールアップ、再起動はすべてスナップショットを参照するため、チームの存続期間中、ロールのワーカー CLI とモデルは固定されます。

例 — ユーザーのターゲットマッピング

// .claude/omc.jsonc
{
  "team": {
    "roleRouting": {
      "orchestrator": { "model": "inherit" },
      "planner": { "provider": "claude", "model": "HIGH" },
      "analyst": { "provider": "claude", "model": "HIGH" },
      "executor": { "provider": "claude", "model": "MEDIUM" },
      "debugger": { "provider": "cursor" },
      "critic": { "provider": "codex" },
      "code-reviewer": { "provider": "gemini" },
      "test-engineer": { "provider": "gemini", "model": "MEDIUM" },
    },
  },
}

ロール	プロバイダー	モデル
orchestrator	claude（固定）	呼び出し元セッションを継承
planner	claude	HIGH（opus）
analyst	claude	HIGH（opus）
executor	claude	MEDIUM（sonnet）
debugger	cursor	cursor-agent のデフォルト
critic	codex	codex のデフォルト
code-reviewer	gemini	gemini のデフォルト
test-engineer	antigravity	antigravity のデフォルト

標準ロール

orchestrator、planner、analyst、architect、executor、debugger、critic、code-reviewer、security-reviewer、test-engineer、designer、writer、code-simplifier、explore、document-specialist。

ユーザー向けのエイリアスは normalizeDelegationRole() を介して正規化されます。たとえば、reviewer → code-reviewer、quality-reviewer → code-reviewer、harsh-critic → critic、build-fixer → debugger です。受け付けられたエイリアスキーは、検証時だけでなく、解決済みスナップショットの作成時と後続のステージルーティング時にも適用されます。不明なロールは解析時に検証エラーになります。

仕様フィールド（TeamRoleAssignmentSpec）

• provider — "claude" | "codex" | "gemini" | "antigravity" | "grok" | "cursor"。省略した場合は claude がデフォルトになります。
• model — ティア名（"HIGH" | "MEDIUM" | "LOW"）または明示的なモデル ID です。ティアは routing.tierModels を通じて解決されます。
• agent — オプションの Claude エージェント名です（例："critic"、"executor"）。解決されたプロバイダーが claude の場合にのみ適用されます。

orchestrator は claude に固定されており、ユーザーが設定できるのは model のみです。orchestrator にほかのキーを指定すると、バリデーターによって拒否されます。

cursor は cursor-agent をインタラクティブなワーカーとして起動します。レビュアー／判定ロール（critic、code-reviewer、security-reviewer、test-engineer）がサポートされており、Claude 以外のほかのプロバイダーと同じ構造化された判定出力の契約が適用されます。判定を受け取った後のタスク状態の遷移はリーダーが担います。最終承認は引き続きリードセッションの責任です。

環境変数によるオーバーライド

OMC_TEAM_ROLE_OVERRIDES='{"critic":{"provider":"codex"},"code-reviewer":{"provider":"gemini"}}'

優先順位：OMC_TEAM_ROLE_OVERRIDES > .claude/omc.jsonc（プロジェクト）> ~/.config/claude-omc/config.jsonc（ユーザー）> 組み込みのデフォルト値。不正な JSON は警告を記録して無視されます。環境変数によるオーバーライドはベストエフォートで適用され、実行が中断されることはありません。

CLI 不在時の事前チェック

チームの起動時には、アイドルワーカーへの割り当てや明示的なロールルートも含め、初期ワーカーに実際に使用されるプロバイダーのみを厳密に事前チェックします。ロールルーティングによって各ワーカーの初回起動時のプロバイダーが選択されます。既存のペインに後から割り当てられたタスクでは、そのワーカーのプロバイダーが維持され、タスクのロールによる再ルーティングは行われません。選択されたプロバイダーのバイナリが見つからない場合、相対パスの場合、または信頼できない場合は、チーム状態やマルチプレクサーへの副作用が発生する前に失敗します。ルーティングスナップショットに存在するだけのプロバイダーや、宣言されたエージェントリストに含まれるだけのプロバイダー（起動対象として選択されていないロールのプロバイダーなど）は検査されません。ルーティングが優先されます。選択されたロールのプロバイダーが利用できない場合、ランタイムが黙って Claude に変更することはありません。スケールアップとワーカーの復旧では、起動しようとするプロバイダーをそれぞれ個別に事前チェックし、利用できない場合はフェイルクローズします。プロバイダーの利用可否は omc doctor --team-routing で確認してください。

固定性 — 一度解決し、すべてで再利用

解決済みのルーティングはチームごとに不変です。各ワーカーの初回起動時の割り当てが選択され、既存のペインで後から実行されるタスクは、タスクのロールによるプロバイダーの再ルーティングを行わず、そのワーカーのプロバイダーを引き続き使用します。チームの稼働中に設定を編集しても実行中のチームには反映されません。新しい /team 呼び出しで新しいマッピングが適用されます。起動、スケールアップ、ワーカーの再起動では、起動するワーカーに同じスナップショットが使用されます。このスナップショットは TeamConfig とともに引き継がれるため、ワークツリーのデタッチ後も維持されます。

ゼロ設定時の動作

team.roleRouting が空の場合、パッチ適用前の動作が維持されます。すべてのワーカーが Claude となり、モデルのティアには routing.tierModels が適用されます。また、/team 3:executor ... を実行すると、引き続き Claude Sonnet のエグゼキューターが 3 つ起動します。

状態のクリーンアップ

Team とリンクされた Ralph のクリーンアップには /oh-my-claudecode:cancel を使用してください。この正式なフローでは、セッション ID、ロック／所有権、正常終了と強制終了の待機、レガシーランタイムのクリーンアップが処理されます。ネイティブ Claude Code 2.1.178+ には TeamDelete がありません。通常の完了時は、シャットダウンプロトコルの後に実行してください。取得されていない Team ルートと引き継ぎは保持されます。

Git Worktree との統合

MCP ワーカーは、並行して動作するワーカー間のファイル競合を防ぐため、分離された git ワークツリーで作業できます。

動作の仕組み

1. ワークツリーの作成：ワーカーを起動する前に、createWorkerWorktree(teamName, workerName, repoRoot) を呼び出して、.omc/worktrees/{team}/{worker} に omc-team/{teamName}/{workerName} ブランチで隔離されたワークツリーを作成します。

2. ワーカーの分離：ワーカーの BridgeConfig で、ワークツリーのパスを workingDirectory として渡します。ワーカーは自身のワークツリー内でのみ作業します。

3. マージの調整：ワーカーがタスクを完了したら、checkMergeConflicts() を使ってブランチを問題なくマージできることを確認し、続いて mergeWorkerBranch() を使って --no-ff でマージし、履歴を明確に保ちます。

4. チームのクリーンアップ：チームのシャットダウン時に、cleanupTeamWorktrees(teamName, repoRoot) を呼び出して、すべてのワークツリーとブランチを削除します。

API リファレンス

関数	説明
createWorkerWorktree(teamName, workerName, repoRoot, baseBranch?)	隔離されたワークツリーを作成
removeWorkerWorktree(teamName, workerName, repoRoot)	ワークツリーとブランチを削除
listTeamWorktrees(teamName, repoRoot)	チームのすべてのワークツリーを一覧表示
cleanupTeamWorktrees(teamName, repoRoot)	チームのすべてのワークツリーを削除
checkMergeConflicts(workerBranch, baseBranch, repoRoot)	非破壊的な競合チェック
mergeWorkerBranch(workerBranch, baseBranch, repoRoot)	ワーカーブランチをマージ（--no-ff）
mergeAllWorkerBranches(teamName, repoRoot, baseBranch?)	完了したすべてのワーカーの変更をマージ

重要な注意事項

• tmux-session.ts の createSession() はワークツリーの作成を処理しません。ワークツリーのライフサイクルは git-worktree.ts を介して別途管理されます。
• 個々のワーカーのシャットダウン時にワークツリーがクリーンアップされることはありません。事後調査を可能にするため、クリーンアップはチームのシャットダウン時にのみ行われます。
• ブランチ名は、インジェクションを防ぐために sanitizeName() でサニタイズされます。
• すべてのパスはディレクトリトラバーサルに対して検証されます。

注意点

1. 内部／ライフサイクルタスクの項目がタスクリストの出力を汚染する場合があります -- Claude Code が、生成されたチームメイトの内部ライフサイクル項目を報告する場合があります。実際のタスクの進捗を数えるときは、それらを除外してください。内部タスクの件名は、チームメイトの名前であることがよくあります。

2. アトミックなタスクの取得はできません -- SQLite swarm とは異なり、ネイティブのタスクリスト／TodoWrite の状態では、トランザクションによるタスクの取得はできません。2 人のチームメイトが競合して同じタスクを取得する可能性があります。対策： チームメイトを生成する前に、リードが担当者を割り当ててください。チームメイトは、自分に割り当てられたタスクのみを担当してください。

3. タスクリストツールで公開されるタスク ID は文字列です -- ID は整数ではなく、自動採番された文字列（「1」、「2」、「3」）の場合があります。タスクリストツールを使用する際は、taskId フィールドに必ず文字列を渡してください。

4. TeamDelete によるクリーンアップはありません -- Claude Code 2.1.178+ では TeamDelete が削除されました。シャットダウンメッセージと OMC の状態クリーンアップを使用してください。

5. メッセージは自動配信されます -- チームメイトからのメッセージは、新しい会話ターンとしてリードに届きます。受信メッセージをポーリングしたり、受信トレイを確認したりする必要はありません。ただし、リードのターン処理中はメッセージがキューに入り、ターン終了後に配信されます。

6. チームメイトへのプロンプトに秘密情報を含めないでください -- プロンプトはログ、状態、会話履歴に保持される場合があります。認証情報や機密データをチームメイトへのプロンプトに含めないでください。

7. シャットダウン確認は状態／報告イベントです -- チームメイトがシャットダウンを承認して終了した後は、その確認を OMC の状態／報告で追跡してください。Claude Code のチームメンバーシップ設定が更新されることは期待しないでください。

8. shutdown_response には request_id が必要です -- チームメイトは、受信したシャットダウンリクエスト JSON から request_id を抽出し、送り返す必要があります。形式は shutdown-{timestamp}@{worker-name} です。この ID を捏造すると、シャットダウンは通知なしで失敗します。

9. チーム名は有効なスラッグである必要があります -- 小文字、数字、ハイフンを使用してください。タスクの説明から名前を作成します（例：「fix TypeScript errors」は「fix-ts-errors」になります）。

10. ブロードキャストはコストがかかります -- ブロードキャストを行うと、チームメイト全員に個別のメッセージが送られます。デフォルトでは message（DM）を使用してください。本当にチーム全体にとって重要なアラートの場合に限り、ブロードキャストを使用してください。

11. CLI ワーカーの稼働期間はプロバイダーに従います -- 「CLI ワーカーの動作」を参照してください。Tmux CLI ワーカーは、Claude Code のネイティブのタスクリストやチームメッセージ機能を使用しません。

並列セッションに関する注意点

• 複数リポジトリのワークスペース基点： 親ディレクトリに .omc-workspace マーカーを配置すると、サブリポジトリにまたがる複数のセッションで 1 つの .omc/ を共有できます。解決順序：OMC_STATE_DIR > .omc-workspace > git > cwd。docs/REFERENCE.md を参照してください。
• セッション ID の取得元： CLI コンテキストでは OMC_SESSION_ID env var が優先され、フックコンテキストでは hook payload の data.session_id が優先されます。
• 計画 ID（該当する場合）： チームの状態はセッション単位です。.omc/handoffs/ のチーム間ハンドオフは、設計上共有されます（ワークスペース計画の Wave G を参照）。
• 並列判定： サポートされています（セッション単位＋設計上共有されるハンドオフ）