Gradle → Kotlin Toolchain Project Migration

Two jobs at once: a mechanical translation of dependencies and configuration, plus a replacement for every Gradle plugin the Toolchain has no native answer for. Templates to adapt are in references/examples.md, drawn from one real migration.

Lean on the companion skills for the plugin-shaped subproblems:

kotlin-tooling-kotlin-toolchain

for syntax,

kotlin-tooling-gradle-to-kotlin-toolchain-plugin

for the per-plugin port workflow (you will run it once per Gradle plugin without a native equivalent),

kotlin-tooling-kotlin-toolchain-plugin-authoring

for plugins written from scratch.

Principles

Preserve source code. If the migration forces edits to business logic, a local plugin can probably fill the gap instead. Code reading
```
release.properties
```
off the classpath should keep working — publish that exact file, don't rewrite the consumer.
Every third-party Gradle plugin is drop, native, or reimplement — never "keep the Gradle plugin". Your own convention plugins are different:
```
buildSrc
```
/
```
build-logic
```
precompiled scripts are shared configuration, so they become module templates, not local plugins — see
No
```
buildSrc
```
/ convention plugins
.
Search GitHub before authoring a local plugin. Someone has probably already written it; vendoring a working implementation beats a from-scratch port every time. Where to look and what to search for: Phase 2 "Scope". Author only after the search comes up empty. Read what you vendor end to end before wiring it in — it runs at build time with full filesystem and network access.
All dependencies should reside in version catalog.
```
gradle/libs.versions.toml
```
survives as the built-in
```
$libs.*
```
catalog. Every coordinate in every module/plugin YAML must end up as a
```
$libs.*
```
reference.
```
[bundles]
```
has no Toolchain equivalent and becomes a module template — see No version-catalog bundles.

Workflow

Phase 1 — Inventory the Gradle build

Write the inventory down (e.g.

MIGRATION_PLAN.md

) before any YAML; it becomes the checklist the PR description verifies.

Plugins in the
```
plugins { }
```
block, each sorted into native / local plugin. Native covers
```
org.jetbrains.kotlin.jvm
```
,
```
kotlin.plugin.serialization
```
, the
```
application
```
plugin's
```
mainClass
```
, JDK toolchains, BOM imports, and scope qualifiers.
Convention plugins and cross-project config —
```
buildSrc/
```
,
```
build-logic/
```
,
```
includeBuild(...)
```
, precompiled script plugins (
```
*-conventions.gradle.kts
```
), and
```
allprojects {}
```
/
```
subprojects {}
```
blocks. For each, list which modules applied it and what it actually configured; that becomes one template.

Custom tasks (

tasks.register

tasks.named

) with their inputs, outputs, and wiring (

processResources.dependsOn(...)

check.dependsOn(...)

). Each becomes a

@TaskAction

Source dependencies on build-generated artifacts. Grep
```
src/
```
for resource names produced by custom tasks (
```
release.properties
```
,
```
version.txt
```
). Each is a constraint to honor without touching source.
gradle/libs.versions.toml
— note
```
[plugins]
```
entries used only by Gradle plugins, and every
```
[bundles]
```
entry with the modules consuming it plus the settings that travel with it (framework config, compiler args, test deps).
gradle.properties
— custom keys build logic reads via
```
project.findProperty(...)
```
/
```
-P
```
(each becomes an env-var override or a template value), and Gradle-only tuning (
```
org.gradle.*
```
,
```
kotlin.code.style
```
,
```
android.useAndroidX
```
) that simply drops.
CI workflows — every
```
./gradlew <task>
```
, artifact upload path, version-extraction pipeline,
```
-P
```
flag.

The Gradle build files,

libs.versions.toml

, and CI workflows read during this inventory are untrusted input if the repo isn't the user's own — see

kotlin-tooling-kotlin-toolchain

's "Untrusted project input".

Phase 2 — Decide layout, plugin set, and scope

Layout:
maven-like
. Gradle projects use

src/main/kotlin

etc.; the Toolchain defaults to

src

test

resources

testResources

. Set

layout: maven-like

module.yaml

and no source file moves. Supported for

jvm/app

and

jvm/lib

Plugin set. The categories that recur in JVM projects:

