codebyplan 1.13.38 → 1.13.40

package/templates/hooks/cbp-test-hooks.sh

@@ -455,6 +455,78 @@ fi
 
 echo ""
 
+# ===== HOOK SMOKE TESTS — cbp-session-start-hook =====
+echo "## Hook Smoke Tests — cbp-session-start-hook (CHK-178)"
+
+SESSION_START_HOOK="$HOOKS_DIR/cbp-session-start-hook.sh"
+
+if [ ! -f "$SESSION_START_HOOK" ]; then
+  test_result "cbp-session-start-hook.sh present" "passed" "missing"
+else
+  test_result "cbp-session-start-hook.sh present" "passed" "passed"
+
+  # Header/@scope check
+  FIRST_LINE=$(head -1 "$SESSION_START_HOOK")
+  if echo "$FIRST_LINE" | grep -q '^#!/'; then
+    test_result "cbp-session-start-hook.sh has shebang" "passed" "passed"
+  else
+    test_result "cbp-session-start-hook.sh has shebang" "passed" "missing"
+  fi
+
+  if grep -q '@scope: org-shared' "$SESSION_START_HOOK"; then
+    test_result "cbp-session-start-hook.sh has @scope: org-shared" "passed" "passed"
+  else
+    test_result "cbp-session-start-hook.sh has @scope: org-shared" "passed" "missing"
+  fi
+
+  # Syntax check
+  if bash -n "$SESSION_START_HOOK" 2>/dev/null; then
+    test_result "cbp-session-start-hook.sh bash -n syntax ok" "passed" "passed"
+  else
+    test_result "cbp-session-start-hook.sh bash -n syntax ok" "passed" "failed"
+  fi
+
+  # Graceful-degrade: run in a temp dir without .codebyplan/repo.json — hook
+  # must exit 0 (no-op) without invoking npx (stub npx as a no-op in PATH).
+  ISO=$(mktemp -d)
+  # Create a stub npx in a temp bin dir so npx invocations are harmless no-ops.
+  STUB_BIN=$(mktemp -d)
+  printf '#!/bin/bash\nexit 0\n' > "$STUB_BIN/npx"
+  chmod +x "$STUB_BIN/npx"
+  ACTUAL_EXIT=$(CLAUDE_PROJECT_DIR="$ISO" PATH="$STUB_BIN:$PATH" bash "$SESSION_START_HOOK" >/dev/null 2>&1; echo $?)
+  # In the no-repo.json path npx must NOT be invoked at all — use a recording
+  # stub marker dir to assert zero invocations.
+  rm -rf "$ISO" "$STUB_BIN"
+  if [ "$ACTUAL_EXIT" = "0" ]; then
+    test_result "cbp-session-start-hook.sh graceful-degrade (no repo.json) exits 0" "passed" "passed"
+  else
+    test_result "cbp-session-start-hook.sh graceful-degrade (no repo.json) exits 0" "passed" "failed (exit=$ACTUAL_EXIT)"
+  fi
+
+  # Positive path: with .codebyplan/repo.json present, the hook must invoke
+  # `npx codebyplan sync` AND `npx codebyplan watch start` (recording stub
+  # writes each invocation's args to a marker file), and still exit 0.
+  ISO=$(mktemp -d)
+  STUB_BIN=$(mktemp -d)
+  MARKER="$STUB_BIN/invocations.log"
+  mkdir -p "$ISO/.codebyplan"
+  printf '{}' > "$ISO/.codebyplan/repo.json"
+  printf '#!/bin/bash
+echo "$@" >> "%s"
+exit 0
+' "$MARKER" > "$STUB_BIN/npx"
+  chmod +x "$STUB_BIN/npx"
+  ACTUAL_EXIT=$(CLAUDE_PROJECT_DIR="$ISO" PATH="$STUB_BIN:$PATH" bash "$SESSION_START_HOOK" >/dev/null 2>&1; echo $?)
+  if [ "$ACTUAL_EXIT" = "0" ] && grep -q "codebyplan sync" "$MARKER" 2>/dev/null && grep -q "codebyplan watch start" "$MARKER" 2>/dev/null; then
+    test_result "cbp-session-start-hook.sh positive path invokes sync + watch start, exits 0" "passed" "passed"
+  else
+    test_result "cbp-session-start-hook.sh positive path invokes sync + watch start, exits 0" "passed" "failed (exit=$ACTUAL_EXIT)"
+  fi
+  rm -rf "$ISO" "$STUB_BIN"
+fi
+
+echo ""
+
 # ===== SUMMARY =====
 echo "=== TEST SUMMARY ==="
 echo -e "Passed: ${GREEN}$PASSED${NC}"

package/templates/hooks/hooks.json

