RCP-CWK-041 Monorepo Disaster Recovery

Structured recovery procedure for monorepo incidents — accidental history destruction, orphan branches, folder deletion, force-push damage, and merge conflicts

Walks through a 5-phase workflow: assess current state, identify recovery sources, execute recovery, verify restored state, and document the incident. Every destructive step requires explicit human confirmation.

Monorepo Disaster Recovery

Cowork | Safety | Difficulty: Advanced | Time: 15–45 min
Tags: Introduced in Beta, Safety, Disaster Recovery, Git, Monorepo, Backup, Incident Response, Advanced, Cowork

TL;DR

What It Does
Structured recovery procedure for monorepo incidents — accidental history destruction, orphan branches, folder deletion, force-push damage, and merge conflicts. Walks through a 5-phase workflow: assess current state, identify recovery sources, execute recovery, verify restored state, and document the incident. Every destructive step requires explicit human confirmation.
How It Works
Five phases. Phase 1 assesses the monorepo’s current state — checks .git integrity, branch status, directory structure (framework/ and specifications/ for two-repo model), remote synchronization, and recent history. Classifies severity as CRITICAL, MODERATE, or MINOR. Phase 2 identifies available recovery sources in priority order: local snapshot bundles (CWK-037), automated zip backups (CWK-ADM-076 project and framework zips), backup repository, and git reflog (last resort). Phase 3 executes recovery from the selected source with human confirmation at every destructive step. Phase 4 verifies the restored state against expected structure, branch, and file counts. Phase 5 documents the incident, updates the changelog, notifies connected projects via CWK-039, and creates a post-recovery snapshot.
What To Expect
Detailed state assessment with severity classification. A prioritized list of available recovery sources. Human-confirmed recovery execution with pre-recovery safety snapshot. Post-recovery verification report. Incident documentation and project notifications.
Best Results When You
Have recent CWK-037 snapshots or CWK-ADM-076 automated zip backups available. Provide a clear description of what went wrong. Stay present for human confirmation prompts — every destructive operation requires your approval.
Typical Time
15–45 minutes depending on severity and recovery source. MINOR incidents with available snapshots resolve quickly. CRITICAL incidents with no automated backups require more time for manual reconstruction.
Difficulty
Advanced — the recipe handles complex git operations and destructive recovery steps. Understanding of git history, branching, and the two-repo architecture helps interpret assessment results. Human judgment required at multiple decision points.

How To Start

This recipe activates when a monorepo incident requires structured recovery. The MASTER project (MONOREPO_ROLE=MASTER) is the sole Global pusher, so recovery simplifies to MASTER restoring framework state. Connected projects pull updated files post-recovery. For post-recovery pushes, use CWK-046 (Push Orchestrator) which delegates to CWK-045 for Global files.

STEP 1Initiate Disaster Recovery

Provide the repository path, session ID, project ID, and a description of the incident.
Available parameters
  • monorepo_path · string · required
    Path to the cloned monorepo root.
  • session_id · string · required
    Current session ID for incident tracking.
  • project_id · string · required
    Project initiating the recovery.
  • incident_description · string · required
    Human-provided description of what went wrong.
  • backup_dir · string · optional · default: {monorepo_path}/backups
    Directory containing snapshot bundles.
  • backup_repo_url · string · optional · default: craft-framework-backup
    URL of backup GitHub repository.
Invocations
Standard disaster recovery
#H->AI::Directive: (Execute CWK-041 with monorepo_path="/tmp/p060-clone", session_id="H074", project_id="CP-060", incident_description="Accidental force-push destroyed commit history")
Custom backup directory
#H->AI::Directive: (Execute CWK-041 with monorepo_path="/tmp/p060-clone", session_id="H074", project_id="CP-060", incident_description="Missing framework directory", backup_dir="/home/backups")

Usage Examples

EXAMPLE 1Recovery from snapshot bundle

User
Something’s wrong with the monorepo — git log shows orphan commits. Run disaster recovery.
Cat
Disaster Recovery — Phase 1: State assessment. Severity: MODERATE. Phase 2: Snapshots AVAILABLE (3 bundles), zip backups AVAILABLE. Recommended: snapshots. [User selects snapshots] Phase 3: Pre-recovery snapshot saved. Bundle verified. Reset confirmed. Recovery successful. Phase 4: Verification PASS — structure intact, branch main. Phase 5: Incident logged. Post-recovery snapshot created. Notify projects via CWK-039.

EXAMPLE 2Critical incident — structure damaged

User
The framework directory is gone. I think something corrupted the repo.
Cat
Disaster Recovery — Phase 1: Structure: framework MISSING. Severity: CRITICAL. Phase 2: No snapshots. Framework zips AVAILABLE (3 zips). Recommended: framework_zips. [User selects] Phase 3: Zip verified. Extracted to temp directory for review. Apply extracted framework/ over damaged location. Phase 4: Verification PASS after restoration. Phase 5: Incident logged. Recovery complete.

