tanuki-telemetry 1.1.3 → 1.1.5

package/bin/tanuki.mjs

@@ -67,6 +67,7 @@ ${w}  Usage:${r}
     ${cy}npx tanuki-telemetry status${r}   check if running
     ${cy}npx tanuki-telemetry setup${r}    configure claude code
     ${cy}npx tanuki-telemetry update${r}   rebuild with latest
+    ${cy}npx tanuki-telemetry skills${r}   install/update skills
     ${cy}npx tanuki-telemetry version${r}  show version
 
 ${w}  Environment:${r}
@@ -188,6 +189,46 @@ function getMcpEntry() {
   };
 }
 
+function installSkills() {
+  const skillsDir = path.resolve(path.dirname(import.meta.url.replace("file://", "")), "../skills");
+  const targetDir = path.join(os.homedir(), ".claude", "commands");
+
+  if (!fs.existsSync(skillsDir)) {
+    info("skills directory not found in package");
+    return 0;
+  }
+
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  const skills = fs.readdirSync(skillsDir).filter((f) => f.endsWith(".md"));
+  let installed = 0;
+
+  for (const skill of skills) {
+    const src = path.join(skillsDir, skill);
+    const dest = path.join(targetDir, skill);
+
+    if (fs.existsSync(dest)) {
+      // Check if ours is newer/different
+      const srcContent = fs.readFileSync(src, "utf-8");
+      const destContent = fs.readFileSync(dest, "utf-8");
+      if (srcContent === destContent) continue;
+
+      // Back up existing
+      fs.copyFileSync(dest, dest + ".bak");
+    }
+
+    fs.copyFileSync(src, dest);
+    installed++;
+  }
+
+  if (installed > 0) {
+    ok(`${installed} skill${installed > 1 ? "s" : ""} installed to ~/.claude/commands/`);
+  } else {
+    ok(`${skills.length} skills up to date`);
+  }
+  return installed;
+}
+
 function autoConfigureClaude() {
   const claudeConfig = path.join(os.homedir(), ".claude.json");
 
@@ -235,7 +276,7 @@ if (command === "start") {
   log(LOGO);
   log(BANNER);
 
-  step(1, 4, "checking requirements");
+  step(1, 5, "checking requirements");
   checkRequirements();
 
   fs.mkdirSync(DATA_DIR, { recursive: true });
@@ -254,14 +295,14 @@ if (command === "start") {
     catch { return false; }
   })();
 
-  step(2, 4, hasImage ? "docker images" : "building docker images");
+  step(2, 5, hasImage ? "docker images" : "building docker images");
   if (!hasImage) {
     info("first run — this takes ~30s...");
     buildImages();
   }
   ok(hasImage ? "cached" : "images built");
 
-  step(3, 4, "starting dashboard");
+  step(3, 5, "starting dashboard");
   startDashboard();
 
   let healthy = false;
@@ -274,21 +315,32 @@ if (command === "start") {
   }
   ok(healthy ? `running on port ${PORT}` : `starting — check port ${PORT}`);
 
-  step(4, 4, "configuring claude code");
+  step(4, 5, "configuring claude code");
   autoConfigureClaude();
 
+  step(5, 5, "installing skills");
+  installSkills();
+
   log("");
   log(`  ${d}─────────────────────────────────────────${r}`);
   log("");
-  log(`  ${w}dashboard${r}  ${cy}http://localhost:${PORT}${r}`);
-  log(`  ${w}data${r}       ${d}${DATA_DIR}${r}`);
+  log(`  ${g}${b}ready${r}`);
   log("");
-  log(`  ${y}if claude code is already open,${r}`);
-  log(`  ${y}restart it to load MCP tools.${r}`);
+  log(`  ${w}dashboard${r}   ${cy}http://localhost:${PORT}${r}`);
+  log(`  ${w}data${r}        ${d}${DATA_DIR}${r}`);
   log("");
-  log(`  ${d}npx tanuki-telemetry stop${r}`);
-  log(`  ${d}npx tanuki-telemetry status${r}`);
-  log(`  ${d}npx tanuki-telemetry update${r}`);
+  log(`  ${w}skills installed:${r}`);
+  log(`    ${g}/start-work${r}    ${d}autonomous dev — context to PR${r}`);
+  log(`    ${g}/coordinate${r}    ${d}manage cmux workspaces${r}`);
+  log(`    ${g}/walkthrough${r}   ${d}execute UI test scenarios${r}`);
+  log(`    ${g}/debug${r}         ${d}systematic bug investigation${r}`);
+  log(`    ${g}/review-code${r}   ${d}PR code review${r}`);
+  log(`    ${g}/sessions${r}      ${d}browse past sessions${r}`);
+  log(`    ${g}/create-path${r}   ${d}generate walkthrough scenarios${r}`);
+  log(`    ${g}/edit-path${r}     ${d}update walkthrough scenarios${r}`);
+  log(`    ${g}/cmux-guide${r}    ${d}workspace navigation ref${r}`);
+  log("");
+  log(`  ${y}restart claude code to load MCP tools + skills${r}`);
   log("");
 }
 
