> ## Documentation Index
> Fetch the complete documentation index at: https://onvex-ai-admin-mcp-release-0-24-0-7b1e713.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# /pm:upgrade — Migrate State and Refresh PM Rules

> Refresh the CLAUDE.md managed rules block, run any pending state migrations, re-render PROJECT.md, and stamp the new pmVersion. Safe to run more than once.

`/pm:upgrade` brings your project up to date after installing a new version of PM. It refreshes the managed rules block in `CLAUDE.md`, runs any pending migrations on `.conductor/state.json`, re-renders `PROJECT.md`, and stamps the new `pmVersion` — all without touching your epic history or any non-PM content. Use it whenever the `SessionStart` briefing shows an upgrade nudge like `pm 0.4.0 → 0.4.1 available`.

## When to run it

The `SessionStart` briefing tells you when an upgrade is needed. The sequence is always:

1. Install the new PM version via the Claude Code plugin marketplace.
2. Run `/reload-plugins` (or restart Claude Code) to load the new plugin code into the running session.
3. Run `/pm:upgrade` to migrate your project's state and refresh the rules block.

If you skip step 2, Claude Code is still executing the old plugin code and the upgrade will not apply the correct migrations. The briefing message `"this is pm 0.4.0 but 0.4.1 is installed"` is the reload reminder — it means the reload has not happened yet.

## What it does

<Steps>
  <Step title="Refreshes the managed rules block">
    The managed PM section is replaced with the version shipped by the new plugin. Any content outside the managed delimiters — your own notes, other tool rules, project context — is left completely untouched.

    As of 0.24.0 the target file is platform-aware: `CLAUDE.md` on Claude Code, and on a platform that resolves project context through a precedence chain, whichever file that platform will actually read. Upgrading from a pre-0.24.0 release also migrates the block's own delimiter wording in place — detection keys on a stable prefix, so an older block is found and refreshed rather than duplicated.
  </Step>

  <Step title="Runs pending state migrations">
    The engine applies any schema migrations needed to bring `state.json` up to the new version's format. Migrations are idempotent: if your state is already at the target schema, the migration step is skipped with no changes written. The `0.24.0` migration stamps a `platform` field on repos that predate it, defaulting to `claude-code`.
  </Step>

  <Step title="Re-renders PROJECT.md">
    `PROJECT.md` is regenerated from the now-migrated `state.json`, picking up any new fields or formatting changes introduced in the new version.
  </Step>

  <Step title="Stamps pmVersion">
    The `pmVersion` field in `state.json` is updated to the newly installed version, so future `SessionStart` checks know the upgrade has been applied and stop showing the nudge.
  </Step>
</Steps>

## Idempotency

Running `/pm:upgrade` more than once is always safe. If your project is already at the latest version, every step is a no-op — nothing is written, nothing is changed, and the command exits cleanly.

<Warning>
  Always run `/reload-plugins` **before** `/pm:upgrade` when you've just installed a new version. If you skip the reload, Claude Code is still running the old plugin code, and the upgrade command will apply the old engine's logic rather than the new one. Reload first, then upgrade.
</Warning>

## Recommending adoption of new capabilities

After printing the changelog delta, PM doesn't just leave you to read it — the agent reviews each `Added` headline in the "What's new in pm" output and judges whether it describes an **opt-in capability** (a new flag, a new `set-*` subcommand, a new tracker/autonomy/review-mode behavior) rather than a bug fix or a change that applies automatically with no action needed. For anything opt-in that looks relevant to your project's current `.conductor/state.json` — say, you already have a primary tracker configured but haven't added a secondary one, or you're touching schema-sensitive files without `thorough` review mode turned on — the agent recommends it in one line: what it is, why it fits, and the exact command to enable it. It never enables anything on its own; adoption is always your call. If nothing in the delta is opt-in or relevant to your project, the agent says so rather than silently skipping the review.

## /pm:changelog — Review what changed between versions

`/pm:changelog` surfaces the PM plugin's own changelog entries that are newer than a given version, so you know exactly what a release brought rather than just that an upgrade happened. By default, the floor is the version stamped in your project's `.conductor/state.json` (`pmVersion`) — so running it after an upgrade shows you everything that version introduced.

`/pm:upgrade` automatically prints this changelog delta for the versions it crosses, so you see what changed as part of every upgrade. Use `/pm:changelog` directly to review the delta again or to inspect a different version range on demand.

```text theme={null}
/pm:changelog              # entries newer than this repo's stamped pmVersion
/pm:changelog --since 0.3.0   # everything released after 0.3.0
```