@sienklogic/plan-build-run 2.9.1 → 2.11.0

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

@@ -19,9 +19,9 @@ Additionally for this skill:
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► REVIEWING PHASE {N}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► REVIEWING PHASE {N}                        ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Where `{N}` is the phase number from `$ARGUMENTS`. Then proceed to Step 1.
@@ -62,6 +62,7 @@ Execute these steps in order.
 
 1. Parse `$ARGUMENTS` for phase number and `--auto-fix` flag
 2. Read `.planning/config.json`
+   **CRITICAL: Write .active-skill NOW.** Write the text "review" to `.planning/.active-skill` using the Write tool.
 3. Resolve depth profile: run `node ${PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth` to get the effective feature/gate settings for the current depth. Store the result for use in later gating decisions.
 4. Validate:
    - Phase directory exists at `.planning/phases/{NN}-{slug}/`
@@ -535,6 +536,10 @@ Ask user: "Would you like to proceed with gap-closure plans without root cause a
 
 ---
 
+## Cleanup
+
+Delete `.planning/.active-skill` if it exists. This must happen on all paths (success, partial, and failure) before reporting results.
+
 ## Completion
 
 After review completes, always present a clear next action:
@@ -543,9 +548,9 @@ After review completes, always present a clear next action:
 
 Display the "Phase Complete" banner inline:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PHASE {N} COMPLETE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PHASE {N} COMPLETE                         ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N}: {Name}**
 
@@ -576,9 +581,9 @@ Then the branded "Next Up" block:
 
 **If gaps remain:**
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND                       ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N}: {name}** — {count} gaps remaining
 
@@ -605,9 +610,9 @@ Then the branded "Next Up" block:
 
 Display the "Milestone Complete" banner inline:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► MILESTONE COMPLETE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► MILESTONE COMPLETE                         ║
+╚══════════════════════════════════════════════════════════════╝
 
 {N} phases completed
 All phase goals verified

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

@@ -8,9 +8,9 @@ description: "Analyze an existing codebase. Maps structure, architecture, conven
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► SCANNING CODEBASE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SCANNING CODEBASE                          ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -177,9 +177,9 @@ Agent that failed: {focus_area} mapper
 Read key findings from each file (frontmatter or first section) and display using the branded stage banner from `references/ui-formatting.md`:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► SCAN COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SCAN COMPLETE ✓                            ║
+╚══════════════════════════════════════════════════════════════╝
 
 Project: {type} ({scale})
 Stack: {primary language} + {framework}
@@ -206,9 +206,10 @@ Top concerns:
 
 Then use the "Next Up" routing block:
 ```
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Start a project** — use the scan results to plan your work
 
@@ -216,13 +217,10 @@ Then use the "Next Up" routing block:
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
-
 **Also available:**
 - `/pbr:milestone new` — create a milestone to address concerns
 - `/pbr:status` — see project status
 
-───────────────────────────────────────────────────────────────
 ```
 
 ### Step 7: Git Integration

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

@@ -8,9 +8,9 @@ description: "Onboarding wizard. Initialize project, select models, verify setup
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► SETUP
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SETUP                                      ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -21,14 +21,29 @@ You are running the **setup** skill. This is an interactive onboarding wizard th
 
 ---
 
-## Step 1: Detect Project State
+## Step 1: Detect Project State — Idempotency Guard
 
 Check if `.planning/` directory exists in the current working directory.
 
 **If `.planning/` exists**:
