pause

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.

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

   • Extract: current phase, current plan, progress, blockers
   • 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.
     

2. .planning/config.json — Project settings

   • Extract: project name, feature toggles

3. .planning/ROADMAP.md — Phase overview

   • 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:

   • 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

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}, Plan {M}
Completed: {count} plans this session
Remaining: {count} plans in this phase



╔══════════════════════════════════════════════════════════════╗
║  ▶ NEXT UP                                                   ║
╚══════════════════════════════════════════════════════════════╝

**Resume in your next session**

`/pbr:resume-work`

<sub>`/clear` first → fresh context window</sub>

---

What Gets Captured

Information	Source	Why It Matters
Phase + plan position	STATE.md	Know where to start
Completed work	SUMMARY.md files, git log	Know what's already done
Remaining work	Plan files without summaries	Know what's left
Decisions	CONTEXT.md, SUMMARY.md	Preserve user preferences
Blockers	STATE.md, verification files	Don't repeat failed approaches
Next steps	Routing logic	Immediate action on resume

---

Reference: skills/shared/error-reporting.md for branded error output patterns.

Edge Cases

No work was done this session

• Still write the continue-here file
• "Completed This Session" section says: "No plans completed (discussion/planning only)"
• Capture any decisions or context from the conversation

Multiple phases were worked on

• Write .continue-here.md in the MOST RECENT phase directory
• Reference the other phases in the "Completed This Session" section
• Next steps should focus on the current position

Mid-task pause (executor was interrupted)

• Note which task was in progress
• Warn: "Task {name} was in progress when paused. It may need to be re-executed."
• Check git log to see if any partial commits exist

.continue-here.md already exists

• Always REPLACE the existing file entirely — never append
• Appending causes stale data from previous sessions to persist, which confuses resume
• The old .continue-here.md content is superseded by the current state
• No need to ask the user — the current session state is always more accurate

STATE.md doesn't exist

• Warn: "No STATE.md found. Creating a minimal pause file."
• Write .continue-here.md based on git log and file system scan only
• Don't try to update STATE.md

No git history (fresh project)

• Skip the git log step
• Estimate session work from file modification times
• Still write the continue-here file

---

Anti-Patterns

1. DO NOT include full file contents in .continue-here.md — keep it concise
2. DO NOT stage code files in the WIP commit — only planning docs
3. DO NOT skip the commit when planning.commit_docs is enabled — the WIP commit preserves the pause state in version control and ensures .continue-here.md is not lost if working tree changes occur
4. DO NOT write multiple .continue-here.md files — one per pause
5. DO NOT include sensitive information (API keys, passwords) in the handoff
6. DO NOT modify any code files — this skill only writes planning docs
7. DO NOT skip the "Next Steps" section — it's the most important part for resumption