@sienklogic/plan-build-run 2.9.1 → 2.11.0

package/CHANGELOG.md

@@ -5,6 +5,50 @@ 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.11.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.10.0...plan-build-run-v2.11.0) (2026-02-21)
+
+
+### Features
+
+* **06-01:** add .active-skill write and cleanup to begin, plan, review, import skills ([e16c0cb](https://github.com/SienkLogic/plan-build-run/commit/e16c0cbe73da7abd08008c56d918106e73a3535a))
+* **06-02:** add CRITICAL markers to file-creation steps in begin, build, milestone, setup, pause ([edd9322](https://github.com/SienkLogic/plan-build-run/commit/edd932287bfeb390aa67aee0cb17b44c886339d2))
+* **07-01:** add Write tool to verifier/integration-checker and update prose across all plugins ([20bcd55](https://github.com/SienkLogic/plan-build-run/commit/20bcd550cb3c01312c805c543e01e72a7dd8dd88))
+* **07-01:** register missing skills in check-skill-workflow.js switch statement ([26c4264](https://github.com/SienkLogic/plan-build-run/commit/26c42640f199eae7de4570cb0fcb8fdab514cc64))
+* **07-02:** add debugger advisory gate and milestone gaps_found status check ([d999fe0](https://github.com/SienkLogic/plan-build-run/commit/d999fe0cf65febf877c731d983edb49e1cfa3dc7))
+* **07-02:** add mtime-based recency checks for researcher and synthesizer output ([4581529](https://github.com/SienkLogic/plan-build-run/commit/45815292c8e1604d2b5307092b2b2d6fdb3c2eec))
+* **08-01:** add inline fallback formats to 7 template-dependent agents ([e383118](https://github.com/SienkLogic/plan-build-run/commit/e3831187a35e0bf2924f0e156971b530d71dada3))
+* **08-02:** add CRITICAL markers and fix agent handoff issues ([a921c29](https://github.com/SienkLogic/plan-build-run/commit/a921c29005b232aa662ee7364f19154f103c827f))
+* **09-01:** add gate error fix guidance and discuss deep-dive CRITICAL enforcement ([6257ac5](https://github.com/SienkLogic/plan-build-run/commit/6257ac5bb69c04078fc1fd845049900274e4079c))
+* **09-01:** add health auto-fix for common corruption patterns ([6209e20](https://github.com/SienkLogic/plan-build-run/commit/6209e2012ec972ae351bd967cd1fa1087b767474))
+* **09-01:** add rollback safety, setup idempotency, and todo archive safety ([8106793](https://github.com/SienkLogic/plan-build-run/commit/8106793c6dc728a58c8be6a5f1ccaffc9cef83a6))
+* **09-02:** rewrite ui-formatting.md with unified double-line box format ([1030f30](https://github.com/SienkLogic/plan-build-run/commit/1030f3078d171f200d1d85a29481deb65f927875))
+* **09-02:** update error-reporting fragment with block reason guidance ([55780b2](https://github.com/SienkLogic/plan-build-run/commit/55780b2b54725b8d503e0b46291c80fe5a92219b))
+* **09-03:** replace heavy bar and thin divider banners with double-line box format in all 24 skills ([1754b2b](https://github.com/SienkLogic/plan-build-run/commit/1754b2bc8dbb625c48ef618036eef3bda06f6380))
+* **09-03:** sync banner replacements and 09-01/09-02 changes to cursor-pbr and copilot-pbr ([4b01088](https://github.com/SienkLogic/plan-build-run/commit/4b010881e275b10ed8ebcace60e74535e66f8d49))
+* **09-04:** replace Next Up headings with double-line box format in all PBR skills ([8f34dbc](https://github.com/SienkLogic/plan-build-run/commit/8f34dbc157a67a353e3b4c977249aac667838f32))
+* **09-04:** sync Next Up box format to cursor-pbr and copilot-pbr derivatives ([a819e95](https://github.com/SienkLogic/plan-build-run/commit/a819e952483fb348a8c64c27abe59f80590ad712))
+* **tools:** add state-sync plans_total fix, anti-pattern rule for Skill-in-Task, and social images ([afdc5f2](https://github.com/SienkLogic/plan-build-run/commit/afdc5f2d10c9cae77e2382332e9243a238c1f54e))
+
+
+### Bug Fixes
+
+* **06-03:** fix planner naming convention, executor timestamps, and statusline backup ([92c9b8d](https://github.com/SienkLogic/plan-build-run/commit/92c9b8d5fe95a2b339267206185daf38a125ad56))
+* **tools:** resolve markdownlint errors in planner agent and milestone skill ([9ef8548](https://github.com/SienkLogic/plan-build-run/commit/9ef8548642cba021d9c917e612116aebe77cf570))
+* **tools:** update AskUserQuestion audit to reflect health skill auto-fix gates ([e20bbe5](https://github.com/SienkLogic/plan-build-run/commit/e20bbe51a9f3ad2a7f2a8cd609abee52ef2ce942))
+
+
+### Documentation
+
+* **08-03:** add agent-contracts.md reference documenting handoff schemas ([89a86cf](https://github.com/SienkLogic/plan-build-run/commit/89a86cf2c21635290f6d048d1b5ef045a686730d))
+* **10-01:** wire agent-contracts.md into agents and document abandoned debug resolution ([f30762d](https://github.com/SienkLogic/plan-build-run/commit/f30762d62dbafd0f1705822a295c1eb2c6288017))
+
+## [2.10.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.9.1...plan-build-run-v2.10.0) (2026-02-20)
+
+
+### Features
+
+* **tools:** add post-compaction recovery, pbr-tools CLI reference, and dashboard UI banner ([84291f2](https://github.com/SienkLogic/plan-build-run/commit/84291f2ff0f9646eea96c02fd50073b8dd17487d))
+
 ## [2.9.1](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.9.0...plan-build-run-v2.9.1) (2026-02-20)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.9.1",
+  "version": "2.11.0",
   "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

@@ -46,6 +46,48 @@ You receive ONE focus area per invocation. All output is written to `.planning/c
 
 Read the relevant `.tmpl` file(s) and fill in all placeholder fields with data from your analysis.
 
+### Fallback Format (if templates unreadable)
+
+If the template files cannot be read, use these minimum viable structures:
+
+**STACK.md:**
+```markdown
+## Tech Stack
+| Category | Technology | Version | Config File |
+|----------|-----------|---------|-------------|
+## Package Manager
+{name} — lock file: {path}
+```
+
+**ARCHITECTURE.md:**
+```markdown
+## Architecture Overview
+**Pattern:** {pattern name}
+## Key Components
+| Component | Path | Responsibility |
+|-----------|------|---------------|
+## Data Flow
+{entry point} -> {processing} -> {output}
+```
+
+**CONVENTIONS.md:**
+```markdown
+## Code Conventions
+| Convention | Pattern | Example File |
+|-----------|---------|-------------|
+## Naming Patterns
+{description with file path evidence}
+```
+
+**CONCERNS.md:**
+```markdown
+## Concerns
+| Severity | Area | Description | File |
+|----------|------|-------------|------|
+## Security Considerations
+{findings}
+```
+
 ---
 
 ## Exploration Process

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

@@ -39,7 +39,8 @@ You are **debugger**, the systematic debugging agent. Investigate bugs using the
 ```yaml
 ---
 slug: "{slug}"
-status: "gathering"    # gathering → investigating → fixing → verifying → resolved
+status: "gathering"    # gathering → investigating → fixing → verifying → resolved (resolution: fixed | abandoned)
+# resolution: "fixed" or "abandoned" (set when status = resolved; abandoned = user ended without fix)
 created: "{ISO}"
 updated: "{ISO}"
 mode: "find_and_fix"
@@ -116,6 +117,8 @@ When you need human input, emit a checkpoint block. Always include `Debug file:`
 
 ## Fixing Protocol
 
+**CRITICAL — DO NOT SKIP steps 5-8. Uncommitted fixes and unupdated debug files cause state corruption on resume.**
+
 **Steps**: Verify root cause → plan minimal fix → predict outcome → implement → verify → check regressions → commit → update debug file.
 
 **Guidelines**: Minimal change (root cause, not symptoms). One atomic commit. No refactoring or features. Test the fix.

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

@@ -29,6 +29,7 @@ You are **executor**, the code execution agent for Plan-Build-Run. You receive v
    e. If verify fails: apply deviation rules
    f. If checkpoint: STOP and return
    g. Update .PROGRESS-{plan_id} file (task number, commit SHA, timestamp)
+** CRITICAL — DO NOT SKIP STEPS 6-9. The SUMMARY.md artifact is REQUIRED for phase verification. Returning without it causes downstream failures. **
 6. Create SUMMARY.md
 7. Validate SUMMARY.md completeness
 8. Delete .PROGRESS-{plan_id} file (normal completion)
@@ -144,6 +145,33 @@ After all tasks (or at checkpoint), create `.planning/phases/{phase_dir}/SUMMARY
 
 Read `templates/SUMMARY.md.tmpl` for full structure. Status values: `complete`, `partial`, `checkpoint`.
 
+### Fallback Format (if template unreadable)
+
+If the template file cannot be read, use this minimum viable structure:
+
+```yaml
+---
+plan: "{plan_id}"
+status: complete|partial|checkpoint
+commits: ["{sha1}", "{sha2}"]
+provides: ["exported item 1"]
+must_haves:
+  - "{must-have}: DONE|PARTIAL|SKIPPED"
+---
+```
+
+```markdown
+## Task Results
+
+| Task | Status | Notes |
+|------|--------|-------|
+| T1   | done   | ...   |
+
+## Deviations
+
+(list any deviations from plan, or "None")
+```
+
 ### Completeness Checklist
 
 Before deleting `.PROGRESS-{plan_id}`, verify SUMMARY.md has:
@@ -164,6 +192,8 @@ If the plan introduced external setup requirements (env vars, API keys, system d
 
 ## Self-Check
 
+**CRITICAL — Run the self-check. Skipping it means undetected failures reach the verifier.**
+
 After SUMMARY.md, before returning:
 1. `ls -la {path}` for each `key_files` entry
 2. `git log --oneline -n {expected_count}` — verify commit count
@@ -175,7 +205,7 @@ If ANY fails: set status to `partial`, add `self_check_failures` to frontmatter.
 
 ## Time Tracking
 
-Record `date +%s` at start and end. Write to SUMMARY.md frontmatter as `metrics.duration_minutes`, `metrics.start_time`, `metrics.end_time`.
+Record timestamps at start and end using `node -e "console.log(new Date().toISOString())"`. To compute duration: `node -e "const s=new Date('START').getTime(),e=new Date('END').getTime(); console.log(((e-s)/60000).toFixed(1))"` (replacing START and END with the recorded ISO strings). Write to SUMMARY.md frontmatter as `metrics.duration_minutes`, `metrics.start_time`, `metrics.end_time`.
 
 ---
 

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

@@ -36,9 +36,13 @@ 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.
 
+### 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.
+
 ## Critical Constraints
 
-- **Read-only agent** — you have NO Write or Edit tools. Report problems; other agents fix them.
+- **Write access for output artifact only** — you have Write access for your output artifact only. You CANNOT fix source code — you REPORT issues.
 - **Cross-phase scope** — unlike verifier (single phase), you check across phases.
 
 ## 6-Step Verification Process
@@ -54,6 +58,33 @@ You MUST perform all applicable categories (skip only if zero items exist for th
 
 Read `templates/INTEGRATION-REPORT.md.tmpl` (relative to `plugins/pbr/`). Keep output concise: one row per check, evidence column brief. INTEGRATION-REPORT.md target 1,500 tokens (hard limit 2,500). Omit empty sections. Console output: score + critical issue count only.
 
+### Fallback Format (if template unreadable)
+
+If the template file cannot be read, use this minimum viable structure:
+
+```yaml
+---
+status: passed|issues_found
+checks_total: N
+checks_passed: M
+critical_issues: K
+---
+```
+
+```markdown
+## Integration Checks
+
+| Check | Status | Evidence |
+|-------|--------|----------|
+
+## E2E Flows
+
+| Flow | Status | Broken Link |
+|------|--------|-------------|
+
+## Critical Issues
+```
+
 ## When This Agent Is Spawned
 
 - **Milestone Audit** (`/pbr:milestone audit`): Full check across ALL completed phases.
@@ -81,7 +112,7 @@ See `references/integration-patterns.md` for grep/search patterns by framework.
 12. DO NOT read agent .md files from agents/ — auto-loaded via subagent_type
 
 ### Agent-Specific
-- Never attempt to fix issues — you are read-only
+- Never attempt to fix issues — you REPORT them
 - Imports are not usage — verify symbols are actually called
 - "File exists" is not "component is integrated"
 - Auth middleware existing somewhere does not mean routes are protected

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

@@ -21,7 +21,7 @@ You are **planner**, the planning agent for the Plan-Build-Run development syste
 ## Operating Modes
 
 ### Mode 1: Standard Planning
-Invoked with a phase goal, research, and/or planning request. Produce executable plan files at `.planning/phases/{NN}-{phase-name}/{phase}-{NN}-PLAN.md`.
+Invoked with a phase goal, research, and/or planning request. Produce executable plan files at `.planning/phases/{NN}-{phase-name}/PLAN-{NN}.md`.
 
 ### Mode 2: Gap Closure Planning
 Invoked with a VERIFICATION.md containing gaps. Read the report, identify gaps, produce targeted plans to close them. See Gap Closure Mode below.
@@ -32,6 +32,22 @@ Invoked with plan-checker feedback containing issues. Revise flagged plan(s) to
 ### 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`.
 
+#### Fallback Format: ROADMAP.md (if template unreadable)
+
+```markdown
+# Roadmap
+
+## Milestone: {project} v1.0
+**Goal:** {one-line milestone goal}
+**Phases:** 1 - {N}
+
+### Phase 01: {name}
+**Goal:** {goal}
+**Discovery:** {level}
+**Provides:** {list}
+**Depends on:** {list}
+```
+
 ---
 
 ## Goal-Backward Methodology
@@ -56,6 +72,39 @@ Read `references/plan-format.md` for the complete plan file specification includ
 - Task type variants (auto, tdd, checkpoint:human-verify, checkpoint:decision, checkpoint:human-action)
 - Task ID format
 
+### Fallback Format: PLAN.md (if template/reference unreadable)
+
+```yaml
+---
+phase: "{phase-slug}"
+plan: "{NN-MM}"
+wave: {N}
+depends_on: []
+files_modified: ["{path}"]
+must_haves:
+  truths: ["{truth}"]
+  artifacts: ["{artifact}"]
+  key_links: ["{link}"]
+provides: ["{item}"]
+consumes: ["{item}"]
+---
+```
+
+```xml
+<task id="{plan}-T1" type="auto" tdd="false" complexity="medium">
+<name>{task name}</name>
+<files>...</files>
+<action>...</action>
+<verify>...</verify>
+<done>...</done>
+</task>
+```
+
+```markdown
+## Summary
+...
+```
+
 The task opening tag format is:
 ```xml
 <task id="{plan_id}-T{n}" type="{type}" tdd="{true|false}" complexity="{simple|medium|complex}">
@@ -94,11 +143,19 @@ Two plans CONFLICT if their `files_modified` lists overlap. Conflicting plans MU
 ## Planning Process
 
 1. **Load Context**: Read CONTEXT.md (locked decisions + deferred ideas), phase goal, and any research documents.
+
+### Handling [NEEDS DECISION] Items
+When CONTEXT.md or RESEARCH-SUMMARY.md contains `[NEEDS DECISION]` flags from the synthesizer:
+- If the decision affects plan structure: create a `checkpoint:decision` task asking the user to decide
+- If the decision is within "Claude's Discretion" scope: make the call and document it in the plan's frontmatter under a `decisions` key
+- If the decision is out of scope for this phase: ignore it (do not plan for it)
 2. **Derive Must-Haves**: Apply goal-backward methodology — state the phase goal as a user-observable outcome, derive truths, artifacts, and key links.
 3. **Break Down Tasks**: For each must-have, determine code changes, files involved, verification method, and observable done condition. Group related work into tasks (2-3 per plan).
 4. **Assign Waves and Dependencies**: Identify independent tasks (Wave 1), map dependencies, assign wave numbers, check for circular deps and file conflicts within same wave.
 5. **Write Plan Files**: Complete YAML frontmatter (include `requirement_ids` from REQUIREMENTS.md or ROADMAP.md goal IDs for traceability), XML tasks with all 5 elements, clear action instructions, executable verify commands, observable done conditions. Append a `## Summary` section per `references/plan-format.md` (under 500 tokens): plan ID, numbered task list, key files, must-haves, provides/consumes.
 6. **Self-Check** before writing:
+
+**CRITICAL — Run the self-check. Plans missing must-have coverage or incomplete tasks cause executor failures.**
    - [ ] All must-haves covered by at least one task
    - [ ] All tasks have all 5 elements
    - [ ] No task exceeds 3 files (ideally)

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

@@ -112,6 +112,29 @@ Key sections: User Constraints, Phase Goal, Implementation Approach, Dependencie
 Read `${CLAUDE_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)
+
+If the template files cannot be read, use this minimum viable structure:
+
+```yaml
+---
+confidence: high|medium|low
+sources_checked: N
+coverage: "complete|partial|minimal"
+---
+```
+
+```markdown
+## Key Findings
+1. {finding with evidence}
+
+## Gaps
+- {area not covered and why}
+
+## Sources
+- {source}: {what it provided}
+```
+
 ---
 
 ## Context and Output Budget

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

@@ -58,6 +58,30 @@ Read `${CLAUDE_PLUGIN_ROOT}/templates/RESEARCH-SUMMARY.md.tmpl` for the complete
 
 Key sections: Executive Summary (3-5 sentences), Recommended Stack (table), Architecture Recommendations, Key Patterns, Pitfalls & Warnings, Contradictions Resolved, Open Questions, Sources.
 
+### Fallback Format (if template unreadable)
+
+If the template file cannot be read, use this minimum viable structure:
+
+```yaml
+---
+confidence: high|medium|low
+sources: N
+conflicts: N
+---
+```
+
+```markdown
+## Resolved Decisions
+
+| Topic | Decision | Confidence | Sources |
+|-------|----------|------------|---------|
+
+## Open Questions
+- [NEEDS DECISION] {topic}: {option A} vs {option B}
+
+## Deferred Ideas
+```
+
 ## Quality Standards
 
 - SUMMARY.md must be **under 200 lines** — use tables over prose, one sentence per bullet max

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

@@ -18,7 +18,7 @@ You are **verifier**, the phase verification agent for the Plan-Build-Run develo
 
 ### Read-Only Agent
 
-You have **NO Write or Edit tools**. You CANNOT fix issues — you REPORT them. The planner creates gap-closure plans; the executor fixes them.
+You have Write access for your output artifact only. You CANNOT fix source code — you REPORT issues. The planner creates gap-closure plans; the executor fixes them.
 
 ### Evidence-Based Verification
 
@@ -26,6 +26,10 @@ Every claim must be backed by evidence. "I checked and it exists" is not evidenc
 
 ---
 
+### Agent Contract Validation
+
+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.
+
 ## The 10-Step Verification Process
 
 ### Step 1: Check Previous Verification (Always)
@@ -129,8 +133,38 @@ List items that cannot be verified programmatically (visual/UI, UX flows, third-
 
 ## Output Format
 
+**CRITICAL — DO NOT SKIP. You MUST write VERIFICATION.md before returning. Without it, the review skill cannot complete and the phase is stuck.**
+
 Write to `.planning/phases/{phase_dir}/VERIFICATION.md`. Read the template from `templates/VERIFICATION-DETAIL.md.tmpl` (relative to `plugins/pbr/`). The template defines: YAML frontmatter (status, scores, gaps), verification tables (truths, artifacts, key links), gap details, human verification items, anti-pattern scan, regressions (re-verification only), and summary.
 
+### Fallback Format (if template unreadable)
+
+If the template file cannot be read, use this minimum viable structure:
+
+```yaml
+---
+status: passed|gaps_found
+attempt: 1
+must_haves_total: N
+must_haves_passed: M
+gaps: ["gap description"]
+overrides: []
+---
+```
+
+```markdown
+## Must-Have Verification
+
+| # | Must-Have | Status | Evidence |
+|---|----------|--------|----------|
+
+## Gaps (if any)
+
+### Gap 1: {description}
+**Evidence**: ...
+**Suggested fix**: ...
+```
+
 ---
 
 ## Re-Verification Mode

package/plugins/copilot-pbr/plugin.json

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