feat: add resume and save session commands for session management

commands/resume-session.md

@@ -0,0 +1,156 @@
+---
+description: Load the most recent session file from .claude/sessions/ in the current project (or ~/.claude/sessions/ globally) 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/ (project level)
+/resume-session 2024-01-15                                           # loads most recent session for that date
+/resume-session .claude/sessions/2024-01-15-abc123-session.tmp      # loads specific file path
+/resume-session ~/.claude/sessions/2024-01-15-abc123-session.tmp    # loads from global location
+```
+
+## Process
+
+### Step 1: Find the session file
+
+If no argument provided:
+
+1. First check `.claude/sessions/` in the current project directory
+2. If not found there, fall back to `~/.claude/sessions/`
+3. Pick the most recently modified `.tmp` file from whichever location has files
+4. If neither folder exists or both are empty, tell the user:
+   ```
+   No session files found in .claude/sessions/ or ~/.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`), search `.claude/sessions/` first then `~/.claude/sessions/` for files matching
+  `YYYY-MM-DD-session.tmp` (old format) or `YYYY-MM-DD-<shortid>-session.tmp` (new format)
+  and load the most recently modified variant for that date
+- 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: [actual resolved path to the file]
+════════════════════════════════════════════════
+
+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-session.tmp`, `2024-01-15-abc123-session.tmp`):
+Load the most recently modified file for that date.
+
+**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 more than 7 days ago:**
+Note the gap — "⚠️ This session is from N days ago (threshold: 7 days). 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-abc123-session.tmp
+════════════════════════════════════════════════
+
+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