codebyplan 1.5.0 → 1.8.0

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

@@ -0,0 +1,187 @@
+---
+scope: org-shared
+name: cbp-session-end
+description: End a development session
+effort: xhigh
+---
+
+# Session End Command
+
+End the current session. Commits only non-task files — files tied to an unfinished task stay uncommitted so the user finishes them on their terms.
+
+## Instructions
+
+### Step 1: Finalize Session Log
+
+Always write a session log for this session — **even if empty**. `/cbp-session-start` opens the log; session-end finalizes it.
+
+1. Resolve the current session log:
+   - Preferred: use the log ID held in context from `/cbp-session-start`.
+   - Fallback: MCP `get_session_logs` (limit 1, most recent open log for this `repo_id`).
+   - If still none found (e.g. session-start was skipped), create one now with MCP `create_session_log`.
+2. Pull facts from the DB rather than narrating from memory:
+   - Rounds added/completed, tasks advanced/completed during this session
+   - Decisions, blockers, or discoveries recorded in checkpoint/task context
+
+### Step 1.3: Capture Handoff Snapshot
+
+Snapshot the current next-action so the next `/cbp-session-start` (Step 4.5) can auto-resume. Per `.claude/rules/session-resume.md` write-path contract.
+
+1. Call MCP `get_next_action({ repo_id, worktree_id })`.
+2. If the returned `command` is non-empty (active work in flight):
+   ```yaml
+   handoff:
+     command: <result.command> # e.g. "/cbp-round-update"
+     instructions: <result.instructions> # human-readable trigger reason
+     state: <result.state> # workflow state label
+     context: <result.context> # entity ids (checkpoint_id / task_id / round_id) used by freshness probe
+     captured_at: <ISO now> # for entity-drift freshness comparison
+     captured_session_log_id: <current session log id>
+   ```
+3. If `command` is empty / idle / queue-empty: set `handoff = null` so the next session's probe falls through to `/cbp-todo`.
+4. Hold `handoff` in context for Step 1's `update_session_log` call below — it ships in the same write as `ended_at` and `summary`.
+
+Continuing Step 1:
+
+3. Use MCP `update_session_log` to finalize:
+   - `ended_at`: now (maps to the `closed_at` column per TASK-2 alias)
+   - `handoff`: from Step 1.3 (jsonb or `null`; MCP write surface aliases to the `content` column transparently per CHK-111 Migration A — `handoff` wins over `content` when both are passed)
+   - `summary`: concise — may be empty if nothing happened
+   - `pending`: open items the next session should see first
+
+### Step 1.5: Commit Non-Task Files
+
+Same rule as `/cbp-session-start` Step 5.7 — only commit files that are **not** part of an unfinished task.
+
+1. `git status --porcelain` — list all modified/untracked files. If empty → skip this step.
+2. Resolve **task-related files** (leave these uncommitted):
+   - MCP `get_current_task(repo_id)` → active task
+   - If active task exists: MCP `get_rounds(task_id)`, filter to rounds with status not in `completed` / `cancelled`
+   - Collect `files[]` from those rounds → `task_files` set
+   - If no active task exists, `task_files` is empty
+3. `infra_files = changed_files − task_files`
+4. If `infra_files` is empty → skip. Otherwise present once:
+
+   ```
+   Commit these non-task files before ending session?
+   [list of infra_files]
+
+   Reply: yes | no | select
+   ```
+
+5. On `yes`: `git add` the listed files, then trigger `/cbp-git-commit`.
+   On `no`: skip. On `select`: ask which subset.
+
+Non-blocking — session end proceeds either way.
+
+### Step 1.7: Auto-Update CodeByPlan Assets
+
+Run the latest published CLIs to pull any asset or config changes. Sub-block A runs first, then Sub-block B. A failure in A does **not** skip B — each sub-block has its own retry-and-warn lane.
+
+**a) `codebyplan claude` (asset subcommand group)**
+
+Run the latest published CLI's asset-update verb to pull any skill / agent / hook changes:
+
+```
+npx codebyplan@latest claude update
+```
+
+Always run — do not skip, even when the current repo is the canonical-owner monorepo source.
+
+The command may pause for interactive prompts when:
+
+- a tracked file has been hand-edited locally (overwrite / skip / diff)
+- a new file is being shipped for the first time (opt-in / skip)
+- a file has been removed from the package (remove / keep)
+
+Respond to each prompt in the terminal as it appears. The commit prompt below runs only after all per-file prompts are resolved.
+
+Failure handling:
+
+- On non-zero exit: wait ~5 s, retry once.
+- If retry also fails: print a warning and continue — this step is non-blocking.
+
+After the command exits (success):
+
+1. Run `git status --porcelain -- .claude/` to detect any file changes.
+2. If non-empty, present once (same pattern as Step 1.5):
+
+   ```
+   .claude/ was updated. Commit these changes?
+   [list of changed paths under .claude/]
+
+   Reply: yes | no | select
+   ```
+
+   On `yes`: `git add` the listed paths only (not the whole `.claude/` directory), then trigger `/cbp-git-commit`.
+   On `no`: skip. On `select`: ask which subset.
+
+3. Print the final stdout line from the update command as a one-line session summary (e.g. `codebyplan claude update: 47 files tracked.`). Silent when the command produces no stdout.
+
+Non-blocking — session end proceeds regardless of outcome.
+
+**b) `codebyplan` (project CLI)**
+
+Fetch the latest published version of the project CLI. The `codebyplan` CLI has no `update` verb (subcommands are `setup`, `sync`, `eslint`); the freshness idiom is to invoke a fast read-only flag with `@latest` so npx fetches and caches the newest published version:
+
+```
+npx codebyplan@latest --version
+```
+
+Do **not** run `sync`, `setup`, or any other state-changing subcommand — this step updates the cached binary only.
+
+Failure handling:
+
+- On non-zero exit: wait ~5 s, retry once.
+- If retry also fails: print a warning and continue — this step is non-blocking.
+
+After the command exits (success):
+
+1. Run `git status --porcelain -- .codebyplan/` to detect any file changes.
+2. If non-empty, present once (same pattern as Step 1.5):
+
+   ```
+   .codebyplan/ was updated. Commit these changes?
+   [list of changed paths under .codebyplan/]
+
+   Reply: yes | no | select
+   ```
+
+   On `yes`: `git add` the listed paths only, then trigger `/cbp-git-commit`.
+   On `no`: skip. On `select`: ask which subset.
+
+3. Print the command's stdout (the version line) as a one-line session summary (e.g. `codebyplan 1.4.2`). Silent when the command produces no stdout.
+
+Non-blocking — session end proceeds regardless of outcome.
+
+### Step 2: Auto-Stop Servers
+
+**Skip if `server_type` is `"none"`.**
+
+1. Get `server_port` from `.codebyplan/server.json` context
+2. Check for running process: `lsof -ti:{PORT} 2>/dev/null`
+3. If process found, kill: `lsof -ti:{PORT} | xargs kill -9 2>/dev/null || true`
+
+Non-blocking — if kill fails, warn and continue. Silent when no process found.
+
+### Step 3: Update Session State
+
+Use MCP `update_session_state` with action `deactivate`.
+
+### Step 4: Output
+
+```
+Session ended. Log finalized.
+
+You can close this window.
+```
+
+## Integration
+
+- **Triggered by**: user invocation (prompted by `/cbp-todo` when no work remains)
+- **Reads**: `.codebyplan/repo.json`, MCP `get_session_logs` (resolve current log), MCP `get_current_task`, MCP `get_rounds`, MCP `get_next_action` (Step 1.3 handoff snapshot)
+- **Writes**: MCP `update_session_log` (with `ended_at` + `handoff` per TASK-2 alias surface; or `create_session_log` fallback), MCP `update_session_state` (deactivate)
+- **Spawns**: none
+- **Triggers**: none at the skill-contract level. Steps 1.5 and 1.7 may invoke `/cbp-git-commit` inline on user approval.
+- **Paired with**: `/cbp-session-start`
+- **Pairs with**: `.claude/rules/session-resume.md` (handoff payload shape + write-path contract)

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

