agentleFS
kvdm-co-pilotkvdm-co-pilot/create-cmp/skills/cmp-upgrade/SKILL.md

cmp-upgrade

Skill0 starsChanged 47 days agoMITView on GitHub

Migrate an existing Kotlin/Compose Multiplatform (CMP/KMP) project to the next PROVEN-GREEN dependency version set. Use this when the user wants to upgrade Kotlin, KSP, Compose Multiplatform, Room, AGP, Koin, or Ktor versions in a KMP project, bump their KMP dependencies, or asks "upgrade kotlin/compose/KMP versions", "bump my KMP dependencies", "update my version catalog", "my build broke after updating kotlin", "kotlin and ksp version mismatch", "migrate to the latest CMP", or "is my libs.versions.toml up to date". Diffs the project's gradle/libs.versions.toml against a CI-verified version set, applies surgical in-place edits with backups, guards the kotlin↔ksp lockstep, and can prove the result with the green-build gate. Works on ANY project with a Gradle version catalog — not just create-cmp-scaffolded ones.

The file

Files
SKILL.md

cmp-upgrade — move a KMP project to a proven-green version set

Your job: turn "upgrade my KMP versions" (or "my build broke after a version bump") into a project sitting on a proven-green version set — one that is known to build on Android + iOS — without hand-editing versions one at a time. You wrap the engine's upgrade command (exposed on the CLI as the upgrade subcommand). Do not hand-edit libs.versions.toml yourself when the engine can do it — the engine diffs, guards the lockstep, writes surgically, and backs up.

Why this exists. The recurring pain of KMP is that Kotlin / KSP / Compose / Room / AGP move in lockstep or the build dies. Upgrading "just Kotlin" is how projects break: ksp must always be <kotlin>-<kspVersion> (e.g. kotlin 2.2.20 ↔ ksp 2.2.20-2.0.4), Room on iOS needs ksp.useKSP2=true, and AGP pins a minimum Gradle wrapper. A proven-green set moves all of them together — one command instead of a day of dependency archaeology.

The workflow: diff → apply → verify

# 1. DIFF (safe, writes nothing) — show what the upgrade would change:
node "${CLAUDE_PLUGIN_ROOT}/bin/create-cmp.mjs" upgrade --dry-run
#    (add --target-dir <dir> when not running from the project root,
#     --set <id> to target a specific registry set instead of the latest)

# 2. APPLY — after the user has seen and accepted the diff:
node "${CLAUDE_PLUGIN_ROOT}/bin/create-cmp.mjs" upgrade --yes

# 3. VERIFY — prove the build is green (or chain it: upgrade --yes --verify):
node "${CLAUDE_PLUGIN_ROOT}/bin/create-cmp.mjs" verify

(If invoked from the published package: npx create-cmp-cli@latest upgrade ….)

What the engine does when applying:

  • Rewrites only the changed version values in gradle/libs.versions.toml — surgical line edits; comments, formatting, and every unrelated line are preserved byte-for-byte.
  • Adds/updates the gradle.properties flags the set requires (e.g. ksp.useKSP2=true).
  • Updates the Gradle wrapper distributionUrl when the set pins one.
  • Rewrites compileSdk / targetSdk in composeApp/build.gradle.kts when the set pins them (its androidSdk block) — the Android SDK levels are coupled to the set (a newer AGP + newer androidx force a higher compileSdk), so the version set manages them too, not just the catalog.
  • Backs up every touched file before writing into one directory per run, build/create-cmp-upgrade/<timestamp>/<file> (Gradle's ignored output root — never beside the file, where a backup inside an Android res/ directory breaks the build), and prints the exact mv commands to revert. ./gradlew clean does not remove the backups (the root project has no clean task); create-cmp clean does, and keeps build/create-cmp-upgrade/ while it holds an unresolved *.cmp-new. Every *.bak-upgrade and *.cmp-new an earlier engine left in the tree is moved first to build/create-cmp-upgrade/<timestamp>/legacy/<its path> — never deleted, each move reported (a tracked one shows in git as deleted; the report says where it went).
  • Versions the project declares that the set doesn't know are left untouched (and warned), so project-specific dependencies survive.

The lockstep guardrail — relay it, don't fight it

The engine refuses to write any file where the resulting ksp is not in lockstep with kotlin — either <kotlin> (the KSP2 aligned scheme, from Kotlin 2.3) or <kotlin>-<kspVersion> (the classic KSP1 form). If it errors with a lockstep violation, that is the product working as designed: the target set or the project's partial state would produce a known-dead build. Fix by upgrading kotlin and ksp together (which is exactly what a registry set does) — never by overriding one of them by hand.

Consent gating

Applying mutates the user's build files. Default behavior is a dry run: without --yes (or an interactive "y"), nothing is written. Show the user the diff table first and get their go-ahead before passing --yes. Never skip straight to apply on a project you haven't diffed.

Any project welcome

This works on any Gradle project with a gradle/libs.versions.toml, whoever scaffolded it. The engine detects the create-cmp frozen-set marker only to adjust messaging — for non-create-cmp projects, review the diff with extra care (their catalog may pin versions for reasons the registry doesn't know), and lean on the warned "left untouched" list.

Report

Tell the user: which set was targeted (and its notes — they explain the lockstep and the KSP2/iOS catch-22), the change table, which files were written and where the backups are (build/create-cmp-upgrade/<timestamp>/), the revert commands, and the GREEN/FAIL verdict if --verify/verify was run. If the build is not green afterwards, revert with the printed mv commands and run cmp-doctor to diagnose. If the toolchain itself is incomplete, point them at cmp-doctor first.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.