Upgrade Agent Native

---
name: upgrade-agent-native
description: >-
  Bring an older Agent-Native app or workspace current. Use when updating
  @agent-native/core, fixing a broken upgrade, or when tempted to patch or
  override core/dispatch packages to make an old branch run.
scope: dev
metadata:
  internal: true
---

# 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**

   ```bash
   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**

   ```bash
   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.

   ```bash
   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**

   ```bash
   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