android-sdd 1.0.0

package/skills/Build Infrastructure/Build Orchestration/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: build-orchestration
+description: >
+  Build orchestration for Android multi-module projects — task ordering,
+  parallel builds, and coordinating complex build pipelines.
+  Load this skill when optimizing multi-module build order, configuring
+  parallel execution, or designing the build pipeline for CI/CD.
+---
+
+# Build Orchestration
+
+## Overview
+Build orchestration is the coordination of Gradle tasks across modules — ensuring they run in the right order, in parallel where possible, and with the right inputs/outputs declared. In multi-module projects, a poorly orchestrated build is the single biggest source of wasted build time.
+
+---
+
+## Core Principles
+
+- Gradle determines task order from **dependency declarations** — not manual ordering
+- Tasks that don't depend on each other run **in parallel** when `org.gradle.parallel=true`
+- The **critical path** is the longest chain of dependent tasks — optimize it first
+- Declare task **inputs and outputs** correctly — enables parallelism and caching
+- Module **dependency graph shape** determines maximum parallelism
+
+---
+
+## Parallel Build Configuration
+
+```properties
+# gradle.properties
+org.gradle.parallel=true           # ✅ enable parallel task execution
+org.gradle.workers.max=8           # max parallel workers (default = CPU cores)
+org.gradle.caching=true            # tasks restored from cache run "instantly"
+org.gradle.configuration-cache=true
+org.gradle.jvmargs=-Xmx6g -XX:+UseParallelGC
+```
+
+---
+
+## Module Dependency Graph and Parallelism
+
+```
+# Wide graph = more parallelism
+:app
+├── :feature:home     ← builds in parallel
+├── :feature:auth     ← builds in parallel
+├── :feature:profile  ← builds in parallel
+└── :core:network     ← shared, built once
+
+# Deep/narrow graph = sequential, slower
+:app → :feature:home → :core:ui → :core:common
+# Each must wait for the previous — no parallelism
+```
+
+```kotlin
+// ✅ Avoid deep chains — prefer wide, shallow dependency graphs
+// feature modules should only depend on :core:*, not on each other
+```
+
+---
+
+## Task Dependencies
+
+```kotlin
+// ✅ Explicit task ordering when needed
+tasks.named("generateBuildConfig") {
+    mustRunAfter("clean")
+}
+
+// ✅ Finalizer task — runs after another regardless of success/failure
+tasks.named("assembleRelease") {
+    finalizedBy("uploadToStore")
+}
+
+// ✅ Lifecycle task — aggregate multiple tasks
+tasks.register("buildAll") {
+    group = "build"
+    description = "Build all variants"
+    dependsOn(
+        ":app:assembleDebug",
+        ":app:assembleRelease",
+        ":app:bundleRelease"
+    )
+}
+```
+
+---
+
+## Build Lifecycle Hooks
+
+```kotlin
+// ✅ Run a task before every build
+tasks.named("preBuild") {
+    dependsOn("validateModuleDependencies")
+    dependsOn("assertModuleGraph")
+}
+
+// ✅ Run code quality checks as part of build
+tasks.named("check") {
+    dependsOn("detekt")
+    dependsOn("ktlintCheck")
+}
+
+// ✅ Hook into assemble
+tasks.configureEach {
+    if (name == "assembleRelease") {
+        doFirst {
+            println("Starting release build: ${project.version}")
+        }
+        doLast {
+            println("Release build complete")
+        }
+    }
+}
+```
+
+---
+
+## Multi-Module Build Order
+
+```kotlin
+// ✅ Gradle determines order automatically from module dependencies
+// :core:common compiles first (no deps)
+// :core:network compiles after :core:common
+// :feature:home compiles after :core:network
+// :app compiles last (depends on all features)
+
+// ✅ Verify build order with
+// ./gradlew :app:assembleDebug --dry-run
+// Shows tasks in order without executing
+```
+
+---
+
+## Composite Builds
+
+```kotlin
+// ✅ Include build-logic as a composite build
+// settings.gradle.kts
+pluginManagement {
+    includeBuild("build-logic")
+}
+
+// ✅ Multiple composite builds
+pluginManagement {
+    includeBuild("build-logic")
+    includeBuild("shared-conventions")
+}
+
+// Benefits:
+// - build-logic plugins are compiled separately
+// - Changes to build-logic don't invalidate app module caches
+// - Build-logic can be shared across projects
+```
+
+---
+
+## Build Scan Integration
+
+```kotlin
+// settings.gradle.kts
+plugins {
+    id("com.gradle.develocity") version "3.18"
+}
+
+develocity {
+    buildScan {
+        termsOfUseUrl = "https://gradle.com/terms-of-service"
+        termsOfUseAgree = "yes"
+        publishing.onlyIf { System.getenv("CI") == "true" }
+
+        tag(if (System.getenv("CI") == "true") "CI" else "Local")
+        value("Git Branch", System.getenv("GITHUB_REF_NAME") ?: "local")
+    }
+}
+```
+
+---
+
+## CI Build Matrix
+
+```yaml
+# .github/workflows/build.yml
+jobs:
+  build:
+    strategy:
+      matrix:
+        task: [assembleDebug, test, lint, detekt]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: gradle/actions/setup-gradle@v3
+      - name: Run ${{ matrix.task }}
+        run: ./gradlew ${{ matrix.task }}
+```
+
+---
+
+## Build Time Analysis
+
+```bash
+# ✅ Profile build
+./gradlew assembleDebug --profile
+# Open: build/reports/profile/profile-*.html
+
+# ✅ Build scan (detailed — requires Gradle Enterprise or free plan)
+./gradlew assembleDebug --scan
+
+# ✅ Find the critical path
+./gradlew assembleDebug --scan
+# Build scan shows critical path in timeline view
+
+# ✅ Identify slowest tasks
+./gradlew assembleDebug --profile 2>&1 | grep "ms :" | sort -t' ' -k1 -rn | head -20
+```
+
+---
+
+## Optimizing the Critical Path
+
+```kotlin
+// The critical path is typically:
+// :app:compileDebugKotlin → :app:mergeDebugResources → :app:packageDebug
+
+// ✅ Strategy 1: Move code out of :app into feature modules
+// Less code in :app = faster :app:compileDebugKotlin
+
+// ✅ Strategy 2: Use @JvmField and @JvmStatic where appropriate
+// Reduces generated code size
+
+// ✅ Strategy 3: Avoid annotation processing in :app
+// Move annotated classes to feature/core modules
+
+// ✅ Strategy 4: Use Baseline Profiles
+// Reduces ART compilation burden at install time (not build time)
+```
+
+---
+
+## Anti-Patterns
+
+- All code in `:app` — no parallelism possible, everything sequential
+- Feature modules depending on each other — forces sequential builds
+- Missing `org.gradle.parallel=true` — single-threaded builds
+- No build caching — every CI run starts from scratch
+- Too many custom task hooks — interference with Gradle's optimization
+- Running all checks in one sequential job in CI — parallelize with job matrix
+
+---
+
+## Related Skills
+- `gradle` — Gradle build fundamentals
+- `build-cache` — caching task outputs
+- `incremental-build` — UP-TO-DATE checks
+- `modularization` — module structure for build parallelism
+- `module-dependency-graph-validation` — keeping the graph valid
+- `environment-validator` — validating build environment before running

