Merge pull request #54 from MSiccDev/claude/checkpoint-skills

Author: MSicc

.agents/skills/create-checkpoint

@@ -0,0 +1 @@
+../../skills/create-checkpoint

.agents/skills/restore-checkpoint

@@ -0,0 +1 @@
+../../skills/restore-checkpoint

.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
         "repo": "MSiccDev/ai-context-kit"
       },
       "description": "Context-aware AI collaboration skills for creating and validating user context, project AGENTS.md files, and skill artifacts across LLM providers.",
-      "version": "1.4.1",
+      "version": "1.4.2",
       "license": "MIT",
       "homepage": "https://github.com/MSiccDev/ai-context-kit",
       "repository": "https://github.com/MSiccDev/ai-context-kit",

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "ai-context-kit",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "description": "Context-aware AI collaboration skills for creating and validating user context, project AGENTS.md files, and skill artifacts across LLM providers.",
   "author": {
     "name": "MSiccDev Software Development",

AGENTS.md

@@ -1,4 +1,4 @@
-<!-- spec_version: 1.4.1 -->
+<!-- spec_version: 1.4.2 -->
 
 # AI Context Kit Agent Guide
 
@@ -11,7 +11,7 @@ This repository distinguishes:
 
 ## Source Of Truth And Precedence
 Use this order when files differ:
-1. **Specification (authoritative, v1.4.1):** `specs/context_aware_ai_session_spec.md`
+1. **Specification (authoritative, v1.4.2):** `specs/context_aware_ai_session_spec.md`
 2. **Templates (canonical structures):** `templates/*.instructions.md` and `templates/skill_template/SKILL.md`
 3. **Skills (canonical operational workflows):** `skills/*/SKILL.md` and skill-local references
 4. **Prompts (compatibility wrappers):** `prompts/*.prompt.md` (must defer detailed logic to skills)
@@ -47,6 +47,17 @@ Active session state includes:
 - No silent transitions: do not change project, role, phase, output style, tone, or interaction mode without explicit user signal.
 - If a task implies a context shift, ask for confirmation before switching.
 
+### Cross-Session Persistence (spec section 4.4)
+- When the user signals session end or explicitly requests one, propose creating a checkpoint artifact using the `create-checkpoint` skill.
+- Never create a checkpoint silently. User approval is required before writing.
+- When a checkpoint artifact is provided at session start, apply the `restore-checkpoint` skill to restore state and surface any conflicts with active instruction files before proceeding.
+
+### Context Compression (spec section 4.5)
+- When context window saturation is evident, propose compression explicitly — describe what will be retained and what will be dropped before asking for confirmation.
+- Never apply compression silently. The user must confirm before any context is dropped.
+- Before applying compression, offer to export the current state to a checkpoint file using the `create-checkpoint` skill.
+- After compression, do not imply that dropped context is recoverable.
+
 ### Ambiguity Rule
 - If assumptions, state, or intent are ambiguous, ask clarifying questions before acting.
 
@@ -104,7 +115,7 @@ Alias policy:
 - Validation: skill-based validation workflows and reports
 
 ### Current Objectives
-- Keep templates and skills aligned with spec `v1.4.1`.
+- Keep templates and skills aligned with spec `v1.4.2`.
 - Maintain the AGENTS-first project-context model.
 - Preserve deterministic behavior and path stability.
 - Reduce duplication and migration noise.
@@ -185,7 +196,7 @@ When `specs/context_aware_ai_session_spec.md` changes, audit and update all impa
 - `AGENTS.md`
 
 ## Key References
-- Specification (v1.4.1): [`specs/context_aware_ai_session_spec.md`](specs/context_aware_ai_session_spec.md)
+- Specification (v1.4.2): [`specs/context_aware_ai_session_spec.md`](specs/context_aware_ai_session_spec.md)
 - Project operational defaults: this root `AGENTS.md` (Default State For This Repo)
 - User context template: [`templates/usercontext_template.instructions.md`](templates/usercontext_template.instructions.md)
 - Skill template: [`templates/skill_template/SKILL.md`](templates/skill_template/SKILL.md)

AGENTS.validation.md

@@ -14,7 +14,7 @@
 - **Score:** 20/20
 - **Status:** PASS
 - Target file exists and is structurally complete.
-- `<!-- spec_version: 1.4.1 -->` comment is present and current — no version warning.
+- `<!-- spec_version: 1.4.2 -->` comment is present and current — no version warning.
 - Purpose, precedence model, and repository map are explicitly defined.
 - Heading structure is scannable and consistent.
 

CHANGELOG.md

@@ -15,6 +15,33 @@ When a new version is released:
 
 ---
 
+## [1.4.2] - 2026-05-12
+
+### Added
+- **`create-checkpoint` skill** — guided workflow to capture session state as a checkpoint artifact per spec section 4.4, with schema reference and `agents/openai.yaml` sidecar
+- **`restore-checkpoint` skill** — guided workflow to load, validate, and restore a checkpoint artifact at session start per spec section 4.4 restore rules, with conflict resolution reference and `agents/openai.yaml` sidecar
+- **`checkpoint: true` required field** — added to spec section 4.4.2 schema so checkpoint files are self-identifying; restore validation is now fully spec-backed
+- AGENTS.md now references sections 4.4 (Cross-Session Persistence) and 4.5 (Context Compression) with explicit behavioral instructions for both
+- Prompts and Codex symlinks added for both new skills
+- `SKILL.validation.md` added to `create-checkpoint/` and `restore-checkpoint/` skill folders
+
+### Safe to update from template
+- `skills/create-checkpoint/` (new)
+- `skills/restore-checkpoint/` (new)
+- `.agents/skills/` (two new symlinks)
+- `prompts/` (two new prompt files)
+- `specs/context_aware_ai_session_spec.md`
+- `AGENTS.md`
+- `README.md`
+- `CHANGELOG.md`
+
+### Protect (never overwrite)
+- Your personal `*_usercontext.instructions.md`
+- Your project `AGENTS.md`
+- Any custom skills or checkpoint files you have created
+
+---
+
 ## [1.4.1] - 2026-05-11
 - **Claude Code plugin** — `.claude-plugin/plugin.json` manifest makes the repo installable as a native Claude Code plugin; skills are auto-discovered from `skills/`
 - **GitHub Copilot CLI plugin** — `.claude-plugin/marketplace.json` turns the repo into a self-hosted marketplace, enabling `copilot plugin marketplace add MSiccDev/ai-context-kit` install flow (Claude Code and Copilot CLI share the same plugin spec)
@@ -41,8 +68,8 @@ When a new version is released:
 ## [1.4.0] - 2026-05-08
 
 ### Added
-- **Spec §4.4 Cross-Session Persistence** — normative rules for checkpoint artifacts: proposal rules, required schema (project, role, phase, output_style, tone, interaction_mode, open_tasks, key_decisions, active_files, last_updated), and restore/conflict rules
-- **Spec §4.5 Context Compression** — normative rules for managing context window pressure: proposal rules, required compression checkpoint contents, and reversibility requirements
+- **Spec section 4.4 Cross-Session Persistence** — normative rules for checkpoint artifacts: proposal rules, required schema (project, role, phase, output_style, tone, interaction_mode, open_tasks, key_decisions, active_files, last_updated), and restore/conflict rules
+- **Spec section 4.5 Context Compression** — normative rules for managing context window pressure: proposal rules, required compression checkpoint contents, and reversibility requirements
 - `docs/spec-rationale.md`: new "Cross-Session Persistence and Context Compression" section with example checkpoint file, conflict resolution dialog, and annotated compression proposal dialog
 
 ### Changed

README.md

@@ -81,7 +81,7 @@ ai-context-kit/
 │   └── context_aware_ai_session_spec.md              # Specification for AI session management
 │
 ├── templates/
-│  ├── usercontext_template.instructions.md           # Canonical v1.4.1 user context template (authoritative)
+│  ├── usercontext_template.instructions.md           # Canonical v1.4.2 user context template (authoritative)
 │  ├── AGENTS_template.md                             # Canonical AGENTS template (authoritative)
 │  └── skill_template/SKILL.md                        # Canonical skill template
 │
@@ -114,7 +114,7 @@ ai-context-kit/
 
 ---
 
-## Canonical Authority (Spec v1.4.1)
+## Canonical Authority (Spec v1.4.2)
 
 When guidance differs across files, use this authority order:
 
@@ -209,6 +209,8 @@ Operational workflow authority is skill-first:
 - `skills/repository-drift-control/`
 - `skills/create-skill/`
 - `skills/validate-skill/`
+- `skills/create-checkpoint/`
+- `skills/restore-checkpoint/`
 
 ### Invoking Skills
 
@@ -242,13 +244,13 @@ The following paths are considered **canonical**:
 - `AGENTS.md`
   - Primary agent entrypoint (repo-specific operational contract)
 - `templates/`
-  - Canonical instruction templates (spec v1.4.1)
+  - Canonical instruction templates (spec v1.4.2)
 - `skills/`
   - Canonical workflow skills (`SKILL.md`-based folders)
 - `prompts/`
   - Composition wrappers for instruction/skill workflows
 - `specs/context_aware_ai_session_spec.md`
-  - Authoritative specification (v1.4.1+)
+  - Authoritative specification (v1.4.2+)
 - Root `README.md`
   - Human-facing entry point and workflow documentation
 
@@ -352,6 +354,8 @@ Skills are namespaced to the plugin name. Inside a session:
 | `validate-project-instructions` | Validate a project-context `AGENTS.md` with scored report |
 | `validate-skill` | Validate a `SKILL.md` artifact with scored report |
 | `repository-drift-control` | Check and enforce consistency across spec, templates, and docs |
+| `create-checkpoint` | Capture session state as a checkpoint artifact (spec section 4.4) |
+| `restore-checkpoint` | Restore session state from a checkpoint artifact (spec section 4.4) |
 
 ### Update
 
@@ -452,7 +456,7 @@ Each project `AGENTS.md` should define:
 - **Languages:** LLMs work best when instructions are in English, but you can include multilingual content in user context if needed (just be aware of potential comprehension issues)
 - **Versioning:** Update user context when skills/preferences evolve; update project `AGENTS.md` when phases/objectives change. Ideally, these should live in the same repository as your codebase once they are created.
 - **Discoverability:** Semantic file extensions help AI tools identify and load the appropriate instructions automatically
-- **Canonical structure:** The templates in `/templates` define the only supported artifact structures for spec v1.4.1
+- **Canonical structure:** The templates in `/templates` define the only supported artifact structures for spec v1.4.2
 
 ---
 

docs/spec-rationale.md

@@ -1,13 +1,13 @@
 ---
 context_type: rationale
 document_type: companion_document
-spec_version: 1.4.1
+spec_version: 1.4.2
 created: 2025-10-20
 last_updated: 2026-05-09
 status: active
 ---
 
-# Spec Rationale & Extended Reference (v1.4.1)
+# Spec Rationale & Extended Reference (v1.4.2)
 
 This document is the companion to [`specs/context_aware_ai_session_spec.md`](../specs/context_aware_ai_session_spec.md). It contains the background reasoning, extended examples, project profile illustrations, end-to-end scenarios, and future enhancement notes that were removed from the normative spec to keep it readable.
 
@@ -180,7 +180,7 @@ Assistant:
 
 ## Cross-Session Persistence and Context Compression
 
-These features are defined normatively in §4.4 and §4.5 of the spec. This section provides examples and rationale.
+These features are defined normatively in sections 4.4 and 4.5 of the spec. This section provides examples and rationale.
 
 ### Session Persistence: Example Checkpoint File
 

prompts/create-checkpoint.prompt.md

@@ -0,0 +1 @@
+Load `skills/create-checkpoint/SKILL.md` and apply the create-checkpoint workflow to capture the current session state as a checkpoint artifact per spec section 4.4.