codebyplan 1.11.2 → 1.13.0

package/templates/skills/cbp-setup-eslint/reference/react-native.md

@@ -0,0 +1,60 @@
+# react-native — React Native / Expo flat config
+
+For Expo / React Native apps (the CBP `livebyplan` mobile app). **Gap stack — no CBP DB
+preset.** Use Expo's official lint config.
+
+> **Verified 2026-05-31.** `eslint-config-expo` is the official config and ships **flat config
+> by default from Expo SDK 53** onward (SDK 52 and earlier use legacy `.eslintrc`).
+
+## Packages
+
+| Package | Latest | Purpose |
+| ------- | ------ | ------- |
+| `eslint-config-expo` | `56.0.4` | Expo's flat config (`/flat` subpath) |
+
+```bash
+npx expo lint   # installs eslint + eslint-config-expo and scaffolds eslint.config.js
+```
+
+`eslint-config-expo` bundles `eslint-plugin-expo`, `eslint-plugin-react`,
+`eslint-plugin-react-hooks`, `eslint-plugin-import`, and `@typescript-eslint/*`. It does **not**
+bundle `eslint-plugin-react-native` (that's a separate optional add-on, `@5.0.0`).
+
+## Flat config
+
+Expo's template is **CommonJS `eslint.config.js`** (not `.mjs`):
+
+```js
+// eslint.config.js
+const { defineConfig } = require("eslint/config");
+const expoConfig = require("eslint-config-expo/flat");
+const eslintPluginPrettierRecommended = require("eslint-plugin-prettier/recommended");
+
+module.exports = defineConfig([
+  expoConfig,
+  eslintPluginPrettierRecommended,
+  { ignores: ["dist/*"] },
+]);
+```
+
+Minimal form (no Prettier): just `expoConfig` in the array.
+
+## Gotchas
+
+- RN platform support comes from RN global variables + platform file extensions
+  (`.android.ts`, `.ios.ts`, `.web.ts`) and `eslint-plugin-expo` — **not** from
+  `eslint-plugin-react-native`. Add `eslint-plugin-react-native@5.0.0` manually only if you
+  want RN-specific rules (`no-inline-styles`, `no-unused-styles`).
+- Run linting with `npx expo lint` (it wires the config the first time).
+- Expo apps test with **Jest** — add the [jest.md](jest.md) override.
+
+## CBP preset divergence
+
+There is **no** CBP `react-native`/`expo` DB preset, and the `react` preset `excludes`
+nothing for RN but is browser-globals oriented. Use `eslint-config-expo/flat` directly; the
+skill does not add a preset for this stack.
+
+## Official docs
+
+- Using ESLint in Expo: https://docs.expo.dev/guides/using-eslint/
+- eslint-config-expo: https://github.com/expo/expo/tree/main/packages/eslint-config-expo

package/templates/skills/cbp-setup-eslint/reference/react.md

@@ -0,0 +1,82 @@
+# react — standalone React (Vite, Tauri) flat config
+
+For React apps that are **not** Next.js (Vite SPA, Tauri desktop webview). Layers on
+[base](base.md). Maps to the CBP **`react`** DB preset
+(`tech_match.requires: ["React"]`, `excludes: ["Next.js"]`, `requires_capabilities: ["jsx"]`).
+
+> **Verified 2026-05-31.** **Do NOT install `eslint-plugin-react-compiler`** — it is
+> superseded. React Compiler v1.0 (Oct 2025) merged the compiler lint rules into
+> **`eslint-plugin-react-hooks@7`** under `configs.flat["recommended-latest"]`.
+
+## Packages
+
+| Package | Latest | Purpose |
+| ------- | ------ | ------- |
+| `eslint-plugin-react` | `7.37.5` | React rules + JSX parsing (`configs.flat.*`) |
+| `eslint-plugin-react-hooks` | `7.1.1` | hooks rules **+ bundled React Compiler rules** |
+| `eslint-plugin-jsx-a11y` | `6.10.2` | accessibility (`flatConfigs.*` — note plural) |
+
+```bash
+pnpm add -D eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-jsx-a11y globals
+```
+
+## Flat config
+
+```js
+// eslint.config.mjs
+import { defineConfig } from "eslint/config";
+import react from "eslint-plugin-react";
+import reactHooks from "eslint-plugin-react-hooks";
+import jsxA11y from "eslint-plugin-jsx-a11y";
+import globals from "globals";
+
+export default defineConfig([
+  react.configs.flat.recommended,                 // namespaced react/, enables JSX parsing
+  react.configs.flat["jsx-runtime"],              // React 17+ automatic JSX transform
+  reactHooks.configs.flat["recommended-latest"],  // hooks + React Compiler rules
+  jsxA11y.flatConfigs.strict,                      // or flatConfigs.recommended
+  {
+    files: ["**/*.{js,jsx,ts,tsx}"],
+    languageOptions: { globals: globals.browser },
+    settings: { react: { version: "detect" } },
+  },
+]);
+```
+
+## Gotchas
+
+- **`eslint-plugin-react` flat configs do not set `files` or globals** — add your own
+  `files`/`globals.browser`/`settings.react.version` object (shown above) or you'll get the
+  "React version not specified" warning and no JSX globals.
+- **`eslint-plugin-react-hooks` v7 keys** live under `configs.flat.*`:
+  `recommended` (standard hooks) vs `recommended-latest` (hooks **+ compiler** rules — use
+  this for React 19 + the compiler).
+- **`jsx-a11y` uses `flatConfigs` (plural)** — `jsxA11y.flatConfigs.strict`, a different
+  namespace from react's `configs.flat`.
+
+## Storybook (bonus)
+
+If the app uses Storybook, add `eslint-plugin-storybook@10.4.1`:
+
+```js
+import storybook from "eslint-plugin-storybook";
+// ...spread into the array:
+...storybook.configs["flat/recommended"],
+```
+
+The standalone plugin repo was archived (2025-11); it now lives in the Storybook monorepo but
+the npm name `eslint-plugin-storybook` is unchanged.
+
+## CBP preset divergence
+
+CBP's `react` preset still depends on `eslint-plugin-react-compiler: ^19.0.0` and registers
+`react-compiler/react-compiler`. The latest guidance removes that plugin and relies on
+`eslint-plugin-react-hooks@7`'s `recommended-latest`. Adopt that when regenerating; the skill
+does not modify the preset.
+
+## Official docs
+
+- eslint-plugin-react: https://github.com/jsx-eslint/eslint-plugin-react
+- react-hooks: https://react.dev/reference/eslint-plugin-react-hooks
+- React Compiler v1.0: https://react.dev/blog/2025/10/07/react-compiler-1
+- jsx-a11y: https://github.com/jsx-eslint/eslint-plugin-jsx-a11y

package/templates/skills/cbp-setup-eslint/reference/tailwind.md

@@ -0,0 +1,64 @@
+# tailwind — Tailwind CSS class linting
+
+For apps using Tailwind CSS (the CBP `tarkur` repo uses Tailwind + shadcn/ui). **Gap stack —
+no CBP DB preset.** Adds class-sorting / validation rules on top of the app's base config.
+
+> **Verified 2026-05-31.** Use **`eslint-plugin-better-tailwindcss`** — it is the only plugin
+> with first-class **Tailwind v4** + ESLint 9/10 flat-config support. The original
+> `eslint-plugin-tailwindcss` only handles v4 on an unstable alpha — **avoid it for v4.**
+
+## Packages
+
+| Package | Latest | Tailwind v4? | Verdict |
+| ------- | ------ | ------------ | ------- |
+| `eslint-plugin-better-tailwindcss` | `4.5.0` | **yes (stable)** | **use this** |
+| `eslint-plugin-tailwindcss` | `3.18.3` (v4 only on `4.0.0-alpha`) | beta/as-is | avoid for v4 |
+
+```bash
+pnpm add -D eslint-plugin-better-tailwindcss
+```
+
+Peer deps: `eslint ^7 || ^8 || ^9 || ^10`, `tailwindcss ^3.3.0 || ^4.1.17`. Node ≥ 20.19.
+
+## Flat config
+
+```js
+// eslint.config.mjs
+import { defineConfig } from "eslint/config";
+import betterTailwind from "eslint-plugin-better-tailwindcss";
+
+export default defineConfig([
+  {
+    extends: [betterTailwind.configs["recommended"]],
+    settings: {
+      "better-tailwindcss": {
+        // Tailwind v4: path to the CSS file with `@import "tailwindcss"`
+        entryPoint: "src/app/globals.css",
+        // Tailwind v3 ONLY (omit for v4):
+        // tailwindConfig: "tailwind.config.js",
+      },
+    },
+  },
+]);
+```
+
+## Gotchas
+
+- **`settings.entryPoint` is REQUIRED for Tailwind v4** — it points at the global CSS file
+  containing `@import "tailwindcss"` (v4 has no JS config file). For v3, use `tailwindConfig`
+  instead.
+- **Monorepo**: set `settings["better-tailwindcss"].cwd` per file-group so the plugin resolves
+  `tailwindcss` + the config from the correct project dir when ESLint runs from the repo root.
+- Config presets: `recommended`, `correctness` (errors), `stylistic` (warnings); severity
+  suffixes `-error` / `-warn`.
+- Non-JSX file types (Svelte/Vue/Astro/HTML) need the matching `languageOptions.parser`.
+
+## CBP preset divergence
+
+There is **no** CBP `tailwind` DB preset — Tailwind linting is entirely manual. `tarkur`
+currently has no Tailwind ESLint rules; add the block above to lint class order/validity.
+
+## Official docs
+
+- eslint-plugin-better-tailwindcss: https://github.com/schoero/eslint-plugin-better-tailwindcss
+- Settings: https://github.com/schoero/eslint-plugin-better-tailwindcss/blob/main/docs/settings/settings.md

package/templates/skills/cbp-setup-eslint/reference/testing-react.md

@@ -0,0 +1,57 @@
+# testing-react — Testing Library + jest-dom rules
+
+For React component tests (Testing Library assertions). Layers a **test-scoped** override on
+top of [base](base.md) + the test-runner doc ([vitest](vitest.md) or [jest](jest.md)). Maps to
+the CBP **`testing-react`** DB preset
+(`tech_match.requires: ["React", "Vitest"]`, `requires_capabilities: ["jsx"]`).
+
+> **Verified 2026-05-31.** Both plugins use bracketed `configs['flat/...']` keys and each
+> spreads its own plugin registration — keep them as **separate array entries**.
+
+## Packages
+
+| Package | Latest | Purpose |
+| ------- | ------ | ------- |
+| `eslint-plugin-testing-library` | `7.16.2` | Testing Library best-practices |
+| `eslint-plugin-jest-dom` | `5.5.0` | `@testing-library/jest-dom` matchers |
+
+```bash
+pnpm add -D eslint-plugin-testing-library eslint-plugin-jest-dom
+```
+
+## Flat config
+
+```js
+// eslint.config.mjs
+import testingLibrary from "eslint-plugin-testing-library";
+import jestDom from "eslint-plugin-jest-dom";
+
+const TEST_GLOBS = ["**/*.{test,spec}.{ts,tsx,js,jsx}", "**/__tests__/**/*.{ts,tsx,js,jsx}"];
+
+export default [
+  { files: TEST_GLOBS, ...testingLibrary.configs["flat/react"] }, // 'flat/dom' for non-React
+  { files: TEST_GLOBS, ...jestDom.configs["flat/recommended"] },
+];
+```
+
+## Gotchas
+
+- Keep the two as **separate array entries** — each `...config` spread re-declares its own
+  `plugins`. Merging them into one object means you must hand-combine `plugins` + `rules`.
+- `eslint-plugin-testing-library` framework presets: `flat/react`, `flat/dom` (agnostic),
+  `flat/vue`, `flat/angular`, `flat/svelte`, `flat/marko` — pick **one**.
+- Scope to the **same test globs** as your runner override so the rules don't bleed onto
+  production code.
+- Don't let Playwright e2e specs hit `testing-library/*` rules (e.g.
+  `prefer-screen-queries` mis-fires on Playwright's `page.getByRole`) — scope to `src/**`
+  unit tests, not the e2e dir (see [e2e.md](e2e.md)).
+
+## CBP preset divergence
+
+The CBP `testing-react` preset matches this (`eslint-plugin-testing-library: ^7.0.0`,
+`eslint-plugin-jest-dom: ^5.0.0`, `flat/react` + `flat/recommended`). No divergence.
+
+## Official docs
+
+- testing-library: https://github.com/testing-library/eslint-plugin-testing-library
+- jest-dom: https://github.com/testing-library/eslint-plugin-jest-dom

package/templates/skills/cbp-setup-eslint/reference/vitest.md

@@ -0,0 +1,62 @@
+# vitest — Vitest test-file rules
+
+For apps that test with Vitest (CBP web + CLI + most repos). Layers a **test-scoped** override
+on top of [base](base.md). Maps to the CBP **`testing`** DB preset
+(`tech_match.requires: ["Vitest"]`).
+
+> **Verified 2026-05-31.** The package was **renamed** to the scoped
+> **`@vitest/eslint-plugin`** (the old `eslint-plugin-vitest` is the deprecated name). Its
+> flat-config key is plain **`configs.recommended`** — there is **no `flat/` prefix**.
+
+## Packages
+
+| Package | Latest | Purpose |
+| ------- | ------ | ------- |
+| `@vitest/eslint-plugin` | `1.6.18` | Vitest rules (scoped pkg) |
+
+```bash
+pnpm add -D @vitest/eslint-plugin
+```
+
+## Flat config
+
+```js
+// eslint.config.mjs
+import vitest from "@vitest/eslint-plugin";
+
+export default [
+  {
+    files: ["**/*.{test,spec}.{ts,tsx,js,jsx}"],
+    plugins: { vitest },
+    rules: {
+      ...vitest.configs.recommended.rules,
+      // tests are I/O-heavy + mock-heavy — relax type-safety on test files:
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-unsafe-assignment": "off",
+      "@typescript-eslint/no-unsafe-member-access": "off",
+      "@typescript-eslint/no-unsafe-call": "off",
+      "@typescript-eslint/no-unsafe-argument": "off",
+      "@typescript-eslint/no-unsafe-return": "off",
+    },
+    settings: { vitest: { typecheck: true } }, // only if using Vitest type-testing
+  },
+];
+```
+
+## Gotchas
+
+- The key is **`vitest.configs.recommended`** (plain) — NOT `configs['flat/recommended']`.
+  Other plugins use the bracketed `flat/` form; Vitest does not.
+- When you spread only `.rules`, register `plugins: { vitest }` yourself. Alternatively spread
+  the whole `...vitest.configs.recommended` (carries the plugin registration).
+- The `no-unsafe-*` / `no-explicit-any` opt-outs are CBP convention — production code keeps
+  them at `error`; test surfaces relax them because mocks produce `any`-typed values.
+
+## CBP preset divergence
+
+The CBP `testing` preset matches this (the six `no-unsafe-*`/`no-explicit-any` opt-outs,
+`@vitest/eslint-plugin: ^1.0.0`). No divergence.
+
+## Official docs
+
+- @vitest/eslint-plugin: https://github.com/vitest-dev/eslint-plugin-vitest

package/templates/skills/cbp-ship-main/SKILL.md

@@ -52,6 +52,19 @@ Pass `--dry-run` through if the skill was invoked with a dry-run arg.
 
 Parse JSON from Step 3. Report `pr_url`, `merge_commit`, `branch_deleted`. If `checks_failed: true`, surface `checks_failure_reason` and stop.
 
+If `branch_deleted === true`, run a conditional Supabase preview-branch teardown for the feat branch that was just merged:
+
+> Lifecycle contract: see [[supabase-branch-lifecycle]].
+
+- Read `FEAT_BRANCH` from the `feat_branch` field in the Step 3 JSON output — NOT from `git branch --show-current`. By the time Step 4 runs, `codebyplan ship` has already checked out the base branch (unless `--keep-feat` was passed), so the live branch is the base, not the feat branch.
+- Call `mcp__supabase__list_branches` with `project_id: rrvtrumtkhrsbhcyrwvf`.
+- Scan the returned list for an entry whose `name` exactly equals `$FEAT_BRANCH`.
+- If found: call `mcp__supabase__delete_branch` with its `branch_id`. Report the Supabase delete outcome alongside `pr_url` / `merge_commit` / `branch_deleted`.
+- If not found: no-op silently — the GitHub integration may have already removed the preview branch 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 `$FEAT_BRANCH` 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 `rrvtrumtkhrsbhcyrwvf` itself or any persistent/production branch.
+- This coordinates safely with `/cbp-checkpoint-end` — the existence-checked delete makes any second attempt a harmless no-op.
+
 ## Key Rules
 
 - **Read branch names from config** — never hardcode "main"

package/templates/skills/cbp-supabase-branch-check/SKILL.md

@@ -62,10 +62,10 @@ Infer `TARGET` when absent:
 
 ## Step 1 — Read DB Paths Config
 
-Read `.codebyplan.json` to obtain the configured DB path globs:
+Read `.codebyplan/shipment.json` to obtain the configured DB path globs:
 
 ```bash
-DB_PATHS=$(jq -r '.shipment.surfaces.supabase.db_paths[]? // empty' .codebyplan.json 2>/dev/null)
+DB_PATHS=$(jq -r '.shipment.surfaces.supabase.db_paths[]? // empty' .codebyplan/shipment.json 2>/dev/null)
 ```
 
 If `DB_PATHS` is empty, fall back to defaults:
@@ -80,11 +80,11 @@ Store each pattern as a separate entry for matching in Step 2.
 
 ## Step 2 — Detect DB-Path Changes
 
-Resolve the BASE branch from `TARGET`. Read `.codebyplan.json`:
+Resolve the BASE branch from `TARGET`. Read `.codebyplan/git.json`:
 
 ```bash
-INTEGRATION=$(jq -r '.branch_config.integration // "development"' .codebyplan.json)
-PRODUCTION=$(jq -r '.branch_config.production // "main"' .codebyplan.json)
+INTEGRATION=$(jq -r '.branch_config.integration // "development"' .codebyplan/git.json)
+PRODUCTION=$(jq -r '.branch_config.production // "main"' .codebyplan/git.json)
 ```
 
 Set `BASE`:
@@ -156,6 +156,13 @@ Store as `PROJECT_REF`.
 
 ## Step 4 — Handle Missing project_ref
 
+> **Note — Hybrid branch creation**: The preview branch may pre-exist as a CBP-created
+> branch (named identically to the git branch, provisioned lazily by `cbp-supabase-migrate`
+> on first DB change) rather than being auto-created by the GitHub integration on PR open.
+> The by-name resolution in Step 3 works identically for both creation paths because both
+> name the branch verbatim after the git branch. See [[supabase-branch-lifecycle]] for the
+> full lifecycle contract.
+
 If `PROJECT_REF` is empty after Step 3:
 
 - `MODE=pre_pr_create`:

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: