codebyplan 1.11.1 → 1.12.0

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

@@ -56,7 +56,7 @@ Execute the survey instructions inline using Read/Grep/Bash. Save to `round.cont
 For each entry, route per `rules/file-routing.md`:
 
 - `.claude/skills/{name}/SKILL.md` → `cbp-build-cc-skill` via Skill tool
-- `.claude/agents/{name}/AGENT.md` → `cbp-build-cc-agent` via Skill tool
+- `.claude/agents/{name}.md` (or `{name}/AGENT.md` folder form) → `cbp-build-cc-agent` via Skill tool
 - `.claude/rules/{name}.md` → `cbp-build-cc-rule` via Skill tool
 - `.claude/CLAUDE.md` → `cbp-build-cc-claude-file` via Skill tool (or direct Edit)
 - `.claude/settings*.json` → `cbp-build-cc-settings` via Skill tool
@@ -145,28 +145,40 @@ Read `task.context.testing_profile` (already loaded in Step 2).
 
 On pass, synthesise `testing_qa_output` inline per the procedure in `reference/inline-fallback.md` "Validation fallback" section (output shape defined in `agents/cbp-testing-qa-agent.md` Output Contract) and persist to `round.context.testing_qa_output` at Step 7.
 
-**All other profiles**: spawn `cbp-testing-qa-agent` AND `cbp-test-e2e-agent` in parallel (two Agent calls in the same message) per completed wave (or full executor output in single-wave mode). `cbp-test-e2e-agent` is gated on `has_ui_work === true` AND profile in {`web`, `desktop`, `full_matrix`, `cross_app`} — skipped for `claude_only` / `backend`-only.
+**All other profiles**: spawn `cbp-testing-qa-agent` against the wave's `files[]` (or full executor output in single-wave mode), and dispatch e2e specialists **config-driven** in parallel — all Agent calls in the same message:
 
-Input contracts: `cbp-testing-qa-agent` receives `executor_output`, `testing_profile`, `has_ui_work` (see `agents/cbp-testing-qa-agent.md` Input Contract). `cbp-test-e2e-agent` receives `repo_id`, `round_number`, `files_changed`, `prior_round_files_changed` (full task aggregate when round_number ≥ 2), `whole_checkpoint_mode: false`, `test_strategy`, `pages_affected`, `has_auth`, `dev_server_port` (see `agents/cbp-test-e2e-agent.md` Input Contract for the full shape).
+1. **Short-circuit hints** (applied *before* reading `e2e.json`, emit no `e2e_eligible_skipped` signal): if `testing_profile === 'backend'` OR `round.context.round_type === 'survey'`, dispatch `cbp-testing-qa-agent` alone and skip e2e entirely. (The `claude_only` branch above already skips all agent spawns.)
+2. Read `.codebyplan/e2e.json`. If the file is absent or `frameworks` is missing/empty, no framework is eligible — skip e2e entirely (no `e2e_eligible_skipped` signal) and run `cbp-testing-qa-agent` alone.
+3. For each entry in `frameworks` where `enabled === true` AND `auto_run === true`: if `platforms[]` does not include the current CI target (e.g. an iOS-only config on a Linux runner with no simulator), skip the framework — a recorded valid platform skip per `rules/e2e-mandatory.md`, NOT added to `e2e_eligible[]`. Otherwise mark it **eligible** when its `app` source path intersects this wave's `files_changed` (repo root for single-app repos). Record the eligible framework names as `round.context.e2e_eligible[]`.
+4. For every eligible framework, spawn the matching `cbp-e2e-*` specialist (per the `context/testing/e2e.md` dispatch routing table) IN PARALLEL with `cbp-testing-qa-agent` and with each other. Inject `framework`, `app`, `platforms`, and `credential_vars` from `e2e.json` — the config is authoritative; agents do not auto-detect.
+5. `has_ui_work` and `testing_profile` are **hints only** beyond the short-circuit above — they never suppress an eligible framework. Pure `.claude/`-only and docs-only rounds match no configured `app` path and are therefore not eligible.
 
-**Independence**: neither agent reads the other's output. Baseline-regression findings surface as a BLOCKING gate at `/cbp-round-end` Step 7 (an explicit accept-or-fix user decision; baselines are NEVER auto-accepted). Per-wave spawns MAY run in parallel with the next wave's executor when dependency order allows.
+This realises the opt-out contract in `rules/e2e-mandatory.md`: an eligible framework whose specialist does not run — without a recorded valid skip reason — is an `e2e_eligible_skipped` hard-fail at Step 6.
+
+Input contracts: `cbp-testing-qa-agent` receives `executor_output`, `testing_profile`, `has_ui_work` (see `agents/cbp-testing-qa-agent.md` Input Contract). The `cbp-e2e-*` specialist receives `repo_id`, `round_number`, `files_changed`, `prior_round_files_changed` (full task aggregate when round_number ≥ 2), `whole_checkpoint_mode: false`, `framework`, `app`, `platforms`, `credential_vars`, `test_strategy`, `pages_affected`, `has_auth`, `dev_server_port` (see `context/testing/e2e.md` Input Contract for the full shape). `test_strategy` is injected here in per-round mode; `/cbp-checkpoint-check` Step 5b omits it (the specialist self-resolves from `e2e.json` + DB in `whole_checkpoint_mode`).
+
+**Independence**: neither agent reads the other's output. Baseline-regression findings surface as a BLOCKING gate at `/cbp-round-end` Step 7 (an explicit accept-or-fix user decision; baselines are NEVER auto-accepted). Per-wave spawns MAY run in parallel with the next wave's executor when dependency order allows. The `cbp-e2e-*` specialists are parallel siblings of `cbp-testing-qa-agent` — they do not share state.
 
 ### Step 5b: Post-E2E Screenshot Review (cbp-frontend-ui Phase 6.5)
 
-When `round.context.e2e_output.screenshots[]` is non-empty, invoke the `cbp-frontend-ui` skill with `phase: 'screenshot_review'` (input: `files_changed`, `e2e_screenshots: round.context.e2e_output.screenshots`, `context: { checkpoint_goal, round_requirements }`). Under this phase the skill runs only Phase 6.5 (Rendered-Output Visual Review) + 7 + 8 — Phases 1-6 (style) already ran inline at executor Step 3.8 with `phase: 'style_only'`.
+Aggregate screenshots across ALL specialists that ran: `screenshots = Object.values(round.context.e2e_outputs ?? {}).flatMap(o => o.screenshots ?? [])`. When the aggregated list is non-empty, invoke the `cbp-frontend-ui` skill with `phase: 'screenshot_review'` (input: `files_changed`, `e2e_screenshots: <aggregated screenshots>`, `context: { checkpoint_goal, round_requirements }`). Under this phase the skill runs only Phase 6.5 (Rendered-Output Visual Review) + 7 + 8 — Phases 1-6 (style) already ran inline at executor Step 3.8 with `phase: 'style_only'`.
 
 Persist findings to `round.context.frontend_ui_review` (merge with Step 3.8's style-only output if present). Baseline-regression findings surface as a BLOCKING gate at `/cbp-round-end` Step 7 (an explicit accept-or-fix user decision; baselines are NEVER auto-accepted); rendered_visual critical findings are surfaced in the Step 7 findings presentation. Neither auto-fails the round. cbp-testing-qa-agent does NOT read these findings (full independence per Step 5).
 
-**Skip** when `round.context.e2e_output` is absent, `screenshots` is empty, or `testing_profile === 'claude_only'`.
+**Skip** when `round.context.e2e_outputs` is absent/empty, the aggregated `screenshots` list is empty, or `testing_profile === 'claude_only'`.
 
 ### Step 6: Hard-Fail Routing
 
-Per-wave hard-fail signal: `testing_qa_output.totals.hard_fail || e2e_output.status === 'failed' || e2e_output.test_results?.failed > 0`.
+Per-wave hard-fail signal — true when ANY hold:
+
+- `testing_qa_output.totals.hard_fail === true`.
+- For any framework `f` in `round.context.e2e_outputs`: `e2e_outputs[f].status === 'failed'` OR `e2e_outputs[f].test_results?.failed > 0`.
+- **`e2e_eligible_skipped`**: any framework in `round.context.e2e_eligible[]` for which no specialist output exists in `round.context.e2e_outputs` AND no valid skip reason is recorded (per the `rules/e2e-mandatory.md` valid-skip list). A silently-skipped eligible framework is a hard-fail.
 
 **All waves hard_fail: false** → proceed to Step 7. **Any wave hard_fail: true**:
 
-- **Simple fixes** (type errors, lint, missing imports, test assertion fixes, e2e `real`-category with clear code-side root cause, no prior re-trigger this round) → save failure details to round context; retrigger the failing wave's executor; re-run testing-qa AND test-e2e for that wave.
-- **Structural OR already re-triggered once OR e2e preflight aborts** → save failure context via MCP `update_round`; auto-trigger `/cbp-round-input`. STOP.
+- **Simple fixes** (type errors, lint, missing imports, test assertion fixes, e2e `real`-category with clear code-side root cause, no prior re-trigger this round) → save failure details to round context; retrigger the failing wave's executor; re-run testing-qa AND the eligible `cbp-e2e-*` specialists for that wave.
+- **Structural OR already re-triggered once OR e2e preflight aborts OR `e2e_eligible_skipped`** → save failure context via MCP `update_round`; auto-trigger `/cbp-round-input`. STOP.
 
 ## Inline execution fallback
 
@@ -180,9 +192,9 @@ When `cbp-testing-qa-agent` spawn fails OR the resolved `testing_profile` is `cl
 
 Update round context via MCP `update_round`:
 
