Checkpoint

Purpose

Capture session context for continuity when ending a work session (but the bead is not yet closed).

When to Use

User says "checkpoint", "wrap up", "done for now", "let's close out"
Ending work for the day but will continue later
Context-switching between tasks

After task completion: Use /distill to extract knowledge and archive closed tasks.

Process

Step 1: Identify Active Bead

Check conversation context for which bead was being worked on
Run bd list --mine --pretty if needed to find the active bead
If no active bead, just commit any outstanding changes and summarize

Step 2: Capture Plan

If a plan was created/approved in this session:

Find the plan file:
```
ls -lt ~/.claude/plans/ | head -5
```
Identify the plan from this session (most recent, or match by title)

Copy to context dir:

mkdir -p projects/<project>/contexts/<bead-id>/
cp ~/.claude/plans/<slug>.md projects/<project>/contexts/<bead-id>/plan.md

Add to artifacts in bead metadata

If no plan was created, skip this step.

Step 3: Update Bead Metadata

3a. Collect and link artifacts

Gather all artifacts — both local files and external resources — and update the bead metadata.

Local files: If a context folder exists at projects/<project>/contexts/<bead-id>/, list its files.

External resources: Review the session for any external URLs referenced or created:

Meegle stories/tasks (e.g., https://meegle.com/...)
Lark documents or meeting notes
API documentation links
GitHub PRs, issues, or commits
Any other external resource used during the session

Update metadata:

bd show <id> --json — get current metadata (may already have artifacts seeded at claim)
Merge local file paths + external URLs into the artifacts list (deduplicate, preserve existing)
bd update <id> --metadata '<json>'

3b. Record session progress

bd update <id> --metadata '{"last_session":{"date":"YYYY-MM-DD","summary":"<What was accomplished>","next_steps":["<Next action>","<Open question>"]}}'

Step 4: Update Context Notes

If a context folder exists at projects/<project>/contexts/<bead-id>/, append session notes for continuity to notes.md:

## Session: YYYY-MM-DD

### What Was Done
- <Accomplishment 1>
- <Accomplishment 2>

### Where We Left Off
- <Current state>
- <In-progress item>

### Next Steps
- [ ] <Action item>

### Open Questions
- <Question needing resolution>

If no context folder exists and notes are minimal, the bead metadata from Step 2 is sufficient.

Step 5: Review Permission Escalations

Check if any permissions were manually approved during the session that should be added to shared settings:

# Look at settings.local.json for session-added permissions
cat .claude/settings.local.json 2>/dev/null

If local overrides exist:

Show the user what's in local vs shared
Ask which should be promoted to settings.json
Apply changes and remove redundant local entries
If local becomes empty/redundant, delete it

Step 6: Check for Skill Changes

git status --short projects/*/skills/

If skill changes detected:

Show the changes to user
Run Skill(sync-skills) to sync

Step 7: Commit Progress

git add projects/<project>/contexts/<bead-id>/
git add projects/*/skills/   # if skill changes
git add .claude/skills/      # if skill changes

git commit -m "WIP: <bead-title> — <brief session summary>"

Step 8: Summary

Checkpoint saved:
- Bead: <bead-id> (<title>)
- Status: <unchanged — still in_progress>
- Next steps captured in bead metadata
- Committed: <commit-hash>

Tips

Keep notes scannable — bullet points, not paragraphs
Focus on what the next session needs to know to resume
Always commit — don't leave uncommitted wrap-up artifacts
After closing a bead, run /distill to extract knowledge and archive

checkpoint