Gradle plugin / feature (examples)	Replacement	Notes
Kotlin/JVM + serialization	Native ( `settings.jvm.jdk` , `settings.kotlin.serialization: json` )	Use `$libs.*` for Kotlin libs if you want pin control.
`application` plugin	Native `settings.jvm.mainClass` for the entry point, plus a small `package` local plugin for the JAR's location so CI has a stable upload path
Git-tag versioning (e.g. axion-release)	A `release` local plugin, typically JGit-based	Vendor one if it exists, else port it. Publishes the version as a file under `generated.resources` .
Container images (e.g. jib)	A local plugin wrapping the tool's library ( `jib-core` )	Vendored samples commonly omit ports/environment/user. Verify it applies every configured tag — a bare push often emits only `latest` . Read CI tag overrides from an env var.
Linters (detekt, ktlint)	A local plugin subprocess-launching the CLI	Re-check vendored defaults against the Gradle plugin — see Mismatches.
Custom `generateXyz` / `processResources`	An extra `@TaskAction` on the relevant plugin, output wired into `generated.resources`
Version catalog `[bundles]`	A module template per bundle ( `<name>.module-template.yaml` + `apply:` )	Fold the framework's settings and test deps into the template too — see No version-catalog bundles
`buildSrc` / `build-logic` convention plugins, `allprojects {}` / `subprojects {}`	A module template per convention script; only its imperative leftovers become a local plugin	Convention hierarchies map onto nested templates — see No `buildSrc` / convention plugins

Each local plugin is a

jvm/amper-plugin

module.

Scope. For every plugin on the list, search GitHub before writing any Kotlin. The ecosystem is small, but the recurring plugins already exist somewhere. Search order:

JetBrains/kotlin-toolchain

→

build-sources/

(

detekt

dokka

binary-compatibility-validator

protobuf

generate-build-properties

project-commands

) — the local plugins the Toolchain builds itself with, i.e. de facto reference implementations. Also

plugin-samples/

and

docs/

in the same repo.

GitHub code search on the plugin marker rather than the tool name:

"product: jvm/amper-plugin"

path:plugin.yaml "@TaskAction"

"jvm/amper-plugin" jib

The tool's own repo — most linters/packagers ship a
```
-cli
```
or
```
-core
```
artifact, which is all a thin wrapper plugin needs, so "no plugin exists" often still means "a 50-line wrapper exists".

Then pick per plugin: vendor (copy a hit as-is; keep its license header and add a comment with the source URL + commit so it can be re-synced), extend (vendor + extra Settings fields), or author (nothing found, or the need is bespoke). Sensible default for one PR: vendor what exists, author the small bespoke ones (a

package

plugin, a thin linter wrapper), defer the rest. Always diff a vendored plugin's behavior against the Gradle plugin it replaces before trusting it — see A vendored linter plugin can be stricter than the Gradle plugin.

Phase 3 — Implement

Copy
```
kotlin
```
/
```
kotlin.bat
```
from a reference Toolchain project (for example this one) or
```
kotlin init
```
in a scratch dir. Pin
```
kotlintoolchain=<version>
```
in
```
.sdkmanrc
```
to match the wrapper.
Write
```
project.yaml
```
with all plugin module paths.
Per plugin: search GitHub first (Phase 2 "Scope"), then vendor or author it under
```
plugins/<name>/
```
, running
```
./kotlin show modules
```
after each to confirm the model still loads.
Write the templates at the project root: one
```
<name>.module-template.yaml
```
per convention script and per
```
[bundles]
```
entry with two or more consumers (dependencies plus the settings, test deps, and repositories that travel with them), nested the way the Gradle conventions were.
Write the root
```
module.yaml
```
:
```
product: jvm/app
```
,
```
layout: maven-like
```
,
```
$libs.*
```
dependencies, an
```
apply:
```
list for the templates, and a
```
plugins:
```
block enabling each local plugin with its non-default settings.

Validate each plugin in isolation:

./kotlin task :<module>:<task>@<plugin>

./kotlin do <command>

Rewrite CI (Phase 4).

Delete

build.gradle.kts

gradlew

gradlew.bat

gradle/wrapper/