package/skills/Build Infrastructure/Dependency Compatibility Resolver/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: dependency-compatibility-resolver
+description: >
+  Detecting and resolving dependency version conflicts in Android/Gradle projects.
+  Load this skill when a dependency causes a version conflict, when builds fail
+  due to duplicate classes, or when upgrading a library causes transitive
+  dependency issues.
+---
+
+# Dependency Compatibility Resolver
+
+## Overview
+Dependency conflicts occur when multiple libraries require different versions of the same transitive dependency. Gradle resolves these automatically using its "highest version wins" strategy — but this can silently break things. This skill provides systematic techniques to detect, diagnose, and resolve conflicts correctly.
+
+---
+
+## Core Principles
+
+- **Understand the conflict first** — don't just force a version blindly
+- "Highest version wins" is Gradle's default — it usually works but not always
+- Conflicts between **major versions** are often breaking — require careful testing
+- Use **BOM** to align library groups — Firebase, Compose, OkHttp suites
+- Document **why** a version was forced — future maintainers need context
+
+---
+
+## Detecting Conflicts
+
+```bash
+# ✅ View full dependency tree
+./gradlew :app:dependencies --configuration debugRuntimeClasspath
+
+# ✅ Find all versions of a specific dependency
+./gradlew :app:dependencyInsight \
+    --configuration debugRuntimeClasspath \
+    --dependency okhttp
+
+# ✅ Find duplicate classes (build error)
+# Error: Duplicate class kotlin.collections.jdk8.CollectionsJDK8Kt found in modules
+# → Two libraries bring different versions of kotlin-stdlib
+
+# ✅ Check for version conflicts summary
+./gradlew :app:dependencies --configuration debugRuntimeClasspath 2>&1 | grep " -> "
+# Lines with " -> " show where Gradle picked a different version than requested
+```
+
+---
+
+## Reading the Dependency Tree
+
+```
+# ✅ How to read dependency tree output
++--- com.squareup.retrofit2:retrofit:2.11.0
+|    +--- com.squareup.okhttp3:okhttp:4.12.0 (*)     ← (*) = already shown
+|    \--- com.squareup.okio:okio:3.6.0
+\--- com.squareup.okhttp3:logging-interceptor:4.12.0
+     \--- com.squareup.okhttp3:okhttp:4.12.0 (*)
+
+# ✅ Version conflict shown as:
++--- com.example:library-a:1.0.0
+|    \--- com.squareup.okhttp3:okhttp:3.14.9 -> 4.12.0
+#                                           ^^^^^^^^^^
+#                                           Gradle upgraded from 3.x to 4.x
+```
+
+---
+
+## Resolution Strategies
+
+### Strategy 1: Force a Specific Version
+
+```kotlin
+// ✅ Use when you need to pin a transitive dependency
+configurations.all {
+    resolutionStrategy {
+        force("com.squareup.okhttp3:okhttp:4.12.0")
+        force("org.jetbrains.kotlin:kotlin-stdlib:2.0.0")
+    }
+}
+
+// ✅ Document the reason
+configurations.all {
+    resolutionStrategy.eachDependency {
+        if (requested.group == "com.squareup.okhttp3") {
+            useVersion("4.12.0")
+            because("Library X requires 3.x but we need 4.x features; verified compatible")
+        }
+    }
+}
+```
+
+### Strategy 2: Exclude Transitive Dependency
+
+```kotlin
+// ✅ When a library brings an unwanted transitive dep
+implementation(libs.some.library) {
+    exclude(group = "com.google.guava", module = "guava-jre")
+    // guava-jre conflicts with guava-android — exclude jre version
+}
+
+// ✅ Exclude globally across all configurations
+configurations.all {
+    exclude(group = "commons-logging", module = "commons-logging")
+    // replaced by SLF4J — exclude old binding
+}
+```
+
+### Strategy 3: Use BOM for Aligned Versions
+
+```kotlin
+// ✅ BOM ensures all modules in a suite use the same version
+dependencies {
+    // OkHttp BOM
+    implementation(platform("com.squareup.okhttp3:okhttp-bom:4.12.0"))
+    implementation("com.squareup.okhttp3:okhttp")
+    implementation("com.squareup.okhttp3:logging-interceptor")
+    // Both use 4.12.0 — no conflict possible
+
+    // Firebase BOM
+    implementation(platform(libs.firebase.bom))
+    implementation(libs.firebase.analytics)
+    implementation(libs.firebase.crashlytics)
+}
+```
+
+### Strategy 4: Substitute a Dependency
+
+```kotlin
+// ✅ Replace one dependency with another (e.g., different artifact for Android)
+configurations.all {
+    resolutionStrategy.dependencySubstitution {
+        // Replace guava-jre with guava-android
+        substitute(module("com.google.guava:guava-jre"))
+            .using(module("com.google.guava:guava:32.1.3-android"))
+            .because("Android requires -android variant, not -jre")
+    }
+}
+```
+
+---
+
+## Common Conflict Scenarios
+
+### Kotlin Stdlib Conflict
+
+```kotlin
+// Problem: Multiple kotlin-stdlib versions
+// Solution: Force to match project 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")
+        }
+    }
+}
+```
+
+### OkHttp 3 vs 4 Conflict
+
+```kotlin
+// Problem: Library A needs OkHttp 3.x, app uses 4.x
+// Solution: Force 4.x — OkHttp 4 is mostly backward compatible
+configurations.all {
+    resolutionStrategy.force("com.squareup.okhttp3:okhttp:4.12.0")
+}
+// ✅ Test the library that needed 3.x still works
+```
+
+### Duplicate Class Error
+
+```kotlin
+// Error: Duplicate class kotlin.collections.jdk8.CollectionsJDK8Kt
+// Cause: kotlin-stdlib-jdk8 merged into kotlin-stdlib in Kotlin 1.8+
+// Solution: Exclude the separate artifact
+
+configurations.all {
+    resolutionStrategy.eachDependency {
+        if (requested.group == "org.jetbrains.kotlin" &&
+            (requested.name == "kotlin-stdlib-jdk7" ||
+             requested.name == "kotlin-stdlib-jdk8")) {
+            useTarget("org.jetbrains.kotlin:kotlin-stdlib:${requested.version}")
+            because("kotlin-stdlib-jdk7/8 merged into kotlin-stdlib since 1.8")
+        }
+    }
+}
+```
+
+### Guava JRE vs Android
+
+```kotlin
+// Problem: Some libraries bring guava-jre which has Java 8+ APIs not on Android
+configurations.all {
+    resolutionStrategy.dependencySubstitution {
+        substitute(module("com.google.guava:guava"))
+            .using(module("com.google.guava:guava:32.1.3-android"))
+            .because("Android requires -android variant")
+    }
+}
+```
+
+---
+
+## Verification After Resolution
+
+```bash
+# ✅ Verify the resolved version is what you expect
+./gradlew :app:dependencyInsight \
+    --dependency okhttp \
+    --configuration debugRuntimeClasspath
+
+# ✅ Run tests to verify compatibility
+./gradlew test
+./gradlew connectedAndroidTest
+
+# ✅ Check for duplicate classes
+./gradlew assembleDebug 2>&1 | grep "Duplicate class"
+```
+
+---
+
+## Documenting Resolutions
+
+```kotlin
+// ✅ Always explain why a version was forced
+configurations.all {
+    resolutionStrategy.eachDependency {
+        when {
+            requested.group == "com.squareup.okhttp3" -> {
+                useVersion("4.12.0")
+                because(
+                    "Library X still requests OkHttp 3.14 but is compatible with 4.x. " +
+                    "Verified with X's test suite on 2024-11-15. " +
+                    "Remove this override when X releases 2.0 with native OkHttp 4 support."
+                )
+            }
+        }
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Blindly forcing a version without testing — can break the library that needed the old version
+- Not documenting resolution reasons — future maintainers don't know why it's forced
+- Excluding a dep without verifying the library works without it — runtime crash
+- Ignoring `-> x.y.z` in dependency tree — silent upgrades can break things
+- Forcing an older version when Gradle upgraded for good reason — misses security fixes
+
+---
+
+## Related Skills
+- `dependency-management` — dependency configurations and upgrades
+- `version-catalog` — centralized version management
+- `gradle` — Gradle build configuration
+- `build-cache` — cache invalidation after dependency changes