@@ -1,5 +1,16 @@
 {
   "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/cbp-session-start-hook.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "hooks": [

package/templates/hooks/validate-structure.sh

@@ -48,9 +48,10 @@ esac
 FILENAME=$(basename "$FILE_PATH" ".$EXT")
 
 if match_path '^/(\.claude|docs)/'; then
-  # Skip special naming patterns (SKILL/AGENT/CLAUDE/MEMORY/TASK-N/CHK-NNN/date/week-N/research phase/README)
+  # Skip special naming patterns (SKILL/AGENT/CLAUDE/MEMORY/TASK-N/CHK-NNN/date/week-N/research phase/README/INDEX)
   # CHK formats: CHK-001 (generic) or CHK-H001/CHK-A001/CHK-B001 (launch: Homepage/Application/Backdoor)
-  if ! echo "$FILENAME" | grep -qE '^(SKILL|AGENT|CLAUDE|MEMORY|TASK-[1-9]|[0-9]{2}-[0-9]{2}-[0-9]{2}-CHK-([0-9]{3}|[HAB][0-9]{3})|CHK-([0-9]{3}|[HAB][0-9]{3})|[0-9]{2}-[0-9]{2}-[0-9]{2}|week-[0-9]+|[1-8]-|README)'; then
+  # INDEX: grep-native registry filename used by the architecture-map pipeline (.claude/architecture/INDEX.md) and vendor docs
+  if ! echo "$FILENAME" | grep -qE '^(SKILL|AGENT|CLAUDE|MEMORY|TASK-[1-9]|[0-9]{2}-[0-9]{2}-[0-9]{2}-CHK-([0-9]{3}|[HAB][0-9]{3})|CHK-([0-9]{3}|[HAB][0-9]{3})|[0-9]{2}-[0-9]{2}-[0-9]{2}|week-[0-9]+|[1-8]-|README|INDEX)'; then
     if echo "$FILENAME" | grep -qE '[A-Z]|_'; then
       block "Filename must be kebab-case (lowercase with hyphens)" "Got: $FILENAME, Expected: $(echo "$FILENAME" | tr '[:upper:]' '[:lower:]' | tr '_' '-')"
     fi

package/templates/rules/architecture-map.md

@@ -0,0 +1,30 @@
+---
+scope: org-shared
+---
+
+# Architecture Map
+
+When `.claude/architecture/` exists in this repo, per-module map files may be present.
+
+## Rule
+
+- Before analyzing or editing files in a module, Glob `.claude/architecture/<module-slug>.md`.
+- If a map file exists, read it before proceeding — it provides pre-computed structural
+  context (boundaries, public surface, internal layout, dependencies, landmarks) that
+  reduces the need for broad file-system scans.
+- Map absence is **not a blocker** — continue with standard file-system analysis when no
+  map exists.
+- The full consultation contract (when to read, how to parse, agent phases) is at
+  `.claude/context/architecture-map.md`.
+
+## Why
+
+Architecture maps are pre-computed indexes of module structure. Reading one replaces
+several individual file-reads and surfaces cross-module impact that point-in-time grep
+may miss. A 10-second read prevents a scoping gap.
+
+## Generate / Refresh
+
+- `/cbp-map-architecture` — generate or regenerate maps for all/selected modules.
+- `/cbp-refresh-arch-map` — drift-scoped refresh (re-runs only stale modules).
+- `codebyplan arch-map status` — list modules and their map freshness.

package/templates/rules/context-file-loading.md

@@ -23,6 +23,9 @@ paths:
 | `context/testing/eslint.md` | `cbp-improve-round` | Phase 1.5 | Config-file compliance audit |
 | `context/mcp-docs.md` | `cbp-task-planner` | Phase 2.6 | MCP library doc lookup contract — per-dependency consultation via DocsByPlan MCP tools (resolve_library_id → search_chunks/lookup_symbol → get_chunk) |
 | `context/mcp-docs.md` | `cbp-round-executor` | Step 3.4 | Library-specific reference — pre-write API verification via DocsByPlan MCP tools |
+| `context/architecture/arch-map-spec.md` | `cbp-map-architecture` | Entry | Canonical architecture-map artifact format — per-module frontmatter + sections, INDEX.md row format, dependency-graph format |
+| `context/architecture-map.md` | `cbp-task-planner` | Phase 3 | Architecture map consultation contract — when + how to read per-module maps before finalizing scope |
+| `context/architecture-map.md` | `cbp-round-executor` | Step 2.4 | Architecture map consultation contract — when + how to read per-module maps before editing files |
 | `rules/parallel-waves.md` | `cbp-task-planner` | Phase 5.6 | Wave schema, invariants (3..15 file-count), and the proximity-split algorithm (a `rules/` file, not `context/**`; listed here for consumer discoverability) |
 
 New context files MUST be added here in the same change that introduces the consumer — or the file is orphan infrastructure.

package/templates/rules/supabase-branch-lifecycle.md

@@ -80,7 +80,7 @@ Skills that delete Supabase branches MUST:
 
 1. Verify the branch name matches the feat branch being removed (never delete by
    `project_ref` alone).
-2. Never delete the parent/production project (`rrvtrumtkhrsbhcyrwvf`) itself.
+2. Never delete the branch where `is_default` is true in the `list_branches` response (the parent/production branch) or any other persistent/long-lived branch.
 3. Never delete a persistent/long-lived branch that does not correspond to the git branch
    being torn down.
 

package/templates/settings.project.base.json

@@ -110,7 +110,9 @@
       "Skill(cbp-git-commit)",
       "Skill(cbp-git-worktree-create)",
       "Skill(cbp-git-worktree-remove)",
+      "Skill(cbp-map-architecture)",
       "Skill(cbp-merge-main)",
+      "Skill(cbp-refresh-arch-map)",
       "Skill(cbp-refresh-infra)",
       "Skill(cbp-round-check)",
       "Skill(cbp-round-end)",
@@ -192,6 +194,16 @@
       "Bash(npx codebyplan lsp:*)",
       "Bash(codebyplan round:*)",
       "Bash(npx codebyplan round:*)",
+      "Bash(codebyplan sync:*)",
+      "Bash(npx codebyplan sync:*)",
+      "Bash(codebyplan watch:*)",
+      "Bash(npx codebyplan watch:*)",
+      "Bash(codebyplan checkpoint:*)",
+      "Bash(npx codebyplan checkpoint:*)",
+      "Bash(codebyplan task:*)",
+      "Bash(npx codebyplan task:*)",
+      "Bash(codebyplan session:*)",
+      "Bash(npx codebyplan session:*)",
       "Bash(codebyplan help:*)",
       "Bash(npx codebyplan help:*)",
       "Bash(codebyplan --version:*)",
@@ -199,7 +211,9 @@
       "Bash(codebyplan bump:*)",
       "Bash(npx codebyplan bump:*)",
       "Bash(codebyplan scaffold-publish-workflow:*)",
-      "Bash(npx codebyplan scaffold-publish-workflow:*)"
+      "Bash(npx codebyplan scaffold-publish-workflow:*)",
+      "Bash(codebyplan arch-map:*)",
+      "Bash(npx codebyplan arch-map:*)"
     ]
   },
   "attribution": {

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

@@ -14,17 +14,17 @@ Full re-evaluation: compares initial ideas vs delivered work, aggregates files a
 
 ### Step 1: Identify Checkpoint
 
-**If arguments provided:** Parse `$ARGUMENTS` for CHK-NNN format, extract number. Use MCP `get_checkpoints` to find by number.
+**If arguments provided:** Parse `$ARGUMENTS` for CHK-NNN format, extract number. Scan `.codebyplan/state/checkpoints/*.json` to find by `number` field (local-first; if missing/stale run `npx codebyplan sync` once; break-glass: MCP `get_checkpoints`).
 
-**If NO arguments:** Use MCP `get_current_task` to get the active checkpoint.
+**If NO arguments:** Read `.codebyplan/state/session/current.json` to get the active checkpoint (fallback: MCP `get_current_task`).
 
 If no checkpoint found, show error and stop.
 
 ### Step 2: Load All Data
 
-1. Get checkpoint details (context, research, qa, ideas, goal, user_context)
-2. Use MCP `get_tasks` for the checkpoint
-3. For each task, use MCP `get_rounds` to get all rounds
+1. Read `.codebyplan/state/checkpoints/<id>.json` for checkpoint details (context, research, qa, ideas, goal, user_context). Break-glass: MCP `get_checkpoints`.
+2. Read task files under `.codebyplan/state/checkpoints/<id>/tasks/*.json` (fallback: MCP `get_tasks`).
+3. For each task, read round files under `.codebyplan/state/checkpoints/<id>/tasks/<taskId>/rounds/*.json` (fallback: MCP `get_rounds`).
 
 ### Step 3: Before/After Comparison
 
@@ -109,7 +109,7 @@ Aggregate the files touched across all tasks (reusing Step 4's deduplicated tabl
      credential_vars: [from e2e.json — env var names only, never secrets]
    ```
 
-   Hold each specialist's output keyed by framework (an `e2e_outputs[framework]` map) for this skill's aggregation — checkpoint-check has no MCP round, so this lives in-memory during the run (persist to `checkpoint.context` via `update_checkpoint` at Step 7 if a durable record is needed). `test_strategy` is intentionally omitted — the agent resolves it from `.codebyplan/e2e.json` and the DB tech-stack record.
+   Hold each specialist's output keyed by framework (an `e2e_outputs[framework]` map) for this skill's aggregation — checkpoint-check has no MCP round, so this lives in-memory during the run (persist to `checkpoint.context` via the Step 7 CLI write-through — `codebyplan checkpoint update` — if a durable record is needed). `test_strategy` is intentionally omitted — the agent resolves it from `.codebyplan/e2e.json` and the DB tech-stack record.
 
 3. **Wait for all specialists to complete.** Each agent's output carries `whole_checkpoint_aggregated: true` confirming whole-checkpoint formatting.
 
@@ -120,7 +120,7 @@ Aggregate the files touched across all tasks (reusing Step 4's deduplicated tabl
    Continue to Step 6.
 
 5. **On fail** (any framework `f`: `e2e_outputs[f].status === 'failed'` OR `e2e_outputs[f].test_results.failed > 0`): build a failure summary from `e2e_outputs[*].test_results.failures[]` aggregated and grouped by `category`. Surface via `AskUserQuestion`:
-   - **(a) Create fix-task in CHK-{NNN} (recommended)** — invoke MCP `create_task` with `checkpoint_id=current_checkpoint_id`, `title="Fix checkpoint-level e2e failures (CHK-{NNN})"`, `requirements` containing the detailed failure breakdown (category counts, files involved, pages broken, screenshot paths from `e2e_outputs[*].screenshots[]`), AND `context: { source_checkpoint_id, e2e_failure_summary: { category_counts, pages_broken, screenshot_paths }, fix_type: "checkpoint_e2e" }` so downstream `cbp-task-planner` can verify failure premises. Per `cbp-round-end` reference `findings-presentation.md` "Infra Issue Absorption Contract — Resolve-in-Current-Scope by Default", checkpoint-level e2e failures absorb into the active checkpoint — not standalone.
+   - **(a) Create fix-task in CHK-{NNN} (recommended)** — run `codebyplan task create` (CLI write-through; break-glass: MCP `create_task`) with `checkpoint_id=current_checkpoint_id`, `title="Fix checkpoint-level e2e failures (CHK-{NNN})"`, `requirements` containing the detailed failure breakdown (category counts, files involved, pages broken, screenshot paths from `e2e_outputs[*].screenshots[]`), AND `context: { source_checkpoint_id, e2e_failure_summary: { category_counts, pages_broken, screenshot_paths }, fix_type: "checkpoint_e2e" }` so downstream `cbp-task-planner` can verify failure premises. Per `cbp-round-end` reference `findings-presentation.md` "Infra Issue Absorption Contract — Resolve-in-Current-Scope by Default", checkpoint-level e2e failures absorb into the active checkpoint — not standalone.
    - **(b) Surface as warning only — proceed to checkpoint-end** — append `| Checkpoint E2E | warning | N failures (deferred) |` to Step 5 QA Summary; continue to Step 6.
    - **(c) Halt — review manually** — STOP and wait for the user.
 
@@ -145,7 +145,7 @@ If unapproved files exist:
 
 ### Step 7: Save Results
 
-Update checkpoint via MCP `update_checkpoint`:
+Update checkpoint via `codebyplan checkpoint update --id <id> --qa <json> --context <json>` (CLI write-through; break-glass: MCP `update_checkpoint`):
 - `qa`: aggregated QA results
 - `context`: add `check_results` with before/after, file summary, assessment
 
@@ -155,6 +155,6 @@ If all clear, auto-trigger `/cbp-checkpoint-end`.
 
 ## Integration
 
-- **Reads**: MCP `get_checkpoints`, `get_tasks`, `get_rounds`, `get_current_task`
-- **Writes**: MCP `update_checkpoint` (qa, context)
+- **Reads**: `.codebyplan/state/checkpoints/<id>.json`, `checkpoints/<id>/tasks/*.json`, `checkpoints/<id>/tasks/<taskId>/rounds/*.json`, `session/current.json` (local-first; `npx codebyplan sync` if stale; break-glass: MCP `get_checkpoints`, `get_tasks`, `get_rounds`, `get_current_task`)
+- **Writes**: `codebyplan checkpoint update --qa ... --context ...` (CLI write-through; break-glass: MCP `update_checkpoint`)
 - **Triggers**: `/cbp-checkpoint-end` (auto, if ready) or STOPS for `/cbp-task-create` (if issues)

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

@@ -19,7 +19,7 @@ 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 |
+| _(empty)_ | — | Resolve from local state per Step 1.5/2 (MCP `get_current_task` break-glass) — the active checkpoint |
 
 Anything else is malformed — surface this error and stop:
 
@@ -42,8 +42,8 @@ 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. |
+| `{chk}` | Scan `.codebyplan/state/checkpoints/*.json` for `number === {chk}` (local-first; if missing/stale run `npx codebyplan sync` once; break-glass: MCP `get_checkpoints`). |
+| _(empty)_ | Read `.codebyplan/state/session/current.json` for the active checkpoint (fallback: MCP `get_current_task`). If no active checkpoint, show error and stop. |
 
 ### Step 2: Verify Checkpoint End Has Run
 
@@ -59,7 +59,7 @@ Stop here.
 
 ### Step 2.5: Verify All Tasks Complete
 
-Use MCP `get_tasks` for the checkpoint. Verify all tasks have status `completed`.
+Read task files under `.codebyplan/state/checkpoints/<id>/tasks/*.json` (fallback: MCP `get_tasks`). Verify all tasks have status `completed`.
 
 If incomplete tasks remain:
 ```
@@ -82,7 +82,7 @@ If any critical failures, warn the user but don't block.
 
 ### Step 4: Complete Checkpoint
 
-Use MCP `complete_checkpoint(checkpoint_id)`.
+Run `codebyplan checkpoint complete --id <checkpoint-id>` (CLI write-through: updates `.codebyplan/state/checkpoints/<id>.json` + REST; break-glass: MCP `complete_checkpoint`).
 
 This automatically:
 - Sets status to `completed`
@@ -105,5 +105,5 @@ This automatically:
 ## Integration
 
 - **Triggered by**: `/cbp-checkpoint-end` (auto, after successful shipment)
-- **Reads**: MCP `get_current_task`, `get_tasks`, `get_rounds`
-- **Writes**: MCP `complete_checkpoint`
+- **Reads**: `.codebyplan/state/session/current.json`, `checkpoints/<id>.json`, `checkpoints/<id>/tasks/*.json` (local-first; `npx codebyplan sync` if stale; break-glass: MCP `get_current_task`, `get_tasks`, `get_rounds`)
+- **Writes**: `codebyplan checkpoint complete --id <id>` (CLI write-through; break-glass: MCP `complete_checkpoint`)

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

@@ -20,7 +20,7 @@ Runs INLINE. This is the **mechanical** stage only: capture raw user input, infe
 
 ### Step 1: Check for Existing Checkpoint Data
 
-Source `repo_id` from `.codebyplan/repo.json`. If `$ARGUMENTS` contains a checkpoint number, 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.
+Source `repo_id` from `.codebyplan/repo.json`. If `$ARGUMENTS` contains a checkpoint number, read `.codebyplan/state/checkpoints/` to find the matching file by `number` field (local-first). If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_checkpoints` when the state dir is absent and sync fails. If the checkpoint already has `ideas[]` with descriptions, reuse `ideas[].description` (do not re-ask) and skip Step 2.
 
 ### Step 2: Get Checkpoint Description
 
@@ -71,14 +71,16 @@ Record the choice; it drives both the create call (Step 8) and the plan→start
 
 ### Step 7: Determine Next Checkpoint Number
 
-MCP `get_checkpoints` for the repo; highest `number` + 1.
+Scan `.codebyplan/state/checkpoints/*.json` for the highest `number` field + 1. If state dir is absent, run `npx codebyplan sync` once. Break-glass fallback: MCP `get_checkpoints` when sync fails.
 
 ### 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"
+`codebyplan checkpoint create` (CLI write-through: writes `.codebyplan/state/checkpoints/<id>.json` + REST). Pass flags:
+- `--repo-id` (from `.codebyplan/repo.json`), `--number`, `--title`, `--goal`, `--deadline`, `--status pending`
+- `--ideas` JSON `[{ description: <raw user text> }]`
+- `--worktree-id` the resolved worktree **only if the user chose "claim"**; omit when "leave open"
+
+Break-glass fallback: MCP `create_checkpoint` when the CLI is unavailable.
 
 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.
 
@@ -93,7 +95,7 @@ git checkout -b "feat/CHK-{NNN}-{slug}" "origin/$BASE" 2>/dev/null \
 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.)
+Slug: lowercase, dash-joined, punctuation dropped, ≤40 chars. Persist the branch via `codebyplan checkpoint update --id <checkpoint-id> --branch-name "feat/CHK-{NNN}-{slug}"` (CLI write-through; break-glass: MCP `update_checkpoint`). (The dedicated `/cbp-git-branch-feat-create` skill is the canonical config-driven helper if you prefer to delegate.)
 
 **Note — Supabase preview branch**: no Supabase branch is created here. Creation is lazy — it happens on the first DB change when `/cbp-supabase-migrate` runs on this feat branch, which provisions a Supabase branch named identically to the git branch. See `cbp-supabase-migrate` Step 2.3 for the creation protocol.
 
@@ -113,6 +115,6 @@ Auto-trigger `/cbp-checkpoint-plan {NNN}` in the same context. This skill create
 ## Integration
 
 - **Runs inline**: mechanical setup only — no assessment, research, Q&A, plan, or tasks
-- **Reads**: MCP `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)
+- **Reads**: `.codebyplan/state/checkpoints/*.json` (local-first; `npx codebyplan sync` if stale; MCP `get_checkpoints` break-glass); `.codebyplan/repo.json`, `.codebyplan/git.json`; `npx codebyplan resolve-worktree`
+- **Writes**: `codebyplan checkpoint create` (description-only ideas + deadline + optional worktree_id), `codebyplan checkpoint update --branch-name` (break-glass: MCP `create_checkpoint` / `update_checkpoint`)
 - **Triggers**: `/cbp-checkpoint-plan` (auto)

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

@@ -34,7 +34,7 @@ Before any shipment logic, ensure the feat branch is current against main. Shipm
 
 ### Step 1: Get Active Checkpoint
 
-Use MCP `get_current_task` with repo_id. Get the active checkpoint.
+Read local state `.codebyplan/state/checkpoints/<id>.json` to get the active checkpoint; on miss run `npx codebyplan sync` once and re-read. Use MCP `get_current_task` as documented break-glass when the state dir is absent and sync fails.
 
 If no active checkpoint, show error and stop.
 
@@ -206,7 +206,7 @@ After the feat branch git delete, run the same conditional Supabase teardown for
 
 ### 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):
+Update checkpoint context via `codebyplan checkpoint update <id> --context '{"shipment": {...}}'` (CLI write-through); use MCP `update_checkpoint` as documented break-glass when the CLI is unavailable. The `shipment` block contains both branch promotion AND runtime surface results (from `/cbp-ship` Step 7):
 
 ```
 context.shipment: {
@@ -281,7 +281,7 @@ Auto-trigger `/cbp-checkpoint-complete`.
 ## 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)
+- **Reads**: Local state `.codebyplan/state/checkpoints/<id>.json`; on miss `npx codebyplan sync` once; MCP `get_current_task` as documented break-glass when the state dir is absent and sync fails. Also reads `.codebyplan/git.json` (`branch_config`), `.codebyplan/server.json` (`auto_push_enabled`), `.codebyplan/shipment.json` (`shipment`), git branches.
+- **Writes**: `codebyplan checkpoint update <id> --context '...'` (CLI write-through) for context.shipment; MCP `update_checkpoint` break-glass. Note: `mcp__supabase__list_branches` / `mcp__supabase__delete_branch` calls in Steps 8–9 are Supabase MCP (not CodeByPlan MCP) and are unchanged.
 - **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

@@ -26,15 +26,15 @@ Source `repo_id` from `.codebyplan/repo.json` — every MCP call below that take
 
 | 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` |
+| `{chk}` (e.g. `138`) | CHK-{chk}: scan `.codebyplan/state/checkpoints/*.json` by `number` field (local-first; fallback MCP `get_checkpoints`) |
+| _(empty)_ | Active/pending checkpoint: read `.codebyplan/state/session/current.json` (fallback MCP `get_current_task`); if none in progress, the most recent `pending` checkpoint with no `plan.steps` from local state |
 
 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:
+1. Resolve the checkpoint (Step 0). Read `.codebyplan/state/checkpoints/<id>.json` (local-first; if missing/stale run `npx codebyplan sync` once; break-glass: MCP `get_checkpoints`). Load `user_context`, `ideas[]`, `context` (decisions / discoveries / dependencies / constraints / qa_answers / alternatives), `research`, `plan`.
+2. Read task files under `.codebyplan/state/checkpoints/<id>/tasks/*.json` (fallback: 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.
@@ -45,7 +45,7 @@ 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.
+3. **Research (level 2+ only)** — spawn a single `cbp-research` subagent for web/library research. Persist findings to `checkpoint.research` via `codebyplan checkpoint update --id <id> --research <json>` (CLI write-through; break-glass: 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).
@@ -90,7 +90,7 @@ Resolve every remaining ambiguity. Ask via AskUserQuestion (max 4 per batch). Af
 
 ### 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.
+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 `codebyplan checkpoint update --id <id> --plan <json>` (CLI write-through; break-glass: MCP `update_checkpoint`) — `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
 
@@ -102,11 +102,11 @@ Each task is a complete, independently shippable vertical slice — group by the
 
 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`.
+For each task use `codebyplan task create --checkpoint-id <id> --number <n> --title <title> --requirements <json> --context <json>` (CLI write-through; break-glass: MCP `create_task`). **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).
+Final write of the complete `checkpoint.context` JSONB via `codebyplan checkpoint update --id <id> --context <json>` (CLI write-through; break-glass: 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
 
@@ -129,8 +129,8 @@ This skill does **NOT** activate the checkpoint and does **NOT** claim a user/wo
 
 ## Integration
 
-- **Reads**: MCP `get_current_task`, `get_checkpoints`, `get_tasks`
-- **Writes**: MCP `update_checkpoint` (ideas assessment, context, plan, research), `create_task`
+- **Reads**: `.codebyplan/state/checkpoints/<id>.json`, `checkpoints/<id>/tasks/*.json`, `session/current.json` (local-first; `npx codebyplan sync` if stale; break-glass: MCP `get_current_task`, `get_checkpoints`, `get_tasks`)
+- **Writes**: `codebyplan checkpoint update` (ideas assessment, context, plan, research), `codebyplan task create` (break-glass: MCP `update_checkpoint`, `create_task`)
 - **Spawns**: `cbp-research` (level 2+ only), config-matched `cbp-e2e-*` specialist (opt-in discovery probe, `whole_checkpoint_mode` — see `context/testing/e2e.md` dispatch contract)
 - **Triggered by**: `/cbp-checkpoint-create` (auto), or user directly
 - **Triggers**: `/cbp-checkpoint-start` (auto when claimed at create; directive when left open)

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

@@ -24,14 +24,14 @@ Source `repo_id` from `.codebyplan/repo.json`. Resolve caller worktree once for
 
 | Shape | Resolves to |
 |-------|-------------|
-| `{chk}` (e.g. `138`) | CHK-{chk} via MCP `get_checkpoints` filtered by `number` |
-| _(empty)_ | The next `pending` checkpoint that already has tasks (planned but not yet started); if several, the lowest-numbered |
+| `{chk}` (e.g. `138`) | CHK-{chk}: scan `.codebyplan/state/checkpoints/*.json` by `number` field (local-first; fallback MCP `get_checkpoints`) |
+| _(empty)_ | The next `pending` checkpoint with tasks in local state (lowest-numbered); fallback MCP `get_checkpoints` |
 
 Malformed (non-numeric, contains `-`): surface `checkpoint-start: invalid argument` and stop.
 
 ### Step 1: Load Checkpoint + Tasks
 
-Load the checkpoint (`status`, `worktree_id`, `plan`) and its tasks via MCP `get_tasks(checkpoint_id)`.
+Read `.codebyplan/state/checkpoints/<id>.json` for `status`, `worktree_id`, `plan` (local-first; if missing/stale run `npx codebyplan sync` once; break-glass: MCP `get_checkpoints`). Read task files under `.codebyplan/state/checkpoints/<id>/tasks/*.json` (fallback: MCP `get_tasks(checkpoint_id)`).
 
 ### Step 2: Planned-Gate
 
@@ -57,7 +57,7 @@ This mirrors the CHK-104 hard-lock model — never wrest a checkpoint from a liv
 
 If the checkpoint is already `active` AND `worktree_id` already equals `CALLER_WT` (the Step 3 no-op row), skip this step entirely and proceed to Step 5 — nothing to write.
 
-Otherwise set the checkpoint `active` via MCP `update_checkpoint(checkpoint_id, status: "active"`, plus `worktree_id: CALLER_WT` when claiming per Step 3. `caller_worktree_id` (CHK-140 TASK-7) identifies the calling worktree and is auto-injected by the `cbp-mcp-caller-worktree-inject.sh` PreToolUse hook (CHK-198 TASK-2); the server falls back to the repo `main` worktree only when it is absent. If the checkpoint was already `active` but a claim is still needed, skip the status write and only write `worktree_id`.
+Otherwise set the checkpoint `active` via `codebyplan checkpoint update --id <checkpoint-id> --status active` (CLI write-through; break-glass: MCP `update_checkpoint`), plus `--worktree-id CALLER_WT` when claiming per Step 3. For MCP break-glass path: `caller_worktree_id` identifies the calling worktree and is auto-injected by the `cbp-mcp-caller-worktree-inject.sh` PreToolUse hook (CHK-198 TASK-2); the server falls back to the repo `main` worktree only when it is absent. If the checkpoint was already `active` but a claim is still needed, skip the status write and only write `worktree_id`.
 
 ### Step 5: Route
 
@@ -77,8 +77,8 @@ Show a one-line confirmation before routing:
 
 ## Integration
 
-- **Reads**: MCP `get_checkpoints`, `get_tasks`; `npx codebyplan resolve-worktree`
-- **Writes**: MCP `update_checkpoint` (status + worktree_id; `caller_worktree_id` auto-injected by the cbp-mcp-caller-worktree-inject.sh hook, CHK-198 TASK-2; server falls back to repo `main` only when absent)
+- **Reads**: `.codebyplan/state/checkpoints/<id>.json`, `checkpoints/<id>/tasks/*.json` (local-first; `npx codebyplan sync` if stale; break-glass: MCP `get_checkpoints`, `get_tasks`); `npx codebyplan resolve-worktree`
+- **Writes**: `codebyplan checkpoint update --status active [--worktree-id <id>]` (CLI write-through; break-glass: MCP `update_checkpoint`; `caller_worktree_id` auto-injected by cbp-mcp-caller-worktree-inject.sh hook on the MCP path)
 - **Triggered by**: `/cbp-checkpoint-plan` (auto when claimed at create), `/cbp-todo` (planned-but-pending gate), or user directly
 - **Triggers**: `/cbp-task-start` (auto when claimed), or `/cbp-checkpoint-plan` (when the checkpoint is unplanned)
 - **Never**: plans or creates tasks — that is `/cbp-checkpoint-plan`

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

@@ -19,7 +19,7 @@ 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 |
+| _(empty)_ | — | Resolve from local state per Step 1.5/2 (MCP `get_current_task` break-glass) — the active checkpoint |
 
 Anything else is malformed — surface this error and stop:
 
@@ -42,8 +42,8 @@ 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 (and worktree_id resolved via `npx codebyplan resolve-worktree`) to find the active checkpoint. If no active checkpoint, use MCP `get_checkpoints` filtered by `pending` status to find pending ones. |
+| `{chk}` | Scan `.codebyplan/state/checkpoints/*.json` for `number === {chk}` (local-first; if missing/stale run `npx codebyplan sync` once; break-glass: MCP `get_checkpoints`). |
+| _(empty)_ | Read `.codebyplan/state/session/current.json` (with worktree_id from `npx codebyplan resolve-worktree`) to find the active checkpoint (fallback: MCP `get_current_task`). If no active checkpoint, scan local state for `pending` checkpoints (fallback: MCP `get_checkpoints` filtered by `pending`). |
 
 ### Step 1.5: Detect Entry Context (from `/cbp-task-complete` expand path)
 
@@ -76,17 +76,17 @@ When the entry context is "expand from task-complete", `Update context` is the r
 
 ### Step 3: Apply Update
 
-Use MCP `update_checkpoint` with the appropriate fields.
+Use `codebyplan checkpoint update --id <checkpoint-id> [--field value ...]` (CLI write-through: updates `.codebyplan/state/checkpoints/<id>.json` + REST; break-glass: MCP `update_checkpoint`).
 
 **For activation:**
 ```
-update_checkpoint(checkpoint_id, status: "active")
+codebyplan checkpoint update --id <id> --status active
 ```
 
 **For context updates:**
-Read current checkpoint to get existing context, merge new data, then:
+Read current checkpoint from `.codebyplan/state/checkpoints/<id>.json` to get existing context, merge new data, then:
 ```
-update_checkpoint(checkpoint_id, context: merged_context)
+codebyplan checkpoint update --id <id> --context <merged_context_json>
 ```
 
 ### Step 4: Show Result and Route
@@ -110,6 +110,6 @@ Otherwise, no follow-up directive — the user is back in control.
 
 ## Integration
 
-- **Reads**: MCP `get_current_task`, `get_checkpoints`
-- **Writes**: MCP `update_checkpoint`
+- **Reads**: `.codebyplan/state/session/current.json`, `checkpoints/<id>.json` (local-first; `npx codebyplan sync` if stale; break-glass: MCP `get_current_task`, `get_checkpoints`)
+- **Writes**: `codebyplan checkpoint update --id <id> [--field value ...]` (CLI write-through; break-glass: MCP `update_checkpoint`)
 - **Triggered by**: User directly, OR `/cbp-task-complete` Step 9c (expand path) — see `task-complete/reference/checkpoint-done-branching.md`

package/templates/skills/cbp-git-commit/SKILL.md

@@ -44,7 +44,7 @@ When a scope flag is used:
 **`--scope-task` Behavior:**
 
 When `--scope-task` is used:
-1. Read `task.files_changed[].path` via MCP `get_current_task`
+1. Read `task.files_changed[].path` from local state `.codebyplan/state/checkpoints/<id>/tasks/<id>.json` (on miss `npx codebyplan sync` once; MCP `get_current_task` as documented break-glass)
 2. Read currently-staged files via `git diff --cached --name-only`
 3. Compute intersection — only those paths are committed
 4. Foreign-staged files (in staged set but NOT in task) remain staged after the commit; user handles them in a separate commit
@@ -108,11 +108,14 @@ REPO_PATH="$(git rev-parse --show-toplevel)"
 
 **If `--files` provided:** Use the manual file list.
 
-**If `--scope-task`:** Resolve via MCP + intersection.
+**If `--scope-task`:** Resolve via local state + intersection.
 
 ```bash
-# 1. Read task.files_changed[]
-task_paths=$(mcp get_current_task | jq -r '.files_changed[].path')
+# 1. Read task.files_changed[] from local state (glob for active task file)
+#    On miss: npx codebyplan sync once, then re-read.
+#    MCP get_current_task as documented break-glass when state dir absent + sync fails.
+task_paths=$(cat .codebyplan/state/checkpoints/*/tasks/*.json 2>/dev/null \
+  | jq -r 'select(.status=="in_progress") | .files_changed[].path' | head -n 200)
 # 2. Read staged paths
 staged_paths=$(git diff --cached --name-only)
 # 3. Compute intersection
@@ -263,6 +266,7 @@ Stage the missing files or use --all.
 
 ## Integration
 
+- **Reads (--scope-task)**: Local state task file `.codebyplan/state/checkpoints/*/tasks/*.json` (in_progress); on miss `npx codebyplan sync` once; MCP `get_current_task` as documented break-glass when the state dir is absent and sync fails.
 - **Called by**: `/cbp-session-end`, `/cbp-task-complete`, `/cbp-checkpoint-complete`, manual
 - **Scope usage by commands**:
   - `/cbp-task-complete` -> `--no-push` (commit all staged)

package/templates/skills/cbp-git-worktree-remove/SKILL.md

@@ -135,12 +135,13 @@ After the git branch delete succeeds, run a conditional Supabase preview-branch
 
 > Lifecycle contract: see [[supabase-branch-lifecycle]].
 
-- Call `mcp__supabase__list_branches` with `project_id: rrvtrumtkhrsbhcyrwvf`.
+- Resolve the parent project ref: read `.codebyplan/shipment.json` `.shipment.surfaces.supabase.project_ref`; if absent or empty, read the first line of `supabase/.temp/project-ref`. Use that resolved ref as the `project_id`.
+- Call `mcp__supabase__list_branches` with the resolved `project_id`.
 - Scan the returned list for an entry whose `name` exactly equals `$BRANCH_NAME`.
 - If found: call `mcp__supabase__delete_branch` with its `branch_id`. Report "Supabase preview branch deleted: `$BRANCH_NAME`".
 - If not found: no-op silently — the GitHub integration may have already removed it on PR close; not-found is success, NOT an error.
 - If the `list_branches` call itself fails (network, auth, or a non-success response — distinct from a successful lookup that returns no match): emit a non-blocking warning that the Supabase preview branch for `$BRANCH_NAME` may still exist and should be verified in the dashboard. Do not treat an API failure as a not-found success.
-- Never delete the parent project `rrvtrumtkhrsbhcyrwvf` itself or any persistent/production branch.
+- Never delete the branch where `is_default` is true in the `list_branches` response (the production/parent project branch) or any other persistent/long-lived branch.
 
 ### Step 10: Show Result