claudetools/.claude/commands/checkpoint.md

description

description
Create commit with detailed comment and save session context to database

Please create a comprehensive checkpoint that captures BOTH git changes AND session context with the following steps:

Part 1: Git Checkpoint

1. Initialize Git if needed: Run git init if git has not been instantiated for the project yet.

2. Analyze all changes:

   • Run git status to see all tracked and untracked files
   • Run git diff to see detailed changes in tracked files
   • Run git log -5 --oneline to understand the commit message style of this repository

3. Stage everything:

   • Add ALL tracked changes (modified and deleted files)
   • Add ALL untracked files (new files)
   • Use git add -A or git add . to stage everything

4. Create a detailed commit message:

   • First line: Write a clear, concise summary (50-72 chars) describing the primary change
     • Use imperative mood (e.g., "Add feature" not "Added feature")
     • Examples: "feat: add user authentication", "fix: resolve database connection issue", "refactor: improve API route structure"
   • Body: Provide a detailed description including:
     • What changes were made (list of key modifications)
     • Why these changes were made (purpose/motivation)
     • Any important technical details or decisions
     • Breaking changes or migration notes if applicable
   • Footer: Include co-author attribution as shown in the Git Safety Protocol

5. Execute the commit: Create the commit with the properly formatted message following this repository's conventions.

Part 2: Database Context Save

6. Save session context to database:

   After the commit is complete, save the session context to the ClaudeTools database for cross-machine recall.

   API Endpoint: POST http://172.16.3.30:8001/api/conversation-contexts

   Payload Structure:

   {
     "project_id": "<project-uuid>",
     "context_type": "checkpoint",
     "title": "Checkpoint: <commit-summary>",
     "dense_summary": "<comprehensive-session-summary>",
     "relevance_score": 8.0,
     "tags": ["<extracted-tags>"],
     "metadata": {
       "git_commit": "<commit-hash>",
       "git_branch": "<branch-name>",
       "files_changed": ["<file-list>"],
       "commit_message": "<full-commit-message>"
     }
   }
   

   Authentication: Use JWT token from .claude/context-recall-config.env

   How to construct the payload:

   a. Project ID: Get from git config or environment

   PROJECT_ID=$(git config --local claude.projectid 2>/dev/null)
   

   b. Title: Use commit summary line

   "Checkpoint: feat: Add Sequential Thinking to Code Review Agent"
   

   c. Dense Summary: Create compressed summary including:

   • What was accomplished (from commit message body)
   • Key files modified (from git diff --name-only)
   • Important decisions or technical details
   • Context for future sessions

   Example:

   Enhanced code-review.md with Sequential Thinking MCP integration.
   
   Changes:
   - Added trigger conditions for 2+ rejections and 3+ critical issues
   - Created enhanced escalation format with root cause analysis
   - Added UI_VALIDATION_CHECKLIST.md (462 lines)
   - Updated frontend-design skill for automatic invocation
   
   Files: .claude/agents/code-review.md, .claude/skills/frontend-design/SKILL.md,
   .claude/skills/frontend-design/UI_VALIDATION_CHECKLIST.md
   
   Decision: Use Sequential Thinking MCP for complex review issues to break
   rejection cycles and provide comprehensive feedback.
   
   Commit: a1b2c3d on branch main
   

   d. Tags: Extract relevant tags from context (4-8 tags)

   ["code-review", "sequential-thinking", "frontend-validation", "ui", "documentation"]
   

   e. Metadata: Include git info for reference

   {
     "git_commit": "a1b2c3d4e5f",
     "git_branch": "main",
     "files_changed": [
       ".claude/agents/code-review.md",
       ".claude/skills/frontend-design/SKILL.md"
     ],
     "commit_message": "feat: Add Sequential Thinking to Code Review Agent\n\n..."
   }
   

   Implementation:

   # Load config
   source .claude/context-recall-config.env
   
   # Get git info
   COMMIT_HASH=$(git rev-parse --short HEAD)
   BRANCH=$(git rev-parse --abbrev-ref HEAD)
   COMMIT_MSG=$(git log -1 --pretty=%B)
   FILES=$(git diff --name-only HEAD~1 | tr '\n' ',' | sed 's/,$//')
   
   # Create payload and POST to API
   curl -X POST http://172.16.3.30:8001/api/conversation-contexts \
     -H "Authorization: Bearer $JWT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "project_id": "'$CLAUDE_PROJECT_ID'",
       "context_type": "checkpoint",
       "title": "Checkpoint: <commit-summary>",
       "dense_summary": "<comprehensive-summary>",
       "relevance_score": 8.0,
       "tags": ["<tags>"],
       "metadata": {
         "git_commit": "'$COMMIT_HASH'",
         "git_branch": "'$BRANCH'",
         "files_changed": ["'$FILES'"],
         "commit_message": "'$COMMIT_MSG'"
       }
     }'
   

7. Verify both checkpoints:

   • Confirm git commit succeeded (git log -1)
   • Confirm database save succeeded (check API response)
   • Report both statuses to user

8. Refresh directives (MANDATORY):

   • After checkpoint completion, auto-invoke /refresh-directives
   • Re-read directives.md to prevent shortcut-taking
   • Perform self-assessment for any violations
   • Confirm commitment to agent coordination rules
   • Report directives refreshed to user

Benefits of Dual Checkpoint

Git Checkpoint:

• Code versioning
• Change history
• Rollback capability

Database Context:

• Cross-machine recall
• Semantic search
• Session continuity
• Context for future work

Together: Complete project memory across time and machines

IMPORTANT

• Do NOT skip any files - include everything
• Make the commit message descriptive enough that someone reviewing the git log can understand what was accomplished
• Follow the project's existing commit message conventions (check git log first)
• Include the Claude Code co-author attribution in the commit message
• Ensure database context save includes enough detail for future recall
• Use relevance_score 8.0 for checkpoints (important milestones)
• Extract meaningful tags (4-8 tags) for search/filtering