EXAMPLE 3No automated recovery sources

User
Run disaster recovery. Everything looks broken.
Cat
Disaster Recovery — Phase 1: .git missing or corrupted. Severity: CRITICAL. Phase 2: No snapshots, no zip backups, no backup repo, no reflog. NO recovery sources available. Manual recovery required: each project’s local Cowork workspace has the authoritative copy of its own files. Reconstruct monorepo from individual project folders. Re-initialize git history if needed.

How AI Reads This Recipe

When this recipe is triggered, the AI executes a structured 5-phase disaster recovery procedure. The AI should:
  1. Phase 1: Assess current state. Check .git integrity. Inspect branch state, working tree, recent history, directory structure (framework/ and specifications/ for two-repo model), and remote sync. Classify severity: CRITICAL (structure damage, detached HEAD, corrupted history), MODERATE (cannot reach remote), MINOR (accessible, structure intact). Present formatted assessment report.
  2. Phase 2: Identify recovery sources. Check in priority order: local snapshot bundles (backup_dir), automated zip backups (project zips in backups/project/, framework zips in ~/Documents/Claude/craft-framework-beta-dev-backups/), snapshot log history, backup repository remote, and git reflog. Present sources with recommendation. Ask human to select.
  3. Phase 3: Execute recovery. Create pre-recovery snapshot of damaged state first. Execute based on selected source: snapshot bundles (verify, clone, check structure), zip backups (verify, extract to temp, review before applying), backup repo (fetch, compare, human-confirmed reset), reflog (show entries, confirmed reset). Every destructive operation requires explicit human confirmation.
  4. Phase 4: Verify restored state. Check structure (framework/, specifications/, templates/), branch (must be main), history, framework file count, specification file count. Compare against Global file manifest if available. Report PASS or FAIL.
  5. Phase 5: Document and notify. Write incident entry to MONOREPO-INCIDENT-LOG.txt. Update changelog. Prepare CWK-039 notification for connected projects (CRITICAL urgency). Create post-recovery snapshot via CWK-037. Present final report with next steps: use CWK-046 for all post-recovery pushes, notify projects, investigate root cause.

When To Use This Recipe

Use this recipe when the monorepo has experienced data loss, corruption, or structural damage, when git history appears inconsistent or orphaned, when critical directories (framework/, specifications/) are missing, or when a force-push or failed merge has left the repository unrecoverable through normal git operations.
Do Not Use When
The issue is a routine merge conflict resolvable with standard git tools — resolve manually or use CWK-038/CWK-046 pre-push verification first. For routine backup creation without an active incident, use CWK-037 (snapshot) or let CWK-ADM-076 handle automated backups.

Recipe FAQ

What recovery sources does this recipe check?
Five sources in priority order: (1) local snapshot bundles from CWK-037, (2) automated zip backups from CWK-ADM-076 — both project zips in backups/project/ and framework zips in ~/Documents/Claude/craft-framework-beta-dev-backups/, (3) the backup repository remote, and (4) git reflog as a last resort (entries expire, typically 90 days for unreachable commits).
Why does every destructive step need human confirmation?
Disaster recovery involves operations like git reset –hard that permanently alter repository state. Even though the recipe preserves damaged state in a pre-recovery snapshot, explicit human confirmation ensures the operator understands and approves each destructive operation.
What if recovery verification fails?
Try a different recovery source, manually reconstruct from individual project workspaces, or contact Richard. The pre-recovery snapshot preserves the damaged state, so you haven’t lost anything by attempting recovery.
How does this work with the two-repo architecture?
Since the MASTER project is the sole Global pusher, recovery simplifies to MASTER restoring framework state in craft-framework-master-dev. Connected projects pull updated files in their next session. No multi-project push coordination needed. Post-recovery pushes use CWK-046 which delegates to CWK-045 for Global files.
What are the automated zip backups?
CWK-ADM-076 creates zip backups every 10 handoffs. Project zips go to backups/project/ (minimum 10 retained). Framework zips go to ~/Documents/Claude/craft-framework-beta-dev-backups/ (up to 100 retained). Naming: CRAFT-BACKUP-PROJECT-{id}-{date}-H{num}.zip and CRAFT-BACKUP-FRAMEWORK-{date}-H{num}.zip.

Version History

v1.01a — 2026-04-11
SP08 update (P061-H031): Added zip backup knowledge from CWK-ADM-076. Recovery sources now include project zips (backups/project/) and framework zips (~/Documents/Claude/craft-framework-beta-dev-backups/). Removed Google Drive references (CWK-043 eliminated).
v1.00a — 2026-04-05
Structure checks updated for two-repo model (H109) — framework/ and specifications/ instead of projects/ and specs/. Recovery targets craft-framework-master-dev. Initial 5-phase workflow: assess, identify sources, execute, verify, document. Integration with CWK-037, CWK-046, CWK-039.

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