codebyplan 1.5.1 → 1.9.0

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

@@ -0,0 +1,211 @@
+---
+scope: org-shared
+name: cbp-round-execute
+description: Execute the approved plan from /cbp-round-start — runs per-wave executors, inline testing-qa per wave, and routes to /cbp-round-end
+effort: xhigh
+---
+
+# Round Execute Command
+
+Execution and validation phase. Receives the approved plan from `/cbp-round-start`, dispatches wave executors, runs per-wave `cbp-testing-qa-agent` in parallel, and routes to `/cbp-round-end`.
+
+## Pipeline
+
+```
+/cbp-round-start → /cbp-round-execute → /cbp-round-end (auto)
+```
+
+## Identifier Notation
+
+This skill operates on the **active** task/round resolved via MCP `get_current_task` / `get_rounds` and does not accept a positional identifier argument. 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 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.
+
+If no in-progress round: `No active round. Run /cbp-round-start first.`
+
+### Step 2: Load Approved Plan
+
+Read the plan from round context (`context.planner_output`). If no plan: `No approved plan in round context. Run /cbp-round-start first.`
+
+Read effective testing profile: `round.context.testing_profile_override` if set (user override for this round only), else `task.context.testing_profile` (set by planner Phase 4.8), else default `'web'`. Pass the effective profile to all per-wave `cbp-testing-qa-agent` spawns.
+
+### Step 3: Route Execution Path
+
+Inspect `approved_plan.files_to_modify[]` and `approved_plan.round_type`. Four execution paths exist; pick the one that matches BEFORE Step 3a/3b.
+
+| Condition                                                                        | Path                                                                                                             |
+| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `files_to_modify[]` empty AND `round_type === 'survey'`                          | **3-SURVEY** — orchestrator executes inline; constructs executor-equivalent output; NEVER spawn `cbp-round-executor` |
+| Every entry under `.claude/**`                                                   | **3-INLINE** — orchestrator applies via build-cc skills or direct Edit; NEVER spawn `cbp-round-executor`             |
+| At least one entry outside `.claude/**` AND `approved_plan.waves[]` has ≥2 waves | **3-WAVE** — dispatch per-wave per schema in `approved_plan.waves[]`                                             |
+| At least one entry outside `.claude/**` (single wave or no waves field)          | **3-AGENT** — spawn single `cbp-round-executor`                                                                      |
+
+#### Step 3-SURVEY: Empty-Files Survey Path
+
+Execute the survey instructions inline using Read/Grep/Bash. Save to `round.context.survey_output`. Build executor-equivalent output object with `round_type: 'survey'`. Skip to Step 3c.
+
+`round_type: 'survey'` MUST be set in `round.context` so Step 4 (dev-server probe) and downstream skills short-circuit correctly.
+
+#### Step 3-INLINE: `.claude/`-Only Inline Path
+
+For each entry, route per `rules/file-routing.md`:
+
+- `.claude/skills/{name}/SKILL.md` → `cbp-build-cc-skill` via Skill tool
+- `.claude/agents/{name}/AGENT.md` → `cbp-build-cc-agent` via Skill tool
+- `.claude/rules/{name}.md` → `cbp-build-cc-rule` via Skill tool
+- `.claude/CLAUDE.md` → `cbp-build-cc-claude-file` via Skill tool (or direct Edit)
+- `.claude/settings*.json` → `cbp-build-cc-settings` via Skill tool
+- `.claude/context/**`, `.claude/docs/**` → direct Edit
+- `.claude/hooks/{name}.sh` → direct Write/Edit
+
+Build executor-equivalent output object inline. Skip to Step 3c.
+
+#### Step 3-WAVE: Multi-Wave Dispatch
+
+When `approved_plan.waves[]` is present and has ≥2 entries:
+
+1. Topological-sort waves by `depends_on[]` to determine dispatch order.
+2. For each wave whose `depends_on[]` names are all complete, spawn the wave executor:
+   - `agent_type: 'cbp-round-executor'` → spawn `cbp-round-executor` with wave-scoped input (see `agents/cbp-round-executor.md` wave input contract)
+   - `agent_type: 'inline'` → execute inline as 3-INLINE path, scoped to `wave.files[]`
+3. After each wave completes, spawn `cbp-testing-qa-agent` against `wave.files[]` with `testing_profile` from Step 2. Run this testing spawn in PARALLEL with the next wave's executor when dependency order allows.
+4. After all waves complete, merge all `files_changed[]` into a single executor output.
+
+#### Step 3-AGENT: Single `cbp-round-executor` Spawn
+
+#### Mechanical-Edits Delegation Gate
+
+Before spawning `cbp-round-executor`, inspect `task.context.work_mode` (set by cbp-task-planner Phase 4.1).
+
+| Value              | Action                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mechanical`       | Spawn `cbp-mechanical-edits` instead of `cbp-round-executor`. Derive the spec (renames / substitutions / frontmatter_edits / index_regen) from `approved_plan.files_to_modify[]` + the task's deliverables; pass it via the prompt body per the agent's Input Contract. After the agent returns, verify `git status --porcelain` reflects only expected paths AND `validation.orphaned_refs` is empty. Skip the rest of Step 3-AGENT and proceed to Step 3b.                                                                                                                                                                                                         |
+| `mixed`            | Read `task.context.mechanical_files[]` (populated by cbp-task-planner Phase 4.1 per its partition rule). Spawn `cbp-round-executor` for the AUTHORED portion FIRST — the executor's `files` input is `files_to_modify[]` MINUS `mechanical_files[]`. After it returns, spawn `cbp-mechanical-edits` against ONLY `mechanical_files[]` — derive the spec (renames / substitutions / frontmatter_edits / index_regen) from those entries' purpose strings. Merge both `files_changed[]` results into a single output for Step 5. If `mechanical_files[]` is absent or empty when `work_mode === 'mixed'`, halt with a planner-output error (Phase 4.1 contract violation). |
+| `design` or absent | Proceed with the existing `cbp-round-executor` spawn below (no change in behaviour).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+
+**Universal postcondition for both `mechanical` and `mixed`:** if any spawned `cbp-mechanical-edits` reports `validation.orphaned_refs.length > 0`, treat as a hard-fail signal and route through Step 6 (regardless of whether the executor also ran in the `mixed` path).
+
+This gate is distinct from Phase 2.95's `execution_mode` parallelism hint (consumed downstream by `cbp-round-executor` Step 3.5 for batch-create scenarios). Both gates can fire on the same task.
+
+Spawn `cbp-round-executor` with the approved plan and full context:
+
+```yaml
+input:
+  task_number: N
+  round_number: N
+  approved_plan: [from round context]
+  checkpoint: { id, title, goal, context }
+  task: { id, title, requirements, context }
+  resources: [merged from checkpoint.resources + task.resources]
+```
+
+Wait for executor output.
+
+### Step 3b: Database Work (if plan includes DB changes)
+
+If the approved plan includes database schema changes, RLS policies, or type generation:
+
+1. Spawn `cbp-database-agent` with DB-related steps from the plan
+2. Wait for completion
+3. Merge `files_changed` into executor output
+
+### Step 3c: Completion Check
+
+- `status: 'completed'` and all deliverables done → proceed to Step 4
+- `status: 'blocked'` → present blocker to user via AskUserQuestion, resolve, re-spawn executor with remaining work
+- Deliverables incomplete → re-spawn executor with remaining deliverables (max 3 re-triggers). After 3 re-triggers, save partial output and proceed.
+
+### Step 4: Dev-Server Probe (rounds 2+, web/desktop profile)
+
+When `round_number >= 2` AND `testing_profile` is `'web'` or `'desktop'` AND `files_changed` contains any UI file, probe the dev server BEFORE cbp-testing-qa-agent spawns (saves a full agent spawn when the server is down).
+
+Read `.codebyplan/server.json` `port_allocations[]`. For each configured port run:
+
+```bash
+curl -sf --max-time 3 -o /dev/null -w "%{http_code}" http://localhost:{port}/
+```
+
+Any non-2xx/3xx response → AskUserQuestion: start the dev server, skip UI checks, or abort.
+
+Skip this probe for `testing_profile === 'claude_only'` or `'backend'`.
+
+### Step 5: Per-Wave Testing (or global testing for single-wave)
+
+Read `task.context.testing_profile` (already loaded in Step 2).
+
+**claude_only profile**: run inline checks only (no `cbp-testing-qa-agent` spawn):
+
+1. `bash -n <hook-file>` for each modified `.sh` in `files_changed`
+2. Verify each modified/created SKILL.md ≤300 lines (warn threshold; hook blocks at 600); `scope:` marker present; no `/cbp-*` notation
+
+On pass, synthesise `testing_qa_output` inline per the procedure in `reference/inline-fallback.md` "Validation fallback" section (output shape defined in `agents/cbp-testing-qa-agent.md` Output Contract) and persist to `round.context.testing_qa_output` at Step 7.
+
+**All other profiles**: spawn `cbp-testing-qa-agent` AND `cbp-test-e2e-agent` in parallel (two Agent calls in the same message) per completed wave (or full executor output in single-wave mode). `cbp-test-e2e-agent` is gated on `has_ui_work === true` AND profile in {`web`, `desktop`, `full_matrix`, `cross_app`} — skipped for `claude_only` / `backend`-only.
+
+Input contracts: `cbp-testing-qa-agent` receives `executor_output`, `testing_profile`, `has_ui_work` (see `agents/cbp-testing-qa-agent.md` Input Contract). `cbp-test-e2e-agent` receives `repo_id`, `round_number`, `files_changed`, `prior_round_files_changed` (full task aggregate when round_number ≥ 2), `whole_checkpoint_mode: false`, `test_strategy`, `pages_affected`, `has_auth`, `dev_server_port` (see `agents/cbp-test-e2e-agent.md` Input Contract for the full shape).
+
+**Independence**: neither agent reads the other's output. Cross-source user_qa items (cbp-frontend-ui + agent data) are constructed downstream at `/cbp-round-end` Step 3b. Per-wave spawns MAY run in parallel with the next wave's executor when dependency order allows.
+
+### Step 5b: Post-E2E Screenshot Review (cbp-frontend-ui Phase 6.5)
+
+When `round.context.e2e_output.screenshots[]` is non-empty, invoke the `cbp-frontend-ui` skill with `phase: 'screenshot_review'` (input: `files_changed`, `e2e_screenshots: round.context.e2e_output.screenshots`, `context: { checkpoint_goal, round_requirements }`). Under this phase the skill runs only Phase 6.5 (Rendered-Output Visual Review) + 7 + 8 — Phases 1-6 (style) already ran inline at executor Step 3.8 with `phase: 'style_only'`.
+
+Persist findings to `round.context.frontend_ui_review` (merge with Step 3.8's style-only output if present). `/cbp-round-end` Step 3b emits user_qa items for any `category: 'baseline_regression'` (any severity) and any `category: 'rendered_visual' + severity: 'critical'` — neither auto-fails the round. cbp-testing-qa-agent does NOT read these findings (full independence per Step 5).
+
+**Skip** when `round.context.e2e_output` is absent, `screenshots` is empty, or `testing_profile === 'claude_only'`.
+
+### Step 6: Hard-Fail Routing
+
+Per-wave hard-fail signal: `testing_qa_output.totals.hard_fail || e2e_output.status === 'failed' || e2e_output.test_results?.failed > 0`.
+
+**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 test-e2e for that wave.
+- **Structural OR already re-triggered once OR e2e preflight aborts** → save failure context via MCP `update_round`; auto-trigger `/cbp-round-input`. STOP.
+
+## Inline execution fallback
+
+When `cbp-round-executor` spawn fails (per `agent-spawn-failure-fallback.md` triggers), fall through to the 3-INLINE branch in Step 3 above for `.claude/`-only edits. For non-`.claude/` edits, walk `agents/cbp-round-executor.md` Phase 1–4 inline using Read / Edit / Write / Bash. Full procedure: `reference/inline-fallback.md` "Execution fallback" section.
+
+## Inline validation fallback
+
+When `cbp-testing-qa-agent` spawn fails OR the resolved `testing_profile` is `claude_only` (in which case the agent isn't spawned by design), run validation inline. Apply the profile gate matrix in `agents/cbp-testing-qa-agent.md` Phase 3 to determine in-scope checks. Full procedure + per-profile shape: `reference/inline-fallback.md` "Validation fallback" section.
+
+### Step 7: Save Executor Output
+
+Update round context via MCP `update_round`:
+
+- `context`: { ...existing, executor_output, testing_qa_output, e2e_output, frontend_ui_review }
+
+`e2e_output` and `frontend_ui_review` are present only when the gates above admitted them (e2e ran AND Step 5b ran).
+
+### Step 8: Auto-trigger Round End
+
+```
+Execution and validation complete. Starting round wrap-up...
+```
+
+Trigger `/cbp-round-end`.
+
+## Key Rules
+
+- **Code + test writing + inline validation** — planning lives in `round-start`, summary in `round-end`
+- Per-wave `cbp-testing-qa-agent` AND `cbp-test-e2e-agent` run in parallel (both against the same wave's `files[]`); they may also run in parallel with the NEXT wave's executor when dependency order allows
+- `testing_profile` from `task.context` governs which checks run — read it once in Step 2; pass to every testing-qa + test-e2e spawn
+- `claude_only` profile skips all agent spawns (testing-qa AND test-e2e); runs hook syntax and skill structure checks inline
+- Step 5b (cbp-frontend-ui Phase 6.5) runs only when e2e produced screenshots — gated on `e2e_output.screenshots[]` non-empty
+- Claude NEVER git adds files in round commands
+
+## Integration
+
+- **Reads**: MCP `get_current_task`, `get_rounds`
+- **Writes**: MCP `update_round` (context with executor_output + testing_qa_output + e2e_output + frontend_ui_review)
+- **Spawns**: `cbp-round-executor` (per wave or single), `cbp-testing-qa-agent` (per wave, parallel sibling of cbp-test-e2e-agent), `cbp-test-e2e-agent` (per wave when has_ui_work + non-claude_only profile), `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)
+- **Triggered by**: `/cbp-round-start` (auto, after plan approval)

