codebyplan 1.13.39 → 1.13.40

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-merge-main/SKILL.md

@@ -122,10 +122,7 @@ This check is intentionally placed BEFORE Step 2's `git merge`: catching collisi
 
 1. List conflicted files and lock the count: `N=$(git diff --name-only --diff-filter=U | wc -l)`. `N` is the canonical conflict count used by Step 3.5 fallback message and Step 5 output; it stays fixed at the initial value across loop-backs.
 
-2. Load cross-reference context. Via MCP, gather all active CHK/TASK file ownership:
-   - `get_checkpoints(repo_id)` filtered to `status IN ('pending', 'active', 'in_progress')`.
-   - For each active checkpoint, also call `get_tasks(checkpoint_id)` and collect every `task.files_changed[].path` — checkpoint-bound task file ownership lives here, NOT on the checkpoint itself.
-   - `get_tasks(repo_id, standalone: true)` filtered to `status IN ('pending', 'in_progress')` — adds standalone-task file ownership.
+2. Load cross-reference context. Read local state files for per-task file ownership: `.codebyplan/state/checkpoints/<id>.json` (filtered to `status IN ('pending', 'active', 'in_progress')`) and `.codebyplan/state/checkpoints/<id>/tasks/*.json` (collect every `task.files_changed[].path`). On miss run `npx codebyplan sync` once and re-read. Use MCP `get_checkpoints` (active-filter multi-checkpoint scan) / `get_tasks` as documented break-glass when the state dir is absent and sync fails — the full cross-checkpoint scan requires MCP when local state is unavailable.
 
    Build a map `path -> [referencing CHK-NNN TASK-N + brief context]` by matching each conflicted path against:
    - `checkpoint.context.files_to_change[]` (checkpoint-level plan)
@@ -221,7 +218,7 @@ Return control to the caller. **This skill NEVER pushes** — the caller decides
   - `/cbp-task-complete` Step 5.5 (mandatory pre-push, after task commit)
   - `/cbp-checkpoint-end` Step 0 (mandatory pre-shipment)
   - User-invocable manually
-- **Reads**: `.codebyplan/git.json`, MCP `get_checkpoints`, MCP `get_tasks`, git state
+- **Reads**: `.codebyplan/git.json`, local state `.codebyplan/state/checkpoints/<id>.json` + `.../tasks/<id>.json`; on miss `npx codebyplan sync` once; MCP `get_checkpoints` (active-filter multi-checkpoint scan) / MCP `get_tasks` as documented break-glass when the state dir is absent and sync fails (full cross-checkpoint scan). Git state.
 - **Writes**: git merge commit (no MCP writes; no remote push)
 - **Spawns**: none (`/cbp-git-commit` is inline-triggered at Step 0 dirty-tree handling)
 - **Network**: contacts `origin` via `git fetch`. Offline = abort.

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

@@ -15,14 +15,14 @@ Inspect the resolved identifier from argument parsing to determine the task 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`. |
+| _(empty / free-text)_ | Check `get_current_standalone_task` first; if found → `standalone`. Else → `checkpoint` via `get_current_task`. (Kind-detection is MCP-unavoidable — no identifier yet means no local path to probe; subsequent operations are local-first per the rows below.) |
 
 Set `KIND` for the rest of this skill. MCP tool names vary by KIND:
 
 | Operation | `checkpoint` KIND | `standalone` KIND |
 |-----------|------------------|-------------------|
-| Get task | `get_current_task(repo_id)` | `get_current_standalone_task(repo_id)` |
-| Get rounds | `get_rounds(task_id)` | `get_standalone_rounds(standalone_task_id)` |
+| 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 | `add_round(task_id, ...)` | `add_standalone_round(standalone_task_id, ...)` |
 | Update round | `update_round(round_id, ...)` | `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 |
@@ -38,8 +38,8 @@ Run automated checks independently with mandatory execution. Updates round QA. H
 
 Use Kind Detection above to set KIND. Then:
 
