codebyplan 1.11.2 → 1.12.0

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

@@ -3,7 +3,7 @@ scope: org-shared
 name: cbp-supabase-migrate
 description: Scaffold or adopt a Supabase migration for the current PR branch, apply to the branch's preview DB, run advisor checks, regenerate TypeScript types. Includes a fresh-branch dry-run pre-flight that uses one persistent dry-run ephemeral branch per feature branch.
 argument-hint: "[--new <name> | <path-to-sql>]"
-allowed-tools: Read, Edit, Write, Bash(git *), Bash(supabase *), Bash(jq *), Bash(date *), Bash(which *), Bash(cp *), Bash(mv *), Bash(test *), Bash(ls *), mcp__supabase__apply_migration, mcp__supabase__list_migrations, mcp__supabase__get_advisors, mcp__supabase__generate_typescript_types, mcp__supabase__reset_branch, mcp__supabase__list_branches
+allowed-tools: Read, Edit, Write, Bash(git *), Bash(supabase *), Bash(jq *), Bash(date *), Bash(which *), Bash(cp *), Bash(mv *), Bash(test *), Bash(ls *), mcp__supabase__apply_migration, mcp__supabase__list_migrations, mcp__supabase__get_advisors, mcp__supabase__generate_typescript_types, mcp__supabase__reset_branch, mcp__supabase__list_branches, mcp__supabase__create_branch, mcp__supabase__get_cost, mcp__supabase__confirm_cost, mcp__codebyplan__update_checkpoint, mcp__codebyplan__update_task
 model: sonnet
 effort: xhigh
 ---
@@ -61,11 +61,139 @@ Parse the output for:
 - `POSTGRES_URL_NON_POOLING` — direct connection string for the preview DB
 - `project_ref` — the Supabase project ref for this branch's environment
 
