Agent Session Continuity

The Problem

You spent 45 minutes last session debugging a subtle race condition in the payment flow, decided to use PostgreSQL LISTEN/NOTIFY over Redis Pub/Sub, and had the agent create three new files. Today you open a new session and say "continue working on the payment integration." The agent responds: "I don't have context from previous sessions. Could you describe what you're building?" You just lost 15 minutes re-explaining what the agent already knew.

What You Get

• Session journal system — structured .claude/session-journal.md (or equivalent) that captures Accomplished, In Progress, Open Decisions, Files Created/Modified, and Next Steps at every session end
• Machine-readable state file — .claude/state.json tracks last session timestamp, current feature, feature status, blockers, test status, and next steps in a parseable format
• Architecture Decision Records (ADR) — session decisions are captured in .claude/decisions/ with context, alternatives considered, decision rationale, and consequences
• Automatic session start context — agent reads journal + state + ADRs at session start and summarizes the last session in 1-3 sentences without being prompted
• Contradiction detection — when the agent is about to make a decision that conflicts with a prior ADR, it flags the contradiction and asks for confirmation
• Agent-agnostic directory structure — works across Claude Code (.claude/), Cursor (.cursor/), and Codex CLI (.codex/) with automatic directory detection

Why This Beats Prompting It Yourself

You could write "remember our last session" in your CLAUDE.md. But the agent has no structured mechanism to read what "last session" contained. This skill creates the file system infrastructure — journal, state file, ADRs — that gives the agent something concrete to read, parse, and act on. Without structured files, context continuity is hope, not architecture.

Example Session

You: "Continue working on the payment integration"

Agent: [Reads .claude/session-journal.md] "Last session (July 10): Completed Stripe checkout session creation and webhook handler. In progress: subscription management (~60% done). Blocked on: refresh token storage strategy — you wanted httpOnly cookies but security review hasn't happened yet.

Next steps: Complete subscription management in src/billing/subscriptions.ts, handle Stripe webhook signature verification, add idempotency keys.

Shall I pick up from subscription management?"

You: "Yes, and let's use httpOnly cookies for the token"

Agent: "I'll implement httpOnly cookies. I'm writing ADR-003 to document this decision — httpOnly cookies selected over localStorage because they prevent XSS-based token theft, consistent with our security-first approach noted in ADR-001."

Use Cases

• Multi-session feature development where context carries across days
• Team projects where different developers pick up where others left off
• Complex architectural work where decisions need to be traced back to rationale
• Long-running refactors that span weeks and require consistent direction
• Switching between projects and needing quick re-orientation when returning

Known Limitations

The session journal grows over time — without periodic pruning, the agent may take longer to process stale context. State files may become inconsistent if the agent crashes mid-write. This skill works best when you explicitly end sessions with "that's enough for today" rather than abrupt disconnects, though the agent is trained to write state before any exit.