@sienklogic/plan-build-run 2.18.1 → 2.19.1

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

@@ -0,0 +1,206 @@
+---
+name: release
+description: "Generate or update changelog and release notes from project history."
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+argument-hint: "[version] [--draft|--update|--clean]"
+---
+<!-- markdownlint-disable MD012 MD046 -->
+
+**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 tokens. Begin executing Step 1 immediately.**
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► RELEASE                                    ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Then proceed to Step 1.
+
+# /pbr:release — Changelog & Release Notes
+
+You are running the **release** skill. This skill generates polished, user-facing changelog entries from project history — milestone summaries, commit logs, and planning artifacts. It produces Keep a Changelog format with bolded feature names and impact-focused descriptions.
+
+This skill runs **inline** (no subagents).
+
+---
+
+## Argument Parsing
+
+Parse `$ARGUMENTS`:
+
+```
+$ARGUMENTS format: [version] [--flag]
+
+Examples:
+  ""                 → mode=draft, version=auto-detect from package.json
+  "v2.2.0"           → mode=draft, version=v2.2.0
+  "--draft"          → mode=draft, version=auto-detect
+  "--update v2.1.0"  → mode=update, version=v2.1.0
+  "--clean"          → mode=clean, run clean-changelog.js on existing CHANGELOG.md
+```
+
+**Modes:**
+- `draft` (default) — Generate a new changelog entry for unreleased work
+- `update` — Regenerate the entry for an existing version
+- `clean` — Run the scope-cleaning script on the current CHANGELOG.md
+
+---
+
+## Mode: `clean`
+
+Run the changelog cleaning script to strip internal scopes from existing entries:
+
+```bash
+node scripts/clean-changelog.js --write
+```
+
+Display the result and exit.
+
+---
+
+## Mode: `draft` or `update`
+
+### Step 1 — Gather Context
+
+1. **Determine version:**
+   - If provided: use it (auto-prefix `v` if missing)
+   - If not: read `package.json` version field and use that
+
+2. **Read current CHANGELOG.md** (if exists):
+   - Parse existing version entries to avoid duplicating
+   - If `update` mode: find the section for the target version to replace
+
+3. **Determine the change range:**
+
+   For `draft` mode (unreleased work):
+   - Find the most recent git tag: `git describe --tags --abbrev=0`
+   - Collect commits since that tag: `git log {tag}..HEAD --oneline`
+   - Read any milestone archive SUMMARY.md files created since the tag
+
+   For `update` mode (existing version):
+   - Find the tag for the target version
+   - Find the tag before it
+   - Collect commits between those two tags
+   - Read the milestone archive for that version if it exists
+
+### Step 2 — Read Summaries
+
+Read SUMMARY.md files from the relevant phases (archived or active):
+
+- Check `.planning/milestones/` for version-matched archives
+- Check `.planning/phases/` for active phase summaries
+- Extract `provides`, `key_files`, and `key_decisions` fields from frontmatter
+- Read commit messages for additional context
+
+### Step 3 — Draft the Entry
+
+Generate a changelog entry in Keep a Changelog format:
+
+```markdown
+## [{version}] - {YYYY-MM-DD}
+
+### Added
+- **Feature name** — What it does and why it matters
+- **Another feature** — User-facing description
+
+### Changed
+- **Existing feature** — What changed and why
+
+### Fixed
+- **Bug description** — What was broken and how it's resolved
+```
+
+**Rules:**
+- Lead with user-visible impact, not implementation details
+- Group related commits into single entries (5 auth commits → one "Authentication" entry)
+- Use **bold feature names** with em-dash descriptions
+- No commit hashes in the changelog (they're in git, not in prose)
+- No internal scopes (phase-plan numbers, TDD markers, quick-NNN)
+- Omit empty sections (no `### Changed` if nothing changed)
+- End with: `Install/upgrade: \`npx @sienklogic/plan-build-run@latest\``
+
+### Step 4 — User Review
+
+Present the draft to the user:
+
+Use AskUserQuestion:
+```
+question: "Here's the draft changelog for {version}. Review and approve?"
+header: "Changelog Draft"
+options:
+  - label: "Looks good"        description: "Write this to CHANGELOG.md"
+  - label: "Edit"              description: "I'll provide corrections or additions"
+  - label: "Regenerate"        description: "Try again with different grouping"
+  - label: "Cancel"            description: "Don't write anything"
+```
+
+- If "Looks good": proceed to Step 5
+- If "Edit" or "Other": apply corrections, present again
+- If "Regenerate": re-draft with user feedback incorporated, present again
+- If "Cancel": exit without writing
+
+### Step 5 — Write
+
+1. **Write to CHANGELOG.md:**
+   - For `draft`: insert the new entry after the file header, before existing versions
+   - For `update`: replace the existing entry for that version
+
+2. **Commit:**
+   ```bash
+   git add CHANGELOG.md
+   git commit -m "docs: update changelog for {version}"
+   ```
+
+3. **Update GitHub Release** (if tag exists):
+
+   Check if a GitHub release exists for this version:
+   ```bash
+   gh release view {tag} --json tagName 2>/dev/null
+   ```
+
+   If it exists, offer to update the release body:
+
+   Use AskUserQuestion:
+   ```
+   question: "A GitHub release exists for {tag}. Update its release notes too?"
+   header: "GitHub Release"
+   options:
+     - label: "Yes"    description: "Update the GitHub release body with the new notes"
+     - label: "No"     description: "Only update CHANGELOG.md"
+   ```
+
+   If "Yes":
+   ```bash
+   gh release edit {tag} --notes-file - <<< "{changelog entry}"
+   ```
+
+### Step 6 — Confirm
+
+Display:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► CHANGELOG UPDATED                          ║
+╚══════════════════════════════════════════════════════════════╝
+
+Version: {version}
+Sections: {Added: N, Changed: N, Fixed: N}
+File: CHANGELOG.md
+
+{if GitHub release updated: "GitHub release also updated."}
+```
+
+---
+
+## Anti-Patterns
+
+1. **DO NOT** include commit hashes in changelog entries — this is user-facing prose
+2. **DO NOT** use internal scopes (01-01, quick-003) — use descriptive feature names
+3. **DO NOT** list every commit individually — group related work into features
+4. **DO NOT** write the changelog without user confirmation via AskUserQuestion
+5. **DO NOT** include TDD markers (RED, GREEN, REFACTOR) in descriptions
+6. **DO NOT** skip empty section removal — no `### Changed` with no entries

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

@@ -18,7 +18,7 @@ allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 
 Then proceed to Step 1.
 
-# /pbr:resume — Resume Previous Session
+# /pbr:resume-work — Resume Previous Session
 
 You are running the **resume** skill. Your job is to find the last pause point, restore context for the user, and suggest the next action so they can continue seamlessly.
 
@@ -57,28 +57,20 @@ Before presenting the standard resume view, check:
 
 ### Auto-Reconcile STATE.md Against Filesystem
 
-On every resume, reconcile STATE.md claims against filesystem reality. This catches both corruption and drift from interrupted operations.
+On every resume, reconcile STATE.md claims against filesystem reality:
 
-**Step 1: Detect discrepancies** — Compare STATE.md values against the filesystem:
-
-| STATE.md Claim | Filesystem Check |
-|----------------|------------------|
-| Phase number | Does `.planning/phases/{NN}-*/` exist? |
-| Plan count | Count `*-PLAN.md` files in the phase directory |
-| Completed plans | Count `SUMMARY.md` files in the phase directory |
-| Status "verified" | Does `VERIFICATION.md` with `status: passed` exist? |
-| Status "building" | Are there PLAN.md files without SUMMARY.md? |
-| Progress percentage | Recalculate from completed phases / total phases |
-
-**Step 2: Classify** — If any discrepancy found:
-- **Obvious corruption** (duplicate headers, impossible percentages, phase directory missing): flag as corruption
-- **Stale data** (plan count wrong, status outdated): flag as drift
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state check-progress
+```
 
-**Step 3: Repair** —
-- For **corruption**: Present repair and ask for confirmation: "STATE.md appears corrupted. Based on the file system, you're at Phase {N} with {M}/{T} plans complete. Should I repair STATE.md?"
-- For **drift**: Auto-repair silently and note: "Updated STATE.md to match filesystem (plan count {old}→{new}, status {old}→{new})."
+Parse the JSON output:
+- If `discrepancies` array is empty: proceed silently (state is consistent)
+- If discrepancies found with `severity: "corruption"`: present repair and ask for confirmation via AskUserQuestion
+- If discrepancies found with `severity: "drift"`: auto-repair silently and note the changes
 - Log all repairs to `.planning/logs/events.jsonl` with category `state-reconcile`
 
+If the CLI fails, display a branded ERROR box: "Failed to check state consistency." and proceed with resume (non-blocking — state reconciliation is advisory).
+
 ---
 
 ## Flow
@@ -87,16 +79,118 @@ On every resume, reconcile STATE.md claims against filesystem reality. This catc
 
 Read `.planning/STATE.md` for the last known position.
 
-**Extract:**
+**Extract from frontmatter:**
 - Current phase and plan
+- `session_last` — when the last session ended (ISO timestamp)
+- `session_stopped_at` — brief description of where work stopped
+- `session_resume` — path to .continue-here.md file
+
+**If `session_last` exists in frontmatter**, display it immediately before any other output:
+```
+Last session: {session_last}
+Stopped at: {session_stopped_at}
+```
+This gives the user instant context before the full resume analysis runs.
+
+**Also extract from body:**
 - Session Continuity section (if exists):
   - Last paused date
   - Continue file location
   - Suggested next action
 
+**CRITICAL -- DO NOT SKIP: After successful resume**, clear `session_stopped_at` from STATE.md frontmatter (set to empty string or remove) to indicate the session has been resumed. Keep `session_last` and `session_resume` intact for reference.
+
 **If STATE.md doesn't exist:**
 - Go to **Recovery Flow** (Step 4)
 
+### Step 1b: Check for HANDOFF.json and WAITING.json
+
+**Before searching for .continue-here.md**, check for structured state files:
+
+#### HANDOFF.json (Machine-Readable Pause State)
+
+Check if `.planning/HANDOFF.json` exists:
+- If found, parse it and extract structured resume context:
+  - Display: phase, plan, current task, next action, blockers, human actions pending
+  - Use this data to populate the resume display (it's more reliable than .continue-here.md)
+  - After successful resume, **delete HANDOFF.json** (one-shot consumption)
+  - Continue to Step 3a (Normal Resume) using the HANDOFF.json data alongside .continue-here.md
+- If not found, proceed normally to Step 2
+
+#### WAITING.json (External Wait State)
+
+Check if `.planning/WAITING.json` exists:
+- If found, parse it and display the waiting state:
+  ```
+  Project is in WAITING state
+  Reason: {reason}
+  Waiting since: {created_at}
+  Expected duration: {expected_duration}
+  ```
+- Offer to resume: "The project was waiting on an external action. If the action is complete, run `/pbr:resume-work` to clear the waiting state and continue."
+- If the user confirms the wait is resolved, delete WAITING.json and proceed with normal resume
+- If not found, proceed normally to Step 2
+
+#### Autonomous State (.autonomous-state.json)
+
+Check if `.planning/.autonomous-state.json` exists:
+
+- If found, parse it and extract:
+  - `current_phase` -- the phase the autonomous run was on when interrupted
+  - `completed_phases` -- list of phases already completed
+  - `branch_state` -- map of phase -> branch name (may be empty `{}`)
+  - `started_at` -- when the run began
+  - `failed_phase` / `error` -- whether the run failed vs. was interrupted
+- Display a summary block:
+
+```text
+Autonomous Run Detected
+Started: {started_at}
+Completed phases: {completed_phases list, or "none"}
+Current phase: {current_phase}
+{If branch_state non-empty:}
+Active branch: {branch for current_phase, if present}
+{If failed_phase non-null:}
+Failed at phase: {failed_phase} — {error}
+```
+
+- Use AskUserQuestion to offer resumption:
+
+```text
+Use AskUserQuestion:
+  question: "An autonomous run was interrupted at Phase {current_phase}. Continue it?"
+  header: "Autonomous Resume"
+  options:
+    - label: "Continue autonomous run from Phase {current_phase}"
+      description: "Run /pbr:autonomous --from {current_phase}"
+    - label: "Resume manually (normal resume flow)"
+      description: "Continue with the standard resume process"
+    - label: "Discard autonomous state"
+      description: "Delete .autonomous-state.json and start fresh"
+  multiSelect: false
+```
+
+- If user selects **Continue autonomous run**: display `Run: /pbr:autonomous --from {current_phase}` and stop (do not proceed with normal resume flow)
+- If user selects **Resume manually**: proceed with normal resume flow (Step 2 onward), keep .autonomous-state.json intact
+- If user selects **Discard autonomous state**: delete `.planning/.autonomous-state.json`, then proceed with normal resume flow
+- If `.autonomous-state.json` does NOT exist: skip this block entirely, proceed with Step 2
+
+### Step 1c: Read Latest Session Snapshot
+
+Check if `.planning/sessions/snapshots/` directory exists:
+- List files matching `*-snapshot.md`, sorted alphabetically (newest last).
+- If no snapshot files exist, skip this step.
+- Read the LAST file (most recent snapshot).
+- Parse the frontmatter `timestamp` field.
+- If the timestamp is older than 48 hours from now, skip (snapshot is stale).
+- Extract these sections from the snapshot body:
+  - **Working Set** -- files that were being edited
+  - **Current Approach** -- what the previous session was doing
+  - **Pending Decisions** -- unresolved decisions
+  - **Open Questions** -- open questions from prior session
+
+Store the extracted snapshot data for use in Step 3a/3b display. Do NOT display anything yet.
+
 ### Step 2: Search for .continue-here.md Files
 
 Search for `.continue-here.md` files across all phase directories:
@@ -109,6 +203,7 @@ Search for `.continue-here.md` files across all phase directories:
 - This is the resume point. Go to **Normal Resume** (Step 3a).
 
 **If multiple found:**
+**CRITICAL -- DO NOT SKIP**: Present the following choice to the user via AskUserQuestion before proceeding:
 Use the **pause-point-select** pattern (see `skills/shared/gate-prompts.md`):
 
 Use AskUserQuestion:
@@ -136,13 +231,13 @@ Use the selected pause point for the rest of the resume flow.
 ### Step 3a: Normal Resume (from .continue-here.md)
 
 1. Read the `.continue-here.md` file completely
-2. Parse all sections:
-   - Position (phase, plan, status)
-   - Completed work
-   - Remaining work
-   - Decisions
-   - Blockers
-   - Next steps
+2. Parse sections. If the file contains `<current_state>`, parse XML sections. Otherwise, fall back to parsing markdown headers (`## Position`, `## Completed This Session`, etc.) for backward compatibility with old-format files.
+   - `<current_state>` -- phase, plan, status, branch, working files
+   - `<completed_work>` -- what was done last session
+   - `<remaining_work>` -- what's left in this phase
+   - `<decisions_made>` -- key decisions that affect future work
+   - `<context>` -- approach, reasoning, things to watch out for
+   - `<next_action>` -- the single most important next step with exact command
 
 3. Display the resume context using the branded banner:
 
@@ -160,6 +255,15 @@ Status: {status}
 Completed last session:
 {bulleted list of completed work}
 
+{If snapshot loaded and not stale:}
+Last session context:
+- Working on: {files from Working Set, max 5}
+- Approach: {Current Approach text, truncated to 150 chars}
+{If pending decisions exist:}
+- Pending decisions: {count} unresolved
+{If open questions exist:}
+- Open questions: {count} remaining
+
 Remaining in this phase:
 {bulleted list of remaining plans}
 
@@ -167,6 +271,10 @@ Remaining in this phase:
 Key decisions:
 {bulleted list of decisions}
 
+{If context section has content:}
+Session context:
+{approach and reasoning from <context> section}
+
 {If blockers exist:}
 Blockers:
 {bulleted list of blockers}
@@ -178,7 +286,7 @@ Blockers:
    - Check git log to verify commits mentioned in completed work
    - If anything is inconsistent, warn: "Some state has changed since the pause. {details}"
 
-5. Present the next action from the continue-here file.
+5. Present the next action from the continue-here file. When a `<next_action>` section exists with a `Command:` field, prefer that over inferring the next action from state -- the pause skill captured the exact command to run.
 
 **If only one clear next action exists**, present it with branded routing:
 ```
@@ -197,7 +305,9 @@ Blockers:
 
 ```
 
-**If multiple reasonable actions exist** (e.g., the continue-here suggests one thing but the filesystem state suggests another), use the **action-routing** pattern (see `skills/shared/gate-prompts.md`):
+**If multiple reasonable actions exist** (e.g., the continue-here suggests one thing but the filesystem state suggests another):
+**CRITICAL -- DO NOT SKIP**: Present the following choice to the user via AskUserQuestion before proceeding:
+Use the **action-routing** pattern (see `skills/shared/gate-prompts.md`):
 
 Use AskUserQuestion:
   question: "How would you like to proceed?"
@@ -205,7 +315,7 @@ Use AskUserQuestion:
   options:
     - label: "{continue-here suggestion}"   description: "Resume from pause point"
     - label: "{filesystem-inferred action}"  description: "Based on current state"
-    - label: "Show status"                   description: "Run /pbr:status for full overview"
+    - label: "Show status"                   description: "Run /pbr:progress for full overview"
     - label: "Something else"                description: "Enter a different command"
   multiSelect: false
 
@@ -233,22 +343,32 @@ Resuming from STATE.md (no pause file found)
 Position: Phase {N} -- {name}
 Progress: {completed}/{total} plans complete
 
+{If snapshot loaded and not stale:}
+Last session context:
+- Working on: {files from Working Set, max 5}
+- Approach: {Current Approach text, truncated to 150 chars}
+{If pending decisions exist:}
+- Pending decisions: {count} unresolved
+{If open questions exist:}
+- Open questions: {count} remaining
+
 {Plans with summaries listed as complete}
 {Plans without summaries listed as remaining}
 
-Note: No detailed pause context available. Run `/pbr:status` for a full overview.
+Note: No detailed pause context available. Run `/pbr:progress` for a full overview.
 ```
 
 5. Suggest the next action based on phase state using the **action-routing** pattern:
 
+**CRITICAL -- DO NOT SKIP**: Present the following choice to the user via AskUserQuestion before proceeding:
 Use AskUserQuestion:
   question: "What would you like to do next?"
   header: "Next Step"
   options: (build dynamically from phase state)
-    - label: "/pbr:build {N}"       description: "Continue building (plans remaining)"
-    - label: "/pbr:review {N}"      description: "Review completed phase"
-    - label: "/pbr:plan {N} --gaps" description: "Fix verification gaps"
-    - label: "/pbr:plan {N+1}"      description: "Plan the next phase"
+    - label: "/pbr:execute-phase {N}"       description: "Continue building (plans remaining)"
+    - label: "/pbr:verify-work {N}"      description: "Review completed phase"
+    - label: "/pbr:plan-phase {N} --gaps" description: "Fix verification gaps"
+    - label: "/pbr:plan-phase {N+1}"      description: "Plan the next phase"
   multiSelect: false
 
 Show only the options that apply to the current state (1-3 real options + "Something else").
@@ -266,7 +386,7 @@ When neither .continue-here.md nor STATE.md position data exists:
 
      No Plan-Build-Run project found.
 
-     **To fix:** Run `/pbr:begin` to start a new project, or `/pbr:scan` to analyze an existing codebase.
+     **To fix:** Run `/pbr:new-project` to start a new project, or `/pbr:map-codebase` to analyze an existing codebase.
      ```
    - Stop here.
 
@@ -303,7 +423,7 @@ Phase {N}: {name}
 - {X} of {Y} plans completed
 - Last activity: {date from most recent SUMMARY.md or git log}
 
-Suggested: Run `/pbr:status` for a full overview, then choose your next action.
+Suggested: Run `/pbr:progress` for a full overview, then choose your next action.
 ```
 
 ---
@@ -314,13 +434,14 @@ After displaying context, route to the appropriate action:
 
 | Situation | Suggested Action |
 |-----------|-----------------|
-| Mid-phase, plans remaining | `/pbr:build {N}` (executor will skip completed plans) |
-| Phase complete, not reviewed | `/pbr:review {N}` |
-| Phase reviewed, has gaps | `/pbr:plan {N} --gaps` |
-| Phase complete and verified | `/pbr:plan {N+1}` |
-| Between milestones | `/pbr:milestone new` |
+| Autonomous run interrupted | `/pbr:autonomous --from {N}` |
+| Mid-phase, plans remaining | `/pbr:execute-phase {N}` (executor will skip completed plans) |
+| Phase complete, not reviewed | `/pbr:verify-work {N}` |
+| Phase reviewed, has gaps | `/pbr:plan-phase {N} --gaps` |
+| Phase complete and verified | `/pbr:plan-phase {N+1}` |
+| Between milestones | `/pbr:new-milestone` |
 | Active debug session | `/pbr:debug` (will offer to resume) |
-| Pending todos exist | Mention: "Also {count} pending todos. `/pbr:todo list`" |
+| Pending todos exist | Mention: "Also {count} pending todos. `/pbr:check-todos`" |
 
 ---
 
@@ -350,17 +471,19 @@ For each plan file in the current phase:
 
 If .continue-here.md is more than 7 days old:
 - Warn: "This pause point is {N} days old. The codebase may have changed."
-- Suggest: "Run `/pbr:status` to verify the current state before continuing."
+- Suggest: "Run `/pbr:progress` to verify the current state before continuing."
 
 ---
 
+Reference: `skills/shared/error-reporting.md` for branded error output patterns.
+
 ## Edge Cases
 
 ### .continue-here.md references deleted files
 - Warn about each missing file
 - Attempt to find equivalent files (renamed, moved)
 - If phase directory is gone: "Phase {N} directory was removed. This pause point is invalid."
-- Suggest `/pbr:status` for recovery
+- Suggest `/pbr:progress` for recovery
 
 ### Git history doesn't match .continue-here.md
 - Commits referenced in the handoff may have been rebased, amended, or rolled back
@@ -387,7 +510,7 @@ If .continue-here.md is more than 7 days old:
 
   Project was initialized but no work has been done.
 
-  **To fix:** Run `/pbr:plan 1` to start planning, or `/pbr:discuss 1` to talk through the first phase.
+  **To fix:** Run `/pbr:plan-phase 1` to start planning, or `/pbr:discuss-phase 1` to talk through the first phase.
   ```
 
 ---