-- Read `.planning/config.json` to check current settings
-- Tell the user: "Existing Plan-Build-Run project detected. This wizard will review your configuration."
-- Skip to Step 3 (model selection)
+- Check for existing core files: `STATE.md`, `ROADMAP.md`, `config.json`
+- If ANY of these exist, present a checkpoint:
+
+  Use AskUserQuestion:
+    question: "Existing project detected with {list of found files}. How should we proceed?"
+    header: "Setup"
+    options:
+      - label: "Resume"       description: "Keep existing .planning/ and review configuration (recommended)"
+      - label: "Reset"        description: "Archive current .planning/ to .planning.bak/ and start fresh"
+      - label: "Abort"        description: "Cancel setup — keep everything as-is"
+
+  - If "Resume": Tell the user: "Keeping existing project. Reviewing configuration." Skip to Step 3 (model selection)
+  - If "Reset": Run `mv .planning .planning.bak` (creating a backup), then proceed with fresh setup below
+  - If "Abort": Display "Setup cancelled. Run `/pbr:status` to see current project state." and stop
+
+- If `.planning/` exists but has NONE of the core files (empty or only has subdirs):
+  - Tell the user: "Found empty .planning/ directory. Proceeding with initialization."
+  - Continue to fresh setup below
 
 **If `.planning/` does NOT exist**:
 - Ask the user:
@@ -48,10 +63,14 @@ If "No", display: "Run `/pbr:begin` when you're ready to start a project. It inc
 
 If "Yes", create the minimal `.planning/` structure:
 
+**CRITICAL: Create .planning/ directory structure NOW. Do NOT skip this step.**
+
 ```bash
 mkdir -p .planning/phases .planning/todos/pending .planning/todos/done .planning/logs .planning/research
 ```
 
+**CRITICAL: Write .planning/config.json NOW. Do NOT skip this step.**
+
 Create `.planning/config.json` with defaults:
 ```json
 {
@@ -120,6 +139,8 @@ Create `.planning/config.json` with defaults:
 }
 ```
 