-- **checkpoint KIND**: MCP `get_current_task(repo_id)` to find active task, then `get_rounds(task_id)` to find the in-progress round.
-- **standalone KIND**: MCP `get_current_standalone_task(repo_id)` to find active task, then `get_standalone_rounds(standalone_task_id)` to find the in-progress round.
+- **checkpoint KIND**: Read `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>.json` (local-first) to find active task, then read `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>/rounds/<roundId>.json` to find the in-progress round. If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_current_task(repo_id)` + `get_rounds(task_id)` when state dir is absent and sync fails.
+- **standalone KIND**: MCP `get_current_standalone_task(repo_id)` to find active task, then `get_standalone_rounds(standalone_task_id)` to find the in-progress round. (Standalone KIND still uses MCP until a later task.)
 
 ### Step 2: Determine Project Root
 
@@ -83,7 +83,9 @@ Scan all captured output for:
 
 ### Step 6: Save QA Results
 
-Update round QA via MCP `update_round(round_id, qa: ...)` (checkpoint KIND) or `update_standalone_round(standalone_round_id, qa: ...)` (standalone KIND):
+Update round QA:
+- **checkpoint KIND**: `codebyplan round update --id <round_id> --task-id <task_id> --checkpoint-id <checkpoint_id> --qa '<json>'` (CLI write-through: local state file + REST). Break-glass fallback: MCP `update_round(round_id, qa: ...)` when the CLI is unavailable.
+- **standalone KIND**: MCP `update_standalone_round(standalone_round_id, qa: ...)`. (Standalone KIND still uses MCP until a later task.)
 
 ```json
 {
@@ -123,6 +125,8 @@ If soft failures only: `Run /cbp-round-start to trigger auto-fix, or fix manuall
 
 ## Integration
 
-- **Reads**: MCP `get_current_task` / `get_current_standalone_task`, `get_rounds` / `get_standalone_rounds` (per KIND)
-- **Writes**: MCP `update_round` / `update_standalone_round` (qa field) — per KIND
+- **Reads (checkpoint KIND)**: `.codebyplan/state/checkpoints/<id>.json`, `checkpoints/<id>/tasks/<id>.json`, `checkpoints/<id>/tasks/<id>/rounds/<id>.json` (local-first; run `npx codebyplan sync` if missing; break-glass: MCP `get_current_task` / `get_rounds`)
+- **Reads (standalone KIND)**: MCP `get_current_standalone_task` / `get_standalone_rounds` (standalone KIND still uses MCP until a later task)
+- **Writes (checkpoint KIND)**: `codebyplan round update` (qa field). Break-glass: MCP `update_round`.
+- **Writes (standalone KIND)**: MCP `update_standalone_round` (qa field). (Standalone KIND still uses MCP until a later task.)
 - **Standalone**: Can be run independently at any time

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

@@ -15,14 +15,14 @@ Inspect the resolved identifier from argument parsing to determine the task 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`. |
+| _(empty / free-text)_ | Check `get_current_standalone_task` first; if found → `standalone`. Else → `checkpoint` via `get_current_task`. (Kind-detection is MCP-unavoidable — no identifier yet means no local path to probe; subsequent operations are local-first per the rows below.) |
 
 Set `KIND` for the rest of this skill. MCP tool names vary by KIND:
 
 | Operation | `checkpoint` KIND | `standalone` KIND |
 |-----------|------------------|-------------------|
-| Get task | `get_current_task(repo_id)` | `get_current_standalone_task(repo_id)` |
-| Get rounds | `get_rounds(task_id)` | `get_standalone_rounds(standalone_task_id)` |
+| 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)` |
 | Update round | `update_round(round_id, ...)` | `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 |
 
@@ -69,9 +69,9 @@ Given the parse from Step 1:
 
 | Parse | Resolution path |
 |-------|-----------------|