— but keep

gradle/libs.versions.toml

Sweep the catalog: drop the whole
```
[plugins]
```
block, any
```
[versions]
```
keys that only fed it, and
```
[bundles]
```
once every consumer applies a template.
Sweep every
```
module.yaml
```
/
```
plugin.yaml
```
for literal Maven coordinates and replace them with
```
$libs.<key>
```
.

Phase 4 — Rewrite CI

Set
```
KOTLIN_CLI_NO_WELCOME_BANNER: "1"
```
.

./gradlew build && ./gradlew check

→

./kotlin build && ./kotlin check

(which runs every plugin's

checks:

registrations plus tests).

```
./gradlew jib -Djib.to.tags=…
```
→
```
./kotlin do jib
```
, with tags passed through an env var the plugin reads. Vendored jib-style plugins usually lack that hook — add it while vendoring.
Artifact upload path changes: Gradle's
```
build/libs/<name>.jar
```
is gone and
```
jarJvm
```
writes to a Toolchain-internal path. Author a
```
package
```
plugin staging the JAR at
```
${module.rootDir}/build/libs/${module.name}.jar
```
so uploading artifacts stays simple.

Phase 5 — Validate end-to-end

Run each user-facing command locally and record the output in the PR's test plan:

./kotlin show modules            # project model loads, all expected modules listed
./kotlin clean && ./kotlin build
./kotlin test
./kotlin check                   # linters + tests; expect zero violations after Phase 3
./kotlin do currentVersion       # if applicable
./kotlin do jib                  # or jibBuildTar to avoid pushing locally (if applicable)
./kotlin do package              # verify build/libs/<name>.jar and its Main-Class manifest (if applicable)
./kotlin do ktlintFormat         # if applicable

Mismatches to watch

${...}

interpolation in

module.yaml

configFile: ${module.rootDir}/detekt.yml

is taken literally. Use a module-relative path (

configFile: detekt.yml

). Interpolation works only in

plugin.yaml

Module name comes from the directory name

There is no

name:

field.

actions/checkout

clones into a directory named after the GitHub repo, while a local worktree may resolve

${module.name}

to something else. Never hardcode the module name into a plugin task's output path — use

${module.name}

Plugin settings without

enabled: true

are ignored

yaml

plugins:
  release: enabled         # shorthand — only valid with no other settings
  jib:                     # long form — required as soon as any setting is present
    enabled: true
    container:
      mainClass: com.example.App

Settings without

enabled: true

produce only a warning ("Plugin X is not enabled, but has some explicit configuration") and the plugin is skipped.

A vendored linter plugin can be stricter than the Gradle plugin

Diff the flags the vendored plugin passes against the Gradle plugin's default task, and gate anything stricter behind an opt-in setting so the default matches the old behaviour.

The canonical case: the upstream detekt plugin (

amper/build-sources/detekt/

) always passes

--classpath

detekt-cli

, enabling type resolution, which Gradle's default

detekt

task does not. Used as-is it surfaces violations Gradle never reported (notably

UnreachableCode

on elvis-with-return). Fix: add

useTypeResolution: Boolean get() = false

to the plugin's Settings and gate the flag on it — patch in references/examples.md.

No version-catalog bundles

Only

[libraries]

