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.overrides, patchedDependencies, resolutions, local patches, 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
   • 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 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