# elevens

[![npm version](https://img.shields.io/npm/v/@hummer98/elevens.svg)](https://www.npmjs.com/package/@hummer98/elevens)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

c11 を基盤とした multi-agent orchestration パッケージ — [cmux-team](https://github.com/hummer98/cmux-team) の後継。

> **状態。** elevens は cmux-team の後継で、substrate を manaflow-ai/cmux から [Stage 11 Agentics の c11](https://github.com/Stage-11-Agentics/c11) に切り替えたプロジェクト。v0.9.0 (T016) でレガシー cmux backend を撤廃し、**サポート対象 substrate は c11 のみ** になりました（[Substrate](#substrate) を参照）。移行の経緯とフェーズスケジュールは [`docs/seed.md`](docs/seed.md) を参照してください。

**[English README](README.md)**

## デモ

https://github.com/user-attachments/assets/1d402a69-f48c-4a43-b52d-9c80f0f90ea1

## なぜ elevens?

Claude Code の組み込みサブエージェントは便利ですが、**中で何をしているか見えません**。結果だけが返ってきて、途中経過はブラックボックスです。

これは見た目以上に重要な問題です。エージェントが見えない状態で動くと、2つの問題が重なります：

- **異常検知が遅れる**: 何か間違っていても、作業が終わるまでわかりません。途中で介入できず、無駄なコンピューティングと時間が失われます
- **改善サイクルが回せない**: 途中の挙動が見えないと、なぜ結果が良かった・悪かったかがわからず、プロンプトやタスク設計を改善するための情報が得られません

elevens は **AI 観察箱** です。自動化ブラックボックスではありません。ターミナルペインは飾りではなく、それ自体がプロダクトです。Conductor ペインを 10 秒斜め読みするだけで、最終結果まで気づけなかった問題をその場で検出できます。

シェルから離れずに別プロジェクトの runtime 状態を覗くなら `elevens status --project-root /path/to/other`（read 系はデフォルト許可。cross-project の write 系は `--project-root-confirm` または `CMUX_TEAM_PROJECT_ROOT_CONFIRM=1` で skip 可能）。

設計原則：認知負荷を下げるのは「プロセスを隠す」ことではなく、**「プロセスを見やすくする」** ことで。

**あなたがやること**: Claude に自然言語で指示するだけ。
**Claude がやること**: c11 でペインを分割し、サブエージェントを起動・監視・統合 — すべて目の前で。

## 前提条件

- [Claude Code](https://claude.ai/claude-code) がインストール済み
- [c11](https://github.com/Stage-11-Agentics/c11) がインストール済み（v0.9.0 / T016 以降、サポート対象 substrate は c11 のみ）
- [bun](https://bun.sh/) がインストール済み（Manager daemon に必要）
- c11 内で Claude Code を実行していること
- [Nerd Font](https://www.nerdfonts.com/)（推奨）— TUI ダッシュボードのアイコン表示が向上します
  ```bash
  brew install --cask font-hack-nerd-font
  ```
  Nerd Font がなくても動作します（Unicode シンボルにフォールバック）。`CMUX_NERD_FONT=0` を設定するとフォールバックアイコンを明示的に使用できます。

## インストール

```bash
npm install -g @hummer98/elevens
```

### auto-update について

daemon は `update-notifier` で新バージョンを**検出**し、TUI バナーに表示するだけです。install は常に手動で、ユーザー自身が `npm i -g @hummer98/elevens@<latest>` を実行します（複数 Node 環境での予期しない上書きを避けるため）。

2モード（デフォルト: `off`）:

| mode | 挙動 |
|------|------|
| `off` | 何もしない（registry アクセスなし） |
| `notify` | 12h 周期で検出 → TUI バナー表示のみ |

設定（優先順位: **env > config > default**）:

- `CMUX_TEAM_AUTO_UPDATE=off|notify`（`0|false` は off として扱う）
- `.team/config.json`: `{ "autoUpdate": "off" | "notify" }`

関連:
- `NO_UPDATE_NOTIFIER=1` で無効化（update-notifier 標準の環境変数）
- 起動時ログ: `auto_update_config mode=<mode> source=<env|config|default>`

**破壊的変更（v4.5.0、T294）:**
- `task` モード（update タスクの自動起票）を削除しました。`CMUX_TEAM_AUTO_UPDATE=task|1|true` および `.team/config.json: autoUpdate: "task" | true | false` は起動時に exit 1 で reject されます。
- `elevens self-update` サブコマンドを削除しました。
- 移行: `autoUpdate` を `notify`（または `off`）に変更し、バナーが表示されたら `npm install -g @hummer98/elevens@latest` を実行してください。

### Substrate

elevens は [c11](https://github.com/Stage-11-Agentics/c11) ターミナルマルチプレクサの上で動作します。**v0.9.0 (T016) 以降、サポート対象 substrate は c11 のみ** — レガシー cmux backend と `ELEVENS_BACKEND` 環境変数は削除されました。以前 `ELEVENS_BACKEND=cmux` を pin していた場合は unset した上で c11 を導入してください:

```bash
unset ELEVENS_BACKEND
brew install --cask c11   # または Stage-11-Agentics/c11 から c11.app バンドルをダウンロード
```

elevens は `c11` バイナリを次の順で探します: (1) c11.app から launch されたときに同梱される `c11.app/Contents/Resources/bin/c11`（`CMUX_BUNDLED_CLI_PATH` で自動検出）、(2) `$PATH` 上の `c11`。これを上書きする env var はありません — `c11` が見つからない or 動作しない場合、daemon は silent fallback せず明示エラー付きで fail-fast します。

### 設定ファイル（`.team/config.json`）

`elevens start` がプロジェクトごとに自動生成します。全キーは任意で、手動編集も可能（次回 start 時に再読込されます）。共通の優先順位: **CLI フラグ > 環境変数 > `.team/config.json` > 組み込みデフォルト**。

| キー | 型 | デフォルト | 用途 |
|-----|---|----------|------|
| `mainBranch` | string | `origin/HEAD` から自動検出 | 主開発ブランチ。worktree のデフォルト起点・マージ先として使用。上書き: 環境変数 `CMUX_TEAM_MAIN_BRANCH`、CLI `--main-branch`、タスク単位の `--base-branch`。 |
| `layout` | `"wide"` \| `"16x9"` | `"16x9"` | 起動時のペインレイアウト。上書き: CLI `--layout`。 |
| `sleepPrevention` | `"off"` \| `"idle"` \| `"aggressive"` \| boolean | `"aggressive"` | macOS スリープ抑止モード。`aggressive` = `caffeinate -dis`（display + idle + system sleep を全抑止、T256 以降のデフォルト）、`idle` = `caffeinate -i`（user idle のみ抑止、display sleep は許可）、`off` = caffeinate を起動しない。boolean も後方互換で受理（`true` → `aggressive`、`false` → `off`）。上書き: CLI `--sleep-prevention <mode>` または `--no-sleep-prevention`。 |
| `autoUpdate` | `"off"` \| `"notify"` | `"off"` | バージョン検出モード（上記参照）。上書き: 環境変数 `CMUX_TEAM_AUTO_UPDATE`。 |
| `models.master` / `models.conductor` / `models.agent` | string | Claude デフォルト | ロール別モデル指定（例: `"claude-sonnet-4-6"`）。 |
| `dashboard.port` | number | `0`（ephemeral） | Web dashboard server の固定 listen port (T034)。整数 `[1, 65535]` のみ受理。固定すると daemon 再起動を跨いで URL が安定しブックマーク可能。未指定 / `0` / 不正値は ephemeral にフォールバック。詳細は `docs/spec/12-web-dashboard.md`。 |
| `dashboard.lanAccess` | boolean | `false` | Web dashboard を LAN に公開し、スマホ等の別デバイスから `/files` を閲覧できるようにする opt-in 設定。`true` で `0.0.0.0` に bind し、`.team/team.json` に `dashboardServer.lanUrl`（`http://<LAN-IP>:<port>`）を書き出して TUI の `Settings` タブ（`4` キー）に `/files` ビューワーの QR コードを表示します。厳密に `true` のときだけ有効（それ以外は `false` に倒す）。**⚠️ 認証はありません** — 到達可能なネットワーク上の誰でも `docs/` / `.team/artifacts/` / `.team/output/` と metrics API を閲覧できます。信頼できるネットワークでのみ有効にしてください。詳細は `docs/spec/12-web-dashboard.md` §2.3.1。 |
| `envrcHookPromptSkipped` | boolean | `false` | direnv hook プロンプトをスキップした際の内部フラグ。通常手動編集しません。 |
| `cmux.reservedRenameDelayMs` | number | `800` | c11 のタブ名固定タイミング調整 (T026)。reserved Conductor pane を再 rename するまでの遅延（ms、`[0, 60000]` にクランプ）。c11 の default title setter に後着で勝つための待ち時間で、将来の c11 update で title timing が変わったら延長する。 |

例:

```json
{
  "mainBranch": "develop",
  "layout": "16x9",
  "sleepPrevention": "idle",
  "autoUpdate": "notify",
  "models": { "conductor": "claude-sonnet-4-6" }
}
```

解決順や自動検出の詳細は `docs/spec/05-install-and-infrastructure.md` を参照してください。

## 使い方

### 基本的な流れ

c11 を起動し、その中で Claude Code を起動します。

```
$ elevens start
  → daemon が起動し、ダッシュボードを表示
  → Manager / Master ペインが作成され、Conductor も起動される
  → Master ペインに切り替えてタスクを伝える

あなた: React で TODO アプリを作って
Claude: タスクを作成しました。
  → daemon がタスクを検出 → idle Conductor に割り当て
  → Conductor が Agent を同じペインのタブとして起動
  → 各エージェントの作業がリアルタイムで見える

あなた: 状況は？
Claude: （manager.log・cmux tree を確認して報告）
        Conductor-1: 実装中（Agent 2/3 完了）

あなた: あと worktree を整理して
Claude: → elevens create-task --title "..." --status ready
       → daemon が別の idle Conductor に割り当てて並列実行
```

### コマンド一覧

#### CLI コマンド（ターミナルで実行）

完全なリストは `elevens --help` を参照。主要なコマンド:

**ライフサイクル**
| コマンド | やること |
|---------|---------|
| `elevens start` | daemon 起動 + Master + Conductor spawn（レイアウト消失時は自己修復） |
| `elevens status` | チーム状態表示 |
| `elevens --version` | バージョン表示 |

> 注記: `elevens stop` は v4.3.0 で廃止されました。cmux セッション終了時に daemon が自動停止します（pidfile が release される）。手動停止したい場合は `kill <pid>`（PID は `.team/daemon.pid`）。

**タスク管理**
| コマンド | やること |
|---------|---------|
| `elevens create-task --title <t> [--status ready] [--body <b>] [--depends-on <ids>] [--base-branch <branch>] [--run-after-all] [--exclusive] [--epic-id <Eid>]` | タスク作成（`--base-branch`: worktree の起点・マージ先ブランチ、デフォルト: main。`--exclusive`: drain 後に単独実行、`--run-after-all` を含む。`--epic-id`: 親 Epic とリンク、例 `E001`） |
| `elevens update-task --task-id <id> --status <s>` | タスク状態更新 |
| `elevens close-task --task-id <id> --deliverable-kind <files|merged|pr|none> [kind 別フラグ] [--journal <text>] [--force]` | タスク close。`--force` 指定時は `aborted` → `closed` の上書きを許可（AI 判定誤りを人間が救済する経路。reducer は `task_closed_from_aborted` を log し `prev_aborted_at` を残す） |
| `elevens abort-task --task-id <id>` | 実行中タスクを中止 |
| `elevens restart-task --task-id <id>` | assigned タスクの Conductor を再起動 |
| `elevens delete-task --task-id <id>` | draft / ready タスクを削除 |
| `elevens await-task --task-id <id> [--timeout <sec>]` | タスク完了待ち |

> **ベースブランチ (`--base-branch`)**: デフォルトでは各タスクの worktree は `mainBranch`（解決順: 環境変数 `CMUX_TEAM_MAIN_BRANCH` → `config.mainBranch` → `origin/HEAD`）から切られ、Conductor はそれをマージ先として扱います。`--base-branch develop` を渡すと代わりに `develop` から切って `develop` に戻します — hotfix や main 以外の feature ブランチに対する作業向け。起点の解決順位: 明示指定 `--base-branch` → local `<mainBranch>`（origin より ahead）→ `origin/<mainBranch>` → local `<mainBranch>` → `HEAD`（詳細は `docs/spec/05-install-and-infrastructure.md`）。

**Epic（PoC — Phase 1）**

Task / Artifact と並ぶ第三のカテゴリ。「達成したいゴール」を、自律エージェントである **Epic Planner**（Phase 1 では `/loop` で手動起動）が Task に分解して進めます。詳細は `docs/spec/14-epic.md` 参照。

| コマンド | やること |
|---------|---------|
| `elevens epic create --title <t> [--body <intent>] [--budget-token <n>] [--budget-iteration <n>] [--budget-hours <h>]` | 新規 Epic を作成（`status=active`、budget 上限は任意） |
| `elevens epic list [--status active\|blocked\|closed\|aborted\|all]` | Epic 一覧（status で filter 可） |
| `elevens epic show <Eid>` | frontmatter + body + 配下 Task（`--epic-id` でリンクされた Task）を表示 |
| `elevens epic resume <Eid> [--budget-token <n>] [--budget-iteration <n>] [--budget-hours <h>] [--journal <text>]` | `blocked → active`（必要なら budget 増額） |
| `elevens epic abort <Eid> [--journal <text>]` | `active`/`blocked` → `aborted` |

> Phase 1 PoC スコープ: CLI + epic.md + Planner template + 手動 `/loop`。daemon 統合 / 自動 spawn / abort cascade / budget hard enforcement は Phase 2。

**Integration Queue / Integrator（PoC — Phase 1）**

開発の後工程レーン。Conductor は PR 納品（`deliverable=pr`）で終え、単一の **Integrator**（Phase 1 では `/loop` で手動起動）が closed PR をキューから pull します。`main` / deploy / 実機を触れるのは Integrator だけで、single-writer パターンにより統合を構造的に直列化します。採用は per-project の opt-in（base Conductor template はデフォルトでローカルマージのまま）。詳細は `docs/spec/17-integration-queue.md` 参照。

| コマンド | やること |
|---------|---------|
| `elevens integ enqueue --task <id> [--pr <url>] [--branch <name>] [--force]` | closed な `deliverable=pr` Task を統合 item（`Qnnn`）として投入 |
| `elevens integ list [--state queued\|integrating\|verifying\|done\|failed\|all]` | item 一覧（state で filter 可） |
| `elevens integ show <Qid>` | item 詳細を表示 |
| `elevens integ update <Qid> --state <state> [--batch <B>] [--artifact <A>] [--followup <id>] [--retry-inc] [--reason <text>]` | FSM 遷移（5 状態。`done`/`failed` は `--artifact` 必須、`failed` は `--followup` も必須） |

> Phase 1 PoC スコープ: CLI + Item FSM + Integrator template + opt-in な Conductor pr 納品注記。daemon auto-enqueue / イベント駆動 Integrator spawn / staging release-train / deploy guardrail hook は Phase 2。

**Agent / Conductor**
| コマンド | やること |
|---------|---------|
| `elevens spawn-conductor [--resume <session-id>] [--task-prompt <path>]` | 現在の surface で Conductor を起動・登録（proxy 自動解決）。CONDUCTOR_REGISTERED で自己登録。T421: `--resume` も統合（旧 `elevens conductor` / `elevens resume` を置換） |
| `elevens spawn-agent --conductor-surface <s> --role <r> --prompt <p>` | Agent タブを起動 |
| `elevens agents` | 稼働中エージェント一覧 |
| `elevens close-agent --surface <s>` | Agent を正常終了 |
| `elevens kill-agent --surface <s>` | Agent を強制停止（crash 扱い） |
| `elevens send-agent --surface <s> <message>` | Agent / Conductor にメッセージ送信 |
| `elevens spawn-master` | Master 起動（proxy 自動解決） |
| `elevens reset-conductor [--surface <s>] [--force]` | 任意状態の Conductor をそのレーンに閉じて `reserved` に局所復旧する CLI（surface ターミナルから自分自身を呼び戻す想定）。`--surface` 省略時は `CMUX_SURFACE` から自動解決。`assigned` 中は `--force` 必須で、対象タスクは `reason=reset_conductor` で aborted + cascade。`SESSION_CLEAR(running)` 経路と対称 |
| `elevens clear-conductor [--surface <s>]` | `broken` 状態の Conductor をプールから外す。surface は**一切閉じない** — entry を削除し `maxConductors` を 1 減算、その surface からの再登録を拒否する（daemon 再起動 / `cmux-team start` でリセット）。`--surface` 省略時は `CMUX_SURFACE` から自動解決。クリアできるのは `broken` のみで、他状態は `reset-conductor` / `abort-task` / `restart-task` を使う |
| `elevens clear-master --surface <s>` | Master（状態不問）をプールから外す。surface は**一切閉じない**: Master entry を削除し master ファイルを削除、watcher 停止、再登録を拒否する（daemon 再起動でリセット）。新しい Master を立てるには `spawn-master` または `reset-master` |
| `elevens reset-master --surface <s>` | Master を作り直す: 古い Master を外し（surface 非 close）、新しい Master を新 pane で spawn する。`disconnected` で居座った Master を解消する主力経路 |

**トークンプール**
| コマンド | やること |
|---------|---------|
| `elevens token add` | manual API key を対話式で登録（トークンを貼り付け） |
| `elevens token add --subscription <handle> [--plan max-x20] [--tags any]` | Claude Max / subscription トークンを登録（keychain snapshot を取らず Claude Code 管理の OAuth に委ねる） |
| `elevens token list` | 登録済みトークンと 5h/7d 使用率を表示 |
| `elevens token remove --handle <h>` | トークンを削除 |
| `elevens token rotate --handle <h>` | credential を再取得して auth hash を更新 |
| `elevens token set-plan --handle <h> --plan <p>` | plan / ratio を手動設定 |
| `elevens token promote --handle <h>` | auto-discover トークンを selectable に昇格 |
| `elevens token migrate-subscription` | subscription row 用の cmux-team-token keychain エントリを一括削除（冪等） |
| `elevens pool status` | pool capacity ダッシュボードを表示 |

#### manual と subscription の違い

- **`manual`** — 永続的な API key。elevens が macOS keychain（service `cmux-team-token`）にトークンを保存し、spawn したエージェントへ `CLAUDE_CODE_OAUTH_TOKEN` を inject する。
- **`--subscription`** — Claude Max などの subscription。Claude Code 本体が `~/.claude/.credentials.json` で OAuth を管理し、必要に応じてトークンを refresh する。elevens は keychain snapshot を持たず、agent にトークンを inject しない — 認証は Claude Code に委ね、proxy 経由でリクエストを観測して使用率を追跡するのみ。subscription 由来の handle はすべてこちらを使う。

**診断・補助**
| コマンド | やること |
|---------|---------|
| `elevens trace-task <task-id>` | タスクのセッション履歴を表示 |
| `elevens trace-hooks` | hook シグナル履歴を表示 |
| `elevens artifacts [add\|show\|open\|search]` | アーティファクト管理 |
| `elevens metrics [--since <range>] [--group-by day]` | タスク lifecycle / tool call / token の集計サマリ（詳細は `docs/spec/11-metrics.md`） |
| `elevens metrics snapshot\|compare\|health\|query` | daily snapshot / cohort 比較 / health check / DuckDB ad-hoc query |
| `elevens events [--follow] [--types <names>] [--format json\|tsv]` | events stream（`.team/logs/events.jsonl`）を tail / filter |
| `elevens events emit --type <name> [--message <text>] [--actor <id>] [--data k=v]...` | events stream に free-form な user signal を append（best-effort、daemon 停止中でも動作）。`docs/spec/10-events-stream.md` §6.20 参照 |

#### スラッシュコマンド（Claude 内で実行）

| コマンド | やること | いつ使う |
|---------|---------|---------|
| `/master` | Master ロール再読み込み | `/clear` 後 |
| `/elevens:watch` | events stream を監視して PR merge（squash）/ `git pull --ff-only` を自動処理（opt-in）。conflict は自動解決せず escalate して停止 | 完了した PR の自動 merge と介入要 event のエスカレーションを Master に任せたい時 |
| `/team-spec [概要]` | 要件をブレスト | 何を作るか決める時 |
| `/team-task [操作]` | タスク管理 | タスクの作成・一覧・クローズ |
| `/team-archive [範囲]` | 完了タスクのアーカイブ | タスク整理時 |
| `/artifact [type] "タイトル"` | 知見をアーティファクトとして保存 | 調査・判断の記録 |
| `/docs-sync [--dry-run\|--auto]` | `docs/spec/` を実装と同期 | ドキュメント整備 |
| `/trace-task <task-id>` | タスクのセッション履歴を分析 | デバッグ・レビュー |

## アーキテクチャ

### 概要

```
┌─────────────────────────────────────────┐
│  elevens 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 の決定論的ループ**で動作します。

- **HTTP メッセージキュー**（内蔵 proxy 経由、`elevens send <TYPE>`）— イベント駆動
- **ファイルベースのタスク状態**（`.team/tasks/` + `task-state.json`）
- **zod** によるメッセージスキーマ検証
- **ink** ベースの TUI ダッシュボード
- **Web ファイルビューワー** (`/files`) — `docs/` / `.team/artifacts/` / `.team/output/` をブラウザで 2 ペイン閲覧（Markdown レンダリング・HTML レポート/画像表示・更新日時ソート・タイプフィルター）。**時系列モード**（`time` チップ）では 3 ルートを横断して更新が新しい順にタイトルで一覧でき、ペイン間の仕切りはドラッグで幅変更できます（どちらも `localStorage` に保存）。URL は `.team/team.json` の `dashboardServer.url` + `/files`。`elevens open <file>` で開いているタブが該当ファイルに自動追従（タブを増やさない）。`dashboard.lanAccess: true` にするとスマホから LAN 経由で閲覧できます（TUI `Settings` タブに QR コード。**認証は無い**点に注意）
- **タスク依存解決** (`depends_on` フィールド)
- **優先度ソート** (high > medium > low)
- **Agent 完了は fs.watch**（Agent の Stop / SessionEnd hook が done マーカーを書き、Conductor が `elevens await-agent` で待機。busy polling 不要、T181）

```bash
# daemon 操作
elevens start                                            # 起動 + Master spawn + ダッシュボード
elevens send TASK_CREATED --task-id 035 --task-file .team/tasks/035-xxx/task.md
elevens status                                           # ステータス表示
# daemon は cmux 終了で自動停止。手動停止は `kill <pid>` で（PID は `.team/daemon.pid`）
```

### タスクの依存関係

タスクファイルの YAML frontmatter で依存を宣言できます:

```yaml
---
id: 13
title: 統合レポート作成
status: ready
depends_on: [10, 11, 12]  # 10, 11, 12 が全て完了するまで待機
---
```

daemon は依存が解決されたタスクのみ Conductor に割り当てます。

### 通信モデル

| 方向 | 手段 |
|------|------|
| Master → daemon | `elevens send <TYPE>` → proxy 経由の HTTP メッセージ |
| daemon → Conductor | `cmux send`（`/clear` + 新プロンプト。Conductor ペインは常駐） |
| daemon ← Conductor | done マーカーファイル（`.team/conductors/<id>/done`）+ SESSION_* hook メッセージ |
| Conductor → Agent | `elevens send-agent` / `spawn-agent`（`cmux send` の直接呼び出しは hook でブロック） |
| Conductor ← Agent | `elevens await-agent`（Agent done マーカーを fs.watch） |
| daemon → Master | なし（Master が `manager.log` / `task-state.json` を直接参照） |
| daemon → 外部 reader | events stream（`.team/logs/events.jsonl`、JSONL append-only）— opt-in。`elevens events --follow` / Master `/elevens:watch` が購読 |

### エージェントロール

| ロール | 担当 | 出力例 |
|--------|-----|--------|
| Conductor | タスクオーケストレーション、Agent 管理 | summary.md |
| Researcher | 技術調査・事実収集 | 比較表、推奨事項 |
| Architect | 技術設計 | 設計書、Mermaid 図 |
| Reviewer | 品質チェック | Approved / Changes Requested |
| Implementer | コーディング | コード、変更ファイル一覧 |
| Tester | テスト作成・実行 | テストコード、実行結果 |

## プロジェクト内に作られるもの

`elevens start` を実行すると、プロジェクトに `.team/` ディレクトリが作られます：

```
.team/
├── team.json          # チーム構成（daemon が自動更新）
├── task-state.json    # タスク状態（status: draft/ready/assigned/closed）
├── tasks/             # タスクファイル（TNNN-slug/ にタスク本体と runs/）
│   └── archived/      # アーカイブ済み（closed → archived）
├── artifacts/         # 知見の記録（Axxx 番号付き、直接ファイル作成可）
├── agent-instructions/ # Agent ロール別の project-local overlay
├── specs/             # 仕様書（git tracked）
├── conductors/        # Conductor 状態ファイル + agent-done/ マーカー
├── sessions/          # セッション情報
├── output/            # エージェント出力（taskRunId 別、gitignore）
├── prompts/           # プロンプト監査証跡（gitignore）
├── logs/              # manager.log + traces/bodies/（gitignore）
├── traces/            # SQLite FTS5 トレース DB
├── daemon.heartbeat   # 10s 間隔の sync write（daemon 死亡時刻の証拠、v0.8）
├── logs/manager.stderr.log     # daemon の stderr redirect（Bun panic も拾う、v0.8）
├── logs/manager.telemetry.jsonl # 30s 間隔 RSS/heap/event loop trajectory（v0.8）
└── proxy-port         # プロキシポート番号
```

`daemon.heartbeat` と `logs/manager.{stderr,telemetry.jsonl,log}` は daemon が無言で死亡した時の事後分析用 evidence。詳細は `docs/spec/15-post-mortem-evidence.md` を参照。

## プロジェクト固有の追加指示

10 個の overlay 対応ロール（researcher / architect / planner / design-reviewer / implementer / inspector / dockeeper / task-manager / **master / conductor**）に対してプロジェクト固有の追加指示を `.team/agent-instructions/<role>.md` に置くと、対応するプロンプトに自動的に組み込まれます:

- **Agent ロール (8)** — `elevens spawn-agent` 実行時に Agent prompt-file 内の `{{PROJECT_INSTRUCTIONS}}` を置換します。
- **master / conductor (T342)** — daemon 起動時に `generateMasterPrompt` / `generateConductorRolePrompt` が `.team/prompts/master.md` / `.team/prompts/conductor-role.md` 生成時に展開する shared system prompt overlay として機能します。`elevens spawn-agent --role master` / `--role conductor` は exit 1（"reserved" エラー）となり、agent としては spawn できません。

```bash
# overlay を書き込む
elevens set-agent-instructions --role implementer --from-file ./my-impl-notes.md
elevens set-agent-instructions --role researcher --body "調査対象は 2025 年以降の論文に限る"
elevens set-agent-instructions --role master --body "進捗は常に 3 行でまとめること"
elevens set-agent-instructions --role conductor --from-file ./conductor-overlay.md

# 内容確認 / 一覧
elevens get-agent-instructions --role implementer
elevens list-agent-instructions

# 削除
elevens delete-agent-instructions --role implementer
```

overlay の最大サイズは 100 KB。dashboard TUI の `Settings` タブ（`4` キー）で全 10 ロールの overlay 状況と config をプレビューできます。

## 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"
      }]
    }]
  }
}
```

## トークンプール

複数の Claude アカウントを持っている場合、Agent spawn を自動的に振り分けてレート制限を回避できます。

**有効化**（opt-in、プロジェクト単位）:

```json
// .team/config.json
{ "tokenPool": { "enabled": true } }
```

または環境変数: `CMUX_TEAM_TOKEN_POOL=1`。

**トークン登録**（`manual` は macOS Keychain 必須。`subscription` は keychain を使わない）:

```bash
# Manual API key（対話式、keychain に保存）
elevens token add

# Claude Max subscription（keychain を使わず、認証は Claude Code 管理）
elevens token add --subscription @tayo --plan max-x20 --tags any

elevens token list     # 5h/7d 使用率とともに全トークンを表示
```

**選択アルゴリズム**（Agent spawn ごと）:

1. `policy.exclude` に含まれる handle を除外
2. lease 中（120 秒）または `util_5h > 95%` のトークンを除外
3. 以下の順で admit: `projectDefault` 一致 → `include` リスト → `isOss` フラグ → tag マッチ（`"any"`）
4. スコア = `0.3 × util_5h + 0.7 × util_7d` — 最小値を選択

TUI dashboard ヘッダーには **7 日 forecast スパークライン**（Day 0..6 の日次割当、100% = BLOCKER_7D (=0.95) を上限とした sustainable pace）と次に spawn-agent が選ぶ **next 候補** を表示します:

```
pool 7d  ██▇▅▅▆█   next: @kddi 5h:65%
```

per-surface decoration（`@handle <5h:X%/7d:Y%> cap:Z%`）は撤去し、ヘッダー集約に一本化しました。アカウント別の詳細は `elevens pool status` で確認してください。

詳細（tag フィルタ・exclude/include ポリシー・plan ratio）は `docs/spec/09-token-pool.md` を参照。

## トレーサビリティ

daemon 起動中、組み込みプロキシを通じて全 API リクエストが自動記録されます。

### タスクのセッション履歴

```bash
# 特定タスクのセッション一覧（Conductor + Agent）
elevens trace-task 035
```

トレースは `.team/traces/traces.db` に、リクエスト/レスポンス本文は `.team/logs/traces/bodies/` に保存されます。メタデータヘッダー（`x-cmux-task-id`, `x-cmux-conductor-surface`, `x-cmux-role`）が伝播されるため、API リクエストを起票元タスクと紐付けられます。

### Daemon が無言で死んだときの事後分析（v0.8）

daemon が原因不明でクラッシュした場合に WHEN/WHAT/WHY を再構成するための evidence が `.team/` 配下に残ります。

- `.team/daemon.heartbeat` — 10s 間隔の sync write。残存していれば異常終了の証拠、mtime が死亡時刻 (±10s)
- `.team/logs/manager.telemetry.jsonl` — 30s 間隔の RSS / heap / event loop lag の trajectory（leak 型 OOM 検出用）
- `.team/logs/manager.stderr.log` — daemon の OS fd 2 redirect（Bun runtime panic / Rust panic / libc abort も残る）
- `.team/logs/manager.log` の `fatal_uncaught` / `signal_received` event — JS 例外 / signal 受信の sync 記録

事後分析 cookbook（コマンド例つき）と config override（`.team/config.json` の `postMortem.*`）は `docs/spec/15-post-mortem-evidence.md` を参照。

## トラブルシューティング

### daemon が起動しない

**bun がインストールされていない**: `brew install oven-sh/bun/bun` でインストール。

**c11 環境外**: c11 内で実行してください。`CMUX_SOCKET_PATH` 環境変数が必要です。

### ペインが狭くなって動作しない

ペイン数が多すぎると cmux コマンドが失敗します。cmux セッションを終了（daemon は自動停止）してから `CMUX_TEAM_MAX_CONDUCTORS=1` を設定して再起動してください。

### Conductor が自分で作業してしまう

Conductor テンプレートに「自分でコードを書かない」ルールがありますが、守られない場合があります。テンプレートを更新するか、`elevens 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 が自動承認を試みるが、失敗する場合は手動承認が必要。

## テスト

> **⚠️ manager ディレクトリ全体への `bun test` は実行しないでください。**
> 全件実行は O(N²) 級に劣化し、30 分以上ハングします
> （詳細は `.team/artifacts/A021-research.md`）。代わりに個別ファイル iteration を使ってください:
>
> ```bash
> cd skills/cmux-team/manager
> for f in *.test.ts state-machine/*.test.ts dashboard-*.test.tsx; do
>   bun test --timeout 30000 "$f" || echo "FAIL: $f"
> done
> ```
>
> CI (`.github/workflows/test.yml`) は PR と main push 時に同じループを実行します。
> 根本原因（module-level singleton の累積）が修正されたら通常実行に戻す予定です。

## 開発への貢献

テスト方法、リポジトリ構造、コーディング規約については [CONTRIBUTING.md](CONTRIBUTING.md) を参照してください。

## ライセンス

MIT License - 詳細は [LICENSE](LICENSE) を参照。