Upgrade Agent-Native

Rule

When an older Agent-Native app/branch needs to run on current packages, use
agent-native upgrade. Never "fix" upgrade breakage with
pnpm patch, pnpm patch-commit, pnpm.patchedDependencies,
pnpm.overrides, patchedDependencies, resolutions, local patch artifacts,
or edits under node_modules/@agent-native/* — especially not against
@agent-native/core or @agent-native/dispatch.

Why

Agents often respond to a failed core bump by inventing framework patches and
dispatch behavior overrides. That hides the real app-level break, drifts from
upstream, and makes the next upgrade worse. The supported path is bump →
install → refresh scaffold skills → verify, then fix app code only.

How

1. Preview migration codemods first

   npx @agent-native/core@latest upgrade --codemods

   Codemods are preview-by-default: read the diff before applying it. Do not
   manually edit imports before running this command; the migration manifest is
   the source of truth for renamed specifiers and symbols.

2. Apply the reviewed codemods, then run the upgrade

   npx @agent-native/core@latest upgrade --codemods --yes
   npx @agent-native/core@latest upgrade

   Or from an already-installed CLI: pnpm exec agent-native upgrade /
   agent-native upgrade.

   What it does:

   • Blocks (unless --force) when @agent-native/* overrides/patches exist
   • Rewrites non-local @agent-native/* dependency pins to latest
   • Runs the package manager install
   • Rewrites those pins to the exact versions the install resolved, so the
     committed manifest names one release instead of re-resolving next install
   • Runs skills update scaffold --project
   • Runs typecheck when the project has that script

3. Pull upstream template changes (optional, separate from the bump)

   agent-native upgrade moves package versions. It never touches files that
   were copied out of a template at scaffold time, so template fixes and
   improvements do not arrive with a bump.

   agent-native template status        # recorded ref vs latest, drift counts
   agent-native template diff          # what upstream changed, read-only
   agent-native template sync          # 3-way merge it into the app

   sync defaults to the ref matching the installed @agent-native/core, so
   run it after upgrade. It merges per file against a pristine baseline
   stored in refs/agent-native/template-baseline/<app-path>; files upstream
   did not touch are left alone, and real collisions get conflict markers.
   After resolving markers, run agent-native template accept — the baseline
   deliberately does not advance past an unresolved merge.

   Apps scaffolded before provenance existed have no baseline. Create one
   with agent-native template baseline before the first sync.

4. If upgrade or typecheck fails

   • Read the concrete error
   • Fix app source, actions, config, or env — not framework packages
   • Re-run agent-native upgrade or pnpm typecheck
   • Stop and ask the user if you cannot fix the app-level error

   Intentional app-level UI customization is a separate workflow. Read
   customizing-agent-native when the product needs to own a selectively
   copied component; do not use that path to reproduce framework runtime
   behavior or hide version skew.

5. Dry-run / partial runs

   agent-native upgrade --dry-run
   agent-native upgrade --skip-verify
   agent-native upgrade --skip-install   # package.json bumps only
   agent-native doctor --only migration-manifest

   migration-manifest has no opt-out. Run it in CI before upgrading to find
   imports that will break, then use npx @agent-native/core@latest upgrade --codemods
   to preview the supported rewrite.

Don't

• Don't add pnpm.overrides, overrides, resolutions, or
  patchedDependencies for any @agent-native/* package
• Don't run pnpm patch or pnpm patch-commit, or commit files under
  patches/, for any dependency
• Don't edit node_modules/@agent-native/core or
  node_modules/@agent-native/dispatch
• Don't invent local "dispatch behavior" shims to paper over version skew
• Don't keep iterating with more framework patches after a failed install
• Don't skip skills update scaffold --project after a core bump (the
  upgrade command does this for you)

Related Skills

• self-modifying-code — Tier 4: framework packages are off limits
• agent-native-docs — version-matched docs after the bump
• customizing-agent-native — intentional app-owned UI copies, not upgrade patches
• portability — keep app code provider-agnostic across upgrades