RCP-CWK-037 Monorepo Snapshot Backup

Creates point-in-time backup of the project repository before any push or on-demand

Uses git bundle for atomic snapshots, tags with date and session ID, verifies bundle integrity, and records the snapshot in a tracking log. Designed to protect against accidental destructive operations and provide recovery points.

Monorepo Snapshot Backup

Cowork | Safety | Difficulty: Intermediate | Time: 2–5 min
Tags: Introduced in Beta, Safety, Git, Backup, Snapshot, Bundle, Recovery, Cowork

TL;DR

What It Does
Creates point-in-time backup of the project repository before any push or on-demand. Uses git bundle for atomic snapshots, tags with date and session ID, verifies bundle integrity, and records the snapshot in a tracking log. Designed to protect against accidental destructive operations and provide recovery points.
How It Works
Nine operational steps after pre-flight. Verifies clean git state (warns if uncommitted changes exist). Captures snapshot metadata (HEAD commit, branch, timestamp). Creates a git bundle containing all branches and tags. Verifies bundle integrity with git bundle verify. Tags the snapshot in the repository. Records the snapshot in MONOREPO-SNAPSHOT-LOG.txt with full metadata. Optionally pushes the snapshot tag and mirror to a backup repository.
What To Expect
A .bundle file in the backup directory containing a complete, verified copy of the repository. A snapshot tag on HEAD. A log entry in MONOREPO-SNAPSHOT-LOG.txt. If backup repo push is enabled, the tag and mirror are pushed to the backup repository.
Best Results When You
Run before any push operation or risky git operations. Keep uncommitted changes committed before snapshotting for the cleanest backups. Use this as the pre-push safety step — it pairs naturally with CWK-005 (Git Checkpoint) for routine saves and CWK-046 (Push Orchestrator) for actual pushes.
Typical Time
2–5 minutes depending on repository size. Bundle creation and verification are the main time costs. Backup repo push adds 1–2 minutes if enabled.
Difficulty
Intermediate — the recipe handles all git operations internally. User only needs to provide the repository path and session ID. Understanding of git bundles is helpful but not required.

How To Start

This recipe creates a point-in-time backup of your project repository. Run it before pushes, before risky operations, or periodically for safety. The MASTER project (MONOREPO_ROLE=MASTER) uses this as the primary pre-push backup mechanism.

STEP 1Provide Repository and Session Info

Specify the repository path and current session ID. Optionally configure backup directory and remote push.
Available parameters
  • monorepo_path · string · required
    Path to the cloned repository root.
  • session_id · string · required
    Current session ID for snapshot tagging (e.g., “H073”).
  • backup_dir · string · optional · default: {monorepo_path}/backups
    Directory to store bundle files.
  • push_to_backup_repo · boolean · optional · default: false
    Whether to push the snapshot to the backup repository.
  • backup_repo_url · string · optional · default: github.com/CRAFTFramework/craft-framework-backup
    URL of the backup GitHub repository.
Invocations
Local snapshot only
#H->AI::Directive: (Execute CWK-037 with monorepo_path="/tmp/p060-clone", session_id="H073")
Snapshot with backup repo push
#H->AI::Directive: (Execute CWK-037 with monorepo_path="/tmp/p060-clone", session_id="H073", push_to_backup_repo=true)

Usage Examples

EXAMPLE 1Pre-push local snapshot

User
Create a backup snapshot before we push.
Cat
Initiating monorepo snapshot. Working tree clean. HEAD: a1b2c3d (main). Bundle created: monorepo-snapshot-2026-03-05_143022-H073.bundle (12.4 MB). Verification: PASS. Tagged: snapshot-2026-03-05_143022-H073. Logged to MONOREPO-SNAPSHOT-LOG.txt. Safe to push.

EXAMPLE 2Snapshot with backup repo push

User
Full backup — snapshot and push to the backup repo.
Cat
Initiating monorepo snapshot with backup repo push. Working tree clean. Bundle created and verified (14.1 MB). Tagged locally. Pushing to craft-framework-backup. Tag pushed. Mirror pushed. Snapshot complete — local bundle + remote backup.