@@ -317,6 +369,13 @@ else if (command === "status") {
 else if (command === "setup") {
   log(BANNER);
   autoConfigureClaude();
+  installSkills();
+  log("");
+}
+
+else if (command === "skills") {
+  log(BANNER);
+  installSkills();
   log("");
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tanuki-telemetry",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Workflow monitor and telemetry dashboard for Claude Code autonomous agents",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   },
   "files": [
     "bin/",
+    "skills/",
     "src/",
     "frontend/src/",
     "frontend/index.html",

package/skills/cmux-guide.md

@@ -0,0 +1,197 @@
+---
+description: |
+  Reference guide for cmux workspace navigation. Consult this before ANY cmux operation — sending, reading, screenshotting, or creating workspaces.
+allowed-tools: Bash
+---
+
+# cmux Operations Guide
+
+## ⛔ Golden Rules
+
+1. **NEVER omit `--surface`.** Every read/send/send-key MUST target a specific surface.
+2. **NEVER assume a surface is Claude.** Always discover first.
+3. **Use full workspace IDs** for newer workspaces (e.g., `workspace:10` not `10`). Shorthand numbers only work reliably for original workspaces.
+4. **Always resync** after creating or closing workspaces.
+
+---
+
+## Surface Discovery (DO THIS FIRST)
+
+Workspaces have multiple surfaces — Claude terminals, browsers, dev servers, idle shells. You must find the Claude surface before doing anything.
+
+```bash
+# Step 1: List surfaces
+cmux list-pane-surfaces --workspace <id>
+
+# Step 2: Identify Claude surface
+# Look for: label contains "Claude Code" or "✳ Claude Code"
+# NOT: URLs (browser), "idle", server logs
+
+# Step 3: Verify by reading it
+cmux read-screen --workspace <id> --surface <surface_id> --lines 3
+# Should show: ❯ prompt with "bypass permissions" text
+
+# Step 4: Cache the surface ID — don't re-discover every time
+```
+
+### Signs you're on the WRONG surface:
+- ASCII art (fish, buildings) → idle Claude splash screen, actually correct but idle
+- HTML or URLs → browser surface
+- Server logs / compilation output → dev server surface
+- "Surface is not a terminal" error → browser or non-terminal surface
+- Code output from a different task → stale scrollback, might still be correct surface
+- zsh/bash prompt (e.g., `┏[user][branch]`) → Claude exited, this is a bare shell. **Do NOT send to this.** Spin up a new workspace instead.
+
+### Dead workspaces
+Claude can exit in a workspace, leaving only a shell or browser behind. If `list-pane-surfaces` shows NO "Claude Code" label, the workspace is dead. Create a new workspace instead of trying to reuse it.
+
+---
+
+## Reading Screens
+
+```bash
+# Always use --surface
+cmux read-screen --workspace <id> --surface <surface_id> --lines 10
+
+# Keep lines LOW (10-15) to protect context
+# Only go higher (30-40) if actively debugging
+```
+
+### How to tell if Claude is working vs idle:
+- **Working:** "esc to interrupt" at bottom, tool calls visible, spinner
+- **Idle:** Just `❯` prompt with "bypass permissions", no "esc to interrupt"
+- **Queued message:** "Press up to edit queued messages" — message entered but not submitted
+
+---
+
+## Sending Messages
+
+```bash
+# Step 1: Send the text
+cmux send --workspace <id> --surface <surface_id> "<message>"
+
+# Step 2: ALWAYS press Enter after
+cmux send-key --workspace <id> --surface <surface_id> Enter
+
+# Step 3: Verify it's running (wait 2-3 sec)
+cmux read-screen --workspace <id> --surface <surface_id> --lines 5
+```
+
+### Send response format:
+- `OK surface:X workspace:Y` — the workspace:Y in the response is an INTERNAL ID, not necessarily the workspace you targeted. Don't trust it for routing confirmation. Always verify by reading the screen.
+
+### Multi-line messages:
+- cmux send handles multi-line strings in quotes
+- For very long prompts, the pasted text shows as `[Pasted text #1 +N lines]`
+
+---
+
+## Creating Workspaces
+
+```bash
+# Create — use the CORRECT working directory for the task
+cmux new-workspace --cwd <path> --command "claude"
+
+# MUST wait for initialization (3-5 seconds)
+sleep 5
+
+# MUST resync
+cmux list-workspaces
+
+# MUST rename immediately so workspaces are identifiable
+cmux rename-workspace --workspace "workspace:N" "Descriptive Task Name"
+
+# MUST use full ID format for new workspaces
+cmux list-pane-surfaces --workspace "workspace:N"  # NOT just N
+
+# Discover and cache the Claude surface
+cmux list-pane-surfaces --workspace "workspace:N"
+```
+
+### Choose the right --cwd
+The `--cwd` path determines where Claude starts. **Pick the most relevant directory for the task:**
+- Working on the main app? → `--cwd ~/project` (NOT the repo root)
+- Working on a worktree? → `--cwd ~/worktrees/<worktree-name>`
+- Working on a package? → `--cwd ~/project/packages/<package-name>`
+- General/cross-cutting? → `--cwd ~/project`
+
+**Wrong cwd = confused Claude.** If Claude is in the repo root, it may not find the right files or understand the project structure. Match the cwd to where the relevant code lives.
+
+### Always rename new workspaces
+New workspaces default to "Claude Code" which is useless when you have 5+ workspaces. **Immediately rename** after creation:
+```bash
+cmux rename-workspace --workspace "workspace:N" "Short Task Description"
+```
+Keep names short but descriptive (e.g., "Benchmark Deck", "PPTX Import", "Auth Migration").
+
+### Gotcha: New workspace IDs
+- `cmux new-workspace` returns `OK workspace:N`
+- For commands like `list-pane-surfaces` and `read-screen`, use the full `"workspace:N"` string
+- `send` and `send-key` may work with just the number after surface is known, but prefer full ID
+
+---
+
+## Monitoring Workspaces
+
+### Quick status check (low context cost):
+```bash
+cmux read-screen --workspace <id> --surface <surface_id> --lines 5
+```
+
+### What to look for:
+| Screen Content | Status |
+|----------------|--------|
+| `❯` prompt + "bypass permissions" only | Idle |
+| `esc to interrupt` at bottom | Working |
+| `Worked for Xm Ys` | Just finished |
+| Tool calls / file reads visible | Actively working |
+| Error messages | Failed — needs attention |
+| "Press up to edit queued messages" | Message queued, not submitted |
+
+### Prefer telemetry over screen reads when available:
+```
+mcp__telemetry__get_session_summary({ session_id: "..." })
+```
+
+---
+
+## Screenshotting / Comparing
+
+For visual comparison of slides or UI:
+```bash
+# Take screenshot of a browser surface (not Claude surface)
+# First find the browser surface:
+cmux list-pane-surfaces --workspace <id>
+# Look for surface with URL in label
+
+# Read the browser surface for visual content
+cmux read-screen --workspace <id> --surface <browser_surface_id> --lines 40
+```
+
+---
+
+## Troubleshooting
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| "Surface is not a terminal" | Targeting a browser surface | Use `list-pane-surfaces`, pick the terminal |
+| "Workspace index not found" | Using shorthand ID | Use full `"workspace:N"` format |
+| Message sent to wrong workspace | Surface ID belongs to different workspace | Re-run `list-pane-surfaces` for the correct workspace |
+| Reading shows old/stale output | Scrollback from previous task | Check bottom of screen for idle/working indicators |
+| ASCII art fish/buildings | Claude is idle (splash screen) | This IS the Claude surface, it's just idle |
+| Send returns wrong workspace in OK | cmux internal ID ≠ workspace number | Ignore the response ID, verify by reading screen |
+
+---
+
+## Quick Reference
+
+```bash
+cmux list-workspaces                                                      # all workspaces
+cmux list-pane-surfaces --workspace "workspace:N"                         # all surfaces in workspace
+cmux read-screen --workspace "workspace:N" --surface surface:X --lines 10 # read
+cmux send --workspace "workspace:N" --surface surface:X "msg"             # send text
+cmux send-key --workspace "workspace:N" --surface surface:X Enter         # press key
+cmux new-workspace --cwd <path> --command "claude"                        # create
+cmux rename-workspace --workspace "workspace:N" "Task Name"              # rename (DO THIS immediately)
+cmux notify "message"                                                     # macOS notification
+```

package/skills/coordinate.md

@@ -0,0 +1,270 @@
+---
+description: |
+  Central coordinator mode. Become the hub that manages all cmux workspaces — dispatch work, monitor progress, and persist state across conversations.
+  Use this to initialize or resume a coordinator session.
+allowed-tools: Bash, Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, mcp__telemetry__*, mcp__linear__*
+---
+
+# Coordinate — Central Workspace Coordinator
+
+## Role
+
+You are the **central coordinator**. The user talks to you, and you manage all cmux workspaces. You do NOT write code directly — you dispatch, monitor, and integrate.
+
+## ⛔ CRITICAL RULES
+
+1. **You are the hub.** All communication to other workspaces goes through you via `cmux send` + `cmux send-key Enter`.
+2. **Be concise.** Don't dump raw screen output. Summarize what's happening in each workspace.
+3. **Protect context.** This is your biggest constraint. Minimize context usage by:
+   - Summarizing `cmux read-screen` output instead of showing it raw
+   - Using `mcp__telemetry__get_session_summary` instead of screen reads when possible
+   - Periodically compacting state (see Phase 3)
+4. **Persist state.** Save coordinator state to telemetry so you can resume across conversations.
+5. **Be proactive.** After dispatching work, monitor it without being asked. Alert the user when workspaces finish or hit errors.
+6. **Always target the Claude surface.** Run `/cmux-guide` if unsure about any cmux operation. Key rules: never omit `--surface`, use full `"workspace:N"` IDs for new workspaces, always discover surfaces before interacting. See "Surface Discovery" below.
+7. **⛔ LOG EVERYTHING TO THE LIVE FEED.** Every dispatch, every monitor check, every status change, every decision — call `mcp__telemetry__log_event` immediately. The dashboard live feed is useless without constant logging. If you did something and didn't log it, go back and log it now. Target 5+ events per user interaction. Use these event types:
+   - `action` — dispatched work, checked workspace, created workspace
+   - `decision` — chose which workspace, prioritized a task, skipped something
+   - `info` — status update, workspace completed, workspace idle
+   - `error` — workspace failed, send failed, workspace unreachable
+8. **⛔ SYNC STATE AFTER EVERY CHANGE.** Call `save_coordinator_state` after EVERY workspace status change, dispatch, or completion — not just "every 5-10 interactions". The dashboard reads state directly. Stale state = stale dashboard.
+
+---
+
+## Phase 1: Initialize
+
+### If resuming (default — check for prior state first):
+```
+state = mcp__telemetry__get_coordinator_state()
+```
+If state exists:
+- Load workspace statuses, pending tasks, decisions
+- Run `cmux list-workspaces` to verify what's actually running
+- Reconcile (workspaces may have changed since last session)
+- Present a brief status update to the user
+
+### If fresh start:
+```
+cmux list-workspaces
+```
+- Map all active workspaces
+- Create coordinator state:
+```
+mcp__telemetry__save_coordinator_state({
+  session_id: "<generated-id>",
+  state: {
+    workspaces: { ... },
+    pending_tasks: [],
+    decisions: [],
+    notes: ""
+  }
+})
+```
+- Present workspace map to user
+
+---
+
+## Surface Discovery
+
+Workspaces often have multiple surfaces (panes) — Claude terminals, web browsers, dev servers, idle shells. **You must always identify and target the Claude surface** for reads and sends.
+
+### How to discover surfaces
+```bash
+cmux list-pane-surfaces --workspace <id>
+```
+This returns all surfaces in a workspace. Identify the Claude surface by:
+- Label contains "Claude Code"
+- When read, shows the `❯` prompt with `bypass permissions` text
+- NOT a browser (URL in label), NOT a dev server (logs), NOT "idle"
+
+### Cache surface IDs
+Store the Claude surface ID per workspace in coordinator state:
+```json
+{
+  "workspace:1": { "name": "Telemetry MCP", "status": "idle", "claude_surface": "surface:2" },
+  "workspace:5": { "name": "CDD Slides", "status": "idle", "claude_surface": "surface:7" }
+}
+```
+
+### Always use `--surface`
+**Every** `read-screen`, `send`, and `send-key` command MUST include `--surface <surface_id>`:
+```bash
+cmux read-screen --workspace <id> --surface <surface_id> --lines 10
+cmux send --workspace <id> --surface <surface_id> "<text>"
+cmux send-key --workspace <id> --surface <surface_id> Enter
+```
+
+### When to re-discover
+- On initialization (Phase 1) — discover all surfaces for all workspaces
+- After creating a new workspace
+- If a `read-screen` or `send` returns an error or unexpected content (browser HTML, ASCII art, server logs)
+- If a surface ID returns "Surface is not a terminal" error
+
+### During Phase 1 initialization
+After `cmux list-workspaces`, run `cmux list-pane-surfaces --workspace <id>` for **every** workspace. Build the full surface map before presenting status.
+
+---
+
+## Phase 2: Active Coordination
+
+### Dispatching work
+When the user asks you to send work to a workspace:
+1. Get the Claude surface from state (or discover via `cmux list-pane-surfaces` if not cached)
+2. Check if workspace is idle: `cmux read-screen --workspace <id> --surface <claude_surface> --lines 5`
+3. If busy, add to `pending_tasks` in state and tell the user
+4. If idle, send via: `cmux send --workspace <id> --surface <claude_surface> "<message>"` then `cmux send-key --workspace <id> --surface <claude_surface> Enter`
+4. Log the dispatch to telemetry:
+```
+mcp__telemetry__log_event({
+  session_id: coordinator_session_id,
+  phase: "coordination",
+  event_type: "action",
+  message: "Dispatched to <workspace-name>: <summary>",
+  metadata: { workspace: "<id>", full_message: "<what was sent>" }
+})
+```
+5. Update workspace status in state
+
+### Monitoring
+When checking on workspaces:
+- **Prefer telemetry over screen reads** — `get_session_summary` is cheaper on context
+- **Screen reads for non-telemetry workspaces** — always use `--surface <claude_surface>`: `cmux read-screen --workspace <id> --surface <claude_surface> --lines 10` (not 40+)
+- **If read returns unexpected content** (HTML, ASCII art, server logs, "Surface is not a terminal") — you're on the wrong surface. Re-discover with `cmux list-pane-surfaces`
+- **Summarize aggressively** — "Telemetry MCP: building screenshot thumbnails, 3min in" not the full output
+- **⛔ Log EVERY monitor check:**
+```
+mcp__telemetry__log_event({
+  session_id: coordinator_session_id,
+  phase: "coordination",
+  event_type: "info",
+  message: "<workspace-name>: <what you observed>",
+  metadata: { workspace: "<id>", status: "<idle|working|done|failed>" }
+})
+```
+- After monitoring, update state AND call `save_coordinator_state` immediately
+
+### Session Linking (for live feed)
+The telemetry dashboard live feed shows events from all workspace sessions — but ONLY if the coordinator state has their `session_id` linked. **You must actively link sessions.**
+
+After dispatching `/start-work` to a workspace:
+1. Wait ~30 seconds for the session to be created
+2. Run `mcp__telemetry__list_sessions({ status: "in_progress", limit: 5 })`
+3. Match the new session to the workspace by worktree name
+4. Update coordinator state with the `session_id` on that workspace
+
+**Periodically re-link:** Every 5-10 interactions, run `list_sessions` and reconcile — new sessions may have been created, old ones may have completed.
+
+Without this linking, the coordinator live feed will be empty even though workspaces are logging events.
+
+### Responding to the user
+- Lead with the answer, not the process
+- Use tables for multi-workspace status
+- Don't repeat what the user said
+
+### Intent Routing (auto-detect workspace)
+
+The user will often just say what they want without naming a workspace. **You must infer the target workspace** from context. Do NOT ask "which workspace?" unless genuinely ambiguous.
+
+**Routing priority:**
+1. **Explicit name** — user says "telemetry" or "slides" → direct match
+2. **Topic match** — match keywords to workspace descriptions in state:
+   - Screenshots, dashboard, events, sessions, thumbnails → Telemetry MCP
+   - Slides, generation, template, PPTX, quality score → Slide Generation
+   - Database, JWT, auth, migration → DB Migration
+   - (Update these mappings as workspaces change)
+3. **Recency** — if user just saw output from a workspace and responds, it's about that workspace
+4. **Active work** — if only one workspace is actively working, comments about "it" or "that" refer to it
+5. **Ambiguous** — only ask if 2+ workspaces are equally likely. Present as numbered options:
+   ```
+   That could be about:
+   1. Telemetry MCP (working on thumbnails)
+   2. Slide Generation (idle, last worked on quality)
+   Which one?
+   ```
+
+**Build the keyword map from workspace state.** When saving state, include a `topics` array per workspace:
+```json
+{
+  "workspace:1": { "name": "Telemetry MCP", "topics": ["telemetry", "dashboard", "screenshots", "events", "sessions", "MCP"] },
+  "workspace:4": { "name": "Slide Generation", "topics": ["slides", "pptx", "generation", "template", "quality"] }
+}
+```
+
+**The user should feel like they're just talking, and messages magically go to the right place.**
+
+---
+
+## Phase 3: Context Management
+
+### Periodic state saves
+After EVERY workspace status change, save state immediately. At minimum every 2-3 interactions:
+```
+mcp__telemetry__save_coordinator_state({
+  session_id: coordinator_session_id,
+  state: { workspaces: {...}, pending_tasks: [...], decisions: [...], notes: "..." }
+})
+```
+
+### When context is getting heavy
+Signs: conversation is long, lots of screen reads accumulated, you're near context limits.
+
+1. Save everything important:
+```
+mcp__telemetry__compact_coordinator_context({
+  session_id: coordinator_session_id,
+  context: {
+    summary: "<what happened this conversation>",
+    decisions: ["<key decisions made>"],
+    workspace_states: { ... },
+    pending_work: ["<things still to do>"],
+    user_preferences_learned: ["<any new preferences>"]
+  }
+})
+```
+2. Tell the user: "Context is getting heavy. I've saved state — you can start a fresh `/coordinate` and I'll pick up where we left off."
+3. The user starts a new conversation and runs `/coordinate` — Phase 1 loads the saved state.
+
+---
+
+## Phase 4: Pending Task Management
+
+When a workspace finishes and has pending tasks:
+1. Check the workspace is actually idle
+2. Send the next pending task
+3. Remove from pending list
+4. Update state
+
+When the user queues something for a busy workspace:
+1. Add to `pending_tasks` with workspace ID and message
+2. Confirm: "Queued for <workspace-name> — will send when it's free"
+3. Check periodically if it's free
+
+---
+
+## Workspace Command Reference
+
+```bash
+cmux list-workspaces                                                    # see all workspaces
+cmux list-pane-surfaces --workspace <id>                                # list all surfaces in a workspace
+cmux read-screen --workspace <id> --surface <surface_id> --lines 10    # check output (ALWAYS use --surface)
+cmux send --workspace <id> --surface <surface_id> "<text>"             # send message (ALWAYS use --surface)
+cmux send-key --workspace <id> --surface <surface_id> Enter            # press Enter (ALWAYS use --surface)
+cmux new-workspace --cwd <path> --command "claude"                     # spawn new workspace
+cmux notify "<message>"                                                # macOS notification
+```
+
+**⚠️ Never omit `--surface`.** Bare commands without `--surface` will target whatever surface is "selected" — which may be a browser, dev server, or idle shell, not Claude.
+
+---
+
+## On Conversation Start
+
+Always begin with:
+1. Load prior coordinator state (or initialize fresh)
+2. `cmux list-workspaces` to get current workspace map
+3. `cmux list-pane-surfaces --workspace <id>` for **every** workspace — build the surface map
+4. Identify the Claude surface in each workspace (label contains "Claude Code", or read to verify)
+5. Cache `claude_surface` per workspace in coordinator state
+6. Quick status check on active workspaces (using `--surface` for all reads)
+7. Present status table to user (include surface IDs for reference)
+8. Ask: "What should we work on?" (or pick up pending tasks)