@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/plugins/pbr/skills/milestone/templates/audit-output.md.tmpl

@@ -0,0 +1,76 @@
+## If PASSED
+
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► MILESTONE AUDIT PASSED ✓                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+All phases verified, integration checks passed, requirements covered.
+
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Complete the milestone** — archive and tag
+
+`/pbr:complete-milestone {version}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+
+
+**Also available:**
+- `/pbr:plan-milestone-gaps` — address any minor issues first
+- `/pbr:progress` — see project status
+
+
+## If GAPS FOUND
+
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► MILESTONE AUDIT — GAPS FOUND ⚠             ║
+╚══════════════════════════════════════════════════════════════╝
+
+Found {count} gaps:
+- {gap 1}
+- {gap 2}
+
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Close the gaps** — create fix phases
+
+`/pbr:plan-milestone-gaps`
+
+<sub>`/clear` first → fresh context window</sub>
+
+
+
+**Also available:**
+- `/pbr:complete-milestone` — proceed despite gaps
+- `/pbr:progress` — see project status
+
+
+## If TECH DEBT
+
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► MILESTONE AUDIT — TECH DEBT ⚠              ║
+╚══════════════════════════════════════════════════════════════╝
+
+Milestone functional but has {count} tech debt items.
+
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Address tech debt or proceed**
+
+`/pbr:plan-milestone-gaps` — create cleanup phases
+`/pbr:complete-milestone` — proceed as-is
+
+<sub>`/clear` first → fresh context window</sub>

package/plugins/pbr/skills/milestone/templates/complete-output.md.tmpl

@@ -0,0 +1,32 @@
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► MILESTONE COMPLETE 🎉                      ║
+╚══════════════════════════════════════════════════════════════╝
+
+**{version}**
+
+Stats:
+- {count} phases, {count} plans
+- {count} commits, {lines} lines of code
+- {duration} days
+
+Archived to: .planning/milestones/{version}/
+Git tag: {version}
+
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Start the next milestone** — plan new features
+
+`/pbr:new-milestone`
+
+<sub>`/clear` first → fresh context window</sub>
+
+
+
+**Also available:**
+- `/pbr:progress` — see project status
+- `/pbr:help` — see all commands
+

package/plugins/pbr/skills/milestone/templates/edge-cases.md

@@ -0,0 +1,54 @@
+# Milestone Edge Cases
+
+## No ROADMAP.md exists
+- For `new`: Create one from scratch (this is a fresh start)
+- For others, display:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+No roadmap found.
+
+**To fix:** Run `/pbr:new-project` or `/pbr:new-milestone` first.
+```
+
+## Milestone has no phases
+Display:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+No phases found for this milestone.
+
+**To fix:**
+- For `complete`: Nothing to complete — add phases first.
+- For `audit`: Nothing to audit — build phases first.
+```
+
+## Audit finds no gaps
+- Status: PASSED
+- Skip the recommendations section
+- Suggest proceeding to complete
+
+## Version already exists (tag collision)
+Display:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+Git tag {version} already exists.
+
+**To fix:** Use a different version number (e.g., {version}.1).
+```
+Ask for alternative via AskUserQuestion.
+
+## Partially verified milestone
+- `complete` warns but allows proceeding with user confirmation
+- `audit` treats unverified phases as gaps
+
+## Large milestone (8+ phases)
+- `audit` may take longer due to integration checking
+- Warn: "This milestone has {count} phases. The audit may take a few minutes."

package/plugins/pbr/skills/milestone/templates/gaps-output.md.tmpl

