Java to Kotlin Migration
The target is equivalent capability and behavior, not similar-looking code. A compiling Kotlin project is only an intermediate state.
Non-negotiable completion contract
- Every in-scope Java production class, interface, enum, record, annotation, nested type, constructor, method, field-backed contract, and externally visible behavior is recorded.
- Every record is
IMPLEMENTED, ADAPTED with evidence, or explicitly out of scope with approved rationale. No silent omission, stub, unfinished marker, or placeholder counts.
- Java semantics for values, errors, ordering, state, concurrency, serialization, reflection metadata, resources, and side effects are preserved unless an intentional, documented change is approved.
- Kotlin-native design may replace Java mechanics, but it must not reduce capability.
- Completion is not declared until
kotlin-java-migration-testing passes the full source-suite and differential gates.
Required workflow
1. Freeze scope and baselines
Record source/target commits, Java/JDK/Gradle/Kotlin versions, modules, generated sources, supported platforms, feature flags, external services, and exclusions. Capture the Java build and test baseline before implementation.
2. Build the source ledger
Use package/class discovery plus parser or compiler metadata. Track at least:
java_key | kind | target_path | target_symbol | status | evidence | notes
Method overloads require full signatures. Nested types and default/interface methods are separate rows. Reconcile the ledger in CI so new Java objects cannot appear unnoticed.
3. Map architecture and semantics
- Maven/Gradle modules become coherent Gradle Kotlin modules, not arbitrary file buckets.
CompletableFuture/Reactor map to suspend/Flow only after cancellation, ordering, backpressure, scheduler, and error semantics are specified.- Jackson, reflection, annotations, service loading, proxies, synchronization, thread locals, and checked exceptions need explicit target designs.
- Preserve Java-call-site ABI where compatibility is required; otherwise document the Kotlin-first API and adapter boundary.
- Keep one Kotlin source file per primary migrated Java object when traceability benefits, but allow idiomatic Kotlin organization when the ledger remains exact.
Read Kotlin migration adapter before choosing framework mappings.
4. Implement in vertical slices
For each slice: migrate contracts, production behavior, source tests, copied assets, differential cases, and Kotlin-specific tests together. Do not finish all production code before beginning parity testing.
5. Preserve documentation
Translate semantic Javadoc, parameter/return/error contracts, thread-safety notes, lifecycle rules, and compatibility constraints into KDoc. Avoid comments that merely restate syntax.
6. Run gates
./gradlew --no-daemon compileKotlin compileTestKotlin
./gradlew --no-daemon test
./gradlew --no-daemon check
Then run the dedicated <project>-test module and complete Java/Kotlin differential suite defined by kotlin-java-migration-testing.
Status reporting
Report separate denominators for production objects, members, source test methods/cases, assets, differential cases, and Kotlin-only obligations. Never collapse these into one percentage, and never use coverage as the migration-completion percentage.
1---2name: kotlin-java-migration3description: Migrate Java systems to Kotlin without semantic simplification by inventorying every production object and member, preserving public behavior and compatibility, mapping Java frameworks deliberately, implementing Kotlin-native code, and maintaining a machine-checkable migration ledger. Use for Java-to-Kotlin ports, rewrites, compatibility layers, or migration-completeness work; pair with kotlin-java-migration-testing for proof.4license: Apache-2.05---67# Java to Kotlin Migration89The target is equivalent capability and behavior, not similar-looking code. A compiling Kotlin project is only an intermediate state.1011## Non-negotiable completion contract1213- Every in-scope Java production class, interface, enum, record, annotation, nested type, constructor, method, field-backed contract, and externally visible behavior is recorded.14- Every record is `IMPLEMENTED`, `ADAPTED` with evidence, or explicitly out of scope with approved rationale. No silent omission, stub, unfinished marker, or placeholder counts.15- Java semantics for values, errors, ordering, state, concurrency, serialization, reflection metadata, resources, and side effects are preserved unless an intentional, documented change is approved.16- Kotlin-native design may replace Java mechanics, but it must not reduce capability.17- Completion is not declared until `kotlin-java-migration-testing` passes the full source-suite and differential gates.1819## Required workflow2021### 1. Freeze scope and baselines2223Record source/target commits, Java/JDK/Gradle/Kotlin versions, modules, generated sources, supported platforms, feature flags, external services, and exclusions. Capture the Java build and test baseline before implementation.2425### 2. Build the source ledger2627Use package/class discovery plus parser or compiler metadata. Track at least:2829```text30java_key | kind | target_path | target_symbol | status | evidence | notes31```3233Method overloads require full signatures. Nested types and default/interface methods are separate rows. Reconcile the ledger in CI so new Java objects cannot appear unnoticed.3435### 3. Map architecture and semantics3637- Maven/Gradle modules become coherent Gradle Kotlin modules, not arbitrary file buckets.38- `CompletableFuture`/Reactor map to suspend/Flow only after cancellation, ordering, backpressure, scheduler, and error semantics are specified.39- Jackson, reflection, annotations, service loading, proxies, synchronization, thread locals, and checked exceptions need explicit target designs.40- Preserve Java-call-site ABI where compatibility is required; otherwise document the Kotlin-first API and adapter boundary.41- Keep one Kotlin source file per primary migrated Java object when traceability benefits, but allow idiomatic Kotlin organization when the ledger remains exact.4243Read [Kotlin migration adapter](references/kotlin-migration-adapter.md) before choosing framework mappings.4445### 4. Implement in vertical slices4647For each slice: migrate contracts, production behavior, source tests, copied assets, differential cases, and Kotlin-specific tests together. Do not finish all production code before beginning parity testing.4849### 5. Preserve documentation5051Translate semantic Javadoc, parameter/return/error contracts, thread-safety notes, lifecycle rules, and compatibility constraints into KDoc. Avoid comments that merely restate syntax.5253### 6. Run gates5455```bash56./gradlew --no-daemon compileKotlin compileTestKotlin57./gradlew --no-daemon test58./gradlew --no-daemon check59```6061Then run the dedicated `<project>-test` module and complete Java/Kotlin differential suite defined by `kotlin-java-migration-testing`.6263## Status reporting6465Report separate denominators for production objects, members, source test methods/cases, assets, differential cases, and Kotlin-only obligations. Never collapse these into one percentage, and never use coverage as the migration-completion percentage.
full-stack-skills