codebyplan 1.11.1 → 1.12.0

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

@@ -0,0 +1,99 @@
+---
+scope: org-shared
+description: Supabase preview-branch lifecycle mirrors the git feat-branch lifecycle
+paths:
+  - "supabase/migrations/**"
+  - ".codebyplan/shipment.json"
+  - ".codebyplan/git.json"
+  - ".claude/skills/cbp-supabase-migrate/**"
+  - ".claude/skills/cbp-supabase-branch-check/**"
+  - ".claude/skills/cbp-checkpoint-end/**"
+  - ".claude/skills/cbp-git-worktree-remove/**"
+  - ".claude/skills/cbp-ship-main/**"
+---
+
+# Supabase Branch Lifecycle
+
+When a checkpoint or standalone task does DB work on its own feat branch, that branch gets
+a Supabase preview branch whose lifecycle mirrors the git branch — created on first DB
+change, deleted when the git branch is removed.
+
+## Contract
+
+Each feat branch that touches the database owns exactly one Supabase preview branch, named
+identically to the git branch. The git branch is the source of truth; the Supabase branch
+follows it.
+
+## Create (lazy)
+
+The Supabase branch is created by `cbp-supabase-migrate` (Step 2.3) on the **first DB
+change** for the branch — never eagerly at git-branch creation time. Creation is guarded
+by the skill's db_paths detection so the step fires only when the invocation actually
+touches the database.
+
+The branch is named **verbatim** after the git branch, slashes included (e.g.
+`feat/CHK-144-supabase-branch-lifecycle`). This identical naming is the linchpin: the
+GitHub branching integration reconciles to the same branch on PR open rather than creating
+a duplicate.
+
+After creation, the branch name and resulting `project_ref` are recorded on the parent
+checkpoint or standalone task context (via `mcp__codebyplan__update_checkpoint` /
+`mcp__codebyplan__update_task`) and may also be noted in `.codebyplan/shipment.json` so
+cleanup skills can discover and remove it without querying the API.
+
+## Delete
+
+The Supabase branch is removed wherever the git branch is deleted:
+
+| Skill | Trigger |
+|---|---|
+| `cbp-checkpoint-end` | stale-branch cleanup + current feat-branch delete on ship |
+| `cbp-git-worktree-remove` | worktree teardown removes the coupled Supabase branch |
+| `cbp-ship-main` | `branch_deleted` event after PR merge |
+
+Deletion is **existence-checked and idempotent** — a not-found response is treated as
+success. This tolerates the GitHub integration auto-deleting the preview branch on PR
+close before the skill runs.
+
+These skills use `delete_branch` (MCP tool), never `merge_branch`. Production migrations
+reach main via the existing merge path (GitHub rebuild / `last_shipped_migration_version`);
+there is no separate Supabase branch merge step.
+
+## Exclusions
+
+This lifecycle applies **only to feat branches**. It MUST NOT fire for:
+
+- The main/production branch (`branch_config.production`, default `"main"`)
+- Any branch listed in `branch_config.protected[]`
+- A standalone task running directly on the production branch
+- The integration branch (`branch_config.integration`) when non-null — it gets a persistent branch via `cbp-supabase-setup`, not a lazy ephemeral one.
+
+`cbp-supabase-migrate` Step 2.3 Guard 1 enforces this by reading `.codebyplan/git.json`
+and skipping provisioning when the current branch matches `$PRODUCTION`, `$PROTECTED`, or
+a non-null `$INTEGRATION`.
+
+## Guards
+
+Skills that delete Supabase branches MUST:
+
+1. Verify the branch name matches the feat branch being removed (never delete by
+   `project_ref` alone).
+2. Never delete the parent/production project (`rrvtrumtkhrsbhcyrwvf`) itself.
+3. Never delete a persistent/long-lived branch that does not correspond to the git branch
+   being torn down.
+
+## PR Gate (retained)
+
+`cbp-supabase-branch-check` runs as a required PR gate, independent of the create/delete
+coupling. By-name resolution works whether the branch was created by `cbp-supabase-migrate`
+or auto-created by the GitHub integration — both paths use the same branch name.
+
+## Skill Map
+
+| Role | Skill |
+|---|---|
+| Create (lazy) | `cbp-supabase-migrate` (Step 2.3) |
+| Delete | `cbp-checkpoint-end`, `cbp-git-worktree-remove`, `cbp-ship-main` |
+| PR gate | `cbp-supabase-branch-check` |
+
+Each skill in the Skill Map above carries an inline back-reference to this rule at its create or teardown step.