@@ -0,0 +1,25 @@
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► GAP PHASES CREATED ✓                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+Created {count} gap-closure phase(s):
+- Phase {N}: {name}
+- Phase {N+1}: {name}
+
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Plan the first gap-closure phase**
+
+`/pbr:plan-phase {N}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+
+
+**Also available:**
+- `/pbr:progress` — see project status
+

package/plugins/pbr/skills/milestone/templates/integration-checker-prompt.md.tmpl

@@ -0,0 +1,25 @@
+You are integration-checker. Perform cross-phase integration verification.
+
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/ROADMAP.md — phase structure, goals, and dependencies
+2. .planning/phases/{NN}-{slug}/SUMMARY.md — for each milestone phase (read all)
+</files_to_read>
+
+Milestone: {version or "current"}
+Phases to check: {list of phase directories}
+
+Instructions:
+1. Read all SUMMARY.md files for the milestone phases
+2. Build a dependency graph from provides/affects/requires fields
+3. Verify integration points:
+   a. Every "requires" in a later phase is "provided" by an earlier phase
+   b. Every "affects" target still exists and hasn't been broken
+   c. No circular dependencies
+   d. No orphaned provides (things built but never consumed)
+4. Check for:
+   - Broken imports/references between phases
+   - API contract mismatches
+   - Missing error handling at integration points
+   - Configuration inconsistencies
+5. Return findings as a structured report

package/plugins/pbr/skills/milestone/templates/new-output.md.tmpl

@@ -0,0 +1,29 @@
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► MILESTONE CREATED ✓                        ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Milestone: {name}** — {count} phases
+
+Phases:
+{N}. {name}
+{N+1}. {name}
+...
+
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Phase {N}: {name}** — start with discussion or planning
+
+`/pbr:discuss-phase {N}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+
+
+**Also available:**
+- `/pbr:plan-phase {N}` — skip discussion, plan directly
+- `/pbr:progress` — see project status
+

package/plugins/pbr/skills/note/SKILL.md

@@ -25,6 +25,10 @@ You are running the **note** skill. Your job is zero-friction idea capture. One
 
 This skill runs **inline** — no Task, no AskUserQuestion, no Bash.
 
+## References
+
+- `references/ui-brand.md` — Status symbols, banners, formatting for note display output
+
 ---
 
 ## Storage Format
@@ -131,7 +135,7 @@ Convert a note into a todo file.
 1. Run the **list** logic to build the numbered index (both scopes)
 2. Find entry N from the numbered list
 3. If N is invalid or refers to an already-promoted note, tell the user and stop
-4. **Requires `.planning/` directory** — if it doesn't exist, warn: "Todos require a Plan-Build-Run project. Run `/pbr:begin` to initialize one, or use `/pbr:todo add` in an existing project."
+4. **Requires `.planning/` directory** — if it doesn't exist, warn: "Todos require a Plan-Build-Run project. Run `/pbr:new-project` to initialize one, or use `/pbr:add-todo` in an existing project."
 5. Ensure `.planning/todos/pending/` directory exists
 6. Generate todo ID: `{NNN}-{slug}` where NNN is the next sequential number (scan both `.planning/todos/pending/` and `.planning/todos/done/` for the highest existing number, increment by 1, zero-pad to 3 digits) and slug is the first ~4 meaningful words of the note text, lowercase, hyphen-separated
 7. Extract the note text from the source file (body after frontmatter)
@@ -169,7 +173,7 @@ Promoted from quick note captured on {original date}.
 
 1. **"list" as note text**: `/pbr:note list of things` → saves note "list of things" (subcommand only when `list` is the entire arg)
 2. **No `.planning/`**: Falls back to global `~/.claude/notes/` — works in any directory
-3. **Promote without project**: Warns that todos require `.planning/`, suggests `/pbr:begin`
+3. **Promote without project**: Warns that todos require `.planning/`, suggests `/pbr:new-project`
 4. **Large files**: `list` shows last 10 when >20 active entries
 5. **Duplicate slugs**: Append `-2`, `-3` etc. to filename if slug already used on same date
 6. **`--global` position**: Stripped from anywhere — `--global my idea` and `my idea --global` both save "my idea" globally
@@ -180,6 +184,8 @@ Promoted from quick note captured on {original date}.
 
 ## Error Handling
 
+Reference: `skills/shared/error-reporting.md` for branded error output patterns.
+
 ### Write failure
 If the Write tool fails (permissions, disk full, etc.), display:
 ```
@@ -206,6 +212,8 @@ Note {N} not found. Valid range: 1-{max}.
 
 ---
 
+Reference: `skills/shared/commit-planning-docs.md` -- if `planning.commit_docs` is true, commit the note file.
+
 ## Anti-Patterns
 
 1. **DO NOT** ask questions on append — just write and confirm

package/plugins/pbr/skills/pause/SKILL.md

@@ -18,7 +18,7 @@ allowed-tools: Read, Write, Bash, Glob
 
 Then proceed to Step 1.
 
-# /pbr:pause — Save Session State
+# /pbr:pause-work — Save Session State
 
 You are running the **pause** skill. Your job is to capture the current session state so the user can resume exactly where they left off in a future conversation. This creates a `.continue-here.md` handoff file with everything the next session needs.
 
@@ -56,7 +56,7 @@ Read the following files to understand where things stand:
 
      No Plan-Build-Run project state found. Nothing to pause.
 
-     **To fix:** Run `/pbr:begin` to initialize a project first.
+     **To fix:** Run `/pbr:new-project` to initialize a project first.
      ```
 
 2. **`.planning/config.json`** — Project settings
