android-sdd 1.0.0

package/skills/Build System/Build Variant/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: build-variant
+description: >
+  Android build types and product flavors for managing multiple build variants.
+  Load this skill when configuring debug/release builds, multiple environments
+  (dev/staging/prod), or feature-based flavors.
+---
+
+# Build Variant
+
+## Overview
+Build variants are the combination of build types and product flavors. Build types define how the app is built (debug vs release), product flavors define what is built (dev vs prod, free vs paid). Every combination produces a distinct variant — e.g., `devDebug`, `prodRelease`.
+
+---
+
+## Core Principles
+
+- **Build types** = how to build (debug, release, staging)
+- **Product flavors** = what to build (dev, prod, free, paid)
+- Use **BuildConfig fields** for environment-specific values — not hardcoded strings
+- Each variant can have its own `google-services.json` and resources
+- Minimize the number of variants — complexity grows exponentially
+
+---
+
+## Build Types
+
+```kotlin
+android {
+    buildTypes {
+
+        debug {
+            isDebuggable = true
+            isMinifyEnabled = false
+            applicationIdSuffix = ".debug"
+            versionNameSuffix = "-debug"
+            buildConfigField("String", "API_URL", "\"https://dev.api.example.com/\"")
+            buildConfigField("Boolean", "ENABLE_LOGGING", "true")
+        }
+
+        release {
+            isDebuggable = false
+            isMinifyEnabled = true
+            isShrinkResources = true
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro"
+            )
+            buildConfigField("String", "API_URL", "\"https://api.example.com/\"")
+            buildConfigField("Boolean", "ENABLE_LOGGING", "false")
+            signingConfig = signingConfigs.getByName("release")
+        }
+
+        // ✅ Custom build type — staging
+        create("staging") {
+            initWith(getByName("release"))  // inherit from release
+            isDebuggable = true
+            applicationIdSuffix = ".staging"
+            versionNameSuffix = "-staging"
+            buildConfigField("String", "API_URL", "\"https://staging.api.example.com/\"")
+            buildConfigField("Boolean", "ENABLE_LOGGING", "true")
+            matchingFallbacks += listOf("release")  // fallback for dependencies
+        }
+    }
+}
+```
+
+---
+
+## Product Flavors
+
+```kotlin
+android {
+    flavorDimensions += listOf("environment", "tier")
+
+    productFlavors {
+
+        // Environment dimension
+        create("dev") {
+            dimension = "environment"
+            applicationIdSuffix = ".dev"
+            versionNameSuffix = "-dev"
+            buildConfigField("String", "ENVIRONMENT", "\"dev\"")
+        }
+
+        create("prod") {
+            dimension = "environment"
+            buildConfigField("String", "ENVIRONMENT", "\"prod\"")
+        }
+
+        // Tier dimension
+        create("free") {
+            dimension = "tier"
+            buildConfigField("Boolean", "IS_PREMIUM", "false")
+        }
+
+        create("premium") {
+            dimension = "tier"
+            buildConfigField("Boolean", "IS_PREMIUM", "true")
+        }
+    }
+}
+
+// Resulting variants:
+// devFreeDebug, devFreeRelease
+// devPremiumDebug, devPremiumRelease
+// prodFreeDebug, prodFreeRelease
+// prodPremiumDebug, prodPremiumRelease
+```
+
+---
+
+## Flavor-Specific Source Sets
+
+```
+app/src/
+├── main/                  ← shared for all variants
+├── debug/                 ← debug build type only
+│   └── google-services.json
+├── release/               ← release build type only
+│   └── google-services.json
+├── dev/                   ← dev flavor only
+│   ├── java/
+│   │   └── com/example/app/
+│   │       └── DevTools.kt
+│   └── res/
+│       └── values/
+│           └── strings.xml   ← override app_name for dev
+├── prod/                  ← prod flavor only
+│   └── res/
+│       └── values/
+│           └── strings.xml
+└── devDebug/              ← specific variant only
+    └── java/
+```
+
+---
+
+## Variant-Specific Dependencies
+
+```kotlin
+dependencies {
+    // ✅ Debug-only dependencies
+    debugImplementation(libs.leakcanary)
+    debugImplementation(libs.compose.ui.tooling)
+
+    // ✅ Flavor-specific
+    "devImplementation"(libs.debug.drawer)
+
+    // ✅ Test
+    testImplementation(libs.junit)
+    androidTestImplementation(libs.espresso.core)
+
+    // ✅ Staging matches release dependencies
+    // (handled by matchingFallbacks)
+}
+```
+
+---
+
+## BuildConfig Usage
+
+```kotlin
+// ✅ Access in code
+class ApiConfig {
+    val baseUrl: String = BuildConfig.API_URL
+    val isLoggingEnabled: Boolean = BuildConfig.ENABLE_LOGGING
+    val environment: String = BuildConfig.ENVIRONMENT
+    val isPremium: Boolean = BuildConfig.IS_PREMIUM
+}
+
+// ✅ Conditional behavior
+if (BuildConfig.DEBUG) {
+    Timber.plant(Timber.DebugTree())
+}
+
+if (BuildConfig.ENABLE_LOGGING) {
+    OkHttpClient.Builder().addInterceptor(HttpLoggingInterceptor())
+}
+```
+
+---
+
+## Variant Filtering
+
+```kotlin
+// ✅ Exclude unused variants to speed up build
+android {
+    variantFilter {
+        // Ignore staging + free combination — doesn't make sense
+        if (flavors.any { it.name == "free" } && buildType.name == "staging") {
+            ignore = true
+        }
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Hardcoding API URLs — use `buildConfigField` per build type/flavor
+- Too many dimensions — variants multiply, CI time explodes
+- Not using `matchingFallbacks` for custom build types — dependency resolution fails
+- Different logic in code for dev/prod via `if (BuildConfig.FLAVOR == "dev")` — use polymorphism or source sets
+- Committing production `google-services.json` to version control unprotected
+
+---
+
+## Related Skills
+- `gradle` — build system fundamentals
+- `version-catalog` — dependency management per variant
+- `convention-plugin` — shared build type configuration
+- `build-flavor-strategy` — deciding on flavor structure
+- `ci-cd` — building specific variants in CI

package/skills/Build System/Convention Plugin/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: convention-plugin
+description: >
+  Gradle convention plugins for sharing build logic across modules.
+  Load this skill when creating reusable build configuration,
+  eliminating duplication across module build files, or setting up
+  a build-logic module.
+---
+
+# Convention Plugin
+
+## Overview
+Convention plugins are Gradle plugins written in `build-logic/` that encapsulate shared build configuration. Instead of duplicating Android, Kotlin, and Hilt setup in every module's `build.gradle.kts`, each module applies a single convention plugin that contains all the shared logic.
+
+---
+
+## Core Principles
+
+- Convention plugins live in `build-logic/` — a separate included build
+- Each plugin covers **one concern** — Android app, Android library, Compose, Hilt, etc.
+- Modules apply **multiple small plugins** rather than one large plugin
+- Convention plugins use the **Version Catalog** for all dependency/version references
+- Changes to a convention plugin propagate to **all modules** that apply it
+
+---
+
+## Project Structure
+
+```
+build-logic/
+├── settings.gradle.kts
+└── convention/
+    ├── build.gradle.kts
+    └── src/main/kotlin/
+        ├── AndroidApplicationConventionPlugin.kt
+        ├── AndroidLibraryConventionPlugin.kt
+        ├── AndroidComposeConventionPlugin.kt
+        ├── AndroidHiltConventionPlugin.kt
+        ├── AndroidRoomConventionPlugin.kt
+        └── KotlinSerializationConventionPlugin.kt
+```
+
+---
+
+## build-logic Setup
+
+```kotlin
+// build-logic/settings.gradle.kts
+dependencyResolutionManagement {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    versionCatalogs {
+        create("libs") {
+            from(files("../gradle/libs.versions.toml"))
+        }
+    }
+}
+rootProject.name = "build-logic"
+include(":convention")
+```
+
+```kotlin
+// build-logic/convention/build.gradle.kts
+plugins {
+    `kotlin-dsl`
+}
+
+dependencies {
+    compileOnly(libs.android.gradlePlugin)
+    compileOnly(libs.kotlin.gradlePlugin)
+    compileOnly(libs.ksp.gradlePlugin)
+}
+```
+
+```toml
+# Add to libs.versions.toml for use in build-logic
+[libraries]
+android-gradlePlugin = { module = "com.android.tools.build:gradle", version.ref = "agp" }
+kotlin-gradlePlugin  = { module = "org.jetbrains.kotlin:kotlin-gradle-plugin", version.ref = "kotlin" }
+ksp-gradlePlugin     = { module = "com.google.devtools.ksp:com.google.devtools.ksp.gradle.plugin", version.ref = "ksp" }
+```
+
+---
+
+## Android Application Plugin
+
+```kotlin
+// AndroidApplicationConventionPlugin.kt
+class AndroidApplicationConventionPlugin : Plugin<Project> {
+    override fun apply(target: Project) {
+        with(target) {
+            with(pluginManager) {
+                apply("com.android.application")
+                apply("org.jetbrains.kotlin.android")
+            }
+
+            extensions.configure<ApplicationExtension> {
+                compileSdk = libs.findVersion("android-compileSdk").get().toString().toInt()
+
+                defaultConfig {
+                    minSdk = libs.findVersion("android-minSdk").get().toString().toInt()
+                    targetSdk = libs.findVersion("android-targetSdk").get().toString().toInt()
+                    testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+                }
+
+                compileOptions {
+                    sourceCompatibility = JavaVersion.VERSION_17
+                    targetCompatibility = JavaVersion.VERSION_17
+                }
+
+                kotlinOptions { jvmTarget = "17" }
+            }
+        }
+    }
+}
+
+private val Project.libs
+    get(): VersionCatalog = extensions.getByType<VersionCatalogsExtension>().named("libs")
+```
+
+---
+
+## Android Library Plugin
+
+```kotlin
+// AndroidLibraryConventionPlugin.kt
+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 = libs.findVersion("android-compileSdk").get().toString().toInt()
+
+                defaultConfig {
+                    minSdk = libs.findVersion("android-minSdk").get().toString().toInt()
+                    testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+                    consumerProguardFiles("consumer-rules.pro")
+                }
+
+                compileOptions {
+                    sourceCompatibility = JavaVersion.VERSION_17
+                    targetCompatibility = JavaVersion.VERSION_17
+                }
+
+                kotlinOptions { jvmTarget = "17" }
+            }
+        }
+    }
+}
+```
+
+---
+
+## Compose Plugin
+
+```kotlin
+// AndroidComposeConventionPlugin.kt
+class AndroidComposeConventionPlugin : Plugin<Project> {
+    override fun apply(target: Project) {
+        with(target) {
+            pluginManager.apply("org.jetbrains.kotlin.plugin.compose")
+
+            val extension = extensions.findByType<CommonExtension<*, *, *, *, *, *>>()
+                ?: error("Android plugin must be applied first")
+
+            extension.apply {
+                buildFeatures { compose = true }
+            }
+
+            dependencies {
+                val bom = libs.findLibrary("compose-bom").get()
+                add("implementation", platform(bom))
+                add("implementation", libs.findLibrary("compose-ui").get())
+                add("implementation", libs.findLibrary("compose-material3").get())
+                add("implementation", libs.findLibrary("compose-ui-tooling-preview").get())
+                add("debugImplementation", libs.findLibrary("compose-ui-tooling").get())
+            }
+        }
+    }
+}
+```
+
+---
+
+## Hilt Plugin
+
+```kotlin
+// AndroidHiltConventionPlugin.kt
+class AndroidHiltConventionPlugin : Plugin<Project> {
+    override fun apply(target: Project) {
+        with(target) {
+            with(pluginManager) {
+                apply("com.google.dagger.hilt.android")
+                apply("com.google.devtools.ksp")
+            }
+
+            dependencies {
+                add("implementation", libs.findLibrary("hilt-android").get())
+                add("ksp", libs.findLibrary("hilt-compiler").get())
+            }
+        }
+    }
+}
+```
+
+---
+
+## Registering Plugins
+
+```kotlin
+// build-logic/convention/build.gradle.kts
+gradlePlugin {
+    plugins {
+        register("androidApplication") {
+            id = "myapp.android.application"
+            implementationClass = "AndroidApplicationConventionPlugin"
+        }
+        register("androidLibrary") {
+            id = "myapp.android.library"
+            implementationClass = "AndroidLibraryConventionPlugin"
+        }
+        register("androidCompose") {
+            id = "myapp.android.compose"
+            implementationClass = "AndroidComposeConventionPlugin"
+        }
+        register("androidHilt") {
+            id = "myapp.android.hilt"
+            implementationClass = "AndroidHiltConventionPlugin"
+        }
+    }
+}
+```
+
+---
+
+## Usage in Modules
+
+```kotlin
+// app/build.gradle.kts
+plugins {
+    id("myapp.android.application")
+    id("myapp.android.compose")
+    id("myapp.android.hilt")
+}
+
+android {
+    namespace = "com.example.app"
+    defaultConfig { applicationId = "com.example.app" }
+}
+
+dependencies {
+    implementation(projects.feature.home)
+    implementation(projects.core.network)
+}
+
+// feature/home/build.gradle.kts
+plugins {
+    id("myapp.android.library")
+    id("myapp.android.compose")
+    id("myapp.android.hilt")
+}
+
+android { namespace = "com.example.feature.home" }
+```
+
+---
+
+## Anti-Patterns
+
+- One giant convention plugin for everything — hard to apply selectively
+- Duplicating Android config across module build files — defeats the purpose
+- Not using Version Catalog inside convention plugins — version drift
+- Business logic in convention plugins — they configure, not implement
+- Not including `build-logic` in `settings.gradle.kts` — plugins not found
+
+---
+
+## Related Skills
+- `gradle` — Gradle fundamentals
+- `version-catalog` — used inside convention plugins
+- `build-variant` — build type config in convention plugins
+- `modularization` — convention plugins enable consistent multi-module setup