The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat: add resume and save session commands for session management
avesh-devx6937491d2a78
diff --git a/commands/resume-session.md b/commands/resume-session.mdnew file mode 100644index 000000000..b33da0cc8--- /dev/null+++ 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 filediff --git a/commands/save-session.md b/commands/save-session.mdnew file mode 100644index 000000000..84254e1e3--- /dev/null+++ 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