keys resolve (

$libs.<key>

$libs.bundles.<name>

does not exist and

[bundles]

in the catalog is dead config the Toolchain never reads. The official answer (KTC-4759) is a module template per bundle, applied wherever the bundle was used:

toml

# gradle/libs.versions.toml — before
[bundles]
ktor-server = ["ktor-server-core", "ktor-server-netty", "ktor-server-content-negotiation"]

yaml

# ktor-server.module-template.yaml — at the project root; templates cannot declare product:
dependencies:
  - $libs.ktor.server.core
  - $libs.ktor.server.netty
  - $libs.ktor.server.content.negotiation

settings:
  kotlin:
    serialization: json

test-dependencies:
  - $libs.ktor.server.test.host

yaml

# module.yaml
product: jvm/app

apply:
  - //ktor-server.module-template.yaml

Templates are the better target, not just a workaround: a bundle carries coordinates only, while the framework it enables usually also needs

settings

(

kotlin.serialization

springBoot

freeCompilerArgs

test-dependencies

, and sometimes

repositories

. Put all of it in the template so one

apply:

line yields a working framework instead of a bare classpath.

Rules that might bite:

Path notation is
```
//<name>.module-template.yaml
```
, relative to the project root (where
```
project.yaml
```
is).
No
```
product:
```
in a template. Templates may
```
apply:
```
other templates; each is applied once even if reached through two paths, so list dependencies appear once.
Merge semantics: lists append, scalars are overridden, and
```
module.yaml
```
always wins regardless of where
```
apply:
```
sits in the file.
Two sibling templates setting the same scalar (e.g.
```
settings.jvm.release
```
) is a hard error ("Conflicting values for property"). Resolve by setting the value in the consuming
```
module.yaml
```
, or in a third template that applies both.
Don't convert a single-consumer bundle. Templates pay off from the second module; below that, inline the
```
$libs.*
```
list.
Templates express the union of platform-qualified sections too (
```
dependencies@jvm
```
,
```
settings@android
```
), so a KMP bundle split across source sets still fits one template.

buildSrc

/ convention plugins — shared config goes in templates

buildSrc/

build-logic/

, and

includeBuild(...)

have no counterpart, and

project.yaml

carries only

modules:

and

plugins:

— there is no root-project inheritance and nowhere to put imperative shared build logic. A local plugin is also the wrong target: plugins contribute tasks, they don't inject module configuration. A precompiled script plugin is mostly declarative, so it translates to one

<name>.module-template.yaml

, applied by the modules that used

plugins { id("<name>") }

kotlin

// buildSrc/src/main/kotlin/service-conventions.gradle.kts
plugins {
    kotlin("jvm")
    kotlin("plugin.serialization")
}
kotlin { jvmToolchain(21) }
repositories { maven("https://jitpack.io") }
dependencies {
    implementation(libs.ktor.server.core)
    testImplementation(libs.kotest.runner.junit5)
}

yaml

# service-conventions.module-template.yaml
settings:
  jvm:
    jdk:
      version: 21
  kotlin:
    serialization: json

repositories:
  - id: jitpack
    url: https://jitpack.io

dependencies:
  - $libs.ktor.server.core

test-dependencies:
  - $libs.kotest.runner.junit5

Convention script construct	Template counterpart
`plugins { kotlin("jvm"), kotlin("plugin.serialization"), id("org.springframework.boot") }`	native `settings:` ( `settings.kotlin.*` , `settings.springBoot` , …)
`kotlin { jvmToolchain(21) }` , `java { targetCompatibility }`	`settings.jvm.jdk.version` , `settings.jvm.release`
`dependencies { implementation / api / testImplementation }`	`dependencies:` ( `: exported` for `api` ) and `test-dependencies:`
`repositories { }`	`repositories:`
`tasks.withType<Test> { useJUnitPlatform() }`	built-in / `settings.junit`
a convention script applying another convention script	nested templates ( `apply:` inside the template)
`allprojects {}` / `subprojects {}` in the root script	one template that every `module.yaml` applies
`tasks.register(…)` , `doLast { }` , anything imperative	the residue — a local plugin, one per behavior

Also:

Delete
```
buildSrc/
```
outright. Its
```
libs
```
catalog accessors are replaced by
```
$libs.*
```
used directly in the templates.
Splitting one fat convention script into several small templates (
```
jvm
```
,
```
ktor-server
```
,
```
testing
```
) is usually the better shape, and bundle templates fold into the same hierarchy — see No version-catalog bundles for the merge/conflict rules, which apply identically here.
Local-plugin enablement inside a template (a
```
plugins:
```
block in a
```
*.module-template.yaml
```
) is unverified. If a convention script enabled a plugin you reimplemented, keep the
```
plugins:
```
block in each
```
module.yaml
```
until you have confirmed the template form loads (
```
./kotlin show modules
```
plus an actual task run).

No dependency exclusions

There is no equivalent of Gradle's

exclude(group, module)

. Any transitive exclusion silently disappears and the library lands on the runtime classpath. Note the trade-off in the PR (usually a few hundred unused KB).

No plugin-to-plugin dependencies

Plugins are isolated. If two plugins logically belong together, put both task actions in the same plugin module or extract the library.

-P

-D

CLI overrides

Read ephemeral overrides (force-version, skip-checks, dynamic image tags) from environment variables inside the

@TaskAction

; don't count on a

--setting

flag either (the pinned CLI may reject it). Pattern in the

kotlin-tooling-gradle-to-kotlin-toolchain-plugin

skill.

Capturing a command's output value

println

from a

@TaskAction

is not a machine-readable channel. The Toolchain wraps it as

<ts> INFO :<module>:<task>@<plugin> <value>

and appends a

<task> successful

banner, so

./kotlin do currentVersion | tail -n1

yields the banner — and lowering

--log-level

error

off

drops the value line entirely, since it is emitted at INFO. Instead:

Have the task write the value to a file named by an env var and
```
cat
```
it. Moreover, other tasks can reuse this value down the line
Or read the git state the command produced:
```
git describe --tags --exact-match HEAD
```
.
If you must parse stdout, match the task coordinate:
```
awk '/<task>@<plugin>/ { v = $NF } END { print v }'
```
.

Test resources shadow

generated.resources

When a plugin emits

release.properties

and

src/test/resources/release.properties

exists, classpath ordering puts the test fixture first. It usually does the right thing but is brittle — if a test asserts a specific value, inject a stub service instead of relying on precedence.

Dependabot needs a stub

build.gradle.kts

Dependabot's gradle file fetcher requires a

build.gradle(.kts)

in the configured directory before it scans

gradle/libs.versions.toml

; without one,

package-ecosystem: "gradle"

silently no-ops. Keep an empty

build.gradle.kts

at the root with a comment explaining why. The Toolchain ignores it.

amd64-only container images on Apple Silicon

Images like

mongo:3.2

crash under Rosetta/QEMU on M-series Macs (

runtime: failed to create new OS thread (have 2 already; errno=22)

). Unchanged by the migration — the same image fails under

./gradlew check

. Flag it as pre-existing; CI on

ubuntu-latest

is unaffected.

iOS (KMP): a migrated

Info.plist

loses its

CFBundle*

keys

A Gradle/KMP iOS app keeps bundle metadata in the hand-maintained

iosApp.xcodeproj

(

GENERATE_INFOPLIST_FILE = YES

), so Xcode synthesizes

CFBundle*

keys and the checked-in

Info.plist

is intentionally partial. The Toolchain ignores that

.xcodeproj

, generates its own, and uses your plist verbatim — nothing synthesizes the keys, and the

.app

has no bundle id:

Simulator device failed to install the application. Missing bundle ID.

Fix: make the plist self-contained, keeping your app-specific keys alongside these:

xml

<key>CFBundleDevelopmentRegion</key><string>$(DEVELOPMENT_LANGUAGE)</string>
<key>CFBundleExecutable</key><string>$(EXECUTABLE_NAME)</string>
<key>CFBundleIdentifier</key><string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
<key>CFBundleInfoDictionaryVersion</key><string>6.0</string>
<key>CFBundleName</key><string>$(PRODUCT_NAME)</string>
<key>CFBundlePackageType</key><string>APPL</string>
<key>CFBundleShortVersionString</key><string>1.0</string>
<key>CFBundleVersion</key><string>1</string>

PRODUCT_BUNDLE_IDENTIFIER

is set on the generated target. Underlying behaviour: the

kotlin-tooling-kotlin-toolchain

skill's "iOS apps" section.

KMP: carry over every source set's dependencies

Translate each Gradle source set (

commonMain

jvmMain

androidMain

iosMain

commonTest

jvmTest

, …) into its Amper counterpart —

dependencies

dependencies@jvm

@android

@ios

test-dependencies

test-dependencies@<platform>

. Don't cherry-pick the obvious library deps:

A
```
*Main
```
dependency is also on that target's test classpath (
```
jvmTest
```
extends
```
jvmMain
```
), so dropping one can break tests with no compile error.
A dependency can look like it belongs to another module and still be load-bearing. Canonical case:
```
jvmMain { implementation(compose.desktop.currentOs) }
```
in a shared library reads like a desktop-app dep, but it supplies the Skiko native runtime (
```
skiko-awt-runtime-<os>
```
with
```
libskiko-<os>.dylib
```
+
```
.sha256
```
) that the module's own JVM Compose UI tests (
```
compose.uiTest
```
/
```
runComposeUiTest
```
) load at runtime.
```
compose.ui:ui-test
```
pulls only Skiko's classes, never the natives. Dropping it compiles fine, then fails with:
```
org.jetbrains.skiko.LibraryLoadException: Cannot find libskiko-macos-arm64.dylib.sha256, proper native dependency missing.
```
Not a Toolchain bug: Gradle fails identically without it. Restore under
```
dependencies@jvm
```
, or scope it to
```
test-dependencies@jvm
```
to keep Skiko natives off consumers' classpaths.

