session-resume

Session resume protocol and session repairs handling. Loaded when spellbook_session_init returns resume_available: true, or when session_init returns a repairs array. Triggers: 'resume', 'continue', 'where were we', session resume, session repairs.

5 stars

byaxiomantic

View on GitHub Installation ↓

Best use case

session-resume is best used when you need a repeatable AI agent workflow instead of a one-off prompt.

Teams using session-resume should expect a more consistent output, faster repeated execution, less prompt rewriting.

When to use this skill

You want a reusable workflow that can be run more than once with consistent structure.

When not to use this skill

You only need a quick one-off answer and do not need a reusable workflow.
You cannot install or maintain the underlying files, dependencies, or repository context.

Installation

Claude Code / Cursor / Codex

$curl -o ~/.claude/skills/session-resume/SKILL.md --create-dirs "https://raw.githubusercontent.com/axiomantic/spellbook/main/skills/session-resume/SKILL.md"

Manual Installation

Download SKILL.md from GitHub
Place it in .claude/skills/session-resume/SKILL.md inside your project
Restart your AI agent — it will auto-discover the skill

How session-resume Compares

Feature / Agent	session-resume	Standard Approach
Platform Support	Not specified	Limited / Varies
Context Awareness	High	Baseline
Installation Complexity	Unknown	N/A

Frequently Asked Questions

What does this skill do?

Where can I find the source code?

You can find the source code on GitHub using the link provided at the top of the page.

SKILL.md Source

<analysis>
Protocol for restoring prior session state (skill phase, todos, workflow) and handling session repairs from spellbook_session_init.
</analysis>

<reflection>
Did I execute the boot prompt immediately and announce restoration in the greeting, including any repair items?
</reflection>

## Invariant Principles

1. **Boot Prompt Executes Immediately** - The resume boot prompt runs before any other user interaction; it is not optional or deferrable.
2. **Continuation Intent Governs Action** - The user's first message determines whether to resume, start fresh, or default to resume; never assume.
3. **Corrupted State Is Announced, Not Silently Skipped** - If todos or workflow state is malformed, inform the user explicitly rather than proceeding with partial data.

## Session Resume Protocol

When `spellbook_session_init` returns `resume_available: true`, follow this protocol exactly.

### Resume Fields

| Field                     | Type   | Description                        |
| ------------------------- | ------ | ---------------------------------- |
| `resume_available`        | bool   | Recent session (<24h) exists       |
| `resume_session_id`       | string | Session soul ID                    |
| `resume_age_hours`        | float  | Hours since bound                  |
| `resume_bound_at`         | string | ISO bind timestamp                 |
| `resume_active_skill`     | string | Active skill (e.g., "develop")     |
| `resume_skill_phase`      | string | Skill phase (e.g., "DESIGN")       |
| `resume_pending_todos`    | int    | Incomplete todo count              |
| `resume_todos_corrupted`  | bool   | Todo JSON malformed                |
| `resume_workflow_pattern` | string | Workflow (e.g., "TDD")             |
| `resume_boot_prompt`      | string | Section 0 boot prompt              |

### Resume Execution

1. Execute `resume_boot_prompt` IMMEDIATELY (Section 0 actions)
2. Section 0 includes: skill invocation with `--resume <phase>` if active, `Read()` for planning docs, `TodoWrite()` for todo state, behavioral constraints from prior session
3. After Section 0, announce restoration in greeting

If `resume_todos_corrupted: true`: announce to user that todo state was malformed and requires manual restoration.

### Continuation Detection

| Pattern                                     | Intent      | Action                                        |
| ------------------------------------------- | ----------- | --------------------------------------------- |
| "continue", "resume", "where were we"       | continue    | Execute boot prompt                           |
| "start fresh", "new session", "clean slate" | fresh_start | Skip resume, return `resume_available: false` |
| "ok", "next", neutral message               | neutral     | Execute boot prompt (if session exists)       |

## Session Repairs

When `spellbook_session_init` returns a `repairs` array, display each repair according to its severity:

| Severity  | Action                                                    |
| --------- | --------------------------------------------------------- |
| `error`   | Display prominently. These may affect functionality.      |
| `warning` | Display as informational. Suggest the fix command.        |

### Example Greeting with Repairs

