Skip to Content
Cheat Sheet/upgrade

/upgrade

Check for a newer version of Gemba Flow and sync framework files from the latest upstream release. Your project’s content is never modified — only the framework files that come from the upstream template.

When to use it

Run this when the framework releases an update (announced upstream or surfaced by /doctor as a stale-version warning) and you want the latest improvements to skills, hooks, and agent templates. The command checks the upstream release, downloads the new framework files, and syncs them into your project — touching only the paths under the framework’s distribution boundary (per docs/DISTRIBUTION.md). User content (your content/ pages, your docs/PRODUCT-REQUIREMENTS.md, your tickets) is left alone.

The framework/user-content boundary is the key safety property this command depends on. If you’ve modified a file that the framework owns, your modification gets overwritten by the upgrade. That’s why docs/DISTRIBUTION.md enumerates the boundary explicitly — before this command runs, the operator can check whether any of their changes will be overwritten.

Don’t run this with uncommitted changes in your working tree. The command refuses to run dirty — see the pre-flight check. Commit or stash first.

How it fits

After this lands, re-running /bootstrap-agents re-specializes the updated agent templates against the project’s PRD + architecture. /doctor verifies the upgrade took effect cleanly.

What it does (quick)

  • Verifies the working tree is clean (refuses to run dirty)
  • Queries the upstream release feed for the latest version
  • Compares against the current .gembaflow-version file (or package.json equivalent)
  • Downloads the new framework files and syncs into the project, respecting the framework/user-content boundary from docs/DISTRIBUTION.md
  • Outputs a summary of files changed + a recommendation to re-run /bootstrap-agents and /doctor
  • /doctor — surfaces “framework version is stale” as a check; natural trigger for running this command
  • /bootstrap-agents — the right follow-up after upgrade to re-specialize against the new templates
  • /report-issue — when an upgrade brings a regression, this command files an upstream issue

Canonical spec: .claude/commands/upgrade.md

Last updated on
/doctor/create-ticket