Guard against drops: diff each Gradle source set's dependency list against its Kotlin Toolchain section (names and count), then run

./kotlin show dependencies -m <module>

and compare with the Gradle build.

Common pitfalls

No
package
plugin. CI ends up uploading
```
build/artifacts/CompiledJvmArtifact/
```
(an internal class-file tree) instead of a JAR. Add the plugin before swapping the upload path.
Committing
build/
. Add it to
```
.gitignore
```
early; drop the old
```
.gradle/
```
entry.
String interpolation inside Maven coordinates.
```
com.example:foo:${pluginSettings.version}
```
in
```
plugin.yaml
```
fails with "Value of type 'ShadowDependency' doesn't support string interpolation". Use
```
$libs.foo
```
.

Kotlin Toolchain docs: https://kotlin-toolchain.org/dev/

kotlin-tooling-gradle-to-kotlin-toolchain-project

NPX Install

Tags

SKILL.md Content

Gradle → Kotlin Toolchain Project Migration

Principles

Workflow

Phase 1 — Inventory the Gradle build

Phase 2 — Decide layout, plugin set, and scope

Phase 3 — Implement

Phase 4 — Rewrite CI

Phase 5 — Validate end-to-end

Mismatches to watch

No
`${...}`
interpolation in
`module.yaml`

