@sienklogic/plan-build-run 2.50.0 → 2.52.0

package/plugins/copilot-pbr/skills/begin/SKILL.md

@@ -3,16 +3,18 @@ name: begin
 description: "Start a new project. Deep questioning, research, requirements, and roadmap."
 ---
 
+**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.**
+
 # /pbr:begin — Project Initialization
 
-You are the orchestrator for `/pbr:begin`. This skill initializes a new Plan-Build-Run project through deep questioning, optional research, requirements scoping, and roadmap generation. Your job is to stay lean — delegate heavy work to agents and keep the user's main context window clean.
+You are the orchestrator for `/pbr:begin`. This skill initializes a new Plan-Build-Run project through deep questioning, optional research, requirements scoping, and roadmap generation. Your job is to stay lean — delegate heavy work to Task() agents and keep the user's main context window clean.
 
 ## Context Budget
 
 Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
 
 Additionally for this skill:
-- **Minimize** reading agent output — read only summaries, not full research docs
+- **Minimize** reading subagent output — read only summaries, not full research docs
 - **Delegate** all analysis work to agents — the orchestrator routes, it doesn't analyze
 
 ## Step 0 — Immediate Output
@@ -36,7 +38,7 @@ Then proceed to Step 1.
 
 ## Orchestration Flow
 
-Execute these steps in order. Each step specifies whether it runs inline (in your context) or is delegated to an agent.
+Execute these steps in order. Each step specifies whether it runs inline (in your context) or is delegated to a subagent.
 
 ---
 
@@ -118,7 +120,7 @@ Have a natural conversation to understand the user's vision. Do NOT present a fo
 
 ### Step 3: Workflow Preferences (inline)
 
-After understanding the project, configure the Plan-Build-Run workflow. Present preferences sequentially with conversational bridging (e.g., "Great. Next...") to keep the flow natural.
+After understanding the project, configure the Plan-Build-Run workflow. Use AskUserQuestion for each preference below. Present them sequentially with conversational bridging (e.g., "Great. Next...") to keep the flow natural.
 
 **3a. Mode:**
 Use the **toggle-confirm** pattern from `skills/shared/gate-prompts.md`:
@@ -165,7 +167,7 @@ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
 
 **After gathering preferences:**
 
-**CRITICAL: You MUST create the .planning/ directory and write config.json NOW. Do not proceed without this.**
+**CRITICAL (no hook): You MUST create the .planning/ directory and write config.json NOW. Do not proceed without this.**
 
 1. Read the config template from `skills/begin/templates/config.json.tmpl`
 2. Apply the user's choices to the template
@@ -174,7 +176,7 @@ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
 
 **IMPORTANT**: This step MUST happen BEFORE research (Step 5) because depth controls how many researchers to spawn.
 
-**CRITICAL: Write .active-skill NOW.** Write the text "begin" to `.planning/.active-skill` using the Write tool. Verify the file exists before proceeding.
+**CRITICAL (hook-enforced): Write .active-skill NOW.** Write the text "begin" to `.planning/.active-skill` using the Write tool. Verify the file exists before proceeding.
 
 ---
 
@@ -208,9 +210,9 @@ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
 
 ### Step 5: Research (delegated to agents)
 
-Spawn parallel agents for research. Each researcher writes to `.planning/research/`.
+Spawn parallel Task() agents for research. Each researcher writes to `.planning/research/`.
 
-**CRITICAL: Create .planning/research/ directory NOW before spawning researchers. Do NOT skip this step.**
+**CRITICAL (no hook): Create .planning/research/ directory NOW before spawning researchers. Do NOT skip this step.**
 
 **Learnings injection (opt-in):** Before spawning researchers, check if global learnings exist:
 
@@ -231,13 +233,19 @@ If the command succeeds AND returns a non-empty JSON array:
 
 If no learnings exist or the command fails: skip injection silently.
 
-**For each research topic, invoke the @researcher agent:**
+**For each research topic, spawn a Task():**
 
-Invoke `@researcher` with the research prompt constructed from the template.
+```
+Task({
+  subagent_type: "pbr:researcher",
+  // After researcher: check for ## RESEARCH COMPLETE or ## RESEARCH BLOCKED
+  prompt: <see researcher prompt template below>
+})
+```
 
-**NOTE**: The `@researcher` agent is defined in `agents/researcher.md`. Do NOT inline the agent definition — it wastes main context.
+**NOTE**: The `pbr:researcher` subagent type auto-loads the agent definition from `agents/researcher.md`. Do NOT inline the agent definition — it wastes main context.
 