> Welcome to spellbook-enhanced Claude.
>
> Repairs needed:
> - (warnings surfaced by `spellbook_session_init`; suggest each entry's `fix_command`)

Related Skills

session-mode-init

from axiomantic/spellbook

Loaded at session start when spellbook_session_init returns mode data, or when mode.type is 'unset'. Triggers: session init mode handling, '/mode', mode selection, 'fun mode', 'tarot mode'.

rounding-up-worktree-sessions

from axiomantic/spellbook

Use when scattered Claude Code sessions need to be found, grouped by effort, relocated to the right worktree's resume picker, or reopened together. Triggers: 'round up my sessions', 'find my worktree sessions', 'reopen my claude sessions by worktree', 'reorient sessions', 'relaunch sessions', 'resume my recent sessions grouped by worktree', 'my sessions are scattered', 'open all sessions for this effort'. NOT for: relocating a project's sessions because the CODE moved (use move-project); creating worktrees (use using-git-worktrees).

writing-skills

from axiomantic/spellbook

Use when creating new skills, editing existing skills, or verifying skills work before deployment. Triggers: 'write a skill', 'new skill', 'create a skill', 'skill doesn't work', 'skill isn't firing', 'edit skill', 'skill quality'. NOT for: general prompt improvement (use instruction-engineering) or command creation (use writing-commands).

writing-plans

from axiomantic/spellbook

Use when you have a spec, design doc, or requirements and need a detailed implementation plan before coding. Triggers: 'write a plan', 'create implementation plan', 'plan this out', 'break this down into steps', 'convert design to tasks', 'implementation order'. Also invoked by develop during planning. NOT for: reviewing existing plans (use reviewing-impl-plans).

writing-commands

from axiomantic/spellbook

Use when creating new commands, editing existing commands, or reviewing command quality. Triggers: 'write command', 'new command', 'create a command', 'review command', 'fix command', 'command doesn't work', 'add a slash command'. NOT for: skill creation (use writing-skills).

verifying-hunches

from axiomantic/spellbook

Use when about to claim discovery during debugging. Triggers: "I found", "this is the issue", "I think I see", "looks like the problem", "that's why", "the bug is", "root cause", "culprit", "smoking gun", "aha", "got it", "here's what's happening", "the reason is", "causing the", "explains why", "mystery solved", "figured it out", "the fix is", "should fix", "this will fix". Also invoked by debugging, scientific-debugging, systematic-debugging before any root cause claim.

using-skills

from axiomantic/spellbook

System skill loaded at session start to initialize skill routing. Not invoked directly by users. Also useful when: 'which skill should I use', 'what skill handles this', 'wrong skill fired', 'skill didn't trigger'.

using-lsp-tools

from axiomantic/spellbook

Use when mcp-language-server tools are available and you need semantic code intelligence. Triggers: 'find definition', 'find references', 'who calls this', 'rename symbol', 'type hierarchy', 'go to definition', 'where is this used', 'where is this defined', 'what type is this'. Provides navigation, refactoring, and type analysis via LSP.

using-git-worktrees

from axiomantic/spellbook

Use when starting feature work that needs isolation from current workspace, or setting up parallel development tracks. Triggers: 'worktree', 'separate branch', 'isolate this work', 'don't mess up current work', 'work on two things at once', 'parallel workstreams', 'new branch for this', 'keep my current work safe'.

tooling-discovery

from axiomantic/spellbook

Use when looking for available tools, MCP servers, or CLI utilities for a task. Triggers: 'what tools do I have', 'is there an MCP for this', 'what's available', 'find a tool for', 'discover tooling', 'what CLI tools exist'. NOT for: documenting existing tools (use documenting-tools).

testing-strategy

from axiomantic/spellbook

Test selection strategy and scope guidance. Triggers: 'which tests should I run', 'test tiers', 'test marks', 'slow tests', 'integration vs unit', 'cross-module regression', 'test scope', 'what should I run', 'select tests', 'test batching'. NOT for: writing tests (use test-driven-development) or fixing broken tests (use fixing-tests).

test-driven-development

from axiomantic/spellbook

Use when user explicitly requests test-driven development. Triggers: 'TDD', 'write tests first', 'red green refactor', 'test-first', 'start with the test'. Also invoked by develop and executing-plans for implementation tasks. NOT for: full feature work (use develop, which includes TDD internally).