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
For the Core 0.198.0 package and import migration, follow the
Core 0.198.0 upgrade runbook.
It covers the preview and apply commands, Toolkit and optional peer packages,
codemod limits, and a symbol-level path map.
Preview migration codemods first
npx @agent-native/core@0.198.0 upgrade --codemods --dry-run
--dry-run previews the diff without writing. Do not manually edit imports
before applying the codemod; the migration manifest is the source of truth
for renamed specifiers and symbols.
Apply the reviewed upgrade and codemods
npx @agent-native/core@0.198.0 upgrade --codemods
Use the versioned CLI while the app still has Core 0.196 or another older
Core version: its local CLI carries an older migration manifest. After Core
0.198.0 is installed, npx agent-native upgrade --codemods (or
pnpm exec agent-native upgrade --codemods from an already-installed CLI)
uses the matching manifest. Either invocation applies supported codemods and
runs the upgrade, including dependency installation, scaffold skill refresh,
and typecheck when available. Do not run a second upgrade command just to
apply the codemods.
Afterward, run npx agent-native doctor from the app root. Its default
migration-manifest and feature-dependencies checks report stale imports
and missing optional peers detected from local settings. Confirm remote
deployment settings separately because Doctor cannot inspect them.
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
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.
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.
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
1---2name: upgrade-agent-native3description: >-4 Bring an older Agent-Native app or workspace current. Use when updating5 @agent-native/core, fixing a broken upgrade, or when tempted to patch or6 override core/dispatch packages to make an old branch run.7scope: dev8metadata:9 source: https://skillmd.com/skills/builderio/upgrade-agent-native10 internal: true11---1213# Upgrade Agent-Native1415## Rule1617When an older Agent-Native app/branch needs to run on current packages, use18`agent-native upgrade`. Never "fix" upgrade breakage with19`pnpm patch`, `pnpm patch-commit`, `pnpm.patchedDependencies`,20`pnpm.overrides`, `patchedDependencies`, `resolutions`, local patch artifacts,21or edits under `node_modules/@agent-native/*` — especially not against22`@agent-native/core` or `@agent-native/dispatch`.2324## Why2526Agents often respond to a failed core bump by inventing framework patches and27dispatch behavior overrides. That hides the real app-level break, drifts from28upstream, and makes the next upgrade worse. The supported path is bump →29install → refresh scaffold skills → verify, then fix **app** code only.3031## How3233For the Core 0.198.0 package and import migration, follow the34[Core 0.198.0 upgrade runbook](../../../packages/core/docs/content/upgrading-core-ui.mdx).35It covers the preview and apply commands, Toolkit and optional peer packages,36codemod limits, and a symbol-level path map.37381. **Preview migration codemods first**3940 ```bash41 npx @agent-native/core@0.198.0 upgrade --codemods --dry-run42 ```4344 `--dry-run` previews the diff without writing. Do not manually edit imports45 before applying the codemod; the migration manifest is the source of truth46 for renamed specifiers and symbols.47482. **Apply the reviewed upgrade and codemods**4950 ```bash51 npx @agent-native/core@0.198.0 upgrade --codemods52 ```5354 Use the versioned CLI while the app still has Core 0.196 or another older55 Core version: its local CLI carries an older migration manifest. After Core56 0.198.0 is installed, `npx agent-native upgrade --codemods` (or57 `pnpm exec agent-native upgrade --codemods` from an already-installed CLI)58 uses the matching manifest. Either invocation applies supported codemods and59 runs the upgrade, including dependency installation, scaffold skill refresh,60 and typecheck when available. Do not run a second upgrade command just to61 apply the codemods.6263 Afterward, run `npx agent-native doctor` from the app root. Its default64 `migration-manifest` and `feature-dependencies` checks report stale imports65 and missing optional peers detected from local settings. Confirm remote66 deployment settings separately because Doctor cannot inspect them.6768 What it does:6970 - Blocks (unless `--force`) when `@agent-native/*` overrides/patches exist71 - Rewrites non-local `@agent-native/*` dependency pins to `latest`72 - Runs the package manager install73 - Rewrites those pins to the exact versions the install resolved, so the74 committed manifest names one release instead of re-resolving next install75 - Runs `skills update scaffold --project`76 - Runs `typecheck` when the project has that script77783. **Pull upstream template changes (optional, separate from the bump)**7980 `agent-native upgrade` moves package versions. It never touches files that81 were copied out of a template at scaffold time, so template fixes and82 improvements do not arrive with a bump.8384 ```bash85 agent-native template status # recorded ref vs latest, drift counts86 agent-native template diff # what upstream changed, read-only87 agent-native template sync # 3-way merge it into the app88 ```8990 `sync` defaults to the ref matching the installed `@agent-native/core`, so91 run it after `upgrade`. It merges per file against a pristine baseline92 stored in `refs/agent-native/template-baseline/<app-path>`; files upstream93 did not touch are left alone, and real collisions get conflict markers.94 After resolving markers, run `agent-native template accept` — the baseline95 deliberately does not advance past an unresolved merge.9697 Apps scaffolded before provenance existed have no baseline. Create one98 with `agent-native template baseline` before the first sync.991004. **If upgrade or typecheck fails**101102 - Read the concrete error103 - Fix **app** source, actions, config, or env — not framework packages104 - Re-run `agent-native upgrade` or `pnpm typecheck`105 - Stop and ask the user if you cannot fix the app-level error106107 Intentional app-level UI customization is a separate workflow. Read108 `customizing-agent-native` when the product needs to own a selectively109 copied component; do not use that path to reproduce framework runtime110 behavior or hide version skew.1111125. **Dry-run / partial runs**113114 ```bash115 agent-native upgrade --dry-run116 agent-native upgrade --skip-verify117 agent-native upgrade --skip-install # package.json bumps only118 agent-native doctor --only migration-manifest119 ```120121 `migration-manifest` has no opt-out. Run it in CI before upgrading to find122 imports that will break, then use `npx @agent-native/core@latest upgrade --codemods`123 to preview the supported rewrite.124125## Don't126127- Don't add `pnpm.overrides`, `overrides`, `resolutions`, or128 `patchedDependencies` for any `@agent-native/*` package129- Don't run `pnpm patch` or `pnpm patch-commit`, or commit files under130 `patches/`, for any dependency131- Don't edit `node_modules/@agent-native/core` or132 `node_modules/@agent-native/dispatch`133- Don't invent local "dispatch behavior" shims to paper over version skew134- Don't keep iterating with more framework patches after a failed install135- Don't skip `skills update scaffold --project` after a core bump (the136 upgrade command does this for you)137138## Related Skills139140- **self-modifying-code** — Tier 4: framework packages are off limits141- **agent-native-docs** — version-matched docs after the bump142- **customizing-agent-native** — intentional app-owned UI copies, not upgrade patches143- **portability** — keep app code provider-agnostic across upgrades