package/templates/settings.project.base.json

@@ -39,8 +39,7 @@
       "Bash(git push --force:*)",
       "Bash(git push -f:*)",
       "Bash(git checkout -- :*)",
-      "Bash(git add .:*)",
-      "Bash(git add -A:*)",
+      "Bash(git add:*)",
       "Bash(rm -rf:*)",
       "Bash(pnpm add:*)",
       "Bash(pnpm install:*)",

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

@@ -1,7 +1,7 @@
 ---
 scope: org-shared
 name: cbp-build-cc-agent
-description: Build a Claude Code subagent at .claude/agents/{name}/AGENT.md (CBP folder form) following the official sub-agents spec (frontmatter, tools, model, memory, hooks, skills preload, permission modes, isolation).
+description: Build a Claude Code subagent at .claude/agents/{name}.md (flat form, per the official sub-agents spec) following the official sub-agents spec (frontmatter, tools, model, memory, hooks, skills preload, permission modes, isolation).
 argument-hint: "[agent-name] [--scope=project|user] [--memory=project|user|local] [--isolation=worktree]"
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash(mkdir *), Bash(chmod *)
 effort: xhigh
@@ -32,18 +32,18 @@ Do **not** create a subagent for one-off work — spawn `general-purpose` inline
 
 - Name must be lowercase kebab-case (a–z, 0–9, hyphens only)
 - Reject collisions with built-in agents: `Explore`, `Plan`, `general-purpose`, `statusline-setup`, `Claude Code Guide`
-- Reject if `.claude/agents/{name}/AGENT.md` already exists unless the user asked to update
+- Reject if `.claude/agents/{name}.md` already exists unless the user asked to update
 
 ### Step 2 — Pick scope
 
-CBP uses the **folder form** so an agent can bundle supporting docs/scripts next to `AGENT.md`.
+The default layout is **flat form** — a single `.claude/agents/{name}.md` file, matching the official Claude Code sub-agents spec and all 12 existing CBP agents. Use folder form `{name}/AGENT.md` only when the agent bundles supporting files (context, examples, scripts) next to it.
 
-| Scope   | Path                               | Use when                                |
-| ------- | ---------------------------------- | --------------------------------------- |
-| project | `.claude/agents/{name}/AGENT.md`   | Repo-specific, shared with team via git |
-| user    | `~/.claude/agents/{name}/AGENT.md` | Personal, reused across all projects    |
+| Scope   | Path                            | Use when                                |
+| ------- | ------------------------------- | --------------------------------------- |
+| project | `.claude/agents/{name}.md`      | Repo-specific, shared with team via git |
+| user    | `~/.claude/agents/{name}.md`    | Personal, reused across all projects    |
 
-Default: `project`. Pass `--scope=user` to override. Flat form (`.claude/agents/{name}.md`) is the Claude Code native layout but CBP's structure hook expects the folder form — always use that in this repo.
+Default: `project`. Pass `--scope=user` to override. Use folder form `{scope-path}/{name}/AGENT.md` only when bundling supporting files alongside the agent definition.
 
 ### Step 3 — Read the template and CBP context
 
@@ -89,8 +89,8 @@ Cross-references for complex cases:
 
 ### Step 6 — Write the agent file
 
-1. Create directory: `mkdir -p {scope-path}/{name}`
-2. Write `{scope-path}/{name}/AGENT.md`
+1. Write `{scope-path}/{name}.md` (flat form — default for all new agents)
+2. If the agent bundles supporting files (context, examples, scripts), create a folder instead: `mkdir -p {scope-path}/{name}` and write `{scope-path}/{name}/AGENT.md`
 3. Copy the template, fill frontmatter, then write the system prompt as the markdown body. The body becomes the agent's entire system prompt — no CLAUDE.md prefix, no Claude Code defaults.
 
 System prompt guidance:
@@ -100,16 +100,18 @@ System prompt guidance:
 - Output format it must return
 - Failure modes (when to return `blocked`, `failed`, `no_findings`)
 
-Supporting files (optional) live next to `AGENT.md` in the same folder: `{name}/context.md`, `{name}/examples/`, etc.
+Supporting files (optional) live next to the agent in a same-name folder: `{name}/context.md`, `{name}/examples/`, etc. Only create the folder when you are actually writing supporting files.
 
 ### Step 7 — Validate
 
 Run the validator:
 
 ```bash
-bash "${CLAUDE_SKILL_DIR}/scripts/validate-agent.sh" "{scope-path}/{name}/AGENT.md"
+bash "${CLAUDE_SKILL_DIR}/scripts/validate-agent.sh" "{scope-path}/{name}.md"
 ```
 
