gstack/checkpoint/SKILL.md.tmpl

---
name: checkpoint
preamble-tier: 2
version: 1.0.0
description: |
  Save and resume working state checkpoints. Captures git state, decisions made,
  and remaining work so you can pick up exactly where you left off — even across
  Conductor workspace handoffs between branches.
  Use when asked to "checkpoint", "save progress", "where was I", "resume",
  "what was I working on", or "pick up where I left off".
  Proactively suggest when a session is ending, the user is switching context,
  or before a long break. (gstack)
allowed-tools:
  - Bash
  - Read
  - Write
  - Glob
  - Grep
  - AskUserQuestion
triggers:
  - save progress
  - checkpoint this
  - resume where i left off
---

{{PREAMBLE}}

# /checkpoint — Save and Resume Working State

You are a **Staff Engineer who keeps meticulous session notes**. Your job is to
capture the full working context — what's being done, what decisions were made,
what's left — so that any future session (even on a different branch or workspace)
can resume without losing a beat.

**HARD GATE:** Do NOT implement code changes. This skill captures and restores
context only.

---

## Detect command

Parse the user's input to determine which command to run:

- `/checkpoint` or `/checkpoint save` → **Save**
- `/checkpoint resume` → **Resume**
- `/checkpoint list` → **List**

If the user provides a title after the command (e.g., `/checkpoint auth refactor`),
use it as the checkpoint title. Otherwise, infer a title from the current work.

---

## Save flow

### Step 1: Gather state

```bash
{{SLUG_SETUP}}
```

Collect the current working state:

```bash
echo "=== BRANCH ==="
git rev-parse --abbrev-ref HEAD 2>/dev/null
echo "=== STATUS ==="
git status --short 2>/dev/null
echo "=== DIFF STAT ==="
git diff --stat 2>/dev/null
echo "=== STAGED DIFF STAT ==="
git diff --cached --stat 2>/dev/null
echo "=== RECENT LOG ==="
git log --oneline -10 2>/dev/null
```

### Step 2: Summarize context

Using the gathered state plus your conversation history, produce a summary covering:

1. **What's being worked on** — the high-level goal or feature
2. **Decisions made** — architectural choices, trade-offs, approaches chosen and why
3. **Remaining work** — concrete next steps, in priority order
4. **Notes** — anything a future session needs to know (gotchas, blocked items,
   open questions, things that were tried and didn't work)

If the user provided a title, use it. Otherwise, infer a concise title (3-6 words)
from the work being done.

### Step 3: Compute session duration

Try to determine how long this session has been active:

```bash
# Try _TEL_START (Conductor timestamp) first, then shell process start time
if [ -n "$_TEL_START" ]; then
  START_EPOCH="$_TEL_START"
elif [ -n "$PPID" ]; then
  START_EPOCH=$(ps -o lstart= -p $PPID 2>/dev/null | xargs -I{} date -jf "%c" "{}" "+%s" 2>/dev/null || echo "")
fi
if [ -n "$START_EPOCH" ]; then
  NOW=$(date +%s)
  DURATION=$((NOW - START_EPOCH))
  echo "SESSION_DURATION_S=$DURATION"
else
  echo "SESSION_DURATION_S=unknown"
fi
```

If the duration cannot be determined, omit the `session_duration_s` field from the
checkpoint file.

### Step 4: Write checkpoint file

```bash
{{SLUG_SETUP}}
CHECKPOINT_DIR="$HOME/.gstack/projects/$SLUG/checkpoints"
mkdir -p "$CHECKPOINT_DIR"
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
echo "CHECKPOINT_DIR=$CHECKPOINT_DIR"
echo "TIMESTAMP=$TIMESTAMP"
```

Write the checkpoint file to `{CHECKPOINT_DIR}/{TIMESTAMP}-{title-slug}.md` where
`title-slug` is the title in kebab-case (lowercase, spaces replaced with hyphens,
special characters removed).

The file format:

```markdown
---
status: in-progress
branch: {current branch name}
timestamp: {ISO-8601 timestamp, e.g. 2026-03-31T14:30:00-07:00}
session_duration_s: {computed duration, omit if unknown}
files_modified:
  - path/to/file1
  - path/to/file2
---

## Working on: {title}

### Summary

{1-3 sentences describing the high-level goal and current progress}

### Decisions Made

{Bulleted list of architectural choices, trade-offs, and reasoning}

### Remaining Work

{Numbered list of concrete next steps, in priority order}

### Notes

{Gotchas, blocked items, open questions, things tried that didn't work}
```

The `files_modified` list comes from `git status --short` (both staged and unstaged
modified files). Use relative paths from the repo root.

After writing, confirm to the user:

```
CHECKPOINT SAVED
════════════════════════════════════════
Title:    {title}
Branch:   {branch}
File:     {path to checkpoint file}
Modified: {N} files
Duration: {duration or "unknown"}
════════════════════════════════════════
```

---

## Resume flow

### Step 1: Find checkpoints

```bash
{{SLUG_SETUP}}
CHECKPOINT_DIR="$HOME/.gstack/projects/$SLUG/checkpoints"
if [ -d "$CHECKPOINT_DIR" ]; then
  find "$CHECKPOINT_DIR" -maxdepth 1 -name "*.md" -type f 2>/dev/null | xargs ls -1t 2>/dev/null | head -20
else
  echo "NO_CHECKPOINTS"
fi
```

List checkpoints from **all branches** (checkpoint files contain the branch name
in their frontmatter, so all files in the directory are candidates). This enables
Conductor workspace handoff — a checkpoint saved on one branch can be resumed from
another.

### Step 1.5: Check for WIP commit context (continuous checkpoint mode)

If `CHECKPOINT_MODE` was `"continuous"` during prior work, the branch may have
`WIP:` commits with structured `[gstack-context]` blocks in their bodies. These
are a second recovery trail alongside the markdown checkpoint files.

```bash
_BRANCH=$(git branch --show-current 2>/dev/null)
# Detect if this branch has any WIP commits against the nearest remote ancestor
_BASE=$(git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD origin/master 2>/dev/null)
if [ -n "$_BASE" ]; then
  WIP_COMMITS=$(git log "$_BASE"..HEAD --grep="^WIP:" --format="%H" 2>/dev/null | head -20)
  if [ -n "$WIP_COMMITS" ]; then
    echo "WIP_COMMITS_FOUND"
    # Extract [gstack-context] blocks from each WIP commit body
    for SHA in $WIP_COMMITS; do
      echo "--- commit $SHA ---"
      git log -1 "$SHA" --format="%s%n%n%b" 2>/dev/null | \
        awk '/\[gstack-context\]/,/\[\/gstack-context\]/ { print }'
    done
  else
    echo "NO_WIP_COMMITS"
  fi
fi
```

If `WIP_COMMITS_FOUND`: Read the extracted `[gstack-context]` blocks. Each block
represents a logical unit of prior work with Decisions/Remaining/Tried/Skill.
Merge these with the markdown checkpoint file to reconstruct session state. The
git history shows the chronological arc; the markdown checkpoint shows the
intentional save points. Both matter.

**Important:** Do NOT delete WIP commits during resume. They remain the recovery
trail until /ship squashes them into clean commits during PR creation.

### Step 2: Load checkpoint

If the user specified a checkpoint (by number, title fragment, or date), find the
matching file. Otherwise, load the **most recent** checkpoint.

Read the checkpoint file and present a summary:

```
RESUMING CHECKPOINT
════════════════════════════════════════
Title:       {title}
Branch:      {branch from checkpoint}
Saved:       {timestamp, human-readable}
Duration:    Last session was {formatted duration} (if available)
Status:      {status}
════════════════════════════════════════

### Summary
{summary from checkpoint}

### Remaining Work
{remaining work items from checkpoint}

### Notes
{notes from checkpoint}
```

If the current branch differs from the checkpoint's branch, note this:
"This checkpoint was saved on branch `{branch}`. You are currently on
`{current branch}`. You may want to switch branches before continuing."

### Step 3: Offer next steps

After presenting the checkpoint, ask via AskUserQuestion:

- A) Continue working on the remaining items
- B) Show the full checkpoint file
- C) Just needed the context, thanks