@@ -0,0 +1,155 @@
+---
+scope: org-shared
+name: cbp-session-start
+description: Start a development session
+triggers: [cbp-todo]
+effort: low
+---
+
+# Session Start Command
+
+Activate the session, open a fresh session log, and surface the previous log's pending items so the user can pick up where they left off.
+
+## Instructions
+
+Do Steps 0–5 and Step 4.5 silently (no intermediate output). Step 5.7 may surface an approval gate. Produce ONE output block at Step 6, then auto-trigger `/cbp-todo`.
+
+### Step 0: MCP Health Check
+
+Call MCP `health_check` tool.
+
+- **If succeeds**: Continue silently
+- **If fails**: Show warning:
+
+  ```
+  ⚠ MCP connection failed. Check:
+  1. Network connectivity
+  2. API key validity (CODEBYPLAN_API_KEY env var)
+  3. codebyplan.com availability
+
+  Session continues but MCP-dependent features will be unavailable.
+  ```
+
+  Continue to Step 1 (non-blocking).
+
+### Step 1: Load Config
+
+Read per-concern config files from the project root. Single load point for the session:
+
+- `repo_id` (UUID) — from `.codebyplan/repo.json`, required for all MCP operations
+- `server_port`, `server_type`, `auto_push_enabled` — from `.codebyplan/server.json`
+- `git_branch` — from `.codebyplan/git.json`
+
+Resolve `worktree_id` at runtime (CHK-108: never read from `.codebyplan/repo.json`):
+
+```bash
+WORKTREE_ID=$(npx codebyplan resolve-worktree 2>/dev/null)
+```
+
+Pass `WORKTREE_ID` to MCP tools that support it. Empty output means the (device, path, branch) tuple is unregistered — see fallback note below.
+
+**If `worktree_id` resolves to empty** (the (device, path, branch) tuple does not match any registered worktree row): the session continues, but downstream MCP calls treat this caller as untagged — every hard-lock pre-guard sees a NULL `caller_worktree_id` and may reject mutations on assigned rows. Surface a one-line note in the Step 6 output instructing the user to run `npx codebyplan setup` from this directory to register the worktree.
+
+### Step 2: Check Dev Server
+
+**Skip if `server_type` is `"none"`.**
+
+1. Get `server_port` from `.codebyplan/server.json`
+2. Check if running: `lsof -ti:{PORT} 2>/dev/null`
+3. If running, verify health: `curl -s -o /dev/null -w "%{http_code}" http://localhost:{PORT}/ --max-time 2`
+4. If NOT running, note in output that user should start via desktop app
+
+### Step 3: Update Session State
+
+Use MCP `update_session_state` with action `activate`. This deactivates all other repos automatically.
+
+### Step 4: Read Last Session Log
+
+Call MCP `get_session_logs({ repo_id, worktree_id, limit: 1 })` — same inclusive-worktree call shape used by Step 4.5 below so the previous-session display and the handoff probe agree on which row is "most recent for this worktree". Take the first (and only) row.
+
+- If a previous log exists, hold its title/summary/pending items for the Step 6 output so the user sees where they left off.
+- If none exists (first session ever for this worktree), skip silently.
+
+### Step 5: Create This Session's Log
+
+Use MCP `create_session_log` to open a new session log for the current session. Create it **even if empty** — this establishes the record for session-end to finalize.
+
+Minimal seed content:
+
+- `started_at`: now
+- `repo_id` from config; `worktree_id` from `WORKTREE_ID` resolved in Step 1
+- `summary`: empty (session-end fills this in)
+
+Hold the new log's ID in context so `/cbp-session-end` can update the same record.
+
+### Step 4.5: Handoff Auto-Resume Probe
+
+Probe the most-recent closed session log for a structured handoff payload (per `.claude/rules/session-resume.md`) and auto-resume directly into the captured command when fresh. Additive — placed BEFORE the existing `/cbp-todo` auto-trigger; ALL failure paths fall through silently to Step 7.
+
+1. Reuse the row held from Step 4 (same `get_session_logs({ repo_id, worktree_id, limit: 1 })` call shape — no extra MCP round-trip).
+2. **Defensive gates** (any failure → silent fall-through to Step 7):
+   - No row returned → fall through.
+   - Row missing `closed_at` (orphan / still-open session) → fall through.
+   - `row.content` is `null` → no handoff captured at end-of-session → fall through.
+   - `row.content` exists but parse throws or shape mismatch (`command` field absent OR is an empty string) → fall through.
+3. **Freshness gate** — load the row as `handoff = row.content` (per CHK-111 Migration A column alias). Mark stale when ANY of:
+   - `(now - row.closed_at) > freshness_window_hours` (read from `.codebyplan/repo.json`, default 24 hours)
+   - Referenced entity in `handoff.context` has shifted. For each id present, run the matching MCP read and find the row whose `id` matches:
+     - `checkpoint_id` → `get_checkpoints({ repo_id })` → find entry where `entry.id === handoff.context.checkpoint_id`
+     - `task_id` → `get_tasks({ checkpoint_id })` if `handoff.context.checkpoint_id` is present, else `get_tasks({ repo_id, standalone: true })` → find entry where `entry.id === handoff.context.task_id`
+     - `round_id` → `get_rounds({ task_id: handoff.context.task_id })` → find entry where `entry.id === handoff.context.round_id`
+       Then compare `entry.updated_at > handoff.captured_at` → stale on any inequality.
+   - Entity lookup fails OR the matching `id` is not present in the returned array → stale (referenced entity gone or moved out of reach).
+4. **On stale OR any defensive gate hit**: fall through silently to Step 7 (existing `/cbp-todo` trigger).
+5. **On fresh hit**: trigger `handoff.command` directly with `handoff.context` / `handoff.state` in the trigger arguments. The downstream skill self-loads its full context — do NOT duplicate `/cbp-todo` Step 2's context-loading matrix here. Skip Step 5.7, Step 6 output, and Step 7.
+
+### Step 5.7: Commit Non-Task Files
+
+Clean the working tree of leftover infra before the session begins. Only commit files that are **not** part of an unfinished task.
+
+1. `git status --porcelain` — list all modified/untracked files. If empty → skip this step.
+2. Resolve **task-related files** (leave these uncommitted):
+   - MCP `get_current_task(repo_id)` → active task
+   - If active task exists: MCP `get_rounds(task_id)`, filter to rounds with status not in `completed` / `cancelled`
+   - Collect `files[]` from those rounds → `task_files` set
+   - If no active task exists, `task_files` is empty
+3. `infra_files = changed_files − task_files`
+4. **Re-run `git status --porcelain` immediately before showing the commit-prompt** (after Steps 0–5 have completed all MCP round-trips). Eliminates the race where prior-session staged files appear in the index only after MCP init's network round-trips complete. Recompute `infra_files` from the fresh listing.
+5. If `infra_files` is empty → skip. Otherwise present once:
+
+   ```
+   Commit these non-task files before starting session?
+   [list of infra_files]
+
+   Reply: yes | no | select
+   ```
+
+6. On `yes`: `git add` the listed files, then trigger `/cbp-git-commit` (it handles conventional message + commit).
+   On `no`: skip. On `select`: ask which subset.
+
+Non-blocking — session start proceeds either way.
+
+### Step 6: Output
+
+```
+Session active | Worktree: [worktree_id or "main"]
+
+Previous session: [title or "none"]
+  Pending: [pending items from previous log, or "—"]
+
+[⚠ Dev server not running — start via desktop app — only if applicable]
+```
+
+### Step 7: Auto-trigger Todo
+
+Trigger `/cbp-todo` to determine what to work on.
+
+## Integration
+
+- **Triggered by**: user invocation, `/clear` recovery
+- **Reads**: `.codebyplan/repo.json`, 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` / `get_tasks` / `get_rounds` for freshness probe (Step 4.5)
+- **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)
+- **Paired with**: `/cbp-session-end`
+- **Pairs with**: `.claude/rules/session-resume.md` (handoff payload shape + freshness gate contract)

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

@@ -0,0 +1,332 @@
+---
+scope: org-shared
+name: cbp-ship
+description: Orchestrate runtime deployment for a checkpoint — Vercel web, EAS mobile (Expo Go dev build / TestFlight preview), Tauri desktop, npm package publish, VS Code extension, Railway backend, Supabase migrations. Detects configured surfaces, walks the user through what to deploy, executes per-surface deploy steps, verifies each landed.
+effort: xhigh
+---
+
+# Ship Command
+
+Single orchestrator for deploying a checkpoint to every runtime it has — web (Vercel), mobile (EAS / TestFlight), desktop (Tauri), npm packages, VS Code extension, backend (Railway), database migrations (Supabase).
+
+Step 1 of `/cbp-checkpoint-end` handles branch promotion to main via `/cbp-ship-main` (which runs `codebyplan ship`). Runtime deployment happens here, after the branch is already merged.
+
+## When to Use
+
+- Auto-called by `/cbp-checkpoint-end` after branch promotion to main completes
+- User-invokable directly when re-running shipment after a fix (e.g., "Vercel deploy failed, fix the env var, re-run `/cbp-ship`")
+- NOT for mid-checkpoint dev iteration — local development uses `npx expo start` / `pnpm dev` etc., not this skill
+
+## Inputs
+
+| Source                        | What's read                                                                               |
+| ----------------------------- | ----------------------------------------------------------------------------------------- |
+| MCP `get_current_task`        | Active checkpoint (for context.shipment write-back)                                       |
+| `.codebyplan/git.json` + `.codebyplan/shipment.json`            | `branch_config`, `shipment` section if present (per `ship-configure`)      |
+| Repo scan                     | Detect surfaces from filesystem (vercel.json, eas.json, package.json publishConfig, etc.) |
+| `checkpoint.context.shipment` | Last shipment record (timestamp, surfaces, results)                                       |
+
+## Instructions
+
+### Step 1 — Detect applicable surfaces
+
+Run the detection script:
+
+```bash
+bash "${CLAUDE_SKILL_DIR}/scripts/detect-surfaces.sh"
+```
+
+It emits JSON of the form:
+
+```json
+{
+  "surfaces": [
+    {
+      "id": "vercel-web",
+      "app_path": "apps/web",
+      "configured": true,
+      "reason": "vercel.json + .vercel/project.json present"
+    },
+    {
+      "id": "expo-mobile",
+      "app_path": "apps/mobile",
+      "configured": false,
+      "reason": "app.json present but eas.json missing"
+    },
+    {
+      "id": "tauri-desktop",
+      "app_path": "apps/desktop",
+      "configured": true,
+      "reason": "src-tauri/ + .github/workflows/release-desktop.yml present"
+    },
+    {
+      "id": "npm-package",
+      "app_path": "packages/codebyplan-package",
+      "configured": true,
+      "reason": "publishConfig.access set"
+    },
+    {
+      "id": "vscode-ext",
+      "app_path": "apps/vscode",
+      "configured": false,
+      "reason": "package.json contributes block missing publisher"
+    },
+    {
+      "id": "railway-backend",
+      "app_path": "apps/backend",
+      "configured": false,
+      "reason": "Dockerfile missing + railway.toml absent"
+    },
+    {
+      "id": "supabase",
+      "migrations_pending": 4,
+      "configured": true,
+      "reason": "supabase/migrations/ has 4 entries newer than last shipment"
+    }
+  ]
+}
+```
+
+Each surface is one of: `configured: true` (ready to ship), `configured: false` (detected but missing setup), or absent from the array (not detected at all — e.g., a repo with no mobile app).
+
+Surface catalog reference: [reference/surfaces.md](reference/surfaces.md).
+
+### Step 2 — Handle gaps for early-stage repos
+
+For each surface with `configured: false`, present the gap to the user:
+
+```
+[surface-id] detected at [app_path] but not configured for shipment.
+Reason: [reason]
+
+Options:
+A) Configure now via /cbp-ship-configure --surface=[id]
+B) Skip this surface for this checkpoint
+C) Mark "not shipping yet" — record in .codebyplan/shipment.json `disabled[]` (no future prompts)
+```
+
+Use AskUserQuestion. Skip is the safe default for first-stage repos — a Next.js app that's never been Vercel-linked shouldn't block checkpoint shipment. Choice C writes `{"disabled":["vercel-web"]}` to `.codebyplan/shipment.json` so subsequent checkpoints don't re-ask.
+
+If ALL detected surfaces are unconfigured AND the user picks Skip/Mark for all, exit with `## No deployable surfaces configured. Branch promotion already completed; runtime deploy skipped.` Do NOT treat this as failure.
+
+### Step 3 — Build the shipment plan
+
+For each surface with `configured: true`, determine the deploy variant:
+
+| Surface           | Variants                                                                                                                                                                                               |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `vercel-web`      | `production` (when shipping to PRODUCTION branch — Vercel auto-deploys), `preview` (Vercel auto-creates per-PR), `manual` (force redeploy via `vercel --prod`)                                         |
+| `expo-mobile`     | `expo-go` (dev build via `npx expo start`, no shipment — informational only), `eas-internal` (EAS build + TestFlight internal group), `eas-external` (TestFlight external — review-gated, opt-in only) |
+| `tauri-desktop`   | `tag-and-release` (push `v*.*.*` tag, GH Actions builds + signs) — variant matters only when version bumped this checkpoint                                                                            |
+| `npm-package`     | `publish` (only when `package.json` version bumped or release-please PR merged this checkpoint)                                                                                                        |
+| `vscode-ext`      | `vsce-publish` (only when version bumped)                                                                                                                                                              |
+| `railway-backend` | `deploy` (Railway redeploys on integration push if linked; manual `railway up` otherwise)                                                                                                              |
+| `supabase`        | `push-migrations` (only when pending count > 0) — interactive, walks user through diff/review/push                                                                                                     |
+
+For mobile: ask the user via AskUserQuestion which variant for THIS checkpoint:
+
+```
+Mobile shipment for this checkpoint:
+A) Skip — local dev only this checkpoint
+B) EAS build + TestFlight internal (preview to internal testers)
+C) EAS build + TestFlight external (review-gated, public-facing beta)
+```
+
+For all other surfaces, default to the variant that matches the branch the checkpoint just shipped to (`production` for main, `preview` for staging/integration). Don't ask unless the inferred variant is ambiguous (e.g., mobile, or version-gated surfaces where no version bump happened).
+
+### Step 4 — Confirm the shipment plan
+
+Present the plan in one block, ask for confirmation:
+
+```
+## Shipment Plan — Checkpoint CHK-NNN [title]
+
+Will deploy:
+- vercel-web (apps/web)              → production (auto-deploy on main merge)
+- expo-mobile (apps/mobile)          → eas-internal (TestFlight internal group)
+- supabase                           → push 4 pending migrations (interactive review)
+
+Will skip:
+- tauri-desktop  → no version bump this checkpoint
+- npm-package    → no version bump this checkpoint
+- vscode-ext     → not configured (run /cbp-ship-configure when ready)
+
+Confirm shipment? [yes / change / abort]
+```
+
+Use AskUserQuestion. On `change`, re-enter Step 3 with prior answers as defaults. On `abort`, write `checkpoint.context.shipment.aborted_at` and stop — caller (`/cbp-checkpoint-end`) treats abort as "do not call `/cbp-checkpoint-complete`."
+
+### Step 5 — Execute per-surface deploys
+
+For each confirmed surface, load the surface reference file and execute its deploy procedure:
+
+| Surface           | Reference                                                          |
+| ----------------- | ------------------------------------------------------------------ |
+| `vercel-web`      | [reference/surface-vercel.md](reference/surface-vercel.md)         |
+| `expo-mobile`     | [reference/surface-expo-eas.md](reference/surface-expo-eas.md)     |
+| `tauri-desktop`   | [reference/surface-tauri.md](reference/surface-tauri.md)           |
+| `npm-package`     | [reference/surface-npm.md](reference/surface-npm.md)               |
+| `vscode-ext`      | [reference/surface-vscode-ext.md](reference/surface-vscode-ext.md) |
+| `railway-backend` | [reference/surface-railway.md](reference/surface-railway.md)       |
+| `supabase`        | [reference/surface-supabase.md](reference/surface-supabase.md)     |
+
+Each reference file has a `## STEPS` section the orchestrator follows literally. When a step needs user input (npm OTP, TestFlight credentials, Supabase migration approval), use AskUserQuestion inline — do NOT batch user input upfront, because a user may need to abort after seeing one surface's prompt.
+
+Run surfaces sequentially in the order: `supabase` → `vercel-web` → `railway-backend` → `expo-mobile` → `tauri-desktop` → `vscode-ext` → `npm-package`. Database migrations first (web/backend depend on schema). Mobile/desktop/extension/npm later (independent tails).
+
+If a surface fails:
+
+- Capture the error in `shipment_results[surface_id]`
+- Continue with subsequent surfaces (don't block the whole shipment on one failure)
+- Surface the failure in the final report with a clear remediation hint
+
+EXCEPTION: `supabase` migration push failure halts the rest. Schema mismatch downstream is worse than partial shipment.
+
+### Step 6 — Verify each surface landed
+
+After each surface deploys, run its verification:
+
+```bash
+bash "${CLAUDE_SKILL_DIR}/scripts/verify-vercel.sh" "$VERCEL_DEPLOYMENT_ID"
+bash "${CLAUDE_SKILL_DIR}/scripts/verify-expo-eas.sh" "$EAS_BUILD_ID"
+bash "${CLAUDE_SKILL_DIR}/scripts/verify-railway.sh" "$RAILWAY_PROJECT_ID"
+bash "${CLAUDE_SKILL_DIR}/scripts/verify-supabase.sh" "$MIGRATION_VERSION"
+```
+
+Verification timeouts are conservative (Vercel: 5min, EAS: 30min, TestFlight processing: 15min). On timeout, mark `verification_pending` (not failure) — the deploy may still complete async.
+
+### Step 7 — Persist shipment record
+
+Write to `checkpoint.context.shipment` via MCP `update_checkpoint`:
+
+```json
+{
+  "shipment": {
+    "timestamp": "2026-04-29T14:32:00Z",
+    "surfaces": [
+      {
+        "id": "vercel-web",
+        "variant": "production",
+        "status": "verified",
+        "url": "https://codebyplan.com",
+        "deployment_id": "dpl_xyz"
+      },
+      {
+        "id": "expo-mobile",
+        "variant": "eas-internal",
+        "status": "verified",
+        "build_id": "abc123",
+        "testflight_group": "internal"
+      },
+      {
+        "id": "supabase",
+        "variant": "push-migrations",
+        "status": "verified",
+        "migrations_applied": [
+          "0083_add_x",
+          "0084_index_y",
+          "0085_rls_z",
+          "0086_view_w"
+        ]
+      }
+    ],
+    "skipped": [
+      { "id": "tauri-desktop", "reason": "no version bump" },
+      { "id": "vscode-ext", "reason": "not configured" }
+    ],
+    "aborted_at": null
+  }
+}
+```
+
+### Step 8 — Report
+
+```
+## Shipment Complete — CHK-NNN
+
+| Surface | Variant | Status | URL/ID |
+|---|---|---|---|
+| vercel-web | production | ✓ verified | https://codebyplan.com (dpl_xyz) |
+| expo-mobile | eas-internal | ✓ verified | TestFlight build #42 |
+| supabase | push-migrations | ✓ verified | 4 migrations applied |
+| tauri-desktop | — | ⊘ skipped | no version bump |
+| vscode-ext | — | ⊘ skipped | not configured |
+
+All shipments succeeded. Returning control to /cbp-checkpoint-end.
+```
+
+If any surface failed, the report leads with the failures and offers re-run paths:
+
+```
+## Shipment Partial — CHK-NNN
+
+✓ vercel-web (production) → https://codebyplan.com
+✗ expo-mobile (eas-internal) → BUILD FAILED: missing APPLE_TEAM_ID
+  Fix: /cbp-ship-configure --surface=expo-mobile, then re-run /cbp-ship
+⊘ tauri-desktop → skipped (no version bump)
+
+Checkpoint shipment is incomplete. /cbp-checkpoint-end will hold; resolve and re-run.
+```
+
+## Shipment Manifest in `.codebyplan/shipment.json` (optional)
+
+Repos can override default detection by adding entries to `.codebyplan/shipment.json`:
+
+```json
+{
+  "disabled": ["vscode-ext"],
+  "surfaces": {
+    "vercel-web": { "project_id": "prj_abc", "team_id": "team_xyz" },
+    "railway-backend": {
+      "project_id": "rl_123",
+      "service_id": "svc_456",
+      "platform": "railway"
+    },
+    "expo-mobile": {
+      "eas_project_id": "ea_789",
+      "default_testflight_group": "internal"
+    },
+    "supabase": { "project_ref": "abcdefgh", "skip_seed": true }
+  }
+}
+```
+
+When present, this overrides scan results. `ship-configure` writes here.
+
+## Key Rules
+
+- **Branch promotion happens BEFORE this skill** — `/cbp-checkpoint-end` calls `/cbp-ship-main` first (which runs `codebyplan ship`); this skill handles runtime deployment only, never branch promotion
+- **Sequential, not parallel** — surfaces deploy in defined order; supabase first
+- **One verification per surface** — never claim shipment without running the verify script
+- **AskUserQuestion inline, not batched** — user can abort mid-shipment
+- **Skip ≠ fail** — unconfigured surfaces are normal for early-stage repos; never block on them
+- **No mid-checkpoint invocation for dev builds** — local dev uses `npx expo start` / `pnpm dev`; this skill is end-of-checkpoint only
+- **Credentials never live in `.claude/`** — Apple keys, npm tokens, supabase access tokens stay in CLI session / keychain / GH secrets; this skill checks they're reachable, never stores them
+- **Read all platform names from config** — never hardcode "production"/"main"/"development"
+
+## Error Recovery
+
+| Failure                       | Action                                                                      |
+| ----------------------------- | --------------------------------------------------------------------------- |
+| Vercel deploy timeout         | Mark `verification_pending`, continue — Vercel async-deploys                |
+| EAS build failed (credential) | Stop mobile surface, surface error, continue other surfaces                 |
+| Supabase migration error      | HALT shipment — schema mismatch is worse than partial deploy                |
+| npm publish 2FA reject        | Stop npm surface, ask user to re-run with fresh OTP                         |
+| Railway deploy failed         | Continue, mark failed — backend can be re-deployed independently            |
+| All surfaces failed           | Write `shipment.aborted_at`, return failure to `/cbp-checkpoint-end` |
+
+## Additional resources
+
+- Surface catalog: [reference/surfaces.md](reference/surfaces.md)
+- Versioning rules: [reference/versioning.md](reference/versioning.md)
+- Pre-flight checklist: [reference/preflight-checklist.md](reference/preflight-checklist.md)
+- Configure setup: `/cbp-ship-configure`
+- Detection script: [scripts/detect-surfaces.sh](scripts/detect-surfaces.sh)
+
+## Integration
+
+- **Triggered by**: `/cbp-checkpoint-end` (auto, after branch promotion to main via `/cbp-ship-main`); user direct invocation for re-runs
+- **Reads**: MCP `get_current_task`, `.codebyplan/git.json` + `.codebyplan/shipment.json` (`branch_config` + `shipment`), filesystem scan
+- **Writes**: MCP `update_checkpoint` (context.shipment)
+- **Calls**: per-surface deploy via reference files (vercel CLI, eas CLI, supabase CLI, npm, vsce, railway CLI, gh release)
+- **Triggers**: returns control to caller — does NOT auto-trigger `/cbp-checkpoint-complete` (that's the caller's job)