android-sdd 1.0.0

package/skills/Build Infrastructure/Environment Validator/SKILL.md

@@ -0,0 +1,311 @@
+---
+name: environment-validator
+description: >
+  Validating the build environment before running Android builds.
+  Load this skill when ensuring required tools are installed, verifying
+  SDK versions, checking environment variables, or creating pre-build
+  validation tasks that fail fast with clear error messages.
+---
+
+# Environment Validator
+
+## Overview
+Environment validation ensures the build environment has all required tools, SDKs, and configuration before the build starts. Without validation, builds fail with cryptic errors mid-way through. A good validator fails fast with clear, actionable messages.
+
+---
+
+## Core Principles
+
+- **Fail fast** — validate before any build work begins
+- Provide **clear, actionable error messages** — tell the developer exactly what to fix
+- Validate in `settings.gradle.kts` or a `preBuild` task — earliest possible point
+- Check **required tools** (Java, Android SDK, NDK if needed) and **environment variables**
+- Validation must be **fast** — it runs on every build
+
+---
+
+## Gradle Wrapper Version Validation
+
+```kotlin
+// settings.gradle.kts
+// ✅ Validate Gradle wrapper version
+val minGradleVersion = "8.7"
+val currentVersion = gradle.gradleVersion
+
+if (GradleVersion.version(currentVersion) < GradleVersion.version(minGradleVersion)) {
+    throw GradleException(
+        """
+        ❌ Gradle $minGradleVersion or higher is required.
+        Current version: $currentVersion
+        
+        Fix: Run ./gradlew wrapper --gradle-version=$minGradleVersion
+        """.trimIndent()
+    )
+}
+```
+
+---
+
+## Java Version Validation
+
+```kotlin
+// settings.gradle.kts or root build.gradle.kts
+// ✅ Validate Java version
+val minJavaVersion = JavaVersion.VERSION_17
+val currentJavaVersion = JavaVersion.current()
+
+if (currentJavaVersion < minJavaVersion) {
+    throw GradleException(
+        """
+        ❌ Java $minJavaVersion or higher is required.
+        Current version: $currentJavaVersion
+        
+        Fix: Install JDK 17+ and set JAVA_HOME:
+          export JAVA_HOME=${'$'}(/usr/libexec/java_home -v 17)
+        """.trimIndent()
+    )
+}
+```
+
+---
+
+## Android SDK Validation
+
+```kotlin
+// root build.gradle.kts
+// ✅ Validate Android SDK is installed
+subprojects {
+    afterEvaluate {
+        val androidExtension = extensions.findByName("android") ?: return@afterEvaluate
+        tasks.register("validateAndroidSdk") {
+            group = "verification"
+            doLast {
+                val sdkDir = System.getenv("ANDROID_HOME")
+                    ?: System.getenv("ANDROID_SDK_ROOT")
+                    ?: "${System.getProperty("user.home")}/Library/Android/sdk"
+
+                if (!File(sdkDir).exists()) {
+                    throw GradleException(
+                        """
+                        ❌ Android SDK not found at: $sdkDir
+                        
+                        Fix: Install Android Studio or set ANDROID_HOME:
+                          export ANDROID_HOME=~/Library/Android/sdk
+                        """.trimIndent()
+                    )
+                }
+
+                val compileSdkVersion = 35
+                val platformDir = File(sdkDir, "platforms/android-$compileSdkVersion")
+                if (!platformDir.exists()) {
+                    throw GradleException(
+                        """
+                        ❌ Android SDK platform $compileSdkVersion not installed.
+                        
+                        Fix: Open Android Studio → SDK Manager → Install Android $compileSdkVersion
+                        Or run: sdkmanager "platforms;android-$compileSdkVersion"
+                        """.trimIndent()
+                    )
+                }
+            }
+        }
+
+        tasks.named("preBuild") {
+            dependsOn("validateAndroidSdk")
+        }
+    }
+}
+```
+
+---
+
+## Environment Variables Validation
+
+```kotlin
+// build.gradle.kts (app)
+// ✅ Validate required environment variables for release builds
+tasks.register("validateReleaseEnvironment") {
+    group = "verification"
+    onlyIf { gradle.taskGraph.hasTask(":app:assembleRelease") }
+
+    doLast {
+        val required = mapOf(
+            "KEYSTORE_PATH"     to "Path to the release keystore file",
+            "KEYSTORE_PASSWORD" to "Password for the keystore",
+            "KEY_ALIAS"         to "Key alias in the keystore",
+            "KEY_PASSWORD"      to "Password for the key"
+        )
+
+        val missing = required.filter { (key, _) ->
+            System.getenv(key).isNullOrBlank()
+        }
+
+        if (missing.isNotEmpty()) {
+            throw GradleException(
+                buildString {
+                    appendLine("❌ Missing required environment variables for release build:")
+                    missing.forEach { (key, description) ->
+                        appendLine("  - $key: $description")
+                    }
+                    appendLine()
+                    appendLine("Fix: Set these variables in your CI environment or local .env file.")
+                }
+            )
+        }
+    }
+}
+
+tasks.named("preBuild") {
+    dependsOn("validateReleaseEnvironment")
+}
+```
+
+---
+
+## google-services.json Validation
+
+```kotlin
+// app/build.gradle.kts
+// ✅ Validate google-services.json exists before build
+tasks.register("validateGoogleServices") {
+    group = "verification"
+    doLast {
+        val googleServicesFile = file("google-services.json")
+        if (!googleServicesFile.exists()) {
+            throw GradleException(
+                """
+                ❌ google-services.json not found at: ${googleServicesFile.absolutePath}
+                
+                Fix:
+                1. Go to Firebase Console → Project Settings → Your App
+                2. Download google-services.json
+                3. Place it in the app/ directory
+                
+                Note: Never commit this file to public repositories.
+                """.trimIndent()
+            )
+        }
+    }
+}
+
+tasks.named("preBuild") {
+    dependsOn("validateGoogleServices")
+}
+```
+
+---
+
+## Convention Plugin for Environment Validation
+
+```kotlin
+// build-logic/convention/src/main/kotlin/EnvironmentValidationPlugin.kt
+class EnvironmentValidationPlugin : Plugin<Project> {
+    override fun apply(target: Project) {
+        target.tasks.register("validateEnvironment") {
+            group = "verification"
+            description = "Validates build environment prerequisites"
+
+            doLast {
+                val errors = mutableListOf<String>()
+
+                // Java version
+                if (JavaVersion.current() < JavaVersion.VERSION_17) {
+                    errors += "Java 17+ required (current: ${JavaVersion.current()})"
+                }
+
+                // Gradle version
+                if (GradleVersion.version(target.gradle.gradleVersion) <
+                    GradleVersion.version("8.7")) {
+                    errors += "Gradle 8.7+ required (current: ${target.gradle.gradleVersion})"
+                }
+
+                // ANDROID_HOME
+                val androidHome = System.getenv("ANDROID_HOME")
+                    ?: System.getenv("ANDROID_SDK_ROOT")
+                if (androidHome.isNullOrBlank()) {
+                    errors += "ANDROID_HOME environment variable not set"
+                }
+
+                if (errors.isNotEmpty()) {
+                    throw GradleException(
+                        buildString {
+                            appendLine("❌ Build environment validation failed:")
+                            errors.forEach { appendLine("  • $it") }
+                            appendLine()
+                            appendLine("Fix each issue above and try again.")
+                        }
+                    )
+                }
+
+                println("✅ Build environment validation passed")
+            }
+        }
+
+        target.tasks.configureEach {
+            if (name == "preBuild") {
+                dependsOn("validateEnvironment")
+            }
+        }
+    }
+}
+```
+
+---
+
+## local.properties Validation
+
+```kotlin
+// root build.gradle.kts
+// ✅ Validate local.properties exists and has required keys
+tasks.register("validateLocalProperties") {
+    group = "verification"
+    doLast {
+        val localProps = file("local.properties")
+        if (!localProps.exists()) {
+            throw GradleException(
+                """
+                ❌ local.properties not found.
+                
+                Fix: Create local.properties in the project root with:
+                  sdk.dir=/path/to/your/android/sdk
+                  
+                Android Studio creates this automatically — open the project in AS.
+                """.trimIndent()
+            )
+        }
+
+        val props = java.util.Properties().apply {
+            load(localProps.inputStream())
+        }
+
+        if (props.getProperty("sdk.dir").isNullOrBlank()) {
+            throw GradleException(
+                """
+                ❌ sdk.dir not set in local.properties.
+                
+                Fix: Add to local.properties:
+                  sdk.dir=/Users/yourname/Library/Android/sdk
+                """.trimIndent()
+            )
+        }
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Validation that runs too late — after expensive tasks have already started
+- Cryptic error messages — "SDK not found" without telling where it looked
+- Validating everything on every build — slow, check only what's needed
+- Not validating in CI — environment assumption mismatches cause mysterious failures
+- Hardcoding paths in validation — use environment variables and standard locations
+
+---
+
+## Related Skills
+- `build-orchestration` — task ordering and build pipeline
+- `gradle` — Gradle task configuration
+- `build-variant` — validating per-variant requirements
+- `ci-cd` — environment setup in CI pipeline

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

@@ -0,0 +1,233 @@
+---
+name: build-cache
+description: >
+  Gradle build cache setup for local and remote caching in Android projects.
+  Load this skill when configuring build cache, speeding up CI builds,
+  sharing cached outputs across team members, or debugging cache misses.
+---
+
+# Build Cache
+
+## Overview
+Gradle Build Cache stores task outputs (compiled classes, resources, generated code) and reuses them when the same task runs again with identical inputs. Local cache helps individual developers; remote cache shares outputs across the whole team and CI — dramatically reducing build times.
+
+---
+
+## Core Principles
+
+- Local cache is **always worth enabling** — zero configuration cost, significant speedup
+- Remote cache requires a server — Gradle Enterprise, self-hosted, or GitHub Actions cache
+- Cache keys are computed from task **inputs** — any input change = cache miss
+- **Configuration cache** and **build cache** are complementary but different
+- Never cache tasks with **non-deterministic outputs** — timestamps, random values
+
+---
+
+## Local Cache Setup
+
+```properties
+# gradle.properties
+org.gradle.caching=true       # ✅ enable local build cache
+org.gradle.parallel=true      # parallel execution benefits from cache
+```
+
+```kotlin
+// settings.gradle.kts — explicit local cache config (optional)
+buildCache {
+    local {
+        isEnabled = true
+        directory = File(rootDir, ".gradle/build-cache")
+        removeUnusedEntriesAfterDays = 30
+    }
+}
+```
+
+---
+
+## Remote Cache Setup
+
+### Gradle Enterprise / Develocity
+
+```kotlin
+// settings.gradle.kts
+plugins {
+    id("com.gradle.develocity") version "3.18"
+}
+
+develocity {
+    buildScan {
+        termsOfUseUrl = "https://gradle.com/terms-of-service"
+        termsOfUseAgree = "yes"
+    }
+}
+
+buildCache {
+    local { isEnabled = true }
+    remote<HttpBuildCache> {
+        url = uri("https://gradle-cache.example.com/cache/")
+        credentials {
+            username = System.getenv("GRADLE_CACHE_USERNAME")
+            password = System.getenv("GRADLE_CACHE_PASSWORD")
+        }
+        isPush = System.getenv("CI") == "true"  // only CI pushes to remote
+        isEnabled = true
+    }
+}
+```
+
+### GitHub Actions Cache (Free Alternative)
+
+```yaml
+# .github/workflows/build.yml
+- name: Setup Gradle
+  uses: gradle/actions/setup-gradle@v3
+  with:
+    cache-encryption-key: ${{ secrets.GRADLE_ENCRYPTION_KEY }}
+    # Automatically caches ~/.gradle and build outputs
+```
+
+---
+
+## Verifying Cache Effectiveness
+
+```bash
+# ✅ Run build twice — second should show FROM-CACHE
+./gradlew assembleDebug
+./gradlew clean
+./gradlew assembleDebug
+# Expected: :app:compileDebugKotlin FROM-CACHE
+
+# ✅ Check cache hit rate
+./gradlew assembleDebug --build-cache --info 2>&1 | grep "FROM-CACHE\|UP-TO-DATE\|EXECUTED"
+
+# ✅ Build scan for detailed cache analysis
+./gradlew assembleDebug --scan
+```
+
+---
+
+## Cache Miss Debugging
+
+```bash
+# ✅ Find why a task isn't cached
+./gradlew assembleDebug --info 2>&1 | grep -A5 "compileDebugKotlin"
+# Look for: "Input property ... has changed"
+
+# ✅ Task input fingerprint
+./gradlew assembleDebug --rerun-tasks  # force all tasks to run
+# Then compare with cached run inputs
+
+# Common cache miss causes:
+# - Absolute paths in task inputs
+# - Timestamps in generated files
+# - Environment variables not declared as inputs
+# - Non-deterministic code generation
+```
+
+---
+
+## Making Custom Tasks Cacheable
+
+```kotlin
+// ✅ Declare task as cacheable with proper input/output declarations
+@CacheableTask
+abstract class GenerateApiTask : DefaultTask() {
+
+    @get:InputFiles
+    @get:PathSensitive(PathSensitivity.RELATIVE)  // ✅ relative paths = cache-portable
+    abstract val inputSpecs: ConfigurableFileCollection
+
+    @get:Input
+    abstract val apiVersion: Property<String>
+
+    @get:OutputDirectory
+    abstract val outputDir: DirectoryProperty
+
+    @TaskAction
+    fun generate() {
+        val output = outputDir.get().asFile
+        output.mkdirs()
+        inputSpecs.forEach { spec ->
+            // generate code from spec
+        }
+    }
+}
+
+// ✅ Register
+tasks.register<GenerateApiTask>("generateApi") {
+    inputSpecs.from(fileTree("src/api/specs"))
+    apiVersion.set("v2")
+    outputDir.set(layout.buildDirectory.dir("generated/api"))
+}
+```
+
+---
+
+## Path Sensitivity
+
+```kotlin
+// ✅ Use PathSensitivity to make inputs cache-portable
+@get:InputFiles
+@get:PathSensitive(PathSensitivity.RELATIVE)  // only relative path matters
+abstract val sourceFiles: ConfigurableFileCollection
+
+@get:InputFiles
+@get:PathSensitive(PathSensitivity.NAME_ONLY)  // only filename matters
+abstract val resourceFiles: ConfigurableFileCollection
+
+@get:InputFiles
+@get:PathSensitive(PathSensitivity.NONE)  // only content matters, not path
+abstract val configFiles: ConfigurableFileCollection
+
+// ❌ Absolute path (default) — cache misses on different machines
+@get:InputFiles
+abstract val files: ConfigurableFileCollection  // absolute path = machine-specific
+```
+
+---
+
+## CI Cache Configuration
+
+```yaml
+# .github/workflows/build.yml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 17
+
+      # ✅ Cache Gradle dependencies and build outputs
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v3
+        with:
+          cache-encryption-key: ${{ secrets.GRADLE_ENCRYPTION_KEY }}
+
+      - name: Build
+        run: ./gradlew assembleDebug
+        env:
+          CI: true
+```
+
+---
+
+## Anti-Patterns
+
+- Not enabling local cache — free speedup left on the table
+- Absolute paths in task inputs — cache miss on every machine
+- Non-deterministic task outputs — cache entries become stale/incorrect
+- Pushing to remote cache from developer machines — pollutes cache with unverified outputs
+- `@CacheableTask` without `@PathSensitive` on file inputs — over-broad cache invalidation
+- Timestamps or build numbers as task inputs — always a cache miss
+
+---
+
+## Related Skills
+- `incremental-build` — incremental task execution
+- `gradle` — Gradle build configuration
+- `build-orchestration` — remote cache in multi-project builds
+- `ci-cd` — cache configuration in CI pipeline

package/skills/Build System/Build Flavor Strategy/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: build-flavor-strategy
+description: >
+  Strategy for designing product flavors and build variant structure.
+  Load this skill when deciding how many flavors to create, what each
+  flavor dimension should represent, and how to keep variants manageable.
+---
+
+# Build Flavor Strategy
+
+## Overview
+Product flavors define what variant of the app is built — different environments, tiers, or feature sets. A poorly designed flavor structure leads to exponential variant count, complex CI pipelines, and unmaintainable build files. This skill defines how to design flavor structure deliberately.
+
+---
+
+## Core Principles
+
+- Fewer flavors = simpler CI, faster builds, less maintenance
+- Each flavor dimension should represent a **clearly different product concern**
+- Prefer **build types** for environment differences — flavors for product differences
+- Avoid flavors for things that can be done with **feature flags** or **Remote Config**
+- Document the variant matrix — every combination must have a clear purpose
+
+---
+
+## Common Flavor Patterns
+
+### Pattern 1: Environment Only (Most Common)
+
+```kotlin
+// ✅ Use when you need different backend environments
+flavorDimensions += "environment"
+
+productFlavors {
+    create("dev") {
+        dimension = "environment"
+        applicationIdSuffix = ".dev"
+        buildConfigField("String", "API_URL", "\"https://dev.api.example.com/\"")
+    }
+    create("staging") {
+        dimension = "environment"
+        applicationIdSuffix = ".staging"
+        buildConfigField("String", "API_URL", "\"https://staging.api.example.com/\"")
+    }
+    create("prod") {
+        dimension = "environment"
+        buildConfigField("String", "API_URL", "\"https://api.example.com/\"")
+    }
+}
+// Variants: devDebug, devRelease, stagingDebug, stagingRelease, prodDebug, prodRelease
+```
+
+### Pattern 2: Tier Only
+
+```kotlin
+// ✅ Use when distributing free vs paid version of same app
+flavorDimensions += "tier"
+
+productFlavors {
+    create("free") {
+        dimension = "tier"
+        buildConfigField("Boolean", "IS_PREMIUM", "false")
+    }
+    create("premium") {
+        dimension = "tier"
+        buildConfigField("Boolean", "IS_PREMIUM", "true")
+    }
+}
+```
+
+### Pattern 3: Two Dimensions (Use Sparingly)
+
+```kotlin
+// ✅ Only when both dimensions represent truly independent product axes
+flavorDimensions += listOf("environment", "tier")
+
+// Results in: devFreeDebug, devPremiumDebug, prodFreeRelease, prodPremiumRelease...
+// 8 variants — manageable if most are excluded
+
+android {
+    variantFilter {
+        // Only build dev+free and prod+premium — others don't make sense
+        val env = flavors.find { it.dimension == "environment" }?.name
+        val tier = flavors.find { it.dimension == "tier" }?.name
+        if ((env == "dev" && tier == "premium") || (env == "prod" && tier == "free")) {
+            ignore = true
+        }
+    }
+}
+```
+
+---
+
+## Environment via Build Type vs Flavor
+
+```kotlin
+// ✅ Environment differences → Build Types (simpler)
+// Use when dev/staging/prod differ only in config (URL, keys)
+buildTypes {
+    debug   { buildConfigField("String", "API_URL", "\"https://dev.api.com/\"") }
+    create("staging") { buildConfigField("String", "API_URL", "\"https://staging.api.com/\"") }
+    release { buildConfigField("String", "API_URL", "\"https://api.com/\"") }
+}
+
+// ✅ Environment via Flavors
+// Use when environments need different:
+//   - Firebase projects (different google-services.json)
+//   - App IDs (can install dev and prod side by side)
+//   - Dependencies (dev has debug tools, prod doesn't)
+```
+
+---
+
+## Decision Framework
+
+```
+Do you need separate Firebase projects per environment?
+    YES → Use flavors (each flavor can have its own google-services.json)
+    NO  → Use build types
+
+Do you need to install dev and prod side by side?
+    YES → Use flavors (different applicationId per flavor)
+    NO  → Use build types + applicationIdSuffix
+
+Do you have multiple product tiers (free/paid)?
+    YES → Add a tier flavor dimension
+    NO  → Use feature flags or Remote Config
+
+Would Remote Config solve this without a new flavor?
+    YES → Use Remote Config — avoid the flavor
+    NO  → Proceed with flavor
+```
+
+---
+
+## Variant Matrix Documentation
+
+```markdown
+<!-- Always document the variant matrix in the project -->
+
+## Build Variant Matrix
+
+| Variant | Purpose | Used By |
+|---------|---------|---------|
+| devDebug | Local development | Developers |
+| devRelease | Dev build for QA | QA team |
+| stagingRelease | Pre-prod testing | QA + stakeholders |
+| prodRelease | Production release | Play Store |
+
+### Excluded Variants
+- stagingDebug — unnecessary (staging = pre-prod, always release config)
+- prodDebug — security risk (debuggable prod build)
+```
+
+---
+
+## Anti-Patterns
+
+- More than 2 flavor dimensions — variant count explodes (3 dims × 2 values = 8+ variants)
+- Using flavors for feature flags — use Remote Config instead, no rebuild needed
+- No variant filtering — building all combinations wastes CI time
+- Flavors with overlapping purposes with build types — pick one
+- Not documenting the variant matrix — developers don't know which variant to use
+
+---
+
+## Related Skills
+- `build-variant` — implementing build types and flavors
+- `gradle` — Gradle build configuration
+- `remote-config` — replacing flavor-based feature switching
+- `ci-cd` — building specific variants in CI pipeline