-Capture both values. The `project_ref` is used in Steps 3, 4, 6, 7, and 8. (Step 5.5 resolves its own separate dry-run branch `project_ref` — see [reference/preflight-dry-run.md](reference/preflight-dry-run.md).)
+Capture both values. The `project_ref` is used from Step 3 onward; Step 2.3 may replace it with a `PREVIEW_PROJECT_REF` when it lazily provisions the branch. (Step 5.5 resolves its own separate dry-run branch `project_ref` — see [reference/preflight-dry-run.md](reference/preflight-dry-run.md).)
+
+## Step 2.3 — Ensure Supabase Branch Exists
+
+Couples the Supabase preview branch lifecycle to the git branch: when this skill runs on a
+feat branch that touches the database, a Supabase branch named **exactly** the current git
+branch is guaranteed to exist before any migration is applied. Naming it identically to the
+git branch is the linchpin that lets the GitHub branching integration reconcile to the same
+branch (no duplicate).
+
+> Lifecycle contract: see [[supabase-branch-lifecycle]].
+
+This step runs **before** Step 2.5: it lazily provisions the branch so that an empty
+`project_ref` from Step 2 gets filled in. Step 2.5 then fires only when `project_ref` is
+**still** empty after this step (i.e. this step was skipped or creation was declined).
+
+### Guard 1 — feat-branch only
+
+Read branch config 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)
+INTEGRATION=$(jq -r '.branch_config.integration // empty' .codebyplan/git.json)
+```
+
+If `$BRANCH` equals `$PRODUCTION` or appears in `$PROTECTED`, skip this entire step — never
+provision a Supabase branch for the production/protected branch. On `$PRODUCTION` the
+`project_ref` from Step 2 is the parent project itself; Step 3's main-project guard handles
+that case. (A standalone task pinned to the production branch is covered by this same check,
+since its `$BRANCH` equals `$PRODUCTION`.)
+
+If `$INTEGRATION` is non-empty and `$BRANCH` equals `$INTEGRATION`, skip this step — the
+integration branch uses a persistent Supabase branch provisioned by `cbp-supabase-setup`,
+not a lazy ephemeral one. Do NOT default or write `$INTEGRATION` to any value; only read and
+skip.
+
+### Guard 2 — DB-path / migration intent
+
+Reuse the db_paths detection so the step proceeds only when this invocation actually touches
+the database. Read the globs (default `supabase/**`, `apps/backend/**`, `packages/**/db/**`):
+
+```bash
+DB_PATHS=$(jq -r '.shipment.surfaces.supabase.db_paths[]? // empty' .codebyplan/shipment.json 2>/dev/null)
+[ -z "$DB_PATHS" ] && DB_PATHS=$(printf '%s\n' 'supabase/**' 'apps/backend/**' 'packages/**/db/**')
+```
+
+Proceed when **either**:
+- the branch diff against `origin/$PRODUCTION` touches any `DB_PATHS` glob, **or**
+- this invocation will create/adopt a migration — `$ARGUMENTS` is `--new <name>` or a `.sql`
+  path (the migration file may not exist on disk yet, so explicit migrate intent counts as a
+  DB change). The bare-picker case (Step 5 Case C) is treated as migrate intent.
+
+If neither holds (no DB-path changes and no migrate intent), skip this step silently and let
+Step 2.5 / the normal flow handle the empty `project_ref` — do not provision or prompt for
+cost on a branch that touches no database paths.
+
+### Already-provisioned reuse
+
+If `project_ref` from Step 2 is already non-empty, the GitHub integration (or a prior run)
+already provisioned the branch. Capture it as `PREVIEW_PROJECT_REF` and jump straight to
+"Record connection" below — idempotent, no creation.
+
+### Idempotency check (list before create)
+
+Call `mcp__supabase__list_branches` with the parent `project_id` `rrvtrumtkhrsbhcyrwvf`. The
+parent `project_id` for MCP calls is the same ref string stored in `.codebyplan/shipment.json`
+`surfaces.supabase.project_ref` — Supabase uses that one ref as both the project identifier
+and the branch target. Scan the returned list for an entry whose `name` exactly equals
+`$BRANCH` (slashes included — `feat/CHK-144-...` is a valid Supabase branch name).
+
+- **Match found**: capture its `project_ref` as `PREVIEW_PROJECT_REF`. Skip creation; proceed
+  to "Record connection". This is the idempotent reuse path (covers a branch the GitHub
+  integration auto-created between Step 2 and now).
+- **No match**: proceed to "Cost confirmation and creation".
+
+### Cost confirmation and creation
+
+Cost confirmation is mandatory before creating a branch — never bypass it:
+
+1. Call `mcp__supabase__get_cost` with `type: "branch"`. Display the returned estimate to the
+   user, capturing the returned `confirm_cost_id`.
+2. Call `mcp__supabase__confirm_cost` with that `confirm_cost_id`.
+3. On user cancellation or cost-confirm rejection: emit a warning and continue in
+   scaffold-only mode (jump to Step 5 write-only path; skip Steps 5.5 and 6). `project_ref`
+   stays empty.
+
+After cost is confirmed, call `mcp__supabase__create_branch`:
+- `project_id`: `rrvtrumtkhrsbhcyrwvf` (parent project ref)
+- `name`: `$BRANCH` (verbatim — slashes included)
+- `confirm_cost_id`: the same id from the `get_cost` response that was passed to `confirm_cost`
+
+After the create call returns, poll `mcp__supabase__list_branches` every 10 s until an entry
+with `name == $BRANCH` appears (up to 60 s / 6 polls). Capture its `project_ref` as
+`PREVIEW_PROJECT_REF`. If polling times out:
+
+```
+Supabase branch creation for <BRANCH> did not settle within 60 s.
+Check the Supabase dashboard: Branches — then re-run /cbp-supabase-migrate.
+```
+
+Stop.
+
+### Record connection
+
+Record the branch so cleanup (see `cbp-checkpoint-end`, `cbp-git-worktree-remove`) and other
+skills can discover it. Phrase any context payload as prose — the MCP edge rejects raw
+uppercase database keywords (Cloudflare WAF).
+
+1. **Checkpoint / task context** — call `mcp__codebyplan__update_checkpoint` (or
+   `mcp__codebyplan__update_task` for a standalone task) to add to `context.discoveries`:
+
+   ```json
+   { "topic": "supabase_preview_branch", "finding": "branch <BRANCH> -> project_ref <PREVIEW_PROJECT_REF>" }
+   ```
+
+2. **`.codebyplan/shipment.json`** — read-merge-write (the `preview_branches` array may not
+   exist yet — create it if absent; never clobber the rest of the file). Under
+   `surfaces.supabase.preview_branches`, first check for an existing entry whose `branch`
+   equals `$BRANCH`: if present, update its `project_ref` only if it differs (no duplicate
+   append); if absent, append:
+
+   ```json
+   { "branch": "<BRANCH>", "project_ref": "<PREVIEW_PROJECT_REF>", "created_at": "<ISO timestamp>" }
+   ```
+
+Set `project_ref = $PREVIEW_PROJECT_REF` so Steps 3 onward target this branch's project.
 
 ## Step 2.5 — Empty project_ref Handling
 
-If `project_ref` is empty after Step 2, AskUserQuestion:
+If `project_ref` is **still** empty after Step 2.3 (no branch was provisioned — e.g. no
+DB-path changes / no migrate intent, or this is a protected branch, or cost confirmation was
+declined), AskUserQuestion:
 
 ```
 Could not resolve a Supabase project_ref for branch: <BRANCH>
@@ -88,12 +216,14 @@ On (C): stop silently.
 
 ## Step 3 — Main-Project Guard
 
-If `project_ref` is empty (scaffold-only mode chosen in Step 2.5), skip Steps 3 and 4 entirely and jump directly to Step 5.
+If `project_ref` is empty, skip Steps 3 and 4 entirely and jump directly to Step 5. (Normally
+Step 2.3 has already populated `project_ref` for a feat branch, or scaffold-only mode was
+chosen in Step 2.5; this remains a defensive guard for the scaffold-only path.)
 
-Read `.codebyplan.json`:
+Read `.codebyplan/shipment.json`:
 
 ```bash
-MAIN_PROJECT_REF=$(jq -r '.shipment.surfaces.supabase.project_ref' .codebyplan.json)
+MAIN_PROJECT_REF=$(jq -r '.shipment.surfaces.supabase.project_ref' .codebyplan/shipment.json)
 ```
 
 `MAIN_PROJECT_REF` is consumed by Step 5.5's dry-run CLI calls (`branches create` and `branches get`) to pin those calls to the parent project rather than any linked preview branch.
@@ -274,16 +404,16 @@ severity level. Hard-block enforcement at ship time is owned by `cbp-supabase-br
 
 ## Step 8 — Regenerate TypeScript Types
 
-Read the types output path from `.codebyplan.json`:
+Read the types output path from `.codebyplan/shipment.json`:
 
 ```bash
-jq -r '.shipment.surfaces.supabase.types_path' .codebyplan.json
+jq -r '.shipment.surfaces.supabase.types_path' .codebyplan/shipment.json
 ```
 
 If the field is missing or empty, AskUserQuestion:
 
 ```
-types_path not found in .codebyplan.json under shipment.surfaces.supabase.types_path.
+types_path not found in .codebyplan/shipment.json under surfaces.supabase.types_path.
 Enter the path where TypeScript types should be written (e.g., apps/web/src/lib/database.types.ts):
 ```
 

package/templates/skills/cbp-supabase-migrate/reference/preflight-dry-run.md

@@ -12,7 +12,7 @@ The dry-run uses ONE persistent branch per feature branch — created on first u
 
     DRY_RUN_BRANCH="${BRANCH}-cbp-migrate-dryrun"
 
-The CLI `branches` sub-commands act on the project the CLI is *linked* to — mid-development that is often a preview branch, not the parent project. Pin every `branches` call to the parent with `--project-ref "$MAIN_PROJECT_REF"`, where `MAIN_PROJECT_REF` is the parent `project_ref` SKILL.md Step 3 already resolves from `.codebyplan.json` (`.shipment.surfaces.supabase.project_ref`). `mcp__supabase__list_branches` and `reset_branch` need no such flag — the MCP server is already bound to the parent project.
+The CLI `branches` sub-commands act on the project the CLI is *linked* to — mid-development that is often a preview branch, not the parent project. Pin every `branches` call to the parent with `--project-ref "$MAIN_PROJECT_REF"`, where `MAIN_PROJECT_REF` is the parent `project_ref` SKILL.md Step 3 already resolves from `.codebyplan/shipment.json` (`.shipment.surfaces.supabase.project_ref`). `mcp__supabase__list_branches` and `reset_branch` need no such flag — the MCP server is already bound to the parent project.
 
 1. Call `mcp__supabase__list_branches`. Look for an entry whose name equals `DRY_RUN_BRANCH`. If found, capture its `id` field as `DRY_RUN_BRANCH_ID` — `reset_branch` and every status poll below act on the branch id, not the name.
 2. **If absent** — run `supabase --experimental branches create "$DRY_RUN_BRANCH" --project-ref "$MAIN_PROJECT_REF" --yes`. The `--yes` flag is required: branch creation prompts for cost confirmation and the skill runs non-interactively, so the prompt would otherwise hang. The CLI create command is asynchronous and returns a human-readable message (not JSON with an `id`). After the CLI call, poll `mcp__supabase__list_branches` until an entry whose name equals `DRY_RUN_BRANCH` appears, then capture its `id` as `DRY_RUN_BRANCH_ID`. This poll both confirms the create succeeded and yields the id. Creation clones at `git_ref=main` and replays main's migration chain as a baseline — skip the reset in step 4 and go straight to step 5 (the initial provisioning already gave a main baseline).

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

@@ -1,7 +1,7 @@
 ---
 scope: org-shared
 name: cbp-supabase-setup
-description: Enable Supabase GitHub branching integration — GitHub app authorization, required-status-check enforcement on main + integration branch, persistent branch creation, and idempotency marker in .codebyplan.json.
+description: Enable Supabase GitHub branching integration — GitHub app authorization, required-status-check enforcement on main + integration branch, persistent branch creation, and idempotency marker in .codebyplan/shipment.json.
 argument-hint: "[--force]"
 allowed-tools: Read, Edit, Bash(supabase *), Bash(jq *), Bash(mv *), Bash(date *), Bash(test *), Bash(which *)
 effort: xhigh
@@ -41,13 +41,19 @@ first, then re-invoke /cbp-supabase-setup.
 Read `supabase/config.toml` to extract the linked `project_id` (under `[api]` or the top-level
 `project_id` field, depending on CLI version).
 
-Read `.codebyplan.json`:
+Read `.codebyplan/git.json` and `.codebyplan/shipment.json`:
 
 ```bash
-jq '.branch_config.integration // empty' .codebyplan.json
-jq '.shipment.surfaces.supabase.branching_configured // empty' .codebyplan.json
+jq '.branch_config.integration // empty' .codebyplan/git.json
+jq '.shipment.surfaces.supabase.branching_configured // empty' .codebyplan/shipment.json
 ```
 
+> **Note — Two distinct Supabase branching models**: This skill performs a ONE-TIME
+> persistent setup of the GitHub branching integration (the OAuth link, required-status-check
+> rules, and optional persistent integration branch). It is separate from the PER-FEATURE
+> explicit Supabase branches that `cbp-supabase-migrate` creates lazily on first DB change
+> for each feat branch. See [[supabase-branch-lifecycle]] for the per-feature lifecycle.
+
 Track per-item done state:
 - `github_app_installed` — true if `branching_configured.github_app_installed` is already true
 - `required_check_enforced` — true if `branching_configured.required_check_enforced` is already true
@@ -82,7 +88,7 @@ Set `github_app_installed = true` in the idempotency tracker (persisted at Step
 
 ## Step 4 — GitHub repo: required status check (manual checklist)
 
-Read `branch_config.integration` from `.codebyplan.json`. Determine branches to protect:
+Read `branch_config.integration` from `.codebyplan/git.json`. Determine branches to protect:
 
 - Always: `main`
 - Also: `branch_config.integration` (when set and !== 'main')
@@ -193,7 +199,7 @@ sql_paths = ["./seed.sql"]
 
 Reference: [reference/branching-setup.md § 4](reference/branching-setup.md)
 
-## Step 7 — Write idempotency marker to `.codebyplan.json`
+## Step 7 — Write idempotency marker to `.codebyplan/shipment.json`
 
 Generate the ISO timestamp in the shell first (jq can't produce wall-clock time natively),
 then merge the marker under `shipment.surfaces.supabase.branching_configured`:
@@ -204,7 +210,7 @@ jq --arg now "$NOW" '.shipment.surfaces.supabase.branching_configured = {
   enabled_at: $now,
   github_app_installed: true,
   required_check_enforced: true
-}' .codebyplan.json > .codebyplan.json.tmp && mv .codebyplan.json.tmp .codebyplan.json
+}' .codebyplan/shipment.json > .codebyplan/shipment.json.tmp && mv .codebyplan/shipment.json.tmp .codebyplan/shipment.json
 ```
 
 The three sub-fields:

package/templates/skills/cbp-supabase-setup/reference/branching-setup.md

@@ -26,7 +26,7 @@ Verify: the integration tile now shows the connected repository name.
 Protect both `main` AND the integration branch (e.g., `development`) so PRs cannot be merged
 until the Supabase Preview environment passes.
 
-For each branch (`main`, then the integration branch from `.codebyplan.json`
+For each branch (`main`, then the integration branch from `.codebyplan/git.json`
 `branch_config.integration`):
 
 1. **GitHub → Repository → Settings → Branches → Add branch protection rule**.
@@ -94,7 +94,7 @@ migration push.
 
 ## 5. Idempotency Marker
 
-After setup completes, `/cbp-supabase-setup` writes to `.codebyplan.json`:
+After setup completes, `/cbp-supabase-setup` writes to `.codebyplan/shipment.json`:
 
 ```json
 {

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

@@ -115,6 +115,8 @@ fi
 
 **If `git checkout` exits non-zero** (typically "would clobber" because a tracked file has unstaged changes that conflict with target's version): surface the raw git error verbatim, stop, do NOT attempt recovery. The user resolves and re-invokes. This is the only case where `/cbp-task-start` halts on branch state.
 
+**Note — Supabase preview branch**: no Supabase branch is created at this point. Creation is lazy — it happens on the first DB change when `/cbp-supabase-migrate` runs on the feat branch, which provisions a Supabase branch named identically to the git branch. See `cbp-supabase-migrate` Step 2.3 for the creation protocol.
+
 #### 3.4 — Persist + verify
 
 After successful switch: