codebyplan 1.5.1 → 1.9.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,116 @@
+---
+scope: org-shared
+name: cbp-checkpoint-create
+description: Mechanical checkpoint creation — capture the user's description, infer title + goal, dedup against existing modules, create the checkpoint row + feat branch, then hand off to /cbp-checkpoint-plan for deep planning. Creates ZERO tasks.
+argument-hint: [checkpoint description]
+effort: high
+---
+
+# Checkpoint Create Command
+
+Runs INLINE. This is the **mechanical** stage only: capture raw user input, infer a title/goal, run a cheap module-overlap check, create the checkpoint row, create + switch to the feat branch, then auto-trigger `/cbp-checkpoint-plan`. It does **NOT** assess the idea, run research, conduct exhaustive Q&A, generate a plan, or create tasks — all of that is `/cbp-checkpoint-plan`'s job.
+
+## Pipeline
+
+```
+/cbp-checkpoint-create (mechanical, here) → /cbp-checkpoint-plan (deep planning + tasks) → /cbp-checkpoint-start (activate + claim)
+```
+
+## Instructions
+
+### Step 1: Check for Existing Checkpoint Data
+
+Source `repo_id` from `.codebyplan/repo.json`. If `$ARGUMENTS` contains a checkpoint number, or MCP `get_next_action` returns one, load it via MCP `get_checkpoints`. If the checkpoint already has `ideas[]` with descriptions, reuse `ideas[].description` (do not re-ask) and skip Step 2.
+
+### Step 2: Get Checkpoint Description
+
+**If `$ARGUMENTS` provided:** use it as the description. **Else** ask via AskUserQuestion: "What should this checkpoint accomplish? Describe the work in a sentence or two."
+
+Data routing: `ideas[].description` = the user's raw words (immutable; never overwrite). Do NOT write any Claude analysis into `user_context` — that field is raw user text only. Assessment, decisions, and discoveries are written later by `/cbp-checkpoint-plan`.
+
+### Step 3: Prompt for Deadline
+
+Skip if a deadline is already set. Else ask via AskUserQuestion: Today / Tomorrow / This week (Friday) / Custom date.
+
+### Step 4: Semantic-Domain Module Dedup
+
+Cheap module-overlap pre-flight — catching "is this even a new module?" here halves the planner's round-1 surface area for duplicate-feature checkpoints.
+
+**Trigger**: the description contains a feature verb/noun in a user-facing semantic domain:
+
+| 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**: tokenise the description; for each matched domain, Glob the target. Zero entries → proceed. One+ existing modules → ask via AskUserQuestion before continuing: (A) extend the existing module, (B) build a separate module — give the 1–2 sentence distinction, (C) unrelated, (D) cancel. Save the answer as a `locked: true` decision in `context.decisions[]` so `/cbp-checkpoint-plan` honors it.
+
+Skip when the description has zero domain matches OR the user already named a target module path.
+
+### Step 5: Infer Title + Goal
+
+Lightweight inference from the description — no deep analysis. **Title**: concise, ≤80 chars. **Goal**: ≤300 chars, a faithful restatement of intent (not a plan).
+
+### Step 6: Claim-or-Open Prompt
+
+Ask the user via AskUserQuestion whether to claim this checkpoint now:
+
+- **Claim for me + this worktree** (default) — resolve `npx codebyplan resolve-worktree 2>/dev/null` and set it as the checkpoint `worktree_id` at create. The creator carries momentum straight through plan → start.
+- **Leave it open** — create with `worktree_id` null so anyone free can claim it later via `/cbp-checkpoint-start`.
+
+Record the choice; it drives both the create call (Step 8) and the plan→start routing in `/cbp-checkpoint-plan`.
+
+### Step 7: Determine Next Checkpoint Number
+
+MCP `get_checkpoints` for the repo; highest `number` + 1.
+
+### Step 8: Create Checkpoint Row
+
+MCP `create_checkpoint`:
+- `repo_id` (from `.codebyplan/repo.json`), `number`, `title`, `goal`, `deadline`, `status: "pending"`
+- `ideas`: `[{ description: <raw user text> }]`
+- `worktree_id`: the resolved worktree from Step 6 **only if the user chose "claim"**; omit when "leave open"
+
+This is the first identity-stamping point — when claiming, passing `worktree_id` here engages the CHK-104 hard-lock from birth. No `context`, `research`, `plan`, or tasks are written here.
+
+### Step 9: Create + Switch to Feat Branch
+
+Read `.codebyplan/git.json` `branch_config.production` (default `"main"`) as `BASE`. codebyplan repos are main-only — never create or branch from a `development`/integration branch.
+
+```bash
+git fetch origin "$BASE" 2>/dev/null || true
+git checkout -b "feat/CHK-{NNN}-{slug}" "origin/$BASE" 2>/dev/null \
+  || git checkout -b "feat/CHK-{NNN}-{slug}" "$BASE"
+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.)
+
+### Step 10: Show Result + Auto-Trigger Plan
+
+```
+## Checkpoint Created
+
+**CHK-NNN**: [title]  •  **Deadline**: [date]  •  **Branch**: feat/CHK-NNN-slug
+**Claim**: [claimed by this worktree / left open]
+
+Now planning CHK-NNN… handing off to /cbp-checkpoint-plan.
+```
+
+Auto-trigger `/cbp-checkpoint-plan {NNN}` in the same context. This skill created ZERO tasks — the plan skill produces them.
+
+## Integration
+
+- **Runs inline**: mechanical setup only — no assessment, research, Q&A, plan, or tasks
+- **Reads**: MCP `get_next_action`, `get_checkpoints`; `.codebyplan/repo.json`, `.codebyplan/git.json`; `npx codebyplan resolve-worktree`
+- **Writes**: MCP `create_checkpoint` (description-only ideas + deadline + optional worktree_id), `update_checkpoint` (branch_name)
+- **Triggers**: `/cbp-checkpoint-plan` (auto)

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)

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

@@ -0,0 +1,137 @@
+---
+scope: org-shared
+name: cbp-checkpoint-plan
+description: Deep inline planning for a checkpoint — assess, gap-analyse, decide dependencies, compare alternatives, optionally e2e-probe a suspected-broken area, then create tasks as vertical slices. Runs after /cbp-checkpoint-create (mechanical) and before /cbp-checkpoint-start (activate + claim). Does NOT activate or claim.
+argument-hint: [checkpoint-number]
+effort: xhigh
+---
+
+# Checkpoint Plan Command
+
+Runs INLINE (no subagent) — all analysis and Q&A stay in the main session. This is the rigour stage that prevents half-baked plans: it discovers shortcomings, decides whether existing dependencies suffice or a new one is warranted, compares competing approaches, and only THEN creates tasks. It produces `plan.steps[]` + tasks but **never activates the checkpoint and never claims a user/worktree** — that is `/cbp-checkpoint-start`.
+
+## Pipeline
+
+```
+/cbp-checkpoint-create (mechanical) → /cbp-checkpoint-plan (deep planning, here) → /cbp-checkpoint-start (activate + claim)
+```
+
+Semantic-domain module dedup already ran in `/cbp-checkpoint-create` (its Step 4) — do NOT repeat it here. This skill assumes the checkpoint row, title, goal, branch, and any module-overlap decision already exist.
+
+## Instructions
+
+### Step 0: Parse `$ARGUMENTS`
+
+Source `repo_id` from `.codebyplan/repo.json` — every MCP call below that takes `repo_id` uses it.
+
+| Shape | Resolves to |
+|-------|-------------|
+| `{chk}` (e.g. `138`) | CHK-{chk} via MCP `get_checkpoints` filtered by `number` |
+| _(empty)_ | Active/pending checkpoint via MCP `get_current_task`; if none in progress, the most recent `pending` checkpoint that has no `plan.steps` |
+
+Malformed (non-numeric, contains `-`): surface `checkpoint-plan: invalid argument` and stop.
+
+### Step 1: Load Checkpoint + Existing Tasks
+
+1. Resolve the checkpoint (Step 0). Load `user_context`, `ideas[]`, `context` (decisions / discoveries / dependencies / constraints / qa_answers / alternatives), `research`, `plan`.
+2. MCP `get_tasks(checkpoint_id)` — load existing tasks. This sets the mode:
+   - **fresh** — zero tasks: full plan + create all tasks.
+   - **additive re-plan** — tasks exist: gap-analyse against them; only ADD new tasks or refine requirements for gaps. NEVER delete or overwrite an in-flight task.
+3. Note whether `worktree_id` is set (claimed at create) — drives routing in Step 11.
+
+### Step 2: Assess Ideas + Codebase
+
+Iterate ALL `ideas[]` (not just the first). For each:
+
+1. **Discovery level** — 0 (trivial) · 1 (check existing patterns) · 2 (read docs/APIs) · 3 (unfamiliar territory).
+2. **Codebase analysis** — Glob/Grep/Read the related code: existing patterns to follow, files that will change, integration points.
+3. **Research (level 2+ only)** — spawn a single `cbp-research` subagent for web/library research. Persist findings to `checkpoint.research` via MCP `update_checkpoint` — never to local docs. In additive re-plan mode, read the existing `research` (loaded in Step 1) and append — do not replace the object.
+4. **Cross-reference** ideas against each other: overlaps, conflicts, shared dependencies.
+
+Write each idea's analysis into `ideas[N].assessment` (Claude-authored; never touch `description`, which is the user's words).
+
+### Step 3: Gap Analysis
+
+Find what the raw request misses — this is the core anti-"half-ass" step. Load `reference/gap-analysis-playbook.md` and run its two passes:
+
+- **Pass 1 (in-scope gaps)** — shortcomings, half-implemented patterns, and missing foundations WITHIN the stated scope. Record each as a `context.discoveries[]` entry.
+- **Pass 2 (adjacent findings)** — problems in the same neighbourhood but outside the literal request. Per locked policy, adjacent findings are **pulled INTO this checkpoint** as additional plan steps / tasks (scope absorption) rather than deferred — unless the user explicitly scopes them out in Step 7, or absorbing them would push the checkpoint past its deadline (surface in Step 7 for confirmation before absorbing).
+
+### Step 4: E2E Discovery Probe (opt-in)
+
+Only relevant when an idea touches a UI surface AND you SUSPECT an existing flow is already broken. Load `reference/e2e-discovery-probe.md`.
+
+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).
+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.
+
+### Step 5: Dependency Decisions
+
+When an idea could be built by extending something already installed OR by adding a new dependency, do NOT silently pick one. Load `reference/dep-decision-rubric.md` and:
+
+1. Identify the capability needed and whether an existing dependency already covers it.
+2. If a new dependency is a candidate, surface the trade-off (capability gap, bundle weight, maintenance, vendor-docs availability) — via AskUserQuestion when the choice is consequential.
+3. Lock the outcome as a `context.decisions[]` entry with `locked: true` and a rationale.
+
+### Step 6: Alternative Comparison
+
+When more than one viable approach exists for a meaningful design fork, present the alternatives before committing. Load `reference/alternative-comparison-template.md`:
+
+1. Build 2–4 options with a one-line trade-off each; mark a recommendation.
+2. Ask via AskUserQuestion (use `preview` for code/layout comparisons).
+3. Save the comparison + the user's choice to `context.alternatives[]` and mirror the chosen path as a `context.decisions[]` entry.
+
+### Step 7: Exhaustive Q&A
+
+Resolve every remaining ambiguity. Ask via AskUserQuestion (max 4 per batch). After each batch, append to `context.qa_answers[]`. Continue until nothing material is unresolved — including confirming the scope-absorption candidates from Step 3 Pass 2 (keep / drop each).
+
+### Step 8: Generate or Extend `plan.steps[]`
+
+Build an ordered `plan.steps[]` where each step is `{ title, description, scope }` (`scope` = which idea/requirement it addresses). Every `ideas[].requirements` item AND every kept gap finding must be covered by ≥1 step. In additive mode, append/refine steps — do not drop steps that map to existing tasks. Save via MCP `update_checkpoint(checkpoint_id, plan: { steps: [...] })` — `plan` is a top-level checkpoint field, so this write does not touch `context` or `research`; the context-replaces rule in Step 10 applies only to the `context` JSONB.
+
+### Step 9: Create Tasks as Vertical Slices
+
+Each task is a complete, independently shippable vertical slice — group by theme, not by layer.
+
+**BAD (horizontal layers):** TASK-1 DB functions · TASK-2 API routes · TASK-3 UI.
+**GOOD (vertical slices):** TASK-1 user auth (DB + API + UI) · TASK-2 profile page (DB + API + UI).
+**GOOD (infra by theme):** TASK-1 config rule + Step-0 removal · TASK-2 task-sizing + round-workflow.
+
+Sizing: with a 1M-token context, tasks can be large — group by coherent purpose; a single task touching 30+ files is fine if they serve one theme. Only split when themes are genuinely independent.
+
+For each task use MCP `create_task` (`checkpoint_id`, sequential `number` after the current max, `title`, `requirements`, `context` with the relevant decisions/discoveries). **Additive mode:** create only tasks for steps not already covered by an existing task; never delete in-flight tasks. **Coverage check** — a plan step counts as covered only when an existing task's requirements address its full scope; when uncertain, create the task and note in its requirements `may overlap with TASK-N — review before executing`.
+
+### Step 10: Persist Full Context
+
+Final write of the complete `checkpoint.context` JSONB via MCP `update_checkpoint`. Honor the **context-replaces-not-merges** contract: read the current context, merge your additions in memory, write the FULL object (`decisions` + `discoveries` + `dependencies` + `constraints` + `qa_answers` + `alternatives`). A partial write clobbers sibling keys. Phrase any database-verb words as prose in payloads (WAF gate).
+
+### Step 11: Show Result + Route
+
+```
+## Checkpoint Planned
+
+**CHK-NNN**: [title]
+**Tasks**: [created N] (additive: [+M new])  •  **Plan steps**: [count]
+**Locked decisions**: [count]  •  **E2E probe**: [fired / skipped]
+
+### Tasks
+1. TASK-1: [title]
+...
+```
+
+This skill does **NOT** activate the checkpoint and does **NOT** claim a user/worktree.
+
+- **Claimed by THIS session** — `worktree_id` is set AND equals `npx codebyplan resolve-worktree 2>/dev/null`: auto-trigger `/cbp-checkpoint-start` in the same context (the creator carries momentum into activation).
+- **Otherwise** — `worktree_id` is null, set to a different worktree, or `resolve-worktree` is empty: surface a single directive — `Next: /cbp-checkpoint-start` — so the owning session (or anyone free, if open) claims and starts it. Never auto-activate a checkpoint owned by a different worktree.
+
+## Integration
+
+- **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`)
+- **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/alternative-comparison-template.md

