We taught an AI how to upgrade Magnolia DXP

Every Magnolia DXP team knows the shape of a platform upgrade. The steps are documented, the module matrices exist, the release notes are public. And yet a 6.2 or 6.3 to 6.4 upgrade still consumes senior-developer weeks — not because any single step is hard, but because there are so many of them, they have to happen in a precise order, and getting one wrong only shows up hours later as a cryptic build failure. Rewrite a javax.jcr import that should have stayed untouched, bump a POM before the Jakarta migration runs, miss a renamed artifact, and you're debugging a symptom two steps removed from its cause.

This is exactly the kind of work AI coding assistants should be good at: repetitive, rule-driven, verifiable against a known-good answer. But a generalist AI assistant doesn't know, out of the box, that OpenRewrite has to run before any POM edit, that vaadin-server becomes vaadin-server-mpr-jakarta, or which artifacts were renamed between 6.3 and 6.4. Point an unassisted AI at a Magnolia DXP upgrade, and you'll get something plausible — and wrong in the ways that matter most.

So, for upgrades, we did what we already did for Magnolia DXP development: we documented the expert knowledge as skills.

The magnolia-upgrade-6 plugin grew out of real customer-project upgrades. Every upgrade our services team ran taught us something: which order of operations avoids rework, which module renames trip people up, which config has to be pulled from the live instance rather than assumed. That experience is now a self-contained plugin — one driver skill, one estimator, and three specialist sub-skills the driver calls on automatically.

While the earlier Magnolia DXP development skills are reference material an AI consults while building, the upgrade plugin is a procedure it follows. It reads the project, detects what applies, does the mechanical work, checks its own output, and stops at every point where a person should look at a diff before it becomes a commit.

Think of it as the difference between handing an AI assistant the upgrade guide and handing it a senior engineer's runbook, caution included.

The driver detects which of these apply to a given project. One with no jsmodels never sees the jsmodels skill; one with content apps gets the WARP UI audit automatically. [Image of the mgnl-upgrade-64 driver sequence, showing pre-flight checks through to the Docker smoke test, with the three specialist skills branching off where they apply]

An AI assistant editing dozens of files across a codebase needs more than competence — it needs restraint. The upgrade skills carry hard guardrails as part of their definition, and they're worth naming plainly because they're the reason a team can hand this work over at all:

Read together, these guardrails are the actual point of the plugin. Encoding the upgrade steps saves time; encoding where a human has to look before the work becomes permanent is what makes that time savings safe to take.

The skills are built for AI coding assistants that support the open skills format — Claude Code among them. Once the magnolia-upgrade-6 plugin is published alongside the existing magnolia-development-6 plugin, installing it and pointing it at the project you want to upgrade looks like this:

Add --dry-run to see the full plan without writing anything, or --target-version to pin to a specific 6.4.x release. Everything the skill needs — the customer upgrade guide, the module and incubator matrices, per-version release-note digests, and neutralized example patches — ships bundled inside the plugin, so it behaves the same on every machine and doesn't depend on live documentation lookups at runtime.

That said, the skill operationalizes Magnolia DXP's official upgrade documentation; it doesn't replace it. For the source material behind the driver's logic, or for anything project-specific the skill flags in its run report, the official guides are still the reference: upgrading Magnolia 6.2 to 6.4 and the general guide to upgrading Magnolia DXP.

The upgrade itself was never the interesting part of a Magnolia DXP project — it's the toll you pay to get to the interesting part. With the playbook encoded as skills, the mechanical majority of the work runs at AI speed under human review, and your senior developers spend their time on what actually needs judgment: the custom code, the edge cases, the project-specific decisions no matrix can capture.

The platform has always been upgradeable. Now the AI assistants your developers already use know how, too.