@hummer98/cmux-team 3.0.0

package/README.md

@@ -0,0 +1,158 @@
+![cmux-team](banner.jpeg)
+
+# cmux-team
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Multi-agent development orchestration with Claude Code + cmux.
+
+**[日本語版 README はこちら](README.ja.md)**
+
+## Why cmux-team?
+
+Claude Code's built-in sub-agents (the Agent tool) are useful, but **you can't see what they're doing**. You only get the final result — the process is a black box.
+
+cmux-team uses cmux's terminal splitting to run sub-agents **visibly** in parallel.
+
+**What you do**: Just give Claude instructions in natural language.
+**What Claude does**: Splits panes via cmux, launches sub-agents, monitors them, and integrates results.
+
+## Prerequisites
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed
+- [cmux](https://github.com/manaflow-ai/cmux) installed
+- [bun](https://bun.sh/) installed (required for the Manager daemon)
+- Running Claude Code inside a cmux session
+
+## Installation
+
+```bash
+npm install -g @hummer98/cmux-team
+```
+
+## Usage
+
+### Basic Workflow
+
+Start cmux, launch Claude Code inside it.
+
+```
+You:    /cmux-team:start
+  → Daemon starts with TUI dashboard
+  → Master pane auto-created
+  → Switch to Master pane to give tasks
+
+You:    Build a TODO app with React
+Claude: Task created.
+  → Daemon detects task → spawns Conductor
+  → Conductor spawns Agents in adjacent panes
+  → Watch each agent working in real time
+
+You:    How's it going?
+Claude: (checks manager.log, cmux tree)
+        Conductor-1: implementing (2/3 agents done)
+
+You:    Also clean up worktrees (TODO)
+Claude: → Sends TODO to queue via CLI
+       → Daemon spawns new Conductor in parallel
+```
+
+### Commands
+
+| Command | What it does | When to use |
+|---------|-------------|-------------|
+| `/cmux-team:start` | Start daemon + Master | Once per session |
+| `/cmux-team:master` | Reload Master role | After `/clear` |
+| `/team-spec [summary]` | Brainstorm requirements | Deciding what to build |
+| `/team-research <topic>` | Parallel research | Technical research |
+| `/team-design` | Design + review | After requirements |
+| `/team-impl [task\|all]` | Parallel implementation | After design |
+| `/team-review` | Implementation review | After implementation |
+| `/team-test [scope\|all]` | Create & run tests | After implementation |
+| `/team-sync-docs` | Sync documentation | When specs change |
+| `/team-task [action]` | Task management | Record decisions |
+| `/team-archive [range]` | Archive closed tasks | Task cleanup |
+| `/team-status` | Show team status | Anytime |
+| `/team-disband [force]` | Terminate all agents | When done |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│  cmux-team daemon (TypeScript/bun)      │
+│  ┌───────────────────────────────────┐  │
+│  │  TUI Dashboard                    │  │
+│  │  Tasks: 2 open | Conductors: 1/3  │  │
+│  └───────────────────────────────────┘  │
+│  Queue ← Master/Hook write via CLI      │
+│  Loop  → Task scan → Conductor spawn    │
+│  Monitor → Completion → Result collect   │
+└───────────┬────────────┬────────────────┘
+            │            │
+     [Master]    [Conductor-035]
+     Claude Code  Claude Code
+     (Opus)       → [Agent] Claude Code
+```
+
+### Deterministic Manager
+
+The Manager is **not** a Claude Code session. It's a TypeScript program with a deterministic event loop:
+
+- **File queue** (`.team/queue/`) for communication (no `cmux send-key`)
+- **zod** schema validation for all messages
+- **ink** TUI dashboard
+- **Task dependency resolution** via `depends_on` field
+- **Priority sorting** (high > medium > low)
+
+### Task Dependencies
+
+```yaml
+---
+id: 13
+title: Consolidated report
+status: ready
+depends_on: [10, 11, 12]  # waits for all to complete
+---
+```
+
+### Communication
+
+| Direction | Mechanism |
+|-----------|-----------|
+| Master → daemon | CLI (`main.ts send`) → `.team/queue/*.json` |
+| daemon → Conductor | `cmux new-split` + Claude Code launch |
+| Conductor → daemon | SessionEnd hook + `cmux read-screen` polling |
+
+## Troubleshooting
+
+### Daemon won't start
+
+**bun not installed**: `brew install oven-sh/bun/bun`
+
+**Not in cmux**: Run inside cmux. `CMUX_SOCKET_PATH` must be set.
+
+### Panes too narrow
+
+Too many panes cause cmux commands to fail. Use `/team-disband` and set `CMUX_TEAM_MAX_CONDUCTORS=1` to limit concurrency.
+
+### View Conductor session logs
+
+```bash
+grep conductor-xxx .team/logs/manager.log
+# → task_completed ... session=abc-123
+claude --resume abc-123
+```
+
+## Known Limitations
+
+- **API rate limits**: Multiple concurrent agents. Claude Max recommended. Control with `CMUX_TEAM_MAX_CONDUCTORS` (default: 3).
+- **Pane width**: Too many panes can break cmux commands.
+- **Trust prompts**: New directories trigger trust confirmation. Conductor auto-approves but may need manual intervention.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for testing, repository structure, and coding conventions.
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

package/bin/cmux-team.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+// cmux-team CLI ラッパー
+// bun で skills/cmux-team/manager/main.ts を実行する
+
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const mainTs = join(__dirname, "..", "skills", "cmux-team", "manager", "main.ts");
+
+// bun の存在確認
+try {
+  execFileSync("which", ["bun"], { stdio: "ignore" });
+} catch {
+  console.error("エラー: bun がインストールされていません。");
+  console.error("インストール: https://bun.sh/docs/installation");
+  process.exit(1);
+}
+
+// 引数を透過して bun run で実行
+const args = process.argv.slice(2);
+try {
+  execFileSync("bun", ["run", mainTs, ...args], { stdio: "inherit" });
+} catch (e) {
+  process.exit(e.status ?? 1);
+}

package/bin/postinstall.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+// npm postinstall スクリプト
+// manager/ の依存を bun install で解決
+
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const managerDir = join(__dirname, "..", "skills", "cmux-team", "manager");
+
+// bun install（manager/ の依存解決）
+try {
+  execFileSync("which", ["bun"], { stdio: "ignore" });
+  console.log("cmux-team: bun install を実行中...");
+  execFileSync("bun", ["install"], { cwd: managerDir, stdio: "inherit" });
+} catch {
+  console.warn("cmux-team: bun が見つかりません。手動で以下を実行してください:");
+  console.warn(`  cd ${managerDir} && bun install`);
+}
+
+// インストール完了メッセージ
+console.log("cmux-team: インストール完了");
+console.log("  Plugin としても使う場合: claude plugin add hummer98/cmux-team");

package/commands/master.md

@@ -0,0 +1,8 @@
+---
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+description: "Masterロールを読み込んでタスク待機する（/clear 後の再読み込み用）"
+---
+
+`.team/prompts/master.md` を読んで、その指示に従ってください。ユーザーからのタスクを待ってください。
+
+ファイルが存在しない場合は「`/cmux-team:start` を先に実行してください」と案内してください。

package/commands/start.md

@@ -0,0 +1,42 @@
+---
+allowed-tools: Bash, Read
+description: "チーム体制を構築する（daemon + Master を起動）"
+---
+
+# /cmux-team:start
+
+cmux-team daemon を起動し、固定2x2レイアウトで Master + Conductor x3 を構築する。
+
+## 手順
+
+```bash
+# cmux-team コマンドで起動
+if ! command -v cmux-team >/dev/null 2>&1; then
+  echo "ERROR: cmux-team がインストールされていません"
+  echo "npm install -g cmux-team を実行してください"
+  exit 1
+fi
+
+# node_modules がなければ依存インストール
+MANAGER_DIR="$(npm prefix -g)/lib/node_modules/cmux-team/skills/cmux-team/manager"
+if [ ! -d "$MANAGER_DIR/node_modules" ]; then
+  (cd "$MANAGER_DIR" && bun install)
+fi
+
+# daemon 起動
+cmux-team start
+```
+
+## daemon が自動的に行うこと
+
+1. **インフラ初期化** — `.team/` ディレクトリ構造を作成（tasks/, output/, logs/, prompts/ 等）
+2. **Master ペイン作成** — 左上ペインにユーザー対話用の Claude セッションを起動
+3. **固定2x2レイアウト作成** — 以下の4ペイン（5 surface）を作成:
+   ```
+   [Manager|Master] | [Conductor-1]
+   [Conductor-2   ] | [Conductor-3]
+   ```
+4. **各 Conductor で Claude を idle 起動** — 常駐セッションとしてタスク割り当てを待機
+5. **ダッシュボード表示** — チーム状態をサイドバーに表示
+
+このセッションの役割はここで終了。Master ペインに切り替えてタスクを伝えること。

package/commands/team-archive.md

@@ -0,0 +1,63 @@
+---
+allowed-tools: Bash, Read
+description: "完了タスクをアーカイブする（closed → archived）"
+---
+
+# /cmux-team:team-archive
+
+`task-state.json` で closed 状態のタスクをアーカイブディレクトリに移動する。
+
+## 引数
+
+`$ARGUMENTS` でアーカイブ対象を指定:
+
+- `/team-archive` — closed 状態の全タスクをアーカイブ
+- `/team-archive 1-33` — ID 1〜33 のタスクをアーカイブ
+- `/team-archive 15` — ID 15 のタスクのみアーカイブ
+
+## 手順
+
+### 1. アーカイブディレクトリ作成
+
+```bash
+ARCHIVE_DIR=".team/tasks/archived/$(date +%Y-%m-%d)"
+mkdir -p "$ARCHIVE_DIR"
+```
+
+### 2. closed タスクの特定
+
+`task-state.json` から closed 状態のタスク ID を取得:
+
+```bash
+cat .team/task-state.json
+# → closed 状態のエントリを抽出
+```
+
+### 3. 対象タスクの移動
+
+`$ARGUMENTS` を解析:
+
+- **空** → closed 状態の全タスクファイルを `"$ARCHIVE_DIR/"` に移動
+- **`N-M` 形式** → ID が N 以上 M 以下かつ closed 状態のタスクファイルを移動
+- **`N` 形式** → ID が N かつ closed 状態のタスクファイルのみ移動
+
+ID はファイル名の先頭の数字部分（例: `016-conductor-self-review.md` → ID 16）で判定する。
+
+```bash
+# task-state.json から closed ID を取得し、範囲指定と照合
+for f in .team/tasks/*.md; do
+  ID=$(basename "$f" | grep -oE '^[0-9]+' | sed 's/^0*//')
+  # task-state.json で closed かつ ID が範囲内なら移動
+  if [[ $ID -ge $START && $ID -le $END ]]; then
+    mv "$f" "$ARCHIVE_DIR/"
+  fi
+done
+```
+
+移動後、`task-state.json` から該当エントリの status を `archived` に更新する。
+
+### 4. 結果報告
+
+```
+アーカイブ完了: N 件を .team/tasks/archived/YYYY-MM-DD/ に移動
+```

package/commands/team-design.md

@@ -0,0 +1,199 @@
+---
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+description: "アーキテクト+レビュアーエージェントで設計フェーズを実行する"
+---
+
+# /team-design
+
+アーキテクトとレビュアーエージェントを起動し、設計フェーズを実行してください。
+
+## 手順
+
+### 1. 前提チェック
+
+- `.team/team.json` が存在すること
+- `CMUX_SOCKET_PATH` が設定されていること
+- `cmux` コマンドが利用可能であること
+- `.team/specs/requirements.md` が存在し、`Status: Approved` が含まれていること
+  - 存在しない場合: 「要件定義がありません。`/team-spec` を先に実行してください」
+  - 未承認の場合: 「要件が未承認です。`/team-spec` で承認してください」と警告（続行は可能）
+
+### 2. コンテキスト収集
+
+以下を読み込む:
+- `.team/specs/requirements.md` — 要件定義
+- `.team/specs/research.md` — リサーチ結果（あれば）
+- `.team/tasks/` — オープンタスク（あれば。`task-state.json` で状態確認）
+- プロジェクトの主要ディレクトリ構造
+
+### 3. アーキテクトプロンプト生成
+
+1. `~/.claude/skills/cmux-team/templates/common-header.md` を読み込み
+2. `~/.claude/skills/cmux-team/templates/architect.md` を読み込み
+3. テンプレート変数を置換:
+   - `{{ROLE_ID}}` → `architect`
+   - `{{TASK_DESCRIPTION}}` → "要件に基づく技術設計の作成"
+   - `{{OUTPUT_FILE}}` → `.team/output/architect.md`
+   - `{{PROJECT_ROOT}}` → カレントディレクトリ
+   - `{{REQUIREMENTS_CONTENT}}` → requirements.md の内容
+   - `{{RESEARCH_SUMMARY}}` → research.md の内容（あれば。なければ "リサーチ結果なし"）
+   - `{{CODEBASE_CONTEXT}}` → 主要ディレクトリ構造 + 既存の主要ファイル一覧
+   - `{{COMMON_HEADER}}` → 展開済み共通ヘッダー
+4. `.team/prompts/architect.md` に書き出す
+
+### 4. アーキテクトエージェント起動
+
+サブエージェントの配置は cmux-team SKILL.md §5 参照。
+
+```bash
+# a. Conductor と同じワークスペース内で分割（デフォルト）
+cmux new-split right  # → surface:S
+
+# b. ステータス設定
+cmux set-status architect "spawning" --icon sparkle --color "#ffcc00"
+
+# d. Claude 起動（シェルコマンドは \n で送信可能）
+cmux send --surface surface:S --workspace workspace:W "claude --dangerously-skip-permissions\n"
+
+# e. 起動完了を待つ（Trust確認 or ❯ プロンプトをポーリング、cmux-team SKILL.md §2.1 Step 5 参照）
+for i in $(seq 1 10); do
+  SCREEN=$(cmux read-screen --surface surface:S --workspace workspace:W 2>&1)
+  if echo "$SCREEN" | grep -q "Yes, I trust"; then
+    cmux send-key --surface surface:S --workspace workspace:W "return"
+    sleep 5; break
+  elif echo "$SCREEN" | grep -q '❯'; then
+    break
+  fi
+  sleep 3
+done
+
+# f. プロンプト送信（単一行指示 → \n で送信可能）
+cmux send --surface surface:S --workspace workspace:W ".team/prompts/architect.md を読んで指示に従ってください。\n"
+
+# g. 送信確認 + ステータス更新
+sleep 3
+SCREEN=$(cmux read-screen --surface surface:S --workspace workspace:W 2>&1)
+if ! echo "$SCREEN" | grep -qE '(Stewing|Thinking|Reading|Searching|Ideating)'; then
+  cmux send-key --surface surface:S --workspace workspace:W "return"
+  sleep 3
+fi
+cmux set-status architect "running" --icon hammer --color "#0099ff"
+```
+
+### 5. アーキテクト完了待機
+
+```bash
+cmux set-progress 0.0 --label "Design: architect working..."
+cmux wait-for "architect-done" --timeout 600
+```
+
+- 10 分のタイムアウト（設計は時間がかかる場合がある）
+- 定期的に画面を確認し、進捗を報告
+
+### 6. 設計結果の処理
+
+1. `.team/output/architect.md` を読み込む
+2. 内容を `.team/specs/design.md` にコピー
+3. ユーザーに設計概要を提示
+4. アーキテクトペインを閉じる（またはアイドル状態にする）
+
+### 7. レビュアー起動
+
+ユーザーに確認: 「設計のレビューを実行しますか？」
+
+YES の場合:
+
+```bash
+# Design ワークスペース内で分割（アーキテクトペインを再利用 or 新規分割）
+cmux new-split right --workspace workspace:W  # → surface:A
+cmux new-split right --workspace workspace:W  # → surface:B
+```
+
+各レビュアーに対して（cmux-team SKILL.md §2.1 の手順に従う）:
+1. `~/.claude/skills/cmux-team/templates/reviewer.md` からプロンプトを生成
+   - `{{ROLE_ID}}` → `reviewer-1`, `reviewer-2`
+   - `{{ARTIFACT_CONTENT}}` → design.md の内容
+   - `{{REQUIREMENTS_CONTENT}}` → requirements.md の内容
+   - `{{DESIGN_CONTENT}}` → ""（設計そのものをレビュー中のため）
+2. `.team/prompts/reviewer-{1,2}.md` に書き出す
+3. 1体ずつ起動: Claude 起動 → Trust 確認ポーリング → プロンプト送信（`send-key return`）→ 送信確認
+
+### 8. レビュアー完了待機
+
+```bash
+cmux set-progress 0.5 --label "Design: reviewers working..."
+cmux wait-for "reviewer-1-done" --timeout 300
+cmux wait-for "reviewer-2-done" --timeout 300
+```
+
+### 9. レビュー結果の統合
+
+1. `.team/output/reviewer-1.md` と `.team/output/reviewer-2.md` を読み込む
+2. レビュー結果を統合:
+   - **Verdict**: 両方 Approved なら "Approved"、それ以外は "Changes Requested"
+   - **共通指摘**: 両レビュアーが指摘した問題
+   - **個別指摘**: 各レビュアー固有の指摘
+   - **Critical/Major 項目**: 即座に対応が必要な指摘
+3. 統合結果をユーザーに提示
+
+### 10. イテレーション判断
+
+レビュー結果に基づいて:
+
+- **Approved**:
+  - `.team/specs/design.md` の末尾に承認ステータスを追記
+  - 次のステップ案内
+- **Changes Requested**:
+  - Critical/Major 指摘を一覧表示
+  - ユーザーに確認: 「設計を修正しますか？」
+    - YES: レビューフィードバックをアーキテクトプロンプトに追加し、再度アーキテクトを起動（手順 3 に戻る）
+    - NO: 現状の設計で続行（ユーザー判断）
+
+### 11. タスク分解（オプション）
+
+設計が承認されたら:
+- ユーザーに確認: 「設計からタスク一覧を生成しますか？」
+- YES の場合:
+  - design.md を分析してタスクを抽出
+  - 各タスクに並列実行可能フラグ `(P)` を付与
+  - `.team/specs/tasks.md` に書き出す
+  - 形式:
+    ```markdown
+    # タスク一覧
+
+    ## Task 1: <タスク名> (P)
+    - 説明: <詳細>
+    - 依存: なし
+    - 推定規模: S/M/L
+
+    ## Task 2: <タスク名>
+    - 説明: <詳細>
+    - 依存: Task 1
+    - 推定規模: M
+    ```
+
+### 12. クリーンアップと状態更新
+
+- レビュアーペインを閉じる
+- （team.json は daemon が自動更新する）
+- プログレスバーをクリア
+
+### 13. 次のステップ案内
+
+```
+設計フェーズが完了しました。
+
+次のステップ:
+  /team-impl    → 実装フェーズに進む
+  /team-review  → 追加レビューが必要な場合
+```
+
+## 引数
+
+なし
+
+## エラーハンドリング
+
+- アーキテクトがタイムアウトした場合: 画面を確認し、進捗に応じて延長または中断を提案
+- レビュアーの結果が矛盾する場合: 両者の見解を並列表示し、ユーザーに判断を委ねる
+- イテレーションが 3 回を超えた場合: ユーザーに設計の根本的な見直しを提案

package/commands/team-disband.md

@@ -0,0 +1,79 @@
+---
+allowed-tools: Bash, Read, Write, Edit
+description: "全層を終了しチームを解散する"
+---
+
+# /team-disband
+
+全層（Agent → Conductor → Manager）を bottom-up で終了してください。
+
+## 手順
+
+1. .team/team.json を読む（なければ未初期化を案内）
+   稼働中の Conductor は `cmux tree` で確認する
+
+2. **Layer 1: Agent 終了**
+   各 Conductor の Agent を終了:
+   - cmux send --surface <agent-surface> "/exit\n"
+   - sleep 2
+   - cmux close-surface --surface <agent-surface>
+
+3. **Layer 2: Conductor 終了**
+   各 Conductor を終了:
+   - cmux send --surface <conductor-surface> "/exit\n"
+   - sleep 2
+   - cmux close-surface --surface <conductor-surface>
+
+4. **Layer 3: git worktree クリーンアップ**
+   - `git worktree list` で `.worktrees/` 内の worktree を列挙
+   - 各 worktree について未マージの変更を確認:
+     ```bash
+     cd <worktree-path>
+     UNMERGED=$(git log --oneline main..HEAD 2>/dev/null)
+     if [ -n "$UNMERGED" ]; then
+       echo "WARNING: 未マージの変更があります: <worktree-path>"
+       echo "$UNMERGED"
+     fi
+     ```
+   - **未マージの変更がある場合**: ユーザーに警告を表示し確認を求める。`$ARGUMENTS = "force"` の場合のみスキップして強制削除
+   - **未マージの変更がない場合**: `git worktree remove <path>` で削除（`--force` 不要）
+   - 対応するブランチを `git branch -d` で削除（マージ済みのみ。未マージは `-d` が失敗するので安全）
+
+5. **Layer 4: Manager 終了**
+   TypeScript Manager プロセスに SHUTDOWN メッセージを送信:
+   ```bash
+   # SHUTDOWN キューメッセージを送信
+   .team/manager/main.ts stop
+
+   # プロセスが終了するまで待機（最大 15 秒）
+   MANAGER_PID=$(python3 -c "import json; d=json.load(open('.team/team.json')); print(d.get('manager',{}).get('pid',''))")
+   for i in $(seq 1 15); do
+     kill -0 $MANAGER_PID 2>/dev/null || break
+     sleep 1
+   done
+
+   # まだ生きていたら SIGTERM
+   kill $MANAGER_PID 2>/dev/null || true
+
+   # Manager ペインを閉じる
+   MANAGER_SURFACE=$(python3 -c "import json; d=json.load(open('.team/team.json')); print(d.get('manager',{}).get('surface',''))")
+   cmux close-surface --surface $MANAGER_SURFACE 2>/dev/null || true
+   ```
+
+6. **ステータスクリア**
+   - cmux clear-progress
+   - cmux のサイドバーステータスをすべてクリア
+
+7. **team.json 更新**
+   daemon の stop コマンド（手順5）が team.json の状態を自動更新する（phase: "disbanded" 等）。直接書き込みは不要。
+
+8. サマリー表示
+
+## 引数
+
+$ARGUMENTS = "force" → グレースフル終了をスキップし即座にペインクローズ
+
+## 注意事項
+
+- .team/ ディレクトリ自体は削除しない
+- マージされていない worktree ブランチがある場合は警告を表示