codebyplan 1.5.1 → 1.9.0

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

@@ -0,0 +1,239 @@
+---
+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.
+argument-hint: "[--force]"
+allowed-tools: Read, Edit, Bash(supabase *), Bash(jq *), Bash(mv *), Bash(date *), Bash(test *), Bash(which *)
+effort: xhigh
+---
+
+# Supabase Branching Setup
+
+Enable Supabase's GitHub branching integration so every pull request gets an isolated preview
+environment and the integration branch (`branch_config.integration`) gets a persistent
+Supabase project for shared staging.
+
+Invoke at any time. Already-completed steps are skipped via idempotency checks.
+Pass `--force` to re-run all steps regardless of marker state.
+
+## Arguments
+
+Inspect `$ARGUMENTS` for `--force`. If present, set `force_mode = true` and bypass every
+per-item idempotency check in Steps 2–5 (the marker is still re-written at Step 7).
+Absent: proceed with normal idempotency — already-done items report `already-done` and skip.
+
+## Step 1 — Verify Supabase is initialised locally
+
+```bash
+test -f supabase/config.toml && echo "ok" || echo "missing"
+test -d supabase/migrations && echo "ok" || echo "missing"
+```
+
+If either is missing: bail with this message and stop.
+
+```
+supabase/ not found in this repo. Run `supabase init` and `supabase link --project-ref <ref>`
+first, then re-invoke /cbp-supabase-setup.
+```
+
+## Step 2 — Read project_id and idempotency state
+
+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`:
+
+```bash
+jq '.branch_config.integration // empty' .codebyplan.json
+jq '.shipment.surfaces.supabase.branching_configured // empty' .codebyplan.json
+```
+
+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
+- `persistent_branch_created` — true if `[remotes.<integration>]` block already exists in
+  `supabase/config.toml`
+
+With `--force`, treat all as false and re-run.
+
+## Step 3 — Dashboard: enable GitHub integration (manual checklist)
+
+If `github_app_installed` is already true, print `already done — skipping` and continue to Step 4.
+
+Otherwise, display the checklist and AskUserQuestion for confirmation when done:
+
+```
+Dashboard checklist (do each step in the Supabase dashboard, then confirm):
+
+  1. Project Settings → Integrations → GitHub → Authorize GitHub
+  2. Select this repository from the dropdown
+  3. Set Supabase directory to: ./supabase
+  4. Enable: Automatic branching
+  5. Enable: Supabase changes only
+  6. Enable: Deploy to production
+  7. Click Save / Enable integration
+
+Full step-by-step: reference/branching-setup.md § 1
+```
+
+AskUserQuestion: "Confirm when the GitHub integration is saved in the Supabase dashboard."
+
+Set `github_app_installed = true` in the idempotency tracker (persisted at Step 7).
+
+## Step 4 — GitHub repo: required status check (manual checklist)
+
+Read `branch_config.integration` from `.codebyplan.json`. Determine branches to protect:
+
+- Always: `main`
+- Also: `branch_config.integration` (when set and !== 'main')
+
+If `required_check_enforced` is already true, print `already done — skipping` and continue.
+
+Otherwise, display the checklist for EACH branch and AskUserQuestion:
+
+```
+GitHub required-status-check setup (repeat for each branch listed):
+
+Branches to protect: main, <integration>
+
+For each branch:
+  1. GitHub → Repository → Settings → Branches → Add branch protection rule
+  2. Branch name: <branch-name>
+  3. Enable: Require status checks to pass before merging
+  4. Search for and select: "Supabase Preview"
+  5. Enable: Require branches to be up to date before merging
+  6. Save changes
+
+Full step-by-step: reference/branching-setup.md § 2
+```
+
+AskUserQuestion: "Confirm when the required-status-check rules are saved on GitHub."
+
+Set `required_check_enforced = true` in the idempotency tracker.
+
+## Step 5 — Persistent branch creation (CLI or manual)
+
+Skip this entire step if `branch_config.integration` is empty OR equals `main`.
+
+Skip if `persistent_branch_created` is already true.
+
+### 5a — Detect CLI
+
+```bash
+which supabase 2>/dev/null && supabase --version || echo "CLI_ABSENT"
+```
+
+If `CLI_ABSENT`, skip to manual path (Step 5c).
+
+### 5b — AskUserQuestion before creating the branch
+
+```
+A persistent Supabase branch will be created for: <integration>
+This creates a dedicated Supabase project environment for that branch.
+
+Proceed?
+```
+
+On confirm, run the commands below. **If the user declines, fall through to Step 5c
+(manual fallback) — do NOT skip Step 5 entirely.** The user may prefer the dashboard
+even when the CLI is available (e.g., they want to set custom branch options).
+
+```bash
+supabase --experimental branches create --persistent <integration>
+supabase --experimental branches list
+```
+
+Capture the `project_id` from the list output. See [reference/cli-fallback.md](reference/cli-fallback.md)
+for full parsing guidance.
+
+### 5c — Manual fallback (CLI absent or user prefers)
+
+Display manual dashboard steps. AskUserQuestion for the `project_id` once the user has
+created the branch and copied the ref from the dashboard.
+
+Full fallback walkthrough: [reference/cli-fallback.md](reference/cli-fallback.md)
+
+### 5d — Append `[remotes.<integration>]` block to `supabase/config.toml`
+
+```toml
+[remotes.<integration>]
+project_id = "<returned-project-id>"
+```
+
+Use Edit to append to `supabase/config.toml`. Do NOT overwrite existing content.
+
+## Step 6 — Optional: enable seed config
+
+**Skip this entire step if Step 5 was skipped** (`branch_config.integration` empty or
+`= 'main'`, OR `persistent_branch_created` was already true at Step 2 AND the existing
+`[remotes.<integration>]` block already declares its own `db.seed` policy). The seed
+sub-block is only meaningful when this run authored the `[remotes.<integration>]` parent
+above — otherwise opting in here writes a `[remotes.<integration>.db.seed]` block with
+no parent section and produces invalid TOML.
+
+Otherwise, AskUserQuestion:
+
+```
+Enable [remotes.<integration>.db.seed] in supabase/config.toml?
+
+When enabled, supabase db reset on the branch will run your seed SQL.
+Default: OFF — only enable if the team needs consistent seed data on integration resets.
+
+A) Yes — add seed config (enabled = true, sql_paths = ["./seed.sql"])
+B) No — leave seed disabled (default)
+```
+
+If A, append to `supabase/config.toml` under the `[remotes.<integration>]` block:
+
+```toml
+[remotes.<integration>.db.seed]
+enabled = true
+sql_paths = ["./seed.sql"]
+```
+
+Reference: [reference/branching-setup.md § 4](reference/branching-setup.md)
+
+## Step 7 — Write idempotency marker to `.codebyplan.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`:
+
+```bash
+NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+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
+```
+
+The three sub-fields:
+
+| Field | Value |
+|---|---|
+| `enabled_at` | ISO 8601 timestamp of this run |
+| `github_app_installed` | true — GitHub integration was authorized |
+| `required_check_enforced` | true — required-status-check confirmed on both branches |
+
+## Step 8 — Final status report
+
+Emit a per-item done vs already-done table:
+
+```
+## Supabase Branching Setup — Complete
+
+| Step | Status |
+|---|---|
+| GitHub integration (dashboard) | done / already-done |
+| Required status check (GitHub) | done / already-done |
+| Persistent branch (<integration>) | done / already-done / skipped (main) |
+| Seed config | enabled / disabled |
+| Idempotency marker written | done |
+
+Ready for /cbp-ship. Every PR will now get an isolated Supabase preview environment.
+```
+
+## Additional resources
+
+- Dashboard walkthrough + GitHub checklist: [reference/branching-setup.md](reference/branching-setup.md)
+- CLI detection + branch parsing + manual fallback: [reference/cli-fallback.md](reference/cli-fallback.md)

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

@@ -0,0 +1,121 @@
+# Supabase Branching Setup — Full Walkthrough
+
+Covers the GitHub integration dashboard steps, GitHub required-status-check configuration,
+and the persistent-branch creation that `/cbp-supabase-setup` automates.
+
+## 1. Dashboard: Enable GitHub Integration
+
+Navigate: **Project Settings → Integrations → GitHub**.
+
+Steps (one at a time — complete each before the next):
+
+1. Click **Authorize GitHub** and complete the OAuth flow.
+2. After redirect, select the repository from the dropdown.
+3. Set **Supabase directory** to `./supabase` (relative path from repo root).
+4. Enable **Automatic branching** — toggles preview environments per pull request.
+5. Enable **Supabase changes only** — previews only redeploy when `supabase/` files change,
+   not on every commit.
+6. Enable **Deploy to production** — migrations run against production project on merge to
+   the production branch (usually `main`).
+7. Click **Save** (or **Enable integration**).
+
+Verify: the integration tile now shows the connected repository name.
+
+## 2. GitHub Repo: Required Status Check
+
+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`
+`branch_config.integration`):
+
+1. **GitHub → Repository → Settings → Branches → Add branch protection rule**.
+2. Enter the branch name exactly.
+3. Enable **Require status checks to pass before merging**.
+4. In the status check search box, type **Supabase Preview** and select it.
+5. Enable **Require branches to be up to date before merging** (recommended).
+6. Click **Save changes**.
+
+> If `branch_config.integration === 'main'` or is unset, only add the rule once for `main`.
+
+## 3. Persistent Branch (integration branch only)
+
+A persistent branch creates a long-lived Supabase environment for the integration branch,
+separate from ephemeral PR previews. Only needed when `branch_config.integration` is set and
+differs from `main`.
+
+### Via CLI (preferred when available)
+
+```bash
+supabase --experimental branches create --persistent development
+# Replace 'development' with your actual integration branch name
+
+supabase --experimental branches list
+# Locate the row for 'development'; copy the project_id (8-char ref)
+```
+
+### Append to `supabase/config.toml`
+
+Use the `project_id` returned from `branches list`:
+
+```toml
+[remotes.development]
+project_id = "<returned-8-char-ref>"
+
+# Optional: enable seed on branch reset
+# [remotes.development.db.seed]
+# enabled = true
+# sql_paths = ["./seed.sql"]
+```
+
+Replace `development` with the actual integration branch name if different.
+
+### Manual fallback (when CLI unavailable)
+
+Navigate: **Supabase Dashboard → Project → Branches** (left sidebar).
+Click **Create branch** → enter branch name → select **Persistent** → confirm.
+Copy the project ref from the branch row and paste into `config.toml` as above.
+
+See [cli-fallback.md](cli-fallback.md) for full CLI detection and parsing steps.
+
+## 4. Optional: Seed Config
+
+When a seed file exists and should run on branch database reset:
+
+```toml
+[remotes.development.db.seed]
+enabled = true
+sql_paths = ["./seed.sql"]
+```
+
+Default is **OFF**. Enable only when the team needs consistent seed data on integration
+branch resets. Seed runs happen on `supabase db reset` against the branch — not on every
+migration push.
+
+## 5. Idempotency Marker
+
+After setup completes, `/cbp-supabase-setup` writes to `.codebyplan.json`:
+
+```json
+{
+  "shipment": {
+    "surfaces": {
+      "supabase": {
+        "branching_configured": {
+          "enabled_at": "2026-05-20T10:00:00Z",
+          "github_app_installed": true,
+          "required_check_enforced": true
+        }
+      }
+    }
+  }
+}
+```
+
+Fields:
+- `enabled_at` — ISO timestamp when setup completed
+- `github_app_installed` — true when the GitHub integration was authorized and saved
+- `required_check_enforced` — true when the user confirms the required-status-check rule
+  is in place on both branches
+
+On re-run, the skill reads this marker and skips any step already marked complete.