+(Pass `{scope-path}/{name}/AGENT.md` instead if folder form was chosen.)
+
 It checks: name format, frontmatter parses, required fields present (`name`, `description`, `scope`), tool names are valid, model alias is recognised.
 
 ### Step 8 — Surface to the user
@@ -126,7 +128,7 @@ Report:
 
 - **Triggered by**: user invocation
 - **Reads**: `${CLAUDE_SKILL_DIR}/templates/agent.md`, `${CLAUDE_SKILL_DIR}/reference/*.md` (including `cbp-quality.md`)
-- **Writes**: `.claude/agents/{name}/AGENT.md` or `~/.claude/agents/{name}/AGENT.md`
+- **Writes**: `.claude/agents/{name}.md` (flat default) or `.claude/agents/{name}/AGENT.md` (folder form, when bundling supporting files); same under `~/.claude/` for user scope
 - **Related skills**: `/cbp-build-cc-skill` (skill-level workflows), `/cbp-build-cc-settings` (session-level `SubagentStart`/`SubagentStop` hooks), `/cbp-build-cc-mode` (canonical model/effort matrix — audit or apply)
 
 ## Key Rules
@@ -136,4 +138,4 @@ Report:
 - `bypassPermissions` and `acceptEdits` inherited from the parent cannot be weakened by the child
 - Preloaded skills inject _full content_ at startup — don't preload `disable-model-invocation: true` skills
 - Restart the session or use `/agents` to load a newly written agent file
-- CBP folder form is required — the structure hook blocks flat agent files in this repo
+- Flat form `.claude/agents/{name}.md` is the default and matches all 12 existing CBP agents; folder form `{name}/AGENT.md` is optional and only for agents that bundle supporting files alongside them

package/templates/skills/cbp-build-cc-agent/reference/cbp-quality.md

@@ -4,11 +4,11 @@ scope: org-shared
 
 # Agent Authoring Quality
 
-Quality expectations and structure for `/.claude/agents/{name}/AGENT.md` files. This file adds CBP-specific constraints on top of the official Claude Code sub-agents spec.
+Quality expectations and structure for `/.claude/agents/{name}.md` files. This file adds CBP-specific constraints on top of the official Claude Code sub-agents spec.
 
-## CBP Folder Form
+## Agent Layout
 
-CBP uses the folder form `.claude/agents/{name}/AGENT.md`, not Claude Code's native flat `.claude/agents/{name}.md`. The structure hook enforces this. Folder form lets an agent bundle supporting files (context, examples, scripts) next to `AGENT.md`.
+CBP uses the flat form `.claude/agents/{name}.md` — the default per the official Claude Code sub-agents spec. All 12 existing CBP agents use this layout. Folder form `.claude/agents/{name}/AGENT.md` is optional and only appropriate when the agent bundles supporting files (context, examples, scripts) next to the definition.
 
 ## Required CBP Frontmatter
 
@@ -125,7 +125,7 @@ Agents that modify `.claude/` files MUST:
 
 | Situation                                | Action                                          |
 | ---------------------------------------- | ----------------------------------------------- |
-| Existing agent covers the domain         | Update its AGENT.md                             |
+| Existing agent covers the domain         | Update its agent definition file                |
 | New domain, no existing agent covers it  | Create new agent                                |
 | Existing agent is too large (>400 lines) | Split into orchestrator + specialist            |
 | One-off task, not recurring              | Don't create an agent — use inline instructions |

package/templates/skills/cbp-build-cc-agent/scripts/validate-agent.sh

@@ -1,11 +1,12 @@
 #!/bin/bash
-# Validate a Claude Code subagent file (CBP folder form).
-# Usage: validate-agent.sh <path-to-AGENT.md>
+# Validate a Claude Code subagent file (flat form or CBP folder form).
+# Usage: validate-agent.sh <path-to-agent-file>
+# Accepts: flat agents/{name}.md (spec default) or folder agents/{name}/AGENT.md (for bundling).
 # Exit 0 = valid, exit 1 = invalid (errors printed to stderr).
 
 set -uo pipefail
 
-FILE="${1:?Usage: validate-agent.sh <path-to-AGENT.md>}"
+FILE="${1:?Usage: validate-agent.sh <path-to-agent-file>}"
 
 if [ ! -f "$FILE" ]; then
   echo "ERROR: file not found: $FILE" >&2
