codebyplan 1.13.15 → 1.13.16

package/README.md

@@ -91,7 +91,7 @@ Print the CLI version.
 
 When you run Claude Code inside a [cmux](https://github.com/nicholasgasior/cmux) workspace, the `codebyplan` plugin automatically keeps the workspace metadata in sync with your git context:
 
-- **On session start** — the workspace title is set to the current git branch and the workspace description is set to the repo folder basename.
+- **On session start** — the workspace title is set to the current git branch, the workspace description is set to the repo folder basename, and the workspace color is applied from `.codebyplan/cmux.json` (configured via `/cbp-setup-cmux`). If no color is set, a one-line nudge is printed to session output.
 - **On `git checkout` / `git switch`** — the same sync runs automatically after the Bash tool call completes (the match is broad and a redundant sync on a file-restore checkout is harmless, since `codebyplan cmux-sync` is idempotent).
 
 This means your cmux workspace always reflects which branch and repo you're working in, without any manual intervention.
@@ -109,7 +109,7 @@ Both hooks delegate all logic to `codebyplan cmux-sync` — no cmux or git logic
 
 ### Binary resolution order
 
-The `cmux` binary is resolved in this order (by `codebyplan cmux-sync`):
+The `cmux` binary is resolved in this order (by `codebyplan cmux-sync` and `codebyplan cmux-status`, both delegating to `resolveCmuxBin()` in `lib/cmux.ts`):
 
 1. `$CMUX_BUNDLED_CLI_PATH` — path cmux injects into its Claude hook environment
 2. `$CMUX_CLAUDE_HOOK_CMUX_BIN` — alternative env var the hook environment may set
@@ -119,6 +119,81 @@ The `cmux` binary is resolved in this order (by `codebyplan cmux-sync`):
 
 Both hooks check for `$CMUX_WORKSPACE_ID` before doing anything. If you are not running inside a cmux workspace, the hooks exit immediately with no output and no side effects. Repos that do not use cmux are completely unaffected.
 
+### Status surface
+
+`codebyplan cmux-status` pushes CodeByPlan development state into the cmux workspace sidebar. The lifecycle skills (`cbp-task-start`, `cbp-task-complete`, `cbp-round-execute`) call it automatically — no manual invocation is needed.
+
+**Flags:**
+
+| Flag                  | Description                                                     |
+| --------------------- | --------------------------------------------------------------- |
+| `--checkpoint <text>` | Set the `cbp-checkpoint` status key                             |
+| `--task <text>`       | Set the `cbp-task` status key                                   |
+| `--qa <text>`         | Set the `cbp-qa` status key                                     |
+| `--progress <val>`    | Set the sidebar progress bar (0.0–1.0 float, or `N/D` fraction) |
+| `--clear`             | Clear all four keys from the sidebar                            |
+
+**Examples:**
+
+```bash
+# Pushed by cbp-task-start when you start a task:
+npx codebyplan cmux-status --checkpoint "CHK-176: cmux status" --task "TASK-2: implement cmux-status"
+
+# Pushed by cbp-task-complete when a task finishes:
+npx codebyplan cmux-status --task "TASK-2: implement cmux-status done" --progress 2/5
+
+# Pushed by cbp-round-execute after each round:
+npx codebyplan cmux-status --qa "R1 completed"
+
+# Clear all status keys:
+npx codebyplan cmux-status --clear
+```
+
+**`auto_status` toggle.** The command is gated by the `auto_status` field in `.codebyplan/cmux.json` (configured via `/cbp-setup-cmux`). When `auto_status` is `false`, every call is a no-op. The default is `true` — status pushing is enabled as long as the file exists or is absent (absent defaults to enabled).
+
+**No-op outside cmux.** Like `codebyplan cmux-sync`, this command checks for `$CMUX_WORKSPACE_ID` before doing anything. Outside a cmux workspace it exits immediately with no output, so it is safe to call unconditionally from scripts and hooks.
+
+### Auto dev server (`codebyplan cmux-serve`)
+
+`codebyplan cmux-serve` auto-starts the dev server for any app whose source files are touched by the current round, and opens a cmux browser pane pointing at the allocated port. `cbp-round-execute` calls it automatically at round-execution start — no manual invocation is needed.
+
+**How it works:**
+
+The command receives the round's changed file list via `--files <comma-separated paths>`. It reads `.codebyplan/server.json` `port_allocations[]` and resolves which apps' source directories intersect the file list. For each matching app it:
+
+1. Probes the allocated port (500ms `node:net` connection attempt — no `curl`, no `timeout`).
+2. If the port is **not** listening: creates a `cmux new-split down` terminal pane and sends the dev command via `cmux send`.
+3. Opens a browser pane via `cmux new-pane --type browser --url http://localhost:<port>`.
+
+If the port is already listening (another worktree, or a previously started server) it skips straight to step 3 — only the browser pane is opened. This mitigates the multi-worktree port collision by never starting a second server on an already-occupied port.
+
+**App-source-dir heuristic mapping** (from `port_allocations[].label` when `command` / `working_dir` are null):
+
+| Label                          | App dir                    |
+| ------------------------------ | -------------------------- |
+| `Web Dev`                      | `apps/web`                 |
+| `Web Dev (codebyplan-desktop)` | `apps/desktop`             |
+| `Backend Dev`                  | `apps/backend`             |
+| `MCP Dev`                      | `apps/mcp`                 |
+| `Docs Ingest`                  | `apps/docs-ingest`         |
+| `E2E Tests`                    | skipped (not a dev server) |
+
+When `allocation.command` and `allocation.working_dir` are both set (Tier 1), those values are used directly — the label heuristic is skipped. When no mapping exists for a label, one log line is emitted and the allocation is skipped; the rest continue.
+
+**`auto_dev_server` toggle.** Gated by the `auto_dev_server` field in `.codebyplan/cmux.json` (configured via `/cbp-setup-cmux`). When `auto_dev_server` is `false`, every call is a no-op. The default is `true` — the feature is enabled as long as the file is absent or the key is not explicitly set to `false`.
+
+**No-op outside cmux.** Like `codebyplan cmux-status`, this command checks for `$CMUX_WORKSPACE_ID` before doing anything. Outside a cmux workspace it exits immediately with no output and no side effects.
+
+**Examples:**
+
+```bash
+# Called automatically by cbp-round-execute with the round's files:
+npx codebyplan cmux-serve --files "apps/web/src/app/page.tsx,apps/web/src/components/Button.tsx"
+
+# Target a specific app dir instead of a file list:
+npx codebyplan cmux-serve --app apps/backend
+```
+
 ---
 
 ## MCP Server

package/dist/cli.js

@@ -14,7 +14,7 @@ var VERSION, PACKAGE_NAME;
 var init_version = __esm({
   "src/lib/version.ts"() {
     "use strict";
-    VERSION = "1.13.15";
+    VERSION = "1.13.16";
     PACKAGE_NAME = "codebyplan";
   }
 });
@@ -1987,6 +1987,11 @@ async function writeCodebyplanDirectory(projectPath, selectedRepo, deviceId) {
     JSON.stringify({}, null, 2) + "\n",
     "utf-8"
   );
+  await writeFile6(
+    join9(codebyplanDir, "cmux.json"),
+    JSON.stringify({}, null, 2) + "\n",
+    "utf-8"
+  );
   const statuslinePath = join9(codebyplanDir, "statusline.json");
   let statuslineExists = false;
   try {
@@ -2004,7 +2009,7 @@ async function writeCodebyplanDirectory(projectPath, selectedRepo, deviceId) {
   await writeLocalConfig(projectPath, { device_id: deviceId });
   console.log(`  Created ${codebyplanDir}/`);
   console.log(
-    `    repo.json, server.json, git.json, shipment.json, vendor.json, e2e.json, eslint.json, statusline.json`
+    `    repo.json, server.json, git.json, shipment.json, vendor.json, e2e.json, eslint.json, cmux.json, statusline.json`
   );
   console.log(`    device.local.json (gitignored)`);
   const gitignoreAction = await ensureManagedGitignoreBlock(projectPath);
@@ -2081,8 +2086,8 @@ async function runSetup() {
     const deviceId = await getOrCreateDeviceId(projectPath);
     let branch = "main";
     try {
-      const { execSync: execSync9 } = await import("node:child_process");
-      branch = execSync9("git symbolic-ref --short HEAD", {
+      const { execSync: execSync11 } = await import("node:child_process");
+      branch = execSync11("git symbolic-ref --short HEAD", {
         cwd: projectPath,
         encoding: "utf-8"
       }).trim();
@@ -3720,9 +3725,9 @@ async function eslintInit(repoId, projectPath) {
   Install ${missingPkgs.length} missing packages? [Y/n] `
     );
     if (confirmed) {
-      const { execSync: execSync9 } = await import("node:child_process");
+      const { execSync: execSync11 } = await import("node:child_process");
       try {
-        execSync9(installCmd, { cwd: projectPath, stdio: "inherit" });
+        execSync11(installCmd, { cwd: projectPath, stdio: "inherit" });
         console.log("  Packages installed.\n");
       } catch (err) {
         console.error(
@@ -6623,6 +6628,42 @@ var init_upload_e2e_images = __esm({
   }
 });
 
+// src/lib/cmux.ts
+import { readFileSync as readFileSync6 } from "node:fs";
+import { join as join22 } from "node:path";
+function insideCmux() {
+  return !!process.env.CMUX_WORKSPACE_ID;
+}
+function resolveCmuxBin() {
+  return process.env.CMUX_BUNDLED_CLI_PATH || process.env.CMUX_CLAUDE_HOOK_CMUX_BIN || "cmux";
+}
+function readCmuxConfig(projectRoot) {
+  let raw = {};
+  try {
+    const text = readFileSync6(
+      join22(projectRoot, ".codebyplan", "cmux.json"),
+      "utf-8"
+    );
+    raw = JSON.parse(text);
+  } catch {
+    raw = {};
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    raw = {};
+  }
+  const config = raw;
+  return {
+    ...config,
+    auto_status: config.auto_status ?? true,
+    auto_dev_server: config.auto_dev_server ?? true
+  };
+}
+var init_cmux = __esm({
+  "src/lib/cmux.ts"() {
+    "use strict";
+  }
+});
+
 // src/cli/cmux-sync.ts
 var cmux_sync_exports = {};
 __export(cmux_sync_exports, {
@@ -6632,10 +6673,10 @@ import { execSync as execSync8, execFileSync as execFileSync2 } from "node:child
 import { basename as basename2 } from "node:path";
 async function runCmuxSync() {
   try {
-    if (!process.env.CMUX_WORKSPACE_ID) {
+    if (!insideCmux()) {
       process.exit(0);
     }
-    const bin = process.env.CMUX_BUNDLED_CLI_PATH || process.env.CMUX_CLAUDE_HOOK_CMUX_BIN || "cmux";
+    const bin = resolveCmuxBin();
     let branch = "";
     try {
       branch = execSync8("git rev-parse --abbrev-ref HEAD", {
@@ -6644,8 +6685,9 @@ async function runCmuxSync() {
     } catch {
     }
     let folder = "";
+    let toplevel = "";
     try {
-      const toplevel = execSync8("git rev-parse --show-toplevel", {
+      toplevel = execSync8("git rev-parse --show-toplevel", {
         encoding: "utf8"
       }).trim();
       folder = basename2(toplevel);
@@ -6675,6 +6717,26 @@ async function runCmuxSync() {
       } catch {
       }
     }
+    try {
+      const cmuxCfg = readCmuxConfig(toplevel || process.cwd());
+      if (typeof cmuxCfg.workspace_color === "string" && cmuxCfg.workspace_color !== "") {
+        try {
+          execFileSync2(bin, [
+            "workspace-action",
+            "--action",
+            "set-color",
+            "--color",
+            cmuxCfg.workspace_color
+          ]);
+        } catch {
+        }
+      } else {
+        process.stdout.write(
+          "cmux: no workspace color set \u2014 run /cbp-setup-cmux\n"
+        );
+      }
+    } catch {
+    }
     process.exit(0);
   } catch (err) {
     if (err instanceof ProcessExitSignal) throw err;
@@ -6685,23 +6747,346 @@ var init_cmux_sync = __esm({
   "src/cli/cmux-sync.ts"() {
     "use strict";
     init_process_exit_signal();
+    init_cmux();
+  }
+});
+
+// src/cli/cmux-status.ts
+var cmux_status_exports = {};
+__export(cmux_status_exports, {
+  normalizeProgress: () => normalizeProgress,
+  runCmuxStatus: () => runCmuxStatus
+});
+import { execSync as execSync9, execFileSync as execFileSync3 } from "node:child_process";
+function normalizeProgress(raw) {
+  if (raw.includes("/")) {
+    const [numStr, denStr] = raw.split("/", 2);
+    const num = parseInt(numStr ?? "", 10);
+    const den = parseInt(denStr ?? "", 10);
+    if (!Number.isFinite(num) || !Number.isFinite(den) || den === 0) return "0";
+    const ratio = num / den;
+    const clamped2 = Math.max(0, Math.min(1, ratio));
+    return String(clamped2);
+  }
+  const f = parseFloat(raw);
+  if (!Number.isFinite(f)) return null;
+  const clamped = Math.max(0, Math.min(1, f));
+  return String(clamped);
+}
+async function runCmuxStatus(args) {
+  try {
+    if (!insideCmux()) {
+      process.exit(0);
+    }
+    let toplevel = "";
+    try {
+      toplevel = execSync9("git rev-parse --show-toplevel", {
+        encoding: "utf8"
+      }).trim();
+    } catch {
+      toplevel = process.cwd();
+    }
+    const cfg = readCmuxConfig(toplevel);
+    if (cfg.auto_status === false) {
+      process.exit(0);
+    }
+    let checkpoint;
+    let task;
+    let qa;
+    let progress;
+    let clear = false;
+    for (let i = 0; i < args.length; i++) {
+      const flag = args[i];
+      if (flag === "--checkpoint" && i + 1 < args.length) {
+        checkpoint = args[++i];
+      } else if (flag === "--task" && i + 1 < args.length) {
+        task = args[++i];
+      } else if (flag === "--qa" && i + 1 < args.length) {
+        qa = args[++i];
+      } else if (flag === "--progress" && i + 1 < args.length) {
+        progress = args[++i];
+      } else if (flag === "--clear") {
+        clear = true;
+      }
+    }
+    const bin = resolveCmuxBin();
+    if (clear) {
+      try {
+        execFileSync3(bin, ["clear-status", "cbp-checkpoint"]);
+      } catch {
+      }
+      try {
+        execFileSync3(bin, ["clear-status", "cbp-task"]);
+      } catch {
+      }
+      try {
+        execFileSync3(bin, ["clear-status", "cbp-qa"]);
+      } catch {
+      }
+      try {
+        execFileSync3(bin, ["clear-progress"]);
+      } catch {
+      }
+    } else {
+      if (checkpoint !== void 0) {
+        try {
+          execFileSync3(bin, ["set-status", "cbp-checkpoint", checkpoint]);
+        } catch {
+        }
+      }
+      if (task !== void 0) {
+        try {
+          execFileSync3(bin, ["set-status", "cbp-task", task]);
+        } catch {
+        }
+      }
+      if (qa !== void 0) {
+        try {
+          execFileSync3(bin, ["set-status", "cbp-qa", qa]);
+        } catch {
+        }
+      }
+      if (progress !== void 0) {
+        const decimalStr = normalizeProgress(progress);
+        if (decimalStr !== null) {
+          try {
+            execFileSync3(bin, ["set-progress", decimalStr]);
+          } catch {
+          }
+        }
+      }
+    }
+    process.exit(0);
+  } catch (err) {
+    if (err instanceof ProcessExitSignal) throw err;
+    process.exit(0);
+  }
+}
+var init_cmux_status = __esm({
+  "src/cli/cmux-status.ts"() {
+    "use strict";
+    init_process_exit_signal();
+    init_cmux();
+  }
+});
+
+// src/cli/cmux-serve.ts
+var cmux_serve_exports = {};
+__export(cmux_serve_exports, {
+  probePort: () => probePort,
+  runCmuxServe: () => runCmuxServe
+});
+import { execSync as execSync10, execFileSync as execFileSync4 } from "node:child_process";
+import { readFileSync as readFileSync7 } from "node:fs";
+import * as net from "node:net";
+import { join as join23 } from "node:path";
+function resolveAppDir(allocation, toplevel) {
+  if (allocation.command !== null && allocation.working_dir !== null) {
+    const wd = allocation.working_dir;
+    const dir = wd.startsWith(toplevel + "/") ? wd.slice(toplevel.length + 1) : wd;
+    return { appDir: dir, devCommand: allocation.command };
+  }
+  const label = allocation.label ?? "";
+  if (label === "E2E Tests") return { skip: "skip-e2e" };
+  if (label.includes("Web Dev") && !label.toLowerCase().includes("desktop")) {
+    return { appDir: "apps/web", devCommand: null };
+  }
+  if (label.toLowerCase().includes("desktop")) {
+    return { appDir: "apps/desktop", devCommand: null };
+  }
+  const appDir = LABEL_APP_MAP[label];
+  if (appDir !== void 0) {
+    return { appDir, devCommand: null };
+  }
+  return { skip: "no-match" };
+}
+function probePort(port) {
+  return new Promise((resolve8) => {
+    const socket = new net.Socket();
+    let settled = false;
+    const settle = (result) => {
+      if (!settled) {
+        settled = true;
+        socket.destroy();
+        resolve8(result);
+      }
+    };
+    socket.setTimeout(500);
+    socket.on("connect", () => settle(true));
+    socket.on("error", () => settle(false));
+    socket.on("timeout", () => settle(false));
+    socket.connect({ port, host: "127.0.0.1" });
+  });
+}
+async function runCmuxServe(args) {
+  try {
+    if (!insideCmux()) {
+      process.exit(0);
+    }
+    let toplevel = "";
+    try {
+      toplevel = execSync10("git rev-parse --show-toplevel", {
+        encoding: "utf8"
+      }).trim();
+    } catch {
+      toplevel = process.cwd();
+    }
+    const cfg = readCmuxConfig(toplevel);
+    if (cfg.auto_dev_server === false) {
+      process.exit(0);
+    }
+    let filesArg;
+    let appArg;
+    for (let i = 0; i < args.length; i++) {
+      const flag = args[i];
+      if (flag === "--files" && i + 1 < args.length) {
+        filesArg = args[++i];
+      } else if (flag === "--app" && i + 1 < args.length) {
+        appArg = args[++i];
+      }
+    }
+    const changedFiles = filesArg !== void 0 ? filesArg.split(",").map((f) => f.trim()).filter(Boolean) : [];
+    let serverConfig = null;
+    try {
+      const raw = readFileSync7(
+        join23(toplevel, ".codebyplan", "server.json"),
+        "utf-8"
+      );
+      serverConfig = JSON.parse(raw);
+    } catch {
+      process.exit(0);
+    }
+    const allocations = serverConfig?.port_allocations ?? [];
+    if (allocations.length === 0) {
+      process.exit(0);
+    }
+    const bin = resolveCmuxBin();
+    for (const allocation of allocations) {
+      try {
+        const resolved = resolveAppDir(allocation, toplevel);
+        if ("skip" in resolved) {
+          if (resolved.skip === "no-match") {
+            process.stdout.write(
+              `cmux-serve: no app mapping for allocation "${allocation.label ?? ""}" \u2014 skipped
+`
+            );
+          }
+          continue;
+        }
+        const { appDir, devCommand } = resolved;
+        const appDirWithSlash = appDir + "/";
+        const intersects = appArg !== void 0 && (appArg === appDir || appArg.startsWith(appDirWithSlash)) || changedFiles.some(
+          (f) => f === appDir || f.startsWith(appDirWithSlash)
+        );
+        if (!intersects) {
+          continue;
+        }
+        const port = allocation.port;
+        const listening = await probePort(port);
+        if (!listening) {
+          let shellCommand = null;
+          if (devCommand !== null) {
+            shellCommand = `cd "${join23(toplevel, appDir)}" && ${devCommand}`;
+          } else {
+            let hasDev = false;
+            try {
+              const pkgRaw = readFileSync7(
+                join23(toplevel, appDir, "package.json"),
+                "utf-8"
+              );
+              const pkg = JSON.parse(pkgRaw);
+              hasDev = typeof pkg.scripts?.dev === "string";
+            } catch {
+            }
+            if (!hasDev) {
+              process.stdout.write(
+                `cmux-serve: no "dev" script in ${appDir}/package.json \u2014 skipped
+`
+              );
+              continue;
+            }
+            shellCommand = `cd "${join23(toplevel, appDir)}" && pnpm run dev`;
+          }
+          let splitSurfaceRef = null;
+          try {
+            const splitOut = execFileSync4(
+              bin,
+              ["new-split", "down", "--json"],
+              {
+                encoding: "utf8"
+              }
+            );
+            const parsed = JSON.parse(splitOut);
+            if (typeof parsed.surface_ref === "string" && parsed.surface_ref) {
+              splitSurfaceRef = parsed.surface_ref;
+            }
+          } catch {
+          }
+          if (splitSurfaceRef !== null) {
+            try {
+              execFileSync4(bin, [
+                "send",
+                "--surface",
+                splitSurfaceRef,
+                `${shellCommand}
+`
+              ]);
+            } catch {
+            }
+          } else {
+            process.stdout.write(
+              `cmux-serve: could not resolve new split surface for ${appDir} \u2014 dev server not auto-started (open it manually)
+`
+            );
+          }
+        }
+        try {
+          execFileSync4(bin, [
+            "new-pane",
+            "--type",
+            "browser",
+            "--url",
+            `http://localhost:${port}`
+          ]);
+        } catch {
+        }
+      } catch {
+      }
+    }
+    process.exit(0);
+  } catch (err) {
+    if (err instanceof ProcessExitSignal) throw err;
+    process.exit(0);
+  }
+}
+var LABEL_APP_MAP;
+var init_cmux_serve = __esm({
+  "src/cli/cmux-serve.ts"() {
+    "use strict";
+    init_process_exit_signal();
+    init_cmux();
+    LABEL_APP_MAP = {
+      "Backend Dev": "apps/backend",
+      "MCP Dev": "apps/mcp",
+      "Docs Ingest": "apps/docs-ingest"
+    };
   }
 });
 
 // src/lib/migrate-local-config.ts
 import { mkdir as mkdir6, readFile as readFile16, unlink as unlink2, writeFile as writeFile12 } from "node:fs/promises";
-import { join as join22 } from "node:path";
+import { join as join24 } from "node:path";
 function legacySharedPath(projectPath) {
-  return join22(projectPath, ".codebyplan.json");
+  return join24(projectPath, ".codebyplan.json");
 }
 function legacyLocalPath(projectPath) {
-  return join22(projectPath, ".codebyplan.local.json");
+  return join24(projectPath, ".codebyplan.local.json");
 }
 function newDirPath(projectPath) {
-  return join22(projectPath, ".codebyplan");
+  return join24(projectPath, ".codebyplan");
 }
 function sentinelPath(projectPath) {
-  return join22(projectPath, ".codebyplan", "repo.json");
+  return join24(projectPath, ".codebyplan", "repo.json");
 }
 async function statSafe(p) {
   const { stat: stat2 } = await import("node:fs/promises");
@@ -6795,7 +7180,7 @@ async function runLocalMigration(projectPath) {
   if ("organization_id" in cfg) repoJson.organization_id = cfg.organization_id;
   if ("project_id" in cfg) repoJson.project_id = cfg.project_id;
   await writeFile12(
-    join22(projectPath, ".codebyplan", "repo.json"),
+    join24(projectPath, ".codebyplan", "repo.json"),
     JSON.stringify(repoJson, null, 2) + "\n",
     "utf-8"
   );
@@ -6808,7 +7193,7 @@ async function runLocalMigration(projectPath) {
   if ("port_allocations" in cfg)
     serverJson.port_allocations = cfg.port_allocations;
   await writeFile12(
-    join22(projectPath, ".codebyplan", "server.json"),
+    join24(projectPath, ".codebyplan", "server.json"),
     JSON.stringify(serverJson, null, 2) + "\n",
     "utf-8"
   );
@@ -6817,7 +7202,7 @@ async function runLocalMigration(projectPath) {
   if ("git_branch" in cfg) gitJson.git_branch = cfg.git_branch;
   if ("branch_config" in cfg) gitJson.branch_config = cfg.branch_config;
   await writeFile12(
-    join22(projectPath, ".codebyplan", "git.json"),
+    join24(projectPath, ".codebyplan", "git.json"),
     JSON.stringify(gitJson, null, 2) + "\n",
     "utf-8"
   );
@@ -6825,35 +7210,35 @@ async function runLocalMigration(projectPath) {
   const shipmentJson = {};
   if ("shipment" in cfg) shipmentJson.shipment = cfg.shipment;
   await writeFile12(
-    join22(projectPath, ".codebyplan", "shipment.json"),
+    join24(projectPath, ".codebyplan", "shipment.json"),
     JSON.stringify(shipmentJson, null, 2) + "\n",
     "utf-8"
   );
   filesChanged.push(".codebyplan/shipment.json");
   const vendorJson = {};
   await writeFile12(
-    join22(projectPath, ".codebyplan", "vendor.json"),
+    join24(projectPath, ".codebyplan", "vendor.json"),
     JSON.stringify(vendorJson, null, 2) + "\n",
     "utf-8"
   );
   filesChanged.push(".codebyplan/vendor.json");
   const e2eJson = {};
   await writeFile12(
-    join22(projectPath, ".codebyplan", "e2e.json"),
+    join24(projectPath, ".codebyplan", "e2e.json"),
     JSON.stringify(e2eJson, null, 2) + "\n",
     "utf-8"
   );
   filesChanged.push(".codebyplan/e2e.json");
   const eslintJson = {};
   await writeFile12(
-    join22(projectPath, ".codebyplan", "eslint.json"),
+    join24(projectPath, ".codebyplan", "eslint.json"),
     JSON.stringify(eslintJson, null, 2) + "\n",
     "utf-8"
   );
   filesChanged.push(".codebyplan/eslint.json");
   if (!deviceWrittenByHelper) {
     await writeFile12(
-      join22(projectPath, ".codebyplan", "device.local.json"),
+      join24(projectPath, ".codebyplan", "device.local.json"),
       JSON.stringify({ device_id: deviceId }, null, 2) + "\n",
       "utf-8"
     );
@@ -6865,7 +7250,7 @@ async function runLocalMigration(projectPath) {
       "Migration write incomplete: .codebyplan/repo.json was not persisted. Re-run migration to retry from a clean state."
     );
   }
-  const gitignorePath = join22(projectPath, ".gitignore");
+  const gitignorePath = join24(projectPath, ".gitignore");
   try {
     const gitignoreContent = await readFile16(gitignorePath, "utf-8");
     const legacyLine = ".codebyplan.local.json";
@@ -6927,7 +7312,7 @@ __export(config_exports, {
   runConfig: () => runConfig
 });
 import { mkdir as mkdir7, readFile as readFile17, writeFile as writeFile13 } from "node:fs/promises";
-import { join as join23 } from "node:path";
+import { join as join25 } from "node:path";
 async function runConfig() {
   const flags = parseFlags(3);
   const dryRun = hasFlag("dry-run", 3);
@@ -6960,14 +7345,14 @@ async function runConfig() {
   console.log("\n  Config complete.\n");
 }
 async function syncConfigToFile(repoId, projectPath, dryRun) {
-  const codebyplanDir = join23(projectPath, ".codebyplan");
+  const codebyplanDir = join25(projectPath, ".codebyplan");
   let resolvedWorktreeId;
   try {
     const deviceId = await getOrCreateDeviceId(projectPath);
     let branch = "main";
     try {
-      const { execSync: execSync9 } = await import("node:child_process");
-      branch = execSync9("git symbolic-ref --short HEAD", {
+      const { execSync: execSync11 } = await import("node:child_process");
+      branch = execSync11("git symbolic-ref --short HEAD", {
         cwd: projectPath,
         encoding: "utf-8"
       }).trim();
@@ -7087,6 +7472,7 @@ async function syncConfigToFile(repoId, projectPath, dryRun) {
   const vendorPayload = {};
   const e2ePayload = {};
   const eslintPayload = {};
+  const cmuxPayload = {};
   if (dryRun) {
     console.log("  Config would be updated (dry-run).");
     return;
@@ -7099,11 +7485,12 @@ async function syncConfigToFile(repoId, projectPath, dryRun) {
     { name: "shipment.json", payload: shipmentPayload },
     { name: "vendor.json", payload: vendorPayload },
     { name: "e2e.json", payload: e2ePayload, createOnly: true },
-    { name: "eslint.json", payload: eslintPayload, createOnly: true }
+    { name: "eslint.json", payload: eslintPayload, createOnly: true },
+    { name: "cmux.json", payload: cmuxPayload, createOnly: true }
   ];
   let anyUpdated = false;
   for (const { name, payload, createOnly } of files) {
-    const filePath = join23(codebyplanDir, name);
+    const filePath = join25(codebyplanDir, name);
     const newJson = JSON.stringify(payload, null, 2) + "\n";
     let currentJson = "";
     try {
@@ -7123,7 +7510,7 @@ async function syncConfigToFile(repoId, projectPath, dryRun) {
 async function readRepoConfig(projectPath) {
   try {
     const raw = await readFile17(
-      join23(projectPath, ".codebyplan", "repo.json"),
+      join25(projectPath, ".codebyplan", "repo.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -7134,7 +7521,7 @@ async function readRepoConfig(projectPath) {
 async function readServerConfig(projectPath) {
   try {
     const raw = await readFile17(
-      join23(projectPath, ".codebyplan", "server.json"),
+      join25(projectPath, ".codebyplan", "server.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -7145,7 +7532,7 @@ async function readServerConfig(projectPath) {
 async function readGitConfig(projectPath) {
   try {
     const raw = await readFile17(
-      join23(projectPath, ".codebyplan", "git.json"),
+      join25(projectPath, ".codebyplan", "git.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -7156,7 +7543,7 @@ async function readGitConfig(projectPath) {
 async function readShipmentConfig(projectPath) {
   try {
     const raw = await readFile17(
-      join23(projectPath, ".codebyplan", "shipment.json"),
+      join25(projectPath, ".codebyplan", "shipment.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -7167,7 +7554,7 @@ async function readShipmentConfig(projectPath) {
 async function readVendorConfig(projectPath) {
   try {
     const raw = await readFile17(
-      join23(projectPath, ".codebyplan", "vendor.json"),
+      join25(projectPath, ".codebyplan", "vendor.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -7178,7 +7565,7 @@ async function readVendorConfig(projectPath) {
 async function readE2eConfig2(projectPath) {
   try {
     const raw = await readFile17(
-      join23(projectPath, ".codebyplan", "e2e.json"),
+      join25(projectPath, ".codebyplan", "e2e.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -7512,10 +7899,10 @@ async function runTechStack() {
         );
       }
       try {
-        const { execSync: execSync9 } = await import("node:child_process");
+        const { execSync: execSync11 } = await import("node:child_process");
         let branch = "main";
         try {
-          branch = execSync9("git symbolic-ref --short HEAD", {
+          branch = execSync11("git symbolic-ref --short HEAD", {
             cwd: projectPath,
             encoding: "utf-8"
           }).trim();
@@ -8314,13 +8701,13 @@ var init_uninstall = __esm({
 
 // src/index.ts
 init_version();
-import { readFileSync as readFileSync8 } from "node:fs";
+import { readFileSync as readFileSync10 } from "node:fs";
 import { resolve as resolve7 } from "node:path";
 void (async () => {
   if (!process.env.CODEBYPLAN_API_KEY) {
     try {
       const envPath = resolve7(process.cwd(), ".env.local");
-      const content = readFileSync8(envPath, "utf-8");
+      const content = readFileSync10(envPath, "utf-8");
       for (const line of content.split("\n")) {
         const trimmed = line.trim();
         if (!trimmed || trimmed.startsWith("#")) continue;
@@ -8463,6 +8850,18 @@ void (async () => {
     await runCmuxSync2();
     process.exit(0);
   }
+  if (arg === "cmux-status") {
+    const { runCmuxStatus: runCmuxStatus2 } = await Promise.resolve().then(() => (init_cmux_status(), cmux_status_exports));
+    const rest = process.argv.slice(3);
+    await runCmuxStatus2(rest);
+    process.exit(0);
+  }
+  if (arg === "cmux-serve") {
+    const { runCmuxServe: runCmuxServe2 } = await Promise.resolve().then(() => (init_cmux_serve(), cmux_serve_exports));
+    const rest = process.argv.slice(3);
+    await runCmuxServe2(rest);
+    process.exit(0);
+  }
   if (arg === "config") {
     const { runConfig: runConfig2 } = await Promise.resolve().then(() => (init_config(), config_exports));
     await runConfig2();
@@ -8567,6 +8966,8 @@ void (async () => {
     codebyplan resolve-worktree      Resolve active worktree UUID from device+path+branch tuple
     codebyplan version-status        Report installed vs latest version + update guard (JSON)
     codebyplan cmux-sync             Sync cmux workspace title/description to current git branch and repo folder
+    codebyplan cmux-status           Push checkpoint/task/QA + progress to the cmux workspace sidebar
+    codebyplan cmux-serve            Auto-start dev server + browser pane for the round's app files (cmux)
     codebyplan help                  Show this help message
     codebyplan --version             Print version
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.13.15",
+  "version": "1.13.16",
   "description": "CLI for CodeByPlan — AI-powered development planning and tracking",
   "type": "module",
   "bin": {

package/templates/hooks/README.md

@@ -226,7 +226,7 @@ After a `complete_round` MCP call succeeds, reconciles the round's `files_change
 
 ### `cbp-cmux-workspace-sync.sh` — SessionStart, matcher `*`
 
-On every session start, syncs the active [cmux](https://github.com/nicholasgasior/cmux) workspace title to the current git branch and the workspace description to the repo folder basename (the directory that contains `.git/`).
+On every session start, syncs the active [cmux](https://github.com/nicholasgasior/cmux) workspace title to the current git branch, the workspace description to the repo folder basename (the directory that contains `.git/`), and applies the workspace color from `.codebyplan/cmux.json` via `cmux workspace-action --action set-color`. All three actions are delegated to `codebyplan cmux-sync`. If no `workspace_color` is configured, a one-line nudge is printed to stdout prompting the user to run `/cbp-setup-cmux`.
 
 **Blocks vs warns**: never blocks — exit 0 on every path. A SessionStart hook must never prevent a session from opening.
 
@@ -252,6 +252,28 @@ After any Bash tool call that contains a `git checkout` or `git switch` invocati
 
 ---
 
+### Auto dev server (`codebyplan cmux-serve`)
+
+At the start of each round, `cbp-round-execute` (Step 2a) calls `codebyplan cmux-serve --files "<round files>"` to auto-start the dev server for any app whose source files are touched. The subcommand probes each allocated port via `node:net`, starts a `cmux new-split` terminal pane + sends the dev command for any non-listening app, then opens a browser pane. If the port is already listening (another worktree) it only opens the browser pane. No hook registration is needed — the skill invokes the subcommand directly. Gated by `auto_dev_server` in `.codebyplan/cmux.json`; no-op outside cmux.
+
+---
+
+### Status surface (`codebyplan cmux-status`)
+
+The lifecycle skills push CodeByPlan development state into the cmux workspace sidebar via `codebyplan cmux-status`. No hook registration is needed — the skills invoke the subcommand directly:
+
+| Skill | What is pushed |
+| --- | --- |
+| `cbp-task-start` (Step 4.5) | `--checkpoint "CHK-NNN: title" --task "TASK-N: title"` |
+| `cbp-task-complete` (Step 7.3) | `--task "TASK-N: title done" --progress completed/total` |
+| `cbp-round-execute` (Step 3d) | `--qa "R{n} {status}"` where status ∈ completed / blocked / re-triggering |
+
+**`auto_status` toggle.** Gated by the `auto_status` field in `.codebyplan/cmux.json` (configured via `/cbp-setup-cmux`). When `auto_status` is `false`, every call is a no-op. Default is `true` (enabled).
+
+**No-op outside cmux.** `codebyplan cmux-status` checks for `$CMUX_WORKSPACE_ID` before doing anything. Outside a cmux workspace it exits immediately — safe to call unconditionally from skills and hooks.
+
+---
+
 ## Supporting (not registered)
 
 ### `test-hooks.sh` — invoked by `auto-test-hooks.sh`

package/templates/settings.project.base.json

@@ -124,6 +124,7 @@
       "Skill(cbp-round-update)",
       "Skill(cbp-session-end)",
       "Skill(cbp-session-start)",
+      "Skill(cbp-setup-cmux)",
       "Skill(cbp-setup-e2e)",
       "Skill(cbp-setup-eslint)",
       "Skill(cbp-ship-configure)",
@@ -135,6 +136,11 @@
       "Skill(cbp-supabase-branch-check)",
       "Skill(cbp-supabase-migrate)",
       "Skill(cbp-supabase-setup)",
+      "Skill(cbp-standalone-task-check)",
+      "Skill(cbp-standalone-task-complete)",
+      "Skill(cbp-standalone-task-create)",
+      "Skill(cbp-standalone-task-start)",
+      "Skill(cbp-standalone-task-testing)",
       "Skill(cbp-task-check)",
       "Skill(cbp-task-complete)",
       "Skill(cbp-task-create)",
@@ -196,6 +202,10 @@
       "Bash(npx codebyplan resolve-worktree:*)",
       "Bash(codebyplan cmux-sync:*)",
       "Bash(npx codebyplan cmux-sync:*)",
+      "Bash(codebyplan cmux-status:*)",
+      "Bash(npx codebyplan cmux-status:*)",
+      "Bash(codebyplan cmux-serve:*)",
+      "Bash(npx codebyplan cmux-serve:*)",
       "Bash(codebyplan version-status:*)",
       "Bash(npx codebyplan version-status:*)",
       "Bash(codebyplan statusline:*)",

package/templates/skills/cbp-round-execute/SKILL.md

@@ -57,6 +57,16 @@ Read the plan from round context (`context.planner_output`). If no plan: `No app
 
 Read effective testing profile: `round.context.testing_profile_override` if set (user override for this round only), else `task.context.testing_profile` (set by planner Phase 4.8), else default `'web'`. Pass the effective profile to all per-wave `cbp-testing-qa-agent` spawns.
 
+### Step 2a: Auto-Dev-Server (cmux)
+
+Fire the dev-server hook at round-execution start. Self-no-ops outside cmux or when `auto_dev_server` is disabled in `.codebyplan/cmux.json`.
+
+```bash
+npx codebyplan cmux-serve --files "<comma-separated approved_plan.files_to_modify[].path>"
+```
+
+The subcommand reads `.codebyplan/server.json` `port_allocations[]`, resolves which apps' source dirs intersect the round's files, probes each allocated port, and starts a cmux terminal split + browser pane for any app not already serving. Idempotent — if the port is already listening it only opens the browser pane (mitigating the multi-worktree port collision).
+
 ### Step 3: Route Execution Path
 
 Inspect `approved_plan.files_to_modify[]` and `approved_plan.round_type`. Four execution paths exist; pick the one that matches BEFORE Step 3a/3b.
@@ -143,6 +153,14 @@ If the approved plan includes database schema changes, RLS policies, or type gen
 - `status: 'blocked'` → present blocker to user via AskUserQuestion, resolve, re-spawn executor with remaining work
 - Deliverables incomplete → re-spawn executor with remaining deliverables (max 3 re-triggers). After 3 re-triggers, save partial output and proceed.
 
+### Step 3d: Push cmux QA Status
+
+Push the round's QA outcome to the cmux workspace sidebar. Self-no-ops outside cmux or when `auto_status` is disabled. Status is one of: `completed`, `blocked`, or `re-triggering`.
+
+```bash
+npx codebyplan cmux-status --qa "R{round_number} {status}"
+```
+
 ### Step 4: Dev-Server Probe (rounds 2+, web/desktop profile)
 
 When `round_number >= 2` AND `testing_profile` is `'web'` or `'desktop'` AND `files_changed` contains any UI file, probe the dev server BEFORE cbp-testing-qa-agent spawns (saves a full agent spawn when the server is down).

package/templates/skills/cbp-setup-cmux/SKILL.md

@@ -0,0 +1,170 @@
+---
+scope: org-shared
+name: cbp-setup-cmux
+description: Configure .codebyplan/cmux.json — choose workspace color and toggle auto_status / auto_dev_server. Interactive, idempotent.
+argument-hint: "[--force]"
+model: sonnet
+effort: xhigh
+allowed-tools: Read, Write, Edit, Bash(cat *), Bash(jq *), Bash(test *), Bash(mv *), Bash(git check-ignore *), Bash(cmux *), AskUserQuestion
+---
+
+# cmux Setup
+
+Configure `.codebyplan/cmux.json` so the cmux workspace integration knows which color to
+apply on session start and whether auto_status / auto_dev_server are enabled.
+
+Invoke at any time. Existing values are preserved unless `--force` is passed.
+Pass `--force` to re-ask all questions including already-configured fields.
+
+## Arguments
+
+Inspect `$ARGUMENTS` for `--force`. If present, set `force_mode = true`.
+Absent: use idempotent mode — preserve existing configured values, skip re-asking
+already-set fields.
+
+## Step 1 — Parse --force and read existing config
+
+```bash
+cat .codebyplan/cmux.json 2>/dev/null || echo '{}'
+```
+
+Capture the result as `EXISTING_JSON`. Extract existing values:
+
+```bash
+EXISTING_COLOR=$(echo "$EXISTING_JSON" | jq -r '.workspace_color // empty')
+EXISTING_AUTO_STATUS=$(echo "$EXISTING_JSON" | jq -r '.auto_status // empty')
+EXISTING_AUTO_DEV=$(echo "$EXISTING_JSON" | jq -r '.auto_dev_server // empty')
+```
+
+## Step 2 — Ask for workspace color
+
+**Idempotency gate**: skip this question if `force_mode = false` AND `EXISTING_COLOR`
+is a non-empty string. Print the preserved value and continue to Step 3.
+
+Otherwise, AskUserQuestion:
+
+```
+Workspace color for this cmux workspace
+
+Choose a named color or enter a custom hex value (#RRGGBB).
+
+Named colors:
+  A) Red        B) Crimson    C) Orange     D) Amber
+  E) Olive      F) Green      G) Teal       H) Aqua
+  I) Blue       J) Navy       K) Indigo     L) Purple
+  M) Magenta    N) Rose       O) Brown      P) Charcoal
+  Q) Custom hex — enter a value in the format #RRGGBB
+
+Enter a letter (A-Q) or type a custom hex value directly:
+```
+
+Validate the input:
+- If a letter A-P: map to the corresponding color name (e.g. "A" → "Red").
+- If "Q": prompt the user to type a custom hex value, then validate the typed value
+  against `^#[0-9A-Fa-f]{6}$`. If invalid, re-prompt once with an error. Never pass the
+  bare letter "Q" to set-color.
+- If the raw input itself already looks like a hex value: validate it against
+  `^#[0-9A-Fa-f]{6}$` and accept on match.
+- Empty input with no existing color: use no color (leave `workspace_color` as `null`).
+
+Set `NEW_COLOR` to the chosen color name / hex, or `null` if skipped.
+
+## Step 3 — Ask for auto_status and auto_dev_server toggles
+
+**Idempotency gate**: skip questions for fields that are already set (non-empty in
+existing config) when `force_mode = false`.
+
+For each unset field (or all fields when `force_mode = true`), AskUserQuestion:
+
+```
+cmux integration toggles
+
+auto_status: automatically run `cmux status` in this workspace on session start?
+  (default: on)
+  A) On
+  B) Off
+
+auto_dev_server: automatically start the dev server via cmux on session start?
+  (default: on)
+  A) On
+  B) Off
+```
+
+Ask both in a single question when both are unset. Set `NEW_AUTO_STATUS` and
+`NEW_AUTO_DEV` to `true` or `false` based on the answers.
+
+## Step 4 — Write .codebyplan/cmux.json
+
+Build the updated payload using jq deep-merge so sibling fields added by future
+schema versions are preserved. Assemble variables first.
+
+Backfill any field that the Step 2/3 idempotency gates skipped, so each `jq
+--argjson` always receives valid JSON — an empty shell variable makes `jq` exit 1,
+which would leave `NEW_PAYLOAD` empty and silently no-op the write. Fall back to the
+existing value, then to the default (`true` for the toggles):
+
+```bash
+NEW_COLOR="${NEW_COLOR:-$EXISTING_COLOR}"
+NEW_AUTO_STATUS="${NEW_AUTO_STATUS:-${EXISTING_AUTO_STATUS:-true}}"
+NEW_AUTO_DEV="${NEW_AUTO_DEV:-${EXISTING_AUTO_DEV:-true}}"
+```
+
+```bash
+NEW_COLOR_JSON=$(echo "$NEW_COLOR" | jq -R 'if . == "null" or . == "" then null else . end')
+NEW_PAYLOAD=$(jq -n \
+  --argjson color "$NEW_COLOR_JSON" \
+  --argjson auto_status "$NEW_AUTO_STATUS" \
+  --argjson auto_dev_server "$NEW_AUTO_DEV" \
+  '{workspace_color: $color, auto_status: $auto_status, auto_dev_server: $auto_dev_server}')
+```
+
+Atomic write via jq tmp+mv deep-merge (`. * $new` deep-merges, preserving any
+sibling keys not in the new payload):
+
+```bash
+jq --argjson new "$NEW_PAYLOAD" '. * $new' \
+  .codebyplan/cmux.json > .codebyplan/cmux.json.tmp \
+  && mv .codebyplan/cmux.json.tmp .codebyplan/cmux.json
+```
+
+## Step 5 — Apply color immediately
+
+If `NEW_COLOR` is a non-empty, non-null string AND cmux is available in the current
+environment (`$CMUX_WORKSPACE_ID` is set), apply the color immediately so the change
+is visible without needing to restart the session:
+
+```bash
+if [ -n "$CMUX_WORKSPACE_ID" ] && [ -n "$NEW_COLOR" ] && [ "$NEW_COLOR" != "null" ]; then
+  CMUX_BIN="${CMUX_BUNDLED_CLI_PATH:-${CMUX_CLAUDE_HOOK_CMUX_BIN:-cmux}}"
+  "$CMUX_BIN" workspace-action --action set-color --color "$NEW_COLOR" 2>/dev/null || true
+fi
+```
+
+The guard (`2>/dev/null || true`) ensures a missing or non-zero cmux never blocks
+the skill — applying the color is best-effort.
+
+## Step 6 — Verify and report
+
+Re-read `.codebyplan/cmux.json` and emit a summary:
+
+```
+cmux Setup — Complete
+
+  workspace_color : <value or "(none)">
+  auto_status     : <true|false>
+  auto_dev_server : <true|false>
+
+Config written to .codebyplan/cmux.json
+
+Next: on the next SessionStart, codebyplan cmux-sync will apply the color
+automatically. Run `/cbp-setup-cmux --force` at any time to reconfigure.
+```
+
+## Key Rules
+
+- Atomic write (tmp + mv) — never leaves cmux.json in a partial state
+- Deep-merge with `. * $new` — sibling keys from future schema versions are preserved
+- Color apply is best-effort — a missing cmux binary never causes an error
+- `auto_status` and `auto_dev_server` default to `true` when absent (documented in
+  `packages/codebyplan-package/src/lib/types.ts` CmuxConfig)
+- cmux.json is COMMITTED (not gitignored) — workspace color is shared across team members

package/templates/skills/cbp-task-complete/SKILL.md

@@ -138,6 +138,20 @@ Skip the push only when nothing was committed in Step 5 AND `/cbp-merge-main` re
 
 Call `complete_task(task_id)`. The server resolves the caller's worktree identity from the JWT/ctx and enforces the mutate-lock (CHK-140 TASK-3 — `caller_worktree_id` input field removed). The server auto-clears `assigned_user_id` + `assigned_worktree_id` on the task; if this was the last sibling task, it also clears the parent checkpoint's assignment. (Per CHK-104 hard-lock.)
 
+### Step 7.3: Push cmux Status (task done + progress)
+
+Push completion status and checkpoint progress to the cmux workspace sidebar. Self-no-ops outside cmux or when `auto_status` is disabled.
+
+Compute progress from the `get_tasks` data already loaded by the routing step: `completed = count of tasks with status 'completed'`, `total = total task count for the checkpoint`. For standalone tasks (no checkpoint), omit `--progress`.
+
+```bash
+# Checkpoint-bound task:
+npx codebyplan cmux-status --task "TASK-{N}: {task-title} done" --progress {completed}/{total}
+
+# Standalone task:
+npx codebyplan cmux-status --task "TASK-{N}: {task-title} done"
+```
+
 ### Step 8: Run Cleanup + Migration (inline)
 
 Apply the `cleanup` skill inline to remove orphan references to deleted/modified files. Then apply `migration` to propagate renames/moves to consumers. Both run without sub-agent spawns. Skip cleanup if no deletions/modifications; skip migration if cleanup handled everything.

package/templates/skills/cbp-task-start/SKILL.md

@@ -228,6 +228,14 @@ Display context summary:
 - **Previous rounds**: [count] completed
 ```
 
+### Step 4.5: Push cmux Status
+
+Push the active checkpoint and task context to the cmux workspace sidebar. Self-no-ops outside cmux or when `auto_status` is disabled in `.codebyplan/cmux.json`.
+
+```bash
+npx codebyplan cmux-status --checkpoint "CHK-{NNN}: {checkpoint-title}" --task "TASK-{N}: {task-title}"
+```
+
 ### Step 5: Set Task Status
 
 Use MCP `update_task(task_id, status: "in_progress")`.