@sienklogic/plan-build-run 2.20.0 → 2.21.1

package/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to Plan-Build-Run will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.21.1](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.21.0...plan-build-run-v2.21.1) (2026-02-23)
+
+
+### Bug Fixes
+
+* **23-01:** register /pbr:do command and fix critical audit findings ([274f324](https://github.com/SienkLogic/plan-build-run/commit/274f3247ea32557954c45eb321f5551bc3d8b3de))
+* **23-02:** replace CLAUDE_PLUGIN_ROOT with PLUGIN_ROOT in cursor-pbr ([7fa53be](https://github.com/SienkLogic/plan-build-run/commit/7fa53beafaba95ab4c36499e7fb333ec83c58ecc))
+* **23-03:** replace CLAUDE_PLUGIN_ROOT with PLUGIN_ROOT in copilot-pbr ([071f739](https://github.com/SienkLogic/plan-build-run/commit/071f739eab3854e03a68f6b93ad7de40854c8b72))
+* **23-04:** replace subagents terminology with agents in cursor-pbr ([444765f](https://github.com/SienkLogic/plan-build-run/commit/444765f3277d077fba200c6d5f5fde594abdaf9a))
+* **23-05:** fix subagents terminology in copilot-pbr and sync ROADMAP template ([e019e83](https://github.com/SienkLogic/plan-build-run/commit/e019e832b4c2808cec951eda44f0f57cb8755b8c))
+* **23-07:** strip hookSpecificOutput wrapper from check-phase-boundary and pre-write-dispatch ([61e4e1e](https://github.com/SienkLogic/plan-build-run/commit/61e4e1ec7a7db3bc8ac4184e58c94ab5c324eb38))
+* **23-09:** reorder copilot-pbr hooks.json postToolUseFailure before preToolUse to match pbr canonical ordering ([1180c9d](https://github.com/SienkLogic/plan-build-run/commit/1180c9d4ffb2c1bbbe4bc201a5dab126aee43ded))
+* **23-09:** use decision:block in validate-skill-args.js, remove orphaned JSDoc in validate-task.js ([ec8c1d2](https://github.com/SienkLogic/plan-build-run/commit/ec8c1d24f9436c1dee703ec3509eb065fb2c4c92))
+* **23-10:** correct dispatch table — move check-doc-sprawl and check-skill-workflow to pre-write-dispatch ([c6acc27](https://github.com/SienkLogic/plan-build-run/commit/c6acc2791ba652d5f81da231d301afcc90ab5c57))
+* **23-10:** remove dead body from checkStatuslineRules in check-skill-workflow.js ([5a518ec](https://github.com/SienkLogic/plan-build-run/commit/5a518ec4772de1cf2991201e2657f5737efe2ebd))
+* **23-10:** remove redundant allowed-tools Note from health SKILL.md Auto-Fix section ([7dcd549](https://github.com/SienkLogic/plan-build-run/commit/7dcd549bbd0e11b6eb4177e5ed1d4fd5eddc7d9b))
+* **23-12:** fix remaining subagents terminology in scan SKILL.md derivatives ([67b15e8](https://github.com/SienkLogic/plan-build-run/commit/67b15e881d752ad1eb66bfb31496f634cb3c1768))
+* **23-12:** fix test property paths and heredoc extraction to achieve 70% branch coverage ([4b857fe](https://github.com/SienkLogic/plan-build-run/commit/4b857fe73b8d82e6efe05114a7b09737c65dee12))
+* **23-12:** remove excess tool grants from synthesizer and plan-checker agents ([04432b3](https://github.com/SienkLogic/plan-build-run/commit/04432b35dde761e95d14ca98353091bc936512a6))
+* **quick-001:** fix agent prompt issues from audit (items 4-7) ([2772154](https://github.com/SienkLogic/plan-build-run/commit/27721547694686e2f425e95a7257b9cc48316c86))
+* **quick-001:** fix agent prompt issues from audit (items 8-10) ([1c41a8f](https://github.com/SienkLogic/plan-build-run/commit/1c41a8f29a5069f4bb7cec612875b59dc6a22b22))
+* **quick-001:** fix STATE.md body drift, stale status line, and ROADMAP sync gaps ([896494d](https://github.com/SienkLogic/plan-build-run/commit/896494d1215a7aadb7aa5b28c050db282cdcd784))
+* **tools:** fix CI lint errors and macOS symlink test failure ([e5294a0](https://github.com/SienkLogic/plan-build-run/commit/e5294a0e0eefde674203ef0ed587d5def5c0f865))
+
+## [2.21.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.20.0...plan-build-run-v2.21.0) (2026-02-23)
+
+
+### Features
+
+* **tools:** add help docs, concurrent tests, and discuss requirements surfacing ([02e9cc9](https://github.com/SienkLogic/plan-build-run/commit/02e9cc997d5b7d1aed3fc43cd8f8160c6e08d78b))
+* **tools:** add milestone preview subcommand across all plugins ([fa6dca7](https://github.com/SienkLogic/plan-build-run/commit/fa6dca75d78adc952a5ffffd92baf17d8dd23e8e))
+* **tools:** resolve exploration backlog — fix script bugs, add copilot hooks, improve recovery ([8a956dd](https://github.com/SienkLogic/plan-build-run/commit/8a956dd33a7182c402307d5569e0d8d37dbdaf1c))
+
+
+### Bug Fixes
+
+* **tools:** handle concurrent write corruption in flaky test across platforms ([e4e9b4d](https://github.com/SienkLogic/plan-build-run/commit/e4e9b4d524e5c08665b72a3c99555452f8e09089))
+* **tools:** handle empty string race in concurrent .active-skill test on Windows ([9cb294a](https://github.com/SienkLogic/plan-build-run/commit/9cb294a1c7db67c1fe80d9672d4580c8951011c4))
+
 ## [2.20.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.19.0...plan-build-run-v2.20.0) (2026-02-23)
 
 

package/CLAUDE.md

@@ -59,13 +59,13 @@ Markdown files with YAML frontmatter defining specialized subagent prompts. Agen
 |------------|-------------|-------------|
 | SessionStart | progress-tracker.js | — (injects project state) |
 | PostToolUse (Write\|Edit) | post-write-dispatch.js | check-plan-format.js, check-roadmap-sync.js, check-state-sync.js |
-| PostToolUse (Write\|Edit) | post-write-quality.js | check-doc-sprawl.js, check-skill-workflow.js |
+| PostToolUse (Write\|Edit) | post-write-quality.js | — (autoFormat, typeCheck, detectConsoleLogs) |
 | PostToolUse (Task) | check-subagent-output.js | — (validates agent output) |
 | PostToolUse (Write\|Edit) | suggest-compact.js | — (context budget warnings) |
 | PostToolUse (Read) | track-context-budget.js | — (tracks reads for budget) |
 | PostToolUseFailure | log-tool-failure.js | — (logs failures) |
 | PreToolUse (Bash) | pre-bash-dispatch.js | validate-commit.js, check-dangerous-commands.js, check-phase-boundary.js |
-| PreToolUse (Write\|Edit) | pre-write-dispatch.js | — (write guards) |
+| PreToolUse (Write\|Edit) | pre-write-dispatch.js | check-skill-workflow.js, check-summary-gate.js, check-phase-boundary.js, check-doc-sprawl.js |
 | PreCompact | context-budget-check.js | — (preserves STATE.md) |
 | Stop | auto-continue.js | — (chains next command) |
 | SubagentStart/Stop | log-subagent.js | — (tracks lifecycle) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.20.0",
+  "version": "2.21.1",
   "description": "Plan it, Build it, Run it — structured development workflow for Claude Code",
   "keywords": [
     "claude-code",

package/plugins/copilot-pbr/agents/codebase-mapper.agent.md

@@ -22,7 +22,7 @@ You are **codebase-mapper**, the codebase analysis agent for the Plan-Build-Run
 
 ### Forbidden Files
 
-When exploring, NEVER commit or recommend committing:
+When exploring, NEVER write to or include in your output:
 - `.env` files (except `.env.example` or `.env.template`)
 - `*.key`, `*.pem`, `*.pfx`, `*.p12` — private keys and certificates
 - Files containing `credential` or `secret` in their name

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

@@ -8,6 +8,8 @@ target: "github-copilot"
 
 # Plan-Build-Run Debugger
 
+> **Memory note:** Project memory is enabled to provide debugging continuity across investigation sessions.
+
 You are **debugger**, the systematic debugging agent. Investigate bugs using the scientific method: hypothesize, test, collect evidence, narrow the search space.
 
 ## Output Budget

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

@@ -8,6 +8,8 @@ target: "github-copilot"
 
 # Plan-Build-Run Executor
 
+> **Memory note:** Project memory is enabled to provide build history context for deviation awareness.
+
 You are **executor**, the code execution agent for Plan-Build-Run. You receive verified plans and execute them task-by-task, producing working code with atomic commits, deviation handling, and self-verification.
 
 **You are a builder, not a designer.** Plans tell you WHAT to build. You figure out HOW at the code level. You do NOT redesign, skip, reorder, or add scope.
@@ -175,7 +177,7 @@ must_haves:
 ### Completeness Checklist
 
 Before deleting `.PROGRESS-{plan_id}`, verify SUMMARY.md has:
-- [ ] YAML frontmatter with `plan_id`, `status`, `tasks_completed`, `tasks_total`
+- [ ] YAML frontmatter with `plan`, `status`, `tasks_completed`, `tasks_total`
 - [ ] Deviations section (use "None" if empty)
 - [ ] Files Changed listing at least one file
 - [ ] At least one commit hash reference

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

@@ -12,7 +12,8 @@ You are **general**, a lightweight utility agent for the Plan-Build-Run developm
 
 ## When You're Used
 
-- `/pbr:quick` ad-hoc task delegation
+This agent is available for ad-hoc `Task()` calls from skills or custom orchestration. It is not currently spawned by any built-in PBR skill automatically — it must be invoked explicitly.
+
 - Simple file generation or formatting tasks
 - Tasks that need Plan-Build-Run context but not specialized methodology
 - Fallback when a specialized agent would be overkill

package/plugins/copilot-pbr/agents/integration-checker.agent.md

@@ -36,6 +36,8 @@ You MUST perform all applicable categories (skip only if zero items exist for th
 4. **E2E Flow Completeness** — Critical user workflows must trace from UI through API to data layer and back without breaks.
 5. **Cross-Phase Dependency Satisfaction** — Phase N's declared dependencies on Phase M must be actually satisfied in code.
 
+> **First-phase edge case**: If no completed phases exist yet, focus on verifying the current phase's internal consistency — exports match imports within the phase, API contracts are self-consistent. Cross-phase checks are not applicable and should be skipped.
+
 ### Agent Contract Compliance
 
 Read `references/agent-contracts.md` to validate agent-to-agent handoffs. Verify that each agent's actual output matches its declared contract schema — especially `provides`/`consumes` fields in SUMMARY.md and status enums in VERIFICATION.md.

package/plugins/copilot-pbr/agents/plan-checker.agent.md

@@ -140,7 +140,7 @@ Code-producing tasks should include test expectations. Check that tasks creating
 
 ## Verification Process
 
-1. **Load Plans** — Read all plan files. Parse YAML frontmatter and XML tasks. Use `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js frontmatter {path}` and `plan-index {phase}` for frontmatter; read body for XML.
+1. **Load Plans** — Read all plan files. Parse YAML frontmatter and XML tasks. Use `node ${PLUGIN_ROOT}/scripts/pbr-tools.js frontmatter {path}` and `plan-index {phase}` for frontmatter; read body for XML.
 2. **Load Context** — If CONTEXT.md provided, extract locked decisions, deferred ideas, user constraints.
 3. **Load Phase Goal** — From input instruction, phase directory, or plan frontmatter must_haves.
 4. **Run All 10 Dimensions** — Evaluate each plan against all dimensions. Collect issues.

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

@@ -8,6 +8,8 @@ target: "github-copilot"
 
 # Plan-Build-Run Planner
 
+> **Memory note:** Project memory is enabled to provide planning continuity and awareness of prior phase decisions.
+
 You are **planner**, the planning agent for the Plan-Build-Run development system. You transform research, phase goals, and user requirements into executable plans that the executor agent can follow mechanically.
 
 ## Core Principle: Context Fidelity
@@ -30,7 +32,7 @@ Invoked with a VERIFICATION.md containing gaps. Read the report, identify gaps,
 Invoked with plan-checker feedback containing issues. Revise flagged plan(s) to address all blockers and warnings. See Revision Mode below.
 
 ### Mode 4: Roadmap Mode
-Invoked with a request to create/update the project roadmap. Produce `.planning/ROADMAP.md` using the template at `${CLAUDE_PLUGIN_ROOT}/templates/ROADMAP.md.tmpl`.
+Invoked with a request to create/update the project roadmap. Produce `.planning/ROADMAP.md` using the template at `${PLUGIN_ROOT}/templates/ROADMAP.md.tmpl`.
 
 #### Fallback Format: ROADMAP.md (if template unreadable)
 

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

@@ -52,6 +52,8 @@ All claims must be attributed to a source level. Higher levels override lower le
 
 **Attribution rules**: Every factual claim needs a source tag (`[S1]`, `[S2]`, etc.). Version-sensitive information (API signatures, config syntax) MUST come from S1-S3. When citing S2, note the version: `[S2-v14.2]`. Contradictions resolve in favor of higher source level.
 
+**Offline Fallback**: If web tools are unavailable (air-gapped environment, MCP not configured), rely on local sources: codebase analysis via Glob/Grep, existing documentation, and README files. Assign these S3-S4 confidence levels. Do not attempt WebFetch or WebSearch — note in the output header that external sources were unavailable.
+
 ---
 
 ## Confidence Levels
@@ -101,15 +103,15 @@ Before writing output, verify: every claim has source attribution, every recomme
 ## Output Formats
 
 ### Project Research
-Read `${CLAUDE_PLUGIN_ROOT}/templates/research-outputs/project-research.md.tmpl` for format.
+Read `${PLUGIN_ROOT}/templates/research-outputs/project-research.md.tmpl` for format.
 Key sections: User Constraints, Executive Summary, Standard Stack, Architecture Patterns, Common Pitfalls, Code Examples, Integration Points, Coverage Assessment, Open Questions, Sources.
 
 ### Phase Research
-Read `${CLAUDE_PLUGIN_ROOT}/templates/research-outputs/phase-research.md.tmpl` for format.
+Read `${PLUGIN_ROOT}/templates/research-outputs/phase-research.md.tmpl` for format.
 Key sections: User Constraints, Phase Goal, Implementation Approach, Dependencies, Pitfalls, Testing Strategy, Coverage Assessment, Sources.
 
 ### Synthesis
-Read `${CLAUDE_PLUGIN_ROOT}/templates/research-outputs/synthesis.md.tmpl` for format.
+Read `${PLUGIN_ROOT}/templates/research-outputs/synthesis.md.tmpl` for format.
 Key sections: Executive Summary, Key Findings, Contradictions Resolved, Recommended Approach, Risks and Mitigations, Sources.
 
 ### Fallback Format (if templates unreadable)

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

@@ -54,7 +54,7 @@ Output to `.planning/research/SUMMARY.md` (or specified path).
 
 ## Output Format
 
-Read `${CLAUDE_PLUGIN_ROOT}/templates/RESEARCH-SUMMARY.md.tmpl` for the complete output format.
+Read `${PLUGIN_ROOT}/templates/RESEARCH-SUMMARY.md.tmpl` for the complete output format.
 
 Key sections: Executive Summary (3-5 sentences), Recommended Stack (table), Architecture Recommendations, Key Patterns, Pitfalls & Warnings, Contradictions Resolved, Open Questions, Sources.
 

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

@@ -48,8 +48,8 @@ Look for an existing `VERIFICATION.md` in the phase directory.
 
 Use `pbr-tools.js` CLI to efficiently load phase data (saves ~500-800 tokens vs. manual parsing):
 ```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js must-haves {phase_number}
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js phase-info {phase_number}
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js must-haves {phase_number}
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js phase-info {phase_number}
 ```
 
 Stop and report error if pbr-tools CLI is unavailable. Also read CONTEXT.md for locked decisions and deferred ideas, and ROADMAP.md for the phase goal and dependencies.
@@ -216,7 +216,7 @@ Read `references/stub-patterns.md` for stub detection patterns by technology. Re
 
 ### Verifier-Specific Anti-Patterns
 1. DO NOT trust SUMMARY.md claims without verifying the actual codebase
-2. DO NOT attempt to fix issues — you have no Write/Edit tools and that is intentional
+2. DO NOT attempt to fix issues — you have no Edit tool and that is intentional; Write access is only for VERIFICATION.md output
 3. DO NOT mark stubs as SUBSTANTIVE — if it has a TODO, it's a stub
 4. DO NOT mark orphaned code as WIRED — if nothing imports it, it's orphaned
 5. DO NOT skip Level 2 or Level 3 checks — existence alone is insufficient

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

@@ -77,6 +77,19 @@
         ]
       }
     ],
+    "postToolUseFailure": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "bash": "node \"$(cd \"$(dirname \"$0\")\" && pwd)/../../pbr/scripts/run-hook.js\" log-tool-failure.js",
+            "powershell": "node (Join-Path (Split-Path -Parent $PSScriptRoot) 'pbr\\scripts\\run-hook.js') log-tool-failure.js",
+            "cwd": ".",
+            "timeoutSec": 15
+          }
+        ]
+      }
+    ],
     "preToolUse": [
       {
         "matcher": "Bash",
@@ -139,6 +152,82 @@
         ]
       }
     ],
+    "preCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "bash": "node \"$(cd \"$(dirname \"$0\")\" && pwd)/../../pbr/scripts/run-hook.js\" context-budget-check.js",
+            "powershell": "node (Join-Path (Split-Path -Parent $PSScriptRoot) 'pbr\\scripts\\run-hook.js') context-budget-check.js",
+            "cwd": ".",
+            "timeoutSec": 15
+          }
+        ]
+      }
+    ],
+    "stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "bash": "node \"$(cd \"$(dirname \"$0\")\" && pwd)/../../pbr/scripts/run-hook.js\" auto-continue.js",
+            "powershell": "node (Join-Path (Split-Path -Parent $PSScriptRoot) 'pbr\\scripts\\run-hook.js') auto-continue.js",
+            "cwd": ".",
+            "timeoutSec": 15
+          }
+        ]
+      }
+    ],
+    "subagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "bash": "node \"$(cd \"$(dirname \"$0\")\" && pwd)/../../pbr/scripts/run-hook.js\" log-subagent.js start",
+            "powershell": "node (Join-Path (Split-Path -Parent $PSScriptRoot) 'pbr\\scripts\\run-hook.js') log-subagent.js start",
+            "cwd": ".",
+            "timeoutSec": 15
+          }
+        ]
+      }
+    ],
+    "subagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "bash": "node \"$(cd \"$(dirname \"$0\")\" && pwd)/../../pbr/scripts/run-hook.js\" log-subagent.js stop",
+            "powershell": "node (Join-Path (Split-Path -Parent $PSScriptRoot) 'pbr\\scripts\\run-hook.js') log-subagent.js stop",
+            "cwd": ".",
+            "timeoutSec": 15
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "bash": "node \"$(cd \"$(dirname \"$0\")\" && pwd)/../../pbr/scripts/run-hook.js\" event-handler.js",
+            "powershell": "node (Join-Path (Split-Path -Parent $PSScriptRoot) 'pbr\\scripts\\run-hook.js') event-handler.js",
+            "cwd": ".",
+            "timeoutSec": 15
+          }
+        ]
+      }
+    ],
+    "taskCompleted": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "bash": "node \"$(cd \"$(dirname \"$0\")\" && pwd)/../../pbr/scripts/run-hook.js\" task-completed.js",
+            "powershell": "node (Join-Path (Split-Path -Parent $PSScriptRoot) 'pbr\\scripts\\run-hook.js') task-completed.js",
+            "cwd": ".",
+            "timeoutSec": 15
+          }
+        ]
+      }
+    ],
     "configChange": [
       {
         "hooks": [

package/plugins/copilot-pbr/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.20.0",
+  "version": "2.21.1",
   "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/skills/audit/SKILL.md

@@ -85,7 +85,7 @@ find ~/.claude/projects/{encoded-path}/ -name "*.jsonl" -maxdepth 1 \
 
 For each session file found, also check for subagent logs:
 ```bash
-ls ~/.claude/projects/{encoded-path}/{session-id}/subagents/*.jsonl 2>/dev/null
+ls ~/.claude/projects/{encoded-path}/{session-id}/agents/*.jsonl 2>/dev/null
 ```
 
 Display discovery results:

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

@@ -718,11 +718,10 @@ These return `{ success, old_status, new_status }` or `{ success, old_plans, new
 
 **CRITICAL: Update STATE.md NOW with phase completion status. Do NOT skip this step.**
 
-**8b. Update STATE.md:**
-- Phase status: {final_status from Step 8-pre}
-- Plan completion count
-- Last activity timestamp
-- Progress bar
+**8b. Update STATE.md (CRITICAL — 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
 
 **8c. Commit planning docs (if configured):**
 Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.

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

@@ -133,7 +133,7 @@ After setting depth, the profile is automatically resolved. Show the user the ef
   "Depth set to {value}. Effective profile:"
   Then display the profile summary (research, plan-check, verify, scan mappers, debug rounds, inline verify).
 
-To resolve the profile, run: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth`
+To resolve the profile, run: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth`
 
 If the user wants to override a specific profile setting, they can set `depth_profiles.{depth}.{key}` directly.
 For example: to use quick mode but keep plan-checking, the user would set depth to quick and then override:

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

@@ -54,7 +54,7 @@ This handles the case where neither `.planning/` nor `.planning/debug/` exist ye
 
 ### Step 2: Check for Active Debug Sessions
 
-**Load depth profile:** Run `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth` to get `debug.max_hypothesis_rounds`. If the command fails (no config.json or CLI error), default to 5 rounds. Initialize a round counter at 0. This counter increments each time a continuation debugger is spawned.
+**Load depth profile:** Run `node ${PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth` to get `debug.max_hypothesis_rounds`. If the command fails (no config.json or CLI error), default to 5 rounds. Initialize a round counter at 0. This counter increments each time a continuation debugger is spawned.
 
 Scan `.planning/debug/` for existing debug files:
 

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

@@ -78,7 +78,7 @@ Read the following files to understand what this phase needs to accomplish:
    - What patterns have been established (`patterns` field)
    - What decisions were already made (`key_decisions` field)
 
-3. **REQUIREMENTS.md** (if exists) — Read project requirements relevant to this phase
+3. **REQUIREMENTS.md** (if exists) — Read project requirements relevant to this phase. **CRITICAL**: After reading, display to the user which specific requirements map to this phase. Flag any requirements that could constrain decisions. If the user's discussion decisions later contradict a stated requirement, surface the contradiction immediately — don't wait until planning.
 
 4. **CONTEXT.md** (if exists in the phase directory) — Check if a prior discussion already happened
    - If CONTEXT.md exists, inform the user and use the **context-handling** pattern from `skills/shared/gate-prompts.md`:

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

@@ -91,6 +91,7 @@ Display the following reference to the user:
 |---------|-------------|
 | `/pbr:milestone new` | Start a new milestone cycle. |
 | `/pbr:milestone complete` | Archive completed milestone. |
+| `/pbr:milestone preview` | Dry-run of complete — show what would happen. |
 | `/pbr:milestone audit` | Verify milestone completion. |
 | `/pbr:milestone gaps` | Create phases to close audit gaps. |
 | `/pbr:todo add\|list\|done` | Persistent file-based todos. |
@@ -135,6 +136,7 @@ Display the following reference to the user:
 - **Depth**: `quick` (skip research, ~50% cheaper) | `standard` | `comprehensive` (~2x cost)
 - **State files**: `.planning/STATE.md` (position), `.planning/ROADMAP.md` (phases), `.planning/config.json` (settings)
 - **Configure**: `/pbr:config` to change depth, models, gates, parallelization
+- **List agents**: Run `claude agents` in your terminal to see all registered PBR agents and verify loading
 - **Tip**: Use `/pbr:quick` for creative/visual work where structured planning adds overhead without benefit.
 - **PR hygiene**: When creating PRs from a Plan-Build-Run project, `.planning/` commits can be filtered using phase branching (`git.branching: phase`) which squash-merges code-only changes to main.
 - **Seeds**: `/pbr:explore` can create seed files (`.planning/seeds/`) with trigger conditions. Seeds auto-inject into planning when their trigger phase is reached.
@@ -149,6 +151,27 @@ Plan-Build-Run includes three behavioral contexts in `contexts/` that adjust how
 
 Skills automatically activate the appropriate context: `/pbr:build` uses dev context, `/pbr:discuss` uses research context, `/pbr:review` uses review context.
 
+## When to Use Quick vs Plan+Build
+
+| Use `/pbr:quick` when... | Use `/pbr:plan` + `/pbr:build` when... |
+|--------------------------|----------------------------------------|
+| Change touches ≤3 files | Change touches 4+ files |
+| ≤100 lines of code | 100+ lines of code |
+| Single subsystem | Multiple subsystems or cross-cutting |
+| No architectural decisions | Requires design choices |
+| Bug fix, small feature, docs | New feature, refactor, migration |
+
+## Setup vs Begin
+
+- **`/pbr:begin`** — Use this to start a new project. It handles everything: questioning, research, requirements, roadmap, AND config initialization. This is the standard entry point.
+- **`/pbr:setup`** — Use this only to reconfigure an existing project's settings (model profiles, gates, depth, parallelization) without re-running the full begin flow.
+
+If you're unsure, start with `/pbr:begin`. It will detect existing config and offer to reuse or overwrite.
+
+## Team Discussions
+
+The `features.team_discussions` config flag (and `/pbr:build --team`) enables **Agent Teams** for complex builds. When enabled, executor agents can coordinate with each other during parallel wave execution — sharing context about what they've built, resolving interface conflicts, and avoiding duplicate work. Best for phases where multiple plans have shared dependencies. Configure via `/pbr:config`.
+
 ## Getting Started
 
 ```

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

@@ -359,7 +359,7 @@ If the import process surfaced new locked decisions (from blocker resolutions in
 **8e. Emit workflow event (conditional):**
 If the event-logger script is available:
 ```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js event workflow plan-import --phase {N} --plans {count} --source {filepath_or_user_input}
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js event workflow plan-import --phase {N} --plans {count} --source {filepath_or_user_input}
 ```
 Falls back silently if the command is not available.
 

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

@@ -52,6 +52,7 @@ Examples:
   "new User Auth"    → subcommand=new, arg="User Auth"
   "complete v1.0"    → subcommand=complete, arg="v1.0"
   "complete 1.0"     → subcommand=complete, arg="v1.0" (auto-prefix v)
+  "preview v1.0"     → subcommand=preview, arg="v1.0"
   "audit v1.0"       → subcommand=audit, arg="v1.0"
   "audit"            → subcommand=audit, arg=current milestone
   "gaps"             → subcommand=gaps, arg=most recent audit
@@ -64,6 +65,7 @@ Usage: /pbr:milestone <subcommand> [version]
 Subcommands:
   new [name]       — Start a new milestone cycle
   complete [ver]   — Archive completed milestone
+  preview [ver]    — Dry-run of complete (show what would happen)
   audit [ver]      — Verify milestone completion
   gaps             — Create phases to close audit gaps
 ```
@@ -189,6 +191,65 @@ Start a new milestone cycle with new phases.
 
 ---
 
+## Subcommand: `preview`
+
+Dry-run of milestone completion — shows what would happen without making any changes.
+
+### Flow
+
+1. **Determine version:**
+   - Same logic as `complete`: use `$ARGUMENTS` or ask via AskUserQuestion
+
+2. **Identify milestone phases:**
+   - Read ROADMAP.md to find phases belonging to this milestone
+   - List each phase with its current status (from STATE.md or VERIFICATION.md)
+
+3. **Verification status check:**
+   - For each milestone phase, check if VERIFICATION.md exists and its `result` frontmatter
+   - Flag phases that are unverified or have stale verification (SUMMARY.md newer than VERIFICATION.md)
+
+4. **Preview archive structure:**
+   - Show what the archive directory would look like:
+     ```
+     .planning/milestones/v{version}/
+     ├── ROADMAP.md (snapshot)
+     ├── STATS.md (would be generated)
+     ├── REQUIREMENTS.md (snapshot)
+     └── phases/
+         ├── {NN}-{slug}/ (moved from .planning/phases/)
+         │   ├── PLAN-01.md
+         │   ├── SUMMARY.md
+         │   └── VERIFICATION.md
+         └── ...
+     ```
+
+5. **Show what would change:**
+   - Which phase directories would be moved
+   - What ROADMAP.md section would be collapsed
+   - What STATE.md updates would occur
+   - What git tag would be created
+
+6. **Display summary:**
+   ```
+   ╔══════════════════════════════════════════════════════════════╗
+   ║  MILESTONE PREVIEW — v{version}                              ║
+   ╚══════════════════════════════════════════════════════════════╝
+
+   Phases to archive: {count}
+   ✓ Verified: {verified_count}
+   ⚠ Unverified: {unverified_count}
+   ⚠ Stale verification: {stale_count}
+
+   Archive location: .planning/milestones/v{version}/
+   Git tag: v{version}
+
+   Ready to complete? Run: /pbr:milestone complete v{version}
+   ```
+
+**CRITICAL**: This subcommand is READ-ONLY. Do not create directories, move files, modify STATE.md, modify ROADMAP.md, or create git tags. Only read and display.
+
+---
+
 ## Subcommand: `complete`
 
 Archive a completed milestone and prepare for the next one.

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

@@ -462,7 +462,7 @@ Use the approve-revise-abort pattern from `skills/shared/gate-prompts.md`:
   4. Update the `Plans Complete` column to `0/{N}` where N = number of plan files just created
   5. Update the `Status` column to `planned`
   6. Save the file — do NOT skip this step
-- Update STATE.md: set current phase plan status to "planned"
+- Update STATE.md **(CRITICAL — update BOTH frontmatter AND body)**: set `status: "planned"`, `plans_total`, `last_command` in frontmatter AND update `Status:`, `Plan:` lines in body `## Current Position`
 - **If `features.auto_advance` is `true` AND `mode` is `autonomous`:** Chain directly to build. This continues the build->review->plan->build cycle automatically.
 - **Otherwise:** Suggest next action: `/pbr:build {N}`
 

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

@@ -311,10 +311,10 @@ If all automated checks and UAT items passed:
    4. Update the `Status` column to `verified`
    5. Update the `Completed` column to the current date (YYYY-MM-DD)
    6. Save the file — do NOT skip this step
-2. Update `.planning/STATE.md`:
-   - Phase status: "verified"
-   - Progress updated
-   - Last activity timestamp
+2. Update `.planning/STATE.md` **(CRITICAL — update BOTH frontmatter AND body):**
+   - Frontmatter: `status: "verified"`, `progress_percent`, `last_activity`, `last_command`
+   - Body `## Current Position`: `Status:` line, `Last activity:` line, `Progress:` bar
+   - These MUST stay in sync — see `skills/shared/state-update.md`
    - **STATE.md size limit:** Follow size limit enforcement rules in `skills/shared/state-update.md` (150 lines max).
 3. Update VERIFICATION.md with UAT results (append UAT section)
 3. Present completion:

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

@@ -28,9 +28,9 @@ This skill **spawns 4 parallel Task(subagent_type: "pbr:codebase-mapper")** agen
 Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
 
 Additionally for this skill:
-- **Never** analyze the codebase yourself — delegate ALL analysis to the 4 parallel codebase-mapper subagents
+- **Never** analyze the codebase yourself — delegate ALL analysis to the 4 parallel codebase-mapper agents
 - **Minimize** reading mapper outputs — read only frontmatter or first 20 lines of each output document
-- **Delegate** all file reading, pattern analysis, and architecture mapping to the codebase-mapper subagents
+- **Delegate** all file reading, pattern analysis, and architecture mapping to the codebase-mapper agents
 
 ---
 
@@ -50,7 +50,7 @@ Check if `.planning/codebase/` directory exists:
 
 First, resolve the depth profile so you know which areas are available:
 ```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth
 ```
 Read `profile["scan.mapper_areas"]` to determine available areas (quick: tech, arch; standard/comprehensive: tech, arch, quality, concerns).
 
@@ -93,7 +93,7 @@ Refer to the "Reconnaissance Detection Reference" section of `skills/scan/templa
 
 **Resolve mapper configuration:** Before spawning, resolve the depth profile:
 ```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth
 ```
 
 Read `profile["scan.mapper_count"]` and `profile["scan.mapper_areas"]` to determine how many mappers to spawn and which focus areas to cover.

package/plugins/copilot-pbr/skills/shared/config-loading.md

@@ -11,7 +11,7 @@ Standard pattern for loading `.planning/config.json` fields at the start of a sk
 
 Instead of reading and parsing STATE.md, ROADMAP.md, and config.json manually, run:
 ```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js state load
 ```
 This returns a JSON object with `config`, `state`, `roadmap`, `current_phase`, and `progress`. Falls back gracefully if the script is missing -- parse files manually in that case.
 

package/plugins/copilot-pbr/skills/shared/context-budget.md

@@ -1,7 +1,7 @@
 <!-- canonical: ../../../pbr/skills/shared/context-budget.md -->
 # Context Budget Rules
 
-Standard rules for keeping orchestrator context lean. Reference this fragment in skills that spawn Task() subagents.
+Standard rules for keeping orchestrator context lean. Reference this fragment in skills that spawn Task() agents.
 
 See also: `skills/shared/universal-anti-patterns.md` for the complete set of universal rules (context budget + file reading + behavioral rules).
 
@@ -14,7 +14,7 @@ Every skill that spawns agents or reads significant content must follow these ru
 1. **Never** read agent definition files (`agents/*.md`) — `subagent_type` auto-loads them
 2. **Never** inline large files into Task() prompts — tell agents to read files from disk instead
 3. **Minimize** reading subagent output into main context — read only frontmatter, not full content
-4. **Delegate** heavy work to subagents — the orchestrator routes, it doesn't execute
+4. **Delegate** heavy work to agents — the orchestrator routes, it doesn't execute
 5. **Before spawning agents**: If you've already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider running `/pbr:pause` to checkpoint progress." Suggest pause proactively rather than waiting for compaction.
 
 ## Customization
@@ -24,7 +24,7 @@ Skills should add skill-specific rules below the reference line. Common skill-sp
 - **build**: "Minimize reading executor output — read only SUMMARY.md frontmatter, not full content"
 - **plan**: "Minimize reading subagent output — read only plan frontmatter for summaries"
 - **review**: "Minimize reading subagent output — read only VERIFICATION.md frontmatter for summaries"
-- **scan**: "Delegate ALL analysis to the 4 parallel codebase-mapper subagents"
+- **scan**: "Delegate ALL analysis to the 4 parallel codebase-mapper agents"
 - **quick**: "Never implement the task yourself — ALL code changes go through a spawned executor"
 - **debug**: "Never perform investigation work yourself — delegate ALL analysis to the debugger subagent"