Upgrading Your Project
The template behind your project keeps improving, with new workflow features, fixes and security patches. /upgrade brings your project up to a newer template version in one guided step. You don’t touch files or run git commands yourself.
Which version you’re on
Section titled “Which version you’re on”template-version.json at the top of your project records your template version. It’s set when you create the project and updated every time you upgrade.
To hear about new versions, open the template repository on GitHub and click Watch, then Custom, then Releases. Each release lists what changed. See Release Notes.
Before you upgrade
Section titled “Before you upgrade”/upgrade only runs on main with no uncommitted changes. Finish or set aside any epic that’s in progress first. If something is in the way, Claude tells you the one thing to do and stops.
How to upgrade
Section titled “How to upgrade”- Type
/upgrade. - Claude shows you the target version and its highlights, and asks whether to start.
- Claude does the upgrade on a separate branch, then runs the tests and quality checks.
- Claude shows you a plain summary of what changed and asks whether to apply it.
Say yes and Claude merges the upgrade into main for you. Say no and it stays on a branch named chore/upgrade-<version> until you ask to apply it.
If a GitHub check fails on the upgrade, Claude tells you and never merges past it silently.
What the upgrade changes
Section titled “What the upgrade changes”| Area | What happens |
|---|---|
| Workflow files | Claude’s agents, commands, scripts, policies and help pages are updated to the new version. |
| Retired files | Template files the new version no longer uses are removed. Anything you added yourself stays, including your own commands, agents, skills and hooks. |
| Dependencies | New template dependencies and settings are added to web/package.json. Nothing you added is removed. |
.gitignore | New entries the template expects are added. Your existing entries stay as they are. |
CLAUDE.md | The template’s sections are updated. Your project-specific content stays as it is. |
| Guardrails | Changes to settings, hooks and the GitHub Actions workflows are applied and called out in the summary. |
| Workflow state | If the new version changes how the workflow stores its progress, Claude converts it with /migrate-legacy. |
Your application code in web/src/, web/e2e/ and web/public/ is never touched.
What to watch for
Section titled “What to watch for”- Customised report wording:
/upgradereplaces the build report skill files. Keep a copy of any wording change you want to reapply. See Build Reports. - One-off migrations: occasionally a release needs a change Claude won’t make silently, such as moving tests to a new tool. The summary points you to the release notes for these.
If your project predates /upgrade
Section titled “If your project predates /upgrade”Projects created before /upgrade existed don’t have the command yet. Ask Claude to fetch and run the latest /upgrade once. From then on, it updates itself.