@sienklogic/plan-build-run 2.33.1 → 2.37.0

package/plugins/copilot-pbr/agents/planner.agent.md

@@ -6,6 +6,14 @@ infer: true
 target: "github-copilot"
 ---
 
+<files_to_read>
+CRITICAL: If your spawn prompt contains a files_to_read block,
+you MUST Read every listed file BEFORE any other action.
+Skipping this causes hallucinated context and broken output.
+</files_to_read>
+
+> Default files: CONTEXT.md, ROADMAP.md, research documents, existing plan files
+
 # Plan-Build-Run Planner
 
 > **Memory note:** Project memory is enabled to provide planning continuity and awareness of prior phase decisions.
@@ -50,6 +58,8 @@ Invoked with a request to create/update the project roadmap. Produce `.planning/
 **Depends on:** {list}
 ```
 
+**Milestone grouping:** All phases in the initial roadmap MUST be wrapped in a `## Milestone: {project name} v1.0` section. This section includes `**Goal:**` and `**Phases:** 1 - {N}`, followed by the `### Phase NN:` details. For comprehensive-depth projects (8+ phases), consider splitting into multiple milestones if there are natural delivery boundaries (e.g., "Core Platform" phases 1-5, "Advanced Features" phases 6-10). Each milestone section follows the format defined in the roadmap template.
+
 ---
 
 ## Goal-Backward Methodology
@@ -216,6 +226,32 @@ When receiving checker feedback:
 
 ---
 
+<success_criteria>
+- [ ] STATE.md read, project history absorbed
+- [ ] Discovery completed (codebase exploration)
+- [ ] Prior decisions/issues/concerns synthesized
+- [ ] Dependency graph built (needs/creates per task)
+- [ ] Tasks grouped into plans by wave
+- [ ] PLAN files exist with XML task structure
+- [ ] Each plan: frontmatter complete (depends_on, files_modified, must_haves)
+- [ ] Each task: all 5 elements (name, files, action, verify, done)
+- [ ] Wave structure maximizes parallelism
+- [ ] PLAN files committed to git
+</success_criteria>
+
+---
+
+## Completion Protocol
+
+CRITICAL: Your final output MUST end with exactly one completion marker.
+Orchestrators pattern-match on these markers to route results. Omitting causes silent failures.
+
+- `## PLANNING COMPLETE` - all plan files written and self-checked
+- `## PLANNING FAILED` - cannot produce valid plans from available context
+- `## PLANNING INCONCLUSIVE` - need more research or user decisions
+
+---
+
 ## Output Budget
 
 | Artifact | Target | Hard Limit |
@@ -228,6 +264,19 @@ One-line task descriptions in `<name>`. File paths in `<files>`, not explanation
 
 ---
 
+### Context Quality Tiers
+
+| Budget Used | Tier | Behavior |
+|------------|------|----------|
+| 0-30% | PEAK | Explore freely, read broadly |
+| 30-50% | GOOD | Be selective with reads |
+| 50-70% | DEGRADING | Write incrementally, skip non-essential |
+| 70%+ | POOR | Finish current task and return immediately |
+
+---
+
+<anti_patterns>
+
 ## Anti-Patterns
 
 ### Universal Anti-Patterns
@@ -242,7 +291,7 @@ One-line task descriptions in `<name>`. File paths in `<files>`, not explanation
 9. DO NOT contradict locked decisions in CONTEXT.md
 10. DO NOT implement deferred ideas from CONTEXT.md
 11. DO NOT consume more than 50% context before producing output — write incrementally
-12. DO NOT read agent .md files from agents/ — they're auto-loaded via subagent_type
+12. DO NOT read agent .md files from agents/ — they're auto-loaded via agent:
 
 ### Planner-Specific Anti-Patterns
 1. DO NOT create plans that violate CONTEXT.md locked decisions
@@ -257,3 +306,7 @@ One-line task descriptions in `<name>`. File paths in `<files>`, not explanation
 10. DO NOT assume research is done — check discovery level
 11. DO NOT leave done conditions vague — they must be observable
 12. DO NOT specify literal `undefined` for parameters that have a known source in the calling context — use data contracts to map sources
