Dev Session

Operating Modes

Mode 1: Start Session

1. Check if

   SESSION.md

   already exists in the project root
   • If yes: read it and ask whether to continue the existing session or start fresh
   • If no: create from template (see references/session-template.md)
2. 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
3. Read the project's CLAUDE.md to orient on context
4. Present a brief summary: "Session started. Working on [phase] on branch [branch]."

Mode 2: Checkpoint

1. 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
2. Capture learnings:
   • If any patterns, gotchas, or commands were discovered during work, add them to CLAUDE.md
   • One line per concept — concise, not verbose
3. Git checkpoint:
   bash

   git add -A && git commit -m "WIP: [what was accomplished]"

4. Record the commit hash in SESSION.md under Checkpoint
5. Confirm: "Checkpointed at [hash]. SESSION.md updated."

Mode 3: Resume Session

1. Read

   SESSION.md

   — if missing, inform user and offer to start a new session
2. Read the project's

   CLAUDE.md

   for context
3. Check what's changed since the recorded checkpoint:
   bash

   git log --oneline [checkpoint-hash]..HEAD

4. Check for uncommitted changes:

   git status

5. 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

1. Run a full checkpoint (Mode 2)
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)?
3. If the phase is complete:
   • Collapse the phase summary to 2-3 lines
   • Clear Resume Instructions or note "Phase complete — ready for next phase"
4. Confirm: "Session wrapped. Resume with 'resume session' next time."

When to Use

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