@sienklogic/plan-build-run 2.21.1 → 2.21.2

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/milestone-summary/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: milestone-summary
+description: "Generate comprehensive milestone summary from archived artifacts. For team onboarding and stakeholder review."
+allowed-tools: Read, Write, Bash, Glob, Grep
+argument-hint: "[version]"
+---
+
+**STOP — DO NOT READ THIS FILE. You are already reading it.**
+
+# /pbr:milestone-summary — Milestone Summary for Onboarding
+
+Generate a comprehensive, navigable summary document from milestone artifacts. Useful for team onboarding and stakeholder review.
+
+## Step 0 — Banner
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► MILESTONE SUMMARY                          ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+## Step 1 — Determine Milestone
+
+If `$ARGUMENTS` has a version: use it (auto-prefix `v` if missing).
+If empty: use the most recent completed milestone from ROADMAP.md.
+
+## Step 2 — Locate Archive
+
+Check both formats:
+- Directory: `.planning/milestones/v{X}/` (preferred)
+- Flat files: `.planning/milestones/v{X}-*.md` (legacy)
+
+If not found, check if it's the current active milestone (not yet archived) — scan `.planning/phases/` for the milestone's phase range.
+
+## Step 3 — Aggregate Artifacts
+
+For each phase in the milestone:
+1. Read PLAN.md frontmatter: objectives, must_haves, implements
+2. Read SUMMARY.md: what was built, key decisions, deviations
+3. Read VERIFICATION.md: pass/fail status, gaps
+4. Compile into phase summary sections
+
+## Step 4 — Write Summary
+
+Write to `.planning/MILESTONE-SUMMARY.md` (or `.planning/milestones/v{X}/SUMMARY.md` if archived):
+
+```markdown
+# Milestone {version}: {name}
+
+**Shipped:** {date}
+**Phases:** {count}
+**Commits:** {count}
+
+## Overview
+{2-3 sentence summary of what this milestone delivered}
+
+## Phase Summaries
+
+### Phase {N}: {name}
+**Goal:** {from ROADMAP}
+**Status:** {verified/partial}
+**Key files:** {from SUMMARY key_files}
+**Decisions:** {from SUMMARY key_decisions}
+
+{repeat for each phase}
+
+## Requirements Coverage
+| REQ | Status | Phase |
+|-----|--------|-------|
+
+## Architecture Impact
+{What changed in the system architecture across this milestone}
+
+## Known Issues
+{Deferred items, verification gaps, tech debt from this milestone}
+```
+
+## Step 5 — Report
+
+Display: `Summary written to {path} — {phase_count} phases, {commit_count} commits`
+
+## Anti-Patterns
+
+1. DO NOT read full file bodies when frontmatter suffices
+2. DO NOT include raw PLAN.md task content — summarize
+3. DO NOT generate if milestone doesn't exist — error with available milestones

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
@@ -74,7 +78,11 @@ Create a timestamped note file in the target directory.
 
 1. Determine scope (project or global) per Storage Format above
 2. Ensure the notes directory exists (`.planning/notes/` or `~/.claude/notes/`)
-3. Generate slug: first ~4 meaningful words of the note text, lowercase, hyphen-separated (strip articles/prepositions from the start)
+3. Generate slug via CLI:
+   ```bash
+   node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js slug-generate "{note text}"
+   ```
+   Parse the JSON output to get the `slug` field.
 4. Generate filename: `{YYYY-MM-DD}-{slug}.md`
    - If a file with that name already exists, append `-2`, `-3`, etc.
 5. Write the file with frontmatter and note text (see Storage Format)
@@ -131,9 +139,13 @@ 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
+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 generated via CLI:
+   ```bash
+   node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js slug-generate "{note text}"
+   ```
+   Parse the JSON output to get the `slug` field.
 7. Extract the note text from the source file (body after frontmatter)
 8. Create `.planning/todos/pending/{id}.md`:
 
@@ -169,7 +181,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 +192,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 +220,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

@@ -2,6 +2,7 @@
 name: pause
 description: "Save your current session state for later resumption."
 allowed-tools: Read, Write, Bash, Glob
+argument-hint: "[reason]"
 ---
 
 **STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.**
@@ -18,7 +19,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 +57,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 +101,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 +113,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,22 +137,51 @@ 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
+**CRITICAL: Write HANDOFF.json NOW. This file is required for session resumption.**
+
+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 via CLI.**
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state record-session --stopped-at "{brief description of current work}"
+```
 
-```markdown
-### Session Continuity
+This updates STATE.md frontmatter (`session_last`, `session_stopped_at`, `session_resume`, `last_command`, `last_activity`) and the Session Continuity body section atomically.
 
-**Last paused:** {ISO datetime}
-**Position:** Phase {N}, Plan {M}
-**Continue file:** .planning/phases/{NN}-{phase-name}/.continue-here.md
-**Next action:** {suggested command}
+Also update the session_resume pointer:
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update last_command "/pbr:pause-work"
 ```
 
-If the Session Continuity section doesn't exist, create it at the end of STATE.md.
+If the CLI fails, display a branded ERROR box: "Failed to update STATE.md session state." and stop.
 
 ### Step 6: Commit as WIP
 
@@ -154,6 +191,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 +223,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 +245,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>