RCP-CWK-005 Cowork Git Checkpoint

Creates a git commit with a CRAFT-context-aware commit message

The AI stages your modified files, generates a descriptive message that includes what changed and why, commits, runs a post-commit review, and optionally pushes to GitHub with automatic token scrub. Other recipes call this one automatically — you rarely need to invoke it directly.

Cowork Git Checkpoint

Cowork | Safety & Version Control | Difficulty: Beginner | Time: 1–3 min
Tags: Introduced in Beta, Git, Version Control, Safety, Commit, Push, Cowork, Essential, Frequently Used

TL;DR

What It Does
Creates a git commit with a CRAFT-context-aware commit message. The AI stages your modified files, generates a descriptive message that includes what changed and why, commits, runs a post-commit review, and optionally pushes to GitHub with automatic token scrub. Other recipes call this one automatically — you rarely need to invoke it directly.
How It Works
The AI first checks git status and cleans up any stale index.lock from prior sandbox crashes. It captures a snapshot of git state before making changes, then stages modified CRAFT files (project files, cookbooks, handoff logs, CLAUDE.md). The commit message is auto-generated from context — when called by another recipe like Handoff (CWK-002) or Mid-Session Checkpoint (CWK-003), the message includes the calling recipe’s prefix automatically. After committing, the AI runs a state-diff verification comparing before and after snapshots, then triggers a post-commit file review. If the commit touches critical files (cookbooks, handoff logs, CLAUDE.md), the review runs in blocking mode — halting the workflow if serious issues are found.
What To Expect
A verified commit within 1–3 minutes. The AI reports the commit hash, file count, state-diff result, and push status. If the post-commit review finds critical issues in critical files, you will be asked how to proceed (fix, revert, or override).
Best Results When You
Let this recipe run automatically through other recipes — the called_by parameter ensures consistent commit message formatting across your project. For standalone use, provide clear commit_context so the message is meaningful when you review history later.
Typical Time
1–3 minutes. GitHub push adds 1–2 minutes.
Difficulty
Beginner — the AI handles staging, message generation, commit, verification, and optional push. You provide context and approve if asked.

How To Start

This recipe is most often called automatically by other recipes (Handoff, Mid-Session Checkpoint, CLAUDE.md Generator). You can also run it standalone for manual commits.

STEP 1Tell the AI What You Are Committing

Provide a brief description of what changed. If you have specific files to stage, list them — otherwise the AI auto-detects modified CRAFT project files.
Available parameters
  • commit_context · string · required
    Brief context for the commit message — a handoff ID, recipe executed, or description of changes (e.g., “Handoff H003” or “Updated roadmap after SP10 review”).
  • files_to_stage · list · optional · default: auto-detect modified
    Specific files to stage. If not provided, the AI stages all modified tracked files matching CRAFT project patterns.
  • push_to_github · boolean · optional · default: false
    Whether to push to GitHub after committing. Requires a configured remote and a Personal Access Token.
  • called_by · string · optional
    Recipe ID that triggered this checkpoint. When provided, auto-generates a commit message prefix: CWK-002 produces “Handoff {context}”, CWK-003 produces “Checkpoint — {context}”, CWK-007 produces “CLAUDE.md generated — {context}.” Standalone calls use commit_context as-is.
Example invocations
Standalone commit
#H->AI::Directive: (Create git checkpoint with context "Updated lessons learned after H050 review")
Standalone with push
#H->AI::Directive: (Create git checkpoint with context "H051 session close" and push to GitHub)
With specific files
#H->AI::Directive: (Create git checkpoint with context "Roadmap update" for files project/CFT-PROJ-CP-067_ROADMAP.docx and CLAUDE.md)

STEP 2Review the Commit Result

The AI stages files, generates the commit message, and commits. It then runs state-diff verification — comparing the git state before and after the commit to confirm the expected changes were applied with no unintended side effects. The AI reports the commit hash, files committed, and verification status.

STEP 3Address Any Post-Commit Review Findings

After the commit, the AI automatically runs a file review on the committed changes. For most commits, this runs silently in the background. If the commit includes critical CRAFT files (cookbooks, handoff logs, CLAUDE.md, roadmap), the review runs in blocking mode. If blocking review finds critical issues, the AI presents three options: fix the issues and create a corrective commit, revert the commit, or override and proceed.

STEP 4Confirm Optional Push

If you requested a GitHub push, the AI asks for a Personal Access Token. The token is embedded in the remote URL only for the duration of the push, then scrubbed immediately. If no remote is configured, the push is skipped with a note.

Usage Examples

Two scenarios — a standalone manual commit, and an automatic checkpoint called by the Handoff recipe.
Example 1 · Standalone manual commit
User: #H->AI::Directive: (Create git checkpoint with context "Updated lessons learned after retrospective")
AI: Checking git status. Clean index.lock state. Capturing pre-commit snapshot. Auto-detecting modified files: 2 files changed (CFT-PROJ-CP-067_LESSONS-LEARNED.txt, CLAUDE.md). Staging. Generating commit message. Committing.
AI: Committed: f4e7a2b. 2 files. State-diff: VERIFIED (HEAD changed, working tree clean). Post-commit review: auto mode, no findings. Push: skipped (not requested).
[Checkpoint complete — work continues]
Example 2 · Auto-called by Handoff recipe
User: #H->AI::Directive: (Run the Direct Handoff recipe for H051)
AI: Handoff recipe running. Generating session summary and handoff artifacts. Calling git checkpoint internally.
AI: Git checkpoint called by CWK-002. Commit message: “Handoff H051 — session close artifacts.” 5 files staged. Committed: c8d1b3e. State-diff: VERIFIED. Post-commit review: blocking mode (handoff log is a critical file), PASSED — no findings.
[Handoff recipe continues with push prompt]

