cmux-team

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 フェーズ

1. drain — 他の全 open タスクが closed になるまで ready で待機
2. exclusive run — assigned 後、他の全タスクの assignment を停止（単独実行）
3. 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 検証）。