@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/shared/external/gradle-kotlin-dsl/SKILL.md

@@ -0,0 +1,552 @@
+---
+name: gradle-kotlin-dsl
+description: "Configure Android builds with Gradle Kotlin DSL, version catalogs (libs.versions.toml), convention plugins (build-logic module), common configurations for android library/compose/testing, build variants, flavors, signing configs, R8/ProGuard rules, and build performance optimization including configuration cache and parallel execution. Use when setting up Gradle builds, adding dependencies, creating convention plugins, or optimizing build times."
+---
+
+# Gradle Kotlin DSL
+
+Modern Gradle build configuration for Android projects using Kotlin DSL,
+version catalogs, and convention plugins. Targets AGP 8.x+ and Gradle 8.x+.
+
+## Contents
+
+- [Version Catalog](#version-catalog)
+- [Convention Plugins](#convention-plugins)
+- [App Module Configuration](#app-module-configuration)
+- [Library Module Configuration](#library-module-configuration)
+- [Compose Configuration](#compose-configuration)
+- [Build Variants and Flavors](#build-variants-and-flavors)
+- [Signing Config](#signing-config)
+- [R8 and ProGuard](#r8-and-proguard)
+- [Build Performance](#build-performance)
+- [Do's and Don'ts](#dos-and-donts)
+- [Troubleshooting](#troubleshooting)
+- [Review Checklist](#review-checklist)
+
+## Version Catalog
+
+Define all versions, libraries, and plugins in `gradle/libs.versions.toml`:
+
+```toml
+[versions]
+agp = "8.7.3"
+kotlin = "2.1.0"
+ksp = "2.1.0-1.0.29"
+compose-bom = "2024.12.01"
+hilt = "2.53.1"
+room = "2.6.1"
+retrofit = "2.11.0"
+okhttp = "4.12.0"
+coroutines = "1.9.0"
+lifecycle = "2.8.7"
+navigation = "2.8.5"
+serialization = "1.7.3"
+coil = "2.7.0"
+turbine = "1.2.0"
+roborazzi = "1.32.2"
+
+[libraries]
+# Compose
+compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "compose-bom" }
+compose-ui = { group = "androidx.compose.ui", name = "ui" }
+compose-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling" }
+compose-ui-tooling-preview = { group = "androidx.compose.ui", name = "ui-tooling-preview" }
+compose-material3 = { group = "androidx.compose.material3", name = "material3" }
+compose-runtime = { group = "androidx.compose.runtime", name = "runtime" }
+
+# Lifecycle
+lifecycle-runtime-compose = { group = "androidx.lifecycle", name = "lifecycle-runtime-compose", version.ref = "lifecycle" }
+lifecycle-viewmodel-compose = { group = "androidx.lifecycle", name = "lifecycle-viewmodel-compose", version.ref = "lifecycle" }
+
+# Navigation
+navigation-compose = { group = "androidx.navigation", name = "navigation-compose", version.ref = "navigation" }
+
+# Hilt
+hilt-android = { group = "com.google.dagger", name = "hilt-android", version.ref = "hilt" }
+hilt-compiler = { group = "com.google.dagger", name = "hilt-android-compiler", version.ref = "hilt" }
+hilt-navigation-compose = { group = "androidx.hilt", name = "hilt-navigation-compose", version = "1.2.0" }
+
+# Room
+room-runtime = { group = "androidx.room", name = "room-runtime", version.ref = "room" }
+room-ktx = { group = "androidx.room", name = "room-ktx", version.ref = "room" }
+room-compiler = { group = "androidx.room", name = "room-compiler", version.ref = "room" }
+room-testing = { group = "androidx.room", name = "room-testing", version.ref = "room" }
+
+# Network
+retrofit = { group = "com.squareup.retrofit2", name = "retrofit", version.ref = "retrofit" }
+okhttp = { group = "com.squareup.okhttp3", name = "okhttp", version.ref = "okhttp" }
+okhttp-logging = { group = "com.squareup.okhttp3", name = "logging-interceptor", version.ref = "okhttp" }
+serialization-json = { group = "org.jetbrains.kotlinx", name = "kotlinx-serialization-json", version.ref = "serialization" }
+retrofit-serialization = { group = "com.squareup.retrofit2", name = "converter-kotlinx-serialization", version = "2.11.0" }
+
+# Coroutines
+coroutines-core = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-core", version.ref = "coroutines" }
+coroutines-android = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-android", version.ref = "coroutines" }
+coroutines-test = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-test", version.ref = "coroutines" }
+
+# Image loading
+coil-compose = { group = "io.coil-kt", name = "coil-compose", version.ref = "coil" }
+
+# Testing
+junit = { group = "junit", name = "junit", version = "4.13.2" }
+turbine = { group = "app.cash.turbine", name = "turbine", version.ref = "turbine" }
+truth = { group = "com.google.truth", name = "truth", version = "1.4.4" }
+compose-ui-test = { group = "androidx.compose.ui", name = "ui-test-junit4" }
+compose-ui-test-manifest = { group = "androidx.compose.ui", name = "ui-test-manifest" }
+roborazzi = { group = "io.github.takahirom.roborazzi", name = "roborazzi", version.ref = "roborazzi" }
+roborazzi-compose = { group = "io.github.takahirom.roborazzi", name = "roborazzi-compose", version.ref = "roborazzi" }
+
+[bundles]
+compose = ["compose-ui", "compose-ui-tooling-preview", "compose-material3", "compose-runtime"]
+compose-debug = ["compose-ui-tooling", "compose-ui-test-manifest"]
+lifecycle = ["lifecycle-runtime-compose", "lifecycle-viewmodel-compose"]
+room = ["room-runtime", "room-ktx"]
+network = ["retrofit", "okhttp", "okhttp-logging", "serialization-json", "retrofit-serialization"]
+
+[plugins]
+android-application = { id = "com.android.application", version.ref = "agp" }
+android-library = { id = "com.android.library", version.ref = "agp" }
+kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
+kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
+compose-compiler = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
+ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
+hilt = { id = "com.google.dagger.hilt.android", version.ref = "hilt" }
+room = { id = "androidx.room", version.ref = "room" }
+```
+
+## Convention Plugins
+
+Create a `build-logic` module to share common configurations:
+
+### settings.gradle.kts (root)
+
+```kotlin
+pluginManagement {
+    includeBuild("build-logic")
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+```
+
+### build-logic/settings.gradle.kts
+
+```kotlin
+dependencyResolutionManagement {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    versionCatalogs {
+        create("libs") {
+            from(files("../gradle/libs.versions.toml"))
+        }
+    }
+}
+
+include(":convention")
+```
+
+### build-logic/convention/build.gradle.kts
+
+```kotlin
+plugins {
+    `kotlin-dsl`
+}
+
+dependencies {
+    compileOnly(libs.android.gradlePlugin)
+    compileOnly(libs.kotlin.gradlePlugin)
+    compileOnly(libs.compose.gradlePlugin)
+}
+```
+
+### Android Library Convention Plugin
+
+```kotlin
+// build-logic/convention/src/main/kotlin/AndroidLibraryConventionPlugin.kt
+import com.android.build.gradle.LibraryExtension
+import org.gradle.api.Plugin
+import org.gradle.api.Project
+import org.gradle.kotlin.dsl.configure
+
+class AndroidLibraryConventionPlugin : Plugin<Project> {
+    override fun apply(target: Project) {
+        with(target) {
+            with(pluginManager) {
+                apply("com.android.library")
+                apply("org.jetbrains.kotlin.android")
+            }
+
+            extensions.configure<LibraryExtension> {
+                compileSdk = 35
+                defaultConfig {
+                    minSdk = 26
+                    testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+                }
+                compileOptions {
+                    sourceCompatibility = JavaVersion.VERSION_17
+                    targetCompatibility = JavaVersion.VERSION_17
+                }
+            }
+        }
+    }
+}
+```
+
+### Register in build-logic/convention/build.gradle.kts
+
+```kotlin
+gradlePlugin {
+    plugins {
+        register("androidLibrary") {
+            id = "app.android.library"
+            implementationClass = "AndroidLibraryConventionPlugin"
+        }
+        register("androidCompose") {
+            id = "app.android.compose"
+            implementationClass = "AndroidComposeConventionPlugin"
+        }
+        register("androidHilt") {
+            id = "app.android.hilt"
+            implementationClass = "AndroidHiltConventionPlugin"
+        }
+    }
+}
+```
+
+### Usage in Feature Module
+
+```kotlin
+// feature/home/build.gradle.kts
+plugins {
+    id("app.android.library")
+    id("app.android.compose")
+    id("app.android.hilt")
+}
+
+dependencies {
+    implementation(project(":core:model"))
+    implementation(project(":core:data"))
+    implementation(project(":core:ui"))
+}
+```
+
+## App Module Configuration
+
+```kotlin
+// app/build.gradle.kts
+plugins {
+    alias(libs.plugins.android.application)
+    alias(libs.plugins.kotlin.android)
+    alias(libs.plugins.compose.compiler)
+    alias(libs.plugins.hilt)
+    alias(libs.plugins.ksp)
+}
+
+android {
+    namespace = "com.example.app"
+    compileSdk = 35
+
+    defaultConfig {
+        applicationId = "com.example.app"
+        minSdk = 26
+        targetSdk = 35
+        versionCode = 1
+        versionName = "1.0.0"
+        testInstrumentationRunner = "com.example.app.HiltTestRunner"
+    }
+
+    buildTypes {
+        release {
+            isMinifyEnabled = true
+            isShrinkResources = true
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro",
+            )
+        }
+        debug {
+            isMinifyEnabled = false
+            applicationIdSuffix = ".debug"
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = "17"
+    }
+}
+
+dependencies {
+    implementation(platform(libs.compose.bom))
+    implementation(libs.bundles.compose)
+    implementation(libs.bundles.lifecycle)
+    implementation(libs.navigation.compose)
+    implementation(libs.hilt.android)
+    ksp(libs.hilt.compiler)
+    implementation(libs.hilt.navigation.compose)
+
+    debugImplementation(libs.bundles.compose.debug)
+
+    testImplementation(libs.junit)
+    testImplementation(libs.truth)
+    testImplementation(libs.coroutines.test)
+    testImplementation(libs.turbine)
+
+    androidTestImplementation(platform(libs.compose.bom))
+    androidTestImplementation(libs.compose.ui.test)
+}
+```
+
+## Library Module Configuration
+
+```kotlin
+// core/data/build.gradle.kts
+plugins {
+    alias(libs.plugins.android.library)
+    alias(libs.plugins.kotlin.android)
+    alias(libs.plugins.hilt)
+    alias(libs.plugins.ksp)
+}
+
+android {
+    namespace = "com.example.core.data"
+    compileSdk = 35
+
+    defaultConfig {
+        minSdk = 26
+    }
+}
+
+dependencies {
+    implementation(project(":core:model"))
+    implementation(project(":core:network"))
+    implementation(project(":core:database"))
+    implementation(libs.hilt.android)
+    ksp(libs.hilt.compiler)
+    implementation(libs.coroutines.core)
+
+    testImplementation(libs.junit)
+    testImplementation(libs.truth)
+    testImplementation(libs.coroutines.test)
+}
+```
+
+## Compose Configuration
+
+```kotlin
+// Convention plugin or inline
+android {
+    buildFeatures {
+        compose = true
+    }
+}
+
+// With Kotlin 2.0+, use the Compose Compiler plugin:
+plugins {
+    alias(libs.plugins.compose.compiler)
+}
+
+// Optional: Compose compiler metrics for performance debugging
+// In gradle.properties or via command line:
+// composeCompiler.reportsDestination=build/compose-reports
+// composeCompiler.metricsDestination=build/compose-metrics
+```
+
+## Build Variants and Flavors
+
+```kotlin
+android {
+    buildTypes {
+        release {
+            isMinifyEnabled = true
+            isShrinkResources = true
+            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
+        }
+        debug {
+            isMinifyEnabled = false
+            applicationIdSuffix = ".debug"
+            isDebuggable = true
+        }
+        create("staging") {
+            initWith(getByName("release"))
+            applicationIdSuffix = ".staging"
+            isMinifyEnabled = true
+            matchingFallbacks += "release"
+        }
+    }
+
+    flavorDimensions += "environment"
+    productFlavors {
+        create("dev") {
+            dimension = "environment"
+            applicationIdSuffix = ".dev"
+            buildConfigField("String", "BASE_URL", "\"https://dev-api.example.com/\"")
+        }
+        create("prod") {
+            dimension = "environment"
+            buildConfigField("String", "BASE_URL", "\"https://api.example.com/\"")
+        }
+    }
+}
+```
+
+## Signing Config
+
+```kotlin
+android {
+    signingConfigs {
+        create("release") {
+            storeFile = file(System.getenv("KEYSTORE_PATH") ?: "release.keystore")
+            storePassword = System.getenv("KEYSTORE_PASSWORD") ?: ""
+            keyAlias = System.getenv("KEY_ALIAS") ?: ""
+            keyPassword = System.getenv("KEY_PASSWORD") ?: ""
+        }
+    }
+
+    buildTypes {
+        release {
+            signingConfig = signingConfigs.getByName("release")
+        }
+    }
+}
+```
+
+Never commit keystore passwords. Use environment variables or `local.properties` (gitignored).
+
+## R8 and ProGuard
+
+### proguard-rules.pro
+
+```proguard
+# Kotlin serialization
+-keepattributes *Annotation*, InnerClasses
+-dontnote kotlinx.serialization.AnnotationsKt
+
+-keepclassmembers class kotlinx.serialization.json.** {
+    *** Companion;
+}
+-keepclasseswithmembers class kotlinx.serialization.json.** {
+    kotlinx.serialization.KSerializer serializer(...);
+}
+-keep,includedescriptorclasses class com.example.app.data.dto.**$$serializer { *; }
+-keepclassmembers class com.example.app.data.dto.** {
+    *** Companion;
+}
+-keepclasseswithmembers class com.example.app.data.dto.** {
+    kotlinx.serialization.KSerializer serializer(...);
+}
+
+# Retrofit
+-keepattributes Signature
+-keepattributes Exceptions
+-keepclassmembers,allowshrinking,allowobfuscation interface * {
+    @retrofit2.http.* <methods>;
+}
+-dontwarn javax.annotation.**
+-dontwarn kotlin.Unit
+-dontwarn retrofit2.KotlinExtensions
+-dontwarn retrofit2.KotlinExtensions$*
+
+# OkHttp
+-dontwarn okhttp3.internal.platform.**
+-dontwarn org.conscrypt.**
+-dontwarn org.bouncycastle.**
+-dontwarn org.openjsse.**
+
+# Hilt
+-keep class dagger.hilt.** { *; }
+```
+
+## Build Performance
+
+### gradle.properties
+
+```properties
+# Parallel execution
+org.gradle.parallel=true
+
+# Configuration cache
+org.gradle.configuration-cache=true
+
+# Build cache
+org.gradle.caching=true
+
+# JVM memory
+org.gradle.jvmargs=-Xmx4g -XX:+UseG1GC -XX:MaxMetaspaceSize=1g
+
+# Kotlin daemon
+kotlin.daemon.jvmargs=-Xmx2g
+
+# Non-transitive R classes (reduces rebuild scope)
+android.nonTransitiveRClass=true
+
+# Disable unused features
+android.defaults.buildfeatures.buildconfig=false
+android.defaults.buildfeatures.aidl=false
+android.defaults.buildfeatures.renderscript=false
+```
+
+### Dependency Locking
+
+```kotlin
+dependencyLocking {
+    lockAllConfigurations()
+}
+
+// Generate lock files: ./gradlew dependencies --write-locks
+```
+
+## Do's and Don'ts
+
+### Do's
+- Use version catalogs (`libs.versions.toml`) for all dependencies
+- Use convention plugins for shared configuration
+- Use `alias(libs.plugins.xxx)` for plugin application
+- Set `isMinifyEnabled = true` and `isShrinkResources = true` for release builds
+- Keep signing credentials in environment variables or CI secrets
+- Use bundles for related dependencies
+- Enable configuration cache and parallel execution
+- Use `ksp` instead of `kapt` for annotation processing
+
+### Don'ts
+- Do not hardcode versions in `build.gradle.kts` -- use version catalog
+- Do not use `kapt` for new projects -- KSP is faster
+- Do not commit keystore passwords or `local.properties`
+- Do not disable R8 in release builds without strong justification
+- Do not use `implementation` for dependencies that consumers need -- use `api`
+- Do not add `-dontwarn *` globally in ProGuard rules
+- Do not skip `isShrinkResources` when `isMinifyEnabled` is true
+
+## Troubleshooting
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| `Unresolved reference` in version catalog | Typo or wrong bundle/library name | Check `libs.versions.toml` entries match exactly |
+| KSP not generating code | Missing `ksp` plugin or wrong dependency | Use `ksp(libs.xxx)` not `annotationProcessor` |
+| Configuration cache failure | Unsupported plugin or task | Check plugin compatibility; report to plugin author |
+| `Duplicate class` error | Dependency conflict | Use `./gradlew dependencies` to find conflicts; exclude transitive |
+| R8 strips too much code | Missing keep rules | Add ProGuard rules for reflection-used classes (serialization, Retrofit) |
+| Slow builds | No parallel, no cache, low memory | Enable settings in `gradle.properties` |
+| `Could not resolve` dependency | Wrong repository or network issue | Check `repositories {}` block in settings.gradle.kts |
+| Version conflict between modules | Different versions in submodules | Use version catalog and convention plugins for consistency |
+
+## Review Checklist
+
+- [ ] All versions in `libs.versions.toml`, none hardcoded in `build.gradle.kts`
+- [ ] Convention plugins for shared Android/Compose/Hilt configuration
+- [ ] KSP used instead of kapt
+- [ ] Release builds have `isMinifyEnabled` and `isShrinkResources` enabled
+- [ ] ProGuard rules cover serialization, Retrofit, and Hilt
+- [ ] No signing credentials in source code
+- [ ] `gradle.properties` has parallel, caching, and memory settings
+- [ ] `android.nonTransitiveRClass=true` enabled
+- [ ] Bundles used for related dependency groups
+- [ ] No `kapt` usage in new modules