Checkpoint Automation Skill

How to Use This Skill

Review the patterns and examples below
Apply the relevant patterns to your implementation
Follow the best practices outlined in this skill

Automated checkpoint creation system for session preservation and context continuity. Creates timestamped markdown documents, manages git commits, handles multi-submodule repositories, and provides comprehensive audit trails.

When to Use This Skill

✅ Use this skill when:

Ending a development session and want to preserve context
Completing a sprint or significant milestone
Need to create recovery point before risky operations
Working across multiple submodules needing synchronized commits
Want automatic TASKLIST and PROJECT-PLAN updates
Need audit trail for checkpoint operations
Preparing handoff documentation for team members

❌ Don't use this skill when:

Just need simple git commit (use /commit instead)
Only exporting conversation (use /export instead)
Need full repository sync (use /git-sync instead)
Creating documentation (use /document instead)

What It Automates

Before: (Manual checkpoint)

# Manually create checkpoint document
vim MEMORY-CONTEXT/checkpoints/2025-12-11-checkpoint.md
# Write summary, git status, next steps...
# Then commit
git add .
git commit -m "Checkpoint: work done"
# Update README, TASKLIST...
# Handle submodules separately...

After: (Automated)

# Single command creates everything
python3 scripts/create-checkpoint.py "Sprint 3 complete" --auto-commit

# Result:
# ✅ Timestamped checkpoint document created
# ✅ Git status and diff captured
# ✅ Recent commits summarized
# ✅ All changes committed
# ✅ TASKLIST references updated
# ✅ Next session context prepared

Usage

Basic Checkpoint

cd /path/to/project
python3 scripts/create-checkpoint.py "Feature implementation complete"
# Output: context-storage/checkpoints/2025-12-11T08-30-00Z-feature-implementation-complete.md

Auto-Commit Checkpoint

python3 scripts/create-checkpoint.py "Sprint 3 done" --auto-commit
# Creates checkpoint AND commits to git with standard message

Multi-Submodule Checkpoint

python3 scripts/checkpoint-with-submodules.py "Cross-repo sync"
# 1. Detects all modified submodules
# 2. Commits each submodule independently
# 3. Pushes each to remote
# 4. Updates parent with submodule pointers
# 5. Commits and pushes parent
# 6. Generates audit report

Checkpoint Without Commit

python3 scripts/create-checkpoint.py "WIP snapshot" --no-commit
# Creates checkpoint file only (no git operations)

Output Format

Checkpoint Document

# Session Checkpoint: 2025-12-11T08-30-00Z

## Sprint: Feature implementation complete

## Work Completed
- Implemented user authentication module
- Added JWT token validation
- Created login/logout endpoints
- Updated API documentation

## Git Status
- **Branch:** main
- **Recent Commits:**
  - abc1234: feat: Add auth middleware
  - def5678: test: Add auth unit tests
- **Uncommitted Changes:** 3 files

## Updated Files
| File | Changes |
|------|---------|
| src/auth/middleware.py | +156 -12 |
| tests/test_auth.py | +89 -0 |
| docs/API.md | +34 -5 |

## Next Steps
1. Implement password reset flow
2. Add rate limiting to auth endpoints
3. Create admin user management

