# adaptable-upgrade
Canonical page: https://www.adaptabletools.com/docs/getting-started-ai-skills-upgrade
- Plans a move to a newer AdapTable major, then applies that plan in a separate session
- Includes the AG Grid upgrade that has to move with it, and the State migration
The `adaptable-upgrade` AI Skill helps you to upgrade to a new AdapTable version.
It first **plans** a move to a newer major version of AdapTable, and then **applies** that plan.
The AI Skill can help you with:
- Upgrading from AdapTable 21 or later, one step at a time or jumping several versions
- The AG Grid version that AdapTable pairs with
- Changed Adaptable Options, the API, object types, CSS and AdapTableQL
- Migrating Initial State so it is compatible with the target version
- Applying the plan in a fresh session
- Do not use this for a Grid that is misbehaving on the version you already have (use `adaptable-debug`)
- Nor to add a feature (use `adaptable-dev`) or to add AdapTable for the first time (use `adaptable-setup`)
Plan our upgrade to AdapTable 24
Apply the plan in ADAPTABLE_UPGRADE_CHANGES.md with the adaptable-upgrade skill
Plan our move from AdapTable 22 to 24
Which AdapTable versions can we move to without upgrading AG Grid?
## How it Works
There are two modes, and they run in two sessions:
- **Plan mode** writes three files and does not touch the application
- **Apply mode** starts from those files in a fresh session and changes the application.
The workflow for the Skill is as follows:
- It finds every project, the versions, and the target you confirm
- It checks whether AG Grid must move, and asks how: `ag-update`, a version bump you handle, or already handled elsewhere
- It lists every change between the two versions that touches your code, and migrates each `initialState`
- It asks you, one by one, about behaviour changes and deprecations
- Apply mode moves the packages, applies the plan, then checks, builds and runs
### What the plan files hold, and how apply mode uses them
**Plan mode** writes three files and nothing else:
- `ADAPTABLE_UPGRADE_SCOPE.md` records the projects and their versions, the target and the AG Grid version it pairs with, the environment minimums (Node, TypeScript, framework), every shortfall, and your AG Grid decision
- `ADAPTABLE_UPGRADE_CHANGES.md` is the change list, verbatim: one entry per change that applies to your repository, with its `file:line` matches, what changed, the remedy and the release-note section. `BREAKING` entries always stay. `BEHAVIOUR` and `DEPRECATED` entries stay only if you chose to deal with them now
- `ADAPTABLE_UPGRADE_STATE/` holds every `initialState` literal after migration, as JSON, with a report per file of what it could not convert
**Apply mode**, in a fresh session
- moves AG Grid as the scope file says and every `@adaptabletools/*` package to the target
- applies the `BREAKING` entries file by file, replaces each `initialState` with its migrated copy, migrates leftover Expressions, then runs `check state`, `check expression` and `check setup`
- type-checks, builds and runs the app, and reads the console for anything AdapTable marks "(needs migration)"
- It does not run AG Grid's codemod
- AG Grid moves through `ag-update`, or you handle it from AG Grid's own upgrade guide
| | |
| --- | --- |
| What the agent asks | - It does not ask on every step
- It asks only when a choice is hard to undo, and then carries on
- Whether to resume or start fresh, when plan files already exist. It never resumes silently
- The projects in scope, their current versions and the target major
- How to handle AG Grid when it has to move
- For each behaviour change or deprecation: accept the new behaviour, or keep the old one
- In apply mode, how saved user State, remote persistence and Team Sharing roll out. It changes nothing in storage
|
| What it writes | - Plan mode: the three plan files only. Never application source or `package.json`
- Apply mode: the application
|
| What it runs | - You do not run these — the agent does: `detect`, `compat`, `changes`, `migrate state`, `migrate expression`, `check state --major `, `check expression` and `check setup`
|
| When it is finished | - Plan: the three files exist, your projects, target and AG Grid decision are recorded, and no application file changed
- Apply: the build is green, the checks are clean, the application starts, and the report lists what is left to do by hand
|
### Taking a look inside the Skill
After you install the Skill, `adaptable-upgrade` looks like this:
```text
adaptable-upgrade/
├── SKILL.md # description + procedure
├── VERSION.md # the version checked against /.well-known/skills/VERSION
├── scripts/
│ └── adaptable.mjs # runs the CLI at the version the Skill was built for
└── references/
├── plan-preamble.md # what each plan file starts with
├── apply-order.md # the order apply mode follows
└── _shared/ # the same in every Skill
├── grounding.md
├── docs-protocol.md
├── validation-loop.md
├── conversation.md
├── guards.md
├── capabilities.md
└── agents-snippet.md
```
## Examples
### Upgrade an AdapTable Version
Plan our upgrade to AdapTable 24
1. Finds every project using AdapTable, with its framework and versions, and confirms with you the projects and the target version
2. Checks whether AG Grid must move too, and if so asks how: through AG Grid's own `ag-update` Skill, as a version bump you handle, or elsewhere
3. Lists every change between your version and 24 that touches your code, with the file and line, and migrates each `initialState` into a separate folder
4. Walks you through the behaviour changes and deprecations one by one: keep the new behaviour, or keep the old one
5. Writes three plan files, and changes nothing in the application
You get a plan to review:
- `ADAPTABLE_UPGRADE_SCOPE.md` (projects, versions, your answers)
- `ADAPTABLE_UPGRADE_CHANGES.md` (each change, where it hits your code and how to fix it)
- `ADAPTABLE_UPGRADE_STATE/` (your Initial State, already migrated)
A typical plan run would look like:
1. **Freshness** — Skills version matches the docs site
2. **Resume check** — no earlier plan files
3. **Scope** — one React project on AdapTable 23; target 24 confirmed; AG Grid must move to 36.2, TypeScript meets the 5.5.4 floor
4. **AG Grid** — you chose "Run `ag-update` now"; its plan sits next to this one and apply mode runs it first
5. **Changes** — 3 `BREAKING`, 2 `DEPRECATED` and 5 `BEHAVIOUR` records apply; 1 `initialState` migrated to `ADAPTABLE_UPGRADE_STATE/`, 0 leftovers
6. **Trim** — you kept both deprecations and accepted the 3 Adaptable Options behaviour changes; the 2 deployment notes stay
7. **Report** — the plan is ready, and nothing in the application has changed. Start a new session and ask it to apply the plan in `ADAPTABLE_UPGRADE_CHANGES.md` with the adaptable-upgrade skill
A `BREAKING` entry in `ADAPTABLE_UPGRADE_CHANGES.md`, as the CLI writes it (shortened):
```markdown
#### Swatch colour variables
- **BREAKING** · auto-migrated: n/a · id `css-color-swatch-palette`
- `--ab-color-swatch-1 … --ab-color-swatch-20` → `--ab-color-palette-13 … --ab-color-palette-32 (same colours)`
- Note: Replace every --ab-color-swatch-N with --ab-color-palette-{N+12} in theme CSS, initialState styles and code.
- Release note: https://www.adaptabletools.com/support/version-240-release-note#chg-css-color-swatch-palette
- Matches: `src/styles.css:13`
```
The applying session checks every rewritten State and Expression.
It then type-checks, builds and runs the application, and reports anything AdapTable could not migrate.
### Apply an Upgrade Plan
Apply the plan in ADAPTABLE_UPGRADE_CHANGES.md with the adaptable-upgrade skill
In a fresh session, moves the packages, applies the plan file by file, swaps in the migrated Initial State, then checks, builds and runs.
The changed files, and a list of anything left to do by hand.
### Which changes affect you
What changes between AdapTable 22 and 24 affect us?
Writes the plan files for that range — only the changes your code hits, plus the ones that always apply — and edits nothing.
A reviewable list, before you commit to the upgrade.