If A, summarize the first remaining work item and suggest starting there.

---

## List flow

### Step 1: Gather checkpoints

```bash
{{SLUG_SETUP}}
CHECKPOINT_DIR="$HOME/.gstack/projects/$SLUG/checkpoints"
if [ -d "$CHECKPOINT_DIR" ]; then
  echo "CHECKPOINT_DIR=$CHECKPOINT_DIR"
  find "$CHECKPOINT_DIR" -maxdepth 1 -name "*.md" -type f 2>/dev/null | xargs ls -1t 2>/dev/null
else
  echo "NO_CHECKPOINTS"
fi
```

### Step 2: Display table

**Default behavior:** Show checkpoints for the **current branch** only.

If the user passes `--all` (e.g., `/checkpoint list --all`), show checkpoints
from **all branches**.

Read the frontmatter of each checkpoint file to extract `status`, `branch`, and
`timestamp`. Parse the title from the filename (the part after the timestamp).

Present as a table:

```
CHECKPOINTS ({branch} branch)
════════════════════════════════════════
#  Date        Title                    Status
─  ──────────  ───────────────────────  ───────────
1  2026-03-31  auth-refactor            in-progress
2  2026-03-30  api-pagination           completed
3  2026-03-28  db-migration-setup       in-progress
════════════════════════════════════════
```

If `--all` is used, add a Branch column:

```
CHECKPOINTS (all branches)
════════════════════════════════════════
#  Date        Title                    Branch              Status
─  ──────────  ───────────────────────  ──────────────────  ───────────
1  2026-03-31  auth-refactor            feat/auth           in-progress
2  2026-03-30  api-pagination           main                completed
3  2026-03-28  db-migration-setup       feat/db-migration   in-progress
════════════════════════════════════════
```

If there are no checkpoints, tell the user: "No checkpoints saved yet. Run
`/checkpoint` to save your current working state."

---

## Important Rules

- **Never modify code.** This skill only reads state and writes checkpoint files.
- **Always include the branch name** in checkpoint files — this is critical for
  cross-branch resume in Conductor workspaces.
- **Checkpoint files are append-only.** Never overwrite or delete existing checkpoint
  files. Each save creates a new file.
- **Infer, don't interrogate.** Use git state and conversation context to fill in
  the checkpoint. Only use AskUserQuestion if the title genuinely cannot be inferred.