android-sdd 1.0.0

package/skills/Build System/Dependency Management/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: dependency-management
+description: >
+  Gradle dependency management — conflict resolution, dependency configurations,
+  transitive dependencies, and keeping dependencies up to date.
+  Load this skill when resolving version conflicts, understanding dependency
+  graphs, or managing third-party library upgrades.
+---
+
+# Dependency Management
+
+## Overview
+Dependency management covers how Gradle resolves, configures, and maintains third-party libraries. Conflicts arise when multiple libraries require different versions of the same transitive dependency. Understanding configurations (`implementation`, `api`, `compileOnly`) and resolution strategies prevents runtime crashes and build issues.
+
+---
+
+## Core Principles
+
+- Use `implementation` by default — expose via `api` only when the type is part of your public API
+- Let Version Catalog be the **single source of truth** for all versions
+- Resolve conflicts **explicitly** — never rely on Gradle's default resolution silently winning
+- Keep dependencies **up to date** — stale deps accumulate security vulnerabilities
+- Audit the **dependency tree** regularly — transitive deps can surprise you
+
+---
+
+## Dependency Configurations
+
+```kotlin
+dependencies {
+    // ✅ implementation — compile + runtime, NOT exposed to consumers
+    implementation(libs.retrofit)
+
+    // ✅ api — compile + runtime, EXPOSED to consumers (module's public API)
+    api(libs.kotlinx.coroutines.core)  // use when consumers need this type
+
+    // ✅ compileOnly — compile time only, not in runtime classpath
+    compileOnly(libs.javax.annotation)
+
+    // ✅ runtimeOnly — runtime only, not available at compile time
+    runtimeOnly(libs.room.runtime)
+
+    // ✅ testImplementation — test compile + runtime only
+    testImplementation(libs.junit)
+
+    // ✅ androidTestImplementation — instrumented test only
+    androidTestImplementation(libs.espresso.core)
+
+    // ✅ debugImplementation — debug build type only
+    debugImplementation(libs.leakcanary)
+
+    // ✅ ksp — annotation processor (KSP)
+    ksp(libs.hilt.compiler)
+}
+```
+
+---
+
+## Viewing the Dependency Tree
+
+```bash
+# ✅ Full dependency tree for a configuration
+./gradlew :app:dependencies --configuration debugRuntimeClasspath
+
+# ✅ Find who brings a specific dependency
+./gradlew :app:dependencyInsight \
+    --configuration debugRuntimeClasspath \
+    --dependency okhttp
+
+# ✅ Per-module dependency tree
+./gradlew :core:network:dependencies
+```
+
+---
+
+## Resolving Version Conflicts
+
+```kotlin
+// ✅ Force a specific version globally
+configurations.all {
+    resolutionStrategy {
+        force("com.squareup.okhttp3:okhttp:4.12.0")
+        force("org.jetbrains.kotlin:kotlin-stdlib:2.0.0")
+    }
+}
+
+// ✅ Prefer highest version (Gradle default — explicit for clarity)
+configurations.all {
+    resolutionStrategy.eachDependency {
+        if (requested.group == "com.squareup.okhttp3") {
+            useVersion("4.12.0")
+            because("Align all OkHttp modules to same version")
+        }
+    }
+}
+
+// ✅ Exclude a transitive dependency
+implementation(libs.some.library) {
+    exclude(group = "com.google.guava", module = "guava")
+}
+
+// ✅ Exclude globally
+configurations.all {
+    exclude(group = "commons-logging", module = "commons-logging")
+}
+```
+
+---
+
+## Platform BOM (Bill of Materials)
+
+```kotlin
+// ✅ BOM aligns all library versions in a group
+dependencies {
+    // Firebase BOM — manages all Firebase SDK versions
+    implementation(platform(libs.firebase.bom))
+    implementation(libs.firebase.analytics)   // no version needed
+    implementation(libs.firebase.crashlytics) // no version needed
+
+    // Compose BOM
+    implementation(platform(libs.compose.bom))
+    implementation(libs.compose.ui)           // no version needed
+    implementation(libs.compose.material3)    // no version needed
+}
+```
+
+---
+
+## Dependency Locking
+
+```kotlin
+// ✅ Lock dependency versions for reproducible builds
+// In settings.gradle.kts or build.gradle.kts
+dependencyLocking {
+    lockAllConfigurations()
+}
+
+// Generate lock files
+// ./gradlew dependencies --write-locks
+
+// Verify locked versions
+// ./gradlew dependencies --verify-metadata
+```
+
+```
+# gradle/dependency-locks/*.lockfile — commit these to version control
+# They ensure every developer and CI uses identical dependency versions
+```
+
+---
+
+## Keeping Dependencies Updated
+
+```bash
+# ✅ Use Gradle Versions Plugin
+plugins {
+    id("com.github.ben-manes.versions") version "0.51.0"
+}
+
+# Check for updates
+./gradlew dependencyUpdates
+
+# Report format options:
+./gradlew dependencyUpdates -Drevision=release
+```
+
+```kotlin
+// ✅ Configure to only suggest stable releases
+tasks.withType<DependencyUpdatesTask> {
+    rejectVersionIf {
+        isNonStable(candidate.version) && !isNonStable(currentVersion)
+    }
+}
+
+fun isNonStable(version: String): Boolean {
+    val unstableKeywords = listOf("alpha", "beta", "rc", "cr", "m", "preview", "eap")
+    return unstableKeywords.any { version.lowercase().contains(it) }
+}
+```
+
+---
+
+## Module Dependency Graph
+
+```kotlin
+// ✅ Enforce no circular dependencies between modules
+// In build-logic convention plugin
+configurations.all {
+    resolutionStrategy.dependencySubstitution {
+        // Feature modules must not depend on each other
+    }
+}
+
+// ✅ Use module dependency graph validation (see module-dependency-graph-validation skill)
+```
+
+---
+
+## Common Conflict Scenarios
+
+```kotlin
+// Scenario 1: Two libraries require different OkHttp versions
+// Library A requires okhttp:3.x, Library B requires okhttp:4.x
+// Gradle picks 4.x by default (highest) — usually fine but verify
+
+// ✅ Verify by checking the dependency tree:
+// ./gradlew :app:dependencyInsight --dependency okhttp
+
+// Scenario 2: Kotlin stdlib version mismatch
+// ✅ Force Kotlin stdlib version to match your Kotlin version
+configurations.all {
+    resolutionStrategy.eachDependency {
+        if (requested.group == "org.jetbrains.kotlin" &&
+            requested.name.startsWith("kotlin-")) {
+            useVersion(libs.versions.kotlin.get())
+            because("Align all Kotlin modules to project Kotlin version")
+        }
+    }
+}
+
+// Scenario 3: Duplicate classes from different artifacts
+// Example: guava-jre vs guava-android
+implementation(libs.guava) {
+    exclude(group = "com.google.guava", module = "guava-jre")
+}
+```
+
+---
+
+## `api` vs `implementation` in Library Modules
+
+```kotlin
+// ✅ Use api() when consumers need the type in their code
+// core/network module:
+api(libs.retrofit)         // ✅ consumers call Retrofit types in their code
+implementation(libs.okhttp) // ✅ consumers don't see OkHttp directly
+
+// ✅ Use implementation() for everything else
+// Leaking implementation details via api() increases compilation coupling
+// — changes to api() deps trigger recompilation of all consumers
+```
+
+---
+
+## Anti-Patterns
+
+- Using `api()` for everything — every change triggers full recompilation
+- Ignoring version conflict warnings — silent resolution may pick wrong version
+- Not using BOM for library groups (Firebase, Compose) — version mismatches
+- Transitive dependency assumption — a dep available via transitive might disappear
+- No dependency locking in CI — different devs get different dependency versions
+- Outdated dependencies — security vulnerabilities accumulate silently
+
+---
+
+## Related Skills
+- `version-catalog` — centralized version definitions
+- `gradle` — Gradle build configuration
+- `build-cache` — caching with consistent dependencies
+- `dependency-compatibility-resolver` — automated conflict resolution
+- `module-dependency-graph-validation` — enforcing module boundaries

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

