| name | dev-session |
| description | Manage long development sessions with structured progress tracking. Creates SESSION.md files for multi-session handoff, checkpoints progress with WIP commits, and captures learnings to CLAUDE.md. Trigger with 'start session', 'checkpoint', 'wrap session', 'resume session', or 'context getting full'. |
| compatibility | claude-code-only |
Dev Session
Manage multi-session development work with structured progress files, checkpoint commits, and durable learnings. Produces SESSION.md files that survive context compaction and enable clean handoff between sessions.
Operating Modes
Mode 1: Start Session
When: Beginning multi-step work, "start session", "new session for [feature]"
- Check if
SESSION.md already exists in the project root
- Pre-fill fields:
- Project: from CLAUDE.md or directory name
- Branch: from
git branch --show-current
- Last Updated: current timestamp
- Phase: ask user what they're working on
- Read the project's CLAUDE.md to orient on context
- Present a brief summary: "Session started. Working on [phase] on branch [branch]."
Mode 2: Checkpoint
When: "checkpoint", major milestone reached, before risky changes, context getting large
- Update SESSION.md:
- Add completed items to What Works
- Update Current Position with exact location (file paths, line numbers)
- Clear resolved Blockers, add new ones
- Write concrete Resume Instructions
- Capture learnings:
- If any patterns, gotchas, or commands were discovered during work, add them to CLAUDE.md
- One line per concept — concise, not verbose
- Git checkpoint:
git add -A && git commit -m "WIP: [what was accomplished]"
- Record the commit hash in SESSION.md under Checkpoint
- Confirm: "Checkpointed at [hash]. SESSION.md updated."
Mode 3: Resume Session
When: "resume", "continue from last session", "where were we", start of a new conversation
- Read
SESSION.md — if missing, inform user and offer to start a new session
- Read the project's
CLAUDE.md for context
- Check what's changed since the recorded checkpoint:
git log --oneline [checkpoint-hash]..HEAD
- Check for uncommitted changes:
git status
- Present a summary:
- Phase: what we were working on
- Position: where we left off
- Changes since: any commits or modifications since checkpoint
- Blockers: anything unresolved
- Suggested next step: first item from Resume Instructions
Mode 4: Wrap Session
When: "wrap session", "done for now", "save progress", ending a session
- Run a full checkpoint (Mode 2)
- Review SESSION.md for completeness:
- Are Resume Instructions concrete enough for a fresh session to continue?
- Is Current Position specific (file paths, not vague descriptions)?
- If the phase is complete:
- Collapse the phase summary to 2-3 lines
- Clear Resume Instructions or note "Phase complete — ready for next phase"
- Confirm: "Session wrapped. Resume with 'resume session' next time."
When to Use
| Scenario | Use this skill? |
|---|
| Multi-phase feature spanning 2+ sessions | Yes |
| Work that might hit context compaction | Yes |
| Before making risky or destructive changes | Yes (checkpoint first) |
| Quick bug fix or single-file edit | No |
| Single-session task with clear scope | No |
SESSION.md Principles
- Track progress, not architecture — SESSION.md is a work log, not project documentation
- Concrete over vague — "Resume at
src/auth.ts:42, implement token refresh" beats "Continue auth work"
- Collapse completed work — finished phases become 1-2 line summaries
- Keep under 100 lines — if it's longer, collapse more aggressively
Autonomy Rules
- Just do it: Read SESSION.md, read CLAUDE.md, check git status/log, present summaries
- Brief confirmation: Creating new SESSION.md, committing WIP checkpoints
- Ask first: Overwriting an existing SESSION.md, deleting session data
Reference Files
