feat: add resume and save session commands for session management

Introduced two new commands: `/resume-session` and `/save-session`. The `/resume-session` command allows users to load the most recent session file or a specific session file, providing a structured briefing of the session's context. The `/save-session` command captures the current session state, saving it to a dated file for future reference. Both commands enhance user experience by enabling seamless session continuity and context preservation.
2026-03-30 21:53:28 +08:00 · 2026-03-09 12:30:40 +05:30
parent 0c2954565d
commit 6937491d2a
2 changed files with 411 additions and 0 deletions
--- a/commands/resume-session.md
+++ b/commands/resume-session.md
@@ -0,0 +1,150 @@
+---
+description: Load the most recent session file from .claude/sessions/ and resume work with full context from where the last session ended.
+---
+
+# Resume Session Command
+
+Load the last saved session state and orient fully before doing any work.
+This command is the counterpart to `/save-session`.
+
+## When to Use
+
+- Starting a new session to continue work from a previous day
+- After starting a fresh session due to context limits
+- When handing off a session file from another source (just provide the file path)
+- Any time you have a session file and want Claude to fully absorb it before proceeding
+
+## Usage
+
+```
+/resume-session                          # loads most recent file in .claude/sessions/
+/resume-session 2024-01-15               # loads specific date
+/resume-session .claude/sessions/foo.md  # loads specific file path
+```
+
+## Process
+
+### Step 1: Find the session file
+
+If no argument provided:
+1. List all files in `.claude/sessions/`
+2. Pick the most recently modified file
+3. If the folder doesn't exist or is empty, tell the user:
+   ```
+   No session files found in .claude/sessions/
+   Run /save-session at the end of a session to create one.
+   ```
+   Then stop.
+
+If an argument is provided:
+- If it looks like a date (`YYYY-MM-DD`), look for `.claude/sessions/YYYY-MM-DD.md`
+- If it looks like a file path, read that file directly
+- If not found, report clearly and stop
+
+### Step 2: Read the entire session file
+
+Read the complete file. Do not summarize yet.
+
+### Step 3: Confirm understanding
+
+Respond with a structured briefing in this exact format:
+
+```
+SESSION LOADED: .claude/sessions/YYYY-MM-DD.md
+════════════════════════════════════════════════
+
+PROJECT: [project name / topic from file]
+
+WHAT WE'RE BUILDING:
+[2-3 sentence summary in your own words]
+
+CURRENT STATE:
+✅ Working: [count] items confirmed
+🔄 In Progress: [list files that are in progress]
+🗒️ Not Started: [list planned but untouched]
+
+WHAT NOT TO RETRY:
+[list every failed approach with its reason — this is critical]
+
+OPEN QUESTIONS / BLOCKERS:
+[list any blockers or unanswered questions]
+
+NEXT STEP:
+[exact next step if defined in the file]
+[if not defined: "No next step defined — recommend reviewing 'What Has NOT Been Tried Yet' together before starting"]
+
+════════════════════════════════════════════════
+Ready to continue. What would you like to do?
+```
+
+### Step 4: Wait for the user
+
+Do NOT start working automatically. Do NOT touch any files. Wait for the user to say what to do next.
+
+If the next step is clearly defined in the session file and the user says "continue" or "yes" or similar — proceed with that exact next step.
+
+If no next step is defined — ask the user where to start, and optionally suggest an approach from the "What Has NOT Been Tried Yet" section.
+
+---
+
+## Edge Cases
+
+**Multiple sessions for the same date** (`2024-01-15.md`, `2024-01-15-2.md`):
+Load the highest-numbered file (most recent).
+
+**Session file references files that no longer exist:**
+Note this during the briefing — "⚠️ `path/to/file.ts` referenced in session but not found on disk."
+
+**Session file is from a very old date:**
+Note the gap — "⚠️ This session is from X days ago. Things may have changed." — then proceed normally.
+
+**User provides a file path directly (e.g., forwarded from a teammate):**
+Read it and follow the same briefing process — the format is the same regardless of source.
+
+**Session file is empty or malformed:**
+Report: "Session file found but appears empty or unreadable. You may need to create a new one with /save-session."
+
+---
+
+## Example Output
+
+```
+SESSION LOADED: .claude/sessions/2024-01-15.md
+════════════════════════════════════════════════
+
+PROJECT: my-app — JWT Authentication
+
+WHAT WE'RE BUILDING:
+User authentication with JWT tokens stored in httpOnly cookies.
+Register and login endpoints are partially done. Route protection
+via middleware hasn't been started yet.
+
+CURRENT STATE:
+✅ Working: 3 items (register endpoint, JWT generation, password hashing)
+🔄 In Progress: app/api/auth/login/route.ts (token works, cookie not set yet)
+🗒️ Not Started: middleware.ts, app/login/page.tsx
+
+WHAT NOT TO RETRY:
+❌ Next-Auth — conflicts with custom Prisma adapter, threw adapter error on every request
+❌ localStorage for JWT — causes SSR hydration mismatch, incompatible with Next.js
+
+OPEN QUESTIONS / BLOCKERS:
+- Does cookies().set() work inside a Route Handler or only Server Actions?
+
+NEXT STEP:
+In app/api/auth/login/route.ts — set the JWT as an httpOnly cookie using
+cookies().set('token', jwt, { httpOnly: true, secure: true, sameSite: 'strict' })
+then test with Postman for a Set-Cookie header in the response.
+
+════════════════════════════════════════════════
+Ready to continue. What would you like to do?
+```
+
+---
+
+## Notes
+
+- Never modify the session file when loading it — it's a read-only historical record
+- The briefing format is fixed — do not skip sections even if they are empty
+- "What Not To Retry" must always be shown, even if it just says "None" — it's too important to miss
+- After resuming, the user may want to run `/save-session` again at the end of the new session to create a new dated file
--- a/commands/save-session.md
+++ b/commands/save-session.md
@@ -0,0 +1,261 @@
+---
+description: Save current session state to a dated file in .claude/sessions/ so work can be resumed in a future session with full context.
+---
+
+# Save Session Command
+
+Capture everything that happened in this session — what was built, what worked, what failed, what's left — and write it to a dated file so the next session can pick up exactly where this one left off.
+
+## When to Use
+
+- End of a work session before closing Claude Code
+- Before hitting context limits (run this first, then start a fresh session)
+- After solving a complex problem you want to remember
+- Any time you need to hand off context to a future session
+
+## Process
+
+### Step 1: Gather context
+
+Before writing the file, collect:
+
+- Read all files modified during this session (use git diff or recall from conversation)
+- Review what was discussed, attempted, and decided
+- Note any errors encountered and how they were resolved (or not)
+- Check current test/build status if relevant
+
+### Step 2: Create the sessions folder if it doesn't exist
+
+```bash
+mkdir -p .claude/sessions
+```
+
+### Step 3: Write the session file
+
+Create `.claude/sessions/YYYY-MM-DD.md` using today's actual date.
+
+If a file for today already exists (multiple sessions in one day), name it `YYYY-MM-DD-2.md`, `YYYY-MM-DD-3.md`, etc.
+
+### Step 4: Populate the file with all sections below
+
+Write every section honestly. Do not skip sections — write "Nothing yet" or "N/A" if a section genuinely has no content. An incomplete file is worse than an honest empty section.
+
+### Step 5: Show the file to the user
+
+After writing, display the full contents and ask:
+
+```
+Session saved to .claude/sessions/YYYY-MM-DD.md
+
+Does this look accurate? Anything to correct or add before we close?
+```
+
+Wait for confirmation. Make edits if requested.
+
+---
+
+## Session File Format
+
+```markdown
+# Session: YYYY-MM-DD
+**Started:** [approximate time if known]
+**Last Updated:** [current time]
+**Project:** [project name or path]
+**Topic:** [one-line summary of what this session was about]
+
+---
+
+## What We Are Building
+
+[1-3 paragraphs describing the feature, bug fix, or task. Include enough
+context that someone with zero memory of this session can understand the goal.
+Include: what it does, why it's needed, how it fits into the larger system.]
+
+---
+
+## What WORKED (with evidence)
+
+[List only things that are confirmed working. For each item include WHY you
+know it works — test passed, ran in browser, Postman returned 200, etc.
+Without evidence, move it to "Not Tried Yet" instead.]
+
+- **[thing that works]** — confirmed by: [specific evidence]
+- **[thing that works]** — confirmed by: [specific evidence]
+
+If nothing is confirmed working yet: "Nothing confirmed working yet — all approaches still in progress or untested."
+
+---
+
+## What Did NOT Work (and why)
+
+[This is the most important section. List every approach tried that failed.
+For each failure write the EXACT reason so the next session doesn't retry it.
+Be specific: "threw X error because Y" is useful. "didn't work" is not.]
+
+- **[approach tried]** — failed because: [exact reason / error message]
+- **[approach tried]** — failed because: [exact reason / error message]
+
+If nothing failed: "No failed approaches yet."
+
+---
+
+## What Has NOT Been Tried Yet
+
+[Approaches that seem promising but haven't been attempted. Ideas from the
+conversation. Alternative solutions worth exploring. Be specific enough that
+the next session knows exactly what to try.]
+
+- [approach / idea]
+- [approach / idea]
+
+If nothing is queued: "No specific untried approaches identified."
+
+---
+
+## Current State of Files
+
+[Every file touched this session. Be precise about what state each file is in.]
+
+| File | Status | Notes |
+|------|--------|-------|
+| `path/to/file.ts` | ✅ Complete | [what it does] |
+| `path/to/file.ts` | 🔄 In Progress | [what's done, what's left] |
+| `path/to/file.ts` | ❌ Broken | [what's wrong] |
+| `path/to/file.ts` | 🗒️ Not Started | [planned but not touched] |
+
+If no files were touched: "No files modified this session."
+
+---
+
+## Decisions Made
+
+[Architecture choices, tradeoffs accepted, approaches chosen and why.
+These prevent the next session from relitigating settled decisions.]
+
+- **[decision]** — reason: [why this was chosen over alternatives]
+
+If no significant decisions: "No major decisions made this session."
+
+---
+
+## Blockers & Open Questions
+
+[Anything unresolved that the next session needs to address or investigate.
+Questions that came up but weren't answered. External dependencies waiting on.]
+
+- [blocker / open question]
+
+If none: "No active blockers."
+
+---
+
+## Exact Next Step
+
+[If known: The single most important thing to do when resuming. Be precise
+enough that resuming requires zero thinking about where to start.]
+
+[If not known: "Next step not determined — review 'What Has NOT Been Tried Yet'
+and 'Blockers' sections to decide on direction before starting."]
+
+---
+
+## Environment & Setup Notes
+
+[Only fill this if relevant — commands needed to run the project, env vars
+required, services that need to be running, etc. Skip if standard setup.]
+
+[If none: omit this section entirely.]
+```
+
+---
+
+## Example Output
+
+```markdown
+# Session: 2024-01-15
+**Started:** ~2pm
+**Last Updated:** 5:30pm
+**Project:** my-app
+**Topic:** Building JWT authentication with httpOnly cookies
+
+---
+
+## What We Are Building
+
+User authentication system for the Next.js app. Users register with email/password,
+receive a JWT stored in an httpOnly cookie (not localStorage), and protected routes
+check for a valid token via middleware. The goal is session persistence across browser
+refreshes without exposing the token to JavaScript.
+
+---
+
+## What WORKED (with evidence)
+
+- **`/api/auth/register` endpoint** — confirmed by: Postman POST returns 200 with user
+  object, row visible in Supabase dashboard, bcrypt hash stored correctly
+- **JWT generation in `lib/auth.ts`** — confirmed by: unit test passes
+  (`npm test -- auth.test.ts`), decoded token at jwt.io shows correct payload
+- **Password hashing** — confirmed by: `bcrypt.compare()` returns true in test
+
+---
+
+## What Did NOT Work (and why)
+
+- **Next-Auth library** — failed because: conflicts with our custom Prisma adapter,
+  threw "Cannot use adapter with credentials provider in this configuration" on every
+  request. Not worth debugging — too opinionated for our setup.
+- **Storing JWT in localStorage** — failed because: SSR renders happen before
+  localStorage is available, caused React hydration mismatch error on every page load.
+  This approach is fundamentally incompatible with Next.js SSR.
+
+---
+
+## What Has NOT Been Tried Yet
+
+- Store JWT as httpOnly cookie in the login route response (most likely solution)
+- Use `cookies()` from `next/headers` to read token in server components
+- Write middleware.ts to protect routes by checking cookie existence
+
+---
+
+## Current State of Files
+
+| File | Status | Notes |
+|------|--------|-------|
+| `app/api/auth/register/route.ts` | ✅ Complete | Works, tested |
+| `app/api/auth/login/route.ts` | 🔄 In Progress | Token generates but not setting cookie yet |
+| `lib/auth.ts` | ✅ Complete | JWT helpers, all tested |
+| `middleware.ts` | 🗒️ Not Started | Route protection, needs cookie read logic first |
+| `app/login/page.tsx` | 🗒️ Not Started | UI not started |
+
+---
+
+## Decisions Made
+
+- **httpOnly cookie over localStorage** — reason: prevents XSS token theft, works with SSR
+- **Custom auth over Next-Auth** — reason: Next-Auth conflicts with our Prisma setup, not worth the fight
+
+---
+
+## Blockers & Open Questions
+
+- Does `cookies().set()` work inside a Route Handler or only in Server Actions? Need to verify.
+
+---
+
+## Exact Next Step
+
+In `app/api/auth/login/route.ts`, after generating the JWT, set it as an httpOnly
+cookie using `cookies().set('token', jwt, { httpOnly: true, secure: true, sameSite: 'strict' })`.
+Then test with Postman — the response should include a `Set-Cookie` header.
+```
+
+---
+
+## Notes
+
+- Each session gets its own file — never append to a previous session's file
+- The "What Did NOT Work" section is the most critical — future sessions will blindly retry failed approaches without it
+- If the user asks to save mid-session (not just at the end), save what's known so far and mark in-progress items clearly
+- The file is meant to be read by Claude at the start of the next session via `/resume-session`
+- Keep this file in `.claude/sessions/` — add that folder to `.gitignore` if session logs shouldn't be committed