-| `{chk}-{task}-{round}` | MCP `get_checkpoints(repo_id)` → filter `number === {chk}`. MCP `get_tasks(checkpoint_id)` → filter `number === {task}`. MCP `get_rounds(task_id)` → filter `number === {round}`. |
-| `{task}-{round}` | MCP `get_standalone_rounds` via `get_current_standalone_task` or direct task lookup → filter `number === {round}`. |
-| _(empty)_ | Use Kind Detection: checkpoint KIND → MCP `get_current_task(repo_id)` + `get_rounds(task_id)`; standalone KIND → MCP `get_current_standalone_task(repo_id)` + `get_standalone_rounds(standalone_task_id)`. |
+| `{chk}-{task}-{round}` | **checkpoint KIND** — Read `.codebyplan/state/checkpoints/<checkpointId>.json` (local-first). If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_checkpoints(repo_id)` → `get_tasks` → `get_rounds` when state dir is absent and sync fails. Filter by `number` fields to match `{chk}`, `{task}`, `{round}`. |
+| `{task}-{round}` | **standalone KIND** — MCP `get_standalone_rounds` via `get_current_standalone_task` or direct task lookup → filter `number === {round}`. (Standalone KIND still uses MCP until a later task.) |
+| _(empty)_ | Use Kind Detection: **checkpoint KIND** → Read `.codebyplan/state/` local files for active task + latest round (break-glass: MCP `get_current_task(repo_id)` + `get_rounds(task_id)`); **standalone KIND** → MCP `get_current_standalone_task(repo_id)` + `get_standalone_rounds(standalone_task_id)`. |
 
 If no task found: `No active task. Nothing to complete.`
 
@@ -108,7 +108,7 @@ This is the **single** explicit reconcile owned by this skill. (The `cbp-mcp-rou
 
 Calculate duration from the round's `started_at` to now in minutes.
 
-- **checkpoint KIND**: MCP `complete_round(round_id, duration_minutes)`.
+- **checkpoint KIND**: `codebyplan round complete --id <round_id> --task-id <task_id> --checkpoint-id <checkpoint_id>` (CLI write-through: local state file + REST). Break-glass fallback: MCP `complete_round(round_id, duration_minutes)` when the CLI is unavailable. Note: the CLI does not accept `duration_minutes`; the backend computes duration server-side.
 - **standalone KIND**: MCP `complete_standalone_round(standalone_round_id, duration_minutes, caller_worktree_id)`. ⚠️ `caller_worktree_id` is REQUIRED — resolve via `CALLER_WT=$(npx codebyplan resolve-worktree 2>/dev/null)`. If `CALLER_WT` is empty, surface this warning and ask the user to confirm before proceeding:
 
   ```
@@ -145,7 +145,11 @@ Calculate duration from the round's `started_at` to now in minutes.
     another round.
     ```
 
-Persist a breadcrumb on the round via `update_round` / `update_standalone_round` per KIND: `round.context.round_complete = { staged_count, unstaged_count, route, decided_at }`.
+Persist a breadcrumb on the round:
+- **checkpoint KIND**: `codebyplan round update --id <round_id> --task-id <task_id> --checkpoint-id <checkpoint_id> --context '<json>'` (CLI write-through). Break-glass fallback: MCP `update_round(round_id, ...)` when the CLI is unavailable.
+- **standalone KIND**: MCP `update_standalone_round(standalone_round_id, ...)` (standalone KIND still uses MCP until a later task).
+
+Payload: `round.context.round_complete = { staged_count, unstaged_count, route, decided_at }`.
 
 ## Key Rules
 
@@ -159,6 +163,8 @@ Persist a breadcrumb on the round via `update_round` / `update_standalone_round`
 
 - **Gates**: `ask`-tier `Skill(cbp-round-complete)` permission prompt — the harness confirms before the skill runs; a decline makes NO writes. There is no in-skill AskUserQuestion.
 - **Triggered by**: `/cbp-round-update` (auto, clean triage), or user manually
-- **Reads**: MCP `get_current_task` / `get_current_standalone_task`, `get_rounds` / `get_standalone_rounds` (per KIND); delegates git+approval sync to `npx codebyplan round sync-approvals`
-- **Writes**: MCP `complete_round` / `complete_standalone_round` (per KIND); `update_round` / `update_standalone_round` (`round_complete` breadcrumb); round+task `files_changed` written by the CLI
+- **Reads (checkpoint KIND)**: `.codebyplan/state/checkpoints/<id>.json`, `.codebyplan/state/checkpoints/<id>/tasks/<id>.json`, `.codebyplan/state/checkpoints/<id>/tasks/<id>/rounds/<id>.json` (local-first; run `npx codebyplan sync` if missing; break-glass: MCP `get_current_task` / `get_rounds`). Delegates git+approval sync to `npx codebyplan round sync-approvals`.
+- **Reads (standalone KIND)**: MCP `get_current_standalone_task` / `get_standalone_rounds` (standalone KIND still uses MCP until a later task).
+- **Writes (checkpoint KIND)**: `codebyplan round complete` (Step 3); `codebyplan round update` (Step 4 breadcrumb). Break-glass: MCP `complete_round` / `update_round`. Round+task `files_changed` written by the CLI sync-approvals.
+- **Writes (standalone KIND)**: MCP `complete_standalone_round` / `update_standalone_round` (standalone KIND still uses MCP until a later task).
 - **Triggers**: `/cbp-task-check` (checkpoint KIND, all files approved), `/cbp-standalone-task-check` (standalone KIND, all files approved), `/cbp-round-input` (some files unapproved — fires independent of staging count)

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

