codebyplan 1.5.0 → 1.8.0

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

@@ -0,0 +1,239 @@
+---
+scope: org-shared
+name: cbp-task-start
+description: Start a task, load context from DB
+triggers: [cbp-round-start]
+argument-hint: [chk-task | task]  # e.g. `108-1` (CHK-108 TASK-1) or `45` (standalone TASK-45)
+effort: xhigh
+---
+
+# Task Start Command
+
+Start a task by loading context from the database and preparing for work.
+
+## Instructions
+
+### Step 1: Parse `$ARGUMENTS`
+
+Parse the argument using the canonical chk-task-round notation (see `.claude/rules/notation-consistency.md`):
+
+| Shape | Regex | Resolves to |
+|-------|-------|-------------|
+| `{chk}-{task}` (e.g. `108-1`) | `^[0-9]+-[0-9]+$` | Checkpoint-bound: CHK-{chk} TASK-{task} |
+| `{task}` (e.g. `45`) | `^[0-9]+$` | Standalone: standalone TASK-{task} **only** (bare number = standalone discriminator) |
+| _(empty)_ | — | Use MCP `get_current_task` to find the next pending task |
+
+Anything else is malformed — surface this error and stop:
+
+```
+task-start: invalid argument `{value}`. Expected:
+  108-1  → CHK-108 TASK-1 (checkpoint-bound)
+  45     → standalone TASK-45
+  (empty) → next pending task
+
+For a specific round, use `/cbp-round-start 108-1-2`.
+```
+
+Error cases: `108-1-2` (that is round-start's shape), `abc`, `108-`, `-1`, `108--1`, anything with whitespace or non-numeric characters.
+
+**BREAKING from prior behaviour**: bare-number now resolves to **standalone only**. Previously `task-start 45` would match the first TASK-45 it found anywhere; that heuristic is removed. To target a checkpoint-bound TASK-45, use `{chk}-45`.
+
+#### Worked examples
+
+- `task-start 108-1` → CHK-108 TASK-1
+- `task-start 45` → standalone TASK-45 (errors if no standalone TASK-45 exists)
+- `task-start` (no arg) → next pending via `get_current_task`
+- `task-start 108-1-2` → error: "use `/cbp-round-start 108-1-2`"
+- `task-start abc` → error: malformed
+- `task-start 108-` → error: malformed
+
+### Step 2: Resolve Checkpoint and Task
+
+Given the parse from Step 1:
+
+| Parse | Resolution path |
+|-------|-----------------|
+| `{chk}-{task}` | MCP `get_checkpoints(repo_id)` → filter `number === {chk}` (must exist). MCP `get_tasks(checkpoint_id)` → filter `number === {task}` (must exist). |
+| `{task}` | MCP `get_tasks(repo_id, standalone: true)` → filter `number === {task}` (must exist). Checkpoint context is null for the rest of the skill. |
+| _(empty)_ | MCP `get_current_task(repo_id)` — output gives both checkpoint (if any) and task. When multiple checkpoints are active and the result is ambiguous, surface the disambiguation prompt and stop. |
+
+If any required row is missing, surface this and stop:
+
+```
+task-start: no task found for `{ARG}`.
+  - For `108-1`: CHK-108 may not exist, or TASK-1 may not exist within it.
+  - For `45`: no standalone TASK-45 exists. If a checkpoint-bound TASK-45 exists, invoke as `{chk}-45`.
+```
+
+### Step 3: Branch Auto-Handling
+
+The task MUST run on its target feat branch. Claude switches/creates that branch automatically — never asks the user to do it.
+
+#### 3.1 — Determine the target branch
+
+Read `.codebyplan/git.json`:
+- `branch_config.protected` (fall back to `["main", "development"]`)
+- `branch_config.integration` (fall back to `"development"`)
+
+Compute `TARGET`:
+
+| Task type | TARGET |
+|-----------|--------|
+| Checkpoint-bound, `checkpoint.branch_name` set | `checkpoint.branch_name` (e.g. `feat/CHK-095-pricing-page`) |
+| Checkpoint-bound, `branch_name` null (legacy) | `feat/CHK-{NNN}-{kebab-slug-from-checkpoint-title}` |
+| Standalone | `feat/standalone-TASK-{N}-{kebab-slug-from-task-title}` |
+
+Slug rules: lowercase, words joined by `-`, drop punctuation, truncate to 40 chars.
+
+#### 3.2 — Compare current branch
+
+Run `git branch --show-current`. If `current == TARGET` → continue to Step 3b. Done.
+
+#### 3.3 — Switch automatically (no AskUserQuestion, no blocking)
+
+Run the switch directly. Three sub-cases, in order:
+
+```bash
+# (a) target exists locally
+if git rev-parse --verify "$TARGET" >/dev/null 2>&1; then
+  git checkout "$TARGET"
+
+# (b) target exists on origin (track it)
+elif git rev-parse --verify "origin/$TARGET" >/dev/null 2>&1; then
+  git checkout -t "origin/$TARGET"
+
+# (c) target doesn't exist — create from integration branch
+else
+  # First make sure integration is up to date
+  git fetch origin "$INTEGRATION" 2>/dev/null || true
+  git checkout -b "$TARGET" "origin/$INTEGRATION" 2>/dev/null \
+    || git checkout -b "$TARGET" "$INTEGRATION"
+fi
+```
+
+**Carrying uncommitted work** — `git checkout` carries clean (non-conflicting) working-tree changes to the new branch automatically. This is intended: changes made on `development` while preparing the task move with the user to the new feat branch. No `git stash`, ever (per `git-safety.md`). No `git add`, ever (per `git-workflow.md`).
+
+**If `git checkout` exits non-zero** (typically "would clobber" because a tracked file has unstaged changes that conflict with target's version): surface the raw git error verbatim, stop, do NOT attempt recovery. The user resolves and re-invokes. This is the only case where `/cbp-task-start` halts on branch state.
+
+#### 3.4 — Persist + verify
+
+After successful switch:
+
+1. Re-run `git branch --show-current` to confirm `current == TARGET`. If not, fail loudly — something raced.
+2. **Persist for next time**:
+   - Standalone task → `update_task(task_id, context: { ...task.context, branch_name: TARGET })`
+   - Checkpoint with `branch_name: null` → `update_checkpoint(checkpoint_id, branch_name: TARGET)`
+   - Checkpoint with existing `branch_name` → no write (already canonical)
+3. One-line confirmation in output: `Branch: [TARGET] (switched from [previous])`. No prompt, no waiting.
+
+#### 3.5 — Protected-branch sanity (defensive)
+
+After all of the above, `current` should be a feat branch by construction. If somehow it's still in `branch_config.protected` (e.g. TARGET resolved to "development" because a checkpoint has a malformed `branch_name`), THEN block with a hard error citing the bad config — this is a data bug, not a user workflow problem.
+
+### Step 3b: Clean Slate
+
+Before loading context, ensure a clean working tree:
+
+1. Run `git status --short` to check for uncommitted files
+2. If uncommitted files exist → commit them with message `chore: clean slate for task start`. **Prefer plain `git add -A && git commit -m "..."` over MCP `git_commit`** — the MCP variant resolves to the main repo path and silently fails inside a worktree.
+3. This ensures the task starts with a clean working tree so all file changes during the task are properly tracked
+
+### Step 3c: CVE/GHSA Audit Sweep
+
+Skip this step if the task title and requirements contain no CVE ID (`CVE-YYYY-NNNNN`) or GHSA ID (`GHSA-xxxx-xxxx-xxxx`). Otherwise:
+
+1. Run `pnpm audit --json` from the monorepo root. If it fails (network, registry), surface the error and stop — do NOT start a CVE task without a clean snapshot.
+2. Parse the advisory list from the JSON output.
+3. Call MCP `get_tasks(repo_id)`; for each advisory, match by ID in task title/requirements.
+4. For every advisory with no matching open task, call MCP `create_task` per `immediate-issue-capture.md`.
+5. Report the sweep result:
+   ```
+   ## CVE/GHSA Audit Sweep
+   - Total advisories: N
+   - Already tracked: M
+   - Newly captured: K (TASK-a, TASK-b, …)
+   ```
+
+See `dependency-vulnerability-fixes.md` "Audit Sweep at Task Start" for the source rule.
+
+### Step 3.5: Worktree-Match Verification
+
+Before activating the task, verify the caller's worktree matches the assigned worktree on the target row. (Per CHK-104 TASK-2 — DB-level hard-lock prevents cross-worktree mutations.)
+
+1. Read caller worktree: `CALLER_WT=$(npx codebyplan resolve-worktree 2>/dev/null)`. If empty, the `caller_worktree_id` parameter is omitted from the MCP call entirely — the pre-guard is skipped and the update proceeds without a worktree check (backwards-compat).
+2. Determine target worktree:
+   - **Checkpoint-bound tasks**: `TARGET_WT = checkpoint.worktree_id` (read from MCP `get_checkpoints`). Note: checkpoint-bound tasks may have a NULL `task.assigned_worktree_id` because the lock lives on the parent checkpoint — fall through to `checkpoint.worktree_id`.
+   - **Standalone tasks**: `TARGET_WT = task.assigned_worktree_id`.
+3. If `TARGET_WT IS NOT NULL AND TARGET_WT != CALLER_WT`, surface this error and abort:
+
+   ```
+   TASK-N is assigned to worktree {TARGET_WT_NAME} ({TARGET_WT}); current worktree is {CALLER_WT_NAME} ({CALLER_WT}).
+   Use the release_assignment MCP tool (requires maintainer role) if {TARGET_WT_NAME} is dead, then re-run /cbp-task-start.
+   ```
+
+4. If `TARGET_WT IS NULL` or matches, proceed.
+
+### Step 3.6: Integration Drift Check (optional)
+
+Before loading context, check if the feat branch has drifted from integration. Soft-skip on fetch failure (this gate is optional, not mandatory).
+
+1. Run `git fetch origin {INTEGRATION}` where `{INTEGRATION}` comes from `.codebyplan/git.json` `branch_config.integration` (default `development`). If fetch fails (offline, auth), skip this entire step silently and proceed to Step 4.
+2. Compute: `BEHIND=$(git rev-list --count HEAD..origin/{INTEGRATION})`.
+3. Compute `LAST_FETCH_AGE_HOURS` from the mtime of `.git/FETCH_HEAD` relative to now.
+4. If `BEHIND >= 10` OR `LAST_FETCH_AGE_HOURS > 24`: surface AskUserQuestion:
+
+   ```
+   Feat branch is {BEHIND} commits behind origin/{INTEGRATION} (last fetch {AGE}h ago).
+   Merge integration now before starting the task?
+   A) Yes — run /cbp-merge-main (recommended)
+   B) No — continue without merging
+   ```
+
+5. On **A**: trigger `/cbp-merge-main`. Wait for completion. If it fails (this is a hard stop — the user consented to the merge, so failure means the branch cannot safely proceed), surface the error and STOP `/cbp-task-start`.
+6. On **B**, or if `BEHIND < 10` AND `LAST_FETCH_AGE_HOURS <= 24`: proceed silently to Step 4.
+
+### Step 4: Load Context
+
+Load context from DB:
+
+1. **Checkpoint context**: decisions, discoveries, dependencies, constraints
+2. **Task context**: task-specific decisions and requirements
+3. **Task research**: if any research was done
+4. **Previous rounds**: check for completed rounds via MCP `get_rounds`
+
+Display context summary:
+
+```
+## Starting Task: TASK-[N]
+
+**Checkpoint**: CHK-[NNN] - [title]
+**Task**: [title]
+**Requirements**: [requirements]
+
+### Context
+- **Decisions**: [list locked decisions relevant to this task]
+- **Dependencies**: [relevant dependencies]
+- **Previous rounds**: [count] completed
+```
+
+### Step 5: Set Task Status
+
+Use MCP `update_task(task_id, status: "in_progress")`.
+
+If worktree_id present, include `claim_worktree_id` to auto-claim the checkpoint AND `caller_worktree_id: CALLER_WT` so the MCP server's pre-guard accepts the call (CHK-104 TASK-2 hard-lock).
+
+### Step 6: Auto-trigger Round Start
+
+Automatically trigger `/cbp-round-start` for the first round. Do NOT wait for user input.
+
+```
+Starting first round...
+```
+
+Trigger `/cbp-round-start` (which will use task.requirements for round 1).
+
+## Integration
+
+- **Reads**: MCP `get_current_task`, `get_tasks`, `get_rounds`
+- **Writes**: MCP `update_task`
+- **Triggers**: `/cbp-round-start` (auto, round 1)

package/templates/skills/cbp-task-testing/SKILL.md

@@ -0,0 +1,277 @@
+---
+scope: org-shared
+name: cbp-task-testing
+description: Run comprehensive task-level testing after /cbp-task-check passes
+argument-hint: [chk-task | task]
+triggers: [cbp-task-complete]
+effort: xhigh
+---
+
+# Task Testing Command
+
+Comprehensive task-level testing — runs all automated tests and walks the user through manual testing one-by-one. Distinct from round-level testing (`testing-qa-agent`): this tests the **entire delivered feature holistically** after all rounds are complete. Runs inline — no sub-agent.
+
+## When Used
+
+- After `/cbp-task-check` passes with READY verdict (auto-triggered)
+- Before `/cbp-task-complete`
+- **Never skippable**
+
+## Scope vs Round-Level Validation
+
+Per-wave `testing-qa-agent` runs inside `/cbp-round-execute` Step 5. This skill adds the cross-cutting layer that is only visible across the full task diff: full-repo lint, workspace tsc, full test suite, `pnpm audit`, and full-diff security scan — each run once here, not per-round.
+
+## Instructions
+
+### Step 1: Parse `$ARGUMENTS`
+
+Parse the argument using the canonical chk-task-round notation (see `.claude/rules/notation-consistency.md`):
+
+| Shape | Regex | Resolves to |
+|-------|-------|-------------|
+| `{chk}-{task}` (e.g. `108-1`) | `^[0-9]+-[0-9]+$` | Checkpoint-bound: CHK-{chk} TASK-{task} |
+| `{task}` (e.g. `45`) | `^[0-9]+$` | Standalone: standalone TASK-{task} **only** |
+| _(empty)_ | — | Use MCP `get_current_task` to find the active in-progress task |
+
+Anything else is malformed — surface this error and stop:
+
+```
+task-testing: invalid argument `{value}`. Expected:
+  108-1  → CHK-108 TASK-1 (checkpoint-bound)
+  45     → standalone TASK-45
+  (empty) → active in-progress task
+
+For a specific round, use `/cbp-round-update 108-1-2`.
+```
+
+Error cases: `108-1-2` (that is round-update's shape), `abc`, `108-`, `-1`, `108--1`, anything with whitespace or non-numeric characters.
+
+#### Worked examples
+
+- `task-testing 108-1` → CHK-108 TASK-1
+- `task-testing 45` → standalone TASK-45
+- `task-testing` (no arg) → active in-progress task via `get_current_task`
+- `task-testing 108-1-2` → error: "use `/cbp-round-update 108-1-2`"
+- `task-testing abc` → error: malformed
+
+### Step 1.5: Get Current Task
+
+Given the parse from Step 1:
+
+| Parse | Resolution path |
+|-------|-----------------|
+| `{chk}-{task}` | MCP `get_checkpoints(repo_id)` → filter `number === {chk}`. MCP `get_tasks(checkpoint_id)` → filter `number === {task}`. |
+| `{task}` | MCP `get_tasks(repo_id, standalone: true)` → filter `number === {task}`. |
+| _(empty)_ | MCP `get_current_task(repo_id)` — finds the active in-progress task. |
+
+If no in-progress task, show error and stop.
+
+### Step 2: Verify All Rounds Complete
+
+Use MCP `get_rounds(task_id)`. Verify all rounds are `completed`. If any still `in_progress`:
+
+```
+## Cannot Run Task Testing
+
+TASK-[N] has an active round (Round [N]). Complete it first:
+- Run `/cbp-round-update` to finish the round
+```
+
+Stop.
+
+### Step 3: Verify `/cbp-task-check` Passed
+
+Check `task.context.check_verdict`: must exist and have `verdict = "READY"`. Otherwise:
+
+```
+## Cannot Run Task Testing
+
+`/cbp-task-check` has not passed yet. Run `/cbp-task-check` first.
+```
+
+Stop.
+
+### Step 4: Aggregate Files Changed
+
+Collect all `files_changed` from all rounds, deduplicate (latest action per path wins). Skip deleted files for file-reading in Step 5.
+
+### Step 5: Read ALL Final Changed Files
+
+Read every non-deleted file in the aggregated list. Understand the complete delivered work across all rounds. Build a mental model of what was built and how it connects.
+
+### Step 6: Run Comprehensive Automated Testing
+
+Capture stdout and stderr for each check.
+
+**Hard-fail tests** (block completion):
+
+| Category                | Command                         | Condition                        |
+| ----------------------- | ------------------------------- | -------------------------------- |
+| Full-repo lint          | `pnpm -w lint`                  | Always                           |
+| Full-repo types         | `pnpm exec tsc --noEmit`        | Source files changed             |
+| Full-repo unit tests    | `pnpm test --run`               | Source files in aggregated_files |
+| Full-repo audit         | `pnpm audit`                    | Always                           |
+| Per-package E2E         | `pnpm --filter <pkg> e2e:test`  | UI files in aggregated_files     |
+| Full-diff security scan | inline grep or `security-agent` | Always                           |
+
+Per-file lint + format are enforced by `lint-format-on-edit.sh` hook per edit. This step catches cross-package issues invisible to per-wave checks.
+
+**Soft tests** (report, don't block):
+
+| Category   | Method                                    | Condition                    |
+| ---------- | ----------------------------------------- | ---------------------------- |
+| Visual     | Screenshot compare via `e2e:visual-check` | UI work + dev server running |
+| API Health | `curl` health endpoint                    | API routes changed           |
+
+For each test, record: `category, status (pass|fail|skipped), details, stdout, stderr`.
+
+#### Step 6.x: Autonomous Sim Screenshot Validation (mobile / on-device)
+
+For mobile rounds (Maestro / XCUITest / Tauri-mobile) where unit tests passed but the round touched component-mount code paths (custom hooks, prop signatures, conditional renders, navigation tabs), unit-test green is NOT sufficient evidence that the screen mounts at runtime. Use the autonomous sim screenshot loop to catch runtime crashes invisible to mocked unit tests.
+
+**Procedure** (when iOS Simulator is the target — adapt the screenshot command for Android/Tauri equivalents):
+
+1. Confirm the target screen's default state via `Read` of its parent component or store.
+2. If the screen is normally gated behind a tab/route the simulator isn't currently on, temporarily flip the gating state's default value at the screen's entry point (`useState(initialTab) → useState('targetTab')` or equivalent) so the screen mounts on the next reload.
+3. Trigger a Fast Refresh by saving a touched file, then capture: `xcrun simctl io booted screenshot /tmp/codebyplan-task-testing-{task}-{state}.png`.
+4. Read the screenshot via the multimodal Read tool. Confirm the screen rendered (vs blank/crash/red-box error overlay).
+5. Revert the state-default flip from step 2. Confirm the file diff is empty (`git diff <path>`) before proceeding.
+
+**When to use**: round modifies hook usage, prop signatures, component-tree shape, or store subscriptions on a screen whose unit tests mock the data layer. Skip when the modified code path has no UI surface (pure utilities, server actions).
+
+**When NOT to use**: don't flip state defaults on the main app entry / auth gate / feature-flag boundaries — the revert risk is too high. Use storybook or a dedicated `__dev__` tab if the screen has cross-cutting state.
+
+Record the result in `task_testing_output.autonomous_sim_check`:
+
+```yaml
+autonomous_sim_check:
+  screen: "<screen-name>"
+  status: "rendered" | "crashed" | "blank"
+  screenshot_path: "/tmp/codebyplan-task-testing-..."
+  state_flip_reverted: true
+```
+
+This technique uniquely catches Rules-of-Hooks violations and prop-shape mismatches that mocked unit tests cannot detect — the runtime hook scheduler is the only oracle.
+
+### Step 6.5: Cross-Round Code Review
+
+Round-level code review runs per-round via `improve-round` at `/cbp-round-end`. This step adds the cross-round holistic layer — things only visible once all rounds are aggregated.
+
+Inline review (no sub-agent) across the aggregated files read in Step 5. Check:
+
+| Concern                   | What to Look For                                                                                                                                 |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Leftover debug            | `console.log`, `debugger`, commented-out blocks, `TODO`/`FIXME` added during this task                                                           |
+| Cross-round duplication   | Same helper/logic written independently in 2+ rounds — candidate for extraction                                                                  |
+| Convention drift          | One round introduces a pattern (error handling, naming, file layout) that contradicts a pattern established in an earlier round of the same task |
+| Incomplete follow-through | A round added a type/field/table column that later rounds never consume                                                                          |
+| Orphaned additions        | Exports or utilities added in an early round with no callers after later rounds refactored past them                                             |
+
+For each finding, record: `{category, file, description, severity: 'low'|'medium'|'high', suggested_fix}`.
+
+Findings with severity `medium` or `high` feed the Step 9 problem classification. `low` findings are recorded in `task_testing_output` for the record but do not block.
+
+If any finding points to a need that exceeds task scope (e.g. a utility worth extracting for the wider codebase, a convention the repo should adopt globally), route per `immediate-issue-capture.md` "How to Capture" — default to a NEW TASK in the current checkpoint, not a standalone task. Standalone routing applies only when the finding is genuinely off-axis from every active checkpoint AND the user has confirmed standalone routing.
+
+### Step 7: Separate Claude-Testable vs User-Testable
+
+**Claude handles automatically** (Step 6): build, types, unit tests, E2E tests, visual, API health.
+
+**User must verify** (requires human judgment):
+
+- Visual appearance quality (does it look good?)
+- UX flow (is the interaction intuitive?)
+- Business logic correctness (does it do the right thing?)
+- Edge cases (unusual inputs, boundary conditions)
+- Cross-browser / real-device behavior
+- Content accuracy (text, labels, messages)
+
+Generate user test items based on: task requirements, changed files, round context.
+
+### Step 8: User Testing Walkthrough
+
+Present all user-testable items as a **single checklist in one `AskUserQuestion` prompt**. Do not ask one question per item — the batched format is preferred.
+
+Format the question so every item is visible in the checklist, with a single overall answer (e.g., "all pass", "minor issues", "major issues"). Provide the description, how-to-test steps, and expected result per item inside the question body. If the user reports mixed results, collect the specifics in a follow-up.
+
+Record the aggregate response and any per-item notes.
+
+### Step 9: Classify Problems
+
+Collect failures from automated tests (Step 6), cross-round code review (Step 6.5, medium+), and user tests (Step 8). Classify:
+
+- **Minor** (round-fixable): styling, small bugs, missing edge cases, localized duplication
+- **Major** (new-task-worthy): architectural issues, missing features, fundamental design problems, convention drift that spans multiple files
+
+### Step 10: Save Results
+
+```ts
+update_task(task_id, {
+  context: {
+    ...existing,
+    task_testing_output: {
+      claude_tests: [...],
+      cross_round_code_findings: [...],   // from Step 6.5
+      user_tests: [...],
+      problems_found: [...],
+      all_passed: boolean,
+      summary: { total, passed, failed, pending }
+    }
+  }
+})
+```
+
+### Step 11: Route Based on Results
+
+**ALL PASS:**
+
+```
+All tests passed for TASK-[N]. Routing to task-complete...
+```
+
+Auto-trigger `/cbp-task-complete`.
+
+**Minor problems found:**
+
+---
+
+**Next:**
+Run `/cbp-round-input` to:
+
+- Address the minor issues found during testing
+- Create a focused round for fixes
+
+---
+
+Waiting for user to run `/cbp-round-input`.
+
+**Major problems found:**
+
+---
+
+**Next:**
+Run `/cbp-task-create` to:
+
+- Create a new task for the identified issues
+
+---
+
+Waiting for user to run `/cbp-task-create`.
+
+**User wants re-test:** Suggest re-running `/cbp-task-testing`.
+
+## Key Rules
+
+- **Never skippable** — mandatory before `/cbp-task-complete`
+- **Must loop until everything passes** — problems must be addressed
+- **No file changes** — testing only, never edit
+- **Batch user tests** — present all user-testable items in a single `AskUserQuestion` checklist; never one-per-question
+- **Read actual files** — do not rely on metadata alone
+- **Run actual commands** — capture real stdout/stderr
+
+## Integration
+
+- **Reads**: MCP `get_current_task`, `get_rounds`, all aggregated files
+- **Writes**: MCP `update_task` (context.task_testing_output)
+- **Triggers**: `/cbp-task-complete` (auto, when ALL PASS)
+- **Triggered by**: user runs `/cbp-task-testing {chk-task}` per directive from `/cbp-task-check` on READY verdict (after `/cbp-round-execute`-driven validation completed all rounds)

package/templates/skills/cbp-todo/SKILL.md

@@ -0,0 +1,97 @@
+---
+scope: org-shared
+name: cbp-todo
+description: Entry point - what to work on next
+effort: low
+---
+
+# Todo Command
+
+Single MCP call to determine next action, then load appropriate context before triggering the command. This is the **sole entry point** after `/clear` — it ensures Claude always has full context before any command runs.
+
+## Instructions
+
+### Step 0: Resolve Caller Worktree
+
+Before any MCP call, derive the caller's `worktree_id` at runtime via `npx codebyplan resolve-worktree` so downstream calls can identify this worktree for hard-lock enforcement (CHK-104 TASK-2). The CLI resolves the tuple (device_id, repo path, current branch) against the worktrees table; CHK-108 removed the legacy `worktree_id` field from `.codebyplan/repo.json`.
+
+```bash
+WORKTREE_ID=$(npx codebyplan resolve-worktree 2>/dev/null)
+```
+
+- **`WORKTREE_ID` non-empty** → forward as `worktree_id` to the `get_next_action` call in Step 1.
+- **`WORKTREE_ID` empty** → the current repo path + branch did not match any worktree row. The MCP server's hard-lock will reject mutations on assigned rows; surface a one-line note to the user that the worktree may need registration via `npx codebyplan setup` from this directory.
+
+### Step 1: Get Next Action
+
+Use MCP `get_next_action` with `repo_id` and `worktree_id` (if present from Step 0).
+
+### Step 2: Load Context Based on Command
+
+Before triggering the command, load the context it needs. This ensures `/clear` + `/cbp-todo` reliably restores full working context.
+
+**Use the context loading matrix below.** Match the `command` from the response to determine what to load.
+
+| Command Pattern | Context to Load |
+|----------------|-----------------|
+| `/cbp-session-start` | None — `/cbp-session-start` handles its own loading |
+| `/cbp-checkpoint-create` | If checkpoint exists in response context: load checkpoint via MCP `get_checkpoints` (filter by number). Display checkpoint title, goal, ideas summary |
+| `/cbp-task-start [N]` | Load via MCP `get_current_task`. Display checkpoint title + task title/requirements summary |
+| `/cbp-round-start` | Load via MCP `get_current_task` + `get_rounds(task_id)`. Display checkpoint + task + round count + last round summary |
+| `/cbp-round-update` | Load via MCP `get_current_task` + `get_rounds(task_id)`. Display checkpoint + task + files_changed approval summary |
+| `/cbp-round-input` | **Full context load** (see Step 2b) |
+| `/cbp-task-check` | Load via MCP `get_current_task`. Display checkpoint + task + files summary |
+| `/cbp-task-testing` | Load via MCP `get_current_task` + `get_rounds(task_id)`. Display checkpoint + task + testing status summary |
+| `/cbp-task-create` | Load via MCP `get_current_task`. Display checkpoint + task list summary |
+| `/cbp-task-complete` | Load via MCP `get_current_task`. Display checkpoint + task summary |
+| `/cbp-checkpoint-complete` | Load via MCP `get_current_task`. Display checkpoint summary |
+| *(no command / idle)* | See Step 3 — suggest `/cbp-session-end` |
+
+**For any unrecognized command:** Load via MCP `get_current_task` as a safe default. Display whatever context is available.
+
+### Step 2b: Full Context Load (for `/cbp-round-input`)
+
+This is the most context-dependent command. Load everything:
+
+1. **MCP `get_current_task`** — checkpoint (title, goal, context with decisions/discoveries) + task (title, requirements, context, files_changed, QA)
+2. **MCP `get_rounds(task_id)`** — all rounds for the task (requirements, context with executor_output/testing_qa_output, QA)
+
+Display a brief context summary:
+
+```
+## Context Loaded
+
+**Checkpoint**: CHK-[NNN] - [title]
+**Task**: TASK-[N] - [title]
+**Rounds completed**: [N]
+**Files**: [X] approved / [Y] total
+
+### Key Decisions:
+- [list locked decisions from checkpoint + task context]
+
+### Last Round:
+[Brief: what was done, what passed/failed]
+```
+
+### Step 3: Suggest Session End When Idle
+
+If `get_next_action` returns no actionable `command` (null, empty, or explicit idle/done signal) — i.e. no active checkpoint with pending work — **do not auto-trigger anything**. Instead, suggest ending the session:
+
+```
+No work remaining in the current checkpoint.
+
+Run `/cbp-session-end` to finalize the session log and close out.
+Or run `/cbp-checkpoint-create` to start new work.
+```
+
+Wait for the user. Do not auto-trigger `/cbp-session-end` — session wrap-up is a user-driven decision.
+
+### Step 4: Display and Auto-trigger
+
+If Step 3 found actionable work, show `instructions` from the get_next_action response (gives user a chance to see what's happening), then auto-trigger the `command`.
+
+## Integration
+
+- **Called by**: `/cbp-session-start`, `/cbp-task-complete`, `/cbp-checkpoint-complete`, manual, after `/clear`
+- **Reads**: MCP `get_next_action`, `get_current_task`, `get_rounds`, `get_checkpoints`
+- **Triggers**: `command` from response (auto)