-**Path resolution**: Before constructing any agent prompt, resolve plugin root to its absolute path. Use the resolved absolute path for any pbr-tools.js or template references included in the prompt.
+**Path resolution**: Before constructing any agent prompt, resolve `${PLUGIN_ROOT}` to its absolute path. Do not pass the variable literally in prompts — Task() contexts may not expand it. Use the resolved absolute path for any pbr-tools.js or template references included in the prompt.
 
 #### Researcher Prompt Template
 
@@ -246,9 +254,10 @@ For each researcher, construct the prompt by reading the template and filling in
 Read `skills/begin/templates/researcher-prompt.md.tmpl` for the prompt structure.
 
 **Prepend this block to the researcher prompt before sending:**
+
 ```
 <files_to_read>
-CRITICAL: Read these files BEFORE any other action:
+CRITICAL (no hook): Read these files BEFORE any other action:
 1. .planning/REQUIREMENTS.md — scoped requirements (if exists)
 {if learnings_temp_path exists}2. {learnings_temp_path} — cross-project learnings (tech stack patterns from past PBR projects){/if}
 </files_to_read>
@@ -292,28 +301,34 @@ If `{learnings_temp_path}` was produced in the learnings injection step above, r
 - What security concerns exist?
 
 **Parallelization:**
-- Spawn ALL researchers in parallel when possible
-- Before spawning, display to the user: `Spawning {N} researchers in parallel...`
-- When each completes: "{topic} researcher complete ({duration})"
-- When all complete: "All {N} researchers finished. Proceeding to synthesis."
+- Spawn ALL researchers in parallel (multiple Task() calls in one response)
+- Use `run_in_background: true` for each researcher
+- Before spawning, display to the user: `◐ Spawning {N} researchers in parallel...`
+- While waiting, display progress to the user:
+  - After spawning: list of topics being researched
+  - Periodically (every ~30s): check `TaskOutput` with `block: false` for each agent and report status
+  - When each completes: "✓ {topic} researcher complete ({duration})"
+  - When all complete: "All {N} researchers finished. Proceeding to synthesis."
 - Wait for all to complete before proceeding
 
-**After each researcher completes**, check the agent output for a completion marker:
-- If `## RESEARCH COMPLETE` is present: researcher finished successfully, proceed
-- If `## RESEARCH BLOCKED` is present: warn the user that research could not complete, ask if they want to proceed with limited context or stop
-- If neither marker is present: warn that researcher may not have completed successfully, but proceed if output files exist on disk
-
 ---
 
-### Step 6: Synthesis (delegated to agent)
+### Step 6: Synthesis (delegated to subagent)
+
+After all researchers complete, display to the user: `◐ Spawning synthesizer...`
 
-After all researchers complete, display to the user: `Spawning synthesizer...`
+Spawn a synthesis agent:
 
-Invoke the `@synthesizer` agent with the synthesis prompt.
+```
+Task({
+  subagent_type: "pbr:synthesizer",
+  prompt: <synthesis prompt>
+})
+```
 
-**NOTE**: The `@synthesizer` agent is defined in `agents/synthesizer.md`. Do NOT inline it.
+**NOTE**: The `pbr:synthesizer` subagent type auto-loads the agent definition. Do NOT inline it. The agent definition specifies `model: sonnet` — do not override it.
 
-**Path resolution**: Before constructing the agent prompt, resolve plugin root to its absolute path. Do not pass the variable literally in prompts.
+**Path resolution**: Before constructing the agent prompt, resolve `${PLUGIN_ROOT}` to its absolute path. Do not pass the variable literally in prompts — Task() contexts may not expand it.
 
 #### Synthesis Prompt Template
 
@@ -322,7 +337,7 @@ Read `skills/begin/templates/synthesis-prompt.md.tmpl` for the prompt structure.
 **Prepend this block to the synthesizer prompt before sending:**
 ```
 <files_to_read>
-CRITICAL: Read these files BEFORE any other action:
+CRITICAL (no hook): Read these files BEFORE any other action:
 1. .planning/research/*.md — all research output files from Step 5
 </files_to_read>
 ```
@@ -390,7 +405,7 @@ Each requirement must be:
 
 **7e. Write REQUIREMENTS.md:**
 
