CRAFT Tutorials · Advanced
When a new CRAFT release comes out, moving your project to it is a simple drag-and-drop — no command line, no Git. Your work is never part of the swap, Claude checks things before and after, and if anything looks off, rolling back takes one step.
What you’ll do: 3 steps plus a one-step safety net · about 10 minutes · once per release.
What an upgrade actually is
Your project lives in two folders side by side:
- CRAFT Core Files — the framework itself. This is the part a release updates.
- CRAFT Project Files — your work: your project, notes, history, and handoffs. An upgrade never touches this.
So an upgrade is just this: you drop a newer CRAFT Core Files folder over the old one. The framework is replaced; your work sits untouched in the folder next to it. And because your old folder can be kept as a safety net, the whole thing is reversible.
Before you start: download and make a safety net
Two quick things before the swap:
- Download the new release and unzip it. Inside you’ll find a fresh CRAFT Core Files folder.
- Keep your current folder as a one-step rollback. Rename your existing CRAFT Core Files to CRAFT Core Files (old) — right-click → Rename on both Mac and Windows. If anything goes wrong later, this is all you need to undo it.
Step 1 — Capture a baseline
Before the swap, have Claude take a snapshot of where things stand, so it can later prove your work was untouched. Just ask:
Claude records your current version and a fingerprint of your CRAFT Project Files. It writes nothing into the framework — it’s just a “before” picture.
✓ You’ll know it worked when Claude confirms it captured your current version and a baseline of your work.
Step 2 — Do the upgrade (drag-and-drop)
Now the swap itself:
- Drag the new CRAFT Core Files folder into your project folder, alongside CRAFT Project Files.
- When your computer asks what to do with the matching folder, choose Replace. (On a Mac you’ll see “Replace”; on Windows, “Replace the files in the destination.”)
- That’s the whole upgrade. Your CRAFT Project Files and your root CLAUDE.md weren’t part of the drop, so they’re exactly as they were.
Good to know: you should now have the new CRAFT Core Files and your renamed CRAFT Core Files (old) sitting side by side. That’s expected — the old one is your safety net until you’ve verified the new one.
Step 3 — Verify
Finally, have Claude check the new release landed cleanly and your work is intact:
Claude shows you a friendly old → new version line, confirms the new framework’s files are complete and intact, and — using that baseline from Step 1 — proves nothing in your CRAFT Project Files changed.
✓ You’ll know it worked when every check passes and you see your new version number. You can delete CRAFT Core Files (old) whenever you’re ready.
If something’s wrong: roll back
If a check fails or anything looks off, you’re never stuck — put the old framework back:
- Delete the new CRAFT Core Files folder.
- Rename CRAFT Core Files (old) back to CRAFT Core Files.
- You’re exactly where you started — and your work was never at risk, because it lives in the other folder the whole time.
Why this is safe: the upgrade only ever replaces the framework folder. Your project, memory, and history live in CRAFT Project Files, which no upgrade touches — so the worst case is simply swapping one framework folder back for the other.
Troubleshooting
- The verifier flags a difference in your work — that’s exactly what the baseline is for. Don’t delete the old folder; ask Claude to explain what it found before you go further.
- You don’t see a “Replace” option, only “Merge” — make sure you’re dropping the whole CRAFT Core Files folder (not its contents) into the project folder, so the names match and your computer offers to replace it.
- Not sure which version you’re on — ask Claude: “What CRAFT version is this project on?”
That’s an upgrade: drag, replace, verify — with a one-step rollback and your work never in the swap. A good next step: Health-check and repair your project — a quick way to confirm everything’s in good shape after an update.