package/templates/skills/cbp-supabase-setup/reference/cli-fallback.md

@@ -0,0 +1,109 @@
+# CLI Detection and Fallback — Supabase Branching
+
+Used by `/cbp-supabase-setup` Step 5 when creating a persistent branch for the integration
+environment. Covers CLI detection, branch creation, project_id parsing, and the manual
+dashboard fallback when the CLI is unavailable.
+
+## 1. Detect CLI Availability
+
+```bash
+which supabase 2>/dev/null && supabase --version
+```
+
+- **Exit 0 + version line** → CLI available, proceed with CLI path below.
+- **Exit non-zero / no output** → CLI absent; show install hint and use Manual path.
+
+Install hint (if absent):
+```
+Supabase CLI not found. Install options:
+  brew install supabase/tap/supabase   (macOS / Homebrew)
+  npm install -g supabase              (npm global)
+  scoop install supabase               (Windows Scoop)
+  https://supabase.com/docs/guides/local-development/cli/getting-started
+```
+
+## 2. CLI Path — Create Persistent Branch
+
+```bash
+# Replace <integration> with branch_config.integration value (e.g., 'development')
+supabase --experimental branches create --persistent <integration>
+```
+
+Expected output (example):
+```
+Created branch: development
+  Branch ID: abc12345
+  Project ref: xyzwabcd
+```
+
+Then list to confirm and retrieve the project ref:
+
+```bash
+supabase --experimental branches list
+```
+
+Expected output (table form):
+```
+  ID          NAME          STATUS    CREATED AT
+  abc12345    development   active    2026-05-20T10:00:00Z
+              project_ref   xyzwabcd
+```
+
+### Parsing the project_id
+
+The `project_ref` / `project_id` value is the 8+ char identifier for the branch environment.
+Locate it in the `branches list` output:
+
+- **Table output**: look for the column labeled `project_ref` or the ref shown adjacent to the
+  branch name.
+- **JSON output** (if `--output json` is supported): `jq '.[].project_ref'`
+
+```bash
+# Attempt JSON parse; fall back to table scan
+supabase --experimental branches list --output json 2>/dev/null \
+  | jq -r '.[] | select(.name=="<integration>") | .project_ref' \
+  || echo "Parse table output manually — see column 'project_ref' or 'ID'"
+```
+
+Use the returned value as the `project_id` in `supabase/config.toml`.
+
+## 3. Append to `supabase/config.toml`
+
+After obtaining the `project_id`:
+
+```toml
+[remotes.<integration>]
+project_id = "<project_id_from_branches_list>"
+```
+
+Example for integration branch `development`:
+
+```toml
+[remotes.development]
+project_id = "xyzwabcd"
+```
+
+## 4. Manual Dashboard Fallback (no CLI)
+
+When the Supabase CLI is unavailable or `--experimental` branches are not yet enabled in
+the installed version:
+
+1. Open the Supabase Dashboard: **https://supabase.com/dashboard**
+2. Select the target project.
+3. In the left sidebar, click **Branches** (under the database section).
+4. Click **Create branch**.
+5. Enter the branch name exactly as it appears in `branch_config.integration`
+   (e.g., `development`).
+6. Select **Persistent** (not ephemeral/PR-scoped).
+7. Click **Create** and wait for provisioning.
+8. From the branch row in the list, copy the **Project ref** (8-char string).
+9. Paste into `supabase/config.toml` under `[remotes.<name>]` as shown in Section 3.
+
+## 5. Verify Branch is Live
+
+```bash
+supabase --experimental branches list
+# Expect the integration branch in the list with status 'active'
+
+# OR via dashboard: Branches section shows the branch with a green status indicator
+```

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