-**CRITICAL: Write REQUIREMENTS.md NOW. The roadmap planner depends on this file.**
+**CRITICAL (no hook): Write REQUIREMENTS.md NOW. The roadmap planner depends on this file.**
 
 Read the template from `skills/begin/templates/REQUIREMENTS.md.tmpl` and write `.planning/REQUIREMENTS.md` with:
 - All v1 requirements grouped by category
@@ -400,15 +415,23 @@ Read the template from `skills/begin/templates/REQUIREMENTS.md.tmpl` and write `
 
 ---
 
-### Step 8: Roadmap Generation (delegated to agent)
+### Step 8: Roadmap Generation (delegated to subagent)
+
+Display to the user: `◐ Spawning planner (roadmap)...`
 
-Display to the user: `Spawning planner (roadmap)...`
+Spawn the planner in roadmap mode:
 
-Invoke the `@planner` agent in roadmap mode with the roadmap prompt.
+```
+Task({
+  subagent_type: "pbr:planner",
+  // After planner: check for ## PLANNING COMPLETE or ## PLANNING FAILED
+  prompt: <roadmap prompt>
+})
+```
 
-**NOTE**: The `@planner` agent is defined in `agents/planner.md`. Do NOT inline it. The planner agent will read REQUIREMENTS.md and SUMMARY.md from disk — you only need to tell it what to do and where files are.
+**NOTE**: The `pbr:planner` subagent type auto-loads the agent definition. Do NOT inline it. The planner agent will read REQUIREMENTS.md and SUMMARY.md from disk — you only need to tell it what to do and where files are.
 
-**Path resolution**: Before constructing the agent prompt, resolve plugin root to its absolute path. Do not pass the variable literally in prompts.
+**Path resolution**: Before constructing the agent prompt, resolve `${PLUGIN_ROOT}` to its absolute path. Do not pass the variable literally in prompts — Task() contexts may not expand it.
 
 #### Roadmap Prompt Template
 
@@ -417,7 +440,7 @@ Read `skills/begin/templates/roadmap-prompt.md.tmpl` for the prompt structure.
 **Prepend this block to the roadmap planner prompt before sending:**
 ```
 <files_to_read>
-CRITICAL: Read these files BEFORE any other action:
+CRITICAL (no hook): Read these files BEFORE any other action:
 1. .planning/REQUIREMENTS.md — scoped requirements for phase planning
 2. .planning/research/SUMMARY.md — research synthesis (if exists)
 </files_to_read>
@@ -428,17 +451,14 @@ CRITICAL: Read these files BEFORE any other action:
 - `{description}` — project description from Step 2
 - `{quick|standard|comprehensive}` — depth setting from Step 3
 
-**After the planner completes**, check the agent output for a completion marker:
-- If `## PLANNING COMPLETE` is present: planner finished successfully, proceed
-- If `## PLANNING FAILED` is present: warn the user that planning could not complete, display the reason, and offer to retry or abort
-- If neither marker is present: warn that planner may not have completed successfully, but proceed if ROADMAP.md exists on disk
-
+**After the planner completes:**
 - **Spot-check:** Verify `.planning/ROADMAP.md` exists on disk using Glob before attempting to read it. If missing, the planner may have failed silently — warn: `⚠ ROADMAP.md not found after planner completed. Re-spawning planner...` and retry once.
 - Read `.planning/ROADMAP.md`
-- Count the phases and milestones from the roadmap content
+- Count the phases from the roadmap content
+- Verify the roadmap contains a `## Milestone:` section wrapping the phases (the planner should generate this). If not, the initial set of phases constitutes the first milestone — add the section header yourself.
 - Display:
   ```
-  Roadmap created — {N} phases across {M} milestones
+  ✓ Roadmap created — {N} phases in milestone "{name}"
   ```
 - If `gates.confirm_roadmap` is true in config, use the **approve-revise-abort** pattern from `skills/shared/gate-prompts.md`:
   question: "Approve this roadmap?"
@@ -446,7 +466,7 @@ CRITICAL: Read these files BEFORE any other action:
     - label: "Approve"          description: "Proceed with this roadmap"
     - label: "Request changes"  description: "Discuss adjustments before proceeding"
     - label: "Abort"            description: "Cancel and start over"
-    - If user selects "Request changes": edit the roadmap inline (small changes) or re-invoke planner
+    - If user selects "Request changes": edit the roadmap inline (small changes) or re-spawn planner
     - If user selects "Approve": proceed to Step 9
     - If user selects "Abort": stop execution
 
