Verify Compiler Plugin Compatibility Agent Skill

Verify Compiler Plugin Compatibility

Systematically build the compiler plugin against each provided Kotlin compiler version,

identify compilation failures, and fix them.

Input

The user provides one or more Kotlin versions to verify. If none are given, determine

the set of versions to test by inspecting the CSM template version ranges in these files:

• compiler-plugin/compiler-plugin-backend/src/main/templates/kotlinx/rpc/codegen/VersionSpecificApiImpl.kt
• compiler-plugin/compiler-plugin-k2/src/main/templates/kotlinx/rpc/codegen/FirVersionSpecificApiImpl.kt

Extract the distinct version ranges from //##csm specific=[...] directives. For each

range, pick one actually published Kotlin release that falls within it. Also include

the current default from versions-root/libs.versions.toml kotlin-lang.

CSM range boundaries are NOT real Kotlin versions

CSM range lower bounds (e.g., 2.1.22, 2.1.11, 2.4.0) represent the Kotlin version

that introduced an API change, but that exact version may never have been published as a

stable release. Kotlin publishes specific patch versions (like 2.1.0, 2.1.20, 2.2.0,

2.2.20), not every number in sequence. **Never use CSM boundary values directly as build

versions** — they will fail to resolve from Maven Central.

Resolving real versions for each range

For each CSM range, find the lowest published Kotlin release that falls within it:

• Read the range bounds (e.g., 2.1.22...2.3.*)
• Look up actual published Kotlin releases. Use the managing_gradle_dependencies skill

to query Maven Central for available versions of org.jetbrains.kotlin:kotlin-stdlib

if you are unsure which versions exist.

• Pick the first published version that falls within the range.
• If the range's lower bound hasn't been published yet and no published version falls

within it, that range covers a future Kotlin version — test it via the Kotlin Master

workflow (see references/kotlin-master.md), not by guessing a version number.

Kotlin publishes in a pattern: X.Y.0, then X.Y.10, X.Y.20, etc. (not sequential

patches). For example, after 2.1.0 the next release was 2.1.10, then 2.1.20,

then 2.1.21 — there was never a 2.1.1 through 2.1.9 or a 2.1.11 through 2.1.19.

Build Execution: Use Gradle Skills

All builds MUST go through the running_gradle_builds skill. Do not run ./gradlew

directly via shell. The running_gradle_builds skill provides background orchestration,

structured failure analysis via inspect_build, and reliable output capture.

When invoking builds through the skill, use:

• projectRoot: absolute path to compiler-plugin/ directory
• Gradle task: clean compileKotlin
• Additional arguments: -Pkotlin.compiler=<VERSION>

Use inspect_build to diagnose failures -- it gives structured access to errors,

task outputs, and build problems rather than raw log parsing.

When you need to understand what a Kotlin compiler API looks like in a specific version,

use the searching_dependency_sources skill to search the Kotlin compiler jar for the

class or method name. This reveals new signatures, package locations, and parameter lists.

Workflow

Phase 1: Verify Each Version

For each Kotlin version, build the compiler plugin using the running_gradle_builds

skill with these arguments:

• Tasks: clean compileKotlin
• Extra args: -Pkotlin.compiler=<VERSION>
• Project root: absolute path to the compiler-plugin/ directory

The -Pkotlin.compiler=<VERSION> flag overrides the Kotlin compiler version at build

time. The CSM template processor reads this to select the right code blocks.

Record the result for each version: PASS or FAIL with the error summary.

After testing all versions, present a summary table:

| Version | Status | Errors |
|---------|--------|--------|
| 2.1.0   | PASS   |        |
| 2.1.20  | PASS   |        |
| 2.2.0   | FAIL   | 3 errors in FirVersionSpecificApiImpl.kt |
| 2.3.0   | FAIL   | 5 errors in VersionSpecificApiImpl.kt    |

If everything passes, report success and stop.

Phase 2: Diagnose Failures

For each failing version, use inspect_build with mode="details" to get structured

error information. Categorize every compilation error:

Category A -- Import change: A class/function moved to a different package.

Symptom: Unresolved reference on an import.

Category B -- Signature change: A method's parameters or return type changed.

Symptom: None of the following candidates is applicable, Too many arguments.

Category C -- API replacement: An entire API was replaced by a new mechanism.

Symptom: Unresolved reference on a class or method that no longer exists.

Category D -- Structural change: Property became function, List became MutableList, etc.

Symptom: Val cannot be reassigned, Type mismatch.

To understand what the new API looks like, use the searching_dependency_sources skill

to search the Kotlin compiler sources for the class or method name.

Phase 3: Fix Incompatibilities

Read references/csm-fix-patterns.md for the CSM template system, fix patterns (import

changes, signature changes, new VS methods, checker signatures), and the template files

reference table listing all CSM files that may need changes.

The key principle: **default blocks hold the latest version's code; specific blocks

hold older versions.**

Phase 4: Re-verify

After applying fixes, re-run the build (via the running_gradle_builds skill) for every

version that failed. If new errors appear, go back to Phase 2. Repeat until all versions

pass.

Then present the final summary:

All versions verified successfully:
| Version | Status |
|---------|--------|
| 2.1.0   | PASS   |
| 2.1.20  | PASS   |
| 2.2.0   | PASS   |
| 2.3.0   | PASS   |

Testing with Kotlin Master

This is a mandatory test for all changes to the compiler plugin.

If the user requests Kotlin Master testing, or after fixing incompatibilities for released

versions, read references/kotlin-master.md for the full download, build, and verification

workflow.

Updating Golden Test Data

After fixing CSM templates, golden file mismatches may occur in

:tests:compiler-plugin-tests. Read references/golden-test-data.md for the

scripts/update_test_data.sh usage and important caveats about passing properties to the test JVM.

Debugging Tips

• Use inspect_build from the running_gradle_builds skill to get structured error

details instead of parsing raw logs.

• Inspect generated CSM output in <module>/build/generated-sources/csm/ after building.
• CSM logs matched blocks: look for [CSM] Matched specific or [CSM] Matched default

in build output (use inspect_build with consoleTail=true to find these).

• If an import section error occurs, check that the specific block has ALL needed

imports for that version, not just the changed ones.

• When unsure about new API shape, use the searching_dependency_sources skill to search

the Kotlin compiler jar for the symbol name.