EXAMPLE 3Snapshot with uncommitted changes

User
Snapshot the repo — I have some uncommitted work.
Cat
Warning: uncommitted changes detected. Snapshot will capture current state including uncommitted changes. Proceed? [User confirms] Bundle created: 13.8 MB. Verification: PASS. Tagged and logged. Note: consider committing changes and re-snapshotting for a cleaner recovery point.

How AI Reads This Recipe

When this recipe is triggered, the AI creates a point-in-time repository backup. The AI should:
  1. Pre-Flight (Step 0). Verify monorepo_path exists and is a git repository. Fail with error if not.
  2. Verify Clean State (Step 1). Run git status –porcelain. If uncommitted changes exist, warn the user and ask for confirmation before proceeding.
  3. Capture Metadata (Step 2). Get HEAD commit hash, current branch, last commit date, and generate snapshot timestamp. Build snapshot tag name and bundle filename from metadata.
  4. Create Backup Directory (Step 3). Create backup_dir if it does not exist. Verify directory is writable.
  5. Create Git Bundle (Step 4). Run git bundle create with –all flag to capture all branches and tags. Report bundle file size.
  6. Verify Bundle (Step 5). Run git bundle verify on the created bundle. Fail with error if verification fails.
  7. Tag Snapshot (Step 6). Create a git tag at HEAD with the snapshot tag name. Warn (do not fail) if tagging fails.
  8. Record in Log (Step 7). Append full snapshot metadata to MONOREPO-SNAPSHOT-LOG.txt. Create the log file with header if it does not exist.
  9. Backup Repo Push (Step 8). If push_to_backup_repo is true, push the snapshot tag and then push –mirror to the backup repository URL. If push fails due to unrelated histories, note the CWK-045 /tmp clone pattern as alternative.
  10. Report Status (Step 9). Display completion summary with snapshot tag, bundle filename, size, and verification status.

When To Use This Recipe

Use this recipe when you are about to push to a shared repository and want a recovery point, want periodic point-in-time backups of the project repository, need to create a portable backup (bundle file) that can be stored or transferred independently, or are the MASTER project performing pre-push safety operations.
Do Not Use When
You only need a routine commit checkpoint — use CWK-005 (Git Checkpoint) instead. For the actual push workflow, use CWK-046 (Push Orchestrator) which calls this recipe as its pre-push step. For Global file pushes to craft-framework-master-dev, use CWK-045 directly.

Recipe FAQ

What is a git bundle?
A git bundle is a single file that contains a complete copy of the repository including all branches, tags, and commit history. It can be used to restore the repository to the exact state at the time of creation, or to transfer a repository without network access.
How is this different from CWK-005 (Git Checkpoint)?
CWK-005 creates a commit in the working repository — it is a lightweight, frequent operation. CWK-037 creates an external backup file (bundle) that exists independently of the repository. Use CWK-005 for routine saves, CWK-037 for recovery points before risky operations.
What happens if the backup repo push fails?
The local bundle is still valid — you have a local backup regardless of push status. If push fails due to unrelated histories (common in Cowork sandbox environments), use the CWK-045 /tmp clone pattern as an alternative push mechanism.
Where are the bundle files stored?
By default in {monorepo_path}/backups/. You can override this with the backup_dir parameter. Each bundle is named with the timestamp and session ID for easy identification.
Should I clean up old bundles?
Yes — bundle files can be large. Keep the most recent 3–5 snapshots and archive or delete older ones. The snapshot log retains the metadata for all snapshots regardless of whether the bundle file still exists.

Version History

v1.00a — 2026-03-05
Initial creation. Git bundle-based atomic snapshots with integrity verification, snapshot tagging, log tracking via MONOREPO-SNAPSHOT-LOG.txt, optional backup repository push with mirror support, and uncommitted changes warning flow.

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