@@ -456,9 +476,9 @@ CRITICAL: Read these files BEFORE any other action:
 
 Write the project state files from templates:
 
-**CRITICAL: You MUST write all 5 state initialization files (Steps 9a-9e). Do NOT skip any.**
+**CRITICAL (no hook): You MUST write all 5 state initialization files (Steps 9a-9e). Do NOT skip any.**
 
-**CRITICAL: Write PROJECT.md NOW. Do NOT skip this step.**
+**CRITICAL (no hook): Write PROJECT.md NOW. Do NOT skip this step.**
 
 **9a. Write PROJECT.md:**
 1. Read `skills/begin/templates/PROJECT.md.tmpl`
@@ -472,7 +492,7 @@ Write the project state files from templates:
 3. Write to `.planning/PROJECT.md`
 4. Ensure the `## Milestones` section is filled in with the project name and phase count from the roadmap
 
-**CRITICAL: Write STATE.md NOW. Do NOT skip this step.**
+**CRITICAL (no hook): Write STATE.md NOW. Do NOT skip this step.**
 
 **9b. Write STATE.md:**
 1. Read `skills/begin/templates/STATE.md.tmpl`
@@ -486,7 +506,7 @@ Write the project state files from templates:
 4. Fill in the `## Milestone` section with the project name and total phase count
 5. **STATE.md size limit**: Follow size limit enforcement rules in `skills/shared/state-update.md` (150 lines max).
 
-**CRITICAL: Write CONTEXT.md NOW. Do NOT skip this step.**
+**CRITICAL (no hook): Write CONTEXT.md NOW. Do NOT skip this step.**
 
 **9c. Write CONTEXT.md:**
 Create `.planning/CONTEXT.md` from information gathered during questioning:
@@ -512,7 +532,7 @@ Create `.planning/CONTEXT.md` from information gathered during questioning:
 | {feature} | {reason} |
 ```
 
-**CRITICAL: Write HISTORY.md NOW. Do NOT skip this step.**
+**CRITICAL (no hook): Write HISTORY.md NOW. Do NOT skip this step.**
 
 **9d. Write HISTORY.md:**
 Create `.planning/HISTORY.md` with an initial entry:
@@ -527,7 +547,7 @@ Create `.planning/HISTORY.md` with an initial entry:
 - Roadmap: {N} phases planned
 ```
 
-**CRITICAL: Create phase directories NOW. Do NOT skip this step.**
+**CRITICAL (no hook): Create phase directories NOW. Do NOT skip this step.**
 
 **9e. Create phase directories:**
 For each phase in the roadmap, create the directory structure:
@@ -587,10 +607,10 @@ Display the `PROJECT INITIALIZED ✓` banner with project name, core value, phas
 ## Error Handling
 
 ### Research agent fails
-If a researcher agent fails or times out:
+If a researcher Task() fails or times out:
 - Note which topic wasn't researched
 - Continue with available research
-- Display: "Research on {topic} failed. Proceeding without it. You can re-research during /pbr:plan."
+- Display: `⚠ Research on {topic} failed. Proceeding without it. You can re-research during /pbr:plan.`
 
 ### User wants to restart
 If user says they want to start over mid-flow:
