@sienklogic/plan-build-run 2.0.2 → 2.1.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

@@ -12,9 +12,9 @@ argument-hint: "<text> | list | promote <index> [--global]"
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► NOTE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► NOTE                                       ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -25,14 +25,29 @@ 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
+
 ---
 
-## Scope Detection
+## Storage Format
 
-Two scopes exist. Auto-detect which to use:
+Notes are stored as **individual markdown files** in a notes directory:
 
-1. **Project scope**: `.planning/NOTES.md` — used when `.planning/` directory exists in cwd
-2. **Global scope**: `~/.claude/notes.md` — used as fallback when no `.planning/`, or when `--global` flag is present
+- **Project scope**: `.planning/notes/{YYYY-MM-DD}-{slug}.md` — used when `.planning/` directory exists in cwd
+- **Global scope**: `~/.claude/notes/{YYYY-MM-DD}-{slug}.md` — used as fallback when no `.planning/`, or when `--global` flag is present
+
+Each note file has this format:
+
+```markdown
+---
+date: "YYYY-MM-DD HH:mm"
+promoted: false
+---
+
+{note text verbatim}
+```
 
 **`--global` flag**: Strip `--global` from anywhere in `$ARGUMENTS` before parsing. When present, force global scope regardless of whether `.planning/` exists.
 
@@ -57,27 +72,17 @@ Parse `$ARGUMENTS` after stripping `--global`:
 
 ## Subcommand: append
 
-Append a timestamped note to the target file.
+Create a timestamped note file in the target directory.
 
 ### Steps
 
-1. Determine scope (project or global) per Scope Detection above
-2. Read the target file if it exists
-3. If the file doesn't exist, create it with this header:
-
-```markdown
-# Notes
-
-Quick captures from `/pbr:note`. Ideas worth remembering.
-
----
-
-```
-
-4. Ensure the file content ends with a newline before appending
-5. Append: `- [YYYY-MM-DD HH:mm] {note text verbatim}`
-6. Write the file
-7. Confirm with exactly one line: `Noted ({scope}): {note text}`
+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)
+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)
+6. Confirm with exactly one line: `Noted ({scope}): {note text}`
    - Where `{scope}` is "project" or "global"
 
 ### Constraints
@@ -94,11 +99,11 @@ Show notes from both project and global scopes.
 
 ### Steps
 
-1. Read `.planning/NOTES.md` (if exists) — these are "project" notes
-2. Read `~/.claude/notes.md` (if exists) — these are "global" notes
-3. Parse entries: lines matching `^- \[` are notes
-4. Exclude lines containing `[promoted]` from active counts (but still show them, dimmed)
-5. Number all active entries sequentially starting at 1, using plain integers (1, 2, 3...) for display (across both scopes)
+1. Glob `.planning/notes/*.md` (if directory exists) — these are "project" notes
+2. Glob `~/.claude/notes/*.md` (if directory exists) — these are "global" notes
+3. For each file, read frontmatter to get `date` and `promoted` status
+4. Exclude files where `promoted: true` from active counts (but still show them, dimmed)
+5. Sort by date, number all active entries sequentially starting at 1
 6. If total active entries > 20, show only the last 10 with a note about how many were omitted
 
 ### Display Format
@@ -106,18 +111,18 @@ Show notes from both project and global scopes.
 ```
 Notes:
 
-Project (.planning/NOTES.md):
+Project (.planning/notes/):
   1. [2026-02-08 14:32] refactor the hook system to support async validators
   2. [promoted] [2026-02-08 14:40] add rate limiting to the API endpoints
   3. [2026-02-08 15:10] consider adding a --dry-run flag to build
 
-Global (~/.claude/notes.md):
+Global (~/.claude/notes/):
   4. [2026-02-08 10:00] cross-project idea about shared config
 
 {count} active note(s). Use `/pbr:note promote <N>` to convert to a todo.
 ```
 
-If a scope has no file or no entries, show: `(no notes)`
+If a scope has no directory or no entries, show: `(no notes)`
 
 ---
 
@@ -130,10 +135,10 @@ 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 (everything after the timestamp)
+7. Extract the note text from the source file (body after frontmatter)
 8. Create `.planning/todos/pending/{id}.md`:
 
 ```yaml
@@ -159,34 +164,18 @@ Promoted from quick note captured on {original date}.
 - [ ] {primary criterion derived from note text}
 ```
 
-9. Mark the original note as promoted: replace `- [` with `- [promoted] [` on that line
+9. Mark the source note file as promoted: update its frontmatter to `promoted: true`
 10. Confirm: `Promoted note {N} to todo {id}: {note text}`
 
 ---
 
-## NOTES.md Format Reference
-
-```markdown
-# Notes
-
-Quick captures from `/pbr:note`. Ideas worth remembering.
-
----
-
-- [2026-02-08 14:32] refactor the hook system to support async validators
-- [promoted] [2026-02-08 14:40] add rate limiting to the API endpoints
-- [2026-02-08 15:10] consider adding a --dry-run flag to build
-```
-
----
-
 ## Edge Cases
 
 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.md` — works in any directory
-3. **Promote without project**: Warns that todos require `.planning/`, suggests `/pbr:begin`
+2. **No `.planning/`**: Falls back to global `~/.claude/notes/` — works in any directory
+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. **Missing newline**: Always ensure trailing newline before appending
+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
 7. **Promote already-promoted**: Tell user "Note {N} is already promoted" and stop
 8. **Empty note text after stripping flags**: Treat as `list` subcommand
@@ -229,3 +218,4 @@ Note {N} not found. Valid range: 1-{max}.
 4. **DO NOT** create `.planning/` if it doesn't exist — fall back to global
 5. **DO NOT** number promoted notes in the active count (but still display them)
 6. **DO NOT** over-format the confirmation — one line is enough
+7. **DO NOT** use a flat NOTES.md file — always use individual files in notes directory

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

@@ -11,14 +11,14 @@ allowed-tools: Read, Write, Bash, Glob
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PAUSING SESSION
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PAUSING SESSION                            ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 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,7 +112,7 @@ 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"
@@ -121,17 +121,25 @@ Determine the logical next action (same routing logic as `/pbr:status`):
 
 ### Step 4: Write .continue-here.md
 
+**CRITICAL: Write pause state NOW before displaying confirmation. Do NOT skip this step.**
+
 Write the handoff file to the current phase directory:
 
 **Path:** `.planning/phases/{NN}-{phase-name}/.continue-here.md`
 
 **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.
 
 ### 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}`
+
+Then update the Session Continuity section of STATE.md:
 
 ```markdown
 ### Session Continuity
@@ -167,25 +175,27 @@ git commit -m "wip(planning): save session state — phase {N} plan {M}"
 Display branded confirmation:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► SESSION SAVED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SESSION SAVED ✓                            ║
+╚══════════════════════════════════════════════════════════════╝
 
 Position: Phase {N} — {phase name}, Plan {M}
 Completed: {count} plans this session
 Remaining: {count} plans in this phase
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Resume in your next session**
 
-`/pbr:resume`
+`/pbr:resume-work`
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 ---