@@ -0,0 +1,284 @@
+---
+name: gradle
+description: >
+  Gradle build system setup and configuration for Android projects.
+  Load this skill when configuring build.gradle.kts files, setting up
+  Android build config, managing build types, or understanding Gradle
+  fundamentals in an Android context.
+---
+
+# Gradle
+
+## Overview
+Gradle is the build system for Android. It compiles code, manages dependencies, runs tests, and packages the APK/AAB. Android projects use the Kotlin DSL (`build.gradle.kts`) — preferred over Groovy DSL. Understanding Gradle's task graph and configuration phase is essential for maintaining fast, reliable builds.
+
+---
+
+## Core Principles
+
+- Use **Kotlin DSL** (`build.gradle.kts`) — not Groovy (`build.gradle`)
+- Use **Version Catalog** (`libs.versions.toml`) for all dependency versions
+- Use **Convention Plugins** to share build logic across modules
+- Never hardcode versions inline — always reference from Version Catalog
+- Keep `build.gradle.kts` files **short** — logic belongs in convention plugins
+
+---
+
+## Project Structure
+
+```
+project/
+├── build.gradle.kts          ← root build file (minimal)
+├── settings.gradle.kts       ← module declarations
+├── gradle/
+│   ├── libs.versions.toml    ← version catalog
+│   └── wrapper/
+│       └── gradle-wrapper.properties
+├── build-logic/              ← convention plugins
+│   └── convention/
+│       └── src/main/kotlin/
+│           ├── AndroidApplicationConventionPlugin.kt
+│           └── AndroidLibraryConventionPlugin.kt
+├── app/
+│   └── build.gradle.kts
+└── feature/
+    └── build.gradle.kts
+```
+
+---
+
+## settings.gradle.kts
+
+```kotlin
+pluginManagement {
+    includeBuild("build-logic")
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+    repositories {
+        google()
+        mavenCentral()
+    }
+    versionCatalogs {
+        create("libs") {
+            from(files("gradle/libs.versions.toml"))
+        }
+    }
+}
+
+rootProject.name = "MyApp"
+
+include(":app")
+include(":feature:home")
+include(":feature:auth")
+include(":core:network")
+include(":core:database")
+```
+
+---
+
+## Root build.gradle.kts
+
+```kotlin
+// ✅ Root build file — minimal, only plugin declarations
+plugins {
+    alias(libs.plugins.android.application) apply false
+    alias(libs.plugins.android.library) apply false
+    alias(libs.plugins.kotlin.android) apply false
+    alias(libs.plugins.kotlin.serialization) apply false
+    alias(libs.plugins.hilt) apply false
+    alias(libs.plugins.ksp) apply false
+    alias(libs.plugins.google.services) apply false
+    alias(libs.plugins.firebase.crashlytics) apply false
+}
+```
+
+---
+
+## App Module build.gradle.kts
+
+```kotlin
+plugins {
+    alias(libs.plugins.myapp.android.application)  // convention plugin
+    alias(libs.plugins.myapp.android.hilt)
+    alias(libs.plugins.google.services)
+}
+
+android {
+    namespace = "com.example.app"
+
+    defaultConfig {
+        applicationId = "com.example.app"
+        versionCode = 1
+        versionName = "1.0.0"
+
+        // ✅ Build config fields for environment-specific values
+        buildConfigField("String", "API_BASE_URL", "\"https://api.example.com/\"")
+    }
+
+    buildTypes {
+        debug {
+            isDebuggable = true
+            applicationIdSuffix = ".debug"
+            buildConfigField("String", "API_BASE_URL", "\"https://dev.api.example.com/\"")
+        }
+        release {
+            isMinifyEnabled = true
+            isShrinkResources = true
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro"
+            )
+            signingConfig = signingConfigs.getByName("release")
+        }
+    }
+
+    buildFeatures {
+        buildConfig = true
+        compose = true
+    }
+}
+
+dependencies {
+    implementation(projects.core.network)
+    implementation(projects.core.database)
+    implementation(projects.feature.home)
+
+    implementation(platform(libs.firebase.bom))
+    implementation(libs.firebase.analytics)
+}
+```
+
+---
+
+## Library Module build.gradle.kts
+
+```kotlin
+plugins {
+    alias(libs.plugins.myapp.android.library)  // convention plugin
+    alias(libs.plugins.myapp.android.hilt)
+}
+
+android {
+    namespace = "com.example.core.network"
+}
+
+dependencies {
+    implementation(libs.retrofit)
+    implementation(libs.okhttp)
+    implementation(libs.kotlinx.serialization.json)
+    api(libs.retrofit.kotlinx.serialization)  // ✅ api() exposes to consumers
+}
+```
+
+---
+
+## Build Config Access
+
+```kotlin
+// ✅ Access BuildConfig fields in code
+val baseUrl = BuildConfig.API_BASE_URL
+val isDebug = BuildConfig.DEBUG
+val versionName = BuildConfig.VERSION_NAME
+
+// ✅ Enable BuildConfig generation
+android {
+    buildFeatures {
+        buildConfig = true
+    }
+}
+```
+
+---
+
+## Signing Configuration
+
+```kotlin
+// ✅ Read signing config from environment — never hardcode in build file
+android {
+    signingConfigs {
+        create("release") {
+            storeFile = file(System.getenv("KEYSTORE_PATH") ?: "keystore.jks")
+            storePassword = System.getenv("KEYSTORE_PASSWORD")
+            keyAlias = System.getenv("KEY_ALIAS")
+            keyPassword = System.getenv("KEY_PASSWORD")
+        }
+    }
+}
+```
+
+---
+
+## Useful Gradle Tasks
+
+```bash
+# Build
+./gradlew assembleDebug
+./gradlew assembleRelease
+./gradlew bundleRelease          # AAB for Play Store
+
+# Test
+./gradlew test                   # unit tests
+./gradlew connectedAndroidTest   # instrumented tests
+
+# Analysis
+./gradlew lint
+./gradlew detekt
+./gradlew dependencies           # dependency tree
+./gradlew :app:dependencies --configuration debugRuntimeClasspath
+
+# Build performance
+./gradlew assembleDebug --profile   # generates HTML report
+./gradlew assembleDebug --scan      # Gradle build scan
+
+# Clean
+./gradlew clean
+```
+
+---
+
+## Gradle Properties
+
+```properties
+# gradle.properties
+
+# ✅ Performance
+org.gradle.jvmargs=-Xmx4g -XX:+UseParallelGC
+org.gradle.parallel=true
+org.gradle.caching=true
+org.gradle.configuration-cache=true
+
+# ✅ Android
+android.useAndroidX=true
+android.nonTransitiveRClass=true
+android.enableR8.fullMode=true
+
+# ✅ Kotlin
+kotlin.code.style=official
+```
+
+---
+
+## Anti-Patterns
+
+- Groovy DSL (`build.gradle`) in new projects — use Kotlin DSL
+- Hardcoded versions inline — use Version Catalog
+- Business logic in `build.gradle.kts` — use convention plugins
+- `implementation` everywhere — use `api()` when the type is part of public API
+- Not enabling `nonTransitiveRClass` — slows builds in multi-module projects
+- Committing signing credentials in build files — use environment variables
+
+---
+
+## Related Skills
+- `version-catalog` — managing dependency versions
+- `convention-plugin` — shared build logic
+- `build-variant` — build types and flavors
+- `dependency-management` — resolving dependency conflicts
+- `build-cache` — caching build outputs