hummer98 cmux-team: マルチエージェントオーケストレーション
4層アーキテクチャ（Master → Manager → Conductor → Agent）による 自律的マルチエージェント開発オーケストレーションスキル。
0. アーキテクチャ概要
4層構造
[ユーザー] ↔ [Master] → [Manager (daemon)] → [Conductor (常駐)] → [Agent (実作業)]
│ │ │ │ │
│ │ │ │ ├─ コード実装
│ │ │ │ ├─ テスト実行
│ │ │ │ └─ 完了→停止
│ │ │ │
│ │ │ ├─ git worktree 内で作業
│ │ │ ├─ Agent 起動・監視（タブとして作成）
│ │ │ ├─ 結果統合
│ │ │ ├─ タスクを close（cmux-team close-task）
│ │ │ └─ done マーカー作成→idle に戻る
│ │ │
│ │ ├─ タスク検出→idle Conductor にタスク割り当て
│ │ ├─ done マーカーで完了検出（pull 型）
│ │ └─ Journal 読み取り + ログ記録 + Conductor リセット
│ │
│ ├─ タスク作成
│ ├─ 真のソース直接参照→報告
│ └─ Manager 健全性確認
│
└─ 指示・確認
各層の責務
| 層 | 責務 | 特徴 |
|---|---|---|
| Master | ユーザー対話。タスク作成。真のソース直接参照で進捗報告。 | 作業しない。ポーリングしない。 |
| Manager | daemon として常駐。[TASK_CREATED] 通知で起床→タスク検出→idle Conductor にタスク割り当て→done マーカーで完了検出→ログ記録→Conductor リセット→アイドル化。 | アイドル時停止、イベント駆動。 |
| Conductor | 常駐。タスクを割り当てられると自律実行。git worktree 隔離。Agent spawn（タブ）→結果統合→タスクを close（cmux-team close-task）→done マーカー作成→idle に戻る。 |
常駐。タスク完了後も停止しない。 |
| Agent | 実作業（実装・テスト・リサーチ等）。 | 完了したら停止。上位が見に来る。 |
通信方式
| 方向 | 手段 |
|---|---|
| Master → Manager | .team/tasks/ + task-state.json + cmux send 通知（イベント駆動） |
| Manager → Conductor | cmux send（/clear + 新プロンプト送信） |
| Manager ← Conductor | done マーカーファイル（.team/output/conductor-N/done）の存在確認（pull 型） |
| Conductor → Agent | cmux send（プロンプト送信） |
| Conductor ← Agent | cmux-team await-agent（done マーカーの fs.watch）+ PID watcher |
| Manager → Master | .team/logs/manager.log + cmux-team status（team.json + ログ） |
1. コマンド一覧
スラッシュコマンド（Claude 内）
| コマンド | 説明 |
|---|---|
/master |
Master ロール再読み込み（/clear 後の復帰用） |
/team-spec |
要件ブレスト（Master が直接ユーザーと対話） |
/team-task |
タスク管理（タスクの作成・一覧・クローズ） |
/team-archive |
完了タスクのアーカイブ（closed → archived） |
/artifact |
知見のアーティファクト化（作成・一覧・表示） |
CLI サブコマンド
チーム体制の構築・管理はすべて CLI 経由で行う:
| コマンド | 説明 |
|---|---|
cmux-team start |
daemon 起動 + Master spawn + レイアウト構築（レイアウト消失時は自己修復。T286） |
cmux-team status |
ステータス表示（team.json + ログ末尾） |
cmux-team send TASK_CREATED |
タスク作成通知（--task-id, --task-file 必須） |
cmux-team send TODO |
TODO 通知（--content 必須） |
cmux-team send SHUTDOWN |
シャットダウン通知（内部用。明示停止は kill <pid>） |
cmux-team spawn-agent |
Agent spawn（--conductor-surface, --role, --prompt or --prompt-file） |
cmux-team agents |
稼働中エージェント一覧 |
cmux-team kill-agent |
Agent 終了（--surface 必須、--conductor-surface 任意） |
cmux-team create-task |
タスク作成（--title 必須、--priority, --status, --body, --depends-on, --base-branch, --run-after-all, --exclusive 任意） |
cmux-team update-task |
タスク状態更新（--task-id, --status 必須） |
cmux-team close-task |
タスククローズ（--task-id 必須、--journal 任意） |
cmux-team await-task |
タスク完了待ち（--task-id 必須、--timeout 任意） |
cmux-team trace |
API トレース検索（--task, --search, --show） |
cmux-team get-agent-instructions |
Agent ロールの overlay を表示（--role 必須） |
cmux-team set-agent-instructions |
overlay を書き込み（--role 必須、--body / --from-file / --from-stdin） |
cmux-team delete-agent-instructions |
overlay を削除（--role 必須、存在しなければ exit 0） |
cmux-team list-agent-instructions |
全ロールの overlay 状況を一覧表示 |
1.1. プロジェクト固有の追加指示（agent instructions overlay）
プロジェクト固有の Agent への追加指示を .team/agent-instructions/<role>.md に置くと、cmux-team spawn-agent 実行時に prompt-file 中の {{PROJECT_INSTRUCTIONS}} プレースホルダがその内容で置換される。
対象ロール
researcher / architect / planner / design-reviewer / implementer / inspector / dockeeper / task-manager の 8 ロール。
--role impl は implementer、--role reviewer は design-reviewer にエイリアスされる（conductor-role.md の既存 heredoc 例との互換性維持）。
編集方法
# overlay を書き込む
cmux-team set-agent-instructions --role implementer --from-file ./my-impl-notes.md
cmux-team set-agent-instructions --role researcher --body "調査対象は 2025 年以降の論文に限る"
cat ./notes.md | cmux-team set-agent-instructions --role planner --from-stdin
# 内容確認
cmux-team get-agent-instructions --role implementer
cmux-team list-agent-instructions
# 削除
cmux-team delete-agent-instructions --role implementer
overlay ファイルは最大 100 KB。それを超えると set 時に exit 1。
適用タイミング
cmux-team spawn-agent --prompt-file <path> 実行時、prompt-file 内の {{PROJECT_INSTRUCTIONS}} プレースホルダが overlay 本文に展開される。Conductor が Agent 起動用の prompt-file を heredoc で書き出す際は、必ず {{PROJECT_INSTRUCTIONS}} を単独行として残すこと（quoted heredoc 'AGENT_PROMPT' を使うと shell 展開されず安全）。
overlay が存在しない / 空の場合はプレースホルダが空文字に置換される。
典型パターン例
- コーディング規約（命名・コメント言語）を implementer に共有
- テスト方針（モック可否・カバレッジ基準）を inspector に共有
- 調査範囲制限（特定年代・特定著者のみ）を researcher に共有
Settings タブで確認
dashboard TUI の Settings タブ（4 キー）で 8 ロールの overlay 状況と config 値を一覧・プレビューできる（read-only）。
2. トレーサビリティ
daemon 起動時に API Proxy が自動起動し、全 API リクエストを SQLite FTS5 データベースに記録する。Master が過去の作業ログを検索・分析する際に活用できる。
自動プロキシ設定
daemon が起動すると Proxy が自動で立ち上がり、Master および Conductor に ANTHROPIC_BASE_URL=http://127.0.0.1:<port> を設定する。これにより全 API リクエストが Proxy 経由になり、リクエスト/レスポンスが自動記録される。
メタデータ伝播
リクエストヘッダーからメタデータを動的に抽出し、トレースに紐付ける:
| ヘッダー | 内容 |
|---|---|
x-cmux-task-id |
タスクID |
x-cmux-conductor-surface |
Conductor surface |
x-cmux-role |
エージェントロール |
x-claude-code-session-id |
Claude Code セッションID |
trace CLI
cmux-team trace コマンドでトレースを検索・表示できる:
# タスクIDでフィルタ
cmux-team trace --task 035
# 全文検索（SQLite FTS5）
cmux-team trace --search "error"
# 特定トレースの詳細表示（リクエスト/レスポンス本文含む）
cmux-team trace --show 42
# Conductor IDでフィルタ
cmux-team trace --conductor conductor-1
# ロールでフィルタ
cmux-team trace --role impl
# 結果数制限（デフォルト20）
cmux-team trace --limit 50
活用例
Master がユーザーに進捗報告する際、過去の API リクエスト履歴を参照できる:
# あるタスクでどんな API リクエストが行われたか確認
cmux-team trace --task 035
# エラーに関連するリクエストを全文検索
cmux-team trace --search "rate_limit"
3. cmux 操作リファレンス
環境変数
| 変数 | 意味 |
|---|---|
CMUX_SOCKET_PATH |
cmux ソケットパス。設定されていれば cmux 環境内で動作中 |
CMUX_WORKSPACE_ID |
現在のワークスペースID |
CMUX_SURFACE_ID |
現在のサーフェスID |
CMUX_SURFACE |
cmux-team が設定。surface:N 形式。これが設定されていれば cmux-team 管理下 |
基本操作コマンド
| コマンド | 用途 |
|---|---|
cmux identify |
自分の workspace/surface を確認 |
cmux tree |
ペイン・サーフェス階層を表示（T195 以降は init 時の pane 逆引きのみ使用） |
cmux list-panes |
ペイン一覧 |
cmux list-pane-surfaces |
ペイン内のサーフェス一覧 |
cmux new-split right |
右にペイン分割（left/up/down も可） |
cmux new-surface --pane pane:N |
ペイン内に新しいタブを作成 |
cmux send --surface surface:N "command\n" |
コマンド送信 |
cmux send-key --surface surface:N return |
キー送信 |
cmux read-screen --surface surface:N |
画面読み取り |
cmux close-surface --surface surface:N |
サーフェス（タブ）を閉じる |
cmux rename-tab --surface surface:N "name" |
タブ名変更 |
cmux refresh-surfaces |
画面バッファ強制更新 |
send の改行ルール（重要）
単一行: 末尾に \n を付ける。
cmux send --surface surface:1 "echo hello\n"
複数行: 個別の send + send-key return で送信する。
cmux send --surface surface:1 "line 1"
cmux send-key --surface surface:1 return
cmux send --surface surface:1 "line 2"
cmux send-key --surface surface:1 return
注意: \n は最後の1つだけが Enter として機能する。途中の \n は改行にならない。
制御キーの送信
send-key を使う（send ではない）:
cmux send-key --surface surface:N ctrl+c # 中断
cmux send-key --surface surface:N ctrl+d # EOF
cmux send-key --surface surface:N ctrl+z # サスペンド
cmux send-key --surface surface:N return # Enter
cmux send-key --surface surface:N tab # Tab
cmux send-key --surface surface:N escape # Escape
よくある間違い: cmux send "C-c" や cmux send "\x03" → 動作しない。必ず send-key を使うこと。
read-screen トラブルシューティング
| 問題 | 対処 |
|---|---|
| 空・古い出力 | cmux refresh-surfaces してからリトライ |
| 出力が切れる | --scrollback オプションを追加 |
| 特定行数だけ必要 | --lines N オプションを追加 |
| surface が見つからない | cmux list-pane-surfaces で確認 |
通知
# アプリ内通知（ペイン強調 + サイドバーバッジ）
cmux notify --title "完了" --body "ビルドが成功しました"
# macOS 通知センター（サウンド付き）
osascript -e 'display notification "ビルド完了" with title "Claude" sound name "Glass"'
4. タスク完了待ち（await-task）
cmux-team await-task はタスクの完了を fs.watch ベースで待機する CLI コマンド。
cmux-team status のポーリングに比べて軽量・高速で、Claude Code の Bash run_in_background と組み合わせることで Master がブロックされずにタスク完了を待てる。
基本的な使い方
# 単一タスクの完了を待つ
cmux-team await-task --task-id 108
# 複数タスクの完了を待つ（カンマ区切り）
cmux-team await-task --task-id 108,109
# タイムアウト指定（デフォルト: 3600秒）
cmux-team await-task --task-id 108 --timeout 7200
終了コード
| コード | 意味 | stdout/stderr |
|---|---|---|
| 0 | 全タスク closed | summary.md の内容を stdout に出力 |
| 1 | いずれかのタスクが aborted | abort 理由を stderr に出力 |
| 2 | タイムアウト | 残タスク一覧を stderr に出力 |
Master での活用パターン
# バックグラウンドでタスク完了を待つ（Claude Code の Bash run_in_background）
cmux-team await-task --task-id 108
# → task-notification で完了が通知される + summary が読める
# 「結果を見てから次を判断」するフロー
cmux-team await-task --task-id 108
# 完了後に summary を読んで次のアクションを決定
depends-on との使い分け
| 方式 | 用途 |
|---|---|
depends-on (frontmatter) |
自動チェーン: A → B の順序保証。Manager が自動で B を発火 |
await-task (CLI) |
手動チェーン: A の結果を見てから次を判断するケース |
5. タスク属性
タスク frontmatter で表現される実行制御属性。create-task の CLI フラグで指定すると永続化される。
| 属性 | 意味 | CLI フラグ |
|---|---|---|
run_after_all: true |
全 open タスク closed 後に実行（非排他 drain） | --run-after-all |
exclusive: true |
drain 後に単独実行。assigned の間は他の全 assignment を停止（closed 後に再開）。--run-after-all を暗黙に含む |
--exclusive |
exclusive の 3 フェーズ
- drain — 他の全 open タスクが closed になるまで
readyで待機 - exclusive run — assigned 後、他の全タスクの assignment を停止（単独実行）
- resume — closed 後の次 tick から通常 assignment 再開
競合ルール
--exclusive同士は共存可能（ID 昇順に順次排他実行）--exclusive↔ 非排他--run-after-allは共存不可（どちら側から起票してもRUN_AFTER_ALL_CONFLICT）- 非排他
--run-after-all同士は 1 つまで（従来通り） --run-after-allと--exclusiveを同時指定すると警告のみで処理継続
6. 他プロジェクトを覗く
cmux-team は AI 観察箱として、他プロジェクトの runtime 状態を読むことを中核ユースケースの 1 つとしている。--project-root flag で対象を指定できる。
| 用途 | 例 |
|---|---|
| read 系（status / agents / events / metrics 等） | cmux-team status --project-root /path/to/other |
| write 系（create-task / start / spawn-* 等） | cwd と異なる project への書き込みは確認 prompt が出る。TTY なし環境では --project-root-confirm または CMUX_TEAM_PROJECT_ROOT_CONFIRM=1 env で skip |
env 経路 PROJECT_ROOT=... も引き続きサポート（flag が指定されたら env は無視される）。flag で指定した path が存在しない / .team/ を含まない場合は exit 1（strict 検証）。