android-sdd 1.0.0

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

@@ -0,0 +1,199 @@
+---
+name: incremental-build
+description: >
+  Gradle incremental build configuration for Android.
+  Load this skill when optimizing build times, understanding why builds
+  aren't incremental, or configuring tasks for incremental processing.
+---
+
+# Incremental Build
+
+## Overview
+Gradle's incremental build system skips tasks whose inputs and outputs haven't changed. In a properly configured project, only affected modules and tasks re-run after a change. Incremental builds can reduce build time from minutes to seconds.
+
+---
+
+## Core Principles
+
+- Gradle skips tasks when **inputs and outputs are unchanged** — the UP-TO-DATE check
+- Tasks must declare their **inputs and outputs** explicitly for incrementality to work
+- **Configuration cache** skips the configuration phase on subsequent builds
+- **Build cache** reuses task outputs across machines (local and remote)
+- Any task that's not incremental becomes a **build bottleneck**
+
+---
+
+## gradle.properties Configuration
+
+```properties
+# ✅ Enable all incremental build features
+org.gradle.parallel=true                    # parallel task execution
+org.gradle.caching=true                     # local build cache
+org.gradle.configuration-cache=true         # cache configuration phase
+org.gradle.configuration-cache.problems=warn # warn instead of fail on problems
+org.gradle.daemon=true                       # keep Gradle daemon alive
+org.gradle.jvmargs=-Xmx4g -XX:+UseParallelGC
+```
+
+---
+
+## Understanding Task States
+
+```bash
+# Task output states
+# UP-TO-DATE    → inputs/outputs unchanged, task skipped ✅
+# FROM-CACHE    → output restored from build cache ✅
+# NO-SOURCE     → no input sources, task skipped ✅
+# SKIPPED       → task condition not met (e.g., disabled) ✅
+# EXECUTED      → task ran (not incremental) ⚠️
+
+./gradlew assembleDebug --info | grep "Task :"
+# Look for: Task :app:compileDebugKotlin UP-TO-DATE
+```
+
+---
+
+## What Breaks Incrementality
+
+```kotlin
+// ❌ Reading System.currentTimeMillis() in a task — always changes
+tasks.register("generateBuildInfo") {
+    doLast {
+        val file = File(outputDir, "build_info.txt")
+        file.writeText("Built at: ${System.currentTimeMillis()}")  // NOT incremental
+    }
+}
+
+// ✅ Declare inputs/outputs properly
+abstract class GenerateBuildInfoTask : DefaultTask() {
+    @get:Input abstract val buildTimestamp: Property<Long>
+    @get:OutputFile abstract val outputFile: RegularFileProperty
+
+    @TaskAction
+    fun generate() {
+        outputFile.get().asFile.writeText("Built at: ${buildTimestamp.get()}")
+    }
+}
+
+// ✅ Only changes when buildTimestamp input changes
+tasks.register<GenerateBuildInfoTask>("generateBuildInfo") {
+    buildTimestamp.set(System.currentTimeMillis())
+    outputFile.set(layout.buildDirectory.file("generated/build_info.txt"))
+}
+```
+
+---
+
+## KSP Incremental Processing
+
+```kotlin
+// ✅ KSP is incremental by default
+// Room and Hilt benefit automatically
+
+// ✅ Explicit Room incremental config
+ksp {
+    arg("room.incremental", "true")
+}
+```
+
+---
+
+## Avoiding Configuration Cache Problems
+
+```kotlin
+// ❌ Accessing project at execution time — breaks config cache
+tasks.register("badTask") {
+    doLast {
+        println(project.version)  // project accessed at execution — breaks config cache
+    }
+}
+
+// ✅ Capture at configuration time
+tasks.register("goodTask") {
+    val version = project.version.toString()  // captured at config time
+    doLast {
+        println(version)
+    }
+}
+
+// ❌ Using Task.project inside doLast
+tasks.named("assemble") {
+    doLast {
+        project.copy { ... }  // breaks config cache
+    }
+}
+
+// ✅ Use injected services instead
+abstract class MyTask @Inject constructor(
+    private val fs: FileSystemOperations
+) : DefaultTask() {
+    @TaskAction fun run() { fs.copy { ... } }
+}
+```
+
+---
+
+## Checking Build Cache Effectiveness
+
+```bash
+# ✅ Run build twice — second should be FROM-CACHE
+./gradlew assembleDebug
+./gradlew clean
+./gradlew assembleDebug
+# Expected: tasks show FROM-CACHE
+
+# ✅ Build scan — detailed incrementality report
+./gradlew assembleDebug --scan
+# Shows which tasks ran and why
+```
+
+---
+
+## Module-Level Incrementality
+
+```kotlin
+// ✅ Modularization is the biggest win for incremental builds
+// Only modules with changed files recompile
+
+// ✅ Use implementation() not api() — api() propagates recompilation
+// Changing a type in api() triggers recompilation of all consumers
+// Changing a type in implementation() only recompiles that module
+
+// ✅ Minimize module dependencies
+// Feature modules should depend only on :core:* not on each other
+```
+
+---
+
+## Build Performance Profiling
+
+```bash
+# ✅ Profile report (HTML)
+./gradlew assembleDebug --profile
+# Output: build/reports/profile/
+
+# ✅ Build scan (detailed, online)
+./gradlew assembleDebug --scan
+
+# ✅ Find slowest tasks
+./gradlew assembleDebug --profile 2>&1 | grep "ms" | sort -rn | head -20
+```
+
+---
+
+## Anti-Patterns
+
+- Not enabling `org.gradle.caching=true` — cache never used
+- Tasks without declared inputs/outputs — always EXECUTED, never UP-TO-DATE
+- Reading external state (time, random, env vars) inside task actions without declaring as input
+- `api()` dependencies everywhere — breaks incremental compilation between modules
+- Disabling the Gradle daemon — cold start every build
+- Not enabling configuration cache — configuration phase re-runs every build
+
+---
+
+## Related Skills
+- `build-cache` — local and remote build cache
+- `gradle` — Gradle fundamentals
+- `convention-plugin` — consistent task configuration across modules
+- `modularization` — module structure for incremental builds

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