How AI Reads This Recipe

When this recipe is triggered, the AI manages the full git commit lifecycle with built-in verification. The AI should:
  1. CHECK git status and clean up any stale index.lock file before proceeding — stale locks from sandbox crashes are a recurring pattern.
  2. CAPTURE a before-state snapshot (HEAD, porcelain status, staged files) for post-commit state-diff verification.
  3. STAGE files using CRAFT-aware patterns — match project files, cookbooks, handoff logs, CLAUDE.md, manifests, and recipe indexes. Use folder-qualified glob patterns that work with both flat and migrated directory structures.
  4. GENERATE a commit message with an auto-prefix when called_by is provided (Handoff, Checkpoint, CLAUDE.md generated) and include a Co-Authored-By line.
  5. COMMIT and capture the resulting hash.
  6. RUN state-diff verification comparing before and after snapshots to confirm the commit produced the expected result with no unintended side effects.
  7. TRIGGER post-commit file review — use blocking mode when committed files include critical CRAFT files (cookbooks, handoff logs, CLAUDE.md, roadmap). HALT the workflow if blocking review returns CRITICAL findings.
  8. PUSH to GitHub only when requested, with immediate token scrub after successful push.
The AI should NOT skip state-diff verification or post-commit review even for small commits. These checks catch subtle issues that compound across sessions. The index.lock cleanup must be attempted before reporting a failed checkpoint — stale locks are recoverable in most cases.

When to Use This Recipe

Use this recipe when you:
  • Need to commit changes during a session — either standalone or through another recipe that calls it automatically.
  • Want to create a versioned checkpoint before making significant changes to your project.
  • Are closing a session via Handoff (CWK-002) or Mid-Session Checkpoint (CWK-003), which call this recipe internally.
  • Need to push committed changes to GitHub with secure token handling.
  • Want to verify that a commit produced exactly the expected result via state-diff verification.
Do not use this recipe when:
You need to initialize git for the first time — that is CWK-004 (Git Initialization). This recipe requires an existing git repository. It also should not be used to commit files outside the CRAFT project patterns unless you explicitly specify them in files_to_stage.

Recipe FAQ

Q.Do I need to call this recipe directly?

Usually not. Handoff (CWK-002), Mid-Session Checkpoint (CWK-003), and CLAUDE.md Generator (CWK-007) call it automatically. Use it directly when you want a manual commit outside those workflows.

Q.What is the state-diff verification?

After each commit, the AI compares git state before and after — checking that HEAD changed, the working tree is clean (or only expected untracked files remain), and the commit hash is valid. If a push was requested, it also verifies the remote HEAD matches. This catches silent failures.

Q.What triggers blocking mode for the post-commit review?

Commits that include critical CRAFT files: cookbooks, handoff logs, CLAUDE.md, or the project roadmap. These files have outsized impact, so the review runs in blocking mode that halts the workflow if CRITICAL issues are found.

Q.What happens if blocking review finds a problem?

You get three options: fix the issues and create a corrective commit, revert the commit entirely, or override and proceed despite the findings. The commit already exists at that point — the review happens after commit, not before.

Q.What is the index.lock cleanup?

When a prior git operation crashes in the Cowork sandbox, it can leave a stale .git/index.lock file that blocks all future git write operations. This recipe attempts to remove it automatically before proceeding. If removal fails, it reports that git writes are unavailable and preserves your files for the next session.

Q.How does the commit message auto-prefix work?

When another recipe provides its ID via the called_by parameter, the message subject is prefixed automatically: CWK-002 produces “Handoff — {context}”, CWK-003 produces “Checkpoint — {context}”, CWK-007 produces “CLAUDE.md generated — {context}.” Standalone calls use your commit_context as the full subject.

Q.Can I push to multiple remotes?

This recipe supports a single origin remote. If you need multiple remotes, configure them manually and push outside this recipe’s workflow.

Version History

Changes to this recipe over time. Most recent first.
v1.08a 2026-03-15
Folder-qualified staging patterns for post-migration directory structures. Backwards-compatible with flat path layouts. Updated critical file patterns for blocking review mode.
v1.07a 2026-03-10
Added CWK-051 hook integration (commit gate and push gate). Routine commits proceed automatically; non-routine commits (first session commit, large changesets) are escalated for review.
v1.06a 2026-03-05
Added blocking review mode for commits touching critical CRAFT files (cookbooks, handoff logs, CLAUDE.md, roadmap). CRITICAL findings halt the workflow with fix/revert/override options.
v1.05a 2026-03-01
Integrated state-diff verification (before/after snapshot comparison). Added index.lock pre-flight cleanup for sandbox crash recovery.
v1.00a 2026-02-28
Initial release. Git commit with CRAFT-aware message generation, auto-prefix from calling recipes, optional GitHub push with token scrub, and post-commit review via CWK-015.

Get this recipe with CRAFT for Claude Cowork

Cowork recipes ship bundled with CRAFT for Claude Cowork — there’s no separate download. Clone the framework once, and your AI runs every recipe automatically when invoked.

Pull anytime to stay on the latest version — free to clone, no login or email required.

Then start your session

Once CRAFT is in your project folder, open a new Cowork session and ask Claude to initialize. For example:

You

Please initialize my CRAFT session.

Claude

CRAFT session ready. Your project is loaded, your persona is active, and your recipes are available. What would you like to work on?

What is CRAFT for Claude Cowork?

Not familiar with Git? Download as a ZIP

No command line needed. Just download, move, and unzip:

  1. Open the CRAFT framework repo on GitHub.
  2. Click the green Code button, then choose Download ZIP.
  3. Move the downloaded ZIP into your Claude Cowork project folder.
  4. Unzip it: double-click on Mac, or right-click → Extract All on Windows.

Similar Posts