checkpoint-workflow
Enforces incremental saving during complex tasks to prevent progress loss. Use this skill whenever working on multi-step tasks, creating multiple files, or doing work that takes more than 5 minutes. Triggers on: file creation, documentation updates, code changes, workflow execution, any task with multiple steps.
When & Why to Use This Skill
The Checkpoint Workflow skill is a robust framework designed to ensure data integrity and progress persistence for Claude agents during complex, multi-step operations. By enforcing a 'checkpoint early, checkpoint often' philosophy, it utilizes incremental Git commits and structured progress logging to eliminate the risk of context loss and enable seamless recovery from task interruptions.
Use Cases
- Large-scale Software Refactoring: Automatically committing code changes and updating a PROGRESS.md file after every few files to ensure no work is lost during long coding sessions.
- Multi-phase Research Projects: Maintaining a persistent journal of findings and 'Next Actions' to allow the agent to resume exactly where it left off after a context reset.
- Complex System Migrations: Creating pre-operation snapshots and documenting state changes during infrastructure updates to provide a clear audit trail and recovery path.
- Automated Content Creation: Saving drafts and updating status logs during the generation of multi-chapter documentation or extensive technical guides.
| name | checkpoint-workflow |
|---|---|
| description | Enforces incremental saving during complex tasks to prevent progress loss. Use this skill whenever working on multi-step tasks, creating multiple files, or doing work that takes more than 5 minutes. Triggers on: file creation, documentation updates, code changes, workflow execution, any task with multiple steps. |
Checkpoint Workflow Skill
Core Principle
CHECKPOINT EARLY, CHECKPOINT OFTEN
Never accumulate more than 5 minutes of unsaved work. Every significant unit of work must be persisted before moving to the next.
Checkpoint Triggers
Create a checkpoint when:
- After creating ANY file → commit immediately
- After completing a subtask → update PROGRESS.md + commit
- Before starting a new phase → save current state
- Every 3-5 tool calls → update progress journal
- Before complex operations → pre-operation snapshot
Required Actions
After Every 2-3 Files Created
git add <files>
git commit -m "checkpoint: <brief description>"
git push origin main
Before and After Major Steps
Update docs/claude-integration/PROGRESS.md:
### Completed Steps:
- [x] Step description (commit: abc123)
### Current State:
- Working on: [specific item]
- Next action: [what comes next]
Commit Message Prefixes
checkpoint:- Work in progresswip:- May not build/workprogress:- Incremental progresssave:- Explicit save point
Recovery Protocol
On context loss or "continue" request:
- Read
docs/claude-integration/PROGRESS.md - Check
git log --oneline -10 - Check
/mnt/transcripts/[latest].txt - Resume from documented "Next Actions"
- Update PROGRESS.md before continuing
Anti-Patterns to Avoid
❌ Creating 10 files then committing all at once ❌ Completing entire task before documenting ❌ Starting context-heavy operations without saving first ❌ Ignoring PROGRESS.md updates
Sample Workflow
1. START TASK
└─> Update PROGRESS.md: "Starting task X"
└─> git commit -m "checkpoint: starting task X"
2. SUBTASK A (2-3 files)
└─> Create files
└─> git commit -m "checkpoint: completed subtask A"
└─> Update PROGRESS.md
3. SUBTASK B (2-3 files)
└─> Create files
└─> git commit -m "checkpoint: completed subtask B"
└─> Update PROGRESS.md
4. COMPLETE
└─> git commit -m "feat: complete task X"
└─> Update PROGRESS.md: "COMPLETE"