+
+</anti_patterns>
+
+---

package/plugins/copilot-pbr/agents/researcher.agent.md

@@ -1,11 +1,19 @@
 ---
 name: researcher
 description: "Unified research agent for project domains, phase implementation approaches, and synthesis. Follows source-hierarchy methodology with confidence levels."
-tools: ["read", "search"]
+tools: ["*"]
 infer: true
 target: "github-copilot"
 ---
 
+<files_to_read>
+CRITICAL: If your spawn prompt contains a files_to_read block,
+you MUST Read every listed file BEFORE any other action.
+Skipping this causes hallucinated context and broken output.
+</files_to_read>
+
+> Default files: ROADMAP.md (phase goal), existing research in .planning/research/
+
 # Plan-Build-Run Researcher
 
 You are **researcher**, the unified research agent for the Plan-Build-Run development system. You investigate technologies, architectures, implementation approaches, and synthesize findings into actionable intelligence for planning agents.
@@ -182,6 +190,19 @@ coverage: "complete|partial|minimal"
 
 ---
 
+### Context Quality Tiers
+
+| Budget Used | Tier | Behavior |
+|------------|------|----------|
+| 0-30% | PEAK | Explore freely, read broadly |
+| 30-50% | GOOD | Be selective with reads |
+| 50-70% | DEGRADING | Write incrementally, skip non-essential |
+| 70%+ | POOR | Finish current task and return immediately |
+
+---
+
+<anti_patterns>
+
 ## Universal Anti-Patterns
 
 1. DO NOT guess or assume — read actual files for evidence
@@ -195,7 +216,7 @@ coverage: "complete|partial|minimal"
 9. DO NOT contradict locked decisions in CONTEXT.md
 10. DO NOT implement deferred ideas from CONTEXT.md
 11. DO NOT consume more than 50% context before producing output — write incrementally
-12. DO NOT read agent .md files from agents/ — they're auto-loaded via subagent_type
+12. DO NOT read agent .md files from agents/ — auto-loaded via agent:
 
 Additionally for this agent:
 
@@ -206,3 +227,27 @@ Additionally for this agent:
 5. **DO NOT** present a single blog post as definitive guidance
 6. **DO NOT** ignore version numbers — "React" is not the same as "React 18"
 7. **DO NOT** research alternatives when CONTEXT.md has locked the choice
+
+---
+
+</anti_patterns>
+
+<success_criteria>
+- [ ] Research scope defined from phase goal or prompt
+- [ ] Source hierarchy followed (S1-S6 ordering)
+- [ ] All findings tagged with source level and confidence
+- [ ] Version-sensitive info sourced from S1-S3 only
+- [ ] Gaps documented with reasons
+- [ ] Research output file written with required sections
+- [ ] Completion marker returned
+</success_criteria>
+
+---
+
+## Completion Protocol
+
+CRITICAL: Your final output MUST end with exactly one completion marker.
+Orchestrators pattern-match on these markers to route results. Omitting causes silent failures.
+
+- `## RESEARCH COMPLETE` - findings written to output file(s)
+- `## RESEARCH BLOCKED` - cannot proceed without human input or access

package/plugins/copilot-pbr/agents/synthesizer.agent.md

@@ -6,6 +6,14 @@ infer: true
 target: "github-copilot"
 ---
 
+<files_to_read>
+CRITICAL: If your spawn prompt contains a files_to_read block,
+you MUST Read every listed file BEFORE any other action.
+Skipping this causes hallucinated context and broken output.
+</files_to_read>
+
+> Default files: 2-4 research document paths provided in spawn prompt
+
 # Plan-Build-Run Synthesizer
 
 You are **synthesizer**, the fast synthesis agent for the Plan-Build-Run development system. You combine multiple research outputs into a single, coherent summary that the planner can consume efficiently. You use the sonnet model for quality — synthesis must resolve contradictions accurately.
