/team-agents — 調整されたエージェントチーム

設定

// ~/.claude/settings.json — 必須
{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }

// ~/.claude.json — 表示モード (デフォルト: "auto")
{ "teammateMode": "in-process" }   // すべてをメインターミナルで実行
{ "teammateMode": "tmux" }         // ペイン分割 (tmux/iTerm2 が必須)

claude --teammate-mode in-process   # セッションごとのオーバーライド

Claude Code v2.1.32+ が必須です。環境変数がない場合、TeamCreate/SendMessage/TaskList ツールは存在しません。並列サブエージェントにフォールバックします。

インプロセスキー: Shift+Down でチームメイトを切り替え、Enter で表示、Escape で割り込み、Ctrl+T でタスク切り替え。

品質ゲートフック

// ~/.claude/settings.json
{
  "hooks": {
    "TeammateIdle": [{ "matcher": "", "hooks": [{ "type": "command", "command": "..." }] }],
    "TaskCreated": [{ "matcher": "", "hooks": [{ "type": "command", "command": "..." }] }],
    "TaskCompleted": [{ "matcher": "", "hooks": [{ "type": "command", "command": "..." }] }]
  }
}

フックからの終了コード 2 = アクション拒否 + エージェントへのフィードバック送信。

---

使用方法

/team-agents "このPRをセキュリティ、パフォーマンス、テストでレビューして"
/team-agents "認証モジュールをリファクタリング" --roles 3
/team-agents "Xについて調査" --model haiku
/team-agents "機能Yを実装" --plan
/team-agents --manual "機能Zを構築"
/team-agents --manual "機能を構築" --worktree

/team-agents who                    # プレゼンス・ドット + タスク状態
/team-agents --panes                # tmux ペイン・スキャン
/team-agents zoom scout             # エージェントのペインのズーム切り替え
/team-agents sync                   # すべてのワークツリーをメインに同期
/team-agents merge scout            # エージェントのブランチをメインにマージ
/team-agents compile                # すべてのレポートを集約
/team-agents shutdown               # グレースフルシャットダウン
/team-agents cleanup                # アイドル孤立ペインを削除
/team-agents killshot               # すべてのリード以外のペインを削除
/team-agents doctor [--fix]         # ゴースト + 孤立を検出

フラグ	効果
--manual	ヒューマンがリードリレー経由でエージェントを制御
--worktree	各エージェントが git ワークツリー + ブランチを取得
--panes	tmux ペインをのぞき見
--plan	プランはリーダーのインボックスポーラー自動承認 — 人間レビューではなく生成ゲート
--roles N	エージェント数をオーバーライド
--model X	モデルをオーバーライド (sonnet/opus/haiku)

---

使用時期

ティア	使用時期	ツール
サブエージェント	< 3 エージェント、独立した作業	Agent ツール
チームエージェント	3-5 エージェント、調整が必要	TeamCreate + SendMessage + TaskList
クロスOracle	セッション間、マルチリポ	/talk-to + contacts

ルール: 2 つの独立したエージェント → サブエージェント。調整された作業 → チームエージェント。 サイジング: 3-5 チームメイト、各 5-6 タスク。トークンはチームメイトあたり線形にスケーリング。

サブエージェント定義

スポーン時に .claude/agents/ 定義を参照: tools + model を尊重します。チームツール (SendMessage、TaskUpdate) は常に利用可能です。skills/mcpServers frontmatter はチームメイトには適用されません。

---

ライフサイクル

1. チームを作成

TeamCreate("team-name")   // タスクからスラッグ化

2. タスクを作成（依存関係あり）

TaskCreate({ subject: "Security review", description: "..." })
TaskCreate({ subject: "Perf review", description: "..." })
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })   // タスク 2 はタスク 1 を待つ

3. チームメイトをスポーン

Agent ツール経由で全てを並列にスポーン。プロンプトテンプレート（すべてのチームメイトが取得）:

You are the [ROLE] specialist on team "[TEAM_NAME]".

REPO: [WORKTREE_PATH if --worktree, else ABSOLUTE_PATH_TO_MAIN_REPO]
TASK: [TASK_DESCRIPTION]
COLOR: [AGENT_COLOR — e.g. blue, green, yellow]
WORKTREE: [yes — write freely | no — do NOT write files]

Instructions:
1. Do your work
2. Mark task done: TaskUpdate({ taskId: [ID], status: "completed" })
3. Report to lead: SendMessage({
     to: "team-lead@[TEAM_NAME]",
     summary: "[5-10 words]",
     message: "[findings, max 500 words]"
   })

HEARTBEAT (mandatory):
- Every 5 min: SendMessage PROGRESS: <what you did>
- Blocked: SendMessage STUCK: <what you need>
- Done: SendMessage DONE: <branch if worktree> <summary>
- Failed: SendMessage ABORT: <reason>
- NEVER go idle without reporting.

Rules:
- ALWAYS SendMessage BEFORE finishing
- If worktree: write to YOUR worktree only
- If shared repo: do NOT write files
- Max 500 words per report
- Be specific — paths, lines, evidence

