diff --git a/commands/resume-session.md b/commands/resume-session.md new file mode 100644 index 000000000..5f84cf610 --- /dev/null +++ b/commands/resume-session.md @@ -0,0 +1,155 @@ +--- +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 most recent session for that date +/resume-session ~/.claude/sessions/2024-01-15-session.tmp # loads a specific legacy-format file +/resume-session ~/.claude/sessions/2024-01-15-abc123de-session.tmp # loads a current short-id session file +``` + +## Process + +### Step 1: Find the session file + +If no argument provided: + +1. Check `~/.claude/sessions/` +2. Pick the most recently modified `*-session.tmp` file +3. If the folder does not exist or has no matching files, 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`), search `~/.claude/sessions/` for files matching + `YYYY-MM-DD-session.tmp` (legacy format) or `YYYY-MM-DD--session.tmp` (current 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-abc123de-session.tmp`): +Load the most recently modified matching file for that date, regardless of whether it uses the legacy no-id format or the current short-id format. + +**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: /Users/you/.claude/sessions/2024-01-15-abc123de-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 diff --git a/commands/save-session.md b/commands/save-session.md new file mode 100644 index 000000000..676d74cdd --- /dev/null +++ b/commands/save-session.md @@ -0,0 +1,275 @@ +--- +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 + +Create the canonical sessions folder in the user's Claude home directory: + +```bash +mkdir -p ~/.claude/sessions +``` + +### Step 3: Write the session file + +Create `~/.claude/sessions/YYYY-MM-DD--session.tmp`, using today's actual date and a short-id that satisfies the rules enforced by `SESSION_FILENAME_REGEX` in `session-manager.js`: + +- Allowed characters: lowercase `a-z`, digits `0-9`, hyphens `-` +- Minimum length: 8 characters +- No uppercase letters, no underscores, no spaces + +Valid examples: `abc123de`, `a1b2c3d4`, `frontend-worktree-1` +Invalid examples: `ABC123de` (uppercase), `short` (under 8 chars), `test_id1` (underscore) + +Full valid filename example: `2024-01-15-abc123de-session.tmp` + +The legacy filename `YYYY-MM-DD-session.tmp` is still valid, but new session files should prefer the short-id form to avoid same-day collisions. + +### 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 [actual resolved path to the session file] + +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` +- Use the canonical global session store: `~/.claude/sessions/` +- Prefer the short-id filename form (`YYYY-MM-DD--session.tmp`) for any new session file