@@ -0,0 +1,198 @@
+---
+name: kapt
+description: >
+  Kotlin Annotation Processing Tool (KAPT) setup and usage for Android.
+  Load this skill when working with libraries that haven't migrated to KSP yet,
+  configuring KAPT options, or understanding why KAPT is slower than KSP.
+---
+
+# KAPT (Kotlin Annotation Processing Tool)
+
+## Overview
+KAPT is the legacy annotation processing framework for Kotlin. It works by generating Java stubs from Kotlin code and then running Java annotation processors on them. This two-step process makes KAPT significantly slower than KSP. Use KAPT only when a library has no KSP support yet.
+
+---
+
+## Core Principles
+
+- **Prefer KSP over KAPT** whenever possible — KSP is 2x faster
+- Use KAPT only for libraries that **haven't migrated to KSP**
+- Never use both KAPT and KSP for the **same library** in the same module
+- KAPT is not compatible with **Kotlin Multiplatform** — use KSP for KMP
+- Track library KSP migration status — switch when available
+
+---
+
+## When to Use KAPT
+
+| Library | KAPT | KSP |
+|---------|------|-----|
+| Hilt | Legacy | ✅ Use KSP |
+| Room | Legacy | ✅ Use KSP |
+| Moshi Codegen | Legacy | ✅ Use KSP |
+| Glide | ✅ Still KAPT | ❌ No KSP yet |
+| Dagger (without Hilt) | ✅ Still KAPT | Partial |
+| Some third-party libs | ✅ Check | Check |
+
+---
+
+## Setup
+
+```kotlin
+// build.gradle.kts
+plugins {
+    kotlin("kapt")  // apply KAPT plugin
+}
+
+dependencies {
+    // ✅ Use kapt() configuration for annotation processors
+    kapt(libs.glide.compiler)
+    kapt(libs.some.legacy.compiler)
+}
+```
+
+---
+
+## KAPT Configuration Options
+
+```kotlin
+// build.gradle.kts
+kapt {
+    // ✅ Enable incremental processing (limited — less effective than KSP)
+    useBuildCache = true
+
+    // ✅ Correct error types — helps KAPT work with complex generics
+    correctErrorTypes = true
+
+    // ✅ Pass arguments to processors
+    arguments {
+        arg("dagger.fastInit", "enabled")
+        arg("dagger.experimentalDaggerErrorMessages", "enabled")
+    }
+
+    // ✅ Show processor warnings
+    showProcessorStats = true
+}
+```
+
+---
+
+## KAPT vs KSP Performance
+
+```
+KAPT Build Flow:
+1. Kotlin → Java stubs (slow)
+2. Java annotation processors run on stubs (slow)
+3. Generated Java code compiled
+4. Kotlin code compiled
+
+KSP Build Flow:
+1. KSP processors run directly on Kotlin symbols (fast)
+2. Generated Kotlin code compiled together
+
+Result: KSP is typically 2x faster than KAPT
+```
+
+---
+
+## Incremental KAPT (Limited)
+
+```kotlin
+// ✅ Enable incremental annotation processing in KAPT
+// Note: much less effective than KSP's incremental processing
+kapt {
+    useBuildCache = true
+}
+
+// gradle.properties
+kapt.incremental.apt=true
+kapt.use.worker.api=true
+```
+
+---
+
+## Migrating from KAPT to KSP
+
+```kotlin
+// Step 1: Remove KAPT plugin (if no more KAPT processors remain)
+// plugins { kotlin("kapt") }  // remove
+
+// Step 2: Add KSP plugin
+plugins {
+    alias(libs.plugins.ksp)
+}
+
+// Step 3: Replace kapt() with ksp() for each processor
+// Before:
+kapt(libs.hilt.compiler)
+kapt(libs.androidx.room.compiler)
+
+// After:
+ksp(libs.hilt.compiler)
+ksp(libs.androidx.room.compiler)
+
+// Step 4: Update KSP-specific config if needed
+ksp {
+    arg("room.schemaLocation", "$projectDir/schemas")
+    arg("room.incremental", "true")
+}
+```
+
+---
+
+## Mixing KAPT and KSP (When Unavoidable)
+
+```kotlin
+// ✅ OK — different libraries, different processors
+plugins {
+    alias(libs.plugins.ksp)   // for Room, Hilt
+    kotlin("kapt")            // for Glide (no KSP yet)
+}
+
+dependencies {
+    ksp(libs.hilt.compiler)           // KSP
+    ksp(libs.androidx.room.compiler)  // KSP
+    kapt(libs.glide.compiler)         // KAPT — no KSP alternative yet
+}
+
+// ❌ NOT OK — same library using both
+ksp(libs.hilt.compiler)   // ❌
+kapt(libs.hilt.compiler)  // ❌ — pick one
+```
+
+---
+
+## Debugging KAPT Issues
+
+```bash
+# ✅ Enable verbose KAPT output
+./gradlew assembleDebug --info 2>&1 | grep -i "kapt"
+
+# ✅ See processor output
+./gradlew assembleDebug -Dkapt.verbose=true
+
+# ✅ Check generated stubs
+# build/tmp/kapt3/stubs/debug/
+
+# ✅ Check generated sources
+# build/generated/source/kapt/debug/
+```
+
+---
+
+## Anti-Patterns
+
+- Using KAPT for libraries that have KSP support — unnecessary slowdown
+- Mixing KAPT and KSP for the same library — one will be ignored or conflict
+- Not setting `correctErrorTypes = true` — obscure compilation errors with complex types
+- Keeping KAPT plugin when all processors have migrated to KSP — dead weight
+- Using KAPT in KMP modules — it's not supported, use KSP
+
+---
+
+## Related Skills
+- `ksp` — modern alternative to KAPT (preferred)
+- `annotation-processing` — annotation processing patterns
+- `gradle` — plugin configuration
+- `hilt` — Hilt now uses KSP
+- `room` — Room now uses KSP

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

