claudetools/.claude/commands/checkpoint.md

---
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**:
   ```json
   {
     "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
      ```bash
      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)
      ```json
      ["code-review", "sequential-thinking", "frontend-validation", "ui", "documentation"]
      ```

   e. **Metadata**: Include git info for reference
      ```json
      {
        "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**:
   ```bash
   # 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

## 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