codebyplan 1.5.1 → 1.9.0

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

@@ -0,0 +1,206 @@
+---
+scope: org-shared
+name: cbp-task-complete
+description: Complete current task
+argument-hint: [chk-task | task]
+effort: xhigh
+---
+
+# Task Complete Command
+
+Complete the current task. Auto-triggered by `/cbp-task-testing` when all tests pass. Can also be run manually.
+
+## 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-complete: 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-complete 108-1` → CHK-108 TASK-1
+- `task-complete 45` → standalone TASK-45
+- `task-complete` (no arg) → active in-progress task via `get_current_task`
+- `task-complete 108-1-2` → error: "use `/cbp-round-update 108-1-2`"
+- `task-complete 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 Rounds Complete and Validated
+
+Use MCP `get_rounds` for the task. Verify all rounds are `completed`.
+
+If any round is `in_progress`:
+
+```
+## Cannot Complete Task
+
+TASK-[N] has an active round (Round [N]). Run `/cbp-round-update` to finish it.
+```
+
+Stop here.
+
+Verify at least one round has `testing_qa_output` in its context. If not:
+
+```
+## Cannot Complete Task
+
+No testing-qa-agent validation found. Run `/cbp-round-start` to execute a validated round.
+```
+
+Stop here.
+
+### Step 2.5: Verify `/cbp-task-check` Has Run
+
+`task.context.check_verdict` must exist and have `verdict: 'READY'`. If not, surface "Run `/cbp-task-check` first" and stop.
+
+### Step 2.6: Verify `/cbp-task-testing` Has Run
+
+`task.context.task_testing_output` must exist with `all_passed: true`. If not, surface "Run `/cbp-task-testing` first" and stop.
+
+### Step 3: Verify QA and File Approval
+
+Load `task.qa` and `task.files_changed`:
+
+1. **QA**: count items by status (pass / fail / pending / skipped) across all types. If any item has status `fail` or `pending` (including default checklists), warn the user.
+2. **Files**: list any file with `user_approved === false` and warn.
+
+**If issues exist**, AskUserQuestion: `Complete anyway` / `Run QA first` (suggest `/cbp-task-check`) / `Cancel`. On `Run QA first` or `Cancel`, stop. On `Complete anyway`, continue.
+
+**If no issues**, AskUserQuestion to confirm: `Ready to complete TASK-[N]: [title] — [N] rounds, [N] files. Proceed?`
+
+### Step 4: Aggregate Files Changed
+
+Collect all files_changed from task. Deduplicate (latest action wins).
+
+### Step 4.5: Merge Production Branch Before Commit (mandatory)
+
+Before committing task work, ensure the feat branch is current with the latest production (main) work. This prevents shipping a stale PR and surfaces conflicts at task-complete time rather than at PR review.
+
+1. Trigger `/cbp-merge-main`.
+2. If the skill exits with failure (offline, unresolved conflicts, user-aborted): surface the failure and STOP — do NOT proceed to Step 5 (commit). The user resolves and re-invokes `/cbp-task-complete`.
+3. If the skill exits with QA warnings the user chose to commit-as-is: continue to Step 5; surface a soft warning in the Step 9 output (`⚠ Merged with QA failures pending fix in follow-up`).
+4. On clean success: continue to Step 5.
+
+### Step 5: Git Commit and Push
+
+**Zero-file guard**: if `aggregated_files` is empty (investigative or DB-only tasks), skip commit and push. Record "No git commit: zero files changed" in the Step 9 summary.
+
+Otherwise: invoke `/cbp-git-commit` to stage approved files and create the commit. Claude does NOT git add directly. After commit:
+
+```bash
+git push origin $(git branch --show-current)
+```
+
+If push fails, investigate and fix per migration-infrastructure rule — never skip.
+
+### Step 6: Update Task Files
+
+`update_task(task_id, files_changed: aggregated_files)`.
+
+### Step 7: Complete Task
+
+If `CALLER_WT` is non-empty, call `complete_task(task_id, caller_worktree_id: CALLER_WT)`. Otherwise call `complete_task(task_id)` with no worktree id — the pre-guard is skipped (backwards-compat).
+
+**When calling `complete_task`**: pass `caller_worktree_id` resolved from `npx codebyplan resolve-worktree`. The MCP server's pre-guard rejects mutations from non-matching worktrees; supplying `caller_worktree_id` ensures legitimate completion succeeds. The server auto-clears `assigned_user_id` + `assigned_worktree_id` on the task; if this was the last sibling task, it also clears the parent checkpoint's assignment. (Per CHK-104 TASK-2 hard-lock.)
+
+### Step 7.5: Standalone Task Branch Merge
+
+**Standalone tasks only** (no checkpoint). Checkpoint tasks ship via `/cbp-checkpoint-end`.
+
+If `checkpoint_id === null` AND current branch is `feat/*`:
+
+1. Read `.codebyplan/git.json` `branch_config.production` (default `main`).
+2. Merge: `git checkout {production} && git merge {feat-branch} --no-ff -m "Merge {feat-branch}: {task title}"`
+3. Push: `git push origin {production}`
+4. Delete feat branch (local + remote).
+
+If merge has conflicts, stop and ask the user. If current branch is not `feat/*`, skip.
+
+### Step 8: Run Cleanup + Migration (inline)
+
+Apply the `cleanup` skill inline to remove orphan references to deleted/modified files. Then apply `migration` to propagate renames/moves to consumers. Both run without sub-agent spawns. Skip cleanup if no deletions/modifications; skip migration if cleanup handled everything.
+
+### Step 9: Show Result and Route (User-Confirmed)
+
+Show the completion summary:
+
+```
+## Task Completed
+
+**TASK-[N]**: [title]
+**Rounds**: [N] completed
+**Files**: [N] changed
+**Commit**: [hash]
+```
+
+Then route. Same-context transitions (next task in this checkpoint) auto-trigger via the Skill tool. Cross-context transitions (checkpoint done → /cbp-checkpoint-check, session end) surface as a single directive 'Next: /clear, then /cbp-X' for the user to invoke after refreshing context.
+
+#### 9a — Determine routing context
+
+```
+checkpoint_id := current_task.checkpoint_id
+if checkpoint_id is null  → STANDALONE; go to 9b
+else
+  siblings := get_tasks(checkpoint_id) minus current_task
+  all_done := every sibling has status === 'completed'
+  if all_done                → CHECKPOINT-DONE; go to 9c
+  else                       → MORE-TASKS-IN-CHECKPOINT; go to 9b
+```
+
+#### 9b — Next-task routing (more tasks pending OR standalone fall-through)
+
+Identify the next pending task: the lowest-numbered pending task in the same checkpoint, or — for standalone fall-through — the next standalone or in-progress-checkpoint task. Use `{N}` as the chk-task-round identifier form of that task (e.g. `111-5` for CHK-111 TASK-5, or `45` for standalone TASK-45).
+
+Use the Skill tool with `skill: cbp-task-start` and `args: "{NEXT_CHK}-{NEXT_TASK}"` (or `args: "{NEXT_TASK}"` for standalone) to auto-trigger the next task. Same-context transition; no `/clear` needed.
+
+If no next task is found (no pending work anywhere in the repo), emit directive and stop: `Next: Run /clear, then /cbp-session-end.`
+
+#### 9c — Checkpoint-done directive (last task in checkpoint)
+
+The checkpoint has no remaining tasks. Emit this directive and stop:
+
+```
+CHK-{NNN} is fully tasked. Run /clear, then /cbp-checkpoint-check to verify and ship.
+Alternatives: /cbp-checkpoint-update {NNN} to expand the checkpoint with more tasks, or /cbp-session-end to wrap up here.
+```
+
+Do NOT use AskUserQuestion here — this is a directive, not a menu. The user runs whichever command fits their intent.
+
+## Integration
+
+- **Triggered by**: `/cbp-task-testing` (auto, when ALL PASS) — NOT directly from `/cbp-task-check`
+- **Chain**: `/cbp-task-check` → `/cbp-task-testing` → `/cbp-task-complete`
+- **Reads**: MCP `get_current_task`, `get_rounds`, `get_tasks`
+- **Writes**: MCP `update_task`, `complete_task`
+- **Uses skills (inline, no sub-agent)**: `cleanup` (if deletions), `migration` (if exports renamed)
+- **Triggers**: Same-context transitions auto-trigger via the Skill tool (next task in checkpoint → `/cbp-task-start {N}`). Cross-context transitions emit a directive `Next: /clear, then /cbp-X` for the user to invoke.

package/templates/skills/cbp-task-complete/reference/checkpoint-done-branching.md

@@ -0,0 +1,48 @@
+# Checkpoint-Done Branching in `/cbp-task-complete` Step 9
+
+When the just-completed task was the LAST pending task in its checkpoint (every sibling task has `status === 'completed'`), Step 9c emits a directive instead of a routing menu. The user reads the directive and runs whichever command fits their intent — no AskUserQuestion.
+
+This file describes the detection logic, the directive form, and the standalone fall-through.
+
+## Detection
+
+The skill detects "checkpoint done" at Step 9 by:
+
+1. Reading `current_task.checkpoint_id`. If `null` → standalone — see "Standalone Fall-Through" below.
+2. Calling `get_tasks(checkpoint_id)` and checking that EVERY task other than the just-completed one has `status === 'completed'`.
+3. If yes, the checkpoint has no pending or in-progress siblings — emit the Step 9c directive.
+
+## Step 9c Directive Form
+
+When all siblings are done, the skill emits:
+
+```
+CHK-{NNN} is fully tasked. Run /clear, then /cbp-checkpoint-check to verify and ship.
+Alternatives: /cbp-checkpoint-update {NNN} to expand the checkpoint with more tasks, or /cbp-session-end to wrap up here.
+```
+
+This is a directive, not a menu. No AskUserQuestion. The user runs whichever command fits their intent:
+
+- `/clear` then `/cbp-checkpoint-check` — verify deliverables and begin the shipment chain
+- `/cbp-checkpoint-update {NNN}` — expand the checkpoint with more tasks (routes through `checkpoint-update` FIRST, not directly to `task-create`)
+- `/cbp-session-end` — wrap up here
+
+The skill does NOT auto-invoke any of these. Emit the directive, then stop.
+
+## Standalone Fall-Through
+
+When the just-completed task is standalone (`checkpoint_id === null`):
+
+- The Step 9c directive does NOT apply. There is no checkpoint to ship, expand, or defer.
+- Step 9 falls through to next-task routing per `next-step-heuristic.md` "Standalone Variant":
+  - If a next pending task is found (standalone or in-progress checkpoint): auto-trigger via Skill tool — no AskUserQuestion, no /clear.
+  - If no pending tasks remain anywhere: emit single directive `**Next**: Run /clear, then /cbp-session-end.` — all known work complete.
+
+## What the Skill Does NOT Do
+
+Never auto-trigger `/cbp-checkpoint-check`, `/cbp-checkpoint-update`, or auto-mark the checkpoint complete — those are cross-context transitions that emit a single directive, not auto-invocations. Never combine the Step 9c directive with the Step 9b auto-trigger in the same response — one or the other based on detection, not both.
+
+## Pairs With
+
+- `next-step-heuristic.md` — sibling reference for non-last-task-in-checkpoint case (Step 9b auto-trigger)
+- `.claude/skills/cbp-checkpoint-update/SKILL.md` — destination of the expand path; accepts the entry-context preamble described in Step 9c

package/templates/skills/cbp-task-complete/reference/next-step-heuristic.md

@@ -0,0 +1,56 @@
+# Next-Step Heuristic for `/cbp-task-complete` Step 9
+
+Close-out routing splits into two cases by context-continuity.
+
+## Case 1 — Same-Context (next task in same checkpoint)
+
+When a sibling task remains pending in the same checkpoint, auto-trigger the next task without asking. The context window already holds the checkpoint scope; a `/clear` would discard useful state.
+
+Use the Skill tool:
+
+```
+skill: cbp-task-start
+args: "{N}"   # e.g. "111-5" for CHK-111 TASK-5, or "45" for standalone TASK-45
+```
+
+No AskUserQuestion, no `/clear`. The skill fires immediately.
+
+## Case 2 — Cross-Context (checkpoint done, session end)
+
+When the checkpoint is fully done or no pending tasks exist in the current context, emit a single directive line at the end of skill output and stop:
+
+```
+**Next**: Run /clear, then /cbp-checkpoint-check.
+```
+
+Or for session-end:
+
+```
+**Next**: Run /clear, then /cbp-session-end.
+```
+
+The user runs the command after refreshing context. No menu, no options — just one directive.
+
+## Rule
+
+NEVER present a multi-option AskUserQuestion menu for routing between known-next skills. Branching AskUserQuestion is reserved for real branching decisions (errors, data conflicts, multiple-valid-approaches). When the next step is deterministic from context, either auto-trigger it (same-context) or surface a single directive (cross-context).
+
+## Standalone Variant
+
+When the just-completed task is standalone (`current_task.checkpoint_id === null`):
+
+- "Next pending" candidates are picked from BOTH:
+  - Standalone tasks (`get_tasks(repo_id, standalone: true, status: 'pending')`)
+  - In-progress checkpoints' next pending task
+- Prefer in-progress-checkpoint tasks over fresh standalone candidates (continuing committed work first).
+- If a next task is found: auto-trigger via Skill tool (same-context rule).
+- If no pending tasks remain anywhere: emit directive `**Next**: Run /clear, then /cbp-session-end.` — all known work complete.
+
+## Reference
+
+- Auto-memory: `[[feedback_long-lived-branch-integration]]` — related skill-clarity preference (same author feedback thread)
+- Auto-memory: `feedback-close-out-routing` — the rule that drives this heuristic
+
+## Pairs With
+
+- `checkpoint-done-branching.md` — sibling reference for the LAST-task-in-checkpoint case (Step 9c directive)

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

@@ -0,0 +1,167 @@
+---
+scope: org-shared
+name: cbp-task-create
+description: Create a new task within the active checkpoint
+effort: xhigh
+---
+
+# Task Create Command
+
+Create a new task within the active checkpoint. Gathers user context, analyzes existing work, and creates a well-positioned task. Runs inline (no subagent) to preserve Q&A conversation flow.
+
+## When Used
+
+- Suggested by `/cbp-task-check` when scope issues require a new task
+- Suggested by `/cbp-task-testing` when major problems need a separate task
+- User manually wants to add a task to the current checkpoint
+
+## Identifier Notation
+
+This skill operates on the **active** checkpoint resolved via MCP `get_current_task` and does not accept a positional identifier argument. The task it creates gets its `number` from the next-available slot within the active checkpoint (checkpoint-bound) or repo-wide standalone numbering (standalone). Canonical chk-task-round notation — used in prose, error messages, and cross-references — follows `.claude/rules/notation-consistency.md` "CHK / TASK / ROUND Identifier Notation": `108-1` (CHK-108 TASK-1), `45` (standalone TASK-45), `108-1-2` (round 2 of CHK-108 TASK-1), `45-2` (round 2 of standalone TASK-45).
+
+## Instructions
+
+### Step 1: Get Current Checkpoint
+
+Use MCP `get_current_task` with repo_id to find the active checkpoint.
+
+If no active checkpoint, show error and stop.
+
+### Step 2: Gather User Context
+
+Use AskUserQuestion to understand the new task:
+
+```
+## New Task for CHK-[NNN]: [checkpoint title]
+
+Why is this task needed? What should it accomplish?
+
+If this was triggered by `/cbp-task-check` or `/cbp-task-testing`, the findings are:
+[pre-loaded context from check/testing findings if available]
+
+Please describe:
+1. What the task should accomplish
+2. Any specific requirements or constraints
+3. Priority relative to other tasks
+```
+
+### Step 3: Load Existing Tasks
+
+Use MCP `get_tasks` for the checkpoint. Review:
+- Existing task titles and requirements
+- Task statuses (completed, in_progress, pending)
+- Dependencies between tasks
+
+### Step 3.5: Dedup Against Pending Standalone Tasks (MANDATORY)
+
+Per `rules/immediate-issue-capture.md` "Consolidation Before Creation", before creating ANY new task, also check pending standalone tasks for overlap:
+
+```
+mcp__codebyplan__get_tasks(repo_id, standalone=true, status="pending")
+```
+
+Compare the proposed task to each pending standalone task on these match dimensions:
+
+| Match dimension | Action if matched |
+|-----------------|-------------------|
+| Same target file(s) | STOP — `update_task` to append, do not create new |
+| Same feature / module | STOP — `update_task` to append, do not create new |
+| Same root cause (e.g. "prettier drift", "router bug") | STOP — `update_task` to append, do not create new |
+| Same dependency / advisory | STOP — `update_task` to append, do not create new |
+
+If a match is found, surface it to the user before appending:
+
+```
+Found existing pending task TASK-[N]: [title]
+This finding overlaps on [dimension]. Append to TASK-[N] instead of creating new? (yes / no — create separately)
+```
+
+Default to append. Only create a separate task if the user explicitly says no, OR if the existing task is in_progress / completed (in which case use `context.related_task_ids[]` on the new task to cross-reference).
+
+### Step 4: Analyze Codebase Context
+
+Brief inline analysis:
+1. Check checkpoint.context for relevant decisions and discoveries
+2. Grep/Glob for files related to the user's described work
+3. Understand what prior tasks have already built
+
+### Step 5: Clarify Ambiguities (if needed)
+
+If the task scope is unclear after Steps 2-4, ask up to 4 clarifying questions via AskUserQuestion:
+
+```
+To create the best task definition, I need to clarify:
+
+1. [question about scope]
+2. [question about approach]
+[max 4 questions]
+```
+
+Skip if requirements are already clear from Step 2.
+
+### Step 6: Determine Task Position
+
+Find logical position in task order:
+- After which existing task should this go?
+- Consider dependencies (does this depend on other tasks?)
+- Consider checkpoint goal alignment
+
+### Step 7: Create Task
+
+Use MCP `create_task` with:
+- **title**: Concise task title
+- **requirements**: Numbered requirements list
+- **context**: Include decisions from Q&A, dependencies, source findings
+
+**For standalone tasks** (no `checkpoint_id` parameter): resolve worktree_id via `npx codebyplan resolve-worktree 2>/dev/null` and, if non-empty, pass as `assigned_worktree_id`. The `chk_assignment_pair` CHECK constraint permits `assigned_user_id` to be NULL when `assigned_worktree_id` is set — `create_task` does not expose an `assigned_user_id` parameter and none is required. This engages the CHK-104 TASK-2 hard-lock from creation.
+
+**If `worktree_id` is empty AND the task is standalone**: warn the user that the task will be unassigned (no hard-lock from creation) and offer to run `npx codebyplan setup` first from the current directory to register the worktree. After setup, re-resolve the worktree_id and proceed. If the user declines, create the task without `assigned_worktree_id`.
+
+**For checkpoint-bound tasks**, an empty `worktree_id` is fine — no caller-worktree stamping is needed because the parent checkpoint's `worktree_id` governs.
+
+```
+## Task Created
+
+**TASK-[N]**: [title]
+
+### Requirements:
+1. [requirement 1]
+2. [requirement 2]
+...
+
+### Context:
+- Dependencies: [any task dependencies]
+- Decisions: [key decisions from Q&A]
+- Position: After TASK-[X] in checkpoint order
+```
+
+### Step 8: Route
+
+```
+Task TASK-[N] created successfully.
+```
+
+---
+
+**Next:**
+Run `/cbp-task-start [N]` to:
+- Start working on the new task
+- Or run `/cbp-todo` to see the full task queue
+
+---
+Waiting for user to decide next step.
+
+## Key Rules
+
+- **Runs inline** — no subagent, preserves Q&A flow
+- **Gather context first** — understand before creating
+- **Consider existing tasks** — avoid duplication
+- **Respect checkpoint goal** — new task must contribute to checkpoint goal
+- **Does NOT auto-trigger** — user decides when to start
+
+## Integration
+
+- **Reads**: MCP `get_current_task`, `get_tasks`
+- **Writes**: MCP `create_task`
+- **Triggered by**: `/cbp-task-check` (suggested), `/cbp-task-testing` (suggested), user manual
+- **Does NOT auto-trigger** next command — user decides