@@ -600,7 +620,9 @@ If user says they want to start over mid-flow:
 ### Config write fails
 If `.planning/` directory can't be created, display:
 ```
-ERROR
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
 
 Cannot create .planning/ directory.
 

package/plugins/copilot-pbr/skills/build/SKILL.md

@@ -63,7 +63,7 @@ Reference: `skills/shared/config-loading.md` for the tooling shortcut and config
 1. Parse `$ARGUMENTS` for phase number and flags
 2. Read `.planning/config.json` for parallelization, model, and gate settings (see config-loading.md for field reference)
 3. Resolve depth profile: run `node ${PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth` to get the effective feature/gate settings for the current depth. Store the result for use in later gating decisions.
-4. **CRITICAL: Write .active-skill NOW.** Write `.planning/.active-skill` with the content `build` (registers with workflow enforcement hook)
+4. **CRITICAL (hook-enforced): Write .active-skill NOW.** Write `.planning/.active-skill` with the content `build` (registers with workflow enforcement hook)
 5. Validate:
    - Phase directory exists at `.planning/phases/{NN}-{slug}/`
    - PLAN.md files exist in the directory
@@ -82,27 +82,17 @@ Reference: `skills/shared/config-loading.md` for the tooling shortcut and config
 
 **Staleness check (dependency fingerprints):**
 After validating prerequisites, check plan staleness:
-1. Read each PLAN.md file's `dependency_fingerprints` field (if present)
-2. For each fingerprinted dependency, check the current SUMMARY.md file (length + modification time)
-3. If any fingerprint doesn't match: the dependency phase was re-built after this plan was created
-4. Use AskUserQuestion (pattern: stale-continue from `skills/shared/gate-prompts.md`):
-   question: "Plan {plan_id} may be stale — dependency phase {M} was re-built after this plan was created."
-   header: "Stale"
-   options:
-     - label: "Continue anyway"  description: "Proceed with existing plans (may still be valid)"
-     - label: "Re-plan"          description: "Stop and re-plan with `/pbr:plan {N}` (recommended)"
-   If "Re-plan" or "Other": stop and suggest `/pbr:plan {N}`
-   If "Continue anyway": proceed with existing plans
-10. If plans have no `dependency_fingerprints` field, fall back to timestamp-based staleness detection:
-   a. Read `.planning/ROADMAP.md` and identify the current phase's dependencies (the `depends_on` field)
-   b. For each dependency phase, find its phase directory under `.planning/phases/`
-   c. Check if any SUMMARY.md files in the dependency phase directory have a modification timestamp newer than the current phase's PLAN.md files
-   d. If any upstream dependency was modified after planning, display a warning (do NOT block):
-      ```
-      Warning: Phase {dep_phase} (dependency of Phase {N}) was modified after this phase was planned.
-      Plans may be based on outdated assumptions. Consider re-planning with `/pbr:plan {N}`.
-      ```
-   e. This is advisory only — continue with the build after displaying the warning
+
+```bash
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js staleness-check {phase-slug}
+```
+
+Returns `{ stale: bool, plans: [{id, stale, reason}] }`. If `stale: true` for any plan:
+- Use AskUserQuestion (pattern: stale-continue from `skills/shared/gate-prompts.md`):
+  question: "Plan {plan_id} may be stale — {reason}"
+  options: ["Continue anyway", "Re-plan with /pbr:plan {N}"]
+- If "Re-plan": stop. If "Continue anyway": proceed.
+If `stale: false`: proceed silently.
 
 **Validation errors — use branded error boxes:**
 
@@ -198,30 +188,19 @@ Validate wave consistency:
 
 ### Step 5b: Write Checkpoint Manifest (inline)
 
-**CRITICAL: Write .checkpoint-manifest.json NOW before entering the wave loop.**
-
-Before entering the wave loop, write `.planning/phases/{NN}-{slug}/.checkpoint-manifest.json`:
+**CRITICAL (hook-enforced): Initialize checkpoint manifest NOW before entering the wave loop.**
 
-```json
-{
-  "plans": ["02-01", "02-02", "02-03"],
-  "checkpoints_resolved": [],
-  "checkpoints_pending": [],
-  "wave": 1,
-  "deferred": [],
-  "commit_log": [],
-  "last_good_commit": null
-}
+```bash
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js checkpoint init {phase-slug} --plans "{comma-separated plan IDs}"
 ```
 
-This file tracks execution progress for crash recovery and rollback. On resume after compaction, read this manifest to determine where execution left off and which plans still need work.
+After each wave completes, update the manifest:
 
-Update the manifest after each wave completes:
-- Move completed plan IDs into `checkpoints_resolved`
-- Advance the `wave` counter
-- Record commit SHAs in `commit_log` (array of `{ plan, sha, timestamp }` objects)
-- Update `last_good_commit` to the SHA of the last successfully verified commit
-- Append any deferred items collected from executor SUMMARYs
+```bash
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js checkpoint update {phase-slug} --wave {N} --resolved {plan-id} --sha {commit-sha}
+```
+
+This tracks execution for crash recovery and rollback. Read `.checkpoint-manifest.json` on resume to reconstruct which plans are complete.
 
 ---
 
@@ -325,11 +304,11 @@ Use the filled template as the Task() prompt.
 
 ```
 Task({
-  agent_type: "pbr:executor",
+  subagent_type: "pbr:executor",
   prompt: <executor prompt constructed above>
 })
 
-NOTE: The pbr:executor agent type auto-loads the agent definition.
+NOTE: The pbr:executor subagent type auto-loads the agent definition.
 
 After executor completes, check for completion markers: `## PLAN COMPLETE`, `## PLAN FAILED`, or `## CHECKPOINT: {TYPE}`. Route accordingly — PLAN COMPLETE proceeds to next plan, PLAN FAILED triggers failure handling, CHECKPOINT triggers checkpoint flow. Do NOT inline it.
 ```
@@ -357,7 +336,7 @@ For each completed executor:
 
 **Spot-check executor claims:**
 
-CRITICAL: Before reading results or advancing to the next wave, run the spot-check CLI for each completed plan.
+CRITICAL (no hook): Before reading results or advancing to the next wave, run the spot-check CLI for each completed plan.
 
 For each completed plan in this wave:
 
@@ -392,13 +371,7 @@ Use AskUserQuestion with the three options. Route:
 - Also search SUMMARY.md for `## Self-Check: FAILED` marker — if present, warn before next wave
 - Between waves: verify no file conflicts from parallel executors (`git status` for uncommitted changes)
 
-**Additional wave spot-checks:**
-- Check for `## Self-Check: FAILED` in SUMMARY.md — if present, warn user before proceeding to next wave
-- Between waves: verify no file conflicts from parallel executors (check `git status` for uncommitted changes)
-- If ANY spot-check fails, present user with: **Retry this plan** / **Continue to next wave** / **Abort build**
-
 **Read executor deviations:**
-
 After all executors in the wave complete, read all SUMMARY frontmatter and:
 - Collect `deferred` items into a running list (append to `.checkpoint-manifest.json` deferred array)
 - Flag any deviation-rule-4 (architectural) stops — these require user attention
@@ -419,16 +392,14 @@ Wave {W} Results:
 
 **Skip if** the depth profile has `features.inline_verify: false`.
 
-To check: use the resolved depth profile. Only `comprehensive` mode enables inline verification by default.
-
-When inline verification is enabled, each completed plan gets a targeted verification pass before the orchestrator proceeds to the next wave. This catches issues early — before dependent plans build on a broken foundation.
+To check: use the resolved depth profile. Only `comprehensive` mode enables inline verification by default. When inline verification is enabled, each completed plan gets a targeted verification pass before the orchestrator proceeds to the next wave — catching issues early before dependent plans build on a broken foundation.
 
 For each plan that completed successfully in this wave:
 
 1. Read the plan's SUMMARY.md to get `key_files` (the files this plan created/modified)
 2. Display to the user: `◐ Spawning inline verifier for plan {plan_id}...`
 
-   Spawn `Task({ agent_type: "pbr:verifier", model: "haiku", prompt: ... })`. Read `skills/build/templates/inline-verifier-prompt.md.tmpl` and fill in `{NN}-{slug}`, `{plan_id}`, and `{comma-separated key_files list}` (key_files from PLAN.md frontmatter). Use the filled template as the `prompt` value.
+   Spawn `Task({ subagent_type: "pbr:verifier", model: "haiku", prompt: ... })`. Read `skills/build/templates/inline-verifier-prompt.md.tmpl` and fill in `{NN}-{slug}`, `{plan_id}`, and `{comma-separated key_files list}` (key_files from PLAN.md frontmatter). Use the filled template as the `prompt` value.
 
 3. If verifier reports FAIL for any file:
    - Present the failure to the user: "Inline verify failed for plan {plan_id}: {details}"
@@ -487,19 +458,17 @@ Use AskUserQuestion (pattern: multi-option-failure from `skills/shared/gate-prom
 - If yes: warn user that those plans will also need to be skipped or adjusted
 
 **If user selects 'Rollback':**
-- Read `last_good_commit` from `.checkpoint-manifest.json`
-- If `last_good_commit` exists:
-  - Show the user: "Rolling back to commit {sha} (last verified good state). This will soft-reset {N} commits."
-  - Run: `git reset --soft {last_good_commit}`
-  - Delete the failed plan's SUMMARY.md file if it was created
-  - **CRITICAL — Invalidate downstream dependencies:**
-    - Check if any plans in later waves depend on the rolled-back plan
-    - For each downstream plan that depends on it: delete its SUMMARY.md (forces re-execution)
-    - Remove ALL downstream dependent plans from `checkpoints_resolved` in the manifest
-    - If downstream phases (outside this build) have `dependency_fingerprints` referencing this phase, warn: "Downstream phases may need re-planning with `/pbr:plan <N>` since Phase {current} was partially rolled back."
-  - Update the checkpoint manifest: remove the failed plan from `checkpoints_resolved`
-  - Continue to next wave or stop based on user preference
-- If no `last_good_commit`: warn "No rollback point available (this was the first plan). Use abort instead."
+Run the rollback CLI:
+
+```bash
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js rollback .planning/phases/{NN}-{slug}/.checkpoint-manifest.json
+```
+
+Returns `{ ok, rolled_back_to, plans_invalidated, files_deleted, warnings }`.
+
+- If `ok` is `true`: display "Rolled back to commit {rolled_back_to}. {plans_invalidated.length} downstream plans invalidated."
+  Show any warnings. Continue to next wave or stop based on user preference.
+- If `ok` is `false`: display the error message. Suggest "Use abort instead."
 
 **If user selects 'Abort':**
 - Update STATE.md with current progress
@@ -544,34 +513,34 @@ If `config.ci.gate_enabled` is `true` AND `config.git.branching` is not `none`:
 
 1. Push current commits: `git push`
 2. Wait 5 seconds for CI to trigger
-3. Check: `gh run list --branch $(git branch --show-current) --limit 1 --json status,conclusion,url`
-4. If in_progress: poll every 15 seconds up to `config.ci.wait_timeout_seconds`
-5. If failed/timed out: show warning box:
-
+3. Get the current run ID:
+   ```bash
+   gh run list --branch $(git branch --show-current) --limit 1 --json databaseId -q '.[0].databaseId'
    ```
-   ⚠ CI Status: {conclusion}
-   Run: {url}
-   Options: [Wait] [Continue anyway] [Abort]
+4. Poll CI status using CLI:
+   ```bash
+   node ${PLUGIN_ROOT}/scripts/pbr-tools.js ci-poll <run-id> [--timeout <seconds>]
    ```
-
-6. Use AskUserQuestion to present options: Wait / Continue anyway / Abort
-7. If "Continue anyway": log deviation — `DEVIATION: CI gate bypassed for wave {N}`
-8. If "Abort": stop build, update STATE.md
+   Returns `{ status, conclusion, url, next_action, elapsed_seconds }`.
+5. If `next_action` is `"continue"`: proceed to next wave
+6. If `next_action` is `"wait"`: re-run ci-poll after 15 seconds (repeat up to `config.ci.wait_timeout_seconds`)
+7. If `next_action` is `"abort"` or `status` is `"failed"`:
+   Show warning box and use AskUserQuestion: Wait / Continue anyway / Abort
+8. If "Continue anyway": log deviation — `DEVIATION: CI gate bypassed for wave {N}`
+9. If "Abort": stop build, update STATE.md
 
 #### 6f. Update STATE.md
 
 After each wave completes (all plans in the wave are done, skipped, or aborted):
 
 **SUMMARY gate — verify before updating STATE.md:**
+For every plan in the wave, run:
 
-Before writing any STATE.md update, verify these three gates for every plan in the wave:
-1. SUMMARY file exists at the expected path
-2. SUMMARY file is not empty (file size > 0)
-3. SUMMARY file has a valid title and YAML frontmatter (contains `---` delimiters and a `status:` field)
+```bash
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js summary-gate {phase-slug} {plan-id}
+```
 
-Block the STATE.md update until ALL gates pass. If any gate fails:
-- Warn user: "SUMMARY gate failed for plan {id}: {which gate}. Cannot update STATE.md."
-- Ask user to retry the executor or manually inspect the SUMMARY file
+Returns `{ ok: bool, gate: string, detail: string }`. Block STATE.md update until ALL plans return `ok: true`. If any fail, warn: "SUMMARY gate failed for plan {id}: {gate} — {detail}. Cannot update STATE.md."
 
 Once gates pass, update `.planning/STATE.md`:
 
@@ -589,6 +558,12 @@ node ${PLUGIN_ROOT}/scripts/pbr-tools.js state update last_activity now
 
 **STATE.md size limit:** Follow the size limit enforcement rules in `skills/shared/state-update.md` (150 lines max — collapse completed phases, remove duplicated decisions, trim old sessions).
 
+**Completion check:** Before proceeding to next wave, confirm ALL of:
+- [ ] SUMMARY gate passed for every plan in this wave
+- [ ] STATE.md frontmatter `plans_complete` updated
+- [ ] STATE.md body progress bar updated
+- [ ] `last_activity` timestamp refreshed
+
 ---
 
 ### Step 7: Phase Verification (delegated, conditional)
@@ -615,11 +590,11 @@ Spawn a verifier Task():
 
 ```
 Task({
-  agent_type: "pbr:verifier",
+  subagent_type: "pbr:verifier",
   prompt: <verifier prompt>
 })
 
-NOTE: The pbr:verifier agent type auto-loads the agent definition. Do NOT inline it.
+NOTE: The pbr:verifier subagent type auto-loads the agent definition. Do NOT inline it.
 
 After verifier completes, check for completion marker: `## VERIFICATION COMPLETE`. Read VERIFICATION.md frontmatter for status.
 ```
@@ -633,7 +608,7 @@ Use the same verifier prompt template as defined in `/pbr:review`: read `skills/
 **Prepend this block to the verifier prompt before sending:**
 ```
 <files_to_read>
-CRITICAL: Read these files BEFORE any other action:
+CRITICAL (no hook): Read these files BEFORE any other action:
 1. .planning/phases/{NN}-{slug}/PLAN-*.md — must-haves to verify against
 2. .planning/phases/{NN}-{slug}/SUMMARY-*.md — executor build summaries
 3. .planning/phases/{NN}-{slug}/VERIFICATION.md — prior verification results (if exists)
@@ -684,14 +659,14 @@ If triggered:
    Spawn a lightweight mapper Task():
    ```
    Task({
-     agent_type: "pbr:codebase-mapper",
+     subagent_type: "pbr:codebase-mapper",
      model: "haiku",
      prompt: "Incremental codebase map update. These files changed during the Phase {N} build:\n{diff file list}\n\nRead the existing .planning/codebase/ documents. Update ONLY the sections affected by these changes. Do NOT rewrite entire documents — make targeted updates. If a new dependency was added, update STACK.md. If new directories/modules were created, update STRUCTURE.md. If new patterns were introduced, update CONVENTIONS.md. Write updated files to .planning/codebase/."
    })
    ```
 4. Do NOT block on this — use `run_in_background: true` and continue to Step 8a. Report completion in Step 8f if it finishes in time.
 
-**CRITICAL: Update ROADMAP.md progress table NOW. Do NOT skip this step.**
+**CRITICAL (no hook): Update ROADMAP.md progress table NOW. Do NOT skip this step. (roadmap-sync warns)**
 
 **8a. Update ROADMAP.md Progress table** (REQUIRED — do this BEFORE updating STATE.md):
 
@@ -709,13 +684,18 @@ These return `{ success, old_status, new_status }` or `{ success, old_plans, new
 5. Update the `Status` column to the final_status determined in Step 8-pre
 6. Save the file — do NOT skip this step
 
-**CRITICAL: Update STATE.md NOW with phase completion status. Do NOT skip this step.**
+**CRITICAL (no hook): Update STATE.md NOW with phase completion status. Do NOT skip this step. (state-sync warns)**
 
-**8b. Update STATE.md (CRITICAL — update BOTH frontmatter AND body):**
+**8b. Update STATE.md (CRITICAL (no hook) — update BOTH frontmatter AND body):**
 - Frontmatter: `status`, `plans_complete`, `last_activity`, `progress_percent`, `last_command`
 - Body `## Current Position`: `Phase:` line, `Plan:` line, `Status:` line, `Last activity:` line, `Progress:` bar
 - These MUST stay in sync — the status line reads frontmatter, humans read the body
 
+**Completion check:** Before proceeding to 8c, confirm ALL of:
+- [ ] STATE.md frontmatter fields set: status, plans_complete, last_activity, progress_percent, last_command
+- [ ] STATE.md body ## Current Position updated: Phase, Status, Last activity, Progress bar
+- [ ] Frontmatter and body are consistent (same status value in both)
+
 **8c. Commit planning docs (if configured):**
 Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.
 If `planning.commit_docs` is `true`:
@@ -779,6 +759,12 @@ After invoking the chained skill, it runs within the same session. When it compl
 Write `.planning/.auto-next` containing the next logical command (e.g., `/pbr:plan {N+1}` or `/pbr:review {N}`)
 - This file signals to the user or to wrapper scripts that the next step is ready
 
+**Completion check:** Before proceeding to 8f, confirm ALL of:
+- [ ] auto_advance OR auto_continue evaluated (one path taken)
+- [ ] If auto_continue: `.auto-next` file written with correct next command
+- [ ] Pending todos evaluated (Step 8e-ii)
+- [ ] Clearly-satisfied todos auto-closed via `pbr-tools.js todo done`
+
 **8e-ii. Check Pending Todos:**
 
 **CRITICAL (no hook): Check pending todos after build. Do NOT skip this step.**