@hummer98/cmux-team 3.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,21 @@
+{
+  "name": "hummer98-cmux-team",
+  "owner": {
+    "name": "hummer98",
+    "email": "github@hummer98"
+  },
+  "plugins": [
+    {
+      "name": "cmux-team",
+      "source": "./",
+      "description": "Multi-agent development orchestration with Claude Code + cmux",
+      "version": "2.0.0",
+      "author": {
+        "name": "hummer98"
+      },
+      "repository": "https://github.com/hummer98/cmux-team",
+      "license": "MIT",
+      "keywords": ["cmux", "multi-agent", "orchestration", "parallel", "team"]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "cmux-team",
+  "version": "3.0.0",
+  "description": "Multi-agent development orchestration with Claude Code + cmux. Spawn, monitor, and integrate parallel sub-agents visually in terminal panes.",
+  "author": {
+    "name": "hummer98",
+    "url": "https://github.com/hummer98"
+  },
+  "homepage": "https://github.com/hummer98/cmux-team",
+  "repository": "https://github.com/hummer98/cmux-team",
+  "license": "MIT",
+  "keywords": ["cmux", "multi-agent", "orchestration", "parallel", "team"],
+  "skills": "./skills/",
+  "commands": "./commands/"
+}

package/CHANGELOG.md

@@ -0,0 +1,279 @@
+# Changelog
+
+## [3.0.0] - 2026-03-29
+
+### Added
+- npm パッケージとして配布開始 — `npm install -g @hummer98/cmux-team` でインストール可能に
+- `cmux-team` CLI コマンド — シェルから直接 `cmux-team start` で daemon を起動
+- `spawn-agent` に `--pane` オプション追加 — Conductor が自分の pane を直接指定し、Agent をタブとして確実に起動
+- TUI ダッシュボードの Agent 欄に taskTitle を表示 — role のみだった表示にタスク名を追加
+
+### Changed
+- パッケージ名を `@hummer98/cmux-team` にスコープ変更
+- `install.sh` と plugin cache フォールバックを削除（npm 配布に一本化）
+- `prepublishOnly` スクリプト追加（publish 前にテスト実行）
+- テストファイル (`*.test.ts`) を npm パッケージから除外
+
+### Fixed
+- 仕様書（docs/seeds/ + .team/specs/）を現状の実装に同期
+
+## [2.19.0] - 2026-03-29
+
+### Added
+- タスク定義と状態の分離 — `tasks/` をフラット構造に変更し、`task-state.json` で状態を管理
+
+### Fixed
+- TUI ダッシュボード: `Sep` を `Box` でラップし全セクションの1行目空白バグを修正
+- TUI ダッシュボード: Journal/Log のスペーストリム問題を修正
+- `main.ts` / `proxy.test.ts` / `proxy.ts` の TypeScript コンパイルエラー修正
+- `initInfra` の `.gitignore` テンプレートに `task-state.json` を追加
+- テンプレート・コマンド・スクリプト・テストの `tasks/open`, `tasks/closed` 参照をフラット構造に更新
+- `.claude/worktrees/` を git 管理外に変更
+
+## [2.18.1] - 2026-03-29
+
+### Fixed
+- spawn-agent でプロキシの生存確認を行い、プロキシが死んでいる場合は `ANTHROPIC_BASE_URL` を設定せず直接 API 接続にフォールバック
+- `.team/tasks/` を git 管理外にし、worktree マージ時にタスク状態が巻き戻る問題を防止
+
+## [2.18.0] - 2026-03-29
+
+### Added
+- Conductor 起動時に `--append-system-prompt-file` でロール定義をシステムプロンプトに永続化。`/clear` 後もロール定義が維持される
+
+### Fixed
+- Conductor スロット初期化時のプロンプトを明確化。曖昧な待機指示により Conductor が自主的にタスクを検索・実行してしまう問題を防止
+
+## [2.17.0] - 2026-03-29
+
+### Added
+- TODO メッセージを廃止し `create-task --status ready` に一本化。軽微な作業もタスクとして追跡可能に
+
+### Fixed
+- Agent 起動時の `--bare` フラグを除去。`--bare` が OAuth 認証をスキップし Claude Max 環境で API Usage Billing にフォールバックする問題を修正
+- TUI ダッシュボードの Tasks セクションで open タスクが表示されない問題を修正。open タスクを優先表示し、残り枠で直近の closed タスクを表示するよう変更
+- TUI ダッシュボードで長文タイトルが改行を引き起こしレイアウトが崩れる問題を修正
+
+## [2.16.0] - 2026-03-29
+
+### Added
+- Conductor テンプレートに TaskCreate/TaskUpdate によるサブタスク管理を追加。Agent の起動・完了をタスクとして追跡可能に
+- Master 起動時に `--append-system-prompt-file` でロール定義をシステムプロンプトに永続化
+
+### Fixed
+- Conductor 完了判定を done マーカーファイルのみに変更。interrupt 後に誤って done と判定される問題を修正
+
+## [2.15.1] - 2026-03-29
+
+### Fixed
+- SKILL.md の Agent 起動手順を spawn-agent CLI に統一。旧手順（cmux new-surface で直接起動）が残っており、Conductor がプロキシ設定なしで Agent を起動してしまう問題を修正
+
+## [2.15.0] - 2026-03-29
+
+### Changed
+- Conductor の Map キーを固定スロット ID（conductor-slot-1/2/3）に変更。タスク割り当てごとに ID が変わり Map エントリが重複蓄積する問題を解消
+- 起動時の surface 分割順序を修正。全 split で daemon surface を明示指定し、フォーカス状態に依存しないレイアウト構築に変更
+- 手動コマンド（/team-impl 等）から team.json 直接操作を削除し、daemon 管理に統一
+- SKILL.md を TypeScript daemon ベースのアーキテクチャに合わせて全面更新
+
+### Fixed
+- daemon リロード時にプロキシポートを再利用。既存 Conductor の ANTHROPIC_BASE_URL が旧ポートのままハングする問題を修正
+
+## [2.14.0] - 2026-03-29
+
+### Added
+- spawn-agent に `--prompt-file` オプションと `--bare` モードを追加。Agent 起動時のコンテキスト溢れを防止
+
+### Fixed
+- Conductor/Agent 起動時の環境変数が子プロセスに継承されず、Agent が API 認証エラー（Not logged in）になる問題を修正
+
+## [2.13.0] - 2026-03-29
+
+### Added
+- デバッグ用 HTTP API: プロキシサーバーに `/state`, `/tasks`, `/conductors` エンドポイントを追加。Manager 内部状態を外部から JSON で取得可能に
+- Surface 管理を固定 2x2 レイアウト + タブベースサブエージェントに再設計
+
+### Fixed
+- spawn-agent で Agent が worktree ではなくメインリポジトリで作業してしまう問題を修正
+- TUI の Conductors/Tasks セクションで1行目が表示されないバグを修正
+- YAML frontmatter パースで title のダブルクォートが除去されない問題を修正
+- Conductor テンプレート変更に合わせて template.ts の正規表現を更新
+
+## [2.12.0] - 2026-03-28
+
+### Added
+- CLI `create-task` コマンド: ID 自動採番・タスクファイル生成・Manager 通知を一括実行
+- 完了 Conductor を TUI に表示継続: surface 消失時に自動削除
+- Conductor タブ名にタスク番号を追加
+
+### Changed
+- worktree 削除を daemon から Conductor の責務に移譲
+
+### Fixed
+- closed タスク ID のゼロパディング不一致を修正
+- ジャーナルから daemon_reload イベントを除外（ログタブのみに表示）
+- TUI Tasks の表示改善: ソート順、色分け、完了時刻表示、ゼロパディング統一
+- Conductor 完了判定を2回連続 done で確定に変更（誤検知防止）
+
+## [2.11.0] - 2026-03-28
+
+### Added
+- CLI ベースの Agent spawn: `main.ts spawn-agent` コマンドで Conductor からエージェントを起動。logging proxy 統合により全出力を `.team/logs/` に記録
+- `--task-title` オプション: spawn-agent に記述的タブ名を指定可能に
+- TUI journal タブ: Conductor 完了レポートをジャーナル形式で表示。タスク履歴の振り返りが容易に
+- TUI ダッシュボードに Tasks セクション追加: タスク一覧と journal タブのレイアウトを統合
+
+### Changed
+- TUI・status のタイムスタンプをローカルタイムゾーンで表示するよう変更
+
+## [2.10.0] - 2026-03-27
+
+### Added
+- Stop hook によるイベント通知統一: Conductor 終了時に `main.ts send CONDUCTOR_DONE` で成功/失敗を Manager に通知。`hook-agent-spawned.sh` を廃止し全イベントを CLI 経由に一本化
+- `CONDUCTOR_DONE` メッセージに `success` / `reason` / `exitCode` フィールドを追加。エラー終了の検知とリカバリが可能に
+- TUI フッターにバージョン番号を表示
+
+### Changed
+- Conductor 完了時のペイン自動クローズを廃止。作業履歴の確認やデバッグが容易に
+
+### Fixed
+- TUI リロード時のクラッシュを修正（ink unmount してからプロセス再起動）
+- リロード時に `exec` でプロセスを置き換え、Master surface を保持するよう修正
+
+## [2.9.0] - 2026-03-27
+
+### Added
+- Agent surface のツリー表示: Conductor が spawn した Agent を TUI・status API・team.json にツリー構造で表示
+- PostToolUse hook による Agent 自動検出: Conductor の `cmux new-split` を hook で検出し daemon に通知。LLM の協力不要、完全に決定論的
+- Conductor 起動時に `--settings` で hook 付きカスタム設定を注入
+- daemon status API のドキュメントを共通スキル（cmux-agent-role）に追加。全ロールが `main.ts status` で daemon 状態を参照可能に
+
+### Changed
+- Master テンプレートの進捗報告を `main.ts status` に一本化（pid check + cmux read-screen の手動手順を廃止）
+
+## [2.8.0] - 2026-03-27
+
+### Added
+- TUI キーボードショートカット: `r` でリロード、`q` で終了。htop 風のキーヒントを最下段に表示
+- `r` キーで最新 plugin バージョンに自動切り替え: plugin キャッシュから最新の `main.ts` を再検索して再起動
+
+## [2.7.0] - 2026-03-27
+
+### Added
+- `main.ts status` API: daemon に依存せずダッシュボード情報を取得可能。`--log N` でログ末尾行数を指定
+- Conductor のタスクタイトル表示: TUI・status API・タブ名・team.json に反映
+- フルスクリーン TUI ダッシュボード: ターミナルサイズにレスポンシブ、ログ末尾を色分け表示
+
+### Changed
+- **マージ責務を daemon から Conductor に移動**: daemon は決定論的な worktree 削除のみ。マージ/PR は Conductor が判断・実行する。コンフリクト解決も Conductor の責務に
+- Conductor テンプレート: 完了時にローカルマージまたは PR 作成を選択可能に
+
+## [2.6.0] - 2026-03-27
+
+### Added
+- TypeScript daemon による決定論的 Manager（Claude Code セッションを廃止し、bun プロセスに完全移行）
+- TUI ダッシュボード（ink ベース）: タスク・Conductor 状態をリアルタイム表示
+- タスク依存解決: `depends_on` フィールドで依存チェーンを宣言可能
+- 優先度ソート: high > medium > low の順でタスクを実行
+- CLI インターフェース: `main.ts start/send/status/stop` で daemon を操作
+- ファイルキュー通信: `.team/queue/` 経由のメッセージパッシング（`cmux send-key` 不要に）
+- ユニットテスト 39 件: タスクパース、依存解決、キュー送受信、ユースケースシナリオ
+- E2E テストランナー: 独立 cmux workspace で実際の Claude Code を起動して検証（3 シナリオ）
+- CONTRIBUTING.md: テスト方法・リポジトリ構造・コーディング規約をコントリビューター向けに分離
+
+### Changed
+- README.md / README.ja.md を daemon アーキテクチャに合わせて全面書き直し
+- bun を前提条件に追加
+- インストール方法: plugin 推奨、skills add をフォールバックに整理
+
+### Fixed
+- テンプレート検索: `import.meta.path` からの相対パスを最優先にし、任意のプロジェクトで確実に検出
+- テンプレート未検出時: フォールバック動作を廃止し、エラー停止 + リカバリー手段を表示
+- ゼロパディング ID のタスクファイルマッチング（`startsWith("1")` が `001-*.md` にマッチしない問題）
+- Conductor spawn 後 30 秒のガード期間を追加（初期化中の誤完了判定を防止）
+
+## [2.5.0] - 2026-03-25
+
+### Added
+- `/master` コマンド: `/clear` 後に Master ロールを再読み込みする
+
+## [2.4.0] - 2026-03-25
+
+### Added
+- `/team-archive` コマンド: 完了タスクを日付ディレクトリにアーカイブ。範囲指定対応（例: `/team-archive 1-33`）
+
+## [2.3.1] - 2026-03-25
+
+### Changed
+- Master テンプレートに TODO ワークフローと cmux#2042 バリデーションを追加（ランタイムとの乖離を解消）
+- CLAUDE.md にプロンプト編集ルールを追加（テンプレートがソースオブトゥルース、ランタイム直接編集禁止）
+
+### Fixed
+- テンプレート検索で plugin キャッシュの最古バージョン (v2.0.0) が優先される問題を修正（`sort -V | tail -1` で最新を選択）
+- spawn-team.sh が Master プロンプトに common-header.md を付与していた問題を修正（Master のペイン操作が抑制されていた）
+- `/release` で旧バージョンの plugin キャッシュを削除するステップを追加
+
+## [2.3.0] - 2026-03-25
+
+### Added
+- `spawn-team.sh`: `/start` の全フェーズを一括実行するスクリプト（インフラ準備・プロンプト生成・ペイン作成・Trust 承認・team.json 更新）
+
+### Changed
+- `/start` コマンドを `spawn-team.sh` の1回呼び出しに簡素化（約20回の tool call → 1回に高速化）
+
+## [2.2.3] - 2026-03-25
+
+### Fixed
+- `/team-disband` で未マージの worktree を警告なしに強制削除していた問題を修正（未マージの変更がある場合は警告を表示し、`force` 引数がない限り削除しない）
+
+## [2.2.2] - 2026-03-25
+
+### Changed
+- `/start` 実行時に毎回 plugin キャッシュからテンプレートを再生成するよう変更（plugin 更新後にプロンプトが古いまま残る問題を解消）
+- Conductor 最大同時実行数を環境変数 `CMUX_TEAM_MAX_CONDUCTORS` で設定可能に（デフォルト: 3）
+- Conductor 終了時に session_id を manager.log に記録（`claude --resume` で事後確認可能）
+
+### Fixed
+- タスク完了時に worktree のマージを検証せずクローズしていた問題を修正（コード変更の消失を防止）
+
+## [2.2.1] - 2026-03-25
+
+### Changed
+- Conductor テンプレートを強化: 冒頭に「自分でコードを書かない」ルールを配置、`[CMUX-TEAM-AGENT]` ヘッダーを除去
+- Conductor に Agent 監視ループを追加: 30秒間隔のポーリングで Agent 完了を検出（Agent spawn 後に完了を待てない問題を解消）
+- `/release` コマンドをプロジェクトローカル (`.claude/commands/`) に移動（plugin 配布対象から除外）
+- `/release` に marketplace キャッシュ pull + plugin reinstall ステップを追加
+
+### Fixed
+- タブタイトルに surface 番号が表示されない問題を修正（`[M]` → `[58] Master` 等）
+
+## [2.2.0] - 2026-03-25
+
+### Added
+- `/release` コマンド: バージョン自動判定・CHANGELOG 更新・push・GitHub Release を一括実行
+- Conductor にレビュー判断ステップ: コード変更を伴うタスクのみ Reviewer Agent を自動起動
+- Manager に TODO ワークフロー: タスクファイル不要の軽量ジョブを `[TODO]` メッセージで即時実行
+- spawn-conductor.sh がテンプレートベースのプロンプト生成に対応（レビューフロー等がConductor に渡るように）
+- ランタイムスクリプト (`spawn-conductor.sh`, `validate-surface.sh`) を plugin 配布物に同梱
+- `/start` の Phase 0 でスクリプトを `.team/scripts/` に自動コピー
+- surface 存在検証スクリプト (`validate-surface.sh`) で cmux#2042 のフォールバック問題を回避
+
+### Changed
+- Manager テンプレートから `[CMUX-TEAM-AGENT]` ヘッダーを除去（ペイン操作が Manager の主要責務であることを明記）
+- Manager テンプレートの `[PLAN_UPDATE]` 機構を廃止し、Claude Code ネイティブの TaskCreate/TaskUpdate による TODO 管理に置換
+- `cmux rename-tab` を Claude Code 起動後に実行するよう変更（起動前だとタイトルが上書きされる問題を修正）
+- Manager のループプロトコルを改善: 毎サイクルでタスク走査を実行（Conductor 監視中の新規タスク検出漏れを防止）
+
+### Fixed
+- Manager が Conductor を起動せずサブエージェント (Agent ツール) で作業してしまう問題を修正
+- Manager モデルを Haiku から Sonnet に変更（テンプレート指示への追従性向上）
+
+## [2.0.0] - 2026-03-23
+
+### Added
+- 4層アーキテクチャ (Master → Manager → Conductor → Agent) の初期実装
+- 11 のスラッシュコマンド (`/start`, `/team-status`, `/team-impl` 等)
+- 10 のエージェントテンプレート (manager, conductor, researcher, architect 等)
+- git worktree による Agent の作業隔離
+- Manager のイベント駆動型アイドル停止
+- Claude Code Plugin としての配布対応

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cmux-team contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,238 @@
+![cmux-team](banner.jpeg)
+
+# cmux-team
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Claude Code + cmux によるマルチエージェント開発オーケストレーション。
+
+**[English README](README.md)**
+
+## なぜ cmux-team?
+
+Claude Code の組み込みサブエージェント（Agent ツール）は便利ですが、**中で何をしているか見えません**。結果だけが返ってきて、途中経過はブラックボックスです。
+
+cmux-team は、cmux のターミナル分割を使ってサブエージェントを**目に見える形で**並列実行します。
+
+**あなたがやること**: Claude に自然言語で指示するだけ。
+**Claude がやること**: cmux でペインを分割し、サブエージェントを起動・監視・統合。
+
+## 前提条件
+
+- [Claude Code](https://claude.ai/claude-code) がインストール済み
+- [cmux](https://github.com/manaflow-ai/cmux) がインストール済み
+- [bun](https://bun.sh/) がインストール済み（Manager daemon に必要）
+- cmux 内で Claude Code を実行していること
+
+## インストール
+
+```bash
+npm install -g @hummer98/cmux-team
+```
+
+## 使い方
+
+### 基本的な流れ
+
+cmux を起動し、その中で Claude Code を起動します。
+
+```
+あなた: /cmux-team:start
+  → daemon が起動し、ダッシュボードを表示
+  → Master ペインが自動作成される
+  → Master ペインに切り替えてタスクを伝える
+
+あなた: React で TODO アプリを作って
+Claude: タスクを作成しました。
+  → daemon がタスクを検出 → Conductor を起動
+  → Conductor が Agent を隣のペインに起動
+  → 各エージェントの作業がリアルタイムで見える
+
+あなた: 状況は？
+Claude: （manager.log・cmux tree を確認して報告）
+        Conductor-1: 実装中（Agent 2/3 完了）
+
+あなた: あと worktree を整理して（TODO）
+Claude: → CLI でキューに TODO を追加
+       → daemon が新しい Conductor を起動して並列実行
+```
+
+### コマンド一覧
+
+| コマンド | やること | いつ使う |
+|---------|---------|---------|
+| `/cmux-team:start` | daemon 起動 + Master spawn | セッション開始時 |
+| `/cmux-team:master` | Master ロール再読み込み | `/clear` 後 |
+| `/team-spec [概要]` | 要件をブレスト | 何を作るか決める時 |
+| `/team-research <トピック>` | 並列リサーチ | 技術調査が必要な時 |
+| `/team-design` | 設計 + レビュー | 要件が固まった後 |
+| `/team-impl [タスク\|all]` | 並列実装 | 設計が固まった後 |
+| `/team-review` | 実装レビュー | 実装が終わった後 |
+| `/team-test [scope\|all]` | テスト作成・実行 | 実装・レビュー後 |
+| `/team-sync-docs` | ドキュメント同期 | 仕様変更時 |
+| `/team-task [操作]` | タスク管理 | 設計判断・課題の記録 |
+| `/team-archive [範囲]` | 完了タスクのアーカイブ | タスク整理時 |
+| `/team-status` | チーム状態表示 | いつでも |
+| `/team-disband [force]` | 全エージェント終了 | 作業完了時 |
+
+## アーキテクチャ
+
+### 概要
+
+```
+┌─────────────────────────────────────────┐
+│  cmux-team daemon (TypeScript/bun)      │
+│  ┌───────────────────────────────────┐  │
+│  │  TUI Dashboard                    │  │
+│  │  Tasks: 2 open | Conductors: 1/3  │  │
+│  └───────────────────────────────────┘  │
+│  Queue ← Master/Hook が CLI で書き込み   │
+│  Loop  → タスクスキャン → Conductor spawn │
+│  Monitor → 完了検出 → 結果回収          │
+└───────────┬────────────┬────────────────┘
+            │            │
+     [Master]    [Conductor-035]
+     Claude Code  Claude Code
+     (Opus)       → [Agent] Claude Code
+```
+
+### daemon（TypeScript プロセス）
+
+Manager は Claude Code セッションではなく、**TypeScript の決定論的ループ**で動作します。
+
+- **ファイルキュー** (`.team/queue/`) による通信（`cmux send-key` 不要）
+- **zod** によるメッセージスキーマ検証
+- **ink** ベースの TUI ダッシュボード
+- **タスク依存解決** (`depends_on` フィールド)
+- **優先度ソート** (high > medium > low)
+
+```bash
+# daemon 操作
+./main.ts start          # 起動 + Master spawn + ダッシュボード
+./main.ts send TODO --content "worktree 整理"
+./main.ts send TASK_CREATED --task-id 035 --task-file ...
+./main.ts status         # ステータス表示
+./main.ts stop           # graceful shutdown
+```
+
+### タスクの依存関係
+
+タスクファイルの YAML frontmatter で依存を宣言できます:
+
+```yaml
+---
+id: 13
+title: 統合レポート作成
+status: ready
+depends_on: [10, 11, 12]  # 10, 11, 12 が全て完了するまで待機
+---
+```
+
+daemon は依存が解決されたタスクのみ Conductor に割り当てます。
+
+### 通信モデル
+
+| 方向 | 手段 |
+|------|------|
+| Master → daemon | CLI (`main.ts send`) → `.team/queue/*.json` |
+| daemon → Conductor | `cmux new-split` + Claude Code 起動 |
+| Conductor → daemon | SessionEnd hook → `.team/queue/*.json` + `cmux read-screen` ポーリング |
+| daemon → Master | なし（Master が `manager.log` を直接参照） |
+
+### エージェントロール
+
+| ロール | 担当 | 出力例 |
+|--------|-----|--------|
+| Conductor | タスクオーケストレーション、Agent 管理 | summary.md |
+| Researcher | 技術調査・事実収集 | 比較表、推奨事項 |
+| Architect | 技術設計 | 設計書、Mermaid 図 |
+| Reviewer | 品質チェック | Approved / Changes Requested |
+| Implementer | コーディング | コード、変更ファイル一覧 |
+| Tester | テスト作成・実行 | テストコード、実行結果 |
+
+## プロジェクト内に作られるもの
+
+`/cmux-team:start` を実行すると、プロジェクトに `.team/` ディレクトリが作られます：
+
+```
+.team/
+├── team.json          # チーム状態（自動管理）
+├── manager/           # daemon ランタイム（TypeScript）
+├── queue/             # メッセージキュー
+│   └── processed/     # 処理済みメッセージ
+├── tasks/
+│   ├── open/          # 未完了タスク
+│   ├── closed/        # 完了タスク
+│   └── archived/      # アーカイブ済み
+├── specs/             # 仕様書（git tracked）
+├── output/            # エージェント出力（gitignore）
+├── prompts/           # 生成プロンプト（gitignore）
+├── logs/              # manager.log（gitignore）
+└── scripts/           # ランタイムスクリプト
+```
+
+## Hooks 設定（推奨）
+
+`~/.claude/settings.json` に以下を追加すると、エージェントの完了時に cmux の通知リングが光ります：
+
+```json
+{
+  "hooks": {
+    "Notification": [{
+      "matcher": "",
+      "hooks": [{
+        "type": "command",
+        "command": "command -v cmux >/dev/null 2>&1 && cmux claude-hook notification || true"
+      }]
+    }],
+    "Stop": [{
+      "matcher": "",
+      "hooks": [{
+        "type": "command",
+        "command": "command -v cmux >/dev/null 2>&1 && cmux claude-hook stop || true"
+      }]
+    }]
+  }
+}
+```
+
+## トラブルシューティング
+
+### daemon が起動しない
+
+**bun がインストールされていない**: `brew install oven-sh/bun/bun` でインストール。
+
+**cmux 環境外**: cmux 内で実行してください。`CMUX_SOCKET_PATH` 環境変数が必要です。
+
+### ペインが狭くなって動作しない
+
+ペイン数が多すぎると cmux コマンドが失敗します。`/team-disband` で全エージェントを終了し、`CMUX_TEAM_MAX_CONDUCTORS=1` で Conductor 数を制限してください。
+
+### Conductor が自分で作業してしまう
+
+Conductor テンプレートに「自分でコードを書かない」ルールがありますが、守られない場合があります。テンプレートを更新するか、`/cmux-team:start` を再実行してプロンプトを再生成してください。
+
+### Conductor のセッションログを見たい
+
+```bash
+# manager.log から session_id を取得
+grep conductor-xxx .team/logs/manager.log
+# → task_completed ... session=abc-123
+
+# セッションを参照
+claude --resume abc-123
+```
+
+## 制約・既知の問題
+
+- **API レート制限**: 複数エージェント同時実行で過負荷になりやすい。Claude Max 推奨。`CMUX_TEAM_MAX_CONDUCTORS` で同時実行数を制限可能（デフォルト: 3）。
+- **ペイン幅**: ペイン数が多すぎると cmux コマンドが失敗する。
+- **初回 Trust 確認**: 新しいディレクトリで Claude を起動すると信頼確認が表示される。Conductor が自動承認を試みるが、失敗する場合は手動承認が必要。
+
+## 開発への貢献
+
+テスト方法、リポジトリ構造、コーディング規約については [CONTRIBUTING.md](CONTRIBUTING.md) を参照してください。
+
+## ライセンス
+
+MIT License - 詳細は [LICENSE](LICENSE) を参照。