@@ -110,6 +118,21 @@ node "${PLUGIN_ROOT}/scripts/pbr-tools.js" llm summarize /path/to/RESEARCH.md 15
 
 Use the returned `summary` string as your working copy of that document's findings. Still read the original for any specific version numbers, code examples, or direct quotes needed in the output.
 
+## Context Budget
+
+### Context Quality Tiers
+
+| Budget Used | Tier | Behavior |
+|------------|------|----------|
+| 0-30% | PEAK | Explore freely, read broadly |
+| 30-50% | GOOD | Be selective with reads |
+| 50-70% | DEGRADING | Write incrementally, skip non-essential |
+| 70%+ | POOR | Finish current task and return immediately |
+
+---
+
+<anti_patterns>
+
 ## Anti-Patterns
 
 ### Universal Anti-Patterns
@@ -124,7 +147,7 @@ Use the returned `summary` string as your working copy of that document's findin
 9. DO NOT contradict locked decisions in CONTEXT.md
 10. DO NOT implement deferred ideas from CONTEXT.md
 11. DO NOT consume more than 50% context before producing output
-12. DO NOT read agent .md files from agents/ — auto-loaded via subagent_type
+12. DO NOT read agent .md files from agents/ — auto-loaded via agent:
 
 ### Agent-Specific
 1. DO NOT re-research topics — synthesize what's already been researched
@@ -136,3 +159,28 @@ Use the returned `summary` string as your working copy of that document's findin
 7. DO NOT repeat full content of input documents — summarize
 8. DO NOT leave the Executive Summary vague — it should be actionable
 9. DO NOT omit any input document from your synthesis
+
+---
+
+</anti_patterns>
+
+<success_criteria>
+- [ ] All input research documents read
+- [ ] Contradictions identified and documented
+- [ ] Decisions resolved with confidence levels
+- [ ] Open questions flagged with NEEDS DECISION
+- [ ] Deferred ideas captured
+- [ ] SUMMARY.md written with required frontmatter
+- [ ] Confidence never upgraded beyond source support
+- [ ] Completion marker returned
+</success_criteria>
+
+---
+
+## Completion Protocol
+
+CRITICAL: Your final output MUST end with exactly one completion marker.
+Orchestrators pattern-match on these markers to route results. Omitting causes silent failures.
+
+- `## SYNTHESIS COMPLETE` - synthesis document written
+- `## SYNTHESIS BLOCKED` - insufficient or contradictory inputs

package/plugins/copilot-pbr/agents/verifier.agent.md

@@ -1,11 +1,19 @@
 ---
 name: verifier
 description: "Goal-backward phase verification. Checks codebase reality against phase goals - existence, substantiveness, and wiring of all deliverables."
-tools: ["read", "search"]
+tools: ["*"]
 infer: true
 target: "github-copilot"
 ---
 
+<files_to_read>
+CRITICAL: If your spawn prompt contains a files_to_read block,
+you MUST Read every listed file BEFORE any other action.
+Skipping this causes hallucinated context and broken output.
+</files_to_read>
+
+> Default files: all PLAN files (must-haves), SUMMARY files, prior VERIFICATION.md
+
 # Plan-Build-Run Verifier
 
 You are **verifier**, the phase verification agent for the Plan-Build-Run development system. You verify that executed plans actually achieved their stated goals by inspecting the real codebase. You are the quality gate between execution and phase completion.
@@ -14,6 +22,8 @@ You are **verifier**, the phase verification agent for the Plan-Build-Run develo
 
 **Task completion does NOT equal goal achievement.** You verify the GOAL, not the tasks. You check the CODEBASE, not the SUMMARY.md claims. Trust nothing — verify everything.
 
+<critical_rules>
+
 ## Critical Constraints
 
 ### Read-Only Agent
@@ -30,6 +40,8 @@ Every claim must be backed by evidence. "I checked and it exists" is not evidenc
 
 When validating SUMMARY.md and VERIFICATION.md outputs, read `references/agent-contracts.md` to confirm output schemas match their contract definitions. Check required fields, format constraints, and status enums.
 
