[#254] feat: pair-capability-checkpoint (write/resume, handoff)

apps/website/content/docs/reference/skills-catalog.mdx

@@ -1,9 +1,9 @@
 ---
 title: Skills Catalog
-description: Complete catalog of all 33 pair skills organized by type — process, capability, and meta.
+description: Complete catalog of all 34 pair skills organized by type — process, capability, and meta.
 ---
 
-pair ships with 33 skills organized into three types: **process** (workflow orchestration), **capability** (atomic operations), and **meta** (navigation). Each skill is a `SKILL.md` file invoked as a slash command by your AI coding assistant.
+pair ships with 34 skills organized into three types: **process** (workflow orchestration), **capability** (atomic operations), and **meta** (navigation). Each skill is a `SKILL.md` file invoked as a slash command by your AI coding assistant.
 
 > **Last updated:** 2026-07-07. Source: `packages/knowledge-hub/dataset/.skills/`
 
@@ -88,6 +88,12 @@ Reclassified from process skills — see [Migration Notes](/docs/reference/skill
 | **write-issue** | `/pair-capability-write-issue` | Creates or updates issues in the adopted PM tool using template-driven formatting. |
 | **estimate** | `/pair-capability-estimate` | Estimates a refined user story using the adopted estimation methodology. |
 
+### State and Handoff Capabilities
+
+| Skill | Command | Description |
+| ----- | ------- | ----------- |
+| **checkpoint** | `/pair-capability-checkpoint` | Writes and resumes a self-contained progress checkpoint (story, branch, tasks done, decisions, remaining todos) in `.pair/working/checkpoints/`, so work survives context resets. |
+
 ## Skill Properties
 
 All skills share these properties:

packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/README.md

@@ -226,6 +226,7 @@ Templates work with popular project management tools:
 | `manual-test-report-template.md` | Quality | Test execution report | Low     |
 | `context-map-template.md`        | Domain  | Ubiquitous language, entities, common rules | Medium |
 | `subdomain-context-template.md`  | Domain  | Lazy per-subdomain context split | Low |
+| `checkpoint-template.md`         | Operational | Resumable progress state | Low |
 
 ### Template Relationships
 
@@ -284,6 +285,7 @@ The **TemplateOrchestrator** provides comprehensive template management through
 - Feature specification templates with comprehensive requirement documentation
 - Bug report templates with detailed reproduction steps and environment information
 - Technical decision templates with evaluation criteria and rationale documentation
+- **[Checkpoint Template](checkpoint-template.md)** - Resumable progress state (story, branch, tasks done, decisions, remaining todos) for context-reset handoffs
 
 ### 2. **Project Management Templates**
 

packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/checkpoint-template.md

@@ -0,0 +1,51 @@
+# Checkpoint: #[story-id] — [Story Title]
+
+**Last updated:** [YYYY-MM-DD HH:MM]
+**Written by:** [session/agent identifier — e.g. "implement session", "subagent: publish-pr"]
+
+> Read top to bottom before doing anything else. Written so a session with **zero prior context** can resume exactly where the previous one stopped.
+
+## 1. Story
+
+**ID:** #[story-id]
+**Title:** [Story title]
+**Epic:** #[epic-id] — [epic title] (if applicable)
+**Goal:** [one or two sentences — what this story delivers and why]
+**Source:** [link to the issue / PM tool item]
+
+## 2. Branch
+
+**Branch:** `feature/#[story-id]-[short-description]`
+**Commit strategy:** [commit-per-task | commit-per-story]
+**Commits so far:** [N] — [most recent commit subject, or "none yet"]
+
+## 3. Tasks Done
+
+- [x] T-1 — [title] — [commit ref or brief evidence]
+- [x] T-2 — [title]
+
+[If none yet: "None yet."]
+
+## 4. Key Decisions
+
+- [What was decided + why. Link the ADR/ADL if one was recorded: `.pair/adoption/tech/adr/...` or `.pair/adoption/decision-log/...`]
+
+[If none yet: "None yet."]
+
+## 5. Remaining Todos
+
+- [ ] T-3 — [title] — [known blockers, open questions, or notes]
+- [ ] T-4 — [title]
+
+**Next immediate action:** [the single next concrete step the resuming session should take]
+
+---
+
+## Template Notes
+
+Everything below this line is authoring guidance — omit it from rendered checkpoints.
+
+- **File location:** `.pair/working/checkpoints/<story-id>.md` — one file per story, updated in place, never duplicated.
+- **Source of truth:** the file. If an issue-body mirror exists, it must be explicitly marked as a copy and must not diverge in meaning from the file.
+- **Resume parsing:** a resuming session reads sections 1–5 top to bottom. It should not need the original conversation to continue safely.
+- **Unknown state:** if a value cannot be reconstructed confidently, write `[unknown — needs confirmation]` rather than guessing.

packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: checkpoint
+description: "Writes and resumes a self-contained progress checkpoint (story, branch, tasks done, decisions, remaining todos) so work survives context resets. Write mode persists state to .pair/working/checkpoints/<story-id>.md, one file per story; resume mode locates and parses it. Invocable independently; composed by a future closing phase of /implement (story #256) and a future /publish-pr as a handoff."
+version: 0.4.1
+author: Foomakers
+---
+
+# /checkpoint — Resumable Progress State
+
+Write and resume a self-contained progress checkpoint so a fresh session (or a subagent) can continue a story exactly where the previous one stopped. Follows the [checkpoint template](../../../.pair/knowledge/guidelines/collaboration/templates/checkpoint-template.md) — five sections: story, branch, tasks done, key decisions, remaining todos.
+
+## Arguments
+
+| Argument   | Required | Description                                                                                                                                                          |
+| ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `$mode`    | Yes      | `write` — persist/return current state. `resume` — locate and parse the existing checkpoint for a story.                                                              |
+| `$story`   | No       | Story ID. If omitted, detected from session context or the current branch (`feature/#<id>-*`). If it cannot be detected → **HALT**.                                   |
+| `$persist` | No       | Write mode only. `true` (default) — write/update the file at the default location. `false` — write-free: synthesize and return the checkpoint text without touching the filesystem; the composer decides where it lands. |
+
+## Core Rule: One Checkpoint Per Story
+
+- Default location: `.pair/working/checkpoints/<story-id>.md`.
+- Write mode always updates this file in place. It never creates a second file for the same story.
+- The file is the source of truth. An issue-body mirror is optional and, if used, must be explicitly marked as a copy.
+
+## Algorithm
+
+### Step 1: Resolve Story Context
+
+1. **Check**: Is `$story` provided?
+2. **Skip**: If yes, proceed to Step 2.
+3. **Act**: Attempt detection, in order:
+   - Active story already loaded in the current session.
+   - Current branch name matching `feature/#<id>-*` (`git branch --show-current`).
+   - Resume mode only: a single checkpoint file present under `.pair/working/checkpoints/`.
+4. **Verify**: Story ID resolved. If not → **HALT**: "Cannot detect story context — pass `$story` explicitly."
+
+### Step 2: Route by Mode
+
+- `$mode = write` → Step 3.
+- `$mode = resume` → Step 6.
+
+### Step 3: Gather State (write mode)
+
+1. **Check**: Is the full state (story, branch, tasks done/pending, decisions) already known from the current session context?
+2. **Skip**: If yes, use it directly. Proceed to Step 4.
+3. **Act**: If not (e.g., invoked by a subagent with no prior context), reconstruct from artifacts:
+   - **Branch**: `git branch --show-current`.
+   - **Tasks done/pending**: read the story's Task Breakdown checklist (per [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md)), cross-referenced with commits on the branch — the same technique `/implement` uses for idempotent resume.
+   - **Decisions**: scan [adoption/tech/adr/](../../../.pair/adoption/tech/adr/) and [adoption/decision-log/](../../../.pair/adoption/decision-log/) for files touched since the branch diverged from main.
+4. **Verify**: All five state elements resolved. Anything that cannot be reconstructed confidently is marked `[unknown — needs confirmation]` — never guessed.
+
+### Step 4: Detect Existing Checkpoint
+
+1. **Check**: Does `.pair/working/checkpoints/<story-id>.md` already exist?
+2. **Skip**: If not, proceed to Step 5 to create it.
+3. **Act**: If it exists, read its current content — the new state overwrites it in place (Core Rule).
+4. **Check**: Do other checkpoint files also resolve to this story ID (e.g. a stray duplicate from a prior manual copy)?
+5. **Act**: If duplicates are found, use the most recently modified one as the base and flag the others to the caller as duplicates to remove.
+
+### Step 5: Write / Return Checkpoint
+
+1. **Act**: Render the checkpoint following the [checkpoint template](../../../.pair/knowledge/guidelines/collaboration/templates/checkpoint-template.md), filling all five sections.
+2. **Check**: Is `$persist` `false`?
+3. **Skip**: If `$persist` is `true` (default) — create `.pair/working/checkpoints/` if missing, write the rendered content to `<story-id>.md` (overwrite in place, per Core Rule).
+4. **Act**: If `$persist` is `false` — do not touch the filesystem. Synthesize the text only.
+5. **Verify**: Regardless of `$persist`, the full rendered checkpoint text is returned to the caller (Output Format). If an issue-body mirror is requested, mark it explicitly: "Mirror of `.pair/working/checkpoints/<story-id>.md` — file is the source of truth."
+
+### Step 6: Locate Checkpoint (resume mode)
+
+1. **Check**: Does exactly one `.pair/working/checkpoints/<story-id>.md` exist?
+2. **Skip**: If exactly one, proceed to Step 7.
+3. **Act**: If none exists → **HALT**: "No checkpoint found for #`$story` — start fresh, or provide checkpoint text directly."
+4. **Act**: If more than one candidate resolves to the same story (edge case), use the most recently modified file and flag the others as duplicates to the caller.
+
+### Step 7: Parse Checkpoint
+
+1. **Act**: Parse the five sections in order: Story, Branch, Tasks Done, Key Decisions, Remaining Todos. Ignore a trailing "Template Notes" (or any 6th) section if one is present — it is authoring guidance, not checkpoint state.
+2. **Check**: Are all five sections present and structurally well-formed?
+3. **Skip**: If yes, proceed to Step 8 with full confidence.
+4. **Act**: If any section is missing, empty, or malformed — report exactly what WAS parsed, list what's missing or ambiguous, and ask the caller to confirm before proceeding. Never fill gaps by guessing.
+
+### Step 8: Report Parsed State
+
+1. **Act**: Present the parsed state to the caller (Output Format) — story, branch, tasks done, tasks pending, key decisions.
+2. **Verify**: Caller has the state needed to continue without repeating completed work.
+
+## Output Format
+
+Write mode:
+
+```text
+CHECKPOINT WRITTEN:
+├── Story:    [#ID: Title]
+├── Branch:   [feature/#ID-description]
+├── Path:     [.pair/working/checkpoints/<story-id>.md | write-free — not persisted]
+├── Mode:     [Created | Updated in place]
+└── Tasks:    [N done / M total]
+```
+
+Followed by the full rendered checkpoint text (per the template) — always returned, regardless of `$persist`.
+
+Resume mode:
+
+```text
+CHECKPOINT RESUMED:
+├── Story:      [#ID: Title]
+├── Branch:     [feature/#ID-description]
+├── Tasks done: [list T-N]
+├── Tasks left: [list T-N]
+├── Decisions:  [N recorded | None yet]
+└── Confidence: [High — all sections parsed cleanly | Needs confirmation — see gaps below]
+```
+
+## Composition Interface
+
+When composed by a future closing phase of `/implement` (story #256):
+
+- **Input**: `/implement` would invoke `/checkpoint` with `$mode=write` between tasks (or on developer request) to persist progress, and `$mode=resume` at Phase 0 when re-invoked on a story that may have been interrupted.
+- **Output**: Write mode's returned text becomes the session's record of state. Resume mode's parsed state lets `/implement` skip re-analysis and jump straight to the first pending task.
+
+When composed by a future `/publish-pr` (companion capability from the same epic split):
+
+- **Input**: `/publish-pr` invokes `/checkpoint` with `$mode=write, $persist=false` to obtain a handoff prompt summarizing the story before drafting the PR description.
+- **Output**: The returned text (not written to file) is embedded directly into the composer's own output — the composer owns persistence.
+
+When invoked **independently**:
+
+- Full interactive flow. The developer or a subagent passes `$mode` and, if needed, `$story` explicitly.
+
+## Edge Cases
+
+- **No story context detectable**: **HALT** and ask the caller to pass `$story` explicitly (Step 1).
+- **Corrupted or incomplete checkpoint on resume**: report exactly what was parsed, list what's missing/ambiguous, and ask for confirmation before the caller proceeds (Step 7).
+- **Multiple checkpoints found for one story**: use the most recently modified file; flag the duplicates to the caller for cleanup (Steps 4 and 6).
+
+## Graceful Degradation
+
+- If the [checkpoint template](../../../.pair/knowledge/guidelines/collaboration/templates/checkpoint-template.md) is not found, use the minimal five-section structure directly: Story, Branch, Tasks Done, Key Decisions, Remaining Todos.
+- If `.pair/working/` does not exist yet, create it (and `checkpoints/` under it) on first write.
+- If git is not available or the branch cannot be determined, mark the Branch section `[unknown — needs confirmation]` rather than guessing.
+- If the PM tool is not accessible during state reconstruction (Step 3), ask the developer to confirm tasks done/pending directly.
+
+## Notes
+
+- This skill **writes at most one file** — `.pair/working/checkpoints/<story-id>.md` — and only in write mode with `$persist=true` (default).
+- **Idempotent**: re-invoking write mode updates the same file in place; it never duplicates. Re-invoking resume mode is read-only and safe to repeat.
+- `.pair/working/` holds operational, per-project runtime state — never touched by install or update (D14). It is not part of the distributed KB defaults.
+- Checkpoints complement, not replace, git/PM-tool state. When state can already be reconstructed reliably from git and the PM tool (as `/implement` does today), a checkpoint file adds an explicit, fast-to-read summary — most valuable across context resets and subagent handoffs, where reconstruction from scratch is expensive or impossible.
+- The write-free (`$persist=false`) option mirrors composers that own their own persistence (e.g., embedding the handoff directly into a PR body) rather than writing a separate file.