@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/plan-build-run/skills/resume/SKILL.md

@@ -0,0 +1,499 @@
+---
+name: resume
+description: "Pick up where you left off. Restores context and suggests next action."
+allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+---
+
+**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.**
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► RESUMING SESSION                           ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Then proceed to Step 1.
+
+# /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.
+
+This skill runs **inline** (no Task delegation).
+
+---
+
+## Core Principle
+
+**Get the user back to work in under 30 seconds.** Read the handoff, show what matters, and suggest the next command. Don't make them re-discover their own project state.
+
+---
+
+## Resumption Priority Hierarchy
+
+When resuming, scan for conditions in this priority order. Handle the HIGHEST priority item first:
+
+```
+1. 🔴 UAT-BLOCKER (diagnosed) → Fix must come first
+2. 🟡 Interrupted agent → Resume agent from checkpoint
+3. 🟡 .continue-here checkpoint → Resume from checkpoint
+4. 🟡 Incomplete plan → Complete plan execution
+5. 🟢 Phase complete → Transition to next phase
+6. 🟢 Ready to plan/execute → Normal workflow
+```
+
+### Scanning for Priority Items
+
+Before presenting the standard resume view, check:
+
+1. **UAT Blockers**: Search for VERIFICATION.md files with `status: gaps_found` in any phase. If found and gaps are marked as blocking, surface them first: "Phase {N} has {count} blocking verification gaps. These should be fixed before continuing."
+
+2. **Interrupted Agents**: Check for `.checkpoint-manifest.json` files in phase directories with `checkpoints_pending` entries. These indicate a build was interrupted mid-checkpoint.
+
+3. **Stale .continue-here.md**: If the file references commits that don't exist in git log, warn about state corruption.
+
+### 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.
+
+**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
+
+**CRITICAL (no hook) -- DO NOT SKIP: Repair STATE.md when discrepancies are found.**
+
+**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})."
+- Log all repairs to `.planning/logs/events.jsonl` with category `state-reconcile`
+
+---
+
+## Flow
+
+### Step 1: Read STATE.md
+
+Read `.planning/STATE.md` for the last known position.
+
+**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 2: Search for .continue-here.md Files
+
+Search for `.continue-here.md` files across all phase directories:
+
+```
+.planning/phases/**/.continue-here.md
+```
+
+**If exactly one found:**
+- This is the resume point. Go to **Normal Resume** (Step 3a).
+
+**If multiple found:**
+Use the **pause-point-select** pattern (see `skills/shared/gate-prompts.md`):
+
+Use AskUserQuestion:
+  question: "Found multiple pause points. Which would you like to resume?"
+  header: "Resume"
+  options:
+    - label: "Phase {A}"  description: "Paused {date}, {brief context}"
+    - label: "Phase {B}"  description: "Paused {date}, {brief context}"
+    - label: "Phase {C}"  description: "Paused {date}, {brief context}"
+    - label: "Phase {D}"  description: "Paused {date}, {brief context}"
+  multiSelect: false
+
+Build options dynamically from discovered `.continue-here.md` files. Include phase name and pause date in each option. If more than 4 pause points exist, show the 4 most recent and replace the last option with:
+  - label: "Show earlier"  description: "See older pause points"
+
+When "Show earlier" is selected, re-prompt with the next batch of 4.
+
+Use the selected pause point for the rest of the resume flow.
+
+**If none found:**
+- Check STATE.md for position info
+- If STATE.md has position: go to **Inferred Resume** (Step 3b)
+- If STATE.md has no position: go to **Recovery Flow** (Step 4)
+
+### Step 3a: Normal Resume (from .continue-here.md)
+
+1. Read the `.continue-here.md` file completely
+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:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SESSION RESTORED ✓                         ║
+╚══════════════════════════════════════════════════════════════╝
+
+Resuming session from {pause date}
+
+Position: Phase {N} -- {name}
+Plan: {M} of {total}
+Status: {status}
+
+Completed last session:
+{bulleted list of completed work}
+
+Remaining in this phase:
+{bulleted list of remaining plans}
+
+{If decisions were made:}
+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}
+```
+
+4. Validate the resume point:
+   - Check that the phase directory still exists
+   - Check that the plan files mentioned still exist
+   - 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. 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:
+```
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**{explanation from continue-here}**
+
+`{suggested command}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+
+```
+
+**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`):
+
+Use AskUserQuestion:
+  question: "How would you like to proceed?"
+  header: "Next Step"
+  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:progress for full overview"
+    - label: "Something else"                description: "Enter a different command"
+  multiSelect: false
+
+**After user selects an option:**
+- Display "Run: `/pbr:{action} {args}`" so the user can execute it
+- This skill does not auto-execute — it suggests and the user acts
+
+6. Clean up:
+   - **DO NOT** delete the .continue-here.md file yet
+   - It will be naturally superseded when the next pause happens
+   - Or it can be manually removed after the user confirms they're back on track
+
+### Step 3b: Inferred Resume (from STATE.md only)
+
+When there's no .continue-here.md but STATE.md has position info:
+
+1. Read STATE.md position
+2. Scan the current phase directory for plan and summary files
+3. Determine what's complete vs. remaining
+4. Present a reduced resume context:
+
+```
+Resuming from STATE.md (no pause file found)
+
+Position: Phase {N} -- {name}
+Progress: {completed}/{total} plans complete
+
+{Plans with summaries listed as complete}
+{Plans without summaries listed as remaining}
+
+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:
+
+Use AskUserQuestion:
+  question: "What would you like to do next?"
+  header: "Next Step"
+  options: (build dynamically from phase state)
+    - 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").
+
+### Step 4: Recovery Flow
+
+When neither .continue-here.md nor STATE.md position data exists:
+
+1. Check if `.planning/` directory exists at all
+   - If no, display:
+     ```
+     ╔══════════════════════════════════════════════════════════════╗
+     ║  ERROR                                                       ║
+     ╚══════════════════════════════════════════════════════════════╝
+
+     No Plan-Build-Run project found.
+
+     **To fix:** Run `/pbr:new-project` to start a new project, or `/pbr:map-codebase` to analyze an existing codebase.
+     ```
+   - Stop here.
+
+2. If `.planning/` exists, scan for any project state:
+   - Check for ROADMAP.md
+   - Check for any phase directories
+   - Check for any SUMMARY.md files
+   - Check for config.json
+
+3. If some state exists:
+
+```
+Found a Plan-Build-Run project but no pause point.
+
+Project has:
+- {count} phases in ROADMAP.md
+- {count} phase directories
+- {count} completed plans (SUMMARY.md files)
+
+Attempting to determine position...
+```
+
+4. Infer position:
+   - Find the last phase with SUMMARY.md files
+   - Check if all plans in that phase have summaries
+   - Determine the next action
+
+5. Present recovery status:
+
+```
+Best guess for current position:
+
+Phase {N}: {name}
+- {X} of {Y} plans completed
+- Last activity: {date from most recent SUMMARY.md or git log}
+
+Suggested: Run `/pbr:progress` for a full overview, then choose your next action.
+```
+
+---
+
+## Resume Routing
+
+After displaying context, route to the appropriate action:
+
+| Situation | Suggested Action |
+|-----------|-----------------|
+| 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:check-todos`" |
+
+---
+
+## State Validation
+
+When resuming, validate that the project state is consistent:
+
+### Git State Check
+
+```bash
+git status --short
+```
+
+If there are uncommitted changes:
+- Warn: "There are uncommitted changes in the working directory."
+- List the changed files
+- Suggest: "These may be from an interrupted build. Review them before continuing."
+
+### Plan-Summary Consistency
+
+For each plan file in the current phase:
+- Check if SUMMARY.md exists
+- If SUMMARY.md exists, check its status field
+- If status is `partial` or `failed`, warn
+
+### Continuation Context Freshness
+
+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: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:progress` for recovery
+
+### Git history doesn't match .continue-here.md
+- Commits referenced in the handoff may have been rebased, amended, or rolled back
+- Warn: "Some commits referenced in the pause file couldn't be found in git history."
+- Don't treat this as fatal — the file system state matters more than commit hashes
+
+### User made changes between sessions (outside Plan-Build-Run)
+- The user may have manually edited files, committed changes, or modified configs
+- These changes won't be reflected in .continue-here.md
+- Check git log for commits not referenced in the handoff
+- If found: "Found {N} commits since the last pause that aren't tracked in the handoff."
+
+### Multiple users / branches
+- If git branch has changed since the pause:
+  - Warn: "You're on branch `{current}` but the pause was on `{paused-branch}`."
+  - Suggest switching branches or starting fresh
+
+### Empty project (just initialized)
+- If `.planning/` exists but only has config.json, display:
+  ```
+  ╔══════════════════════════════════════════════════════════════╗
+  ║  ERROR                                                       ║
+  ╚══════════════════════════════════════════════════════════════╝
+
+  Project was initialized but no work has been done.
+
+  **To fix:** Run `/pbr:plan-phase 1` to start planning, or `/pbr:discuss-phase 1` to talk through the first phase.
+  ```
+
+---
+
+## Anti-Patterns
+
+1. **DO NOT** auto-execute the suggested next action — just suggest it
+2. **DO NOT** delete .continue-here.md during resume — let the next pause overwrite it
+3. **DO NOT** modify any project files — resume is read-only (except cleaning up stale state)
+4. **DO NOT** assume .continue-here.md is accurate — always validate against the file system
+5. **DO NOT** show overwhelming amounts of detail — focus on actionable information
+6. **DO NOT** ignore inconsistencies — surface them as warnings
+7. **DO NOT** skip the git state check — uncommitted changes are important to surface
+8. **DO NOT** suggest multiple actions without clear priority — one primary suggestion