codebyplan 1.13.11 → 1.13.13

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.11";
+    VERSION = "1.13.13";
     PACKAGE_NAME = "codebyplan";
   }
 });
@@ -1281,7 +1281,11 @@ var init_template_walker = __esm({
       "hooks/validate-structure-lengths.sh",
       "hooks/validate-structure-smoke.sh",
       "hooks/validate-context-usage.sh",
-      "hooks/validate-git-commit.sh"
+      "hooks/validate-git-commit.sh",
+      // Advisory GATE-6 sibling-identity nudge — fires ONLY in the templates source
+      // repo (detects packages/codebyplan-package/templates/). A no-op for consumers,
+      // so it ships neither in hooks.json nor as a copied file.
+      "hooks/cbp-canonical-templates-nudge.sh"
     ]);
   }
 });
@@ -5897,6 +5901,310 @@ var init_resolve_worktree2 = __esm({
   }
 });
 
+// src/cli/create-org.ts
+var create_org_exports = {};
+__export(create_org_exports, {
+  runCreateOrg: () => runCreateOrg
+});
+import { stdin as stdin3, stdout as stdout4 } from "node:process";
+import { createInterface as createInterface3 } from "node:readline/promises";
+function deriveSlug(name) {
+  const trimmed = name.trim();
+  if (trimmed === "") return "";
+  const slug = trimmed.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug || "org";
+}
+async function runCreateOrg() {
+  const rl = createInterface3({ input: stdin3, output: stdout4 });
+  console.log("\n  CodeByPlan \u2014 Create Organization\n");
+  try {
+    const rawName = (await rl.question("  Organization name: ")).trim();
+    if (!rawName) {
+      console.error("\n  Error: Organization name cannot be empty.\n");
+      process.exitCode = 1;
+      return;
+    }
+    const slug = deriveSlug(rawName);
+    if (slug) {
+      console.log(`  Slug preview: ${slug}
+`);
+    }
+    let response;
+    try {
+      response = await apiPost("/organizations", {
+        name: rawName
+      });
+    } catch (err) {
+      if (err instanceof ApiError) {
+        console.error(`
+  Error: ${err.message} (HTTP ${err.status})
+`);
+      } else {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`
+  Error: ${msg}
+`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+    const org = response.data;
+    console.log("\n  Organization created successfully.\n");
+    console.log(`    id:   ${org.id}`);
+    console.log(`    name: ${org.name}`);
+    console.log(`    slug: ${org.slug}
+`);
+  } finally {
+    rl.close();
+  }
+}
+var init_create_org = __esm({
+  "src/cli/create-org.ts"() {
+    "use strict";
+    init_api();
+  }
+});
+
+// src/cli/create-project.ts
+var create_project_exports = {};
+__export(create_project_exports, {
+  runCreateProject: () => runCreateProject
+});
+import { stdin as stdin4, stdout as stdout5 } from "node:process";
+import { createInterface as createInterface4 } from "node:readline/promises";
+function deriveSlug2(name) {
+  const trimmed = name.trim();
+  if (trimmed === "") return "";
+  const slug = trimmed.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug || "project";
+}
+async function runCreateProject() {
+  const rl = createInterface4({ input: stdin4, output: stdout5 });
+  console.log("\n  CodeByPlan \u2014 Create Project\n");
+  try {
+    const orgIdFlag = (() => {
+      const idx = process.argv.indexOf("--org-id");
+      return idx !== -1 ? process.argv[idx + 1] ?? "" : "";
+    })();
+    let organizationId;
+    if (orgIdFlag) {
+      organizationId = orgIdFlag.trim();
+    } else {
+      let orgs = null;
+      try {
+        const resp = await apiGet("/organizations");
+        if (resp.data && resp.data.length > 0) {
+          orgs = resp.data;
+        }
+      } catch {
+      }
+      if (orgs && orgs.length > 0) {
+        console.log("  Available organizations:\n");
+        orgs.forEach((org, i) => {
+          console.log(`    ${i + 1}. ${org.name} (${org.slug})  [${org.id}]`);
+        });
+        console.log("");
+        const rawChoice = (await rl.question(
+          `  Select organization (1\u2013${orgs.length}) or paste an org ID: `
+        )).trim();
+        const choiceNum = parseInt(rawChoice, 10);
+        if (!isNaN(choiceNum) && choiceNum >= 1 && choiceNum <= orgs.length) {
+          organizationId = orgs[choiceNum - 1].id;
+        } else if (rawChoice) {
+          organizationId = rawChoice;
+        } else {
+          console.error("\n  Error: Organization selection cannot be empty.\n");
+          process.exitCode = 1;
+          return;
+        }
+      } else {
+        const rawOrgId = (await rl.question("  Organization ID: ")).trim();
+        if (!rawOrgId) {
+          console.error("\n  Error: Organization ID cannot be empty.\n");
+          process.exitCode = 1;
+          return;
+        }
+        organizationId = rawOrgId;
+      }
+    }
+    const rawName = (await rl.question("  Project name: ")).trim();
+    if (!rawName) {
+      console.error("\n  Error: Project name cannot be empty.\n");
+      process.exitCode = 1;
+      return;
+    }
+    const slug = deriveSlug2(rawName);
+    if (slug) {
+      console.log(`  Slug preview: ${slug}
+`);
+    }
+    let response;
+    try {
+      response = await apiPost("/projects", {
+        organization_id: organizationId,
+        name: rawName
+      });
+    } catch (err) {
+      if (err instanceof ApiError) {
+        console.error(`
+  Error: ${err.message} (HTTP ${err.status})
+`);
+      } else {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`
+  Error: ${msg}
+`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+    const project = response.data;
+    console.log("\n  Project created successfully.\n");
+    console.log(`    id:   ${project.id}`);
+    console.log(`    name: ${project.name}`);
+    console.log(`    slug: ${project.slug}
+`);
+  } finally {
+    rl.close();
+  }
+}
+var init_create_project = __esm({
+  "src/cli/create-project.ts"() {
+    "use strict";
+    init_api();
+  }
+});
+
+// src/cli/create-repo.ts
+var create_repo_exports = {};
+__export(create_repo_exports, {
+  runCreateRepo: () => runCreateRepo
+});
+import { stdin as stdin5, stdout as stdout6 } from "node:process";
+import { createInterface as createInterface5 } from "node:readline/promises";
+async function runCreateRepo() {
+  const rl = createInterface5({ input: stdin5, output: stdout6 });
+  console.log("\n  CodeByPlan \u2014 Create Repository\n");
+  try {
+    const projectIdFlag = (() => {
+      const idx = process.argv.indexOf("--project-id");
+      return idx !== -1 ? process.argv[idx + 1] ?? "" : "";
+    })();
+    let projectId;
+    if (projectIdFlag) {
+      const trimmedFlag = projectIdFlag.trim();
+      if (!UUID_RE.test(trimmedFlag)) {
+        console.error("\n  Error: Project ID must be a valid UUID.\n");
+        process.exitCode = 1;
+        return;
+      }
+      projectId = trimmedFlag;
+    } else {
+      let projects = null;
+      try {
+        const resp = await apiGet("/projects");
+        if (resp.data && resp.data.length > 0) {
+          projects = resp.data;
+        }
+      } catch {
+      }
+      if (projects && projects.length > 0) {
+        console.log("  Available projects:\n");
+        projects.forEach((proj, i) => {
+          console.log(
+            `    ${i + 1}. ${proj.name} (${proj.slug})  [${proj.id}]`
+          );
+        });
+        console.log("");
+        const rawChoice = (await rl.question(
+          `  Select project (1\u2013${projects.length}) or paste a project ID: `
+        )).trim();
+        const choiceNum = parseInt(rawChoice, 10);
+        if (!isNaN(choiceNum) && choiceNum >= 1 && choiceNum <= projects.length) {
+          projectId = projects[choiceNum - 1].id;
+        } else if (rawChoice) {
+          if (!UUID_RE.test(rawChoice)) {
+            console.error("\n  Error: Project ID must be a valid UUID.\n");
+            process.exitCode = 1;
+            return;
+          }
+          projectId = rawChoice;
+        } else {
+          console.error("\n  Error: Project selection cannot be empty.\n");
+          process.exitCode = 1;
+          return;
+        }
+      } else {
+        const rawProjectId = (await rl.question("  Project ID: ")).trim();
+        if (!rawProjectId) {
+          console.error("\n  Error: Project ID cannot be empty.\n");
+          process.exitCode = 1;
+          return;
+        }
+        if (!UUID_RE.test(rawProjectId)) {
+          console.error("\n  Error: Project ID must be a valid UUID.\n");
+          process.exitCode = 1;
+          return;
+        }
+        projectId = rawProjectId;
+      }
+    }
+    const rawName = (await rl.question("  Repository name: ")).trim();
+    if (!rawName) {
+      console.error("\n  Error: Repository name cannot be empty.\n");
+      process.exitCode = 1;
+      return;
+    }
+    const rawPath = (await rl.question("  Local path (optional, press Enter to skip): ")).trim();
+    const rawBranch = (await rl.question(
+      "  Default git branch (optional, press Enter for 'main'): "
+    )).trim();
+    const git_branch = rawBranch || "main";
+    let response;
+    try {
+      response = await apiPost("/repos", {
+        project_id: projectId,
+        name: rawName,
+        ...rawPath ? { path: rawPath } : {},
+        git_branch
+      });
+    } catch (err) {
+      if (err instanceof ApiError) {
+        console.error(`
+  Error: ${err.message} (HTTP ${err.status})
+`);
+      } else {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`
+  Error: ${msg}
+`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+    const repo = response.data;
+    console.log("\n  Repository created successfully.\n");
+    console.log(`    id:         ${repo.id}`);
+    console.log(`    name:       ${repo.name}`);
+    console.log(`    git_branch: ${repo.git_branch ?? git_branch}`);
+    console.log(
+      `
+  Tip: run \`codebyplan setup\` from the repo directory to link it.
+`
+    );
+  } finally {
+    rl.close();
+  }
+}
+var UUID_RE;
+var init_create_repo = __esm({
+  "src/cli/create-repo.ts"() {
+    "use strict";
+    init_api();
+    UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  }
+});
+
 // src/cli/version-status.ts
 var version_status_exports = {};
 __export(version_status_exports, {
@@ -7875,6 +8183,21 @@ void (async () => {
     await runResolveWorktree2();
     process.exit(0);
   }
+  if (arg === "create-org") {
+    const { runCreateOrg: runCreateOrg2 } = await Promise.resolve().then(() => (init_create_org(), create_org_exports));
+    await runCreateOrg2();
+    process.exit(0);
+  }
+  if (arg === "create-project") {
+    const { runCreateProject: runCreateProject2 } = await Promise.resolve().then(() => (init_create_project(), create_project_exports));
+    await runCreateProject2();
+    process.exit(0);
+  }
+  if (arg === "create-repo") {
+    const { runCreateRepo: runCreateRepo2 } = await Promise.resolve().then(() => (init_create_repo(), create_repo_exports));
+    await runCreateRepo2();
+    process.exit(0);
+  }
   if (arg === "version-status") {
     const { runVersionStatus: runVersionStatus2 } = await Promise.resolve().then(() => (init_version_status(), version_status_exports));
     await runVersionStatus2();
@@ -7970,6 +8293,9 @@ void (async () => {
     codebyplan logout                Clear cached OAuth tokens
     codebyplan whoami                Show currently authenticated identity
     codebyplan upgrade-auth          Migrate legacy x-api-key MCP config to OAuth
+    codebyplan create-org            Create a new organization (interactive prompt)
+    codebyplan create-project        Create a new project within an organization (interactive prompt)
+    codebyplan create-repo           Create a new repository within a project (interactive prompt)
     codebyplan config                Sync repo config from DB to .codebyplan/ files
     codebyplan ports                 Verify port allocations against local package.json scripts
     codebyplan tech-stack            Detect and sync tech stack dependencies

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.13.11",
+  "version": "1.13.13",
   "description": "CLI for CodeByPlan — AI-powered development planning and tracking",
   "type": "module",
   "bin": {
@@ -61,6 +61,6 @@
     "prettier": "^3.8.1",
     "typescript": "^5",
     "typescript-eslint": "^8.20.0",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.2"
   }
 }

package/templates/agents/cbp-research.md

@@ -9,6 +9,8 @@ effort: xhigh
 
 # Research Agent
 
+> Adheres to [[agent-claim-verification]] — cite a source file (`path:line`) or vendor docs before asserting any JSON key, schema field, env-var, or API shape exists.
+
 Intelligent research with discovery levels (0-3). Consults `.claude/docs/stack/` first, uses web research when needed, produces DISCOVERY.md for Level 2+.
 
 ## Purpose

package/templates/agents/cbp-round-executor.md

@@ -9,6 +9,8 @@ effort: xhigh
 
 # Round Executor Agent
 
+> Adheres to [[agent-claim-verification]] — cite a source file (`path:line`) or vendor docs before asserting any JSON key, schema field, env-var, or API shape exists.
+
 Execute an already-approved implementation plan. The planner agent has already done analysis and the user has approved the plan - this agent focuses purely on quality execution.
 
 ## Purpose

package/templates/agents/cbp-task-planner.md

@@ -531,6 +531,7 @@ After Phase 5 (solution design) and before Phase 6 (context summary), decompose
 3. **Check DAG invariant**: `depends_on[]` must be acyclic. Any cycle is a plan error — resolve by merging the cyclic waves.
 4. **Populate `skill_preloads[]`**: for each wave whose `files[]` contains UI-bearing paths (`*.tsx`, `*.jsx`, `*.scss`, etc.), add `"frontend-design"` and `"frontend-a11y"` to `skill_preloads[]` (in that order).
 5. **Single-wave default**: if no independence is found, produce ONE wave covering all files. Parallel waves add orchestration overhead — only decompose when the benefit is clear.
+6. **15-file cap**: after decomposition (including the single-wave default), count files in each wave. If any wave would exceed 15 files, auto-split it using the proximity-split algorithm in priority order: (a) **shared directory subtree** — split at the deepest common ancestor that produces two groups each ≥3 files; (b) **shared module** — split at the next directory level below the common ancestor; (c) **arbitrary boundary** — split at the 15-file boundary and add a one-line `note` on the continuation wave explaining the boundary. Split siblings are **independent**: do NOT add `depends_on` between them unless a real shared-file or data dependency requires ordering. **Tail rule**: choose boundaries so every resulting wave holds 3–15 files. A split must never leave a wave with <3 files; rebalance the boundary rather than absorbing a tail into a sibling in a way that pushes it above 15. The 3–15 range is a hard invariant — there is no exception above 15. **Apply the cap iteratively**: after a split, re-check each resulting wave and split again any that still exceeds 15 — a 40-file single-concern plan therefore yields ≥3 waves. When no natural boundary yields groups each ≥3 files, take the smallest ≥3-file prefix as one wave and apply the same procedure to the remainder. The single-wave default is itself subject to this cap. See `rules/parallel-waves.md` for the full algorithm and invariants.
 
 **Output** (added to plan):
 
@@ -541,6 +542,7 @@ plan.waves:
     files: string[]
     depends_on: string[]
     skill_preloads: string[]
+    note: string  # optional — set on continuation waves from an arbitrary-boundary split
 ```
 
 If `files_to_modify[]` contains ≤5 files across a single app, skip decomposition and emit a single wave or omit `waves[]` entirely (single-wave default in `round-execute` handles this gracefully).
@@ -550,7 +552,8 @@ If `files_to_modify[]` contains ≤5 files across a single app, skip decompositi
 - [ ] Every file in `files_to_modify[]` appears in exactly one wave
 - [ ] `depends_on[]` forms a DAG (no cycles)
 - [ ] UI-bearing waves have `frontend-design` + `frontend-a11y` in `skill_preloads[]`
-- [ ] Each wave has ≥3 files (if not, merge into parent wave)
+- [ ] Each wave has ≥3 files (if not, merge into sibling wave)
+- [ ] No wave has >15 files (if so, apply the proximity-split algorithm)
 
 ### Phase 6: Build Context Summary
 

package/templates/hooks/cbp-canonical-templates-nudge.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# @scope: org-shared
+# @event: PreToolUse
+# @matcher: Edit|Write|MultiEdit
+# Advisory source-of-truth nudge. When editing a GATE-6-tracked .claude/ file
+# (skills/agents/hooks/rules) that already has a packages/codebyplan-package/
+# templates/ counterpart, remind the author to mirror the change so the two
+# trees stay byte-identical (scripts/check-sibling-identity.mjs / GATE 6).
+#
+# Fires ONLY in the templates source repo, detected by the presence of
+# packages/codebyplan-package/templates/. Always exits 0 — advisory only,
+# never blocks the edit. (set -u catches typos; -e / -o pipefail are
+# deliberately omitted so the hook can never abort mid-run.)
+
+set -u
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+
+case "$TOOL_NAME" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+# MultiEdit shares the single top-level tool_input.file_path with Edit/Write
+# (only the per-edit content differs); filePath is a defensive camelCase fallback.
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.filePath // empty' 2>/dev/null)
+[ -z "$FILE_PATH" ] && exit 0
+
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+[ -z "$REPO_ROOT" ] && exit 0
+# Symlink-resolve so a /Users vs /private/Users mismatch (macOS) still compares equal.
+REPO_ROOT=$(cd "$REPO_ROOT" 2>/dev/null && pwd -P || echo "$REPO_ROOT")
+
+TEMPLATES_DIR="$REPO_ROOT/packages/codebyplan-package/templates"
+# Not the templates source repo → nothing to mirror.
+[ -d "$TEMPLATES_DIR" ] || exit 0
+
+# Resolve the edited path to a repo-root-relative form. Absolute paths are
+# symlink-normalised (so the prefix match is apples-to-apples); relative paths
+# are taken as-is.
+case "$FILE_PATH" in
+  /*)
+    _dir=$(cd "$(dirname "$FILE_PATH")" 2>/dev/null && pwd -P || echo "")
+    [ -z "$_dir" ] && exit 0
+    FILE_PATH="$_dir/$(basename "$FILE_PATH")"
+    case "$FILE_PATH" in
+      "$REPO_ROOT"/*) REL="${FILE_PATH#"$REPO_ROOT"/}" ;;
+      *) exit 0 ;;
+    esac
+    ;;
+  *) REL="$FILE_PATH" ;;
+esac
+
+# Only the GATE-6-tracked subtrees: .claude/{skills,agents,hooks,rules}/...
+case "$REL" in
+  .claude/skills/*|.claude/agents/*|.claude/hooks/*|.claude/rules/*) ;;
+  *) exit 0 ;;
+esac
+
+SUBREL="${REL#.claude/}"
+COUNTERPART="$TEMPLATES_DIR/$SUBREL"
+
+if [ -e "$COUNTERPART" ]; then
+  echo "cbp: editing .claude/$SUBREL — also mirror this change to packages/codebyplan-package/templates/$SUBREL to keep them byte-identical (GATE 6: node scripts/check-sibling-identity.mjs). Advisory only; continuing." >&2
+fi
+
+exit 0

package/templates/rules/agent-claim-verification.md

@@ -0,0 +1,50 @@
+---
+scope: org-shared
+name: agent-claim-verification
+description: Subagents must cite the source file (path:line) or vendor docs before asserting that any JSON key, schema field, env-var name, or external API shape exists.
+paths:
+  - ".claude/agents/**/*"
+---
+
+# Agent Claim Verification
+
+<!-- Delivery: subagents receive this rule via the [[agent-claim-verification]] pointer in each
+     agent's .md file. The `paths:` frontmatter surfaces it when an agent file is being *edited*,
+     not when the agent is *running* — both mechanisms are intentional, so don't drop the pointer.
+     Scope is agents-only by design (cbp-round-executor, cbp-research); skill files are out of
+     scope this round. -->
+
+Subagents routinely emit tool calls and explanatory text that depend on a named thing *existing* — a JSON config key, a schema field, an environment-variable name, an external API's request/response shape. When that name is recalled from memory instead of read from the source, it is often subtly wrong: a renamed field, a key that moved to a different file, an API shape from an older version. Those hallucinated names cost correction rounds.
+
+## The Rule
+
+Before stating that a **JSON key, schema field, env-var name, or external API shape exists**, the agent MUST first read the authoritative source and cite it inline:
+
+- **In-repo facts** → cite the source file as `path:line` (e.g. `packages/cli/src/config.ts:42`).
+- **External library / API facts** → cite the vendored docs as `vendor/{lib}/v{ver}/{file}` (or the upstream URL when no vendor mirror exists).
+
+A claim that cannot be cited has not been verified — do not state it as fact. Read the file first, or mark the statement explicitly as an assumption still to confirm.
+
+## Applies When
+
+- Emitting a tool call whose correctness depends on a named key/field/shape (passing a config key, asserting an MCP tool parameter, referencing a settings field).
+- Writing explanatory prose that asserts a named key/field/env-var/API shape is present.
+
+## Does NOT Apply To
+
+- **Structural proposals** — "this *should* be a new `retryDelay` field" is a proposal, not a claim. Proposals describe what ought to exist; they need no citation.
+- Well-known language/runtime built-ins (`Array.prototype.map`, `JSON.parse`) — not the failure mode this rule targets.
+
+## Examples
+
+**BAD** (unverified — the field name is recalled, not read):
+
+> The merge config supports a `retryDelay` field, so set it to 500.
+
+**GOOD** (read and cited):
+
+> The merge config schema at `packages/codebyplan-package/src/lib/settings-merge.ts:31` defines `conflictStrategy` (there is no `retryDelay` field), so use `conflictStrategy: "theirs"`.
+
+## Why
+
+Silent recall of config/API names is the single cheapest-to-prevent class of subagent error: one `Read` before the claim replaces a correction round after it. The citation doubles as an audit trail — a reviewer can confirm the fact at the cited line without re-deriving it.

package/templates/rules/context-file-loading.md

@@ -23,6 +23,7 @@ paths:
 | `context/testing/eslint.md` | `cbp-improve-round` | Phase 1.5 | Config-file compliance audit |
 | `context/mcp-docs.md` | `cbp-task-planner` | Phase 2.6 | MCP library doc lookup contract — per-dependency consultation via DocsByPlan MCP tools (resolve_library_id → search_chunks/lookup_symbol → get_chunk) |
 | `context/mcp-docs.md` | `cbp-round-executor` | Step 3.4 | Library-specific reference — pre-write API verification via DocsByPlan MCP tools |
+| `rules/parallel-waves.md` | `cbp-task-planner` | Phase 5.6 | Wave schema, invariants (3..15 file-count), and the proximity-split algorithm (a `rules/` file, not `context/**`; listed here for consumer discoverability) |
 
 New context files MUST be added here in the same change that introduces the consumer — or the file is orphan infrastructure.
 

package/templates/rules/parallel-waves.md

@@ -0,0 +1,59 @@
+---
+scope: org-shared
+name: parallel-waves
+description: Wave schema, invariants, and proximity-split algorithm for cbp-task-planner Phase 5.6 wave decomposition.
+paths:
+  - .claude/agents/cbp-task-planner.md
+---
+
+# Parallel Waves
+
+Authoritative expansion of `cbp-task-planner` Phase 5.6. The planner reads this file at wave decomposition time.
+
+## Wave Schema
+
+Each entry in `plan.waves[]` carries these fields (source: `.claude/agents/cbp-task-planner.md:540`):
+
+```yaml
+- name: string               # short identifier, e.g. "web-ui", "backend", "db"
+  agent_type: 'round-executor' | 'inline'
+  files: string[]            # repo-relative paths owned by this wave
+  depends_on: string[]       # names of waves that must complete before this one starts
+  skill_preloads: string[]   # skills invoked by the executor before Step 3 (e.g. "frontend-design")
+  note: string               # optional — required on continuation waves from an arbitrary-boundary split
+```
+
+## Invariants
+
+**(I) Disjoint files** — a file appears in exactly one wave. If two waves need a shared file, assign it to the earlier wave; the later wave lists the earlier in `depends_on`.
+
+**(II) DAG** — `depends_on[]` must be acyclic. A cycle is a plan error; resolve by merging the cyclic waves.
+
+**(III) 3–15 files per wave** — every wave holds between 3 and 15 files (inclusive).
+  - Below 3: merge into a sibling wave.
+  - Above 15: apply the proximity-split algorithm below.
+  - Sole exception — trivially small plans are exempt from the lower bound: a plan with fewer than 3 total files uses one single wave, and a single-app plan with ≤5 total files MAY skip decomposition entirely (one wave, or `waves[]` omitted — see `cbp-task-planner` Phase 5.6). Zero waves (omitted `waves[]`) trivially satisfies this invariant.
+
+**(IV) UI skill preloads** — for each wave whose `files[]` contains UI-bearing paths (`*.tsx`, `*.jsx`, `*.scss`, etc.), add `"frontend-design"` and `"frontend-a11y"` to `skill_preloads[]` in that order (source: `.claude/agents/cbp-task-planner.md:532`).
+
+## Proximity-Split Algorithm
+
+When a wave would exceed 15 files, split it in priority order:
+
+1. **Shared directory subtree** — split at the deepest common ancestor that produces two groups each ≥3 files. This is the preferred split because it keeps logically related files together.
+2. **Shared module** — split at the next directory level below the common ancestor when subtree split cannot achieve ≥3 per group.
+3. **Arbitrary boundary** — split at the 15-file boundary as a last resort. The continuation wave MUST carry a one-line `note` field explaining the boundary (e.g. `"files 16–28 of auth module, continued from auth-1"`).
+
+**Independence clause** — split siblings are independent. Do NOT add `depends_on` between them unless a real shared-file or data dependency requires ordering.
+
+**Tail rule** — choose split boundaries so every resulting wave holds 3–15 files. A split must never leave a wave with fewer than 3 files; rebalance the boundary rather than absorbing a tail into a sibling in a way that pushes that sibling above 15. The 3–15 range is a hard invariant — there is no exception above 15.
+
+## Single-Wave Default
+
+When no cross-app or cross-concern independence is found, the planner emits one wave covering all files. The 15-file cap applies to this single wave — if the total exceeds 15, apply the proximity-split algorithm even though the original decomposition was a single wave.
+
+## Cross-References
+
+- `agents/cbp-task-planner.md` Phase 5.6 — consumer of this rule; steps 1–6 and verification checklist.
+- `agents/cbp-round-executor.md` Step 2.6 — wave-mode skill preloads.
+- `skills/cbp-round-execute/SKILL.md` Step 3 — per-wave executor dispatch.

package/templates/settings.project.base.json

@@ -58,6 +58,8 @@
       "mcp__codebyplan__create_launch",
       "mcp__codebyplan__update_launch",
       "mcp__codebyplan__delete_launch",
+      "mcp__codebyplan__create_organization",
+      "mcp__codebyplan__create_project",
       "mcp__codebyplan__create_repo",
       "mcp__codebyplan__delete_session_log",
       "mcp__codebyplan__delete_worktree",
@@ -67,6 +69,12 @@
       "mcp__codebyplan__release_assignment",
       "Bash(codebyplan setup:*)",
       "Bash(npx codebyplan setup:*)",
+      "Bash(codebyplan create-org:*)",
+      "Bash(npx codebyplan create-org:*)",
+      "Bash(codebyplan create-project:*)",
+      "Bash(npx codebyplan create-project:*)",
+      "Bash(codebyplan create-repo:*)",
+      "Bash(npx codebyplan create-repo:*)",
       "Bash(codebyplan login:*)",
       "Bash(npx codebyplan login:*)",
       "Bash(codebyplan logout:*)",

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

@@ -61,6 +61,23 @@ Given the parse from Step 1:
 
 If no task found: `No active task. Nothing to update.`
 
+### Step 1.6: Permission Gate
+
+Step 1 (parse) and Step 1.5 (resolve task + round) are read-only. Step 2 onward mutates state — the `sync-approvals` CLI write, `complete_round`, and the auto-trigger of the next step. Before any of that, confirm the user wants this skill to run.
+
+This gate fires on **every** invocation — manual, auto-triggered by `/cbp-round-end`, and on every iteration of the Step 4 auto-loop. There is no bypass. It sits **before** and is independent of the top-of-file HARD GATE (which governs Step 2's exit code, not user consent), and it is distinct from the Branch A clean-exit route choice in Step 5 (that one picks where to go next; this one authorizes running at all).
+
+Ask via AskUserQuestion, naming the resolved round and disclosing the actions:
+
+> Update ROUND-{N} of TASK-{M}?
+> This will sync the git diff + file approvals, complete the round, and route to the next step (which may auto-start a new round).
+>
+> - **Proceed** — run the skill
+> - **Cancel** — do nothing
+
+- **Proceed** → continue to Step 2.
+- **Cancel** → abort cleanly: make NO writes (no `sync-approvals`, no `complete_round`, no auto-trigger) and exit with one line: `Cancelled by user — ROUND-{N} not updated.`
+
 ### Step 2: Sync git diff + approvals via CLI
 
 Run:
@@ -103,6 +120,8 @@ Procedure:
 2. **If `next_index > (round.context.auto_loop_cap ?? 5)`**: surface the cap-exhausted prompt via AskUserQuestion (options: extend cap, stop loop / drop into round-input, close task as-is). Persist `round.context.auto_loop_cap_exhausted = { user_choice, decided_at }` and route per choice.
 3. **Otherwise**: persist `round.context.auto_loop_decision = { spawned_next: true, next_index, decided_at }` on the CURRENT round via `update_round` (audit trail), then auto-trigger `/cbp-round-input` with NO AskUserQuestion. Pass `auto_loop_mode: true`, `auto_loop_index: next_index`, `auto_loop_cap: (prior cap ?? 5)` forward — round-start Step 4 persists them on the new round.
 
+> **Permission-gate note**: the "NO AskUserQuestion" in item 3 governs only the auto-loop's decision to spawn `/cbp-round-input` — it does not add a prompt for that hand-off. It is NOT a bypass of the Step 1.6 permission gate: when the spawned round eventually re-enters `/cbp-round-update`, Step 1.6 prompts again (the gate always fires, including inside the auto-loop).
+
 If BOTH signals are clean, fall through to Step 5 (exit routing).
 
 ### Step 5: Exit Routing
@@ -163,6 +182,7 @@ Unreachable in the auto-loop path — Step 4 catches it first. Retained for MANU
 
 ## Key Rules
 
+- **Step 1.6 permission gate fires first** — every invocation (incl. auto-trigger and the Step 4 auto-loop) asks the user to confirm before any write; **Cancel** is a clean abort (no `sync-approvals`, no `complete_round`, no auto-trigger).
 - **Step 2 (CLI) must exit 0** — if it fails, STOP. The merge semantics are enforced by the CLI.
 - **Step 4 owns the dirty-loop case**; Step 5 owns the clean-exit case. Step 5 Branch C is for manual invocation only.
 - **NEVER ask user to git add files** — only reads staging status. **NEVER stage files** — Claude does not touch git staging area.
@@ -170,6 +190,7 @@ Unreachable in the auto-loop path — Step 4 catches it first. Retained for MANU
 
 ## Integration
 
+- **Gates**: Step 1.6 permission gate — asks the user to confirm before any side effect; **Cancel** aborts cleanly with no writes. Fires on every invocation incl. the Step 4 auto-loop; sits before and independent of the top-of-file Step 2 hard gate.
 - **Triggered by**: `/cbp-round-end` (auto), or user manually
 - **Reads**: MCP `get_current_task`, `get_rounds`; delegates git+approval sync to `npx codebyplan round sync-approvals`
 - **Writes**: MCP `update_round` (auto_loop_decision / auto_loop_exit / auto_loop_cap_exhausted), `complete_round`; round+task files_changed written by CLI

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

@@ -65,6 +65,23 @@ task-start: no task found for `{ARG}`.
   - For `45`: no standalone TASK-45 exists. If a checkpoint-bound TASK-45 exists, invoke as `{chk}-45`.
 ```
 
+### Step 2.5: Permission Gate
+
+Steps 1–2 are read-only (argument parse + DB resolve). Everything from Step 3 onward mutates state — branch switch/create, the clean-slate commit, the task status write, and the round-1 auto-start. Before any of that, confirm the user wants this skill to run.
+
+This gate fires on **every** invocation — manual, auto-triggered from the pipeline, and inside any auto-loop. There is no bypass.
+
+Ask via AskUserQuestion, naming the resolved task and disclosing the actions:
+
+> Start TASK-{N} — {checkpoint or standalone title}?
+> This will switch/create its feat branch, commit a clean slate if the working tree is dirty, set the task `in_progress`, and auto-start round 1.
+>
+> - **Proceed** — run the skill
+> - **Cancel** — do nothing
+
+- **Proceed** → continue to Step 3.
+- **Cancel** → abort cleanly: make NO writes (no branch switch, no commit, no `update_task`, no `/cbp-round-start` trigger) and exit with one line: `Cancelled by user — TASK-{N} not started.`
+
 ### Step 3: Branch Auto-Handling
 
 The task MUST run on its target feat branch. Claude switches/creates that branch automatically — never asks the user to do it.
@@ -226,7 +243,7 @@ If worktree_id present, include `claim_worktree_id` to auto-claim the checkpoint
 
 ### Step 6: Auto-trigger Round Start
 
-Automatically trigger `/cbp-round-start` for the first round. Do NOT wait for user input.
+The Step 2.5 permission gate already covered this hand-off (the user approved running the skill, round-1 auto-start included), so no further prompt is needed here — automatically trigger `/cbp-round-start` for the first round.
 
 ```
 Starting first round...
@@ -236,6 +253,7 @@ Trigger `/cbp-round-start` (which will use task.requirements for round 1).
 
 ## Integration
 
+- **Gates**: Step 2.5 permission gate — asks the user to confirm before any side effect; **Cancel** aborts cleanly with no writes. Fires on every invocation (manual, auto-trigger, auto-loop).
 - **Reads**: MCP `get_current_task`, `get_tasks`, `get_rounds`
 - **Writes**: MCP `update_task`
 - **Triggers**: `/cbp-round-start` (auto, round 1)