package/templates/skills/cbp-round-execute/reference/inline-fallback.md

@@ -0,0 +1,59 @@
+---
+scope: org-shared
+---
+
+# Inline-fallback procedures
+
+When `round-executor` or `testing-qa-agent` cannot be spawned (env limits, monthly cap, 5xx, rate limit, context overflow), the orchestrator falls through to an inline procedure that walks the agent's Phase checklist using its own tools.
+
+The two fallback modes are documented separately so the SKILL.md stubs can link the right section.
+
+## Execution fallback (round-executor spawn failed)
+
+Triggered when the executor agent spawn returns one of the failure classes documented in `agent-spawn-failure-fallback.md`. Procedure:
+
+1. Detect failure class from error string. Record:
+   ```yaml
+   round.context.executor_findings.spawn_failure:
+     class: "monthly_agent_usage_limit" | "provider_5xx" | "rate_limit_429" | "context_overflow_at_spawn" | "billing_limit"
+     error_message: "<verbatim>"
+     decided_at: "<ISO>"
+   ```
+2. For `.claude/`-only file sets, fall through to the 3-INLINE branch in `../SKILL.md` Step 3 (orchestrator routes per file-routing.md to the matching build-cc skill or direct Edit).
+3. For non-`.claude/` file sets, walk `agents/round-executor.md` Phase 1–4 inline using Read / Edit / Write / Bash / Glob / Grep. Step 3 (Implementation) is the load-bearing phase — apply each `files_to_modify[]` deliverable in order, respecting wave boundaries when wave mode is active.
+4. Populate the executor's output contract with `mode: 'inline_fallback'` so analytics distinguishes.
+5. Pre-emptive skip on repeat: if `prior_round.context.executor_findings.spawn_failure.class === current_class`, skip the spawn attempt entirely and go straight to inline.
+
+## Validation fallback (testing-qa-agent spawn failed OR claude_only profile)
+
+Triggered when testing-qa-agent spawn returns a failure class, OR when the resolved profile is `claude_only` (in which case the agent should not have been spawned at all). Procedure:
+
+1. Detect failure class. Record:
+   ```yaml
+   round.context.testing_qa_findings.spawn_failure:
+     class: "<failure_class>"
+     error_message: "<verbatim>"
+     decided_at: "<ISO>"
+   ```
+2. Apply the profile gate matrix from `agents/testing-qa-agent.md` Phase 3 to determine which checks are in-scope:
+   - `claude_only`: only hook bash syntax (`bash -n <hook>`) + skill structure validation (line counts, scope marker, /cbp-* legacy notation absent)
+   - `web`: skip desktop + backend
+   - `backend`: skip web + desktop
+   - `desktop`: skip web + backend
+   - `full_matrix`: all
+   - `cross_app`: union of touched apps
+3. Walk `agents/testing-qa-agent.md` Phase 1 (Setup) + Phase 2 (Discovery) + Phase 3 (Mandatory Automated Testing) inline using Read / Grep / Bash. Aggregate per-check results.
+4. Populate `testing_qa_output` shape with `mode: 'inline_fallback'`. For `claude_only` specifically, use `mode: 'inline_synthesised_for_claude_only_profile'` (the agent was never expected to spawn — this isn't a fallback, it's the documented happy path).
+5. Pre-emptive skip on repeat: if `prior_round.context.testing_qa_findings.spawn_failure.class === current_class`, skip the spawn attempt entirely.
+
+## Pre-emptive skip rule
+
+Per `agent-spawn-failure-fallback.md` item 5: when the same failure class fired in the previous round of the same task, skip the spawn attempt entirely and go straight to inline. This avoids one wasted API call per round during a sustained outage.
+
+## Pairs With
+
+- `../SKILL.md` — points at this reference for procedural detail
+- `agents/round-executor.md` — execution-fallback target agent
+- `agents/testing-qa-agent.md` — validation-fallback target agent + Phase 3 profile gate matrix
+- `rules/agent-spawn-failure-fallback.md` — required-coverage table; canonical failure classes
+- `rules/testing-profile.md` — claude_only profile detail; cross-app union semantics

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

