codebyplan 1.13.52 → 1.13.54

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

@@ -0,0 +1,344 @@
+---
+name: cbp-round-plan
+description: Plan a round — round-1 planning AND round-2+ deep-analysis of unapproved work, then spawn cbp-round-planner and auto-trigger /cbp-round-build
+triggers: [cbp-round-build]
+argument-hint: [chk-task-round | task-round | requirements-text]  # e.g. `108-1-2`, `45-2`, or free-text
+effort: xhigh
+---
+
+## Kind Detection
+
+Inspect the resolved identifier from argument parsing to determine the task kind:
+
+| Identifier shape | KIND |
+|-----------------|------|
+| `{task}-{round}` (2-segment, e.g. `45-2`) | `standalone` |
+| `{chk}-{task}-{round}` (3-segment, e.g. `141-3-1`) | `checkpoint` |
+| _(empty / free-text)_ | Check `get_current_standalone_task` first; if found → `standalone`. Else → `checkpoint` via `get_current_task`. |
+
+Set `KIND` for the rest of this skill. Read/write sources vary by KIND:
+
+| Operation | `checkpoint` KIND | `standalone` KIND |
+|-----------|------------------|-------------------|
+| Get task | local state (break-glass: `get_current_task`) | `get_current_standalone_task(repo_id)` |
+| Get rounds | local state (break-glass: `get_rounds`) | `get_standalone_rounds(standalone_task_id)` |
+| Add round | `codebyplan round add` (break-glass: `add_round`) | `add_standalone_round(standalone_task_id, ...)` |
+| Update round | `codebyplan round update` (break-glass: `update_round`) | `update_standalone_round(standalone_round_id, ...)` |
+| Complete round | `complete_round(round_id, duration_minutes?)` | `complete_standalone_round(standalone_round_id, duration_minutes?, caller_worktree_id)` ⚠️ `caller_worktree_id` is REQUIRED for standalone |
+| Update task | `codebyplan task update` (break-glass: `update_task`) | `update_standalone_task(standalone_task_id, ...)` |
+
+> **Note**: The `standalone` KIND column uses MCP tools unchanged — standalone local-first migration is out of scope and will be addressed in a later task.
+
+# Round Plan Command
+
+The single **planning entry** for the round cycle. It plans BOTH the first round (from `task.requirements`) AND every follow-up round (deep analysis of the prior round's unapproved work, verify gate/proof failures, and reviewer findings — the round-input deep-analysis role is now folded in here). It analyzes context, spawns `cbp-round-planner` for the plan, then auto-triggers `/cbp-round-build` — the `ask`-tier permission prompt on that skill IS the user's plan approval. NO execution or testing here — those belong to `/cbp-round-build` and `/cbp-verify`.
+
+## Planner Spawn Failure Is A Gate Failure
+
+If the `cbp-round-planner` agent spawn fails (`API Error: Extra usage required`, monthly Agent
+usage cap, provider 5xx, rate limit, context overflow at spawn, the agent dying before emitting
+its output contract), that is a **HARD GATE FAILURE** per `rules/spawn-failure-is-gate-failure.md`.
+The orchestrator does **NOT** walk the planner's phases inline and self-certify a plan — doing so
+re-introduces the exact fresh-context blind spot the planner exists to remove. STOP and surface the
+retry directive verbatim:
+
+```
+## Plan blocked — planner could not spawn
+
+The round planner (cbp-round-planner) failed to spawn: <class> — <verbatim error>.
+This is a hard gate failure, not a plan. Retry when capacity returns:
+  Next: /cbp-round-plan
+```
+
+Record `round.context.planner_findings.spawn_failure = { class, error_message, decided_at }` so the
+retry is auditable. Do NOT continue to Step 8/9; no plan means no execution.
+
+## Pipeline
+
+```
+/cbp-round-plan (planning) → /cbp-round-build (ask-tier permission = plan approval)
+```
+
+**Auto-loop mode**: when `auto_loop_mode === true` carries forward from the prior round, the Step 6
+Q&A and the Step 4b mode prompt are skipped, and Step 8's `/cbp-round-build` permission is
+auto-approved. See `cbp-verify` reference `round-scope.md` Phase 5 (the auto-loop decision that
+carries `auto_loop_mode` forward) for the contract.
+
+## Instructions
+
+### Step 0: Parse `$ARGUMENTS` shape
+
+Disambiguate the argument up front. Three input shapes:
+
+### CHK / TASK / ROUND Identifier Notation Vocabulary
+
+| Shape | Regex | Meaning |
+|-------|-------|---------|
+| `{chk}-{task}-{round}` (e.g. `108-1-2`) | `^[0-9]+-[0-9]+-[0-9]+$` | **Identifier**: targets round {round} of CHK-{chk} TASK-{task}. Sets `target_checkpoint`, `target_task`, `target_round`. |
+| `{task}-{round}` (e.g. `45-2`) | `^[0-9]+-[0-9]+$` | **Identifier**: targets round {round} of standalone TASK-{task}. Sets `target_task`, `target_round` (no checkpoint). |
+| Non-empty, non-identifier-shaped | — | **Free-text round requirements** (the follow-up-round requirements path). |
+| _(empty)_ | — | No identifier, no requirements text — derive task/round from Kind Detection above. |
+
+Malformed identifier shapes (`108-`, `-1-2`, `108--1`, `abc-1`) — surface this error and stop, mirroring `/cbp-task-start`'s error vocabulary:
+
+```
+round-plan: invalid argument `{value}`. Expected:
+  108-1-2  → round 2 of CHK-108 TASK-1
+  45-2     → round 2 of standalone TASK-45
+  (free-text) → round requirements (follow-up round)
+  (empty)  → derive from active task/round state
+```
+
+#### Worked examples
+
+- `round-plan 108-1-2` → resolve CHK-108 TASK-1, target round 2
+- `round-plan 45-2` → resolve standalone TASK-45, target round 2
+- `round-plan 108-1` → **standalone TASK-108 round 1** (NOT CHK-108 TASK-1). The 2-segment form means `{task}-{round}`; checkpoint-bound round-targeting requires all three numbers (`108-1-2`). If you got here trying to target CHK-108 TASK-1, you want `108-1-2` (specifying a round number) or `/cbp-task-start 108-1` (specifying just a task).
+- `round-plan "Implement OAuth flow per CHK-X plan"` → free-text path; current-task/round derivation from state
+- `round-plan` (empty) → derive from Kind Detection; round 1 uses `task.requirements`
+- `round-plan 108-` → error: malformed identifier
+- `round-plan -1-2` → error: malformed identifier
+- `round-plan abc-1` → error: malformed identifier
+
+> **Mental-model warning**: `task-start` and `round-plan` interpret the SAME `108-1` argument differently. `task-start 108-1` → CHK-108 TASK-1 (checkpoint-bound task). `round-plan 108-1` → standalone TASK-108 round 1 (because round-plan needs three numbers for a checkpoint-bound round). When in doubt, write all three: `round-plan 108-1-2`.
+
+### Step 1: Get Current Task
+
+If Step 0 produced an identifier (`target_task` set): resolve directly per the identifier (bound or standalone) — use KIND-appropriate sources per the Kind Detection table above.
+
+Otherwise: use Kind Detection to determine KIND, then:
+- **checkpoint KIND**: read `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>.json` (local-first). If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_current_task` when the state dir is absent and sync fails (daemon-dead + CLI-unavailable).
+- **standalone KIND**: MCP `get_current_standalone_task(repo_id)` — standalone tools are NOT migrated; standalone KIND still uses MCP until a later task.
+
+If no in-progress task and Step 0 produced no identifier, show error: `No active task. Run /cbp-task-start first.`
+
+### Step 2: Determine Round Number
+
+If Step 0 produced `target_round`: use that as the round number directly (may target an existing round for resume, or N+1 for a new round — disambiguate by reading local round files or MCP per KIND below).
+
+Otherwise:
+- **checkpoint KIND**: list `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>/rounds/` (local-first). If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_rounds` when the state dir is absent and sync fails.
+- **standalone KIND**: MCP `get_standalone_rounds(standalone_task_id)` — standalone still uses MCP.
+
+Count existing rounds; next is N+1. **Round 1** → run the Step 3 first-round path. **Round 2+** → run the Step 3D deep-analysis path (the folded-in round-input deep-analysis role) before creating the round.
+
+### Step 3: Gather Round Requirements
+
+**If Step 0 parsed an identifier**: this skill was invoked to resume/start a specific round. Requirements come from existing round data (when the round exists) or task.requirements (for new round 1) — `$ARGUMENTS` is the identifier itself, NOT requirements text.
+
+**Else (free-text path), if round number is 1:**
+
+- Use `task.requirements` as the primary requirements
+- If `$ARGUMENTS` provided (free-text), merge as additional context
+
+**Else (round number > 1):** requirements come from the Step 3D Deep Analysis below — the prior round's unapproved work, verify gate/proof failures, and reviewer findings. Free-text `$ARGUMENTS` (if provided) is merged in as additional direction.
+
+### Step 3D: Deep Analysis (round 2+ only — MANDATORY)
+
+Follow-up rounds get the SAME depth as round 1. This is the deep-analysis role that round-input
+formerly owned; it now runs inline here for every round after the first.
+
+**3D-a:** Load task (already loaded in Step 1) — confirm `files_changed`, `requirements`, `context`, `qa` are present.
+
+**3D-b:** Load all rounds:
+- **checkpoint KIND** — Read `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>/rounds/*.json` (local-first; break-glass: MCP `get_rounds(task_id)`). Get previous round context + verify outcome.
+- **standalone KIND** — MCP `get_standalone_rounds(standalone_task_id)`.
+
+**3D-c:** Identify unapproved files from `task.files_changed` where `user_approved === false`.
+
+**3D-d:** Read the content of each unapproved file (Read tool, max 5 files, first 100 lines each).
+
+**3D-e:** Cross-reference with task requirements — for each requirement, is it met or missed?
+
+**3D-f:** Extract verify findings from the latest round context. `/cbp-verify` writes its outcome
+into the round/task context (`verify_manifest`, gate `new_failures[]`, execution-proof gaps, and any
+blocking `cbp-verify-reviewer` findings it could not auto-apply inline because they reference files
+outside the prior round's `files_changed[]`). Include those out-of-scope findings as high-priority
+requirements; deterministic gate failures and proof gaps come first (they block shipping).
+
+**3D-g:** Identify root causes — not "file X is wrong" but "requirement Y was not met because Z".
+
+**3D-h:** Present the analysis to the user:
+
+```
+## Follow-up Round Analysis
+
+### Unapproved Files ([N])
+| File | Action | Issue |
+|------|--------|-------|
+| path | modified | [what's wrong based on reading the file] |
+
+### Requirements Coverage
+| Requirement | Status | Gap |
+|-------------|--------|-----|
+| [req] | met/missed | [what's missing] |
+
+### Verify Findings (from /cbp-verify on the previous round)
+| # | Source | File | Issue |
+|---|--------|------|-------|
+| [gate failure / proof gap / reviewer finding the previous verify could not auto-apply] |
+
+### Root Causes
+1. [root cause with explanation]
+2. [root cause with explanation]
+```
+
+### Step 4: Create Round in DB
+
+**checkpoint KIND**: `codebyplan round add --task-id <uuid> --checkpoint-id <uuid> --number <N> --status in_progress --started-at <ISO> --triggered-by <user|claude|auto_loop> [--requirements <text>] [--context <json>]` (CLI write-through: writes local state at `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>/rounds/<roundId>.json` + REST). Break-glass fallback: MCP `add_round` when the CLI is unavailable.
+
+**standalone KIND**: MCP `add_standalone_round(standalone_task_id, ...)` — standalone still uses MCP.
+
+Fields to supply:
+- `task_id` (checkpoint) / `standalone_task_id` (standalone): current task ID
+- `number`: next round number
+- `status`: "in_progress"
+- `started_at`: now (ISO format)
+- `triggered_by`: `"user"` | `"claude"` | `"auto_loop"` — `auto_loop` when `auto_loop_mode === true` carries forward; `claude` when auto-triggered by a verify failure; `user` otherwise
+- `requirements`: round requirements from Step 3 / 3D
+- `context`: when `auto_loop_mode === true`, persist `auto_loop_mode: true`, `auto_loop_index: N`, `auto_loop_cap: C` into `round.context`
+
+### Step 4b: Choose Mode (round 2+ only)
+
+**If `round.context.auto_loop_mode === true` on the prior round**: skip the AskUserQuestion below. Auto-pick "Start round with these findings" using the Step 3D analysis directly. Set the next round's `auto_loop_mode = true`, carry `auto_loop_index` and `auto_loop_cap` forward.
+
+**Else (manual mode)**, ask user via AskUserQuestion:
+
+- **Start round with these findings** — use the Step 3D analysis as requirements
+- **Discuss first** — open conversation about the analysis
+- **Adjust** — user provides their own requirements
+
+If "Discuss first": enter open discussion; when direction is clear, continue. If "Adjust": merge the user's requirements with the analysis context.
+
+**Under `auto_loop_mode`**: requirements come VERBATIM from the prior round's reviewer findings and verify gate/proof failures, treated as a flat list. Test/gate failures are listed first (they block shipping); reviewer findings follow. Both sets are included unchanged — do not re-summarise or re-prioritise either.
+
+### Step 5: Load Context from DB
+
+Load from checkpoint and task:
+- Checkpoint context (decisions, dependencies, constraints, goal)
+- Task context and requirements
+- Resources from checkpoint and task (documentation links, API docs, guides)
+- Previous round results (files_changed, verify outcomes)
+- For round 2+: load the latest completed round's `context.verify_manifest` and `context.executor_output`:
+  - **checkpoint KIND**: read `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>/rounds/<roundId>.json` (local-first). If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_rounds` when the state dir is absent and sync fails.
+  - **standalone KIND**: MCP `get_standalone_rounds(standalone_task_id)` — standalone still uses MCP.
+- Identify unapproved files from task.files_changed (where user_approved === false)
+
+### Step 6: First Round Analysis (Round 1 only)
+
+For the first round only:
+
+1. Analyze the task context and requirements thoroughly
+2. Identify any ambiguities or gaps
+3. If questions are needed, ask user via AskUserQuestion (max 4 per batch)
+4. If task context changes from Q&A answers:
+   - **checkpoint KIND**: `codebyplan task update --id <task-id> --checkpoint-id <uuid> --context <json>` (CLI write-through: local state at `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>.json` + REST). Break-glass fallback: MCP `update_task` when the CLI is unavailable.
+   - **standalone KIND**: MCP `update_standalone_task(standalone_task_id, context: {...})` — standalone still uses MCP.
+   - Save Q&A decisions as `context.decisions[]`
+
+Skip this step for round 2+ (context already established via the Step 3D deep analysis).
+
+**If `auto_loop_mode === true`, skip Q&A regardless of round number** — the auto-loop already has authoritative requirements from the prior round's findings.
+
+### Step 7: Spawn Round Planner Agent
+
+Spawn `cbp-round-planner` agent with:
+```yaml
+input:
+  task_number: N
+  round_number: N
+  requirements: task.requirements
+  round_requirements: [round-specific input from Step 3 / 3D]
+  checkpoint: {id, title, goal, context}
+  task: {id, title, requirements, context}
+  previous_rounds: {count, files_pending, files_changed, verify_manifest, unapproved_files}
+```
+
+**Round 2+ context**: the planner receives the previous round's verify outcome and the list of unapproved files (from Step 3D).
+
+**Priority**: if `round_requirements` is set (round 2+), the planner focuses on those specific goals while respecting `task.requirements` as context.
+
+Wait for planner output. **If the spawn fails, STOP per "Planner Spawn Failure Is A Gate Failure" above** — do not self-certify a plan inline.
+
+### Step 8: Present Plan
+
+Present the plan to user:
+
+```
+## Round [N] Plan
+
+**Goal**: [goal]
+
+### Steps:
+1. [step]
+2. [step]
+...
+
+### Files to modify:
+| File | Action | Purpose |
+|------|--------|---------|
+| ... | ... | ... |
+```
+
+**Wave table** — when `approved_plan.waves[]` contains ≥2 entries, render a wave summary table BEFORE the files table:
+
+```
+### Execution Waves
+| Wave | Agent type | Files | Depends on | Skill preloads |
+|------|-----------|-------|-----------|----------------|
+| web-ui | cbp-round-builder | 7 | — | cbp-frontend-design |
+| backend-api | cbp-round-builder | 4 | — | — |
+```
+
+Single-wave plans present the existing flat plan view (no wave table) — backward compatible.
+
+**Plan approval is the `ask`-tier `Skill(cbp-round-build)` permission prompt** — there is NO approve/needs-changes/wrong AskUserQuestion here. After presenting the plan, proceed to Step 9, which auto-triggers `/cbp-round-build`; the harness then shows the `ask`-tier permission prompt, and confirming it IS the user's go-ahead on the plan.
+
+**Denied-build handling** — if the user declines the `/cbp-round-build` permission, the plan does not run. Treat the decline as "the plan must change":
+
+- **Minor changes**: collect the user's feedback, re-spawn `cbp-round-planner` with it as a constraint (re-run Step 7), present the revised plan, and re-trigger `/cbp-round-build`.
+- **Wrong direction**: save the rejection reason to round context and re-run this skill's deep-analysis path (Step 3D) for new requirements.
+
+**If `auto_loop_mode === true`**: the loop auto-approves — log `round.context.plan_approval = { mode: "auto_loop", auto_approved_at: <ISO> }`, surface a one-line note `"Auto-approved under auto_loop_mode (round N of cap C)"`, and proceed to Step 9 (the `/cbp-round-build` permission is auto-approved under the loop).
+
+### Step 9: Auto-trigger Round Build
+
+Save planner output to round context, then trigger `/cbp-round-build`. The `ask`-tier permission prompt on `/cbp-round-build` is the user's plan approval (see Step 8).
+
+- **checkpoint KIND**: `codebyplan round update --id <round-id> --task-id <uuid> --checkpoint-id <uuid> --context <json>` (CLI write-through: local state at `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>/rounds/<roundId>.json` + REST). Break-glass fallback: MCP `update_round` when the CLI is unavailable.
+- **standalone KIND**: MCP `update_standalone_round(standalone_round_id, ...)` — standalone still uses MCP.
+
+```
+Starting build phase...
+```
+
+## Fallback: Context Recovery
+
+If this command is triggered **directly** (not via `/cbp-todo`) and no context is available in the session:
+
+1. Read `.codebyplan/repo.json` for `repo_id`
+2. Use Kind Detection to determine KIND, then:
+   - **checkpoint KIND**: Read local `.codebyplan/state/` files for checkpoint + task (break-glass: MCP `get_current_task`).
+   - **standalone KIND**: MCP `get_current_standalone_task`.
+3. Load round history:
+   - **checkpoint KIND**: Read `.codebyplan/state/checkpoints/<id>/tasks/<id>/rounds/*.json` (break-glass: MCP `get_rounds(task_id)`).
+   - **standalone KIND**: MCP `get_standalone_rounds(standalone_task_id)`.
+4. Continue from Step 1 (round 2+ deep analysis at Step 3D handles all context loading)
+
+## Key Rules
+
+- **Planning ONLY** — no code execution, no testing
+- Planner gets full context (checkpoint + task + previous rounds)
+- Round 1 plans from `task.requirements`; round 2+ runs the MANDATORY Step 3D deep analysis (same depth as round 1 — no quick-fix behavior)
+- Planner spawn failure is a HARD GATE FAILURE — STOP + retry directive, NEVER self-certify a plan inline (`rules/spawn-failure-is-gate-failure.md`)
+- Claude NEVER git adds files in round commands
+
+## Integration
+
+- **Reads (checkpoint KIND)**: `.codebyplan/state/checkpoints/<id>.json`, `checkpoints/<id>/tasks/<id>.json`, `checkpoints/<id>/tasks/<id>/rounds/<id>.json` (local-first; `npx codebyplan sync` on miss; MCP `get_current_task` / `get_rounds` as break-glass), file contents (Read tool, round 2+ deep analysis)
+- **Reads (standalone KIND)**: MCP `get_current_standalone_task`, `get_standalone_rounds` — standalone still uses MCP
+- **Writes (checkpoint KIND)**: `codebyplan round add` (Step 4), `codebyplan round update` (Step 9), `codebyplan task update` (Step 6 context only) — break-glass: MCP `add_round` / `update_round` / `update_task`
+- **Writes (standalone KIND)**: MCP `add_standalone_round`, `update_standalone_round`, `update_standalone_task` — standalone still uses MCP
+- **Spawns**: `cbp-round-planner` (spawn failure = hard gate failure → STOP)
+- **Triggers**: `/cbp-round-build` (auto, on plan approval)
+- **Triggered by**: `/cbp-task-start` (round 1), `/cbp-verify` (round 2+ fix round or more-work), `/cbp-todo` (after /clear), user manually

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

@@ -30,7 +30,7 @@ Snapshot the current next-action so the next `/cbp-session-start` (Step 4.5) can
 2. If `rows[0]` exists and its `command` is non-empty (active work in flight):
    ```yaml
    handoff:
-     command: <rows[0].command> # e.g. "/cbp-round-update"
+     command: <rows[0].command> # e.g. "/cbp-verify"
      instructions: <rows[0].instructions> # human-readable trigger reason
      state: <rows[0].state> # workflow state label
      context: # entity ids used by the Step 4.5 freshness probe

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

@@ -0,0 +1,291 @@
+---
+scope: org-shared
+name: cbp-setup-cd
+description: Detect configured CD surfaces, write/update .codebyplan/cd.json via `codebyplan cd init`, scaffold publish.yml and release-desktop.yml GitHub Actions workflows, and walk through environment/approval/OIDC setup. Interactive, idempotent.
+argument-hint: "[--force]"
+effort: xhigh
+allowed-tools: Read, Write, Edit, Bash(cat *), Bash(jq *), Bash(test *), Bash(ls *), Bash(diff *), Bash(codebyplan cd *), Bash(npx codebyplan cd *), AskUserQuestion
+---
+
+# CD Setup
+
+Configure `.codebyplan/cd.json`, scaffold `.github/workflows/publish.yml` and
+`.github/workflows/release-desktop.yml`, and record the credential env-var names needed
+at deploy time. Invoke at any time. Already-configured surfaces are preserved unless
+`--force` is passed.
+
+Pass `--force` to re-detect all surfaces and overwrite existing workflow files.
+
+## Arguments
+
+Inspect `$ARGUMENTS` for `--force`. If present, set `force_mode = true`.
+Absent: idempotent mode — existing surface keys in `.codebyplan/cd.json` are preserved;
+workflow files are not overwritten unless `--force`.
+
+## Step 1 — Detect configured surfaces + read current state
+
+Read detection signals and existing config:
+
+```bash
+cat .codebyplan/shipment.json 2>/dev/null || echo '{}'
+cat .codebyplan/cd.json 2>/dev/null || echo '{}'
+```
+
+**Surface detection signals** (derive from `shipment.json` + filesystem):
+
+| Surface | Signal |
+|---------|--------|
+| `npm` | `packages/*/package.json` with `publishConfig.access` set |
+| `tauri` | `apps/*/src-tauri/tauri.conf.json` present |
+| `vscode` | `apps/*/package.json` with `contributes` block |
+| `expo` | `apps/*/eas.json` present |
+| `vercel` | `.vercel/project.json` or `vercel.json` in any app |
+| `railway` | `apps/*/railway.toml` or `apps/*/Dockerfile` present |
+
+**Idempotency**: a surface already in `.codebyplan/cd.json` is "configured". A newly
+detected surface not yet in the file is "new". A surface in the file but no longer
+detected is "stale".
+
+Display a detection table:
+
+```
+Surface   | Detected | Configured | Workflow file
+--------- | -------- | ---------- | ----------------------------------------
+npm       | yes      | yes        | .github/workflows/publish.yml (present)
+tauri     | yes      | yes        | .github/workflows/release-desktop.yml (present)
+vscode    | no       | no         | —
+expo      | no       | no         | —
+```
+
+## Step 2 — Confirm surfaces to manage
+
+AskUserQuestion (multi-select):
+
+```
+Detected CD surfaces:
+<table from Step 1>
+
+Which surfaces should be managed by cd.json?
+Already-configured surfaces are pre-checked. Deselect to remove from cd.json.
+
+Select all that apply:
+A) npm       — publish.yml (GitHub Actions + OIDC)
+B) tauri     — release-desktop.yml (cross-platform Tauri build + signing)
+C) vscode    — VS Code marketplace publish (undetected — add eas.json to enable)
+D) expo      — EAS build + store submit (undetected)
+E) vercel    — Vercel production deploy (managed by Vercel GitHub integration)
+F) railway   — Railway deploy hook (managed by Railway GitHub integration)
+```
+
+In `--force` mode: re-ask even for already-configured surfaces.
+Otherwise: surfaces already in `cd.json` are preserved without re-asking.
+
+If an expected surface is MISSING from detection: add the detection signal (e.g.
+`publishConfig.access` in package.json, or `src-tauri/tauri.conf.json`) and re-run.
+To DROP a surface: deselect it here and re-run with `--force` to remove its key from
+`cd.json`, or edit `.codebyplan/cd.json` directly.
+
+## Step 3 — Collect credential env-var names (per surface)
+
+For each confirmed surface, collect only the env-var NAMES (never the values). Skip if
+`--force` is absent AND `credentials.env_var_names[]` is already non-empty in `cd.json`.
+
+Per-surface default name sets (accept defaults or override):
+
+| Surface | Default env-var names |
+| ------- | --------------------- |
+| `npm` (OIDC) | *(none — OIDC handles auth; record `[]`)* |
+| `npm` (token) | `NPM_TOKEN` |
+| `tauri` | `TAURI_SIGNING_PRIVATE_KEY`, `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`, `APPLE_CERTIFICATE`, `APPLE_CERTIFICATE_PASSWORD`, `APPLE_SIGNING_IDENTITY`, `APPLE_API_ISSUER`, `APPLE_API_KEY`, `APPLE_API_KEY_CONTENT`, `WINDOWS_CERTIFICATE`, `WINDOWS_CERTIFICATE_PASSWORD` |
+| `vscode` | `VSCE_PAT` |
+| `expo` | `EXPO_TOKEN` |
+
+Full var descriptions: [reference/github-actions-cd.md](reference/github-actions-cd.md) § Per-Surface Credential Var-Name Reference.
+
+Record collected names into `credentials.env_var_names[]`. Never write secret values.
+
+## Step 4 — Collect environment + approval config (per surface)
+
+For each confirmed surface, ask about GitHub Environments and approval gates. Skip if
+already configured in `cd.json` and `--force` is absent.
+
+AskUserQuestion per surface:
+
+```
+GitHub Environment config for [surface]:
+
+1. Deploy environment name (leave blank for none — e.g. "production"):
+   Environment: ___
+
+2. Require manual approval before deploy?
+   A) No — auto-deploy on push (recommended for npm OIDC / Tauri tag)
+   B) Yes — require a reviewer to approve the workflow run
+
+3. OIDC auth (exchange GitHub OIDC token for deploy credential)?
+   A) Yes — recommended for npm (no long-lived token; requires Trusted Publisher config on npmjs.com)
+   B) No — use a long-lived token from repository secrets
+```
+
+Record as `environment`, `approval_required`, and `oidc_auth` on the surface block.
+
+## Step 5 — Write .codebyplan/cd.json
+
+Run `codebyplan cd init` to write the config:
+
+```bash
+npx codebyplan cd init [--force]
+```
+
+The CLI writes `cd.json` from the collected surface data. If the CLI is unavailable (not
+yet on PATH), write the file directly via jq:
+
+```bash
+jq -n \
+  --argjson surfaces "$SURFACES_JSON" \
+  --argjson workflow "$WORKFLOW_JSON" \
+  '{surfaces: $surfaces, workflow: $workflow}' \
+  > .codebyplan/cd.json
+```
+
+Confirm by reading back the result:
+
+```bash
+cat .codebyplan/cd.json
+```
+
+Per-surface shape: `{ trigger, path_filter, approval_required, oidc_auth, version_gate,
+credentials: { env_var_names[] } }`. Credentials are env-var NAMES only — never values.
+Schema: `packages/codebyplan-package/src/lib/types.ts` (`CdConfig`).
+
+## Step 6 — Scaffold workflow files (diff-guarded)
+
+Preview each workflow before writing:
+
+```bash
+npx codebyplan cd scaffold-workflow --dry-run
+```
+
+For each workflow file that already exists, show a diff and ask before overwriting (unless
+`--force` is set):
+
+```bash
+diff .github/workflows/publish.yml <(npx codebyplan cd scaffold-workflow --workflow publish --dry-run)
+```
+
+AskUserQuestion (only when file exists and `--force` is absent):
+
+```
+.github/workflows/publish.yml already exists.
+Diff (existing → new):
+<diff output>
+
+Overwrite?
+A) Yes — adopt the scaffolded workflow (recommended — picks up latest template)
+B) No — keep existing workflow unchanged
+```
+
+Then write:
+
+```bash
+npx codebyplan cd scaffold-workflow [--force]
+```
+
+If the CLI errors (missing bin, not yet released), write from the canonical templates at
+`packages/codebyplan-package/templates/github-workflows/`:
+
+```bash
+cp packages/codebyplan-package/templates/github-workflows/publish.yml \
+   .github/workflows/publish.yml
+cp packages/codebyplan-package/templates/github-workflows/release-desktop.yml \
+   .github/workflows/release-desktop.yml
+```
+
+Only copy templates relevant to the confirmed surface set (npm → publish.yml;
+tauri → release-desktop.yml).
+
+After writing, update `cd.json` to record `workflow.workflows_scaffolded: true` and the
+current timestamp:
+
+```bash
+jq '.workflow.workflows_scaffolded = true | .workflow.scaffolded_at = "'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"' \
+  .codebyplan/cd.json > .codebyplan/cd.json.tmp \
+  && mv .codebyplan/cd.json.tmp .codebyplan/cd.json
+```
+
+## Step 7 — OIDC Trusted Publishing verification (npm surface)
+
+If the npm surface uses `oidc_auth: true`, walk the user through verifying the npmjs.com
+Trusted Publisher registration:
+
+```
+npm OIDC Trusted Publishing setup
+
+Verify these settings on npmjs.com → package → Settings → Trusted Publishers:
+
+  Publisher type : GitHub Actions
+  Repository owner: <github-org>
+  Repository name : <repo-slug>
+  Workflow filename: publish.yml
+  Environment     : (blank, unless you set a GitHub Environment above)
+
+If the Trusted Publisher is NOT configured, publish.yml will fail with E401.
+Configure it at: https://www.npmjs.com/package/<package-name>/access
+
+Configured? (Y/n)
+```
+
+If `n`: print the npmjs.com configuration URL and pause — the user must complete this
+before the first publish will succeed. Record the gap in `cd.json` as
+`workflow.npm_oidc_publisher_verified: false`.
+
+On `Y`: record `workflow.npm_oidc_publisher_verified: true`.
+
+Skip this step when `oidc_auth: false` for the npm surface.
+
+## Step 8 — Verify and report
+
+Re-read the config and confirm workflow files exist:
+
+```bash
+cat .codebyplan/cd.json
+test -f .github/workflows/publish.yml && echo "publish.yml present" || echo "publish.yml MISSING"
+test -f .github/workflows/release-desktop.yml && echo "release-desktop.yml present" || echo "release-desktop.yml MISSING"
+```
+
+Emit a summary:
+
+```
+CD Setup — Complete
+
+Surface | trigger       | path_filter                      | approval | oidc  | version_gate | workflow
+------- | ------------- | -------------------------------- | -------- | ----- | ------------ | --------
+npm     | push-to-main  | packages/codebyplan-package/**   | no       | yes   | yes          | publish.yml (present)
+tauri   | push-to-main  | apps/desktop/**                  | no       | no    | yes          | release-desktop.yml (present)
+
+cd.json:  .codebyplan/cd.json  (written)
+
+Next:
+  1. Add the credential env vars to GitHub repository secrets (Settings → Secrets and variables → Actions).
+  2. For npm OIDC: verify the Trusted Publisher on npmjs.com (Step 7 above).
+  3. Push a version bump to main to verify the publish.yml gate fires.
+  4. See reference/github-actions-cd.md for workflow anatomy and troubleshooting.
+```
+
+## Key Rules
+
+- Credentials are NEVER written to `cd.json` or this skill — var names only
+- Idempotent — re-running without `--force` preserves existing surface keys and workflow
+  files; it never clobbers a customized workflow
+- Diff-guarded — existing workflow files are shown as a diff before overwriting
+- Repos without `cd.json` fall back to the existing surface-detection path in `/cbp-ship`
+  — this skill writes the config that informs `/cbp-ship` Step 3 variant selection
+- This skill is org-shared; its template twin at
+  `packages/codebyplan-package/templates/skills/cbp-setup-cd/SKILL.md` must stay
+  byte-identical (GATE-6)
+
+## Additional resources
+
+- Workflow anatomy + OIDC + drift-guard: [reference/github-actions-cd.md](reference/github-actions-cd.md)
+- CD config schema: `packages/codebyplan-package/src/lib/types.ts` (`CdConfig`)
+- CD CLI commands: `packages/codebyplan-package/src/cli/cd.ts`
+- Surface detection signals: `packages/codebyplan-package/src/lib/cd-init.ts` (`detectSurfaces`, `normaliseSurfaceKey`)