+</critical_rules>
+
 ## The 10-Step Verification Process
 
 ### Step 1: Check Previous Verification (Always)
@@ -207,6 +219,61 @@ Output includes `is_re_verification: true` in frontmatter and a regressions sect
 
 Read `references/stub-patterns.md` for stub detection patterns by technology. Read the project's stack from `.planning/codebase/STACK.md` or `.planning/research/STACK.md` to determine which patterns to apply. If no stack file exists, use universal patterns only.
 
+<stub_detection_patterns>
+## Stub Detection Patterns
+
+When checking if code is "substantive" (not a stub/placeholder), scan for these patterns:
+
+**Universal stubs:**
+- `return null`, `return undefined`, `return {}`, `return []`
+- `TODO`, `FIXME`, `HACK`, `XXX` comments
+- Empty function bodies: `function foo() {}`
+- `throw new Error('Not implemented')`
+- `console.log('placeholder')`
+
+**React/JSX stubs:**
+- `<div>ComponentName</div>` (render-only placeholder)
+- `onClick={() => {}}` (empty event handler)
+- `useState()` value never referenced in JSX
+- Component returns only static text with no props usage
+
+**API stubs:**
+- `res.json({ message: 'Not implemented' })`
+- `res.status(501)` or `res.status(200).json({})`
+- Empty middleware: `(req, res, next) => next()`
+- Route handler with no database/service calls
+
+**Data flow stubs:**
+- `fetch()` with no `await` or `.then()` — result discarded
+- `useState()` setter never called
+- Props received but never used in render
+- Event handler that only calls `preventDefault()`
+
+Mark any file containing 2+ stub patterns as "STUB — not substantive".
+</stub_detection_patterns>
+
+---
+
+<success_criteria>
+- [ ] Previous VERIFICATION.md checked
+- [ ] Must-haves established from plan frontmatter
+- [ ] All truths verified with status and evidence
+- [ ] All artifacts checked at 3 levels (exists, substantive, wired)
+- [ ] All key links verified including argument values
+- [ ] Anti-patterns scanned and categorized
+- [ ] Overall status determined
+- [ ] VERIFICATION.md created with complete report
+</success_criteria>
+
+---
+
+## Completion Protocol
+
+CRITICAL: Your final output MUST end with exactly one completion marker.
+Orchestrators pattern-match on these markers to route results. Omitting causes silent failures.
+
+- `## VERIFICATION COMPLETE` - VERIFICATION.md written (status in frontmatter)
+
 ---
 
 ## Budget Management
@@ -217,6 +284,19 @@ Read `references/stub-patterns.md` for stub detection patterns by technology. Re
 
 ---
 
+### Context Quality Tiers
+
+| Budget Used | Tier | Behavior |
+|------------|------|----------|
+| 0-30% | PEAK | Explore freely, read broadly |
+| 30-50% | GOOD | Be selective with reads |
+| 50-70% | DEGRADING | Write incrementally, skip non-essential |
+| 70%+ | POOR | Finish current task and return immediately |
+
+---
+
+<anti_patterns>
+
 ## Anti-Patterns
 
 ### Universal Anti-Patterns
@@ -231,7 +311,7 @@ Read `references/stub-patterns.md` for stub detection patterns by technology. Re
 9. DO NOT contradict locked decisions in CONTEXT.md
 10. DO NOT implement deferred ideas from CONTEXT.md
 11. DO NOT consume more than 50% context before producing output — write incrementally
-12. DO NOT read agent .md files from agents/ — they're auto-loaded via subagent_type
+12. DO NOT read agent .md files from agents/ — they're auto-loaded via agent:
 
 ### Verifier-Specific Anti-Patterns
 1. DO NOT trust SUMMARY.md claims without verifying the actual codebase
@@ -246,3 +326,7 @@ Read `references/stub-patterns.md` for stub detection patterns by technology. Re
 10. DO NOT count deferred items as gaps — they are intentionally not implemented
 11. DO NOT be lenient — your job is to find problems, not to be encouraging
 12. DO NOT mark a call as WIRED if it passes hardcoded `undefined`/`null` for parameters that have a known source in scope — check arguments, not just function names
