pause

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 ► PAUSING SESSION                            ║
╚══════════════════════════════════════════════════════════════╝

Then proceed to Step 1.

/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.

This skill runs inline (no Task delegation).

Core Principle

Capture everything the next session needs to hit the ground running. The resume skill will read this file cold, with zero prior context. Write it as if you're handing off to a colleague who has never seen this project.

Flow

Step 1: Read Current State

Flag: --checkpoint

If $ARGUMENTS contains --checkpoint:

• Perform a lightweight state dump without full session analysis
• Write a minimal .continue-here.md with just: Position, git status, and suggested next action
• Skip the detailed "Completed This Session" analysis (saves time)
• Useful for quick manual checkpoints at any point

Read the following files to understand where things stand:

1. .planning/STATE.md — Current position
2. Extract: current phase, current plan, progress, blockers
3. If STATE.md doesn't exist, display:

``` ╔══════════════════════════════════════════════════════════════╗ ║ ERROR ║ ╚══════════════════════════════════════════════════════════════╝

No Plan-Build-Run project state found. Nothing to pause.

To fix: Run /pbr:new-project to initialize a project first. ```

1. .planning/config.json — Project settings
2. Extract: project name, feature toggles

1. .planning/ROADMAP.md — Phase overview
2. Extract: current phase name, total phases

Step 2: Determine Current Phase Directory

From STATE.md, get the current phase number and find its directory:

1. List directories in .planning/phases/
2. Match the current phase number to a directory
3. If no match: use the most recently modified phase directory

Step 3: Gather Session State

Collect the following information:

Current Position

• Phase number and name
• Plan number (if mid-phase) or "between plans"
• Status: in-progress, between-plans, between-phases, planning, reviewing

Work Completed This Session

Scan the current phase directory for SUMMARY.md files:

• Read each SUMMARY.md frontmatter
• Note which ones were created/modified recently (check timestamps or git log)
• For recently completed plans: extract the plan name and brief status

Also check git log for recent commits:

git log --oneline -20 --since="8 hours ago"

This gives a reasonable window for "this session's work."

Remaining Work

Scan for plan files without corresponding SUMMARY.md files:

• These are plans that haven't been executed yet
• List them with brief descriptions from their frontmatter

Key Decisions Made

Check for:

• Recent CONTEXT.md files (from /pbr:discuss-phase)
• Key decisions in recent SUMMARY.md files
• Any deviations noted in summaries

Blockers or Concerns

From STATE.md blockers section and any:

• Failed verifications
• Checkpoint stops
• Active debug sessions
• Unresolved issues noted in summaries

What to Do Next

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.

Write the handoff file to the current phase directory:

Path: .planning/phases/{NN}-{phase-name}/.continue-here.md

Content:

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:
6. status: "paused"
7. created_at: current ISO timestamp
8. phase: number, slug, and name from STATE.md
9. plan: number, wave, current task, total tasks
10. next_action: the suggested next action from Step 3
11. blockers: any blockers from STATE.md or verification failures
12. human_actions_pending: any actions the user needs to take
13. completed_tasks: task descriptions already done in current plan
14. uncommitted_files: from git status --short
15. context_notes: mental context about current approach and reasoning

CRITICAL: Write HANDOFF.json NOW. This file is required for session resumption.

1. 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

CRITICAL -- DO NOT SKIP: Update STATE.md via CLI.

pbr-tools state record-session --stopped-at "{brief description of current work}"

This updates STATE.md frontmatter (session_last, session_stopped_at, session_resume, last_command, last_activity) and the Session Continuity body section atomically.

Also update the session_resume pointer:

pbr-tools state update last_command "/pbr:pause-work"

If the CLI fails, display a branded ERROR box: "Failed to update STATE.md session state." and stop.

Step 6: Commit as WIP

Reference: skills/shared/commit-planning-docs.md for the standard commit pattern.

If planning.commit_docs: true in config.json:

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}"

Commit rules:

• Always use wip(planning): prefix for pause commits
• Include phase and plan numbers
• Stage only the continue-here and STATE.md files
• Do NOT stage any code changes (those should already be committed by the executor)

Step 7: Confirm to User

Display branded confirmation:

╔══════════════════════════════════════════════════════════════╗
║  PLAN-BUILD-RUN ► SESSION SAVED ✓                            ║
╚══════════════════════════════════════════════════════════════╝

Position: Phase {N} — {phase name