codebyplan 1.5.0 → 1.8.0

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

@@ -0,0 +1,109 @@
+---
+scope: org-shared
+name: cbp-checkpoint-complete
+description: Complete a checkpoint after all tasks are done
+argument-hint: [checkpoint-number]
+effort: low
+---
+
+# Checkpoint Complete Command
+
+Finalize a checkpoint after all tasks are completed.
+
+## Instructions
+
+### Step 0.5: Parse `$ARGUMENTS`
+
+Parse the argument:
+
+| Shape | Regex | Resolves to |
+|-------|-------|-------------|
+| `{chk}` (e.g. `108`) | `^[0-9]+$` | Target CHK-{chk} |
+| _(empty)_ | — | Use MCP `get_current_task` to find the active checkpoint |
+
+Anything else is malformed — surface this error and stop:
+
+```
+checkpoint-complete: invalid argument `{value}`. Expected:
+  108    → CHK-108
+  (empty) → active checkpoint
+```
+
+#### Worked examples
+
+- `checkpoint-complete 108` → CHK-108
+- `checkpoint-complete` (no arg) → active checkpoint via `get_current_task`
+- `checkpoint-complete abc` → error: malformed
+- `checkpoint-complete 108-1` → error: malformed (that is task-start's shape)
+
+### Step 1: Get Active Checkpoint
+
+Given the parse from Step 0.5:
+
+| Parse | Resolution path |
+|-------|-----------------|
+| `{chk}` | MCP `get_checkpoints(repo_id)` → filter `number === {chk}` (must exist). |
+| _(empty)_ | MCP `get_current_task` with repo_id. Get the active checkpoint. If no active checkpoint, show error and stop. |
+
+### Step 2: Verify Checkpoint End Has Run
+
+Check `checkpoint.context.shipment` — must exist with at least `feat_to_dev.merged: true`.
+
+If not:
+```
+## Cannot Complete Checkpoint
+
+Checkpoint has not been shipped yet. Run `/cbp-checkpoint-end` first to merge feat branch to development.
+```
+Stop here.
+
+### Step 2.5: Verify All Tasks Complete
+
+Use MCP `get_tasks` for the checkpoint. Verify all tasks have status `completed`.
+
+If incomplete tasks remain:
+```
+## Cannot Complete Checkpoint
+
+CHK-[NNN] has [N] incomplete tasks:
+- TASK-[N]: [title] (status: [status])
+
+Complete remaining tasks first, then run `/cbp-checkpoint-complete`.
+```
+Stop here.
+
+### Step 3: Aggregate QA
+
+Collect QA results from all tasks and rounds. Build checkpoint-level QA summary:
+- Count auto checks passed/failed
+- List user QA items pending review
+
+If any critical failures, warn the user but don't block.
+
+### Step 4: Complete Checkpoint
+
+Use MCP `complete_checkpoint(checkpoint_id)`.
+
+This automatically:
+- Sets status to `completed`
+- Sets `completed_at` to now
+- Triggers auto-push to main if enabled
+
+### Step 5: Show Result and Route
+
+```
+## Checkpoint Completed
+
+**CHK-[NNN]**: [Title]
+**Tasks**: [N] completed
+**QA**: [summary]
+**Auto-push**: [result]
+```
+
+**Next**: Run `/clear`, then `/cbp-todo` to find the next checkpoint or standalone task.
+
+## Integration
+
+- **Triggered by**: `/cbp-checkpoint-end` (auto, after successful shipment)
+- **Reads**: MCP `get_current_task`, `get_tasks`, `get_rounds`
+- **Writes**: MCP `complete_checkpoint`

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

@@ -0,0 +1,287 @@
+---
+scope: org-shared
+name: cbp-checkpoint-create
+description: In-depth idea assessment, Q&A, and task creation
+argument-hint: [checkpoint description]
+effort: xhigh
+---
+
+# Checkpoint Create Command
+
+Runs INLINE (no subagent) - all context stays in session. Assesses the idea, runs research if needed, conducts exhaustive Q&A, builds context, and creates tasks as vertical slices.
+
+## Instructions
+
+### Step 1: Check for Existing Checkpoint Data
+
+Before asking the user anything, check if a checkpoint already exists with ideas/context:
+
+1. Use MCP `get_next_action` response context — if it includes a checkpoint, load it via MCP `get_checkpoints`
+2. If `$ARGUMENTS` contains a checkpoint number (e.g., `69` or `CHK-69`), load that checkpoint
+3. Check the checkpoint's `ideas` array and `context` fields
+
+**If checkpoint has `ideas[]` with descriptions/requirements:**
+- Use `ideas[].description` as the checkpoint description (DO NOT ask the user)
+- Use `ideas[].requirements` as the requirements list
+- Use existing `context` (decisions, discoveries, etc.) if populated
+- Skip Steps 1b and 2 if deadline already set
+- Proceed directly to Step 3 with this pre-loaded context
+
+**If checkpoint has NO ideas or is brand new:** Continue to Step 1b.
+
+### Step 1b: Get Checkpoint Description
+
+**If arguments provided:** Use `$ARGUMENTS` as `user_prompt`
+
+**If NO arguments:** Ask user via AskUserQuestion:
+```
+What should this checkpoint accomplish?
+Describe the work in a sentence or two.
+```
+
+**Data routing for ideas[]:**
+- `ideas[].description` = user's raw prompt (user-written, immutable after creation)
+- `ideas[].assessment` = Claude's structured analysis of this idea (Claude-updatable)
+- `context` = structured analysis output (decisions, constraints, discoveries)
+- Do NOT write Claude analysis into `user_context` — that field is for raw user text only
+
+### Step 2: Prompt for Deadline
+
+**Skip if checkpoint already has a deadline set.**
+
+Ask user via AskUserQuestion with options:
+- Today
+- Tomorrow
+- This week (Friday)
+- Custom date
+
+### Step 2.9: Semantic-Domain Module Dedup (BEFORE assessment)
+
+Run BEFORE Step 3 (Assess Idea) so the assessment factors in any existing module that might already cover the proposed feature. Cheaper to clarify intent at checkpoint creation than during planner Phase 1 Q&A.
+
+**Trigger**: the checkpoint description (or any `ideas[].description`) contains a feature verb in a user-facing semantic domain. Domain table — extend as new modules ship:
+
+| Domain | Trigger verbs / nouns | Glob target |
+|--------|----------------------|-------------|
+| Eating | eat, meal, food, recipe, ingredient, nutrition, kitchen | `apps/mobile/src/features/modules/food*/`, `apps/mobile/src/features/modules/eating*/` |
+| Sleeping | sleep, nap, bedtime, wake, dream, rest | `apps/mobile/src/features/modules/sleep*/` |
+| Fitness | workout, exercise, fitness, training, run, lift, rep | `apps/mobile/src/features/modules/fitness*/` |
+| Hobbies | hobby, leisure, craft, game | `apps/mobile/src/features/modules/hobb*/` |
+| Finance | money, expense, budget, transaction, pay, income | `apps/mobile/src/features/modules/finance*/`, `apps/mobile/src/features/modules/money*/` |
+| Mood | mood, emotion, feeling, journal, reflect | `apps/mobile/src/features/modules/mood*/` |
+| Social | friend, contact, message, share, social | `apps/mobile/src/features/modules/social*/` |
+| Reading | read, book, chapter, library | `apps/mobile/src/features/modules/reading*/` |
+| Self-care | selfcare, hygiene, skincare, wellness | `apps/mobile/src/features/modules/selfcare*/`, `apps/mobile/src/features/modules/hygiene*/` |
+| Pets | pet, dog, cat, animal | `apps/mobile/src/features/modules/pet*/` |
+| Work | work, job, task, productivity | `apps/mobile/src/features/modules/work*/` |
+
+**Procedure**:
+
+1. Tokenise the description into verbs/nouns. Match against the trigger column.
+2. For each matched domain, Glob the corresponding target. If the glob returns zero entries, no overlap — proceed.
+3. If the glob returns one or more existing modules, ask the user via AskUserQuestion (BEFORE running Step 3 codebase analysis):
+
+   > Found existing module(s) `{matched-paths}` which may already cover {domain} functionality.
+   >
+   > A) Extend the existing module — add the new feature inside `{primary-match}` rather than creating a new module
+   > B) Build a separate module — explain the distinction in 1-2 sentences (different user intent / different data shape)
+   > C) Unrelated — the new feature is in the same semantic neighbourhood but does not overlap functionally
+   > D) Cancel checkpoint creation — re-frame the description
+
+4. Save the answer as a locked decision in checkpoint context:
+   ```json
+   {
+     "decision": "Extend existing food module rather than create eating module",
+     "rationale": "User clarified meal-tracking lives alongside existing food/recipe data",
+     "locked": true
+   }
+   ```
+   Pass `locked: true` so planner Phase 2 honors it.
+
+5. If (B) "Build separate", record the user's distinction verbatim as the rationale — planner Phase 1 will use it to avoid duplicate scaffolding.
+
+**Why this fires here, not in planner Phase 1**: the planner's Q&A already catches duplicates (livebyplan TASK-4 caught "eating" → existing "food" via planner Q&A), but only after spawning Explore and reading codebase context — wasteful when the question is "is this even a new module?" Catching at checkpoint creation halves the round-1 surface area for duplicate-feature checkpoints.
+
+Skip this step when the description has zero domain matches OR when the user explicitly states intent in the prompt ("extend the existing food module to support meal sessions") with a referenced module path.
+
+### Step 3: Assess Idea (INLINE - no subagent)
+
+Analyze the idea thoroughly:
+
+1. **Discovery Level Detection:**
+   - Level 0: Simple change, no research needed
+   - Level 1: Minor research, check existing patterns
+   - Level 2: Moderate research, check docs/APIs
+   - Level 3: Deep research, unfamiliar territory
+
+2. **Codebase Analysis:** Use Glob/Grep/Read to understand:
+   - Related existing code
+   - Patterns to follow
+   - Dependencies affected
+   - Files that will need changes
+
+3. **Research (Level 2+ only):** Spawn a single `research` subagent for web research. Wait for results.
+   - Research findings MUST be stored in checkpoint.research JSONB via MCP `update_checkpoint` — NEVER write to local docs/ folder
+
+4. **Cross-Reference All Ideas:**
+   - When analyzing ideas[], iterate ALL items — not just the first
+   - Cross-reference requirements across all context items
+   - Identify overlaps, conflicts, and dependencies between ideas
+   - Store cross-reference results in checkpoint context (discoveries[], dependencies[])
+
+5. **Store Assessment Per Idea:**
+   - For each idea analyzed, write Claude's analysis into `ideas[N].assessment`
+   - Use MCP `update_checkpoint` with the full ideas array including assessment fields
+   - The assessment is Claude-written; the description remains the user's original text
+
+### Step 4: Exhaustive Q&A
+
+Ask the user targeted questions to fill gaps. Every answer gets saved immediately.
+
+**Build questions based on:**
+- Ambiguities in the description
+- Multiple valid approaches detected
+- UI/UX decisions needed
+- Scope boundaries unclear
+- Integration points uncertain
+
+Use AskUserQuestion for each question batch (max 4 per call). After each response, save to checkpoint context via MCP `update_checkpoint`:
+
+```json
+{
+  "context": {
+    "decisions": [{"decision": "...", "rationale": "...", "locked": true}],
+    "discoveries": [{"topic": "...", "finding": "..."}],
+    "dependencies": ["..."],
+    "constraints": ["..."],
+    "qa_answers": [{"question": "...", "answer": "..."}]
+  }
+}
+```
+
+Continue asking until all ambiguities resolved.
+
+### Step 5: Determine Next Checkpoint Number
+
+Use MCP `get_checkpoints` for the repo. Find highest checkpoint number, add 1.
+
+### Step 6: Create Checkpoint in DB
+
+**Before calling `create_checkpoint`**: resolve worktree_id via `npx codebyplan resolve-worktree 2>/dev/null`. If non-empty, pass as the `worktree_id` parameter so the checkpoint is born assigned to this worktree. (Per CHK-104 TASK-2 — DB-level hard-lock requires identifying the caller worktree at creation time.)
+
+**Why here specifically**: this is the first identity-stamping point for the checkpoint; if `worktree_id` is missing here, every downstream task and round inherits the gap and the hard-lock pre-guards have no caller identity to compare against. If empty, prompt the user to run `npx codebyplan setup` first from this directory to register the worktree before creating the checkpoint.
+
+Use MCP `create_checkpoint`:
+- `repo_id`: from .codebyplan/repo.json
+- `worktree_id`: from `npx codebyplan resolve-worktree 2>/dev/null` (omit param if empty — checkpoint is created with NULL worktree_id, unassigned)
+- `title`: derived from description
+- `number`: next number
+- `goal`: detailed goal from assessment
+- `deadline`: from Step 2
+- `status`: "pending"
+- `context`: accumulated from Q&A
+- `research`: from Step 3 (if any)
+
+### Step 6b: Generate Plan
+
+Based on the assessment and Q&A, generate a structured plan:
+
+1. Analyze ALL `ideas[]` items — every description and every requirement
+2. Create an ordered sequence of plan steps that covers everything
+3. Each step: `{ title: "What to build", description: "How and why", scope: "Which idea(s) it addresses" }`
+4. Ensure every idea description and every requirement is addressed by at least one step
+5. Cross-reference: if multiple ideas relate, consolidate into cohesive steps
+
+Save plan to checkpoint via MCP `update_checkpoint(checkpoint_id, plan: { steps: [...] })`.
+
+### Step 7: Create Tasks as Vertical Slices
+
+**Critical design principle:** Each task is a complete vertical slice that can be independently implemented and tested. Each task should produce a complete, production-ready deliverable.
+
+**BAD (horizontal layers):**
+- TASK-1: Create database functions
+- TASK-2: Create API routes
+- TASK-3: Create UI components
+
+**GOOD (vertical slices grouped by theme):**
+- TASK-1: Implement user authentication (DB + API + UI)
+- TASK-2: Implement user profile page (DB + API + UI)
+
+**GOOD (theme-based grouping for infrastructure):**
+- TASK-1: Config rule + remove Step 0 from all commands (one theme: eliminate redundant reads)
+- TASK-2: Task sizing + round workflow improvements (one theme: workflow optimization)
+
+**Sizing:** With 1M token context, tasks can be large. Group logically by theme — each task should encompass all work needed to deliver a complete feature or improvement. Only split a vertical slice when it covers genuinely independent themes, not because of size. A single task touching 30+ files is fine if they all serve one coherent purpose.
+
+For each task, use MCP `create_task`:
+- `checkpoint_id`: from Step 6
+- `title`: descriptive vertical slice title
+- `number`: sequential
+- `requirements`: detailed requirements
+- `context`: extracted relevant context from checkpoint
+
+### Step 8: Create Git Branch
+
+Check: `git branch -a | grep development`
+
+**If NO development branch (local or remote):**
+Create it from main:
+```bash
+git checkout main && git checkout -b development && git push -u origin development && echo "Created development branch from main"
+```
+
+**If development branch exists:**
+
+Detect worktree: `IS_WORKTREE=$(test -f "$(git rev-parse --show-toplevel)/.git" && echo "yes" || echo "no")`
+
+**(a) In a worktree:** Create feature branch from current branch:
+```bash
+git checkout -b feat/CHK-{NNN}-{slug}
+git push -u origin feat/CHK-{NNN}-{slug}
+```
+
+**(b) Not in a worktree:** Run:
+```bash
+git checkout -b feat/CHK-{NNN}-{slug}
+git push -u origin feat/CHK-{NNN}-{slug}
+```
+
+### Step 9: Assign Worktree
+
+Resolve `worktree_id` at runtime (CHK-108: never read from `.codebyplan/repo.json`):
+
+```bash
+WORKTREE_ID=$(npx codebyplan resolve-worktree 2>/dev/null)
+```
+
+If `WORKTREE_ID` is non-empty:
+```
+MCP update_checkpoint(checkpoint_id, worktree_id: WORKTREE_ID)
+```
+
+If empty (tuple unmatched): skip — Step 6 already passed `worktree_id` to `create_checkpoint`, so this re-stamp is only a defensive no-op.
+
+### Step 10: Show Result
+
+```
+## Checkpoint Created
+
+**ID**: CHK-[NNN]
+**Title**: [Title]
+**Deadline**: [date]
+**Discovery Level**: [0-3]
+**Tasks**: [N]
+
+### Tasks:
+1. TASK-1: [title]
+2. TASK-2: [title]
+...
+
+Run `/cbp-todo` to start working.
+```
+
+## Integration
+
+- **Runs inline**: All analysis in current session (no context loss)
+- **Spawns**: `research` agent (Level 2+ only, for web research)
+- **Saves to DB**: Context, research, QA answers via MCP

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

