/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