@@ -0,0 +1,166 @@
+---
+scope: org-shared
+name: cbp-task-check
+description: AI production review for the current task
+argument-hint: [chk-task | task]
+triggers: [cbp-task-testing, cbp-round-input]
+effort: high
+---
+
+# Task Check Command
+
+AI-driven production readiness review. Spawns the `cbp-task-check` agent for thorough verification including user satisfaction discussion. This command is a thin orchestrator — the agent does the heavy lifting.
+
+## Inline-Fallback for Spawn Failure
+
+If the `cbp-task-check` agent spawn fails for any reason (`API Error: Extra usage required`, monthly Agent usage cap, provider 5xx, rate limit, context overflow), the orchestrator MUST follow the canonical inline-fallback procedure documented in `skills/cbp-round-end/SKILL.md` "Inline-fallback for any spawn failure".
+
+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.
+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`.
+
+## When Used
+
+- After all rounds complete and all files approved (auto-triggered by `/cbp-round-update`)
+- Before `/cbp-task-testing`
+- `/cbp-task-check` is NEVER skippable
+
+## Instructions
+
+### Step 1: Parse `$ARGUMENTS`
+
+Parse the argument using the canonical chk-task-round notation (see `.claude/rules/notation-consistency.md`):
+
+| Shape | Regex | Resolves to |
+|-------|-------|-------------|
+| `{chk}-{task}` (e.g. `108-1`) | `^[0-9]+-[0-9]+$` | Checkpoint-bound: CHK-{chk} TASK-{task} |
+| `{task}` (e.g. `45`) | `^[0-9]+$` | Standalone: standalone TASK-{task} **only** |
+| _(empty)_ | — | Use MCP `get_current_task` to find the active in-progress task |
+
+Anything else is malformed — surface this error and stop:
+
+```
+task-check: invalid argument `{value}`. Expected:
+  108-1  → CHK-108 TASK-1 (checkpoint-bound)
+  45     → standalone TASK-45
+  (empty) → active in-progress task
+
+For a specific round, use `/cbp-round-update 108-1-2`.
+```
+
+Error cases: `108-1-2` (that is round-update's shape), `abc`, `108-`, `-1`, `108--1`, anything with whitespace or non-numeric characters.
+
+#### Worked examples
+
+- `task-check 108-1` → CHK-108 TASK-1
+- `task-check 45` → standalone TASK-45
+- `task-check` (no arg) → active in-progress task via `get_current_task`
+- `task-check 108-1-2` → error: "use `/cbp-round-update 108-1-2`"
+- `task-check abc` → error: malformed
+
+### Step 1.5: Get Current Task
+
+Given the parse from Step 1:
+
+| Parse | Resolution path |
+|-------|-----------------|
+| `{chk}-{task}` | MCP `get_checkpoints(repo_id)` → filter `number === {chk}`. MCP `get_tasks(checkpoint_id)` → filter `number === {task}`. |
+| `{task}` | MCP `get_tasks(repo_id, standalone: true)` → filter `number === {task}`. |
+| _(empty)_ | MCP `get_current_task(repo_id)` — finds the active in-progress task. |
+
+If no in-progress task, show error and stop.
+
+### Step 2: Quick Gate — Verify All Rounds Complete
+
+Use MCP `get_rounds` for the task. Verify all rounds are `completed`.
+
+If any rounds still in_progress:
+
+```
+## Cannot Run Task Check
+
+TASK-[N] has an active round (Round [N]). Complete it first:
+- Run `/cbp-round-update` to finish the round
+```
+
+Stop here.
+
+### Step 3: Load All Context
+
+1. Get checkpoint details (id, title, goal, context)
+2. Get task details (id, title, requirements, context, files_changed, qa)
+3. Get all rounds via MCP `get_rounds` (number, requirements, context, qa, files_changed)
+
+### Step 4: Spawn Task Check Agent
+
+Spawn `cbp-task-check` agent with full context:
+
+```yaml
+input:
+  task_number: [N]
+  round_number: [total rounds]
+  checkpoint: { id, title, goal, context }
+  task: { id, title, requirements, context, files_changed, qa }
+  rounds: [{ number, requirements, context, qa, files_changed }]
+```
+
+Wait for agent to complete. Agent handles all 10 phases including user satisfaction discussion.
+
+### Step 5: Save Agent Output
+
+Save agent output to task context via MCP `update_task`:
+
+- `task.context.check_verdict` = agent output (verdict, requirements_check, etc.)
+
+### Step 6: Route Based on Verdict
+
+**READY + satisfied:**
+
+**Next**: Run `/clear`, then `/cbp-task-testing {chk-task}` to run comprehensive task-level testing.
+
+**NOT READY — fixable issues:**
+
+```
+Issues found that need addressing:
+- [issue 1]
+- [issue 2]
+```
+
+Suggest: `/cbp-round-input` with specific issues. **STOP HERE** — wait for user.
+
+**NOT READY — needs new task:**
+
+```
+Scope issues identified that require a new task:
+- [scope issue]
+```
+
+Suggest: `/cbp-task-create`. **STOP HERE** — wait for user.
+
+**NOT READY — approvals missing:**
+
+```
+Code review passed but [N] files need user approval.
+```
+
+Suggest: Approve files, then re-run `/cbp-task-check`. **STOP HERE** — wait for user.
+
+## Key Rules
+
+- **`/cbp-task-check` is NEVER skippable** — mandatory before `/cbp-task-testing`
+- **This is AI review + user satisfaction** — not automated testing
+- **Read all changed files** — agent does the heavy lifting
+- **No file changes** — review only, never edit
+
+## Integration
+
+- **Reads**: MCP `get_current_task`, `get_rounds`, all changed files (via agent)
+- **Writes**: MCP `update_task` (context.check_verdict)
+- **Triggers**: emits directive `Next: /clear, then /cbp-task-testing {chk-task}` on READY + satisfied (cross-context — testing is heavyweight, fresh context helps)
+- **Triggered by**: `/cbp-round-update` (auto, when all files approved)