From 02554c3b14290ba1d7aae1e68f5c5b7e18e0f4bf Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Mon, 6 Jul 2026 23:52:14 +0200 Subject: [PATCH 1/6] [#254] feat: pair-capability-checkpoint (write/resume, handoff) - checkpoint-template.md: 5 sections (story, branch, tasks done, decisions, remaining todos), KB placement in collaboration/templates - SKILL.md: write mode (gather/reconstruct state, write-in-place, write-free $persist=false), resume mode (locate, parse, report), edge cases (no story, corrupted checkpoint, duplicates) - docs: skills-catalog.mdx +1 row, 33->34 - dogfood: fresh-context subagent resumed a mid-story fixture from checkpoint text alone, no clarifying questions Refs: #254 --- .pair/knowledge/skills-guide.md | 4 +- .../docs/contributing/writing-skills.mdx | 2 +- .../docs/reference/skill-management.mdx | 2 +- .../content/docs/reference/skills-catalog.mdx | 12 +- .../collaboration/templates/README.md | 2 + .../templates/checkpoint-template.md | 49 ++++++ .../dataset/.pair/knowledge/skills-guide.md | 4 +- .../.skills/capability/checkpoint/SKILL.md | 150 ++++++++++++++++++ 8 files changed, 216 insertions(+), 9 deletions(-) create mode 100644 packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/checkpoint-template.md create mode 100644 packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md diff --git a/.pair/knowledge/skills-guide.md b/.pair/knowledge/skills-guide.md index 15ad5090..b5a070ed 100644 --- a/.pair/knowledge/skills-guide.md +++ b/.pair/knowledge/skills-guide.md @@ -15,9 +15,9 @@ Run `/pair-next` at the start of every session. It reads project adoption files | Type | Count | Purpose | |------|-------|---------| | **Process** | 9 | Lifecycle phases — orchestrate capability skills | -| **Capability** | 24 | Atomic units — perform a single focused operation | +| **Capability** | 25 | Atomic units — perform a single focused operation | -Process skills compose capability skills. Capability skills are independently invocable. Total: 34 (9 process + 24 capability + 1 navigator). +Process skills compose capability skills. Capability skills are independently invocable. Total: 35 (9 process + 25 capability + 1 navigator). ## Full Catalog diff --git a/apps/website/content/docs/contributing/writing-skills.mdx b/apps/website/content/docs/contributing/writing-skills.mdx index 9460499b..6dbd4267 100644 --- a/apps/website/content/docs/contributing/writing-skills.mdx +++ b/apps/website/content/docs/contributing/writing-skills.mdx @@ -177,5 +177,5 @@ Add your skill to `packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.m ## Resources - [Agent Skills specification](https://agentskills.io) — The open standard. -- [Skills Catalog](/docs/reference/skills-catalog) — Full list of all 34 pair skills. +- [Skills Catalog](/docs/reference/skills-catalog) — Full list of all 35 pair skills. - [Skills concept](/docs/concepts/skills) — How skills fit into the pair ecosystem. diff --git a/apps/website/content/docs/reference/skill-management.mdx b/apps/website/content/docs/reference/skill-management.mdx index 03385621..e016efe2 100644 --- a/apps/website/content/docs/reference/skill-management.mdx +++ b/apps/website/content/docs/reference/skill-management.mdx @@ -267,6 +267,6 @@ No code change is required in `apps/pair-cli` — the `skills` registry (`config ## Related -- [Skills Catalog](/docs/reference/skills-catalog) — All 34 pair skills +- [Skills Catalog](/docs/reference/skills-catalog) — All 35 pair skills - [Configuration Reference](/docs/reference/configuration) — config.json registry settings - [KB Structure Reference](/docs/reference/kb-structure) — Directory layout diff --git a/apps/website/content/docs/reference/skills-catalog.mdx b/apps/website/content/docs/reference/skills-catalog.mdx index 4c7d1b56..b57942ad 100644 --- a/apps/website/content/docs/reference/skills-catalog.mdx +++ b/apps/website/content/docs/reference/skills-catalog.mdx @@ -1,11 +1,11 @@ --- title: Skills Catalog -description: Complete catalog of all 34 pair skills organized by type — process, capability, and meta. +description: Complete catalog of all 35 pair skills organized by type — process, capability, and meta. --- -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. +pair ships with 35 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/` +> **Last updated:** 2026-07-11. Source: `packages/knowledge-hub/dataset/.skills/` ## Meta Skills @@ -94,6 +94,12 @@ Reclassified from process skills — see [Migration Notes](/docs/reference/skill | ----- | ------- | ----------- | | **grill** | `/pair-capability-grill` | Reusable interview engine: one question at a time, always with a recommendation, exploring KB/codebase before asking. `sync` mode drives systematic AI-human alignment on a story until explicit shared understanding. Write-free — returns the synthesis to the caller. | +### 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..5f673e3c --- /dev/null +++ b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/checkpoint-template.md @@ -0,0 +1,49 @@ +# 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 + +- **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/.pair/knowledge/skills-guide.md b/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md index 1a7db100..769869e5 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md @@ -15,9 +15,9 @@ Run `/next` at the start of every session. It reads project adoption files and P | Type | Count | Purpose | |------|-------|---------| | **Process** | 9 | Lifecycle phases — orchestrate capability skills | -| **Capability** | 24 | Atomic units — perform a single focused operation | +| **Capability** | 25 | Atomic units — perform a single focused operation | -Process skills compose capability skills. Capability skills are independently invocable. Total: 34 (9 process + 24 capability + 1 navigator). +Process skills compose capability skills. Capability skills are independently invocable. Total: 35 (9 process + 25 capability + 1 navigator). ## Full Catalog 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..33d6ee50 --- /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 or composed by /implement and /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. +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 `/implement`: + +- **Input**: `/implement` invokes `/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. From 993c07e1cf099770eb1eaf0a3befb1621d8b365d Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Tue, 7 Jul 2026 09:49:26 +0200 Subject: [PATCH 2/6] [#254] fix: mark /implement composition as future (#256), template notes as authoring-only MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SKILL.md: reword frontmatter + Composition Interface — /implement has zero /checkpoint refs today, wiring lands with story #256. Step 7: ignore trailing 6th section on parse. Template: explicit "omit from rendered checkpoints" disclaimer on Template Notes. Co-Authored-By: Claude Sonnet 5 --- .../collaboration/templates/checkpoint-template.md | 2 ++ .../dataset/.skills/capability/checkpoint/SKILL.md | 8 ++++---- 2 files changed, 6 insertions(+), 4 deletions(-) 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 index 5f673e3c..d1a2ceb3 100644 --- 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 @@ -43,6 +43,8 @@ ## 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. diff --git a/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md index 33d6ee50..da61499e 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md @@ -1,6 +1,6 @@ --- 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 or composed by /implement and /publish-pr as a handoff." +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 --- @@ -75,7 +75,7 @@ Write and resume a self-contained progress checkpoint so a fresh session (or a s ### Step 7: Parse Checkpoint -1. **Act**: Parse the five sections in order: Story, Branch, Tasks Done, Key Decisions, Remaining Todos. +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. @@ -114,9 +114,9 @@ CHECKPOINT RESUMED: ## Composition Interface -When composed by `/implement`: +When composed by a future closing phase of `/implement` (story #256): -- **Input**: `/implement` invokes `/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. +- **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): From 887247196b58f33b9e2b808023321f683ac1e183 Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Tue, 7 Jul 2026 20:51:19 +0200 Subject: [PATCH 3/6] [#254] fix: correct skill total after rebase (34, not 35) Miscalculated during the rebase conflict resolution: main doesn't have #229 (grill) merged yet, only rebased as a branch. Correct total after adding checkpoint is main's actual 33 + 1 = 34, not 35. Caught by `docs:staleness` which counts skills directly from the dataset. Refs: #254 --- apps/website/content/docs/reference/skills-catalog.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apps/website/content/docs/reference/skills-catalog.mdx b/apps/website/content/docs/reference/skills-catalog.mdx index b57942ad..c2778e04 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 35 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 35 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-11. Source: `packages/knowledge-hub/dataset/.skills/` From 5125e3a237a98e63b32818bc7b68e9793833859e Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Sat, 11 Jul 2026 09:55:00 +0200 Subject: [PATCH 4/6] [#254] fix: re-correct skill total to 35 after second rebase onto main with #229 merged MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit f1b2e77 correctly set the total to 34 when rebased onto a main that only had #229 (grill) as an unmerged branch (33 + checkpoint = 34). Main now has #229 actually merged (34 + checkpoint = 35) — re-applying the +1 this branch's own diff always intended. Refs: #254 --- apps/website/content/docs/reference/skills-catalog.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apps/website/content/docs/reference/skills-catalog.mdx b/apps/website/content/docs/reference/skills-catalog.mdx index c2778e04..b57942ad 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 34 pair skills organized by type — process, capability, and meta. +description: Complete catalog of all 35 pair skills organized by type — process, capability, and meta. --- -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. +pair ships with 35 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-11. Source: `packages/knowledge-hub/dataset/.skills/` From f82a08ab57d6b74d659a77c6c91855070b94bb0e Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Sat, 11 Jul 2026 12:05:53 +0200 Subject: [PATCH 5/6] [#254] fix: add missing installed skill mirror for pair-capability-checkpoint MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The dataset gained packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md but the installed mirror this repo's own agents actually invoke, .claude/skills/pair-capability-checkpoint/SKILL.md, was never created — same gap pattern already found and fixed for #232 (setup-gates). Synced byte-for-byte modulo the standard prefix transform. Refs: #254 --- .../pair-capability-checkpoint/SKILL.md | 150 ++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 .claude/skills/pair-capability-checkpoint/SKILL.md diff --git a/.claude/skills/pair-capability-checkpoint/SKILL.md b/.claude/skills/pair-capability-checkpoint/SKILL.md new file mode 100644 index 00000000..917b7c33 --- /dev/null +++ b/.claude/skills/pair-capability-checkpoint/SKILL.md @@ -0,0 +1,150 @@ +--- +name: pair-capability-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 /pair-process-implement (story #256) and a future /pair-capability-publish-pr as a handoff." +version: 0.4.1 +author: Foomakers +--- + +# /pair-capability-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 `/pair-process-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 `/pair-process-implement` (story #256): + +- **Input**: `/pair-process-implement` would invoke `/pair-capability-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 `/pair-process-implement` skip re-analysis and jump straight to the first pending task. + +When composed by a future `/pair-capability-publish-pr` (companion capability from the same epic split): + +- **Input**: `/pair-capability-publish-pr` invokes `/pair-capability-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 `/pair-process-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. From 80d9fee1f9f332252cf5dc85fb8eb292261f53cf Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Sat, 11 Jul 2026 15:57:08 +0200 Subject: [PATCH 6/6] [#254] fix: .pair/working/ not ambient context; checkpoint cleanup at merge MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - AGENTS.md (dataset-shipped + root) + CLAUDE.md: minimal Quick Rule — .pair/working/ never loaded as context unless explicitly specified; skills that use it decide if and how - checkpoint SKILL Core Rule "Task-Scoped, Cleaned Up" (dataset + mirror): downstream-only consumption, auto-write fine, cleanup on completion - pair-process-review Phase 6.5: remove .pair/working/checkpoints/.md at PR merge (dataset + mirror) - ADL 2026-07-11-working-artifacts-task-scoped Refs: #254 Co-Authored-By: Claude Opus 4.8 (1M context) --- .../pair-capability-checkpoint/SKILL.md | 10 ++--- .claude/skills/pair-process-review/SKILL.md | 3 +- ...026-07-11-working-artifacts-task-scoped.md | 44 +++++++++++++++++++ AGENTS.md | 1 + CLAUDE.md | 1 + .../.skills/capability/checkpoint/SKILL.md | 10 ++--- .../dataset/.skills/process/review/SKILL.md | 3 +- packages/knowledge-hub/dataset/AGENTS.md | 1 + 8 files changed, 61 insertions(+), 12 deletions(-) create mode 100644 .pair/adoption/decision-log/2026-07-11-working-artifacts-task-scoped.md diff --git a/.claude/skills/pair-capability-checkpoint/SKILL.md b/.claude/skills/pair-capability-checkpoint/SKILL.md index 917b7c33..105e8073 100644 --- a/.claude/skills/pair-capability-checkpoint/SKILL.md +++ b/.claude/skills/pair-capability-checkpoint/SKILL.md @@ -17,11 +17,11 @@ Write and resume a self-contained progress checkpoint so a fresh session (or a s | `$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 +## Core Rules -- 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. +- **One file per story:** default location `.pair/working/checkpoints/.md`. Write mode always updates it in place — never 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. +- **Task-scoped:** a checkpoint is a downstream handoff consumed only by a session or subagent resuming or continuing _that_ story. It is NEVER loaded as ambient context into a chat or activity unrelated to the story. +- **Write freely, clean up on completion:** writing — including automatically, e.g. between tasks — is fine; the constraint is on _consumption scope_, not on when it is written. When the story is Done (its closing phase, or PR merge), the checkpoint is removed so finished-story state never lingers as stale context. ## Algorithm @@ -116,7 +116,7 @@ CHECKPOINT RESUMED: When composed by a future closing phase of `/pair-process-implement` (story #256): -- **Input**: `/pair-process-implement` would invoke `/pair-capability-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. +- **Input**: `/pair-process-implement` would invoke `/pair-capability-checkpoint` with `$mode=write` between tasks (or on developer request) to persist progress, `$mode=resume` at Phase 0 when re-invoked on a story that may have been interrupted, and remove the checkpoint on story completion (cleanup). - **Output**: Write mode's returned text becomes the session's record of state. Resume mode's parsed state lets `/pair-process-implement` skip re-analysis and jump straight to the first pending task. When composed by a future `/pair-capability-publish-pr` (companion capability from the same epic split): diff --git a/.claude/skills/pair-process-review/SKILL.md b/.claude/skills/pair-process-review/SKILL.md index 8213535f..e3a35c6d 100644 --- a/.claude/skills/pair-process-review/SKILL.md +++ b/.claude/skills/pair-process-review/SKILL.md @@ -302,7 +302,8 @@ Based on compiled findings: 1. **Act**: Delete the feature branch (remote): - CLI: `git push origin --delete `. -2. **Verify**: Feature branch deleted. +2. **Act**: Remove the story's checkpoint if one exists — `.pair/working/checkpoints/.md` — so completed-story state does not linger as stale context (per the task-scoped cleanup rule; see `/pair-capability-checkpoint`). +3. **Verify**: Feature branch deleted and story checkpoint removed (if any existed). ### Step 6.6: Post-Merge Manual Test Validation (Optional) diff --git a/.pair/adoption/decision-log/2026-07-11-working-artifacts-task-scoped.md b/.pair/adoption/decision-log/2026-07-11-working-artifacts-task-scoped.md new file mode 100644 index 00000000..b8904f3d --- /dev/null +++ b/.pair/adoption/decision-log/2026-07-11-working-artifacts-task-scoped.md @@ -0,0 +1,44 @@ +# Decision: `.pair/working/` Artifacts Are Task-Scoped and Cleaned Up + +## Date + +2026-07-11 + +## Status + +Active + +## Category + +Process Decision + +## Context + +Story #254 (`pair-capability-checkpoint`) writes checkpoints to `.pair/working/checkpoints/.md`. During code review of PR #270, the concern raised was not _when_ checkpoints get written (writing them automatically — e.g. `/pair-process-implement` between tasks — is acceptable), but that a checkpoint's content must not **leak as context** into chats or activities unrelated to the task it describes, and that finished-story checkpoints should not linger. + +D14 already governs distribution (`.pair/working/` is never touched by `install`/`update`). What was missing is a **runtime consumption-scope** policy. + +## Decision + +**A `.pair/working/` artifact is task-scoped, consumed only downstream, and cleaned up on completion.** + +- **Scope:** a checkpoint (or report/handoff) belongs to exactly one task/story. It is consumed only when resuming or continuing _that_ task (downstream — the next session or subagent on the same work). It is NEVER loaded as ambient context into a chat or activity unrelated to that task. +- **Writing is unconstrained:** the file may be written automatically (e.g. between tasks) — the constraint is on consumption scope, not on write timing. +- **Cleanup:** when the story is Done (its closing phase, or PR merge), the checkpoint is removed so finished-story state never persists as stale context. + +Division of responsibility: `AGENTS.md` (dataset-shipped → downstream projects inherit + this repo's root `AGENTS.md`/`CLAUDE.md`) carries only the minimal cross-cutting principle — `.pair/working/` is never loaded as context unless explicitly specified, and the skills that use it decide if and how. The task-scope, downstream-consumption, and cleanup detail lives in the `checkpoint` `SKILL.md` Core Rule "Task-Scoped, Cleaned Up" (dataset + installed mirror). + +## Alternatives Considered + +- **Make checkpoint writes opt-in / never automatic**: rejected — auto-write between tasks is a legitimate, useful default; the real risk is cross-task context leakage, not the write itself. +- **Rely on D14 only**: rejected — D14 covers distribution, not runtime consumption scope. +- **No cleanup (leave checkpoints in place)**: acceptable but weaker — stale finished-story checkpoints add noise and risk being picked up out of context; cleanup on completion is preferred. + +## Consequences + +- Composers that consume checkpoints (`/pair-process-implement` closing phase #256, `/pair-capability-publish-pr` #255, future supervisor #212) must scope reads to the active task and remove the checkpoint on story completion. +- Cleanup is enforced at merge now: `/pair-process-review` Phase 6.5 (Branch Cleanup) removes `.pair/working/checkpoints/.md` when the story's PR merges (dataset + installed mirror). The `/pair-process-implement` closing phase (#256) remains responsible for cleanup when a story completes without going through review-merge. + +## Adoption Impact + +- No project-level configuration change. It is a cross-cutting agent/skill behavioral rule, documented in `AGENTS.md` (dataset-shipped + root) and the `checkpoint` `SKILL.md` (dataset + installed mirror). Downstream projects inherit it via the shipped `AGENTS.md`. diff --git a/AGENTS.md b/AGENTS.md index 7b7ca537..9ddacd79 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -153,6 +153,7 @@ pnpm lint --filter - **No secrets in code** - ask for secure access instructions if needed - **Context consistency** - if switching how-to mid-session, explicitly update your session context - **Bug fix workflow** - NEVER modify code to fix a bug before creating a test that reproduces it. Test-first debugging ensures the fix actually addresses the problem. +- **`.pair/working/` is not ambient context** - Content under `.pair/working/` (checkpoints, reports, handoffs) is never loaded as context unless explicitly specified. The skills that use it decide if and how. - **Record decisions** - architectural/project decisions MUST be recorded as ADR or ADL. Use `/pair-capability-record-decision` skill or write to `.pair/tech/adopted/adr/` (architectural) / `.pair/tech/adopted/adl/` (non-architectural). - **Follow templates** - PRs, code reviews, commits, branches, tasks, user stories MUST follow templates in `.pair/knowledge/guidelines/collaboration/templates/` unless adoption files specify otherwise. Key templates: `pr-template.md`, `code-review-template.md`, `commit-template.md`, `branch-template.md`, `task-template.md`, `user-story-template.md`. diff --git a/CLAUDE.md b/CLAUDE.md index e0ec5a55..08088b4d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -98,6 +98,7 @@ pnpm lint --filter - **No secrets in code** - ask for secure access instructions if needed - **Context consistency** - if switching how-to mid-session, explicitly update your session context - **Bug fix workflow** - NEVER modify code to fix a bug before creating a test that reproduces it. Test-first debugging ensures the fix actually addresses the problem. +- **`.pair/working/` is not ambient context** - Content under `.pair/working/` (checkpoints, reports, handoffs) is never loaded as context unless explicitly specified. The skills that use it decide if and how. - **Record decisions** - architectural/project decisions MUST be recorded as ADR or ADL. Use `/pair-capability-record-decision` skill or write to `.pair/tech/adopted/adr/` (architectural) / `.pair/tech/adopted/adl/` (non-architectural). - **Follow templates** - PRs, code reviews, commits, branches, tasks, user stories MUST follow templates in `.pair/knowledge/guidelines/collaboration/templates/` unless adoption files specify otherwise. Key templates: `pr-template.md`, `code-review-template.md`, `commit-template.md`, `branch-template.md`, `task-template.md`, `user-story-template.md`. diff --git a/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md index da61499e..6b61c59b 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md @@ -17,11 +17,11 @@ Write and resume a self-contained progress checkpoint so a fresh session (or a s | `$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 +## Core Rules -- 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. +- **One file per story:** default location `.pair/working/checkpoints/.md`. Write mode always updates it in place — never 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. +- **Task-scoped:** a checkpoint is a downstream handoff consumed only by a session or subagent resuming or continuing _that_ story. It is NEVER loaded as ambient context into a chat or activity unrelated to the story. +- **Write freely, clean up on completion:** writing — including automatically, e.g. between tasks — is fine; the constraint is on _consumption scope_, not on when it is written. When the story is Done (its closing phase, or PR merge), the checkpoint is removed so finished-story state never lingers as stale context. ## Algorithm @@ -116,7 +116,7 @@ CHECKPOINT RESUMED: 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. +- **Input**: `/implement` would invoke `/checkpoint` with `$mode=write` between tasks (or on developer request) to persist progress, `$mode=resume` at Phase 0 when re-invoked on a story that may have been interrupted, and remove the checkpoint on story completion (cleanup). - **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): diff --git a/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md index a3896620..ec9f2a83 100644 --- a/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md @@ -303,7 +303,8 @@ Based on compiled findings: 1. **Act**: Delete the feature branch (remote): - CLI: `git push origin --delete `. -2. **Verify**: Feature branch deleted. +2. **Act**: Remove the story's checkpoint if one exists — `.pair/working/checkpoints/.md` — so completed-story state does not linger as stale context (per the task-scoped cleanup rule; see `/checkpoint`). +3. **Verify**: Feature branch deleted and story checkpoint removed (if any existed). ### Step 6.6: Post-Merge Manual Test Validation (Optional) diff --git a/packages/knowledge-hub/dataset/AGENTS.md b/packages/knowledge-hub/dataset/AGENTS.md index 90f546fd..5764e41f 100644 --- a/packages/knowledge-hub/dataset/AGENTS.md +++ b/packages/knowledge-hub/dataset/AGENTS.md @@ -155,6 +155,7 @@ pnpm lint --filter - **No secrets in code** - ask for secure access instructions if needed - **Context consistency** - if switching how-to mid-session, explicitly update your session context - **Bug fix workflow** - NEVER modify code to fix a bug before creating a test that reproduces it. Test-first debugging ensures the fix actually addresses the problem. +- **`.pair/working/` is not ambient context** - Content under `.pair/working/` (checkpoints, reports, handoffs) is never loaded as context unless explicitly specified. The skills that use it decide if and how. - **Record decisions** - architectural/project decisions MUST be recorded as ADR or ADL. Use `/record-decision` skill or write to `.pair/adoption/tech/adr/` (architectural) / `.pair/adoption/tech/adl/` (non-architectural). - **Follow templates** - PRs, code reviews, commits, branches, tasks, user stories MUST follow templates in `.pair/knowledge/guidelines/collaboration/templates/` unless adoption files specify otherwise. Key templates: `pr-template.md`, `code-review-template.md`, `commit-template.md`, `branch-template.md`, `task-template.md`, `user-story-template.md`.