save-state— agent skill

Dump the current working context into production/session-state/active.md as a session checkpoint, AND write an atomic per-task checkpoint to .tasks/checkpoints/[task_id].md when a task ID is provided.

Session checkpoint is automatically read by session-start.sh at the next session start and surfaced by pre-compact.sh before context compaction. Per-task checkpoints are used by /resume-from [task_id] to restore granular cognitive state at the exact point of failure.

Steps

1. Parse arguments

Parse $ARGUMENTS to extract:

• task_id (optional): First token matching pattern ^\d{3} or a word without spaces (e.g. 042, auth-api). If present, an atomic checkpoint will be written.
• note (optional): Remaining text after task_id, used as a note.

2. Gather context

Before writing anything, collect the following from the current conversation and working state:

• Current task: What is the primary task being worked on right now?
• agent_id: Which agent is currently executing (e.g. backend-developer, qa-engineer)?
• Progress: What has been completed in this session? List key milestones.
• Decisions made: What architectural, design, or implementation decisions were made? (These are the most important to preserve.)
• Files modified: Run git diff --name-only && git diff --staged --name-only && git ls-files --others --exclude-standard to get the current working tree state.
• output_snapshot: A concise snapshot of the last significant output — last file written, last test result, last API response shape, or last command output.
• Open questions: What is unresolved or blocked?
• Next step: What is the very next action to take when resuming.

If a note was parsed from $ARGUMENTS, append it to the "Notes" section.

2. Extract Durable Memory (Native System)

Are there any lessons learned, coding patterns established, constraints added, or technical decisions made in this session that apply globally to the project? If so, before writing active.md, extract them to the .claude/memory/ directory:

• Write or update a specific topic file (e.g. project_tech_decisions.md or feedback_rules.md), ensuring it has the required YAML frontmatter (name, description, type).
• Update .claude/memory/MEMORY.md with a pointer to that file if it's not already listed.

3. Write production/session-state/active.md

Overwrite the file with this structure:

# Session State

> Saved: [ISO timestamp]
> Branch: [current git branch]

## Current Task

[One sentence describing what is being worked on]

<!-- STATUS -->
Epic: [epic name or leave blank]
Feature: [feature name or leave blank]
Task: [specific task or leave blank]
<!-- /STATUS -->

## Progress (This Session)

[Bulleted list of what was completed]

## Key Decisions Made

[Bulleted list — include the decision AND the rationale. These survive context loss.]

## Files Being Actively Worked On

[List of files currently modified or in progress]

## Open Questions / Blockers

[List of unresolved items. Mark with [BLOCKED] if waiting on someone.]

## Next Step

[The single most important next action to take when resuming]

## Notes

[$ARGUMENTS if provided, otherwise omit this section]

4. Write Atomic Checkpoint (only if task_id was provided)

If a task_id was parsed in Step 1, write .tasks/checkpoints/[task_id].md:

---
task_id: [task_id]
agent_id: [agent currently executing]
saved_at: [ISO timestamp]
status: in_progress
retry_count: 0
backoff_next_s: 2
---

# Checkpoint: [task_id]

## Output Snapshot

[Concise snapshot of the last significant output — last file written, last test result,
last command output, or last API response shape. Max 10 lines.]

## Completed Steps

[Bulleted list of sub-steps already done within this task]

## Next Step

[The exact next action to resume from — be specific enough that a cold-start agent can continue]

## Open Questions

[Unresolved items blocking progress, if any]

## Files Modified

[List of files touched so far in this task]

5. Confirm

Print:

✅ Session state saved → production/session-state/active.md
[If task checkpoint written]: ✅ Atomic checkpoint saved → .tasks/checkpoints/[task_id].md
[If memory was extracted]:    ✅ Durable memories updated → .claude/memory/MEMORY.md

To resume this task: /resume-from [task_id]
To resume session:   read production/session-state/active.md first

When to run /save-state

• Before /clear or starting a new unrelated task
• When context usage feels high (>60%)
• After completing a major milestone (phase, feature, design section)
• Before ending a work session
• When pre-compact.sh warns about no active session state
• After any agent failure — pass the task_id to create a recoverable checkpoint

The session-start.sh hook automatically detects and previews active.md at the start of each new session. The pre-compact.sh hook reads it before compaction to inject it into the summary. Use /resume-from [task_id] to recover a specific task without re-reading the full session.