@@ -27,8 +27,9 @@ This skill operates on the **active** task/round resolved via MCP `get_current_t
 
 ### Step 1: Get Current Task and Round
 
-Use MCP `get_current_task` with repo_id (pass `checkpoint_id` if known to avoid disambiguation) to find the active task.
-Use MCP `get_rounds` for the task to find the in-progress round.
+Read `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>.json` (local-first) to find the active task. 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).
+
+Read `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>/rounds/<roundId>.json` (local-first) to find the in-progress round. Same sync / break-glass pattern (MCP `get_rounds` as fallback).
 
 Load round context with all outputs (executor_output, testing_qa_output, reviewer_output).
 
@@ -70,11 +71,9 @@ Merge with previous rounds (supersede items for re-modified files, preserve veri
 
 ### Step 4: Update Task Files and QA
 
-Update via MCP:
-
-- `update_task(task_id, files_changed: [...])` — merge with existing
-- `update_round(round_id, files_changed: [...], qa: {items: [auto_qa items + default_checklist items]})` — round-specific
-- `update_task(task_id, qa: {items: [auto_qa items + default_checklist items]})` — aggregated
+- **Round files + QA**: `codebyplan round update --id <round-id> --task-id <uuid> --checkpoint-id <uuid> --files-changed <json> --qa <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.
+- **Task files_changed merge**: `codebyplan task update --id <task-id> --checkpoint-id <uuid> --files-changed <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.
+- **Task QA aggregated**: `codebyplan task update --id <task-id> --checkpoint-id <uuid> --qa <json>` (same CLI write-through). Break-glass: MCP `update_task`.
 
 ### Step 5: Present Summary
 
@@ -149,7 +148,7 @@ Example tables and the in-scope/out-of-scope classification: see `reference/find
 Step 7 already auto-applied in-scope findings and logged them to `round.context.inline_fix_log`. Now record any out-of-scope findings and route:
 
 1. **Polish-spiral stop-gate** (round 2+ only): if this is round 2 or later AND the prior round also ended with code-review fixes, surface a one-line stop-gate via AskUserQuestion — *defer remaining polish to a follow-up task* vs *continue with another round*. This is a genuine user decision about scope (it guards against endless low-value polish loops), not a flow-control prompt. Skip on round 1.
-2. Save out-of-scope findings (those NOT auto-applied in Step 7) to round context via MCP `update_round`:
+2. Save out-of-scope findings (those NOT auto-applied in Step 7) to round context via `codebyplan round update --id <round-id> --task-id <uuid> --checkpoint-id <uuid> --context <json>` (break-glass: MCP `update_round`):
    ```json
    {
      "context": {
@@ -169,7 +168,7 @@ Step 7 already auto-applied in-scope findings and logged them to `round.context.
 ## Integration
 
 - **Triggered by**: `/cbp-round-execute` (auto, after all waves + testing complete)
-- **Reads**: MCP `get_current_task`, `get_rounds`, round context
-- **Writes**: MCP `update_round`, `update_task` (files_changed, qa, findings)
+- **Reads**: `.codebyplan/state/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)
+- **Writes**: `codebyplan round update` (Step 4 round files/QA, Step 8 findings; break-glass: MCP `update_round`), `codebyplan task update` (Step 4 files_changed + QA aggregated; break-glass: MCP `update_task`)
 - **Spawns**: `cbp-improve-round` (code quality review)
 - **Triggers**: `/cbp-round-update` (auto, after findings handled)

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

@@ -27,8 +27,9 @@ This skill operates on the **active** task/round resolved via MCP `get_current_t
 
 ### Step 1: Get Current Task and Round
 
-Use MCP `get_current_task` with repo_id (pass checkpoint_id if known) to find the active task.
-Use MCP `get_rounds` for the task to find the in-progress round.
+Read `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>.json` (local-first) to find the active task. 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).
+
+Read `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>/rounds/<roundId>.json` (local-first) to find the in-progress round. Same sync / break-glass pattern (MCP `get_rounds` as fallback).
 
 If no in-progress round: `No active round. Run /cbp-round-start first.`
 