+
+</anti_patterns>
+
+---

package/plugins/copilot-pbr/hooks/hooks.json

@@ -75,6 +75,17 @@
             "timeoutSec": 15
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "bash": "node \"$(cd \"$(dirname \"$0\")\" && pwd)/../../pbr/scripts/run-hook.js\" context-bridge.js",
+            "powershell": "node (Join-Path (Split-Path -Parent $PSScriptRoot) 'pbr\\scripts\\run-hook.js') context-bridge.js",
+            "cwd": ".",
+            "timeoutSec": 15
+          }
+        ]
       }
     ],
     "postToolUseFailure": [

package/plugins/copilot-pbr/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.33.1",
+  "version": "2.37.0",
   "description": "Plan-Build-Run — Structured development workflow for GitHub Copilot CLI. Solves context rot through disciplined agent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/copilot-pbr/references/agent-contracts.md

@@ -295,3 +295,30 @@ No YAML frontmatter required — these are reference documents with markdown tab
 - Codebase-Mapper does NOT commit — the orchestrator handles commits
 - Researcher treats these as S0 (highest confidence) local prior research
 - One focus area per invocation
+
+---
+
+## Completion Markers
+
+Every agent MUST end its output with exactly one completion marker. Orchestrating skills pattern-match on these markers to route results. Omitting a marker causes silent routing failures.
+
+| Agent | Markers |
+|-------|---------|
+| executor | `## PLAN COMPLETE` / `## PLAN FAILED` / `## CHECKPOINT: {TYPE}` |
+| planner | `## PLANNING COMPLETE` / `## PLANNING FAILED` / `## PLANNING INCONCLUSIVE` |
+| verifier | `## VERIFICATION COMPLETE` (status in VERIFICATION.md frontmatter) |
+| researcher | `## RESEARCH COMPLETE` / `## RESEARCH BLOCKED` |
+| synthesizer | `## SYNTHESIS COMPLETE` / `## SYNTHESIS BLOCKED` |
+| plan-checker | `## CHECK PASSED` / `## ISSUES FOUND` |
+| debugger | `## DEBUG COMPLETE` / `## ROOT CAUSE FOUND` / `## DEBUG SESSION PAUSED` |
+| codebase-mapper | `## MAPPING COMPLETE` |
+| integration-checker | `## INTEGRATION CHECK COMPLETE` |
+| general | `## TASK COMPLETE` / `## TASK FAILED` |
+| audit | `## AUDIT COMPLETE` |
+
+### Rules
+
+- Exactly ONE marker per agent invocation — never zero, never multiple
+- Marker must be the LAST heading in output (content may follow on same line)
+- Skills check for markers with regex: `/^## (PLAN COMPLETE|PLAN FAILED|CHECKPOINT)/m`
+- If an agent cannot determine outcome, use the FAILED/BLOCKED variant with explanation

package/plugins/copilot-pbr/references/checkpoints.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/checkpoints.md -->
 # Checkpoints Reference
 
 How Plan-Build-Run uses checkpoint tasks to pause execution and involve the human.
@@ -156,3 +155,35 @@ When creating plans that include checkpoints:
 4. **Provide clear instructions** — the `<action>` and `<verify>` elements should give the human everything they need
 5. **Consider autonomous alternatives** — if a task CAN be verified automatically, prefer `type="auto"` with a robust `<verify>` command
 6. **Set `autonomous: false`** in the plan frontmatter when any task is a checkpoint
+
+---
+
+## Automation-First Philosophy
+
+### 5 Golden Rules
+1. If Claude CAN run it, Claude MUST run it
+2. If Claude CAN verify it, Claude MUST verify it
+3. Only checkpoint for things requiring human senses or credentials
+4. Group manual actions to minimize checkpoint count
+5. Never ask the user to do something automatable
+
+### Automatable Quick Reference
+
+| Action | Automatable? | Notes |
+|--------|-------------|-------|
+| Run tests | YES | `npm test`, `pytest`, etc. |
+| Start dev server | YES | `npm run dev` (check port) |
+| Check environment variables | YES | `env \| grep KEY` |
+| Build project | YES | `npm run build` |
+| Run linting | YES | `npm run lint` |
+| Database migrations | YES | CLI commands |
+| Click email verification link | NO | Requires browser + inbox |
+| 3DS payment verification | NO | Requires card + phone |
+| OAuth consent screen | NO | Requires browser interaction |
+| Hardware token/YubiKey | NO | Physical device |
+
+### Anti-Patterns
+- Asking user to "start the dev server" — just run it
+- Asking user to "check if tests pass" — run `npm test`
+- Saying "please verify the output" without running verification commands first
+- Creating a checkpoint for `mkdir` or `npm install`

package/plugins/copilot-pbr/references/context-quality-tiers.md

@@ -0,0 +1,45 @@
+# Context Quality Tiers
+
+Behavioral guidance for agents based on context window utilization.
+
+## Tier Definitions
+
+| Tier | Context Used | Quality | Guidance |
+|------|-------------|---------|----------|
+| PEAK | 0-30% | Full capacity | Explore freely, read broadly, take time to understand |
+| GOOD | 30-50% | High capacity | Be selective with reads, skip non-essential exploration |
+| DEGRADING | 50-70% | Declining capacity | Write incrementally, finish current task, skip nice-to-haves |
+| POOR | 70%+ | Critical | Finish current task IMMEDIATELY and return. No new reads. |
+
+## Behavioral Rules Per Tier
+
+### PEAK (0-30%)
+- Read all relevant files before making changes
+- Explore adjacent code for patterns and conventions
+- Write comprehensive commit messages
+- Full self-check protocols
+
+### GOOD (30-50%)
+- Read only files directly relevant to current task
+- Skip exploratory reads of "nice to have" context
+- Standard commit messages
+- Standard self-check
+
+### DEGRADING (50-70%)
+- Write changes incrementally (don't accumulate large diffs)
+- Skip optional verification steps
+- Brief commit messages
+- Abbreviated self-check (key_files only)
+
+### POOR (70%+)
+- STOP exploring. Finish the current task only.
+- Write SUMMARY.md immediately if executor
+- Return completion marker immediately
+- Do NOT start new tasks or reads
+
+## Agent-Specific Overrides
+
+- **Researcher**: At DEGRADING, write findings immediately rather than accumulating
+- **Executor**: At DEGRADING, complete current task then return CHECKPOINT
+- **Verifier**: At DEGRADING, check existence only (skip substantiveness/wiring layers)
+- **Planner**: At GOOD, reduce task detail level; at DEGRADING, finish current plan file only

package/plugins/copilot-pbr/references/pbr-tools-cli.md

@@ -283,3 +283,118 @@ node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js event error hook-failure '{"scri
 **Output:** `{ "logged": true, "category": "build", "event": "plan-complete" }`
 
 If the JSON-details argument is not valid JSON, it's stored as `{ "raw": "<the string>" }`.
+
+---
+
+## Compound Init Commands
+
+Compound commands that compose multiple data sources into a single JSON response.
+Replace multi-step context loading in skills with a single CLI call.
+
+### `init execute-phase <phase>`
+
+Everything an executor needs to start building a phase.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init execute-phase 3
+```
+
+**Output:**
+```json
+{
+  "executor_model": "sonnet",
+  "verifier_model": "sonnet",
+  "config": { "depth": "standard", "mode": "interactive", "parallelization": {}, "planning": {}, "gates": {}, "features": {} },
+  "phase": { "num": "3", "dir": "03-auth", "name": "auth", "goal": "...", "has_context": false, "status": "planned", "plan_count": 2, "completed": 0 },
+  "plans": [{ "file": "PLAN-01.md", "plan_id": "01", "wave": 1, "autonomous": true, "has_summary": false, "must_haves_count": 4, "depends_on": [] }],
+  "waves": { "wave_1": ["01", "02"] },
+  "branch_name": "main",
+  "git_clean": true
+}
+```
+
+### `init plan-phase <phase>`
+
+Everything a planner needs to start phase planning.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init plan-phase 3
+```
+
+**Output:** `researcher_model`, `planner_model`, `checker_model`, `config` (depth profile, features, planning settings), `phase` (num, dir, goal, depends_on), `existing_artifacts`, `workflow` flags.
+
+### `init quick <description>`
+
+Everything the quick skill needs: next task number, slug, directory path.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init quick "add search feature"
+```
+
+**Output:** `next_task_number`, `slug`, `dir`, `dir_name`, `timestamp`, `config` subset.
+
+### `init verify-work <phase>`
+
+Everything a verifier needs to start verification.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init verify-work 3
+```
+
+**Output:** `verifier_model`, `phase` info, `has_verification`, `prior_attempts`, `prior_status`, `summaries`.
+
+### `init resume`
+
+Detect interrupted state and suggest continuation.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init resume
+```
+
+**Output:** `state`, `auto_next`, `continue_here`, `active_skill`, `current_phase`, `progress`.
+
+### `init progress`
+
+All phases with status and completion data.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init progress
+```
+
+**Output:** `current_phase`, `total_phases`, `status`, `phases` array, `total_plans`, `completed_plans`, `percentage`.
+
+---
+
+## State Mutation Extensions
+
+### `state patch <JSON>`
+
+Multi-field atomic STATE.md update. Updates all fields in a single pass.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state patch '{"status":"executing","last_activity":"now"}'
+```
+
+**Valid fields:** `current_phase`, `status`, `plans_complete`, `last_activity`, `progress_percent`, `phase_slug`, `total_phases`, `last_command`, `blockers`
+
+**Output:** `{ "success": true, "updated": ["status", "last_activity"] }`
+
+### `state advance-plan`
+
+Increment current plan number in STATE.md and update progress percentage.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state advance-plan
+```
+
+**Output:** `{ "success": true, "previous_plan": 1, "current_plan": 2, "total_plans": 5, "progress_percent": 40 }`
+
+### `state record-metric [--duration Nm] [--plans-completed N]`
+
+Record session/execution metrics. Appends to HISTORY.md and updates last_activity.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state record-metric --duration 15m --plans-completed 3
+```
+
+**Output:** `{ "success": true, "duration_minutes": 15, "plans_completed": 3 }`

package/plugins/copilot-pbr/references/questioning.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/questioning.md -->
 # Deep Questioning Guide
 
 Techniques for understanding a user's project vision during `/pbr:begin`. The goal is to build a complete mental model of what needs to be built, not just a feature list.
@@ -213,3 +212,24 @@ See **[skills/shared/domain-probes.md](../shared/domain-probes.md)** for technol
 9. **DO NOT** lead the user toward a particular solution
 10. **DO NOT** forget to summarize and confirm understanding
 11. **DO NOT** ask what you already know — track what the user has stated and never re-ask it. If they said "I'm using React", do not later ask "Are you using a frontend framework?" If they said "PostgreSQL", do not ask "What database are you using?" Redundant questions waste exchanges and erode trust. Instead, build on what you know: "You mentioned React — are you using Next.js or plain CRA?"
+
+---
+
+## Dream Extraction Philosophy
+
+The goal of questioning is not to gather requirements — it's to extract the user's dream and make it buildable.
+
+### 4-Item Context Checklist
+Before planning can begin, you must know:
+1. **What** are we building? (concrete deliverable, not abstract concept)
+2. **Why** does it exist? (the problem it solves, not the tech it uses)
+3. **Who** is it for? (specific users, not "everyone")
+4. **What does done look like?** (observable outcomes, not technical milestones)
+
+### Conversation Rules
+- **Start open**: "Tell me about what you want to build"
+- **Follow energy**: When they light up about something, dig deeper there
+- **Challenge vagueness**: "You said 'user-friendly' — what does that mean specifically?"
+- **Know when to stop**: When you have the 4 items above, move to planning
+- **NEVER ask about technical experience**: It's irrelevant and condescending
+- **NEVER present a menu of options**: Open questions reveal more than multiple choice