clp-checkpoint

CLP handoff manifests are auto-generated by the PreCompact hook, but they can only extract mechanical data (file paths, tool calls). They cannot capture intent, decisions, or the "why" behind changes. The /clp:checkpoint command lets you enrich the manifest with the actual understanding of the session state. Create a CLP checkpoint by reflecting on the current session and writing a structured handoff manifest. Follow these steps:

1. Identify the current goal — What are we building or fixing right now?
2. List decisions made — What architectural or implementation choices were made and why?
3. List discoveries — What did we learn that wasn't obvious before starting?
4. List files changed — What files were modified or created, with brief descriptions?
5. List completed tasks — What's done?
6. List pending tasks — What's left, in priority order?
7. List known issues — Any bugs, blockers, or workarounds discovered?
8. Note active skills — Which CLP skills/docs are currently loaded?

Write the checkpoint to .claude/handoffs/ as a JSON manifest.

<output_schema> Write the file using this exact JSON structure:

{
  "version": "1.0",
  "session_id": "[current session ID]",
  "timestamp": "[ISO 8601]",
  "trigger": "manual_checkpoint",
  "project": "[project path]",

  "state": {
    "current_goal": "[one clear sentence]",
    "status": "in_progress | blocked | complete",
    "phase": "planning | implementation | testing | debugging | review"
  },

  "context": {
    "decisions": [
      { "decision": "[what]", "rationale": "[why]", "timestamp": "[when]" }
    ],
    "discoveries": [ "[insight 1]", "[insight 2]" ],
    "errors_resolved": [
      { "error": "[what broke]", "resolution": "[how we fixed it]", "file": "[where]" }
    ]
  },

  "files": {
    "modified": [ { "path": "[file]", "change": "[what changed]" } ],
    "created": [ { "path": "[file]", "change": "[what it does]" } ]
  },

  "tasks": {
    "completed": [ "[task 1]", "[task 2]" ],
    "pending": [ "[task 3 - highest priority first]" ],
    "blocked": [ { "task": "[what]", "blocker": "[why]" } ]
  },

  "active_skills": [ "[file paths of loaded skill docs]" ],

  "budget": {
    "kernel": { "allocated": 22000, "used": 0 },
    "active": { "allocated": 40000, "used": 0 },
    "working": { "allocated": 133000, "used": 0 },
    "buffer": { "allocated": 5000, "used": 0 }
  }
}

</output_schema>

- Be specific in decisions and discoveries. "Chose NextAuth" is bad. "Chose NextAuth over custom OAuth because it integrates with our existing Next.js middleware and handles PKCE automatically" is good. - Pending tasks should be in priority order — the most important one first. - File changes should describe WHAT changed, not just that it changed. - After writing the manifest, update `.claude/handoffs/latest.json` to point to it. - Confirm to the user what was saved with a 3-line summary: goal, completed count, pending count. - If $ARGUMENTS is provided, use it as the current_goal override.