diff --git a/apps/website/content/docs/reference/skills-catalog.mdx b/apps/website/content/docs/reference/skills-catalog.mdx index c3b3c6d7..e1e8e75f 100644 --- a/apps/website/content/docs/reference/skills-catalog.mdx +++ b/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: diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/README.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/README.md index 9e0d8185..ccf84768 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/README.md +++ b/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** diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/checkpoint-template.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/checkpoint-template.md new file mode 100644 index 00000000..d1a2ceb3 --- /dev/null +++ b/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/.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. diff --git a/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md new file mode 100644 index 00000000..da61499e --- /dev/null +++ b/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/.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/#-*`). 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/.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/#-*` (`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/.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 `.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/.md` — file is the source of truth." + +### Step 6: Locate Checkpoint (resume mode) + +1. **Check**: Does exactly one `.pair/working/checkpoints/.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/.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/.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.