-- `context`: { ...existing, executor_output, testing_qa_output, e2e_output, frontend_ui_review }
+- `context`: { ...existing, executor_output, testing_qa_output, e2e_eligible, e2e_outputs, frontend_ui_review }
 
-`e2e_output` and `frontend_ui_review` are present only when the gates above admitted them (e2e ran AND Step 5b ran).
+`e2e_outputs` (a framework-keyed map of specialist outputs, e.g. `{ playwright: {...}, maestro: {...} }`) and `frontend_ui_review` are present only when the gates above admitted them (≥1 eligible framework ran AND Step 5b ran). `e2e_eligible[]` records which frameworks were eligible this round and drives the Step 6 `e2e_eligible_skipped` check.
 
 ### Step 8: Auto-trigger Round End
 
@@ -195,17 +207,18 @@ Trigger `/cbp-round-end`.
 ## Key Rules
 
 - **Code + test writing + inline validation** — planning lives in `round-start`, summary in `round-end`
-- Per-wave `cbp-testing-qa-agent` AND `cbp-test-e2e-agent` run in parallel (both against the same wave's `files[]`); they may also run in parallel with the NEXT wave's executor when dependency order allows
-- `testing_profile` from `task.context` governs which checks run — read it once in Step 2; pass to every testing-qa + test-e2e spawn
-- `claude_only` profile skips all agent spawns (testing-qa AND test-e2e); runs hook syntax and skill structure checks inline
-- Step 5b (cbp-frontend-ui Phase 6.5) runs only when e2e produced screenshots — gated on `e2e_output.screenshots[]` non-empty
+- Per-wave `cbp-testing-qa-agent` AND the `cbp-e2e-*` specialist run in parallel (both against the same wave's `files[]`); they may also run in parallel with the NEXT wave's executor when dependency order allows
+- `testing_profile` from `task.context` governs which checks run — read it once in Step 2; pass to every testing-qa + e2e specialist spawn
+- `claude_only` profile skips all agent spawns (testing-qa AND `cbp-e2e-*`); runs hook syntax and skill structure checks inline
+- E2E dispatch is **config-driven and opt-out** (`.codebyplan/e2e.json`), not gated on `has_ui_work`/`testing_profile` — an eligible framework that silently does not run is an `e2e_eligible_skipped` hard-fail (`rules/e2e-mandatory.md`)
+- Step 5b (cbp-frontend-ui Phase 6.5) runs only when e2e produced screenshots — gated on the aggregated `e2e_outputs[*].screenshots[]` being non-empty
 - Claude NEVER git adds files in round commands
 
 ## Integration
 
 - **Reads**: MCP `get_current_task`, `get_rounds`
-- **Writes**: MCP `update_round` (context with executor_output + testing_qa_output + e2e_output + frontend_ui_review)
-- **Spawns**: `cbp-round-executor` (per wave or single), `cbp-testing-qa-agent` (per wave, parallel sibling of cbp-test-e2e-agent), `cbp-test-e2e-agent` (per wave when has_ui_work + non-claude_only profile), `cbp-database-agent` (if DB work), `cbp-security-agent` (if security review needed)
+- **Writes**: MCP `update_round` (context with executor_output + testing_qa_output + e2e_eligible + e2e_outputs + frontend_ui_review)
+- **Spawns**: `cbp-round-executor` (per wave or single), `cbp-testing-qa-agent` (per wave, parallel sibling of the `cbp-e2e-*` specialists), the `cbp-e2e-*` specialists (config-driven dispatch per `context/testing/e2e.md`, one per eligible framework in `.codebyplan/e2e.json`), `cbp-database-agent` (if DB work), `cbp-security-agent` (if security review needed)
 - **Skill invocations**: `cbp-frontend-ui` at Step 5b with `phase: 'screenshot_review'` (post-e2e)
 - **Triggers**: `/cbp-round-end` (auto)
 - **Triggered by**: `/cbp-round-start` (auto, after plan approval)

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

@@ -12,7 +12,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 1.4 may surface a one-line fast-forward note or warning, and Step 5.7 may surface an approval gate. (Step numbers are organizational labels; execution order is 0 → 1 → 1.4 → 2 → 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 1.4 may surface a one-line fast-forward note or warning, Step 1.5 may surface a one-line infra-drift nudge, and Step 5.7 may surface an approval gate. (Step numbers are organizational labels; execution order is 0 → 1 → 1.4 → 1.5 → 2 → 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 Check
 
@@ -77,6 +77,31 @@ CURRENT="$(git rev-parse --abbrev-ref HEAD)"
 
 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 CBP tooling has fallen behind. Runs after Step 1.4 and may add one line to the Step 6 output. Two mutually-exclusive concepts, keyed on repo type (`$PRODUCTION` is the branch resolved in Step 1.4):
+
+- **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:
+
+  ```bash
+  git fetch origin "$PRODUCTION" 2>/dev/null || true
+  node scripts/infra-drift.mjs 2>/dev/null || true
+  ```
+
+  The script self-guards (feat branch + behind > 0) and emits at most one `⚠ .claude/ infra is N behind — run /cbp-refresh-infra` line. Hold any output for Step 6.
+
+- **Consumer (concept B)** — no `templates/`, but an install manifest exists (`.claude/.cbp.manifest.json`, falling back to `.cbp-claude.manifest.json` then `.codebyplan-claude.manifest.json`). Compare its `version` to the latest published `codebyplan`, offline-safe:
+
+  ```bash
+  LATEST="$(npm view codebyplan version 2>/dev/null)"
+  ```
+
+  When `$LATEST` is non-empty and newer than the manifest `version`, hold one line for Step 6: `⚠ codebyplan {installed} → {LATEST} — run npx codebyplan@latest claude update`. Any failure (offline, npm absent) → silent.
+
+- **Neither** → skip silently.
+
+Concept B never fires in the monorepo — the `templates/` guard routes the source repo to concept A only (its manifest `version` is intentionally stale). Fully non-blocking; every failure path falls through with no output.
+
 ### Step 2: Check Dev Server
 
 **Skip if `server_type` is `"none"`.**
@@ -198,7 +223,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 `get_session_logs` (worktree-filtered, limit 1 — single call shared by Step 4 and Step 4.5), MCP `health_check`, MCP `get_current_task`, MCP `get_rounds`, MCP `get_checkpoints` (two calls: `{ repo_id, status: 'active' }` for the Step 5.8 ownership partition; `{ repo_id }` unfiltered for the Step 4.5 freshness probe, which may resolve a non-active checkpoint), MCP `get_tasks` / `get_rounds` for the Step 4.5 freshness probe
+- **Reads**: `.codebyplan/repo.json`, `.codebyplan/git.json` (`branch_config.production` for the Step 1.4 home-branch fast-forward), MCP `get_session_logs` (worktree-filtered, limit 1 — single call shared by Step 4 and Step 4.5), MCP `health_check`, MCP `get_current_task`, MCP `get_rounds`, MCP `get_checkpoints` (two calls: `{ repo_id, status: 'active' }` for the Step 5.8 ownership partition; `{ repo_id }` unfiltered for the Step 4.5 freshness probe, which may resolve a non-active checkpoint), MCP `get_tasks` / `get_rounds` for the Step 4.5 freshness probe; `scripts/infra-drift.mjs` + a best-effort `git fetch` (Step 1.5 monorepo drift) or the install manifest + `npm view codebyplan version` (Step 1.5 consumer drift)
 - **Writes**: MCP `create_session_log` (new, possibly empty), MCP `update_session_state` (activate)
 - **Spawns**: none
 - **Triggers**: `/cbp-git-commit` (conditional, on user approval), `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)

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:

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-check/SKILL.md

@@ -18,12 +18,12 @@ If the `cbp-task-check` agent spawn fails for any reason (`API Error: Extra usag
 Procedure summary (pointer back to canonical):
 
 1. Detect the failure class from the error string; record `round.context.task_check_findings.spawn_failure = { class, error_message, decided_at }`.
-2. Walk the agent's documented Phase 1-10 checklist inline using `Read` / `Grep` / `Bash` / MCP `get_*` tools — the agent's AGENT.md is the inline script.
+2. Walk the agent's documented Phase 1-10 checklist inline using `Read` / `Grep` / `Bash` / MCP `get_*` tools — the agent's definition file is the inline script.
 3. Populate the agent's output contract (`verdict`, `route_recommendation`, `requirements_status`, `qa_status`, `code_review_findings`, `user_satisfaction`, `scope_divergence_detected`, etc.) with `mode: 'inline_fallback'` so analytics distinguishes.
 4. Apply the pre-emptive-skip rule: when the same failure class fired in the previous skill of this session, skip the spawn attempt entirely and go straight to inline.
 5. Continue the skill — do NOT abort. Inline-fallback is intended to keep the pipeline moving under sustained outages.
 
-Inline-fallback is NOT a quality downgrade trapdoor — every Phase from the AGENT.md MUST be walked, in order, with the same Read/Grep depth the agent would have used. Skipping phases under the banner of fallback is a separate failure mode that `cbp-improve-claude` flags as `inline_fallback_shortcutting`.
+Inline-fallback is NOT a quality downgrade trapdoor — every Phase from the agent definition MUST be walked, in order, with the same Read/Grep depth the agent would have used. Skipping phases under the banner of fallback is a separate failure mode that `cbp-improve-claude` flags as `inline_fallback_shortcutting`.
 
 ## When Used
 

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: