codebyplan 1.13.50 → 1.13.52

package/dist/cli.js

@@ -39,7 +39,7 @@ var VERSION, PACKAGE_NAME;
 var init_version = __esm({
   "src/lib/version.ts"() {
     "use strict";
-    VERSION = "1.13.50";
+    VERSION = "1.13.52";
     PACKAGE_NAME = "codebyplan";
   }
 });
@@ -14280,8 +14280,8 @@ var require_RealtimeChannel = __commonJS({
       }
       /** @internal */
       _notThisChannelEvent(event, ref) {
-        const { close, error, leave, join: join46 } = constants_1.CHANNEL_EVENTS;
-        const events = [close, error, leave, join46];
+        const { close, error, leave, join: join48 } = constants_1.CHANNEL_EVENTS;
+        const events = [close, error, leave, join48];
         return ref && events.includes(event) && ref !== this.joinPush.ref;
       }
       /** @internal */
@@ -37932,8 +37932,242 @@ var init_validate_waves2 = __esm({
   }
 });
 
+// src/cli/worktree/path.ts
+import { dirname as dirname13, basename as basename4, join as join45 } from "node:path";
+function computeWorktreePath(cwd, checkpointNumber) {
+  const parent = dirname13(cwd);
+  const base = basename4(cwd);
+  const nnn = String(checkpointNumber).padStart(3, "0");
+  return join45(parent, `${base}-CHK-${nnn}`);
+}
+var init_path = __esm({
+  "src/cli/worktree/path.ts"() {
+    "use strict";
+  }
+});
+
+// src/cli/worktree/add.ts
+import { join as join46, basename as basename5 } from "node:path";
+import { mkdir as mkdir14, readFile as readFile30, writeFile as writeFile23 } from "node:fs/promises";
+import { spawnSync as spawnSync16 } from "node:child_process";
+async function defaultGetRepoId(cwd) {
+  const found = await findCodebyplanConfig(cwd);
+  return found?.contents.repo_id ?? null;
+}
+async function defaultLookupBranch(repoId, checkpointNumber) {
+  const checkpoints = await mcpCall("get_checkpoints", {
+    repo_id: repoId
+  });
+  const list = Array.isArray(checkpoints) ? checkpoints : [];
+  const chk = list.find((c) => c.number === checkpointNumber);
+  if (!chk) {
+    return {
+      found: false,
+      pending: false,
+      message: `No checkpoint found with number ${checkpointNumber} in this repo.`
+    };
+  }
+  if (!chk.branch_name) {
+    const nnn = String(checkpointNumber).padStart(3, "0");
+    return {
+      found: false,
+      pending: true,
+      message: `Branch not yet created for CHK-${nnn} \u2014 connect this repo to GitHub in Settings \u2192 Integrations.`
+    };
+  }
+  return { found: true, branch_name: chk.branch_name };
+}
+function defaultGitRun(args, cwd) {
+  const result = spawnSync16("git", args, {
+    cwd,
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  return {
+    status: result.status,
+    stdout: (result.stdout ?? "").toString(),
+    stderr: (result.stderr ?? "").toString(),
+    error: result.error
+  };
+}
+async function defaultCopyConfigStubs(srcCwd, destPath) {
+  await mkdir14(join46(destPath, ".codebyplan"), { recursive: true });
+  const topLevelStubs = [".mcp.json", ".env.local"];
+  for (const stub of topLevelStubs) {
+    try {
+      const content = await readFile30(join46(srcCwd, stub), "utf-8");
+      await writeFile23(join46(destPath, stub), content, "utf-8");
+    } catch {
+    }
+  }
+  try {
+    const content = await readFile30(
+      join46(srcCwd, ".codebyplan", "repo.json"),
+      "utf-8"
+    );
+    await writeFile23(
+      join46(destPath, ".codebyplan", "repo.json"),
+      content,
+      "utf-8"
+    );
+  } catch {
+  }
+}
+async function defaultRegisterWorktree(repoId, name, path16) {
+  const res = await apiPost("/worktrees", {
+    repo_id: repoId,
+    name,
+    path: path16,
+    status: "active"
+  });
+  return { worktree_id: res.data.id };
+}
+function parseCheckpointNumber(arg) {
+  const m = /^(?:CHK-)?(\d+)$/i.exec(arg.trim());
+  if (!m?.[1]) return null;
+  const n = parseInt(m[1], 10);
+  return isNaN(n) || n < 0 ? null : n;
+}
+async function runWorktreeAdd(args, deps = {}) {
+  const rawArg = args.find((a) => !a.startsWith("--"));
+  if (!rawArg) {
+    process.stderr.write(
+      JSON.stringify({
+        error: "usage: codebyplan worktree add <CHK-NNN>"
+      }) + "\n"
+    );
+    return 1;
+  }
+  const checkpointNumber = parseCheckpointNumber(rawArg);
+  if (checkpointNumber === null) {
+    process.stderr.write(
+      JSON.stringify({
+        error: `Invalid checkpoint identifier '${rawArg}'. Use CHK-NNN or a bare number (e.g. CHK-207 or 207).`
+      }) + "\n"
+    );
+    return 1;
+  }
+  const cwd = deps.cwd ?? process.cwd();
+  const getRepoId = deps.getRepoId ?? defaultGetRepoId;
+  const lookupBranch = deps.lookupBranch ?? defaultLookupBranch;
+  const gitRun = deps.gitRun ?? defaultGitRun;
+  const sleep3 = deps.sleep ?? ((ms) => new Promise((resolve11) => setTimeout(resolve11, ms)));
+  const copyConfigStubs = deps.copyConfigStubs ?? defaultCopyConfigStubs;
+  const registerWorktree = deps.registerWorktree ?? defaultRegisterWorktree;
+  try {
+    const repoId = await getRepoId(cwd);
+    if (!repoId) {
+      process.stderr.write(
+        JSON.stringify({
+          error: "Could not determine repo_id. Ensure .codebyplan/repo.json exists in the project root."
+        }) + "\n"
+      );
+      return 1;
+    }
+    const lookup = await lookupBranch(repoId, checkpointNumber);
+    if (!lookup.found) {
+      if (lookup.pending) {
+        const result = {
+          status: "branch_pending",
+          message: lookup.message
+        };
+        process.stdout.write(JSON.stringify(result) + "\n");
+        return 0;
+      }
+      process.stderr.write(JSON.stringify({ error: lookup.message }) + "\n");
+      return 1;
+    }
+    const branchName = lookup.branch_name;
+    const nnn = String(checkpointNumber).padStart(3, "0");
+    gitRun(["fetch", "origin", branchName], cwd);
+    let branchReady = false;
+    for (let attempt = 0; attempt < BRANCH_RETRY_COUNT; attempt++) {
+      if (attempt > 0) {
+        await sleep3(BRANCH_RETRY_DELAY_MS);
+      }
+      const lsResult = gitRun(
+        ["ls-remote", "--heads", "origin", branchName],
+        cwd
+      );
+      if (lsResult.status === 0 && lsResult.stdout.trim().length > 0) {
+        branchReady = true;
+        break;
+      }
+    }
+    if (!branchReady) {
+      const result = {
+        status: "branch_not_ready",
+        message: `Branch '${branchName}' not yet visible at origin after ${BRANCH_RETRY_COUNT} retries. Connect this repo to GitHub in Settings \u2192 Integrations.`
+      };
+      process.stdout.write(JSON.stringify(result) + "\n");
+      return 1;
+    }
+    const worktreePath = computeWorktreePath(cwd, checkpointNumber);
+    const worktreeName = `${basename5(cwd)}-CHK-${nnn}`;
+    const addResult = gitRun(
+      ["worktree", "add", worktreePath, branchName],
+      cwd
+    );
+    if (addResult.status !== 0) {
+      const errMsg = addResult.stderr.trim() || addResult.error?.message || "unknown error";
+      process.stderr.write(
+        JSON.stringify({ error: `git worktree add failed: ${errMsg}` }) + "\n"
+      );
+      return 1;
+    }
+    try {
+      await copyConfigStubs(cwd, worktreePath);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`Warning: failed to copy config stubs: ${msg}
+`);
+    }
+    try {
+      const { worktree_id } = await registerWorktree(
+        repoId,
+        worktreeName,
+        worktreePath
+      );
+      const result = {
+        status: "added",
+        worktree_path: worktreePath,
+        branch_name: branchName,
+        worktree_id
+      };
+      process.stdout.write(JSON.stringify(result) + "\n");
+      return 0;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      const result = {
+        status: "added",
+        worktree_path: worktreePath,
+        branch_name: branchName,
+        warn: `Worktree created but registration failed: ${msg}`
+      };
+      process.stdout.write(JSON.stringify(result) + "\n");
+      return 0;
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(JSON.stringify({ error: msg }) + "\n");
+    return 1;
+  }
+}
+var BRANCH_RETRY_COUNT, BRANCH_RETRY_DELAY_MS;
+var init_add = __esm({
+  "src/cli/worktree/add.ts"() {
+    "use strict";
+    init_path();
+    init_flags();
+    init_mcp_client();
+    init_api();
+    BRANCH_RETRY_COUNT = 3;
+    BRANCH_RETRY_DELAY_MS = 2e3;
+  }
+});
+
 // src/cli/worktree/create.ts
-import { join as join45 } from "node:path";
+import { join as join47 } from "node:path";
 async function defaultGetRepoIdentity(cwd) {
   const found = await findCodebyplanConfig(cwd);
   const contents = found?.contents ?? null;
@@ -37945,7 +38179,7 @@ async function defaultGetRepoIdentity(cwd) {
     project_id: typeof contents?.["project_id"] === "string" ? contents["project_id"] : void 0
   };
 }
-async function defaultRegisterWorktree(repoId, name, path16) {
+async function defaultRegisterWorktree2(repoId, name, path16) {
   const res = await apiPost("/worktrees", {
     repo_id: repoId,
     name,
@@ -37977,7 +38211,7 @@ async function runWorktreeCreate(args, deps = {}) {
   const cwd = deps.cwd ?? process.cwd();
   const getRepoIdentity = deps.getRepoIdentity ?? defaultGetRepoIdentity;
   const getDeviceId = deps.getDeviceId ?? getOrCreateDeviceId;
-  const registerWorktree = deps.registerWorktree ?? defaultRegisterWorktree;
+  const registerWorktree = deps.registerWorktree ?? defaultRegisterWorktree2;
   const identity = await getRepoIdentity(cwd);
   const repoId = identity?.repo_id ?? null;
   if (!identity || !repoId) {
@@ -37988,7 +38222,7 @@ async function runWorktreeCreate(args, deps = {}) {
     );
     return 1;
   }
-  const worktreePath = explicitPath ?? join45(cwd, "..", name);
+  const worktreePath = explicitPath ?? join47(cwd, "..", name);
   const deviceId = await getDeviceId(cwd);
   let filesWritten = false;
   try {
@@ -38044,7 +38278,9 @@ var init_create = __esm({
 });
 
 // src/cli/worktree/remove.ts
-async function defaultGetRepoId(cwd) {
+import { basename as basename6 } from "node:path";
+import { spawnSync as spawnSync17 } from "node:child_process";
+async function defaultGetRepoId2(cwd) {
   const found = await findCodebyplanConfig(cwd);
   return found?.contents.repo_id ?? null;
 }
@@ -38064,6 +38300,192 @@ async function defaultFindWorktreeId(repoId, name) {
 async function defaultDeregisterWorktree(worktreeId) {
   await mcpCall("delete_worktree", { worktree_id: worktreeId });
 }
+function defaultGitRun2(args, cwd) {
+  const result = spawnSync17("git", args, {
+    cwd,
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  return {
+    status: result.status,
+    stdout: (result.stdout ?? "").toString(),
+    stderr: (result.stderr ?? "").toString(),
+    error: result.error
+  };
+}
+function defaultGetWorktreeBranchName(worktreePath) {
+  const result = spawnSync17("git", ["symbolic-ref", "--short", "HEAD"], {
+    cwd: worktreePath,
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  if (result.status === 0 && result.stdout) {
+    return result.stdout.trim() || null;
+  }
+  return null;
+}
+async function defaultDeleteSupabaseBranch(branchName, cwd) {
+  const token = process.env.SUPABASE_ACCESS_TOKEN;
+  if (!token) {
+    return {
+      deleted: false,
+      warn: "SUPABASE_ACCESS_TOKEN not set \u2014 skipping Supabase preview-branch teardown."
+    };
+  }
+  const shipment = readShipmentConfig(cwd);
+  const parentRef = shipment.parentRef;
+  if (!parentRef) {
+    return {
+      deleted: false,
+      warn: "Supabase project_ref not configured in .codebyplan/shipment.json \u2014 skipping teardown."
+    };
+  }
+  const gitCfg = readGitConfig(cwd);
+  if (branchName === gitCfg.production || gitCfg.protected.includes(branchName)) {
+    return {
+      deleted: false,
+      warn: `Skipping Supabase teardown for protected branch '${branchName}'.`
+    };
+  }
+  if (gitCfg.integration !== null && branchName === gitCfg.integration) {
+    return {
+      deleted: false,
+      warn: `Skipping Supabase teardown for integration branch '${branchName}'.`
+    };
+  }
+  try {
+    const listRes = await fetch(
+      `https://api.supabase.com/v1/projects/${parentRef}/branches`,
+      {
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json"
+        }
+      }
+    );
+    if (!listRes.ok) {
+      return {
+        deleted: false,
+        warn: `Supabase list_branches failed (HTTP ${listRes.status}) \u2014 verify the branch manually in the dashboard.`
+      };
+    }
+    const branches = await listRes.json();
+    if (!Array.isArray(branches)) {
+      return {
+        deleted: false,
+        warn: "Supabase list_branches returned unexpected shape \u2014 verify manually in the dashboard."
+      };
+    }
+    const match = branches.find((b) => b.name === branchName);
+    if (!match) {
+      return { deleted: true };
+    }
+    if (match.is_default === true) {
+      return {
+        deleted: false,
+        warn: `Refusing to delete is_default Supabase branch '${branchName}'.`
+      };
+    }
+    if (!match.id) {
+      return {
+        deleted: false,
+        warn: `Supabase branch '${branchName}' found but has no id \u2014 skipping.`
+      };
+    }
+    const deleteRes = await fetch(
+      `https://api.supabase.com/v1/projects/${parentRef}/branches/${match.id}`,
+      {
+        method: "DELETE",
+        headers: { Authorization: `Bearer ${token}` }
+      }
+    );
+    if (!deleteRes.ok) {
+      return {
+        deleted: false,
+        warn: `Supabase delete_branch failed (HTTP ${deleteRes.status}) \u2014 verify the branch manually in the dashboard.`
+      };
+    }
+    return { deleted: true };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      deleted: false,
+      warn: `Supabase teardown error: ${msg} \u2014 verify manually in the dashboard.`
+    };
+  }
+}
+function parseChkNumber(name) {
+  const chkMatch = /^CHK-(\d+)$/i.exec(name);
+  if (chkMatch?.[1]) {
+    const n = parseInt(chkMatch[1], 10);
+    return isNaN(n) ? null : n;
+  }
+  if (/^\d+$/.test(name)) {
+    const n = parseInt(name, 10);
+    return isNaN(n) ? null : n;
+  }
+  return null;
+}
+async function runWorktreeRemoveChk(checkpointNumber, deps) {
+  const cwd = deps.cwd ?? process.cwd();
+  const getRepoId = deps.getRepoId ?? defaultGetRepoId2;
+  const findWorktreeId = deps.findWorktreeId ?? defaultFindWorktreeId;
+  const deregisterWorktree = deps.deregisterWorktree ?? defaultDeregisterWorktree;
+  const gitRun = deps.gitRun ?? defaultGitRun2;
+  const getWorktreeBranchName = deps.getWorktreeBranchName ?? defaultGetWorktreeBranchName;
+  const deleteSupabaseBranch = deps.deleteSupabaseBranch ?? defaultDeleteSupabaseBranch;
+  const nnn = String(checkpointNumber).padStart(3, "0");
+  const worktreeName = `${basename6(cwd)}-CHK-${nnn}`;
+  const worktreePath = computeWorktreePath(cwd, checkpointNumber);
+  const warnings = [];
+  const branchName = getWorktreeBranchName(worktreePath);
+  const removeResult = gitRun(["worktree", "remove", worktreePath], cwd);
+  const git_removed = removeResult.status === 0;
+  if (!git_removed) {
+    const errMsg = removeResult.stderr.trim() || removeResult.error?.message || "unknown error";
+    warnings.push(`git worktree remove failed: ${errMsg}`);
+  }
+  let mcp_deregistered = false;
+  const repoId = await getRepoId(cwd);
+  if (repoId) {
+    const worktreeId = await findWorktreeId(repoId, worktreeName);
+    if (worktreeId) {
+      try {
+        await deregisterWorktree(worktreeId);
+        mcp_deregistered = true;
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        warnings.push(`MCP deregistration failed: ${msg}`);
+      }
+    } else {
+      warnings.push(
+        `No registered worktree found with name '${worktreeName}' for this repo.`
+      );
+    }
+  } else {
+    warnings.push("Could not determine repo_id \u2014 worktree not deregistered.");
+  }
+  let supabase_torn_down = false;
+  if (branchName) {
+    const teardown = await deleteSupabaseBranch(branchName, cwd);
+    supabase_torn_down = teardown.deleted;
+    if (teardown.warn) {
+      warnings.push(teardown.warn);
+    }
+  } else {
+    warnings.push(
+      `Could not read the branch name for '${worktreePath}' (directory may already be deleted) \u2014 the Supabase preview branch was NOT torn down. Delete it manually in the Supabase dashboard if it still exists.`
+    );
+  }
+  const result = {
+    mcp_deregistered,
+    git_removed,
+    supabase_torn_down,
+    ...warnings.length > 0 ? { warn: warnings.join("; ") } : {}
+  };
+  process.stdout.write(JSON.stringify(result) + "\n");
+  return 0;
+}
 async function runWorktreeRemove(args, deps = {}) {
   const name = args.find((a) => !a.startsWith("--"));
   if (!name) {
@@ -38074,8 +38496,12 @@ async function runWorktreeRemove(args, deps = {}) {
     );
     return 1;
   }
+  const chkNumber = parseChkNumber(name);
+  if (chkNumber !== null) {
+    return runWorktreeRemoveChk(chkNumber, deps);
+  }
   const cwd = deps.cwd ?? process.cwd();
-  const getRepoId = deps.getRepoId ?? defaultGetRepoId;
+  const getRepoId = deps.getRepoId ?? defaultGetRepoId2;
   const findWorktreeId = deps.findWorktreeId ?? defaultFindWorktreeId;
   const deregisterWorktree = deps.deregisterWorktree ?? defaultDeregisterWorktree;
   const repoId = await getRepoId(cwd);
@@ -38114,9 +38540,11 @@ async function runWorktreeRemove(args, deps = {}) {
 var init_remove = __esm({
   "src/cli/worktree/remove.ts"() {
     "use strict";
+    init_path();
     init_api();
     init_mcp_client();
     init_flags();
+    init_supabase();
   }
 });
 
@@ -38127,6 +38555,9 @@ __export(worktree_exports, {
 });
 async function runWorktreeCommand(args) {
   const subcommand = args[0];
+  if (subcommand === "add") {
+    return runWorktreeAdd(args.slice(1));
+  }
   if (subcommand === "create") {
     return runWorktreeCreate(args.slice(1));
   }
@@ -38140,7 +38571,7 @@ async function runWorktreeCommand(args) {
   if (subcommand) {
     process.stderr.write(
       `Unknown subcommand: codebyplan worktree ${subcommand}
-Available: create, remove
+Available: add, create, remove
 `
     );
     return 1;
@@ -38150,12 +38581,13 @@ Available: create, remove
 }
 function printWorktreeHelp() {
   process.stdout.write(
-    "\n  codebyplan worktree <subcommand>\n\n  Subcommands:\n    create <name>   Write .codebyplan/ files and register the worktree in CodeByPlan\n    remove <name>   Deregister a worktree from CodeByPlan\n\n  create flags:\n    --path <abs>    Explicit absolute path to the worktree root (primary mechanism)\n\n  Output is JSON on stdout. Exit 0 on success or non-fatal failure; exit 1 on usage error.\n\n"
+    "\n  codebyplan worktree <subcommand>\n\n  Subcommands:\n    add <CHK-NNN>   Create a per-checkpoint git worktree on the checkpoint's feat branch and register it\n    create <name>   Write .codebyplan/ files and register the worktree in CodeByPlan\n    remove <name>   Deregister a worktree (or `remove CHK-NNN` to prune the per-checkpoint worktree + Supabase preview)\n\n  create flags:\n    --path <abs>    Explicit absolute path to the worktree root (primary mechanism)\n\n  Output is JSON on stdout. Exit 0 on success or non-fatal failure; exit 1 on usage error.\n\n"
   );
 }
 var init_worktree2 = __esm({
   "src/cli/worktree.ts"() {
     "use strict";
+    init_add();
     init_create();
     init_remove();
   }
@@ -38275,7 +38707,7 @@ var init_e2e = __esm({
 });
 
 // src/cli/e2e/verify-round.ts
-import { readFile as readFile30 } from "node:fs/promises";
+import { readFile as readFile31 } from "node:fs/promises";
 import { resolve as resolve9 } from "node:path";
 async function defaultFetchRounds(taskId) {
   return mcpCall("get_rounds", { task_id: taskId });
@@ -38283,7 +38715,7 @@ async function defaultFetchRounds(taskId) {
 async function defaultReadE2eConfig(cwd) {
   try {
     const p = resolve9(cwd, ".codebyplan", "e2e.json");
-    const raw = await readFile30(p, "utf-8");
+    const raw = await readFile31(p, "utf-8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -39063,7 +39495,7 @@ void (async () => {
     codebyplan claude                Claude asset management (install/update/uninstall/generate/migrate-memory)
     codebyplan supabase              Preview-branch helpers (resolve-preview/teardown-preview/new-migration/preview-check)
     codebyplan session               Session helpers (home-ff/freshness-gate/infra-files)
-    codebyplan worktree              Worktree management (create/remove)
+    codebyplan worktree              Worktree management (add/create/remove)
     codebyplan e2e               E2E deterministic gates (verify-round)
     codebyplan statusline            Show or set the statusline renderer (bash/node/python)
     codebyplan resolve-worktree      Resolve active worktree UUID from device+path+branch tuple

package/package.json

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

package/templates/rules/supabase-branch-lifecycle.md

@@ -7,7 +7,6 @@ paths:
   - ".claude/skills/cbp-supabase-migrate/**"
   - ".claude/skills/cbp-supabase-branch-check/**"
   - ".claude/skills/cbp-checkpoint-end/**"
-  - ".claude/skills/cbp-git-worktree-remove/**"
   - ".claude/skills/cbp-ship-main/**"
   - ".claude/skills/cbp-standalone-task-complete/**"
 ---
@@ -48,7 +47,7 @@ The Supabase branch is removed wherever the git branch is deleted:
 | Skill | Trigger |
 |---|---|
 | `cbp-checkpoint-end` | stale-branch cleanup + current feat-branch delete on ship |
-| `cbp-git-worktree-remove` | worktree teardown removes the coupled Supabase branch |
+| `codebyplan worktree remove CHK-NNN` | worktree teardown removes the coupled Supabase branch |
 | `cbp-ship-main` | `branch_deleted` event after PR merge |
 | `cbp-standalone-task-complete` | `branch_deleted` event after standalone PR merge (Step 7.3) |
 
@@ -94,7 +93,7 @@ or auto-created by the GitHub integration — both paths use the same branch nam
 | Role | Skill |
 |---|---|
 | Create (lazy) | `cbp-supabase-migrate` (Step 2.3) |
-| Delete | `cbp-checkpoint-end`, `cbp-standalone-task-complete`, `cbp-git-worktree-remove`, `cbp-ship-main` |
+| Delete | `cbp-checkpoint-end`, `cbp-standalone-task-complete`, `codebyplan worktree remove`, `cbp-ship-main` |
 | PR gate | `cbp-supabase-branch-check` |
 
 Each skill in the Skill Map above carries an inline back-reference to this rule at its create or teardown step.

package/templates/settings.project.base.json

@@ -123,8 +123,6 @@
       "Skill(cbp-frontend-ux)",
       "Skill(cbp-git-branch-feat-create)",
       "Skill(cbp-git-commit)",
-      "Skill(cbp-git-worktree-create)",
-      "Skill(cbp-git-worktree-remove)",
       "Skill(cbp-map-architecture)",
       "Skill(cbp-merge-main)",
       "Skill(cbp-refresh-arch-map)",

package/templates/skills/cbp-build-cc-mode/SKILL.md

@@ -32,7 +32,7 @@ Omit `model:` entirely (inherit the session model). Set `effort:` per the skill'
 | `xhigh`  | deep authoring / planning / orchestration (most skills) | build-cc-*, checkpoint-check/end/plan, round-start/input/execute, task-create/start/complete/testing, standalone-task-*, frontend-*, ship, ship-configure, supabase-*, setup-e2e/eslint, session-end |
 | `high`   | summary / orchestration, lighter than xhigh            | checkpoint-create, checkpoint-start, checkpoint-update, round-end, task-check, standalone-task-check, ship-main, merge-main                                           |
 | `medium` | moderate, scoped sync work                             | refresh-infra                                                                                                                                                        |
-| `low`    | pure mechanical / dispatch / templated work            | checkpoint-complete, round-check, round-complete, round-update, todo, session-start, git-commit, git-branch-feat-create, git-worktree-create, git-worktree-remove    |
+| `low`    | pure mechanical / dispatch / templated work            | checkpoint-complete, round-check, round-complete, round-update, todo, session-start, git-commit, git-branch-feat-create    |
 
 A skill that carries a `model:` line is a **gap** — remove it unless a deliberate, documented exception is recorded here (currently none).
 

package/templates/skills/cbp-build-cc-skill/SKILL.md

@@ -157,5 +157,6 @@ Checks: name matches directory, frontmatter parses, no invalid fields, arg-hint
 - Rendered `SKILL.md` content enters the conversation once when invoked and stays until compaction — write standing instructions, not one-time steps
 - Preloaded subagent skills cannot have `disable-model-invocation: true`
 - `context: fork` is only meaningful when the skill body contains an actionable task; otherwise the subagent receives guidelines with no prompt
+- `context: fork` ALSO disqualifies fan-out / spawn-then-route / inline-by-design / consumed-inline skills — they run in the main context for a reason; see [reference/fork-eligibility.md](reference/fork-eligibility.md) for the eligibility test + the CBP classification of which skills may fork and which must stay inline
 - Descriptions front-load key use case: `description` + `when_to_use` cap at 1,536 chars in the skill listing
 - `paths:` scoping applies when Claude reads files matching the globs, not on every tool use

package/templates/skills/cbp-build-cc-skill/reference/fork-eligibility.md

@@ -0,0 +1,78 @@
+# `context: fork` Eligibility — when to fork a skill, and when not to
+
+`context: fork` runs the **entire SKILL.md body in a forked subagent** — it inherits the
+parent conversation and, per the runtime, **runs in the background by default**. It is
+isolation for a *whole skill*, not a way to delegate one sub-step. A forked body therefore
+cannot drive the main pipeline: it can't `AskUserQuestion`, can't auto-trigger another
+skill, and can't run an inline-fallback that the orchestrator depends on.
+
+So forking only helps a narrow shape of skill. The canonical eligible example is
+[examples/fork-skill.md](../examples/fork-skill.md): a single self-contained analytical task
+that reads, reasons, and returns a summary — nothing else.
+
+## Eligibility test
+
+A skill is **fork-eligible** only when ALL hold:
+
+1. Its whole body is **one** self-contained analytical/generative task (read → reason → return).
+2. It is **non-interactive** — no `AskUserQuestion`, no user decision gates.
+3. It does **not route** — no auto-trigger of another skill, no close-out directive that must
+   fire in the main context.
+4. It does **not fan out** — it does not spawn multiple subagents and coordinate them.
+5. It has **no inline-fallback** contract the orchestrator relies on.
+
+Fail any one → the skill stays **inline** (main context). Inline skills still get clean
+context isolation the right way: by delegating their heavy step to a dedicated **agent**
+(e.g. `cbp-task-check`, `cbp-improve-round`, `cbp-round-executor`). The agent is the
+isolation boundary; the skill stays in the main thread to orchestrate, route, and interact.
+
+## When NOT to use `context: fork` (the disqualifying patterns)
+
+| Pattern | Why it can't fork | Example skills |
+|---------|-------------------|----------------|
+| **fan-out** | spawns multiple agents in parallel and coordinates them | `cbp-round-execute`, `cbp-checkpoint-check`, `cbp-map-architecture`, `cbp-refresh-arch-map` |
+| **spawn-then-route** | spawns one agent, then `AskUserQuestion` / auto-triggers the next skill / runs inline-fallback | `cbp-task-check`, `cbp-standalone-task-check`, `cbp-round-start`, `cbp-round-end`, `cbp-checkpoint-plan` |
+| **inline-by-design** | interactive Q&A or stepwise writes that must stay in the main context | `cbp-task-create`, `cbp-task-complete`, `cbp-round-update`, `cbp-merge-main` |
+| **consumed-inline** | invoked *by* an agent (e.g. round-executor) and applies fixes synchronously into that context | `cbp-frontend-design`, `cbp-frontend-ui`, `cbp-frontend-ux` |
+| **doc-ref-only** | mentions subagents/fork only as documentation; runs inline authoring | the `cbp-build-cc-*` authoring skills, `cbp-supabase-migrate` |
+
+## CHK-220 audit — classification matrix
+
+Every skill whose `SKILL.md` touches the subagent/fork boundary — by spawning a subagent, by
+being invoked inline by an agent, or by documenting the feature — was classified against the
+eligibility test. **Result: 0 of 25 are fork-eligible** — none were migrated, because every
+one either already isolates heavy work in a dedicated agent (the correct boundary) or depends
+on inline orchestration/interaction that a background fork would break.
+
+| Skill | Pattern | Fork-eligible |
+|-------|---------|:---:|
+| cbp-round-execute | fan-out | no |
+| cbp-checkpoint-check | fan-out | no |
+| cbp-map-architecture | fan-out | no |
+| cbp-refresh-arch-map | fan-out | no |
+| cbp-round-start | spawn-then-route | no |
+| cbp-round-end | spawn-then-route | no |
+| cbp-task-check | spawn-then-route | no |
+| cbp-standalone-task-check | spawn-then-route | no |
+| cbp-checkpoint-plan | spawn-then-route | no |
+| cbp-round-update | inline-by-design | no |
+| cbp-task-create | inline-by-design | no |
+| cbp-standalone-task-create | inline-by-design | no |
+| cbp-task-complete | inline-by-design | no |
+| cbp-standalone-task-complete | inline-by-design | no |
+| cbp-merge-main | inline-by-design | no |
+| cbp-task-testing | inline-by-design | no |
+| cbp-standalone-task-testing | inline-by-design | no |
+| cbp-frontend-design | consumed-inline | no |
+| cbp-frontend-ui | consumed-inline | no |
+| cbp-frontend-ux | consumed-inline | no |
+| cbp-supabase-migrate | doc-ref-only | no |
+| cbp-build-cc-skill | doc-ref-only | no |
+| cbp-build-cc-agent | doc-ref-only | no |
+| cbp-build-cc-settings | doc-ref-only | no |
+| cbp-build-cc-mode | doc-ref-only | no |
+
+If a **new** skill is authored that passes the eligibility test above, fork it: add
+`context: fork` + `agent: <Explore|Plan|general-purpose|custom>` (use `--fork` in
+`/cbp-build-cc-skill`). Do not retrofit fork onto any skill in the table — their inline
+shape is load-bearing.

package/templates/skills/cbp-build-cc-skill/reference/frontmatter-fields.md

@@ -20,6 +20,10 @@ Source: official Claude Code skills spec. All fields are optional; `description`
 | `paths` | Globs that auto-load the skill when matching files are in play |
 | `shell` | `bash` (default) or `powershell` for `!`-commands |
 
+> `context: fork` / `agent` are right for only a narrow shape of skill — a single
+> non-interactive analytical body. See [fork-eligibility.md](fork-eligibility.md) for the
+> eligibility test and the CBP classification of which skills may fork (and which must stay inline).
+
 ## Character budget
 
 Combined `description` + `when_to_use` truncates at **1,536 characters** in the skill listing. Front-load the key use case.

package/templates/skills/cbp-checkpoint-create/SKILL.md

@@ -113,6 +113,7 @@ Persist the branch via `codebyplan checkpoint update --id <checkpoint-id> --bran
 
 **CHK-NNN**: [title]  •  **Deadline**: [date]  •  **Branch**: feat/CHK-NNN-slug
 **Claim**: [claimed by this worktree / left open]
+**Worktree**: `npx codebyplan worktree add CHK-{NNN}`
 
 Now planning CHK-NNN… handing off to /cbp-checkpoint-plan.
 ```

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

@@ -72,6 +72,7 @@ Show a one-line confirmation before routing:
 
 **CHK-NNN**: [title]  •  **Status**: active  •  **Claimed by**: [worktree or "open"]
 **Next task**: TASK-[N] — [title]
+**Worktree**: `npx codebyplan worktree add CHK-{NNN}`
 ```
 
 ## Integration

package/templates/skills/cbp-session-end/SKILL.md

@@ -74,23 +74,9 @@ Same rule as `/cbp-session-start` Step 5.7 — only commit files that are **not*
 
 Non-blocking — session end proceeds either way.
 
-### Step 1.6: Home-Branch Fast-Forward
-
-Keep this worktree's **home branch** rooted at the freshest production tip — no prompt, fully non-blocking. Home branches are the folder-named placeholder branches each worktree rests on (e.g. `codebyplan-web`); `feat/*` branches are deliberately skipped — they integrate via `/cbp-merge-main` with QA, never an auto fast-forward.
-
-Runs after Step 1.5 so any infra commits land first, and before Step 1.7 so the freshness gate's asset update operates on the freshest tree.
-
-Run `codebyplan session home-ff` and parse the JSON output (`{ result: 'skipped'|'warn'|'fast_forwarded', reason?, warn? }`):
-
-- **`result === 'skipped'`** (non-home branch or production mismatch): proceed silently.
-- **`result === 'warn'`** (fast-forward attempt failed): surface the `warn` field as one line, then proceed silently.
-- **`result === 'fast_forwarded'`** (home branch updated): proceed silently.
-
-Never rebase, reset, force-push, or stash. A non-fast-forwardable home branch is a signal to reconcile manually, not to overwrite.
-
 ### Step 1.7: Package Freshness Gate
 
-Check whether a newer `codebyplan` is published and safe to auto-install on this worktree's current branch, then run the local install + asset update. Runs after the Step 1.6 home-branch fast-forward (so any update lands on the freshest tree) and before Step 2. Fully non-blocking — the guard and skip branches proceed silently; any failure in the install/update commands warns once and continues to Step 2. session-end never halts.
+Check whether a newer `codebyplan` is published and safe to auto-install on this worktree's current branch, then run the local install + asset update. Runs after the Step 1.5 non-task-file commit and before Step 2. Fully non-blocking — the guard and skip branches proceed silently; any failure in the install/update commands warns once and continues to Step 2. session-end never halts.
 
 Run `codebyplan session freshness-gate` (WITHOUT `--halt-on-update`; session-end is continue-only) and parse the JSON output (`{ result: 'skipped'|'guarded'|'up_to_date'|'updated'|'error', ... }`):
 
@@ -110,8 +96,6 @@ Run `codebyplan session freshness-gate` (WITHOUT `--halt-on-update`; session-end
     On `yes`: `git add` the listed paths only (not the whole directories), then trigger `/cbp-git-commit`. On `no`: skip. On `select`: ask which subset.
   - Continue to Step 2 — session-end does NOT halt. The update lands in the current worktree on its current branch; main/protected branches and the canonical source repo are already excluded by the `result !== 'guarded'` check above.
 
-**Home branches are intentionally not guarded.** A worktree's folder-named home branch (e.g. `codebyplan-web`) is neither protected/main nor the canonical source, so the freshness gate returns `result !== 'guarded'` there and this gate runs the update exactly as on a feat branch — landing it on whichever branch the worktree currently rests on (the deliberate "update the branch they're on, except main/canonical" behavior).
-
 Non-blocking — session end proceeds regardless of outcome.
 
 ### Step 2: Auto-Stop Servers
@@ -149,7 +133,7 @@ You can close this window.
 ## Integration
 
 - **Triggered by**: user invocation (prompted by `/cbp-todo` when no work remains)
-- **Reads**: `.codebyplan/repo.json`, `.codebyplan/git.json` (`branch_config.production` for the Step 1.6 home-branch fast-forward); local-first reads (with `npx codebyplan sync` + MCP break-glass): `.codebyplan/state/session/current.json` (Step 1 resolve log), `.codebyplan/state/todos.json` (Step 1.3 handoff snapshot + Step 1.5 active-task lookup), `.codebyplan/state/checkpoints/<id>/tasks/<id>/rounds/` (Step 1.5 task-file resolution); `codebyplan session home-ff` (Step 1.6 home-branch fast-forward); `codebyplan session freshness-gate` (Step 1.7 package-freshness gate, without --halt-on-update); `codebyplan session infra-files --json --task-files <csv>` (Step 1.5 infra-file set math)
+- **Reads**: `.codebyplan/repo.json`; local-first reads (with `npx codebyplan sync` + MCP break-glass): `.codebyplan/state/session/current.json` (Step 1 resolve log), `.codebyplan/state/todos.json` (Step 1.3 handoff snapshot + Step 1.5 active-task lookup), `.codebyplan/state/checkpoints/<id>/tasks/<id>/rounds/` (Step 1.5 task-file resolution); `codebyplan session freshness-gate` (Step 1.7 package-freshness gate, without --halt-on-update); `codebyplan session infra-files --json --task-files <csv>` (Step 1.5 infra-file set math)
 - **Writes**: `codebyplan session update-log --id <id> ...` (Step 1 finalize — CLI write-through to `.codebyplan/state/session/current.json`; break-glass: MCP `update_session_log`), `codebyplan session create-log` (Step 1 fallback when no log exists; break-glass: MCP `create_session_log`), `codebyplan session update-state --action deactivate` (Step 3 — CLI write-through to `.codebyplan/state/session/state.json`; break-glass: MCP `update_session_state`)
 - **Spawns**: none
 - **Triggers**: none at the skill-contract level. Step 1.5 may invoke `/cbp-git-commit` inline on user approval; Step 1.7 may invoke `/cbp-git-commit` on the `result === 'updated'` path (committing changed `.claude/` and `.codebyplan/` paths).

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

@@ -11,7 +11,7 @@ Activate the session, open a fresh session log, and surface the previous log's p
 
 ## Instructions
 
-Run Steps 0 through 5.8 silently (no intermediate output) — except Step 0 aborts the session on MCP failure, Step 1.4 may surface a one-line fast-forward note or warning, Step 1.5 may surface a one-line infra-drift nudge, Step 1.55 may surface a one-line architecture-map drift nudge, Step 1.6 may run an install-and-halt path, Step 1.7 may surface a one-line LSP binary nudge, Step 4.5 may auto-resume a handoff and exit session-start entirely (no Step 6 output), and Step 5.7 may surface an approval gate. (Step numbers are organizational labels; execution order is 0 → 1 → 1.4 → 1.5 → 1.55 → 1.6 → 1.7 → 3 → 4 → 4.5 → 5 → 5.7 → 5.8 → 6 → 7.) Produce ONE output block at Step 6, then auto-trigger or stop per Step 7.
+Run Steps 0 through 5.8 silently (no intermediate output) — except Step 0 aborts the session on MCP failure, Step 1.5 may surface a one-line infra-drift nudge, Step 1.55 may surface a one-line architecture-map drift nudge, Step 1.6 may run an install-and-halt path, Step 1.7 may surface a one-line LSP binary nudge, Step 4.5 may auto-resume a handoff and exit session-start entirely (no Step 6 output), and Step 5.7 may surface an approval gate. (Step numbers are organizational labels; execution order is 0 → 1 → 1.5 → 1.55 → 1.6 → 1.7 → 3 → 4 → 4.5 → 5 → 5.7 → 5.8 → 6 → 7.) Produce ONE output block at Step 6, then auto-trigger or stop per Step 7.
 
 ### Step 0: MCP Health Gate
 
@@ -50,23 +50,11 @@ Extract `worktree_id` and `error_kind` from the JSON output.
 
 Pass `WORKTREE_ID` to MCP tools that support it. Null `WORKTREE_ID` means the (device, path, branch) tuple is unregistered — note this for Step 6.
 
-### Step 1.4: Home-Branch Fast-Forward
-
-Keep this worktree's **home branch** rooted at the freshest production tip — no prompt, fully non-blocking. Home branches are the folder-named placeholder branches each worktree rests on (e.g. `codebyplan-web`); `feat/*` branches are deliberately skipped — they integrate via `/cbp-merge-main` with QA, never an auto fast-forward.
-
-Run `codebyplan session home-ff` and parse the JSON output (`{ result: 'skipped'|'warn'|'fast_forwarded', reason?, warn? }`):
-
-- **`result === 'skipped'`** (non-home branch or production mismatch): proceed silently.
-- **`result === 'warn'`** (fast-forward attempt failed): surface the `warn` field as one line, then proceed silently.
-- **`result === 'fast_forwarded'`** (home branch updated): proceed silently.
-
-Never rebase, reset, force-push, or stash. A non-fast-forwardable home branch is a signal to reconcile manually, not to overwrite.
-
 ### Step 1.5: Infra Drift Check
 
-Surface — never block — when this worktree's source-monorepo `.claude/` infra has fallen behind. Runs after Step 1.4 and may add one line to the Step 6 output (`$PRODUCTION` is the branch resolved in Step 1.4). Consumer-repo package-version freshness is handled by Step 1.6 (the freshness gate), not here:
+Surface — never block — when this worktree's source-monorepo `.claude/` infra has fallen behind. Runs after Step 1 and may add one line to the Step 6 output (`$PRODUCTION` is `branch_config.production` read in Step 1). Consumer-repo package-version freshness is handled by Step 1.6 (the freshness gate), not here:
 
-- **Monorepo (concept A)** — both `packages/codebyplan-package/templates/` and `scripts/infra-drift.mjs` exist. Step 1.4 skips the fetch on a feat branch, so refresh `origin/$PRODUCTION` best-effort first, then run the reporter:
+- **Monorepo (concept A)** — both `packages/codebyplan-package/templates/` and `scripts/infra-drift.mjs` exist. Refresh `origin/$PRODUCTION` best-effort first, then run the reporter:
 
   ```bash
   git fetch origin "$PRODUCTION" 2>/dev/null || true
@@ -136,8 +124,6 @@ Run `codebyplan session freshness-gate --halt-on-update` and parse the JSON outp
 
     On this update-and-halt path the session is NOT continued: `update_session_state(activate)` is NOT called, `create_session_log` is NOT called, and `/cbp-todo` is NOT triggered.
 
-**Home branches are intentionally not guarded.** A worktree's folder-named home branch (e.g. `codebyplan-web`) is neither protected/main nor the canonical source, so the freshness gate returns `result !== 'guarded'` there and this gate fires exactly as on a feat branch. That is deliberate — the update lands on whatever branch the worktree is currently resting on (the "update the branch they're on, except main/canonical" decision), not an accidental halt.
-
 Populate the claude-status cache best-effort (pure cache population — never gates session-start):
 
 ```bash
@@ -271,7 +257,7 @@ Three-branch gate using `owned_count` and `total_count` from Step 5.8:
 
 - **Triggered by**: user invocation, `/clear` recovery
 - **Resolves**: `npx codebyplan resolve-worktree --json` (worktree id + distress signal; non-tuple-miss distress is non-blocking at session-start)
-- **Reads**: `.codebyplan/repo.json`, `.codebyplan/git.json` (`branch_config.production` for the Step 1.4 home-branch fast-forward), MCP `health_check` (Step 0 hard gate — stays MCP unconditionally); local-first reads (with `npx codebyplan sync` + MCP break-glass): `.codebyplan/state/session/current.json` (Step 4 previous log + Step 4.5 handoff probe), `.codebyplan/state/checkpoints/<id>.json` / `tasks/<id>.json` / `rounds/<id>.json` (Step 4.5 freshness probe), `.codebyplan/state/todos.json` (Step 5.7 active-task lookup); MCP `get_checkpoints({ repo_id, status: 'active' })` (Step 5.8 ownership partition — MCP only, no local mirror for active-filter query); `scripts/infra-drift.mjs` + a best-effort `git fetch` (Step 1.5 monorepo drift); `npx codebyplan arch-map drift` + `.codebyplan/architecture.json` presence (Step 1.55 architecture-map drift nudge, non-blocking); `codebyplan session home-ff` (Step 1.4 home-branch fast-forward); `codebyplan session freshness-gate --halt-on-update` (Step 1.6 package-freshness gate); `codebyplan session infra-files --json --task-files <csv>` (Step 5.7 infra-file set math); `npx codebyplan lsp --check` (Step 1.7 LSP binary nudge — reads `.codebyplan/lsp.json`, non-blocking). Reads at Step 3 and later do NOT fire on a Step 0 MCP hard-fail or the Step 1.6 update-and-halt path
+- **Reads**: `.codebyplan/repo.json`, `.codebyplan/git.json` (`branch_config.production` for Step 1.5 infra-drift fetch), MCP `health_check` (Step 0 hard gate — stays MCP unconditionally); local-first reads (with `npx codebyplan sync` + MCP break-glass): `.codebyplan/state/session/current.json` (Step 4 previous log + Step 4.5 handoff probe), `.codebyplan/state/checkpoints/<id>.json` / `tasks/<id>.json` / `rounds/<id>.json` (Step 4.5 freshness probe), `.codebyplan/state/todos.json` (Step 5.7 active-task lookup); MCP `get_checkpoints({ repo_id, status: 'active' })` (Step 5.8 ownership partition — MCP only, no local mirror for active-filter query); `scripts/infra-drift.mjs` + a best-effort `git fetch` (Step 1.5 monorepo drift); `npx codebyplan arch-map drift` + `.codebyplan/architecture.json` presence (Step 1.55 architecture-map drift nudge, non-blocking); `codebyplan session freshness-gate --halt-on-update` (Step 1.6 package-freshness gate); `codebyplan session infra-files --json --task-files <csv>` (Step 5.7 infra-file set math); `npx codebyplan lsp --check` (Step 1.7 LSP binary nudge — reads `.codebyplan/lsp.json`, non-blocking). Reads at Step 3 and later do NOT fire on a Step 0 MCP hard-fail or the Step 1.6 update-and-halt path
 - **Writes**: `codebyplan session create-log` (Step 5 — CLI write-through; break-glass: MCP `create_session_log`), `codebyplan session update-state --action activate` (Step 3 — CLI write-through to `.codebyplan/state/session/state.json`; break-glass: MCP `update_session_state`) — both SKIPPED on a Step 0 MCP hard-fail and on the Step 1.6 update-and-halt path
 - **Spawns**: none
 - **Triggers**: `/cbp-git-commit` (conditional, on user approval at Step 5.7 or the Step 1.6 update path), `handoff.command` (on fresh handoff hit at Step 4.5), `/cbp-todo` (auto fall-through when owned_count >= 1 or total_count === 0; STOPS with no trigger when total_count >= 1 AND owned_count === 0; NOT triggered on a Step 0 hard-fail or the Step 1.6 update-and-halt path)

package/templates/skills/cbp-supabase-migrate/SKILL.md

@@ -170,7 +170,7 @@ Stop.
 
 ### Record connection
 
-Record the branch so cleanup (see `cbp-checkpoint-end`, `cbp-git-worktree-remove`) and other
+Record the branch so cleanup (see `cbp-checkpoint-end`, `codebyplan worktree remove CHK-NNN`) and other
 skills can discover it. Phrase any context payload as prose — the MCP edge rejects raw
 uppercase database keywords (Cloudflare WAF).
 

package/templates/skills/cbp-git-worktree-create/SKILL.md

@@ -1,199 +0,0 @@
----
-name: cbp-git-worktree-create
-description: Create git worktree with clean command setup and register in CodeByPlan
-argument-hint: <branch-name> e.g. codebyplan-app
-effort: low
----
-
-# Git Worktree Create
-
-Create a git worktree as a sibling folder and register it in CodeByPlan. The worktree gets its own full copy of `.claude/` files on disk (rules, skills, hooks, agents, context) — git deduplicates at the object level so there's no real cost.
-
-## Arguments
-
-`$ARGUMENTS`: branch name — becomes both the branch name and the folder name.
-
-Examples:
-- `codebyplan-app` → folder `../codebyplan-app/`, branch `codebyplan-app`
-- `codebyplan-package` → folder `../codebyplan-package/`, branch `codebyplan-package`
-
-## Prerequisites
-
-- Must run from the **main repo** (the non-worktree checkout)
-- Working tree should be clean
-- Branch should not already exist as a worktree
-- New branches are always rooted at `origin/{production}` (read from `.codebyplan/git.json`), independent of the main repo's currently checked-out branch
-
-## Instructions
-
-### Step 1: Verify Main Repo
-
-```bash
-MAIN_REPO="$(git rev-parse --show-toplevel)"
-```
-
-Verify this is the main repo (not itself a worktree):
-
-```bash
-git rev-parse --git-dir
-```
-
-If the result is a file (not `.git` directory), this is already a worktree. Stop:
-
-```
-## Error
-
-Run this command from the main repo, not from a worktree.
-Main repo: [path from git-common-dir parent]
-```
-
-### Step 2: Validate Arguments
-
-If `$ARGUMENTS` is empty, ask the user:
-
-```
-What should the worktree be called? (e.g. codebyplan-app)
-```
-
-Set:
-- `BRANCH_NAME` = `$ARGUMENTS`
-- `WORKTREE_PATH` = `$MAIN_REPO/../$BRANCH_NAME`
-
-### Step 3: Check for Conflicts
-
-Check if the worktree already exists:
-
-```bash
-git worktree list | grep "$BRANCH_NAME"
-```
-
-If it exists:
-```
-## Worktree Already Exists
-
-Branch `[name]` is already checked out at [path].
-
-Use `/cbp-git-worktree-remove [name]` to remove it first.
-```
-Stop here.
-
-Check if the folder already exists:
-
-```bash
-ls -d "$WORKTREE_PATH" 2>/dev/null
-```
-
-If it exists, stop and inform the user.
-
-### Step 4: Create Branch If Needed
-
-Resolve the production branch: read `.codebyplan/git.json` and take `branch_config.production` (fall back to `main` if the file or field is absent). Call this `$PRODUCTION`.
-
-Check if branch exists:
-
-```bash
-git branch --list "$BRANCH_NAME"
-```
-
-If branch does NOT exist, create it from the freshest production tip — **not** from the main repo's ambient HEAD (which is often a stale home branch such as `codebyplan-main`):
-
-```bash
-git fetch origin "$PRODUCTION" 2>/dev/null || true
-git branch "$BRANCH_NAME" "origin/$PRODUCTION"
-```
-
-This guarantees every worktree starts at `origin/{production}` regardless of which branch the main repo currently has checked out.
-
-### Step 5: Create Worktree
-
-```bash
-git worktree add "$WORKTREE_PATH" "$BRANCH_NAME"
-```
-
-### Step 6: Set Up MCP Connection
-
-Copy `.mcp.json` from the main repo to the worktree. The file is committed and contains only the public MCP URL (no secret), so this is a plain `cp` — no path rewriting or key substitution needed:
-
-```bash
-cp "$MAIN_REPO/.mcp.json" "$WORKTREE_PATH/.mcp.json"
-```
-
-Expected shape (do NOT rewrite paths — this is remote HTTP):
-
-```json
-{
-  "mcpServers": {
-    "codebyplan": {
-      "type": "http",
-      "url": "https://mcp.codebyplan.com/mcp"
-    }
-  }
-}
-```
-
-### Step 7: Set Up Environment
-
-Copy `.env.local` from the main repo to the worktree (contains the app's environment variables such as Supabase keys and feature flags — MCP auth is OAuth Bearer handled by Claude Code, not a key in this file):
-
-```bash
-cp "$MAIN_REPO/.env.local" "$WORKTREE_PATH/.env.local"
-```
-
-Verify `.env.local` is already in `.gitignore` (it should be via `.env.local` pattern). If not, add it.
-
-Also copy the gitignored E2E credentials source (`.codebyplan/e2e.env`, referenced by `.codebyplan/e2e.json`) so the new worktree can run Playwright auth flows immediately:
-
-```bash
-mkdir -p "$WORKTREE_PATH/.codebyplan"
-if [ -f "$MAIN_REPO/.codebyplan/e2e.env" ]; then
-  cp "$MAIN_REPO/.codebyplan/e2e.env" "$WORKTREE_PATH/.codebyplan/e2e.env"
-fi
-```
-
-If the main repo has no `.codebyplan/e2e.env` yet, provision it after setup by running `codebyplan ports --path "$WORKTREE_PATH" --provision-e2e` (copies the canonical E2E vars from `apps/web/.env.local`). Pass `--path` BEFORE the boolean flag. `.codebyplan/e2e.env` is gitignored — never commit it.
-
-### Step 8: Push Branch
-
-```bash
-cd "$WORKTREE_PATH" && git push -u origin "$BRANCH_NAME"
-```
-
-### Step 9: Register Worktree and Write `.codebyplan/` Config
-
-Run `codebyplan worktree create "$BRANCH_NAME" --path "$WORKTREE_PATH"` and parse the JSON output (`{ worktree_files_written: boolean, mcp_registered: boolean, worktree_id?, warn? }`):
-
-- If `warn` is present: surface it as a non-blocking warning.
-- Save the returned `worktree_id` for reference (if present).
-
-The CLI atomically writes the `.codebyplan/` directory with per-concern config stubs and registers the worktree in the CodeByPlan database. The `.codebyplan/device.local.json` file is created by `npx codebyplan setup` on the device (gitignored). The `worktree_id` is never COMMITTED; it may be cached per-device in the gitignored `.codebyplan/worktree.local.json` (branch-keyed, re-derivable via `codebyplan resolve-worktree --cache`), otherwise resolved at runtime from the `(device_id, repo path, branch)` tuple via `npx codebyplan resolve-worktree`.
-
-No need to mark as `skip-worktree` — the committed files are merge-safe per CHK-108 and CHK-120.
-
-### Step 10: Show Result
-
-```
-## Worktree Created
-
-**Branch**: [branch-name]
-**Path**: [worktree-path]
-**Main repo**: [main-repo-path]
-**Base**: origin/[production] ([sha])
-**CodeByPlan**: Registered (worktree ID: [id])
-
-### Setup
-- MCP: connected (remote endpoint, OAuth Bearer)
-- `.claude/` files: full copy on disk (rules, skills, hooks, agents, context)
-
-### Next Steps
-- Open `[worktree-path]` in your editor
-- Run `/cbp-session-start` to begin working
-- Checkpoints can be assigned to this worktree via `worktree_id`
-
-### Existing Worktrees
-[output of git worktree list]
-```
-
-## Integration
-
-- **Related**: `/cbp-git-worktree-remove` (cleanup and deregister)
-- **CLI**: `codebyplan worktree create <name> --path <abs>` (Step 9 — writes `.codebyplan/` config and registers worktree)

package/templates/skills/cbp-git-worktree-remove/SKILL.md

@@ -1,144 +0,0 @@
----
-name: cbp-git-worktree-remove
-description: Remove git worktree and deregister from CodeByPlan
-argument-hint: <name> e.g. codebyplan-app
-effort: low
----
-
-# Git Worktree Remove
-
-Remove a git worktree folder, deregister it from CodeByPlan, and optionally delete its branch.
-
-## Arguments
-
-`$ARGUMENTS`: worktree name or path to remove.
-
-## Prerequisites
-
-- Must run from the **main repo** (not from the worktree being removed)
-
-## Instructions
-
-### Step 1: Verify Main Repo
-
-```bash
-MAIN_REPO="$(git rev-parse --show-toplevel)"
-```
-
-Verify not in a worktree (`.git` should be a directory, not a file).
-
-### Step 2: List Worktrees
-
-```bash
-git worktree list
-```
-
-If `$ARGUMENTS` is empty, show the list and ask which to remove.
-
-### Step 3: Resolve Worktree
-
-Find matching worktree from the list. Match by:
-1. Exact path
-2. Folder name (e.g. `codebyplan-app`)
-3. Branch name
-
-If no match found, show available worktrees and stop.
-
-Set:
-- `WORKTREE_PATH` = resolved path
-- `BRANCH_NAME` = branch checked out in that worktree
-
-### Step 4: Look Up and Deregister Worktree in CodeByPlan
-
-Run `codebyplan worktree remove "$BRANCH_NAME"` and parse the JSON output (`{ mcp_deregistered: boolean, warn? }`):
-
-- If `warn` is present: surface it as a non-blocking warning. The worktree was not found in CodeByPlan or deregistration failed, but local removal will proceed.
-- If `mcp_deregistered === true`: worktree was successfully deregistered.
-- If `mcp_deregistered === false`: worktree was not registered or deregistration failed; continue with local removal.
-
-### Step 5: Check for Assigned Checkpoints
-
-If the worktree was successfully deregistered in Step 4 (`mcp_deregistered === true`), any checkpoints that were assigned to it will become unassigned. This is expected behavior and requires no additional action.
-
-### Step 6: Confirm with User
-
-```
-## Remove Worktree
-
-**Path**: [worktree-path]
-**Branch**: [branch-name]
-**CodeByPlan**: [registered | not registered]
-
-Remove worktree and delete the branch? (The main repo is not affected)
-```
-
-Ask:
-1. Remove worktree only (keep branch)
-2. Remove worktree and delete branch
-3. Cancel
-
-### Step 7: Remove Git Worktree
-
-```bash
-git worktree remove "$WORKTREE_PATH"
-```
-
-If force needed (uncommitted changes):
-```bash
-git worktree remove --force "$WORKTREE_PATH"
-```
-
-Only use `--force` if the user confirms.
-
-### Step 8: Delete Branch (if requested)
-
-**Protected branch check:** Read the protected set from `.codebyplan/git.json`:
-```bash
-PRODUCTION=$(jq -r '.branch_config.production // "main"' .codebyplan/git.json)
-PROTECTED=$(jq -r '.branch_config.protected[]? // empty' .codebyplan/git.json)
-```
-If `$BRANCH_NAME` equals `$PRODUCTION` or appears in `$PROTECTED` — refuse deletion and stop.
-
-**Checkpoint verification:** Before deleting a feat branch, verify that the associated checkpoint has completed via `/cbp-checkpoint-end`. If the checkpoint is still active, warn the user that unshipped work may be lost.
-
-```bash
-git branch -d "$BRANCH_NAME" && git push origin --delete "$BRANCH_NAME"
-```
-
-Use `-d` (not `-D`) to prevent deleting unmerged work. If it fails because the branch is not fully merged, inform the user and ask if they want to force delete with `-D`.
-
-After the git branch delete succeeds, run a conditional Supabase preview-branch teardown for `$BRANCH_NAME`:
-
-> Lifecycle contract: see [[supabase-branch-lifecycle]].
-
-- Resolve the parent project ref and apply the lifecycle guard in one deterministic call:
-
-  ```bash
-  codebyplan supabase teardown-preview "$BRANCH_NAME"
-  ```
-
-  Parse its JSON `{ status, parent_ref, project_ref, reason }`. The command never deletes anything — it reads the parent ref from `.codebyplan/shipment.json` (`.shipment.surfaces.supabase.project_ref`) and applies the protected / production / parent-ref guard from [[supabase-branch-lifecycle]].
-- If `status === "rejected"`: STOP the teardown and surface `reason` — never delete a production / protected / integration branch or one whose preview ref equals the parent.
-- Otherwise (`allowed` or `not_found`), use `parent_ref` for the live existence check — `mcp__supabase__list_branches` with `project_id: <parent_ref>`, then scan for an entry whose `name` exactly equals `$BRANCH_NAME`:
-  - If found: call `mcp__supabase__delete_branch` with its `branch_id`. Report "Supabase preview branch deleted: `$BRANCH_NAME`".
-  - If not found: no-op silently — the GitHub integration may have already removed it on PR close; not-found is success, NOT an error.
-  - If the `list_branches` call itself fails (network, auth, or a non-success response — distinct from a successful lookup that returns no match): emit a non-blocking warning that the Supabase preview branch for `$BRANCH_NAME` may still exist and should be verified in the dashboard. Do not treat an API failure as a not-found success.
-- Never delete the parent project (`parent_ref` from `codebyplan supabase teardown-preview`) itself or any persistent/production branch — the `teardown-preview` guard enforces this.
-
-### Step 9: Show Result
-
-```
-## Worktree Removed
-
-**Removed**: [worktree-path]
-**Branch**: [deleted | kept]
-**CodeByPlan**: [deregistered | was not registered]
-
-### Remaining Worktrees
-[output of git worktree list]
-```
-
-## Integration
-
-- **Related**: `/cbp-git-worktree-create` (create and register)
-- **CLI**: `codebyplan worktree remove <name>` (Step 4 — deregister from CodeByPlan)