@mmerterden/multi-agent-pipeline 20.1.0 → 20.2.1

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

@@ -8,10 +8,19 @@ description: "Configure Android builds with Gradle Kotlin DSL, version catalogs
 Modern Gradle build configuration for Android projects using Kotlin DSL,
 version catalogs, and convention plugins. Targets AGP 8.x+ and Gradle 8.x+.
 
+Full, copy-ready configuration for every section below lives in
+[references/patterns.md](references/patterns.md). Load that file when you need a
+complete example to adapt (catalog, convention plugin, module build file,
+ProGuard rules, or `gradle.properties`). Each heading there mirrors a section
+here.
+
 ## Contents
 
 - [Version Catalog](#version-catalog)
 - [Convention Plugins](#convention-plugins)
+- [Convention Plugin Composition](#convention-plugin-composition)
+- [Typed BuildConfig Injection](#typed-buildconfig-injection)
+- [Typed Module Paths and Flavors](#typed-module-paths-and-flavors)
 - [App Module Configuration](#app-module-configuration)
 - [Library Module Configuration](#library-module-configuration)
 - [Compose Configuration](#compose-configuration)
@@ -19,490 +28,148 @@ version catalogs, and convention plugins. Targets AGP 8.x+ and Gradle 8.x+.
 - [Signing Config](#signing-config)
 - [R8 and ProGuard](#r8-and-proguard)
 - [Build Performance](#build-performance)
+- [Fast-Feedback Tasks](#fast-feedback-tasks)
 - [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" }
-```
+Declare every version, library, and plugin in `gradle/libs.versions.toml` under
+`[versions]`, `[libraries]`, `[bundles]`, and `[plugins]`. Reference them with
+`libs.xxx`, `libs.bundles.xxx`, and `alias(libs.plugins.xxx)`; never hardcode a
+version in a `build.gradle.kts`.
+
+Full catalog (Compose BOM, Hilt, Room, Retrofit, coroutines, testing, bundles,
+plugins): [references/patterns.md#version-catalog](references/patterns.md#version-catalog).
 
 ## 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"))
-}
-```
+Share Android/Compose/Hilt configuration through a `build-logic` included build
+instead of copying blocks between modules. Root `settings.gradle.kts` does
+`includeBuild("build-logic")`; the convention module implements
+`Plugin<Project>` classes and registers them with stable ids
+(`app.android.library`, `app.android.compose`, `app.android.hilt`) that feature
+modules then apply.
+
+Full wiring (settings files, `Plugin<Project>` class, `gradlePlugin` registration,
+feature-module usage):
+[references/patterns.md#convention-plugins](references/patterns.md#convention-plugins).
+
+## Convention Plugin Composition
+
+Compose plugins into a ladder: a higher-level plugin applies the lower ones. A
+single `feature-impl` plugin applies library + hilt + compose + test and wires
+the standard dependency set, so a feature module's `plugins {}` block is one
+line. Put shared toolchain and compiler flags (`jvmTarget`, strict explicit-api,
+`compileSdk`/`minSdk`, Java 17) in one `configureKotlinAndroid()` extension that
+every Android convention plugin calls, so no value is duplicated across plugins.
+
+Alias your own convention plugins in the version catalog
+(`app-android-feature = { id = "app.android.feature", version = "unspecified" }`)
+so modules apply `alias(libs.plugins.app.android.feature)` rather than a raw id
+string.
+
+For build-FAILING quality-gate tasks (module-layer checks, coverage floor,
+Compose stability gate), see the `android-build-quality-gates` skill; those
+tasks are not reproduced here.
+
+Full ladder plugin, `configureKotlinAndroid()`, and catalog aliases:
+[references/patterns.md#convention-plugin-composition](references/patterns.md#convention-plugin-composition).
+
+## Typed BuildConfig Injection
+
+Replace scattered `buildConfigField("String", "KEY", "\"...\"")` strings with a
+typed key `enum` (each key carries its Java type), per-module `contributor`
+objects, and a central `resolver` that filters contributions by module scope and
+de-dupes by key. The convention plugin materializes the resolved entries once per
+flavor, so the type is always right and no module hand-writes a `buildConfigField`.
+
+Full key enum, contributor interface, and resolver:
+[references/patterns.md#typed-buildconfig-injection](references/patterns.md#typed-buildconfig-injection).
+
+## Typed Module Paths and Flavors
+
+Model module paths and flavors as `sealed`/`enum` types so builds reference
+`Module.Core.Domain.toProject()` instead of the stringly-typed
+`project(":core:domain")`, and `Flavor.PROD.baseUrl` instead of a repeated URL
+literal. A typo becomes a compile error, and refactoring a path updates one
+declaration.
+
+Full sealed `Module` hierarchy, `toProject()`, and `Flavor` enum:
+[references/patterns.md#typed-module-paths-and-flavors](references/patterns.md#typed-module-paths-and-flavors).
 
 ## 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)
-}
-```
+Apply plugins via `alias(libs.plugins.xxx)`, set `namespace`/`compileSdk`/
+`defaultConfig`, enable `isMinifyEnabled` + `isShrinkResources` on `release`,
+target Java 17, and pull dependencies from the catalog (`platform(libs.compose.bom)`,
+bundles, `ksp(libs.hilt.compiler)`).
+
+Full `app/build.gradle.kts`:
+[references/patterns.md#app-module-configuration](references/patterns.md#app-module-configuration).
 
 ## 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)
-}
-```
+A library module mirrors the app module but applies `libs.plugins.android.library`,
+declares only its `namespace`/`minSdk`, and depends on sibling `project(...)`
+modules. Full `core/data/build.gradle.kts`:
+[references/patterns.md#library-module-configuration](references/patterns.md#library-module-configuration).
 
 ## 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
-```
+Enable `buildFeatures { compose = true }` and apply the Compose Compiler plugin
+(`alias(libs.plugins.compose.compiler)`) on Kotlin 2.0+. Compiler metrics/reports
+are opt-in via `composeCompiler.*Destination`.
+
+Full snippet: [references/patterns.md#compose-configuration](references/patterns.md#compose-configuration).
 
 ## 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/\"")
-        }
-    }
-}
-```
+Extend `buildTypes` (e.g. a `staging` type via `initWith(getByName("release"))`)
+and declare `productFlavors` under a `flavorDimensions` axis, using
+`buildConfigField` for per-environment values like the base URL.
+
+Full variants + flavors block:
+[references/patterns.md#build-variants-and-flavors](references/patterns.md#build-variants-and-flavors).
 
 ## 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).
+Read keystore path and credentials from environment variables (or gitignored
+`local.properties`), never from committed source, and attach the config to the
+`release` build type. Full `signingConfigs` block:
+[references/patterns.md#signing-config](references/patterns.md#signing-config).
 
 ## 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.** { *; }
-```
+Keep rules are needed for reflection-driven libraries: kotlinx serialization
+(`$$serializer` classes and `Companion`), Retrofit (`@retrofit2.http.*` methods,
+signatures), OkHttp `-dontwarn`s, and Hilt. Never use a global `-dontwarn *`.
 
-## Build Performance
+Full `proguard-rules.pro`:
+[references/patterns.md#r8-and-proguard](references/patterns.md#r8-and-proguard).
 
-### 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
+## Build Performance
 
-# Kotlin daemon
-kotlin.daemon.jvmargs=-Xmx2g
+Enable parallel execution, configuration cache, build cache, sized JVM/daemon
+memory, and `android.nonTransitiveRClass=true` in `gradle.properties`; disable
+unused `buildfeatures`. Optionally lock dependencies with `dependencyLocking`.
 
-# Non-transitive R classes (reduces rebuild scope)
-android.nonTransitiveRClass=true
+Full `gradle.properties` and locking snippet:
+[references/patterns.md#build-performance](references/patterns.md#build-performance).
 
-# Disable unused features
-android.defaults.buildfeatures.buildconfig=false
-android.defaults.buildfeatures.aidl=false
-android.defaults.buildfeatures.renderscript=false
-```
+Keep the build cache (`org.gradle.caching=true`) in this perf-flag set alongside
+parallel execution and the configuration cache.
 
-### Dependency Locking
+## Fast-Feedback Tasks
 
-```kotlin
-dependencyLocking {
-    lockAllConfigurations()
-}
+Install git hooks through a Gradle task wired as a `preBuild` dependency, so a
+fresh clone gets the hooks on its first build with no manual step. Resolve the
+git directory correctly when `.git` is a worktree pointer file (contents
+`gitdir: <path>`) rather than a directory, or the hooks land in the wrong place.
 
-// Generate lock files: ./gradlew dependencies --write-locks
-```
+Full `resolveGitDir` helper, `installGitHooks` task, and `preBuild` wiring:
+[references/patterns.md#fast-feedback-tasks](references/patterns.md#fast-feedback-tasks).
 
 ## Do's and Don'ts
 
@@ -550,3 +217,8 @@ dependencyLocking {
 - [ ] `android.nonTransitiveRClass=true` enabled
 - [ ] Bundles used for related dependency groups
 - [ ] No `kapt` usage in new modules
+- [ ] `BuildConfig` values injected via typed key/contributor/resolver, not scattered `buildConfigField` strings
+- [ ] Module paths and flavors referenced through typed `Module`/`Flavor`, not raw `project(":...")` strings
+- [ ] Convention plugins composed as a ladder with shared config in one `configureKotlinAndroid()` extension
+- [ ] Own convention plugins aliased in the version catalog (`libs.plugins.*`)
+- [ ] Git-hooks install task wired as a `preBuild` dependency, worktree `.git` file handled