+**CRITICAL: Write .planning/STATE.md NOW. Do NOT skip this step.**
+
 Create `.planning/STATE.md`:
 ```markdown
 ---
@@ -215,13 +236,38 @@ Apply selections:
 
 ---
 
+## Step 4b: CLAUDE.md Integration
+
+Check if a `CLAUDE.md` file exists in the project root.
+
+**If it exists**: Read it. If it does NOT already contain a "Plan-Build-Run" section, append the block below.
+**If it does NOT exist**: Create `CLAUDE.md` with the block below.
+
+Append/create this content:
+
+```markdown
+## Plan-Build-Run
+
+This project uses [Plan-Build-Run](https://github.com/SienkLogic/plan-build-run) for structured development.
+
+- Project state: `.planning/STATE.md` (source of truth for current phase and progress)
+- Configuration: `.planning/config.json`
+- Run `/pbr:status` to see current project state and suggested next action.
+
+**After compaction or context recovery**: Read `.planning/STATE.md` (especially the `## Session Continuity` section) before proceeding with any work. The PreCompact hook writes recovery state there automatically.
+```
+
+---
+
 ## Step 5: Verification
 
+**CRITICAL: Run validation checks NOW to confirm setup succeeded. Do NOT skip this step.**
+
 Run a quick health check:
 
 1. Verify `.planning/config.json` is valid JSON
 2. Verify `.planning/STATE.md` exists and is parseable
-3. Verify hook scripts are accessible: `node ${CLAUDE_PLUGIN_ROOT}/scripts/progress-tracker.js` from the project directory
+3. Verify hook scripts are accessible: `node ${PLUGIN_ROOT}/scripts/progress-tracker.js` from the project directory
 4. Check that `npm test` works (if package.json exists)
 
 Display results:

package/plugins/copilot-pbr/skills/shared/error-reporting.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../../pbr/skills/shared/error-reporting.md -->
 # Error Reporting Fragment
 
 Standard error display formats for all skills. Reference `references/ui-formatting.md` for the full brand guide.
@@ -78,3 +77,5 @@ Blocked: {short reason}
 ```
 
 This format is used by validate-commit.js and check-dangerous-commands.js. The `decision: "block"` and `reason` fields in the JSON output follow this pattern.
+
+Block reasons should always include a "To fix:" line with actionable guidance so the user or agent knows how to resolve the block.

package/plugins/copilot-pbr/skills/shared/progress-display.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../../pbr/skills/shared/progress-display.md -->
 # Progress Display Fragment
 
 Standard progress display formats for all skills. Reference `references/ui-formatting.md` for the full brand guide.

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

@@ -24,11 +24,15 @@ These rules prevent context rot -- quality degradation as the context window fil
 8. **Never** read `.planning/logs/` files -- only the health skill reads these.
 9. **Do not** re-read full file contents when frontmatter is sufficient -- frontmatter contains status, key_files, commits, and provides fields.
 
+## Task/Subagent Rules (apply to every skill)
+
+10. **Never** invoke `Skill()` inside a `Task()` subagent -- the Skill tool is not available in subagent contexts. Subagents spawned by `Task()` cannot resolve `/pbr:*` skill prefixes, so `Skill({ skill: "pbr:plan" })` will silently fail. Instead, chain skills at the orchestrator level (return control to the orchestrator, then call `Skill()` from there). For subagent work, use `subagent_type: "pbr:{agent}"` which auto-loads agent definitions.
+
 ## Behavioral Rules (apply to every skill)
 
-10. **Do not** re-litigate decisions that are already locked in CONTEXT.md -- respect locked decisions unconditionally.
-11. **Do not** create artifacts the user did not approve -- always confirm before writing new planning documents.
-12. **Do not** modify files outside the skill's stated scope -- check the "Files Created/Modified" table in each skill.
-13. **Do not** suggest multiple next actions without clear priority -- one primary suggestion, alternatives listed secondary.
-14. **Do not** use `git add .` or `git add -A` -- stage specific files only.
-15. **Do not** include sensitive information (API keys, passwords, tokens) in planning documents or commits.
+11. **Do not** re-litigate decisions that are already locked in CONTEXT.md -- respect locked decisions unconditionally.
+12. **Do not** create artifacts the user did not approve -- always confirm before writing new planning documents.
+13. **Do not** modify files outside the skill's stated scope -- check the "Files Created/Modified" table in each skill.
+14. **Do not** suggest multiple next actions without clear priority -- one primary suggestion, alternatives listed secondary.
+15. **Do not** use `git add .` or `git add -A` -- stage specific files only.
+16. **Do not** include sensitive information (API keys, passwords, tokens) in planning documents or commits.

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

@@ -8,9 +8,9 @@ description: "Show current project status and suggest what to do next."
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PROJECT STATUS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PROJECT STATUS                             ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.

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

@@ -10,9 +10,9 @@ description: "Install or configure the PBR status line in Claude Code."
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► STATUS LINE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► STATUS LINE                                ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -76,9 +76,12 @@ If "Install":
 
 **CRITICAL: Use Read tool to read the file, then Write to update it. Do NOT use sed or other text manipulation on JSON files.**
 
+**CRITICAL: Back up settings.json NOW.** Write the original content to `~/.claude/settings.json.bak` before making any changes.
+
 1. Read `~/.claude/settings.json`
-2. Parse the JSON
-3. Set `statusLine` to:
+2. Write the original content to `~/.claude/settings.json.bak`
+3. Parse the JSON
+4. Set `statusLine` to:
    ```json
    {
      "type": "command",
@@ -86,7 +89,7 @@ If "Install":
    }
    ```
    Where `SCRIPT_PATH` is the resolved absolute path from Step 1. Use forward slashes even on Windows.
-4. Write the updated JSON back (preserve all other settings, use 2-space indentation)
+5. Write the updated JSON back (preserve all other settings, use 2-space indentation)
 
 ### Step 4: Verify and confirm
 
@@ -113,8 +116,9 @@ Customize per-project via .planning/config.json:
 
 1. Read `~/.claude/settings.json`
 2. If no `statusLine` key: inform user "No status line configured." and stop
-3. Remove the `statusLine` key from the JSON
-4. Write the updated file
+3. **CRITICAL: Back up settings.json NOW.** Write the original content to `~/.claude/settings.json.bak` before making any changes.
+4. Remove the `statusLine` key from the JSON
+5. Write the updated file
 5. Display: `✓ PBR status line removed. Restart Claude Code to take effect.`
 
 ---

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

@@ -8,9 +8,9 @@ description: "File-based persistent todos. Add, list, complete — survives sess
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► TODO
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► TODO                                       ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -72,15 +72,17 @@ theme: {inferred-theme}
 
 8. Confirm with branded output:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► TODO ADDED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► TODO ADDED ✓                               ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Todo {NNN}:** {description}
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Work on it now** or see your task list
 
@@ -88,13 +90,13 @@ theme: {inferred-theme}
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
 - `/pbr:todo list` — see all pending todos
 - `/pbr:status` — see project status
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 ### `list [theme]`
@@ -114,21 +116,23 @@ Pending Todos:
 
 5. Offer actions with branded routing:
 ```
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Pick a todo** — mark one done or start working
 
 `/pbr:todo work <NNN>` — start working on a todo
 `/pbr:todo done <NNN>` — mark a todo as complete
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
 - `/pbr:status` — see project status
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 ### `done <NNN>`
@@ -147,20 +151,37 @@ Todo {NNN} not found in pending todos.
 3. Ensure `.planning/todos/done/` directory exists (create if needed)
 4. Read the pending file content
 5. Update frontmatter in the content: set `status: done` and add `completed: {YYYY-MM-DD}`
+
+**CRITICAL: Write to done/ FIRST, verify it exists, THEN delete from pending/. Do NOT delete pending before confirming done/ write succeeded.**
+
 6. Write the updated content to `.planning/todos/done/{NNN}-{slug}.md`
-7. Delete the original file from `.planning/todos/pending/` (use `rm` via Bash)
+7. Verify the done/ file was written successfully: check that `.planning/todos/done/{NNN}-{slug}.md` exists and has content (use `ls` or Glob)
+   - If the done/ write failed, abort and display:
+     ```
+     ╔══════════════════════════════════════════════════════════════╗
+     ║  ERROR                                                       ║
+     ╚══════════════════════════════════════════════════════════════╝
+
+     Failed to write to done/. Pending file preserved.
+
+     **To fix:** Check that `.planning/todos/done/` exists and is writable.
+     ```
+     Do NOT proceed to delete the pending file.
+8. Only THEN delete the original file from `.planning/todos/pending/` (use `rm` via Bash)
 8. Update STATE.md
 9. Confirm with branded output:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► TODO COMPLETED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► TODO COMPLETED ✓                           ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Todo {NNN}:** {title}
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **See remaining tasks**
 
@@ -168,13 +189,13 @@ Todo {NNN} not found in pending todos.
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
 - `/pbr:continue` — execute next logical step
 - `/pbr:status` — see project status
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 ### `work <NNN>`
@@ -206,9 +227,9 @@ Which approach?
 
 6. Display branded output:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► WORKING ON TODO {NNN}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► WORKING ON TODO {NNN}                      ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Todo {NNN}:** {title}
 **Routing to:** /pbr:{chosen-skill}
@@ -228,15 +249,17 @@ For `/pbr:plan`, if no phase exists for this work yet, suggest the user run `/pb
 8. When the skill completes, remind the user:
 
 ```
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Mark this todo as done if the work is complete**
 
 `/pbr:todo done {NNN}`
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 ### No arguments

package/plugins/cursor-pbr/.cursor-plugin/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 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

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

@@ -38,7 +38,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"
@@ -115,6 +116,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/cursor-pbr/agents/executor.md

@@ -28,6 +28,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)
@@ -143,6 +144,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:
@@ -163,6 +191,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
@@ -174,7 +204,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`.
 
 ---