@sienklogic/plan-build-run 2.21.0 → 2.21.1

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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)
 
 

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.21.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,19 +152,6 @@
         ]
       }
     ],
-    "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
-          }
-        ]
-      }
-    ],
     "preCompact": [
       {
         "hooks": [

package/plugins/copilot-pbr/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.21.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/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/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"
 

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

@@ -42,7 +42,7 @@ Reading order (always this sequence):
    - Do NOT read HISTORY.md for normal build/plan/review operations
    - Read ONLY when: debugging a regression that may trace to a prior phase,
      or when a milestone audit needs historical context
-   - Use: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history load`
+   - Use: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js history load`
    - This returns structured JSON -- do not read the raw file
 ```
 

package/plugins/copilot-pbr/skills/shared/state-update.md

@@ -5,12 +5,17 @@ Standard pattern for updating `.planning/STATE.md`. Include this fragment in ski
 
 ---
 
+**CRITICAL: STATE.md has TWO representations — YAML frontmatter AND markdown body. You MUST update BOTH when changing state. The status line reads frontmatter; humans and hooks read the body. If you only update frontmatter, the body goes stale and the status line shows wrong data. Do NOT skip body updates under any circumstances.**
+
+---
+
 ## When to Update STATE.md
 
 | Event | What to Update |
 |-------|---------------|
-| Phase status changes (planned, building, verified) | Current Position section |
-| Plan completes or fails | Plan counter, status, last activity |
+| Phase status changes (planned, building, verified) | Frontmatter fields AND Current Position section |
+| Plan completes or fails | Frontmatter fields AND Plan counter, status, last activity |
+| Phase advances to next phase | Frontmatter fields AND Phase line, Status, Last activity, Progress bar |
 | New decision made | Accumulated Context > Decisions |
 | Blocker discovered or resolved | Accumulated Context > Blockers/Concerns |
 | Session starts or ends | Session Continuity section |
@@ -32,6 +37,9 @@ See: .planning/PROJECT.md (updated {date})
 Update `Current focus` when phase changes.
 
 ### 2. Current Position (lines 9-14)
+
+**CRITICAL: This section MUST match the frontmatter fields above it. When you update `current_phase` or `status` in frontmatter, you MUST also update the corresponding lines below. A hook will auto-fix drift, but do not rely on it.**
+
 ```
 ## Current Position
 Phase: {N} of {total} ({Phase name})
@@ -113,8 +121,8 @@ When a milestone completes or a phase is verified, archive historical context to
 
 Use `pbr-tools.js history append`:
 ```
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history append phase "Phase 3 (Auth)" "Verified 2026-02-10. Key decisions: JWT + httpOnly cookies, Discord OAuth."
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history append milestone "v1.0 User Auth" "Phases 1-4. All verified. Core auth flow complete."
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js history append phase "Phase 3 (Auth)" "Verified 2026-02-10. Key decisions: JWT + httpOnly cookies, Discord OAuth."
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js history append milestone "v1.0 User Auth" "Phases 1-4. All verified. Core auth flow complete."
 ```
 
 ### After Archiving

package/plugins/copilot-pbr/skills/shared/universal-anti-patterns.md

@@ -14,7 +14,7 @@ These rules prevent context rot -- quality degradation as the context window fil
 1. **Never** read agent definition files (`agents/*.md`) -- `subagent_type` auto-loads them. Reading agent definitions into the orchestrator wastes main context for content that is automatically injected into subagent sessions.
 2. **Never** inline large files into Task() prompts -- tell agents to read files from disk instead. Agents have their own 200k token context windows.
 3. **Minimize** reading subagent output into main context -- read only frontmatter, status fields, or summaries. Never read full SUMMARY.md, VERIFICATION.md, or RESEARCH.md bodies into the orchestrator unless specifically needed for inline presentation.
-4. **Delegate** heavy work to Task() subagents -- the orchestrator routes, it does not build, analyze, research, investigate, or verify.
+4. **Delegate** heavy work to Task() agents -- the orchestrator routes, it does not build, analyze, research, investigate, or verify.
 5. **Proactive pause warning**: If you have 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.
 
 ## File Reading Rules (apply to every skill)

package/plugins/copilot-pbr/templates/ROADMAP.md.tmpl

@@ -22,6 +22,13 @@ Phase 01 ──→ Phase 02 ──→ Phase 04
                        └──→ Phase 04
 ```
 
+---
+
+## Milestone: {project name} v1.0
+
+**Goal:** {overall project goal from requirements}
+**Phases:** 1 - {n}
+
 ## Phase Details
 
 ### Phase 01: Project Setup

package/plugins/cursor-pbr/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.21.0",
+  "version": "2.21.1",
   "description": "Plan-Build-Run — Structured development workflow for Cursor. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/cursor-pbr/agents/codebase-mapper.md

@@ -21,7 +21,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/cursor-pbr/agents/debugger.md

@@ -7,6 +7,8 @@ readonly: false
 
 # 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/cursor-pbr/agents/executor.md

@@ -7,6 +7,8 @@ readonly: false
 
 # 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.
@@ -174,7 +176,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/cursor-pbr/agents/general.md

@@ -11,7 +11,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/cursor-pbr/agents/integration-checker.md

@@ -35,6 +35,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/cursor-pbr/agents/plan-checker.md

@@ -139,7 +139,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/cursor-pbr/agents/planner.md

@@ -7,6 +7,8 @@ readonly: false
 
 # 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
@@ -29,7 +31,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)