@@ -100,7 +100,7 @@ Scan for plan files without corresponding SUMMARY.md files:
 
 #### Key Decisions Made
 Check for:
-- Recent CONTEXT.md files (from `/pbr:discuss`)
+- Recent CONTEXT.md files (from `/pbr:discuss-phase`)
 - Key decisions in recent SUMMARY.md files
 - Any deviations noted in summaries
 
@@ -112,13 +112,20 @@ From STATE.md blockers section and any:
 - Unresolved issues noted in summaries
 
 #### What to Do Next
-Determine the logical next action (same routing logic as `/pbr:status`):
+Determine the logical next action (same routing logic as `/pbr:progress`):
 - If mid-plan execution: "Continue building phase N"
 - If between plans in a phase: "Execute next plan (plan M)"
 - If phase complete, not reviewed: "Review phase N"
 - If phase reviewed, has gaps: "Fix gaps in phase N"
 - If phase complete: "Plan phase N+1"
 
+#### Mental Context
+Reflect on the current approach:
+- What strategy is being followed for this phase?
+- Why was this approach chosen over alternatives?
+- What's been tricky or surprising?
+- Any user preferences expressed in the current conversation?
+
 ### Step 4: Write .continue-here.md
 
 **CRITICAL: Write pause state NOW before displaying confirmation. Do NOT skip this step.**
@@ -129,11 +136,45 @@ Write the handoff file to the current phase directory:
 
 **Content:**
 
-Read `skills/pause/templates/continue-here.md.tmpl` for the handoff file format. Fill in all `{variable}` placeholders with actual session data gathered in Steps 1-3.
+Read `${CLAUDE_SKILL_DIR}/templates/continue-here.md.tmpl` for the handoff file format. Fill in all `{variable}` placeholders with actual session data gathered in Steps 1-3. Fill in all XML sections. The `<context>` section should capture your understanding of the current approach and reasoning -- not just facts. Think of it as a message to your future self explaining what was going on.
+
+### Step 4b: Write HANDOFF.json (Machine-Readable Companion)
+
+**CRITICAL: Write HANDOFF.json NOW, alongside .continue-here.md. Do NOT skip this step.**
+
+After writing `.continue-here.md`, also create `.planning/HANDOFF.json` with structured state for machine consumption:
+
+1. Read current STATE.md for phase/plan/status
+2. Read current plan file to get task progress (current task, total tasks)
+3. Check for uncommitted files via `git status --short`
+4. Read the HANDOFF.json template: `${CLAUDE_PLUGIN_ROOT}/templates/HANDOFF.json.tmpl`
+5. Fill in all fields from the template with actual session data:
+   - `status`: "paused"
+   - `created_at`: current ISO timestamp
+   - `phase`: number, slug, and name from STATE.md
+   - `plan`: number, wave, current task, total tasks
+   - `next_action`: the suggested next action from Step 3
+   - `blockers`: any blockers from STATE.md or verification failures
+   - `human_actions_pending`: any actions the user needs to take
+   - `completed_tasks`: task descriptions already done in current plan
+   - `uncommitted_files`: from `git status --short`
+   - `context_notes`: mental context about current approach and reasoning
+6. Write the filled JSON to `.planning/HANDOFF.json`
+
+**Purpose:** `.continue-here.md` is human-readable; `HANDOFF.json` is machine-readable. The resume skill reads HANDOFF.json first for structured data, falling back to `.continue-here.md` for backward compatibility.
 
 ### Step 5: Update STATE.md
 
-Update the Session Continuity section of STATE.md:
+**CRITICAL -- DO NOT SKIP: Update STATE.md frontmatter AND body. Both must be updated atomically.**
+
+First, update the STATE.md YAML frontmatter:
+- Set `last_command: "/pbr:pause-work"`
+- Set `last_activity: {ISO datetime}`
+- Set `session_last: {ISO datetime}` — when this session ended
+- Set `session_stopped_at: "{brief description of current work}"` — e.g. "Phase 2, Plan 3 — building executor agent updates"
+- Set `session_resume: ".planning/phases/{NN}-{phase-name}/.continue-here.md"` — pointer to the detailed handoff file
+
+Then update the Session Continuity section of STATE.md:
 
 ```markdown
 ### Session Continuity
@@ -154,6 +195,7 @@ If `planning.commit_docs: true` in config.json:
 
 ```bash
 git add .planning/phases/{NN}-{phase-name}/.continue-here.md