@@ -0,0 +1,165 @@
+---
+scope: org-shared
+name: cbp-round-input
+description: Gather input for a new round with deep analysis of unapproved work
+argument-hint: [chk-task-round | task-round | requirements-text]
+effort: xhigh
+---
+
+# Round Input Command
+
+Gathers input for a new round. Performs deep analysis of unapproved files, requirements coverage, and testing-QA failures before formulating requirements. Follow-up rounds get the same depth as round 1.
+
+## When Used
+
+- After `/cbp-round-update` routes here (unapproved files)
+- After `/cbp-round-execute` Step 6 routes here (structural failure or retry-exhausted hard-fail)
+- After `/clear` + `/cbp-todo` reloads context and triggers this
+- When user wants to start a new round with specific changes
+
+## Instructions
+
+### Step 1: Parse `$ARGUMENTS`
+
+Try the numeric identifier regex first: `^[0-9]+(-[0-9]+){0,2}$`
+
+| Shape | Segments | Resolves to |
+|-------|----------|-------------|
+| `{task}` (e.g. `45`) | 1 | Standalone TASK-{task} next round (matches cbp-task-start standalone convention) |
+| `{chk}-{task}` (e.g. `108-1`) | 2 | CHK-{chk} TASK-{task} next round (round number implicit — round-input creates a new round) |
+| `{chk}-{task}-{round}` (e.g. `108-1-2`) | 3 | CHK-{chk} TASK-{task} targeting ROUND-{round} (existing round context) |
+| _(no match / empty)_ | — | Free-text requirements (passed through to Step 5) OR empty → use `get_current_task` |
+
+If the argument matches the numeric regex, resolve the target task/round from DB. If no match (or empty), treat the argument as free-text requirements and proceed to Step 2 for context (free-text path still runs deep analysis before Step 5).
+
+#### Worked examples
+
+- `round-input 45` → standalone TASK-45 next round
+- `round-input 108-1` → CHK-108 TASK-1 next round
+- `round-input 108-1-2` → CHK-108 TASK-1 ROUND-2
+- `round-input` (no arg) → active task via `get_current_task`
+- `round-input Fix the broken lint rule in the auth module` → free-text requirements (numeric regex fails → falls through to free-text path)
+
+> **Note on 2-segment divergence**: `round-input 108-1` resolves to **CHK-108 TASK-1** (targeting that task's next round). This diverges from `/cbp-round-start` where the 2-segment `108-1` means **standalone TASK-108 ROUND-1**. Round-input always operates on a task-level context (it creates a new round on a task), so the round number is implicit and 2 segments are interpreted as `{chk}-{task}`. To target a standalone task here, use the 1-segment form `45`. To target a specific existing round, use the 3-segment form `108-1-2`.
+
+### Step 2: Deep Analysis (MANDATORY — always runs)
+
+**2a:** Load task via MCP `get_current_task` (pass `checkpoint_id` if known to avoid disambiguation) — get `files_changed`, `requirements`, `context`, `qa`
+
+**2b:** Load all rounds via MCP `get_rounds(task_id)` — get previous round context, testing-qa output
+
+**2c:** Identify unapproved files from `task.files_changed` where `user_approved === false`
+
+**2d:** Read the content of each unapproved file (using Read tool, max 5 files, first 100 lines each)
+
+**2e:** Cross-reference with task requirements — for each requirement, is it met or missed?
+
+**2f:** Extract testing-qa failures from latest round context (`context.testing_qa_output`)
+
+**2g:** Extract code review findings from latest round context (`context.improve_round_findings`).
+These are user-accepted findings from `improve-round` agent — bugs, logic errors, edge cases
+that the user agreed should be fixed. Include them as high-priority requirements.
+
+**2h:** Identify root causes — not "file X is wrong" but "requirement Y was not met because Z"
+
+**2i:** Produce structured analysis summary
+
+### Step 3: Present Analysis
+
+Show the analysis to the user:
+
+```
+## Follow-up Round Analysis
+
+### Unapproved Files ([N])
+| File | Action | Issue |
+|------|--------|-------|
+| path | modified | [what's wrong based on reading the file] |
+
+### Requirements Coverage
+| Requirement | Status | Gap |
+|-------------|--------|-----|
+| [req] | met/missed | [what's missing] |
+
+### Testing-QA Issues (from previous round)
+- [issue 1 from testing-qa output]
+- [issue 2]
+
+### Code Review Findings (from improve-round)
+| # | Severity | File | Issue |
+|---|----------|------|-------|
+| [findings accepted by user in previous round-end] |
+
+### Root Causes
+1. [root cause with explanation]
+2. [root cause with explanation]
+```
+
+### Step 4: Choose Mode
+
+**If `round.context.auto_loop_mode === true` on the prior round**: skip the AskUserQuestion below. Auto-pick "Start round with these findings" using the analysis directly. Set the next round's `auto_loop_mode = true`, carry `auto_loop_index` and `auto_loop_cap` forward into round-start args.
+
+**Else (manual mode — flag absent or false)**, ask user via AskUserQuestion:
+
+- **Start round with these findings** — use analysis as requirements
+- **Discuss first** — open conversation about the analysis
+- **Adjust** — user provides their own requirements
+
+If "Discuss first": enter open discussion about the analysis. When direction is clear, proceed to Step 5.
+If "Adjust": user provides their own requirements, merged with analysis context.
+
+### Step 5: Formulate Requirements
+
+Based on the analysis + user input, create detailed requirements that:
+
+- Reference specific root causes identified in Step 2
+- Include full task requirements context
+- Are as thorough as round 1 (not quick fixes)
+- Include checkpoint and task context for the planner
+
+**Under `auto_loop_mode`**: requirements come VERBATIM from the prior round's `improve_round_findings[]` and `testing_qa_output` failures, treated as a flat list. Test failures are listed first (they block shipping); reviewer findings follow. Both sets are included unchanged — do not re-summarise or re-prioritise either. The auto-loop transcribes the prior reviewer's output directly.
+
+### Step 6: Update Context (if direction changed)
+
+If the new round requirements change the task direction:
+
+1. Update task context via MCP `update_task(task_id, context: { ... })`:
+   - Add new decisions to `context.decisions[]`
+   - Update `context.discoveries[]` if applicable
+2. If checkpoint-level changes needed, update checkpoint context via MCP `update_checkpoint`
+
+### Step 7: Auto-trigger Round Start
+
+Pass the new requirements to `/cbp-round-start`:
+
+```
+Starting new round with updated requirements...
+```
+
+Trigger `/cbp-round-start` with the round requirements as arguments.
+
+**Under `auto_loop_mode`**: pass `auto_loop_mode: true`, `auto_loop_index: N`, `auto_loop_cap: C` into round-start's args/context so round-start Step 4 can persist them on the new round and downstream skills (round-execute, round-end) read them.
+
+## Fallback: Context Recovery
+
+If this command is triggered **directly** (not via `/cbp-todo`) and no context is available in the session:
+
+1. Read `.codebyplan/repo.json` for `repo_id`
+2. Use MCP `get_current_task` to load checkpoint + task
+3. Use MCP `get_rounds(task_id)` to load round history
+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
+- **Follow-up rounds get same depth as round 1** — no quick-fix behavior
+- **Never ask to git add** — file approval is handled by `/cbp-round-update`
+- **Update all context locations** — task, checkpoint, and round should all have consistent information
+
+## Integration
+
+- **Triggered by**: `/cbp-round-update` (auto, unapproved files), `/cbp-round-execute` (auto, on hard-fail after retry exhausted), `/cbp-todo` (after /clear), user manually
+- **Reads**: MCP `get_current_task`, `get_rounds`, file contents (Read tool)
+- **Writes**: MCP `update_task` (context), `update_checkpoint` (context, if needed)
+- **Triggers**: `/cbp-round-start` (auto)

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

@@ -0,0 +1,222 @@
+---
+scope: org-shared
+name: cbp-round-start
+description: Start a round — planning phase only
+triggers: [cbp-round-execute]
+argument-hint: [chk-task-round | task-round | requirements-text]  # e.g. `108-1-2`, `45-2`, or free-text from /cbp-round-input
+effort: xhigh
+---
+
+# Round Start Command
+
+Planning phase for a new round. Analyzes context, creates plan, gets user approval. NO execution or testing — those are separate commands.
+
+## Inline-Fallback for Planner Spawn Failure
+
+If the `cbp-task-planner` agent spawn fails for any reason (`API Error: Extra usage required`, monthly Agent usage cap, provider 5xx, rate limit, context overflow), the orchestrator MUST follow the canonical inline-fallback procedure documented in `skills/cbp-round-end/SKILL.md` "Inline-fallback for any spawn failure".
+
+Procedure summary (pointer back to canonical):
+
+1. Detect the failure class from the error string; record `round.context.planner_findings.spawn_failure = { class, error_message, decided_at }`.
+2. Walk the planner's documented Phase 0-8 checklist inline using `Read` / `Grep` / `Bash` / MCP `get_*` — `agents/cbp-task-planner.md` is the inline script. Phase 1.5 (Requirement Premise Verification) and Phase 4.7 (Migration Shape-Distribution Pre-Flight) are MANDATORY in fallback mode — these are the gates the agent uniquely enforces; skipping them produces unverified plans.
+3. Populate the planner's output contract (`approved_plan` shape: `files_to_modify[]`, `deliverables`, `specialist_needs`, `round_type`, `shape_distribution` if applicable, `context_summary`) with `mode: 'inline_fallback'`.
+4. Apply the pre-emptive-skip rule: when the same failure class fired in the previous spawn of this session, skip the spawn attempt entirely and go straight to inline.
+5. Continue the skill — do NOT abort. The plan still requires user approval at Step 9.
+
+Inline-fallback is NOT a quality downgrade trapdoor — Phase 1.5 row-by-row verification is mandatory. A fallback plan that skipped premise verification is a regression caught by the next session's cbp-improve-round.
+
+## Pipeline
+
+```
+/cbp-round-start (planning) → [user approval] → /cbp-round-execute (auto)
+```
+
+**Auto-loop mode**: when `round.context.auto_loop_mode === true` flows in from `/cbp-round-input`, Step 6 (Q&A) and Step 8 (user approval) skip user prompts. See cbp-round-update SKILL.md Step 6 (auto-loop decision) and cbp-round-end SKILL.md Step 8 for the full contract.
+
+## Instructions
+
+### Step 0: Parse `$ARGUMENTS` shape
+
+Disambiguate the argument up front. Three input shapes (see `.claude/rules/notation-consistency.md` "CHK / TASK / ROUND Identifier Notation"):
+
+| Shape | Regex | Meaning |
+|-------|-------|---------|
+| `{chk}-{task}-{round}` (e.g. `108-1-2`) | `^[0-9]+-[0-9]+-[0-9]+$` | **Identifier**: targets round {round} of CHK-{chk} TASK-{task}. Sets `target_checkpoint`, `target_task`, `target_round`. |
+| `{task}-{round}` (e.g. `45-2`) | `^[0-9]+-[0-9]+$` | **Identifier**: targets round {round} of standalone TASK-{task}. Sets `target_task`, `target_round` (no checkpoint). |
+| Non-empty, non-identifier-shaped | — | **Free-text round requirements** (the round-input passthrough path). |
+| _(empty)_ | — | No identifier, no requirements text — derive task/round from `get_current_task` / `get_rounds`. |
+
+Malformed identifier shapes (`108-`, `-1-2`, `108--1`, `abc-1`) — surface this error and stop, mirroring `/cbp-task-start`'s error vocabulary:
+
+```
+round-start: invalid argument `{value}`. Expected:
+  108-1-2  → round 2 of CHK-108 TASK-1
+  45-2     → round 2 of standalone TASK-45
+  (free-text) → round requirements (typical from /cbp-round-input)
+  (empty)  → derive from active task/round state
+```
+
+#### Worked examples
+
+- `round-start 108-1-2` → resolve CHK-108 TASK-1, target round 2
+- `round-start 45-2` → resolve standalone TASK-45, target round 2
+- `round-start 108-1` → **standalone TASK-108 round 1** (NOT CHK-108 TASK-1). The 2-segment form means `{task}-{round}`; checkpoint-bound round-targeting requires all three numbers (`108-1-2`). If you got here trying to target CHK-108 TASK-1, you want `108-1-2` (specifying a round number) or `/cbp-task-start 108-1` (specifying just a task).
+- `round-start "Implement OAuth flow per CHK-X plan"` → free-text path; current-task/round derivation from state
+- `round-start` (empty) → derive from `get_current_task` / `get_rounds`; round 1 uses `task.requirements`
+- `round-start 108-` → error: malformed identifier
+- `round-start -1-2` → error: malformed identifier
+- `round-start abc-1` → error: malformed identifier
+
+> **Mental-model warning**: `task-start` and `round-start` interpret the SAME `108-1` argument differently. `task-start 108-1` → CHK-108 TASK-1 (checkpoint-bound task). `round-start 108-1` → standalone TASK-108 round 1 (because round-start needs three numbers for a checkpoint-bound round). When in doubt, write all three: `round-start 108-1-2`.
+
+### Step 1: Get Current Task
+
+If Step 0 produced an identifier (`target_task` set): resolve directly per the identifier (bound or standalone) — MCP `get_checkpoints` + `get_tasks`, or `get_tasks(standalone: true)`.
+
+Otherwise: use MCP `get_current_task` with repo_id (pass checkpoint_id if known to avoid disambiguation) to find the active checkpoint and in-progress task.
+
+If no in-progress task and Step 0 produced no identifier, show error: `No active task. Run /cbp-task-start first.`
+
+### Step 2: Determine Round Number
+
+If Step 0 produced `target_round`: use that as the round number directly (may target an existing round for resume, or N+1 for a new round — disambiguate by checking MCP `get_rounds`).
+
+Otherwise: use MCP `get_rounds` for the task; count existing rounds; next is N+1.
+
+### Step 3: Gather Round Requirements
+
+**If Step 0 parsed an identifier**: this skill was invoked to resume/start a specific round. Requirements come from existing round data (when the round exists) or task.requirements (for new round 1) — `$ARGUMENTS` is the identifier itself, NOT requirements text.
+
+**Else (free-text path), if round number is 1:**
+
+- Use `task.requirements` as the primary requirements
+- If `$ARGUMENTS` provided (free-text), merge as additional context
+
+**Else (free-text path), if round number > 1:**
+
+1. If `$ARGUMENTS` provided (from `/cbp-round-input`): use as round requirements
+2. If NO arguments: show error - `Round 2+ requires input. Run /cbp-round-input first.`
+
+### Step 4: Create Round in DB
+
+Use MCP `add_round`:
+- `task_id`: current task ID
+- `number`: next round number
+- `status`: "in_progress"
+- `started_at`: now (ISO format)
+- `triggered_by`: `"user"` | `"claude"` | `"auto_loop"` — `auto_loop` when `auto_loop_mode === true` flows in from round-input; `claude` when auto-triggered by testing failure; `user` otherwise
+- `requirements`: round requirements from Step 3
+- `context`: when `auto_loop_mode === true`, persist `auto_loop_mode: true`, `auto_loop_index: N`, `auto_loop_cap: C` into `round.context` (carried forward from round-input args)
+
+### Step 5: Load Context from DB
+
+Load from checkpoint and task:
+- Checkpoint context (decisions, dependencies, constraints, goal)
+- Task context and requirements
+- Resources from checkpoint and task (documentation links, API docs, guides)
+- Previous round results (files_changed, QA results)
+- For round 2+: load the latest completed round's `context.testing_qa_output` and `context.executor_output` via `get_rounds` response
+- Identify unapproved files from task.files_changed (where user_approved === false)
+
+### Step 6: First Round Analysis (Round 1 only)
+
+For the first round only:
+
+1. Analyze the task context and requirements thoroughly
+2. Identify any ambiguities or gaps
+3. If questions are needed, ask user via AskUserQuestion (max 4 per batch)
+4. If task context changes from Q&A answers:
+   - Update task context via MCP `update_task(task_id, context: {...})`
+   - Save Q&A decisions as `context.decisions[]`
+
+Skip this step for round 2+ (context already established via `/cbp-round-input`).
+
+**If `auto_loop_mode === true`, skip Q&A regardless of round number** — the auto-loop already has authoritative requirements from the prior round's findings (round 1 is always manual in practice, but the rule is explicit so future round-1 auto-loops follow it).
+
+### Step 7: Spawn Task Planner Agent
+
+Spawn `cbp-task-planner` agent with:
+```yaml
+input:
+  task_number: N
+  round_number: N
+  requirements: task.requirements
+  round_requirements: [round-specific input from Step 3]
+  checkpoint: {id, title, goal, context}
+  task: {id, title, requirements, context}
+  previous_rounds: {count, files_pending, files_changed, testing_qa_output, unapproved_files}
+```
+
+**Round 2+ context**: The planner receives the previous round's testing-qa output and list of unapproved files.
+
+**Priority**: If `round_requirements` is set (round 2+), the planner focuses on those specific goals while respecting `task.requirements` as context.
+
+Wait for planner output.
+
+### Step 8: User Approval
+
+Present the plan to user:
+
+```
+## Round [N] Plan
+
+**Goal**: [goal]
+
+### Steps:
+1. [step]
+2. [step]
+...
+
+### Files to modify:
+| File | Action | Purpose |
+|------|--------|---------|
+| ... | ... | ... |
+```
+
+**Wave table** — when `approved_plan.waves[]` contains ≥2 entries, render a wave summary table BEFORE the files table:
+
+```
+### Execution Waves
+| Wave | Agent type | Files | Depends on | Skill preloads |
+|------|-----------|-------|-----------|----------------|
+| web-ui | cbp-round-executor | 7 | — | cbp-frontend-design, cbp-frontend-a11y |
+| backend-api | cbp-round-executor | 4 | — | — |
+```
+
+Single-wave plans present the existing flat plan view (no wave table) — backward compatible.
+
+**If `auto_loop_mode === true`**: skip the AskUserQuestion below; auto-approve the plan. Log `round.context.plan_approval = { mode: "auto_loop", auto_approved_at: <ISO> }`. Surface a one-line note in the chat output: `"Auto-approved under auto_loop_mode (round N of cap C)"` so the user can see the loop is active. Proceed to Step 9.
+
+**Else (manual mode)**, ask user via AskUserQuestion with explicit options:
+
+1. **Yes** — approve and start execution
+2. **No — needs changes** — user provides feedback, revise the plan (re-run Step 7 with feedback)
+3. **No — totally wrong** — discard plan, return to `/cbp-round-input` for new requirements
+
+**If "Yes"**: proceed to Step 9.
+**If "Needs changes"**: collect user feedback, re-spawn `cbp-task-planner` with feedback as constraint, present revised plan, ask again.
+**If "Totally wrong"**: save rejection reason to round context, auto-trigger `/cbp-round-input`.
+
+### Step 9: Auto-trigger Round Execute
+
+On approval, save planner output to round context via MCP `update_round`, then trigger `/cbp-round-execute`.
+
+```
+Plan approved. Starting execution phase...
+```
+
+## Key Rules
+
+- **Planning ONLY** — no code execution, no testing
+- Planner gets full context (checkpoint + task + previous rounds)
+- Round 1 auto-triggered from `/cbp-task-start`
+- Round 2+ triggered from `/cbp-round-input`
+- Claude NEVER git adds files in round commands
+
+## Integration
+
+- **Reads**: MCP `get_current_task`, `get_rounds`
+- **Writes**: MCP `add_round`, `update_round`, `update_task` (context only)
+- **Spawns**: `cbp-task-planner`
+- **Triggers**: `/cbp-round-execute` (auto, on plan approval)
+- **Triggered by**: `/cbp-task-start` (round 1), `/cbp-round-input` (round 2+)