@@ -0,0 +1,241 @@
+---
+scope: org-shared
+name: cbp-checkpoint-end
+description: Single point for all shipment — branch promotion to main via /cbp-ship-main, runtime deploy via /cbp-ship, branch cleanup, summary. Standalone tasks bypass shipment entirely.
+effort: xhigh
+---
+
+# Checkpoint End Command
+
+Ship the checkpoint in three phases:
+1. **Branch promotion** — merge feat → main via `/cbp-ship-main` (which runs `codebyplan ship`)
+2. **Runtime deploy** — call `/cbp-ship` to deploy every configured surface (Vercel, EAS, npm, Tauri, Railway, Supabase migrations, VS Code marketplace)
+3. **Cleanup + summary** — stale feat branch removal, comprehensive shipment record
+
+Standalone tasks (per `task-start.md`) do NOT go through `/cbp-checkpoint-end` — only checkpoint-bound tasks ship.
+
+## When to Use
+
+- After `/cbp-checkpoint-check` confirms checkpoint is ready
+- Before `/cbp-checkpoint-complete`
+- Checkpoint CANNOT be completed without successful shipment
+
+## Instructions
+
+### Step 0: Sync with Main (mandatory)
+
+Before any shipment logic, ensure the feat branch is current against main. Shipment from a stale feat branch causes preventable PR-time conflicts and a noisy merge history.
+
+1. Trigger `/cbp-merge-main`.
+2. If the skill exits with failure (offline, unresolved conflicts, user-aborted): surface the failure and STOP `/cbp-checkpoint-end` — shipment is not safe until the branch is reconciled. The user resolves and re-invokes.
+3. On clean success: continue to Step 1.
+
+### Step 1: Get Active Checkpoint
+
+Use MCP `get_current_task` with repo_id. Get the active checkpoint.
+
+If no active checkpoint, show error and stop.
+
+### Step 2: Verify Checkpoint Check Passed
+
+Check `checkpoint.context.check_results` — must exist.
+
+If not: `Run /cbp-checkpoint-check first.`
+
+### Step 3: Read Branch Config
+
+Read `.codebyplan/git.json` and extract `branch_config` (handle missing file gracefully):
+
+```
+BASE = branch_config.base ?? branch_config.production ?? "main"
+PROTECTED = branch_config.protected (default: ["main"])
+```
+
+Read `.codebyplan/server.json` and extract `auto_push_enabled` (default: false).
+
+If `branch_config` is absent, use defaults above.
+
+### Step 4: Verify Branch Existence
+
+```bash
+git fetch origin
+```
+
+Check that the base branch exists remotely:
+
+| Branch | Required | If Missing |
+|--------|----------|------------|
+| BASE | Yes | **STOP** — cannot ship without production branch |
+
+### Step 5: Ship to Production
+
+If `auto_push_enabled` is true, run `/cbp-ship-main`.
+
+If false, inform user:
+```
+Auto-push is disabled. To ship to production, run `/cbp-ship-main` manually.
+```
+
+Wait for result. If `/cbp-ship-main` exits with failure (checks failed, PR conflicts, auth error), investigate and fix.
+
+If merge conflicts arise at PR time:
+1. Show the conflicts
+2. Suggest: run `/cbp-merge-main` on the feat branch to resolve conflicts (Step 0 should have caught this — if Step 0 was skipped or new conflicts appeared since, this re-runs the merge gate). NEVER rebase.
+3. **STOP** — wait for user to resolve
+
+### Step 6: Verify Merge Landed
+
+After `/cbp-ship-main` completes, verify the merge landed:
+
+```bash
+PR_DATA=$(gh pr view --json mergedAt,mergeCommit,statusCheckRollup)
+```
+
+Runtime deployment for the base branch is handled in Step 7 by `/cbp-ship` (which detects + verifies all surfaces uniformly). Do NOT do per-surface verification inline here — that duplicates `/cbp-ship` and skips uncovered surfaces.
+
+### Step 7: Runtime Shipment via `/cbp-ship`
+
+After branch promotion to main completes, invoke `/cbp-ship` to deploy every configured surface:
+
+- Vercel auto-deploy verification
+- Mobile shipment (asks user: skip / EAS internal TestFlight / EAS external TestFlight)
+- Tauri desktop release (if version bumped)
+- npm package publish (if version bumped — interactive 2FA)
+- VS Code extension publish (if version bumped)
+- Railway backend deploy
+- Supabase migration push (interactive review per migration)
+
+`/cbp-ship` handles its own confirmation + per-surface verification. Wait for it to complete before continuing.
+
+If `/cbp-ship` reports `aborted_at` (user aborted) or any surface failed verification, halt — do NOT proceed to cleanup. Surface the failure to the user; resolve, then re-run `/cbp-checkpoint-end`.
+
+If the repo has zero configured surfaces (very early-stage), `/cbp-ship` exits with `## No deployable surfaces configured` — that's a success state, continue to cleanup.
+
+### Step 8: Stale Feat Branch Cleanup
+
+After successful shipment, identify stale remote feat branches:
+
+```bash
+git branch -r --list 'origin/feat/*' | sed 's|origin/||'
+```
+
+For each feat branch (excluding current):
+- Check if associated checkpoint is completed (via MCP or branch name matching)
+- Check age: `git log -1 --format=%ci "origin/$BRANCH"`
+- Flag as stale if: checkpoint completed OR older than 30 days
+
+If stale branches found, present list to user via AskUserQuestion:
+```
+Found [N] stale feat branches:
+
+| Branch | Last Commit | Status |
+|--------|-------------|--------|
+| feat/CHK-XXX-... | YYYY-MM-DD | completed / >30 days old |
+
+Delete these branches? (both local and remote)
+Options:
+A) Delete all listed
+B) Delete specific ones (list numbers)
+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"
+```
+
+### Step 9: Current Feat Branch Cleanup
+
+Present comprehensive summary first (Step 10), then ask about current feat branch via AskUserQuestion:
+
+```
+The current feat branch [BRANCH] has been fully merged.
+
+Delete this branch? (both local and remote)
+A) Yes, delete
+B) No, keep it
+```
+
+**Never auto-delete.** Only delete with explicit user confirmation.
+
+If user confirms:
+```bash
+git checkout "$BASE"
+git branch -d "$FEAT_BRANCH"
+git push origin --delete "$FEAT_BRANCH"
+```
+
+### 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):
+
+```
+context.shipment: {
+  timestamp: [ISO],
+  branch_config: { base, protected },
+  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
+}
+```
+
+Present summary:
+
+```
+## Checkpoint Shipment Summary
+
+### Branch Promotion
+- **feat -> [BASE]**: [PR URL] (merged)
+
+### Runtime Surfaces (via /cbp-ship)
+| Surface | Variant | Status | URL/ID |
+| ... | ... | ... | ... |
+(Table populated from context.shipment.surfaces[])
+
+### Branch Operations
+- Stale branches deleted: [N] ([list])
+- Feat branch: [deleted/kept]
+
+### Before/After Branch State
+- Before: [list of feat/* branches]
+- After: [list of remaining feat/* branches]
+```
+
+Auto-trigger `/cbp-checkpoint-complete`.
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Merge fails (conflicts) | Keep feat branch, report failure, suggest resolution via feat branch |
+| Merge fails (CI/review) | Keep feat branch, report status, wait for user |
+| Vercel deployment fails | Keep feat branch, report status, do NOT proceed to cleanup |
+| Branch creation fails | Report error, suggest manual resolution |
+| gh CLI not authenticated | **STOP** — `Run: gh auth login` |
+
+**On any shipment failure:**
+1. Keep the feat branch intact
+2. Report which step failed and why
+3. Suggest resolution path
+4. Route to error recovery (user fixes, then re-runs `/cbp-checkpoint-end`)
+
+## Key Rules
+
+- **Never skip shipment errors** — investigate and fix
+- **PRs only** — never direct push to protected branches
+- **Checkpoint completion is blocked** until shipment succeeds
+- **All merges use `--merge`** — never squash or rebase
+- **Never auto-delete any branch** — always ask user first
+- **Protected branches are NEVER deleted** — read from `branch_config.protected`
+- **Read all branch names from config** — never hardcode
+
+## Integration
+
+- **Triggered by**: `/cbp-checkpoint-check` (auto, when ready)
+- **Reads**: MCP `get_current_task`, `.codebyplan/git.json` (`branch_config`), `.codebyplan/server.json` (`auto_push_enabled`), `.codebyplan/shipment.json` (`shipment`), git branches
+- **Writes**: MCP `update_checkpoint` (context.shipment — both branch promotion and runtime surface results)
+- **Calls**: `/cbp-merge-main` (Step 0, sync); `/cbp-ship-main` (Step 5, branch promotion to main); `/cbp-ship` (Step 7, runtime surface deploy + verification)
+- **Triggers**: `/cbp-checkpoint-complete` (auto, after successful shipment)