+git add .planning/HANDOFF.json
 git add .planning/STATE.md
 git commit -m "wip(planning): save session state — phase {N} plan {M}"
 ```
@@ -185,7 +227,7 @@ Remaining: {count} plans in this phase
 
 **Resume in your next session**
 
-`/pbr:resume`
+`/pbr:resume-work`
 
 <sub>`/clear` first → fresh context window</sub>
 
@@ -207,6 +249,8 @@ Remaining: {count} plans in this phase
 
 ---
 
+Reference: `skills/shared/error-reporting.md` for branded error output patterns.
+
 ## Edge Cases
 
 ### No work was done this session

package/plugins/pbr/skills/pause/templates/continue-here.md.tmpl

@@ -1,71 +1,52 @@
 # Template: Continue Here Handoff File
 # Used by: pause/SKILL.md (Step 4)
 # Output path: .planning/phases/{NN}-{phase-name}/.continue-here.md
-# Variables: {datetime}, {hours}, {phase}, {plan}, {status}, {session work}, {remaining}, {decisions}, {blockers}, {context}, {next steps}
+# Variables: {datetime}, {hours}, {phase}, {plan}, {status}, {branch}, {working files}, {session work}, {remaining}, {decisions}, {context}, {next action}
 
 # Continue Here
 
 **Paused:** {ISO datetime}
-**Session duration:** ~{estimated hours} (based on git log timestamps)
-
-## Position
+**Session duration:** ~{estimated hours}
 
+<current_state>
 Phase: {N} -- {name}
-Plan: {M} of {total} (or "between plans" / "phase complete")
+Plan: {M} of {total}
 Status: {in-progress / between-plans / reviewing / planning}
+Branch: {git branch name}
+Working files: {list of files with uncommitted changes, if any}
+</current_state>
 
-## Completed This Session
-
-{List of work done, with commit references where available}
-
+<completed_work>
+{List of work done with commit references}
 - Plan {A}: {summary} (commit: {short hash})
 - Plan {B}: {summary} (commit: {short hash})
-- Quick task: {description} (commit: {short hash})
-
-{If nothing was completed:}
-- No plans completed this session (discussion/planning only)
-
-## Remaining
+{If nothing completed: "No plans completed (discussion/planning only)"}
+</completed_work>
 
+<remaining_work>
 {What still needs to be done in this phase}
-
 - Plan {C}: {brief description from plan frontmatter}
 - Plan {D}: {brief description from plan frontmatter}
+{If phase complete: "Phase complete. Next: review or next phase"}
+</remaining_work>
 
-{If phase is complete:}
-- Phase {N} is complete. Next: {review or next phase}
-
-## Decisions Made
-
+<decisions_made>
 {Key decisions from this session that affect future work}
-
-- {decision 1}: {brief description}
-- {decision 2}: {brief description}
-
-{If no notable decisions:}
-- No major decisions this session
-
-## Blockers
-
-{Any issues preventing progress}
-
-- {blocker description}
-
-{If no blockers:}
-- None
-
-## Context Notes
-
-{Any additional context that would help the next session}
-
-- {note about something tricky}
-- {note about something to watch out for}
-- {note about user preferences expressed during this session}
-
-## Next Steps
-
-{Ordered list of what to do when resuming}
-
-1. {Specific first action with command}
-2. {Following action}
-3. {And so on}
+- {decision}: {rationale}
+{If none: "No major decisions this session"}
+</decisions_made>
+
+<context>
+{Mental context -- approach, reasoning, "vibe" of the work}
+- Approach: {what strategy was being followed}
+- Reasoning: {why this approach was chosen}
+- Watch out: {things that are tricky or surprising}
+- User preferences: {any preferences expressed during this session}
+</context>
+
+<next_action>
+{Single most important action to take when resuming}
+Command: {exact /pbr: command to run}
+Why: {brief explanation of why this is the right next step}
+Prerequisites: {anything that needs to happen first, or "none"}
+</next_action>