docs: Explain why /save and /load fill a native gap

- Add "Why This Exists" sections to save.md and load.md
- Add "Session Continuity" section to README
- Cite Anthropic's long-running agents article
- Explain TodoWrite state doesn't persist natively
- Compare with native --resume functionality

Reference: https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

README.md

@@ -97,6 +97,43 @@ Then symlink or copy to your Claude directories:
 | [tailwind-expert](agents/tailwind-expert.md) | Tailwind CSS, responsive design |
 | [wrangler-expert](agents/wrangler-expert.md) | Cloudflare Workers deployment, wrangler.toml |
 
+## Session Continuity: `/save` + `/load`
+
+These commands fill a gap in Claude Code's native session management.
+
+**The problem:** Claude Code's `--resume` flag restores conversation history, but **TodoWrite task state does not persist between sessions**. When you start fresh, your task list is gone.
+
+**The solution:** `/save` and `/load` implement the pattern from Anthropic's [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents):
+
+> "Every subsequent session asks the model to make incremental progress, then leave structured updates."
+
+### How It Works
+
+```
+Session 1:
+  [work on tasks]
+  /save "Stopped at auth module"    # Writes .claude/claude-state.json + claude-progress.md
+
+Session 2:
+  /load                              # Restores TodoWrite, shows git diff, suggests next action
+  → "In progress: Auth module refactor"
+  → "Notes: Stopped at auth module"
+```
+
+### Why Not Just Use `--resume`?
+
+| Feature | `--resume` | `/save` + `/load` |
+|---------|------------|-------------------|
+| Conversation history | Yes | No |
+| TodoWrite tasks | **No** | Yes |
+| Git context | No | Yes |
+| Human-readable summary | No | Yes |
+| Git-trackable | No | Yes |
+| Works across machines | No | Yes (if committed) |
+| Team sharing | No | Yes |
+
+**Use both together:** `claude --resume` for conversation context, `/load` for task state.
+
 ## Updating
 
 Pull updates including submodules:

commands/load.md

@@ -6,6 +6,31 @@ description: "Load session context from saved state. Reads claude-state.json and
 
 Load your session context from a previous save. Reads state files, shows what's changed since, and suggests the next action.
 
+## Why This Exists
+
+This command pairs with `/save` to implement structured session continuity. While Claude Code's `--resume` restores conversation history, it **does not restore TodoWrite task state**.
+
+From Anthropic's [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents):
+
+> "Every subsequent session asks the model to make incremental progress, then leave structured updates."
+
+`/load` reads those structured updates and restores your working context:
+- **Tasks** are restored to TodoWrite
+- **Git context** shows what changed since you left
+- **Notes** remind you where you stopped
+- **Suggested action** helps you pick up immediately
+
+### How It Differs from `--resume`
+
+| `claude --resume` | `/load` |
+|-------------------|---------|
+| Restores conversation history | Restores task state from files |
+| Local to your machine | Portable (git-trackable) |
+| Automatic | Explicit (you control when) |
+| Full context | Structured summary |
+
+**Use both together**: `claude --resume` for conversation context, `/load` for task state.
+
 ## Arguments
 
 $ARGUMENTS

commands/save.md

@@ -6,6 +6,33 @@ description: "Save session state before ending. Creates claude-state.json and cl
 
 Save your current session state before ending work. Creates both machine-readable and human-readable progress files.
 
+## Why This Exists
+
+Claude Code's native `--resume` flag restores conversation history, but **TodoWrite state does not persist between sessions**. When you start a new session, your task list is gone.
+
+This command implements the pattern described in Anthropic's [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents):
+
+> "Every subsequent session asks the model to make incremental progress, then leave structured updates."
+
+### The Gap
+
+| Feature | Native `--resume` | `/save` + `/load` |
+|---------|-------------------|-------------------|
+| Conversation history | Yes | No |
+| TodoWrite tasks | **No** | Yes |
+| Git context | No | Yes |
+| Human-readable summary | No | Yes |
+| Git-trackable | No | Yes |
+| Works across machines | No | Yes (if committed) |
+| Team sharing | No | Yes |
+
+### When to Use
+
+- **End of work session** - Save before closing Claude Code
+- **Before context compaction** - Preserve state before `/compact`
+- **Handoff to teammates** - Commit state files for others to load
+- **Long-running tasks** - Checkpoint progress incrementally
+
 ## Arguments
 
 $ARGUMENTS