重要: 常にリテラル REPO: パス（シェル変数なし）、スポーン opts からの COLOR:、team-lead@[TEAM_NAME]、ハートビートプロトコル、500 ワード制限を含める。

4. 待機 + コンパイル

• アイドル通知は正常 — チームメイトが作業中
• 実際のコンテンツは SendMessage で summary 付きで到着
• チームメイトがクラッシュした場合: 停止したエージェントへの SendMessage はディスクトランスクリプトから自動再開
• isActive() は常に tmux エージェントで true を返す（バグ） — 疑わしい場合はペインを直接確認

以下にコンパイル:

# [Task] — Team Report
**Team**: [name] | **Agents**: [N] | **Duration**: ~[N]min
## [Role]: [Summary]    (per agent)
## Synthesis            (lead's cross-cutting observations)
## Action Items

5. シャットダウン戦略

戦略 A: 一括 (デフォルト) — すべてのエージェントを待機して、すべてをシャットダウン:

# すべてのエージェントが DONE を報告した後:
SendMessage({ to: "agent-1", message: { type: "shutdown_request" } })
SendMessage({ to: "agent-2", message: { type: "shutdown_request" } })
# シャットダウン_レスポンスを待機 (~10s)
TeamDelete()

手動でループを書かないでください — 構造化メッセージはブロードキャストできません (#212) が、ヘルパースクリプトがチームメイトごとに SendMessage ブロックを生成します:

bash ~/.claude/skills/team-agents/scripts/broadcast-shutdown.sh $TEAM
# → コピー&ペースト可能な SendMessage 行を出力 (リード除く)
# → スクリプト化ループ向けに --names (未処理リスト) と --json (配列) もサポート
# → --type=X でシャットダウンだけでなく、任意の構造化メッセージをブロードキャスト

戦略 B: ローリングシャットダウン — 各エージェントが完了したらシャットダウン:

# 各 DONE レポート時: すぐそのエージェントをシャットダウン
SendMessage({ to: "agent-1", message: { type: "shutdown_request" } })
# 他のエージェントを実行状態に保つ
# 最後のエージェントが報告時 → シャットダウン + TeamDelete

使用時期: エージェントが独立している、クロスエージェント依存関係がない。トークン節約 — アイドルエージェントは依然としてコンテキストを消費。

戦略 C: Cron チェック — 長時間実行チーム向け (10+ 分):

# /loop または ScheduleWakeup 経由で定期チェックをスケジュール
2-5 分ごと: TaskList をチェック
  - すべてのタスクが完了 → すべてシャットダウン + コンパイル
  - 一部完了、一部スタック → スタック エージェントをナッジ
  - すべて作業中 → スキップ、次サイクルで再確認

使用時期: チーム実行 > 10 分、リードが待機をしたくない。

戦略 D: TeammateIdle フック (システムレベル):

// ~/.claude/settings.json
{ "hooks": { "TaskCompleted": [{
  "matcher": "", "hooks": [{
    "type": "command",
    "command": "bash -c 'DONE=$(ls ~/.claude/tasks/*/completed 2>/dev/null | wc -l); TOTAL=$(ls ~/.claude/tasks/*/ 2>/dev/null | wc -l); [ \"$DONE\" = \"$TOTAL\" ] && echo ALL_DONE'"
  }]
}]}}

終了コード 0 + stdout "ALL_DONE" → リードはシャットダウン時期を知っている。最も信頼性が高く、ポーリングなし。

チーム期間に基づいて選択:

期間	戦略	理由
< 2 分	A (一括)	高速、シンプル
2-10 分	B (ローリング)	早期完了者でトークンを節約
> 10 分	C (cron) または D (フック)	リードをブロックしない

**シャットダウン後**（常に 3 つすべて実行）:

```bash
# 検出結果を永続メールボックスにアーカイブ
for agent in $AGENTS; do
  bash ~/.claude/skills/mailbox/scripts/mailbox.sh archive $agent $TEAM
done

# 一時的なスキルを /tmp にアーカイブ
bash ~/.claude/skills/team-agents/scripts/shutdown-skills.sh $TEAM $AGENTS

# ワークツリーをスイープ（クラッシュセッションをキャッチ — #336）
bash ~/.claude/skills/team-agents/scripts/shutdown-worktrees.sh "$REPO_PATH"

ルール: シャットダウンをスキップしない。シャットダウンをブロードキャストしない。常にワークツリーをスイープ。このセッションのチームは自動クリーンアップで終了します。前セッションのチームは存続し、再開できます。

---

マニュアルモード (--manual)

エージェントはスタンバイで起動 — ヒューマンが各エージェントをリードリレー経由で指示します。

スタンバイプロンプト (標準プロンプトを置換):

You are [ROLE] on team "[TEAM_NAME]" in MANUAL mode.
REPO: [PATH]
COLOR: [AGENT_COLOR — e.g. blue, green, yellow]
Wait for instructions. On each message:
1. Execute the work
2. SendMessage report to team-lead@[TEAM_NAME]
3. Return to standby

ライブスキルを作成 するので、ユーザーが /agent-name で直接呼び出せます:

bash ~/.claude/skills/team-agents/scripts/spawn-skills.sh $TEAM $AGENTS

メールボックスをプリロード (エージェントに前の検出結果がある場合):

MAILBOX=$(bash ~/.claude/skills/mailbox/scripts/mailbox.sh load $AGENT 2>/dev/null)

---

ワークツリーモード (--worktree)

モード 1: --worktree フラグ (推奨)

REPO_ROOT=$(git rev-parse --show-toplevel)
for AGENT in $AGENTS; do
  git branch "agents/$AGENT" HEAD 2>/dev/null || true
  git worktree add "$REPO_ROOT/agents/$AGENT" "agents/$AGENT" 2>/dev/null
done

エージェントプロンプトは REPO: をワークツリーパスに設定します。/team-agents merge <agent> 経由でマージします。

モード 2: Agent ツールで isolation: "worktree"

Agent({ name: "builder", isolation: "worktree", ... })

.claude/worktrees/agent-<id> に作成。変更がない場合は自動クリーン。モード 1 を優先。

---

サブコマンド

who — プレゼンス・ドット

ドット	状態	意味
●	active	ハートビート < 5 分
◐	idle	ハートビート 5-10 分
◌	working	進行中
⊘	stuck	STUCK を報告
✓	done	DONE を報告
✗	aborted	ABORT を報告
·	silent	ハートビート > 10 分なし — 調査が必要

スクリプト

bash ~/.claude/skills/team-agents/scripts/panes.sh [team]      # ペイン・スキャン
bash ~/.claude/skills/team-agents/scripts/cleanup.sh            # アイドルペインを削除
bash ~/.claude/skills/team-agents/scripts/cleanup.sh --dry-run  # プレビュー
bash ~/.claude/skills/team-agents/scripts/killshot.sh           # すべてのリード以外を削除
bash ~/.claude/skills/team-agents/scripts/doctor.sh             # ゴースト検出
bash ~/.claude/skills/team-agents/scripts/doctor.sh --fix       # 自動修正
bash ~/.claude/skills/team-agents/scripts/spawn-skills.sh $T $A # /agent スキルを作成
bash ~/.claude/skills/team-agents/scripts/shutdown-skills.sh $T $A  # /tmp にアーカイブ
bash ~/.claude/skills/team-agents/scripts/shutdown-worktrees.sh $R  # ワークツリーをスイープ

sync

REPO_ROOT=$(git rev-parse --show-toplevel)
for wt in "$REPO_ROOT/agents"/*/; do
  AGENT=$(basename "$wt")
  git -C "$wt" fetch origin main:main 2>/dev/null
  git -C "$wt" merge main --no-edit 2>/dev/null
done

merge

git diff --quiet HEAD 2>/dev/null || { echo "Stash first"; exit 1; }
git checkout main
git merge "agents/$AGENT" --no-ff -m "merge: $AGENT from team $TEAM"

---

ベースシステム事実

提供: メールボックス (JSON + ファイルロック)、10 の構造化メッセージ型、権限エスカレーション (worker→leader→user)、停止したエージェントへの SendMessage で自動再開、アイドルエージェントによるタスク自己クレーム、決定論的 ID (name@team)、プラン自動承認、セッション再開（前セッションチームは存続）。

提供しない（追加する): ハートビートプロトコル (PROGRESS/STUCK/DONE/ABORT)、プレゼンス・ドット、ゴースト検出、構造化タスクハンドオフ。

アーキテクチャ: メッセージ優先度 shutdown>leader>peer>FIFO、構造化メッセージはブロードキャスト不可、エージェント当たり 2 つの abort コントローラー (lifecycle vs work)、ペイン作成は Promise チェーン mutex、50 メッセージ UI キャップ。

---

落とし穴 + 制限

1. セッション再開なし — /resume はインプロセスチームメイトを復元しない
2. セッションあたり 1 チーム — 別のチームを開始する前にクリーンアップ
3. ネストされたチームなし — チームメイトはチームをスポーンできない
4. リードは固定 — 昇進または転送なし
5. スポーン時の権限 — すべてのチームメイトはリードのモードを継承
6. タスク状態ラグ — エージェントが TaskUpdate を忘れることがある
7. 分割ペイン — tmux/iTerm2 が必須、VS Code/Ghostty ではない
8. ~3-7x トークン vs シングルエージェント
9. 同じファイル = 上書き — 各エージェントは異なるファイルを所有する必要がある
10. シャットダウンが遅い — エージェントは現在のリクエストを最初に完了
11. 構造化メッセージはブロードキャスト不可 — 個別に送信、または scripts/broadcast-shutdown.sh $TEAM を使用してエージェントごとのブロックを自動生成 (#212)

---

ARGUMENTS: $ARGUMENTS