@@ -0,0 +1,263 @@
+---
+name: ksp
+description: >
+  Kotlin Symbol Processing (KSP) setup and usage for Android.
+  Load this skill when configuring KSP for code generation libraries
+  (Room, Hilt, Moshi), writing custom KSP processors, or migrating
+  from KAPT to KSP.
+---
+
+# KSP (Kotlin Symbol Processing)
+
+## Overview
+KSP is Kotlin's modern annotation processing framework. It replaces KAPT, is up to 2x faster, supports incremental processing, and works with Kotlin Multiplatform. Most major Android libraries (Room, Hilt, Moshi) have migrated to KSP.
+
+---
+
+## Core Principles
+
+- **Always prefer KSP over KAPT** for new code and when migrating
+- Never mix KSP and KAPT for the **same library** in the same module
+- KSP generates code in `build/generated/ksp/` — never edit generated files
+- KSP configuration goes in the `ksp {}` block — not in `android {}`
+- Enable incremental processing for large codebases
+
+---
+
+## Setup
+
+```toml
+# libs.versions.toml
+[versions]
+ksp = "2.0.0-1.0.21"
+
+[plugins]
+ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
+```
+
+```kotlin
+// build.gradle.kts (module)
+plugins {
+    alias(libs.plugins.ksp)
+}
+
+dependencies {
+    // ✅ KSP-based processors
+    ksp(libs.hilt.compiler)
+    ksp(libs.androidx.room.compiler)
+    ksp(libs.moshi.kotlin.codegen)
+}
+```
+
+---
+
+## KSP Configuration per Library
+
+```kotlin
+// ✅ Room — schema export and incremental processing
+ksp {
+    arg("room.schemaLocation", "$projectDir/schemas")
+    arg("room.incremental", "true")
+    arg("room.expandProjection", "true")
+}
+
+// ✅ Moshi — codegen options
+ksp {
+    arg("moshi.generateProguardRules", "true")
+}
+
+// ✅ Auto Factory — if using Dagger's factory generation
+ksp {
+    arg("dagger.fastInit", "enabled")
+}
+```
+
+---
+
+## KSP in Multi-Module Projects
+
+```kotlin
+// ✅ Apply KSP plugin only in modules that use it
+// feature/home/build.gradle.kts
+plugins {
+    id("myapp.android.library")
+    id("myapp.android.hilt")  // convention plugin applies ksp + hilt.compiler
+}
+
+// ✅ Convention plugin handling KSP setup
+class AndroidHiltConventionPlugin : Plugin<Project> {
+    override fun apply(target: Project) {
+        with(target) {
+            pluginManager.apply("com.google.devtools.ksp")
+            dependencies {
+                add("ksp", libs.findLibrary("hilt-compiler").get())
+            }
+        }
+    }
+}
+```
+
+---
+
+## KSP in KMP Projects
+
+```kotlin
+// ✅ KSP works in KMP — specify target
+kotlin {
+    sourceSets {
+        commonMain.dependencies {
+            implementation(libs.room.runtime)
+        }
+    }
+}
+
+dependencies {
+    // ✅ KSP for specific KMP targets
+    add("kspAndroid", libs.androidx.room.compiler)
+    add("kspJvm", libs.androidx.room.compiler)
+    // add("kspIos...", libs.androidx.room.compiler)  // if supporting iOS
+}
+```
+
+---
+
+## KAPT to KSP Migration
+
+```kotlin
+// ✅ Migration steps per library
+
+// Room — was KAPT
+kapt(libs.androidx.room.compiler)
+// → now KSP
+ksp(libs.androidx.room.compiler)
+
+// Hilt — was KAPT
+kapt(libs.hilt.compiler)
+// → now KSP
+ksp(libs.hilt.compiler)
+
+// Moshi Codegen — was KAPT
+kapt(libs.moshi.kotlin.codegen)
+// → now KSP
+ksp(libs.moshi.kotlin.codegen)
+
+// ✅ Remove KAPT plugin after migration
+// plugins { kotlin("kapt") }  // remove this
+```
+
+---
+
+## Writing a Custom KSP Processor
+
+```kotlin
+// ✅ Implement SymbolProcessor
+class MyProcessor(
+    private val codeGenerator: CodeGenerator,
+    private val logger: KSPLogger,
+    private val options: Map<String, String>
+) : SymbolProcessor {
+
+    override fun process(resolver: Resolver): List<KSAnnotated> {
+        val symbols = resolver
+            .getSymbolsWithAnnotation("com.example.MyAnnotation")
+            .filterIsInstance<KSClassDeclaration>()
+
+        val unprocessed = mutableListOf<KSAnnotated>()
+
+        symbols.forEach { classDecl ->
+            if (!classDecl.validate()) {
+                unprocessed.add(classDecl)
+                return@forEach
+            }
+            generateCode(classDecl)
+        }
+
+        return unprocessed
+    }
+
+    private fun generateCode(classDecl: KSClassDeclaration) {
+        val packageName = classDecl.packageName.asString()
+        val className = "${classDecl.simpleName.asString()}Generated"
+
+        codeGenerator.createNewFile(
+            dependencies = Dependencies(false, classDecl.containingFile!!),
+            packageName = packageName,
+            fileName = className
+        ).use { stream ->
+            stream.write(
+                """
+                package $packageName
+                
+                class $className {
+                    fun hello() = "Generated for ${classDecl.simpleName.asString()}"
+                }
+                """.trimIndent().toByteArray()
+            )
+        }
+    }
+}
+
+// ✅ Provider — registers the processor
+class MyProcessorProvider : SymbolProcessorProvider {
+    override fun create(environment: SymbolProcessorEnvironment): SymbolProcessor =
+        MyProcessor(
+            codeGenerator = environment.codeGenerator,
+            logger = environment.logger,
+            options = environment.options
+        )
+}
+```
+
+```
+# Register in resources/META-INF/services/
+# com.google.devtools.ksp.processing.SymbolProcessorProvider
+com.example.processor.MyProcessorProvider
+```
+
+---
+
+## Viewing Generated Code
+
+```bash
+# Generated code location
+build/generated/ksp/<variant>/kotlin/
+
+# Example for Room
+build/generated/ksp/debug/kotlin/com/example/UserDao_Impl.kt
+
+# ✅ Never edit — regenerated on every build
+```
+
+---
+
+## Incremental Processing
+
+```kotlin
+// ✅ KSP is incremental by default
+// Only reprocesses files that changed
+
+// For custom processors — declare incremental support
+class MyProcessor(...) : SymbolProcessor {
+    // Returning unprocessed symbols from process() is the incremental contract
+    // Symbols that can't be processed yet are returned and retried
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Using KAPT when KSP is available — 2x slower builds
+- Mixing KAPT and KSP for the same library — one will be ignored or conflict
+- Applying KSP plugin to modules that don't use it — unnecessary overhead
+- Editing files in `build/generated/ksp/` — overwritten on next build
+- Not configuring `room.schemaLocation` — migrations can't be written or tested
+
+---
+
+## Related Skills
+- `annotation-processing` — broader annotation processing patterns
+- `room` — Room database with KSP compiler
+- `hilt` — Hilt DI with KSP setup
+- `gradle` — Gradle plugin configuration
+- `kmp` — KSP in multiplatform projects