@@ -0,0 +1,54 @@
+---
+scope: org-shared
+---
+
+# Alternative Comparison Template
+
+Loaded by `/cbp-checkpoint-plan` Step 6. Use when a meaningful design fork has more than one viable answer. Surfacing the alternatives — instead of silently picking one — is what lets the user redirect before tasks are created.
+
+## When a fork warrants a question
+
+Ask the user when ALL of these hold:
+
+- There are 2–4 genuinely viable options (not one obvious winner).
+- The choice is hard to reverse later (architecture, data shape, public API, a one-way dependency).
+- The options have materially different trade-offs the user would care about.
+
+Resolve inline (record a decision, no question) when the choice is reversible, low-stakes, or has a single defensible answer.
+
+## How to present
+
+Use AskUserQuestion. Lead with your recommendation as the first option and tag it `(Recommended)`. Give each option a one-line trade-off. For code/layout/config forks, use the `preview` field to show concrete snippets side by side.
+
+```
+Question: "How should X be structured?"
+Options:
+  - "Approach A (Recommended)" — <one-line trade-off>
+  - "Approach B"               — <one-line trade-off>
+  - "Approach C"               — <one-line trade-off>
+```
+
+## Record format
+
+Persist to `context.alternatives[]` (a JSONB key introduced by this skill — schema-flexible; declare it as below). Read-merge-write the full context per Step 10.
+
+```json
+{
+  "question": "How should X be structured?",
+  "options": [
+    { "label": "Approach A", "tradeoff": "...", "recommended": true },
+    { "label": "Approach B", "tradeoff": "..." }
+  ],
+  "chosen": "Approach A",
+  "rationale": "user picked A because ...",
+  "decided_at": "2026-06-01T..."
+}
+```
+
+Mirror the chosen path as a `context.decisions[]` entry with `locked: true` so the executor treats it as settled and the planner does not re-ask on a re-run.
+
+## Notes
+
+- One question per fork; do not bundle unrelated forks into one multi-select.
+- If the user picks "Other" and writes a custom answer, record their text verbatim as the rationale.
+- Keep the options mutually exclusive — overlapping options produce ambiguous decisions.