## Context for Next Session
- **Key Decisions:** JWT over sessions, bcrypt for passwords
- **Important Files:** src/auth/*, config/auth.yaml
- **Dependencies Added:** PyJWT, bcrypt

---
Generated: 2025-12-11T08:30:00Z
Script: create-checkpoint.py
Framework: CODITECT

Audit Report (Multi-Submodule)

{
  "timestamp": "2025-12-11T08-30-00Z",
  "sprint_description": "Cross-repo sync",
  "repo_root": "/path/to/master",
  "operations": [
    {"repo": "submodules/core", "operation": "commit", "status": "success"},
    {"repo": "submodules/core", "operation": "push", "status": "success"},
    {"repo": "submodules/cloud", "operation": "commit", "status": "success"},
    {"repo": "submodules/cloud", "operation": "push", "status": "success"},
    {"repo": "parent", "operation": "commit", "status": "success"},
    {"repo": "parent", "operation": "push", "status": "success"}
  ],
  "operation_summary": {
    "total_operations": 6,
    "by_status": {"success": 6, "error": 0}
  }
}

Slash Command

/checkpoint "Sprint description" [--auto-commit] [--with-submodules]

Options:

--auto-commit: Commit checkpoint to git
--no-commit: Create file only, no git
--with-submodules: Handle multi-repo commits
--repo-root PATH: Custom repository root

Integration with CODITECT

Workflow:

/export                                    # Export session
/cx                                        # Process into unified store
/checkpoint "Session work" --auto-commit   # Create checkpoint

Related Commands:

/export - Export conversation before checkpoint
/cx - Process exports for context preservation
/git-sync - Full multi-repo synchronization
/commit - Simple git commit

Related Skills:

git-workflow-automation - Git operations
session-analysis - Session indexing
context-save / context-restore - Context management

Technical Details

Scripts:

scripts/create-checkpoint.py - Single repository checkpoints
scripts/checkpoint-with-submodules.py - Multi-submodule checkpoints

Storage:

Checkpoints: context-storage/checkpoints/
Audit logs: context-storage/audit-logs/ (submodule operations)

Features:

ISO 8601 timestamp naming
Git state backup for rollback
Input validation (injection prevention)
Network retry logic (3 attempts)
Comprehensive error handling
Detailed operation logging

Dependencies:

Python 3.10+
Git 2.25+ (submodule support)
Optional: unified_logger, privacy_integration

Safety Features

Input Validation: Prevents command injection via description
Git State Backup: Saves HEAD for rollback on failure
Atomic Operations: Rollback on partial failure
Network Retry: 3 attempts with exponential backoff
Audit Trail: JSON logs for all operations
Safe Characters: Filters unsafe shell characters

Token Efficiency

Before: Manual checkpoint creation

5-10 minutes writing documentation
Multiple git commands
Easy to forget context details

After: Automated checkpoint

10 seconds total
Complete context captured
Consistent format every time

Savings: 5+ minutes per checkpoint × multiple checkpoints per day

Production Validation

✅ Tested with:

Single repositories
57+ submodule repositories
Large git histories
Network interruptions
Permission edge cases

✅ Handles:

Detached HEAD states
Submodule pointer updates
Missing remote branches
Timeout conditions

Examples

Example 1: End of Session Checkpoint

# Export and checkpoint
/export
/cx
python3 scripts/create-checkpoint.py "Completed auth implementation" --auto-commit

# Verify
ls -la context-storage/checkpoints/ | tail -1

Example 2: Multi-Repo Sprint Completion

python3 scripts/checkpoint-with-submodules.py "Sprint 3 - Auth complete"
# Commits: coditect-core, coditect-cloud-backend, coditect-web-frontend
# Updates: coditect-rollout-master (parent)
# Creates: context-storage/audit-logs/2025-12-11T...-audit.json

Example 3: Resume from Checkpoint

# Find latest checkpoint
LATEST=$(ls -t context-storage/checkpoints/*.md | head -1)
echo "Resuming from: $LATEST"
cat "$LATEST"

# Continue work with context loaded

Success Output

When this skill completes successfully, you should see:

✅ SKILL COMPLETE: checkpoint-automation

Completed:
- [x] Checkpoint document created with ISO 8601 timestamp
- [x] Git status and diff captured
- [x] Recent commits summarized
- [x] Updated files cataloged with line changes
- [x] Next steps documented
- [x] Git commit created (if --auto-commit)
- [x] Submodule commits synced (if --with-submodules)
- [x] Audit log generated

Outputs:
- context-storage/checkpoints/2026-01-04T15-30-00Z-feature-complete.md
- Git commit: "checkpoint: Feature complete" (if --auto-commit)
- context-storage/audit-logs/2026-01-04T15-30-00Z-audit.json (if submodules)

Checkpoint Size: 3.2 KB
Files Tracked: 12 modified, 4 new
Submodules Synced: 3 (if applicable)

Completion Checklist

Before marking this skill as complete, verify:

Failure Indicators

This skill has FAILED if:

❌ Checkpoint file not created in context-storage/checkpoints/
❌ Filename timestamp not in ISO 8601 format
❌ Git status section empty or showing errors
❌ Updated files table missing or incomplete
❌ Git commit failed despite --auto-commit flag
❌ Submodule sync failed partially (some pushed, some not)
❌ Audit log missing for multi-submodule operation
❌ Input validation failed (unsafe characters in description)
❌ Git state backup not created before operations
❌ Network timeout during push without retry

When NOT to Use

Do NOT use checkpoint-automation when:

Simple git commit needed - Use /commit or git commit directly
Only exporting conversation - Use /export command instead
Full repository sync needed - Use /git-sync for comprehensive sync
Documentation creation - Use /document or codi-documentation-writer
No changes to preserve - Skip if no uncommitted changes or progress
Mid-task state - Wait until logical stopping point before checkpoint
Emergency debugging - Don't add checkpoint overhead during incident response
CI/CD pipeline - Automated checkpoints not appropriate in CI

Alternative Approaches:

Manual git commit: For simple version control needs
Session export only: /export without checkpoint overhead
TASKLIST update: Modify PILOT plan directly for progress tracking
README update: Document changes in README without full checkpoint

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Checkpointing too frequently	Noise in checkpoint history, wasted time	Checkpoint at logical milestones only (end of session, feature complete)
Vague descriptions	Hard to identify checkpoint later	Use specific descriptions: "Auth module complete" not "Work done"
Skipping git commit	Checkpoint file not version controlled	Always use --auto-commit unless specific reason not to
Forgetting submodules	Parent repo out of sync with submodules	Use --with-submodules for multi-repo projects
No next steps	Context lost for next session	Always document 3-5 next actions
Checkpointing dirty state	Uncommitted changes create confusion	Clean up working directory before checkpoint
Git history cleanup during checkpoint	Risk of data loss	Separate history cleanup from checkpoint creation
Not verifying submodule push	Parent repo points to unpushed commits	Verify all submodule pushes succeed before parent commit
Unsafe description input	Command injection risk	Input validation prevents shell injection
Missing context documentation	Hard to resume next session	Document key decisions, important files, dependencies

Principles

This skill embodies these CODITECT principles:

Session Continuity - Preserve context for seamless session resumption
Automation First - Single command creates checkpoint + git operations
Atomic Operations - Rollback on failure prevents partial states
Audit Trail - JSON logs for multi-repo operations ensure traceability
Safety First - Input validation prevents injection attacks
Network Resilience - Retry logic handles temporary network issues
ISO Standards - ISO 8601 timestamps for global consistency
Progressive Enhancement - Basic checkpoint → auto-commit → multi-submodule

Full Principles: CODITECT-STANDARD-AUTOMATION.md

Command: /checkpoint (slash command wrapper)
Scripts: scripts/create-checkpoint.py, scripts/checkpoint-with-submodules.py
Storage: context-storage/checkpoints/
Skill: git-workflow-automation (related git operations)

How to Use This Skill​

When to Use This Skill​

What It Automates​

Usage​

Basic Checkpoint​

Auto-Commit Checkpoint​

Multi-Submodule Checkpoint​

Checkpoint Without Commit​

Output Format​

Checkpoint Document​

Audit Report (Multi-Submodule)​

Slash Command​

Integration with CODITECT​

Technical Details​

Safety Features​

Token Efficiency​

Production Validation​

Examples​

Example 1: End of Session Checkpoint​

Example 2: Multi-Repo Sprint Completion​

Example 3: Resume from Checkpoint​

Success Output​

Completion Checklist​

Failure Indicators​

When NOT to Use​

Anti-Patterns (Avoid)​

Principles​

Related​