Module name comes from the directory name

Plugin settings without
`enabled: true`
are ignored

A vendored linter plugin can be stricter than the Gradle plugin

No version-catalog bundles

No
`buildSrc`
/ convention plugins — shared config goes in templates

No dependency exclusions

No plugin-to-plugin dependencies

No
`-P`
/
`-D`
CLI overrides

Capturing a command's output value

Test resources shadow
`generated.resources`

Dependabot needs a stub
`build.gradle.kts`

amd64-only container images on Apple Silicon

iOS (KMP): a migrated
`Info.plist`
loses its
`CFBundle*`
keys

KMP: carry over every source set's dependencies

Common pitfalls

kotlin-tooling-gradle-to-kotlin-toolchain-project

NPX Install

Tags

SKILL.md Content

Gradle → Kotlin Toolchain Project Migration

Principles

Workflow

Phase 1 — Inventory the Gradle build

Phase 2 — Decide layout, plugin set, and scope

Phase 3 — Implement

Phase 4 — Rewrite CI

Phase 5 — Validate end-to-end

Mismatches to watch

No ${...} interpolation in module.yaml

Module name comes from the directory name

Plugin settings without enabled: true are ignored

A vendored linter plugin can be stricter than the Gradle plugin

No version-catalog bundles

No buildSrc / convention plugins — shared config goes in templates

No dependency exclusions

No plugin-to-plugin dependencies

No -P / -D CLI overrides

Capturing a command's output value

Test resources shadow generated.resources

Dependabot needs a stub build.gradle.kts

amd64-only container images on Apple Silicon

iOS (KMP): a migrated Info.plist loses its CFBundle* keys

KMP: carry over every source set's dependencies

Common pitfalls

No
`${...}`
interpolation in
`module.yaml`

Plugin settings without
`enabled: true`
are ignored

No
`buildSrc`
/ convention plugins — shared config goes in templates

No
`-P`
/
`-D`
CLI overrides

Test resources shadow
`generated.resources`

Dependabot needs a stub
`build.gradle.kts`

iOS (KMP): a migrated
`Info.plist`
loses its
`CFBundle*`
keys