@@ -182,7 +183,7 @@ Per-wave hard-fail signal — true when ANY hold:
 **All waves hard_fail: false** → proceed to Step 7. **Any wave hard_fail: true**:
 
 - **Simple fixes** (type errors, lint, missing imports, test assertion fixes, e2e `real`-category with clear code-side root cause, no prior re-trigger this round) → save failure details to round context; retrigger the failing wave's executor; re-run testing-qa AND the eligible `cbp-e2e-*` specialists for that wave.
-- **Structural OR already re-triggered once OR e2e preflight aborts OR `e2e_eligible_skipped`** → save failure context via MCP `update_round`; auto-trigger `/cbp-round-input`. STOP.
+- **Structural OR already re-triggered once OR e2e preflight aborts OR `e2e_eligible_skipped`** → save failure context via `codebyplan round update` (break-glass: MCP `update_round`); auto-trigger `/cbp-round-input`. STOP.
 
 ## Inline execution fallback
 
@@ -194,7 +195,7 @@ When `cbp-testing-qa-agent` spawn fails OR the resolved `testing_profile` is `cl
 
 ### Step 7: Save Executor Output
 
-Update round context via MCP `update_round`:
+`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.
 
 - `context`: { ...existing, executor_output, testing_qa_output, e2e_eligible, e2e_outputs, frontend_ui_review }
 
@@ -220,8 +221,8 @@ Trigger `/cbp-round-end`.
 
 ## Integration
 
-- **Reads**: MCP `get_current_task`, `get_rounds`
-- **Writes**: MCP `update_round` (context with executor_output + testing_qa_output + e2e_eligible + e2e_outputs + frontend_ui_review)
+- **Reads**: `.codebyplan/state/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)
+- **Writes**: `codebyplan round update --id <uuid> --task-id <uuid> --checkpoint-id <uuid>` (Steps 6+7 — context with executor_output + testing_qa_output + e2e_eligible + e2e_outputs + frontend_ui_review; break-glass: MCP `update_round`)
 - **Spawns**: `cbp-round-executor` (per wave or single), `cbp-testing-qa-agent` (per wave, parallel sibling of the `cbp-e2e-*` specialists), the `cbp-e2e-*` specialists (config-driven dispatch per `context/testing/e2e.md`, one per eligible framework in `.codebyplan/e2e.json`), `cbp-database-agent` (if DB work), `cbp-security-agent` (if security review needed)
 - **Skill invocations**: `cbp-frontend-ui` at Step 5b with `phase: 'screenshot_review'` (post-e2e)
 - **Triggers**: `/cbp-round-end` (auto)

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

@@ -14,14 +14,14 @@ Inspect the resolved identifier from argument parsing to determine the task 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`. |
+| _(empty / free-text)_ | Check `get_current_standalone_task` first; if found → `standalone`. Else → `checkpoint` via `get_current_task`. (Kind-detection is MCP-unavoidable — no identifier yet means no local path to probe; subsequent operations are local-first per the rows below.) |
 
 Set `KIND` for the rest of this skill. MCP tool names vary by KIND:
 
 | Operation | `checkpoint` KIND | `standalone` KIND |
 |-----------|------------------|-------------------|
-| Get task | `get_current_task(repo_id)` | `get_current_standalone_task(repo_id)` |
-| Get rounds | `get_rounds(task_id)` | `get_standalone_rounds(standalone_task_id)` |
+| 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 | `add_round(task_id, ...)` | `add_standalone_round(standalone_task_id, ...)` |
 | Update round | `update_round(round_id, ...)` | `update_standalone_round(standalone_round_id, ...)` |
 | Update task | `update_task(task_id, ...)` | `update_standalone_task(standalone_task_id, ...)` |
@@ -64,9 +64,13 @@ If the argument matches the numeric regex, resolve the target task/round from DB
 
 ### Step 2: Deep Analysis (MANDATORY — always runs)
 