@@ -15,10 +16,11 @@ fi
 errors=0
 err() { echo "  - $1" >&2; errors=$((errors + 1)); }
 
-# CBP folder form: .claude/agents/{name}/AGENT.md
+# Accept flat agents/{name}.md (spec default) or folder agents/{name}/AGENT.md (when bundling)
 case "$FILE" in
-  */AGENT.md) ;;
-  *) err "CBP expects folder form: .claude/agents/{name}/AGENT.md (got: $FILE)";;
+  */AGENT.md) ;;                # folder form (agent bundles supporting files)
+  */agents/*.md) ;;             # flat form — Claude Code spec default
+  *) err "expected a subagent markdown file under agents/ — flat agents/{name}.md or folder agents/{name}/AGENT.md (got: $FILE)";;
 esac
 
 # Frontmatter must be present

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

@@ -1,7 +1,7 @@
 ---
 scope: org-shared
 name: cbp-build-cc-mode
-description: Audit + apply the CHK-109 model/effort matrix across every authoring skill and agent under `packages/codebyplan-package/templates/`. Bare invocation walks all SKILL.md and AGENT.md files and reports frontmatter gaps; with a path argument, edits the target file's frontmatter to the matrix-decided values.
+description: Audit + apply the CHK-109 model/effort matrix across every authoring skill and agent under `packages/codebyplan-package/templates/`. Bare invocation walks all SKILL.md and agent .md files and reports frontmatter gaps; with a path argument, edits the target file's frontmatter to the matrix-decided values.
 argument-hint: "[path-to-agent-or-skill]"
 allowed-tools: Read, Write, Edit, Glob, Grep
 effort: xhigh
@@ -23,7 +23,7 @@ Audit or apply the canonical `model:` + `effort:` frontmatter convention across
 
 `model: sonnet` + `effort: xhigh`
 
-Eleven of the 12 authoring agents take the default (`cbp-cc-executor`, `cbp-database-agent`, `cbp-improve-claude`, `cbp-improve-round`, `cbp-research`, `cbp-round-executor`, `cbp-security-agent`, `cbp-task-check`, `cbp-task-planner`, `cbp-test-e2e-agent`, `cbp-testing-qa-agent`). The 12th — `cbp-mechanical-edits` — is an explicit haiku-low exception (see below). 27 skills take the default: cbp-round-start, cbp-round-input, cbp-round-execute, cbp-task-create, cbp-task-start, cbp-task-complete, cbp-task-testing, cbp-checkpoint-create, cbp-checkpoint-check, cbp-checkpoint-end, cbp-build-cc-mode, cbp-build-cc-agent, cbp-build-cc-skill, cbp-build-cc-rule, cbp-build-cc-claude-file, cbp-build-cc-memory, cbp-build-cc-settings, cbp-frontend-a11y, cbp-frontend-design, cbp-frontend-ui, cbp-frontend-ux, cbp-session-end, cbp-ship, cbp-ship-configure, cbp-supabase-setup, cbp-supabase-migrate, cbp-supabase-branch-check.
+Fifteen of the 16 authoring agents take the default (`cbp-cc-executor`, `cbp-database-agent`, `cbp-improve-claude`, `cbp-improve-round`, `cbp-research`, `cbp-round-executor`, `cbp-security-agent`, `cbp-task-check`, `cbp-task-planner`, `cbp-testing-qa-agent`, `cbp-e2e-playwright`, `cbp-e2e-maestro`, `cbp-e2e-tauri`, `cbp-e2e-vscode`, `cbp-e2e-xcuitest`). The 16th — `cbp-mechanical-edits` — is an explicit haiku-low exception (see below). 27 skills take the default: cbp-round-start, cbp-round-input, cbp-round-execute, cbp-task-create, cbp-task-start, cbp-task-complete, cbp-task-testing, cbp-checkpoint-create, cbp-checkpoint-check, cbp-checkpoint-end, cbp-build-cc-mode, cbp-build-cc-agent, cbp-build-cc-skill, cbp-build-cc-rule, cbp-build-cc-claude-file, cbp-build-cc-memory, cbp-build-cc-settings, cbp-frontend-a11y, cbp-frontend-design, cbp-frontend-ui, cbp-frontend-ux, cbp-session-end, cbp-ship, cbp-ship-configure, cbp-supabase-setup, cbp-supabase-migrate, cbp-supabase-branch-check.
 
 ### Effort-lowered skills (5)
 
@@ -55,7 +55,7 @@ Eleven of the 12 authoring agents take the default (`cbp-cc-executor`, `cbp-data
 
 ### Haiku-low agents (1)
 
-`model: haiku` + `effort: low`. The 12th authoring agent — pure I/O mechanical work, never authors logic.
+`model: haiku` + `effort: low`. The 16th authoring agent — pure I/O mechanical work, never authors logic.
 
 | agent                | model | effort | reason                                                                              |
 | -------------------- | ----- | ------ | ----------------------------------------------------------------------------------- |
@@ -87,7 +87,7 @@ The audit is read-only — no edits performed.
 
 ## Apply Mode
 
-Invoked with a path argument (the target `SKILL.md` or `AGENT.md`). Procedure:
+Invoked with a path argument (the target `SKILL.md` or agent `.md`). Procedure:
 
 1. Read the file. Identify the skill or agent name from the `name:` frontmatter field (or from the path basename if `name:` is absent).
 2. Look up target `model` + `effort` from the matrix above.

package/templates/skills/cbp-build-cc-settings/reference/cbp-conventions.md

@@ -47,8 +47,7 @@ These values are part of the CBP baseline and should not be weakened:
       "Bash(git push --force:*)",
       "Bash(git push -f:*)",
       "Bash(git checkout -- :*)",
-      "Bash(git add .:*)",
-      "Bash(git add -A:*)",
+      "Bash(git add:*)",
       "Bash(rm -rf:*)",
       "Bash(pnpm add:*)",
       "Bash(pnpm install:*)",

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

@@ -90,11 +90,9 @@ Re-run build/lint/types on current codebase to verify nothing regressed across t
 
 Aggregate the files touched across all tasks (reusing Step 4's deduplicated table) and run e2e once against the union of pages they affect.
 
-1. **Build `pages_affected`** — derive from Step 4's `files_changed` union using the same heuristic as `cbp-test-e2e-agent` Step 5.1 (Next.js: `app/<route>/page.tsx` chains; Expo: screen files; Tauri: route components; fallback: directory-based grouping). Deduplicate by route / screen.
+1. **Build `pages_affected`** — derive from Step 4's `files_changed` union using the same heuristic as `context/testing/e2e.md` Step 5.1 (Next.js: `app/<route>/page.tsx` chains; Expo: screen files; Tauri: route components; fallback: directory-based grouping). Deduplicate by route / screen.
 
-2. **Spawn `cbp-test-e2e-agent`** via the Agent tool with:
-
-   `test_strategy` is intentionally omitted — the agent auto-detects per-app via its Step 1.5 DB tech-stack lookup (`get_repos`) and Step 2 filesystem reconciliation. Mixed-framework monorepos disambiguate via `tech_stack.apps[]`; pre-pass `test_strategy` only when DB tech_stack is empty AND filesystem probe is ambiguous.
+2. **Config-driven dispatch** (per `context/testing/e2e.md` dispatch contract): read `.codebyplan/e2e.json`. If the file is absent or `frameworks` is empty, append `| Checkpoint E2E | n/a | no framework configured |` to the Step 5 QA Summary and continue to Step 6. Otherwise, for each entry where `enabled === true` AND `auto_run === true` whose `app` path intersects the aggregated `files_changed` union, spawn the matching `cbp-e2e-*` specialist via the Agent tool — one per eligible framework, in parallel. Inject `framework`, `app`, `platforms`, and `credential_vars` from `e2e.json` (authoritative; the agent does not auto-detect):
 
    ```yaml
    input:
@@ -105,18 +103,24 @@ Aggregate the files touched across all tasks (reusing Step 4's deduplicated tabl
      pages_affected: [aggregated]
      has_auth: [boolean, from .codebyplan/server.json + repo]
      dev_server_port: [from .codebyplan/server.json]
+     framework: [from e2e.json — authoritative]
+     app: [from e2e.json — e.g. apps/web]
+     platforms: [from e2e.json — e.g. ["web"]]
+     credential_vars: [from e2e.json — env var names only, never secrets]
    ```
 
-3. **Wait for completion.** The agent's output carries `whole_checkpoint_aggregated: true` confirming whole-checkpoint formatting.
+   Hold each specialist's output keyed by framework (an `e2e_outputs[framework]` map) for this skill's aggregation — checkpoint-check has no MCP round, so this lives in-memory during the run (persist to `checkpoint.context` via `update_checkpoint` at Step 7 if a durable record is needed). `test_strategy` is intentionally omitted — the agent resolves it from `.codebyplan/e2e.json` and the DB tech-stack record.
+
+3. **Wait for all specialists to complete.** Each agent's output carries `whole_checkpoint_aggregated: true` confirming whole-checkpoint formatting.
 
-4. **On pass** (`e2e_output.status === 'completed'` AND `e2e_output.test_results.failed === 0`): append a row to the Step 5 QA Summary table:
+4. **On pass** (every eligible framework `f`: `e2e_outputs[f].status === 'completed'` AND `e2e_outputs[f].test_results.failed === 0`): append a row to the Step 5 QA Summary table:
    ```
    | Checkpoint E2E | pass | aggregated |
    ```
    Continue to Step 6.
 
-5. **On fail** (`e2e_output.status === 'failed'` OR `e2e_output.test_results.failed > 0`): build a failure summary from `e2e_output.test_results.failures[]` grouped by `category`. Surface via `AskUserQuestion`:
-   - **(a) Create fix-task in CHK-{NNN} (recommended)** — invoke MCP `create_task` with `checkpoint_id=current_checkpoint_id`, `title="Fix checkpoint-level e2e failures (CHK-{NNN})"`, `requirements` containing the detailed failure breakdown (category counts, files involved, pages broken, screenshot paths from `e2e_output.screenshots[]`), AND `context: { source_checkpoint_id, e2e_failure_summary: { category_counts, pages_broken, screenshot_paths }, fix_type: "checkpoint_e2e" }` so downstream `cbp-task-planner` Phase 1.5 can verify failure premises programmatically without re-parsing the requirements text. Per `infra-issue-absorption.md` "Resolve-in-Current-Scope by Default", checkpoint-level e2e failures absorb into the active checkpoint — not standalone.
+5. **On fail** (any framework `f`: `e2e_outputs[f].status === 'failed'` OR `e2e_outputs[f].test_results.failed > 0`): build a failure summary from `e2e_outputs[*].test_results.failures[]` aggregated and grouped by `category`. Surface via `AskUserQuestion`:
+   - **(a) Create fix-task in CHK-{NNN} (recommended)** — invoke MCP `create_task` with `checkpoint_id=current_checkpoint_id`, `title="Fix checkpoint-level e2e failures (CHK-{NNN})"`, `requirements` containing the detailed failure breakdown (category counts, files involved, pages broken, screenshot paths from `e2e_outputs[*].screenshots[]`), AND `context: { source_checkpoint_id, e2e_failure_summary: { category_counts, pages_broken, screenshot_paths }, fix_type: "checkpoint_e2e" }` so downstream `cbp-task-planner` can verify failure premises. Per `infra-issue-absorption.md` "Resolve-in-Current-Scope by Default", checkpoint-level e2e failures absorb into the active checkpoint — not standalone.
    - **(b) Surface as warning only — proceed to checkpoint-end** — append `| Checkpoint E2E | warning | N failures (deferred) |` to Step 5 QA Summary; continue to Step 6.
    - **(c) Halt — review manually** — STOP and wait for the user.
 

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

@@ -95,6 +95,8 @@ git push -u origin "feat/CHK-{NNN}-{slug}"
 
 Slug: lowercase, dash-joined, punctuation dropped, ≤40 chars. Persist the branch via MCP `update_checkpoint(checkpoint_id, branch_name: "feat/CHK-{NNN}-{slug}")`. (The dedicated `/cbp-git-branch-feat-create` skill is the canonical config-driven helper if you prefer to delegate.)
 
+**Note — Supabase preview branch**: no Supabase branch is created here. Creation is lazy — it happens on the first DB change when `/cbp-supabase-migrate` runs on this feat branch, which provisions a Supabase branch named identically to the git branch. See `cbp-supabase-migrate` Step 2.3 for the creation protocol.
+
 ### Step 10: Show Result + Auto-Trigger Plan
 
 ```

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

@@ -141,13 +141,25 @@ C) Keep all
 
 Only delete with explicit user confirmation. Delete both local and remote:
 ```bash
-git branch -d "$BRANCH" 2>/dev/null
-git push origin --delete "$BRANCH"
+git branch -d "$BRANCH" && git push origin --delete "$BRANCH"
 ```
 
+Only after both the local and remote git delete above succeed, run a conditional Supabase preview-branch teardown for that branch name (do not suppress the delete output — a failed local delete must stay visible):
+
+> Lifecycle contract: see [[supabase-branch-lifecycle]].
+
+- Call `mcp__supabase__list_branches` with `project_id: rrvtrumtkhrsbhcyrwvf`.
+- Scan the returned list for an entry whose `name` exactly equals `$BRANCH`.
+- If found: call `mcp__supabase__delete_branch` with its `branch_id`. Record the branch name in `SUPABASE_BRANCHES_DELETED[]`.
+- If not found: no-op silently — the GitHub integration may have already removed it on PR close; not-found is success, NOT an error.
+- If the `list_branches` call itself fails (network, auth, or a non-success response — distinct from a successful lookup that returns no match): emit a non-blocking warning that the Supabase preview branch for `$BRANCH` 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.
+
+Accumulate all Supabase branch names removed across the loop in `SUPABASE_BRANCHES_DELETED`.
+
 ### Step 9: Current Feat Branch Cleanup
 
-Present comprehensive summary first (Step 10), then ask about current feat branch via AskUserQuestion:
+Before asking about the current feat branch, present a partial summary of what has shipped so far — runtime surfaces (from `/cbp-ship` Step 7), stale branches cleaned (Step 8), and the `SUPABASE_BRANCHES_DELETED` accumulated so far — then ask about the current feat branch via AskUserQuestion (the complete shipment record is finalised in Step 10):
 
 ```
 The current feat branch [BRANCH] has been fully merged.
@@ -166,6 +178,14 @@ git branch -d "$FEAT_BRANCH"
 git push origin --delete "$FEAT_BRANCH"
 ```
 
+After the feat branch git delete, run the same conditional Supabase teardown for `$FEAT_BRANCH`:
+
+- Call `mcp__supabase__list_branches` with `project_id: rrvtrumtkhrsbhcyrwvf`.
+- Scan for an entry whose `name` exactly equals `$FEAT_BRANCH`.
+- If found: call `mcp__supabase__delete_branch` with its `branch_id`. Add `$FEAT_BRANCH` to `SUPABASE_BRANCHES_DELETED[]`.
+- If not found: no-op silently — idempotent, not-found is success.
+- 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.
+
 ### Step 10: Save Shipment Results and Summary
 
 Update checkpoint context via MCP `update_checkpoint`. The `shipment` block contains both branch promotion AND runtime surface results (from `/cbp-ship` Step 7):
@@ -177,8 +197,9 @@ context.shipment: {
   feat_to_base: { pr_url, merged: true/false },
   surfaces: [...],          // populated by /cbp-ship — per-surface deploy results
   skipped: [...],           // populated by /cbp-ship — surfaces explicitly skipped
-  stale_branches_cleaned: [list of deleted branches],
-  feat_branch_deleted: true/false
+  stale_branches_cleaned: [list of deleted git branches],
+  feat_branch_deleted: true/false,
+  supabase_branches_deleted: [list of Supabase preview branch names removed in Steps 8–9]
 }
 ```
 
@@ -198,6 +219,7 @@ Present summary:
 ### Branch Operations
 - Stale branches deleted: [N] ([list])
 - Feat branch: [deleted/kept]
+- Supabase preview branches deleted: [N] ([list from supabase_branches_deleted], or "none")
 
 ### Before/After Branch State
 - Before: [list of feat/* branches]

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

@@ -63,7 +63,7 @@ Only relevant when an idea touches a UI surface AND you SUSPECT an existing flow
 
 1. Surface the suspicion: name the area + the specific pages/screens, and why you think it is broken.
 2. Ask the user via AskUserQuestion to confirm running the probe (it needs a running dev server).
-3. On confirm, spawn `cbp-test-e2e-agent` with `whole_checkpoint_mode: true`, `round_number: 0`, `files_changed: []`, the `pages_affected` you proposed, plus `repo_id` / `test_strategy` / `has_auth` / `dev_server_port`. Resolve `test_strategy` and `dev_server_port` per `reference/e2e-discovery-probe.md` (do not pass placeholder strings).
+3. On confirm, spawn the config-matched `cbp-e2e-*` specialist (for a web app, `cbp-e2e-playwright`) per the `context/testing/e2e.md` dispatch contract, with `whole_checkpoint_mode: true`, `round_number: 0`, `files_changed: []`, the `pages_affected` you proposed, plus `repo_id` / `test_strategy` / `has_auth` / `dev_server_port`. Resolve `test_strategy` and `dev_server_port` per `reference/e2e-discovery-probe.md` (do not pass placeholder strings).
 4. Record the probe outcome (what actually failed vs. what you assumed) in `context.discoveries[]` so the plan targets real defects.
 
 Skip this step entirely for non-UI checkpoints or when no breakage is suspected.
@@ -131,7 +131,7 @@ This skill does **NOT** activate the checkpoint and does **NOT** claim a user/wo
 
 - **Reads**: MCP `get_current_task`, `get_checkpoints`, `get_tasks`
 - **Writes**: MCP `update_checkpoint` (ideas assessment, context, plan, research), `create_task`
-- **Spawns**: `cbp-research` (level 2+ only), `cbp-test-e2e-agent` (opt-in discovery probe, `whole_checkpoint_mode`)
+- **Spawns**: `cbp-research` (level 2+ only), config-matched `cbp-e2e-*` specialist (opt-in discovery probe, `whole_checkpoint_mode` — see `context/testing/e2e.md` dispatch contract)
 - **Triggered by**: `/cbp-checkpoint-create` (auto), or user directly
 - **Triggers**: `/cbp-checkpoint-start` (auto when claimed at create; directive when left open)
 - **Never**: activates the checkpoint or claims a user/worktree — that is `/cbp-checkpoint-start`

package/templates/skills/cbp-checkpoint-plan/reference/e2e-discovery-probe.md

@@ -4,7 +4,7 @@ scope: org-shared
 
 # E2E Discovery Probe
 
-Loaded by `/cbp-checkpoint-plan` Step 4. The probe answers one question before you plan a fix: **is this area actually broken, and how?** It reuses `cbp-test-e2e-agent` (the sole owner of e2e execution) in `whole_checkpoint_mode` rather than introducing a second smoke-test path.
+Loaded by `/cbp-checkpoint-plan` Step 4. The probe answers one question before you plan a fix: **is this area actually broken, and how?** It reuses the config-matched `cbp-e2e-*` specialist (the framework owners of e2e execution) in `whole_checkpoint_mode` rather than introducing a second smoke-test path. See `context/testing/e2e.md` for the dispatch contract that selects which specialist to spawn.
 
 ## When to offer the probe
 
@@ -20,8 +20,8 @@ Skip silently for backend-only / infra / `claude_only` checkpoints, or when you
 1. **State the suspicion** — name the area, the specific pages/screens, and why you think it is broken (a stale selector, a route that 404s, a recent refactor nearby).
 2. **Confirm with the user** via AskUserQuestion — the probe needs a running dev server, so it is opt-in. Options: run the probe / skip and plan from assumption / let me name different pages.
 3. **Resolve the dev-server port** from `.codebyplan/server.json` `port_allocations[]` (pick the entry whose `server_type` matches the app, e.g. `nextjs`). If nothing is running there, ask the user to start it or skip.
-4. **Resolve `test_strategy`** — call MCP `get_repos()`, find the entry where `id === repo_id`, and read the affected app's platform + e2e framework from its `tech_stack` record. If the record has no e2e data, pass `null` for the unknown fields — the agent resolves them itself at its Step 1.5. Do NOT pass placeholder strings.
-5. **Spawn** `cbp-test-e2e-agent` with the payload below.
+4. **Resolve `test_strategy`** — call MCP `get_repos()`, find the entry where `id === repo_id`, and read the affected app's platform + e2e framework from its `tech_stack` record. If the record has no e2e data, pass `null` for the unknown fields — the agent resolves them itself. Do NOT pass placeholder strings.
+5. **Spawn** the config-matched `cbp-e2e-*` specialist per `context/testing/e2e.md` dispatch contract (e.g. `cbp-e2e-playwright` for a web app) with the payload below.
 6. **Interpret** the result: compare what actually failed against what you assumed. Record the delta in `context.discoveries[]` so the plan targets real defects, not imagined ones.
 
 ## Spawn payload (whole_checkpoint_mode)
@@ -52,6 +52,6 @@ The agent returns `test_results` (passed / failed / skipped + per-failure `categ
 - `category: 'env' | 'auth' | 'access' | 'flake'` → not the feature's fault; note it but do not plan a code fix around it.
 - A clean pass → your breakage suspicion was wrong; plan the actual requested change without a "fix" step you did not need.
 
-## Why reuse the agent (not a new smoke probe)
+## Why reuse the specialist agents (not a new smoke probe)
 
-`cbp-test-e2e-agent` is the declared sole owner of e2e: it auto-detects the platform, reconciles against the `tech_stack` DB record, configures the framework if missing, and classifies failures. A bespoke in-skill smoke check would duplicate that ownership and drift. The probe is a thin, opt-in caller of the existing agent.
+The `cbp-e2e-*` specialists are the declared framework owners of e2e: they configure the framework if missing, run preflight, and classify failures. A bespoke in-skill smoke check would duplicate that ownership and drift. The probe is a thin, opt-in caller of the matching existing agent (selected per `context/testing/e2e.md` dispatch contract).