-**2a:** Load task via KIND-appropriate MCP tool (`get_current_task` or `get_current_standalone_task`) — get `files_changed`, `requirements`, `context`, `qa`
+**2a:** Load task:
+- **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(repo_id)` when state dir is absent and sync fails. Get `files_changed`, `requirements`, `context`, `qa`.
+- **standalone KIND** — MCP `get_current_standalone_task(repo_id)`. (Standalone KIND still uses MCP until a later task.)
 
-**2b:** Load all rounds via MCP `get_rounds(task_id)` (checkpoint KIND) or `get_standalone_rounds(standalone_task_id)` (standalone KIND) — get previous round context, testing-qa output
+**2b:** 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, testing-qa output.
+- **standalone KIND** — MCP `get_standalone_rounds(standalone_task_id)`.
 
 **2c:** Identify unapproved files from `task.files_changed` where `user_approved === false`
 
@@ -144,10 +148,12 @@ Based on the analysis + user input, create detailed requirements that:
 
 If the new round requirements change the task direction:
 
-1. Update task context via MCP `update_task(task_id, context: { ... })` / `update_standalone_task(standalone_task_id, context: { ... })` per KIND:
+1. Update task context per KIND:
+   - **checkpoint KIND**: `codebyplan task update --id <task_id> --checkpoint-id <checkpoint_id> --context '<json>'` (CLI write-through: local state file + REST). Break-glass fallback: MCP `update_task(task_id, context: { ... })` when the CLI is unavailable.
+   - **standalone KIND**: MCP `update_standalone_task(standalone_task_id, context: { ... })`. (Standalone KIND still uses MCP until a later task.)
    - Add new decisions to `context.decisions[]`
    - Update `context.discoveries[]` if applicable
-2. If checkpoint-level changes needed (checkpoint KIND only), update checkpoint context via MCP `update_checkpoint`
+2. If checkpoint-level changes needed (checkpoint KIND only): `codebyplan checkpoint update --id <checkpoint_id> --context '<json>'` (CLI write-through). Break-glass fallback: MCP `update_checkpoint`.
 
 ### Step 7: Auto-trigger Round Start
 
@@ -166,14 +172,18 @@ Trigger `/cbp-round-start` with the round requirements as arguments.
 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 use the appropriate MCP tool to load checkpoint + task
-3. Use MCP `get_rounds(task_id)` / `get_standalone_rounds(standalone_task_id)` per KIND to load round history
+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 2 (deep analysis handles all context loading)
 
 ## Key Rules
 
 - **Deep analysis is MANDATORY** — always runs, even if arguments provided (for context)
-- **Analysis reads from DB (MCP)**, not conversation history
+- **Analysis reads from local state first**, falling back to MCP only when state files are absent and sync fails
 - **Follow-up rounds get same depth as round 1** — no quick-fix behavior
 - **Never ask to git add** — user file approval (git staging) is reconciled by `/cbp-round-complete`
 - **Update all context locations** — task, checkpoint, and round should all have consistent information
@@ -181,6 +191,8 @@ If this command is triggered **directly** (not via `/cbp-todo`) and no context i
 ## Integration
 
 - **Triggered by**: `/cbp-round-update` (auto, not-clean triage), `/cbp-round-complete` (auto, files left unapproved after completing the round), `/cbp-round-execute` (auto, on hard-fail after retry exhausted), `/cbp-todo` (after /clear), user manually
-- **Reads**: MCP `get_current_task` / `get_current_standalone_task`, `get_rounds` / `get_standalone_rounds` (per KIND), file contents (Read tool)
-- **Writes**: MCP `update_task` / `update_standalone_task` (context), `update_checkpoint` (context, if checkpoint KIND and needed)
+- **Reads (checkpoint KIND)**: `.codebyplan/state/checkpoints/<id>.json`, `checkpoints/<id>/tasks/<id>.json`, `checkpoints/<id>/tasks/<id>/rounds/*.json` (local-first; break-glass: MCP `get_current_task` / `get_rounds`), file contents (Read tool)
+- **Reads (standalone KIND)**: MCP `get_current_standalone_task` / `get_standalone_rounds` (standalone KIND still uses MCP until a later task)
+- **Writes (checkpoint KIND)**: `codebyplan task update` (context), `codebyplan checkpoint update` (context, if needed). Break-glass: MCP `update_task` / `update_checkpoint`.
+- **Writes (standalone KIND)**: MCP `update_standalone_task` / (checkpoint via MCP `update_checkpoint` if needed). (Standalone KIND still uses MCP until a later task.)
 - **Triggers**: `/cbp-round-start` (auto)