android-sdd 1.0.0

package/skills/Concurrency/Synchronization Policy/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: synchronization-policy
+description: >
+  Thread safety and synchronization policy for Android with coroutines.
+  Load this skill when defining how shared state is accessed across threads,
+  deciding between confinement vs locking, ensuring data consistency,
+  or auditing code for race conditions.
+---
+
+# Synchronization Policy
+
+## Overview
+
+Synchronization policy defines the rules for safely accessing shared mutable state across coroutines and threads. The safest approach is **confinement** — restricting access to a single thread or coroutine — rather than locking. When shared access is unavoidable, use coroutine-friendly primitives like `Mutex` and `StateFlow.update`.
+
+---
+
+## Core Principles
+
+- Prefer **confinement** over locking — restrict state to one dispatcher or coroutine
+- Prefer **immutable data** — no synchronization needed if data can't change
+- Use `StateFlow.update` for UI state — it's atomic and coroutine-safe
+- Use `Mutex` only when state must be shared across multiple coroutines
+- Never access the same mutable state from both `Dispatchers.IO` and `Dispatchers.Main` without synchronization
+
+---
+
+## Strategy 1 — Confinement (Preferred)
+
+```kotlin
+// ✅ Confine mutable state to a single dispatcher
+class DataCache @Inject constructor() {
+    // All access happens on a single-threaded dispatcher
+    private val cacheDispatcher = Dispatchers.IO.limitedParallelism(1)
+    private val cache = mutableMapOf<String, Data>()
+
+    suspend fun get(key: String): Data? = withContext(cacheDispatcher) {
+        cache[key]
+    }
+
+    suspend fun put(key: String, data: Data) = withContext(cacheDispatcher) {
+        cache[key] = data
+    }
+
+    suspend fun clear() = withContext(cacheDispatcher) {
+        cache.clear()
+    }
+}
+```
+
+---
+
+## Strategy 2 — Immutable State + Atomic Updates
+
+```kotlin
+// ✅ Immutable data class + atomic StateFlow update
+class CartManager @Inject constructor() {
+    private val _cart = MutableStateFlow(Cart())
+    val cart: StateFlow<Cart> = _cart.asStateFlow()
+
+    fun addItem(item: CartItem) {
+        _cart.update { current ->
+            current.copy(items = current.items + item)  // new list — immutable
+        }
+    }
+
+    fun removeItem(itemId: String) {
+        _cart.update { current ->
+            current.copy(items = current.items.filter { it.id != itemId })
+        }
+    }
+}
+
+data class Cart(
+    val items: List<CartItem> = emptyList()  // immutable list
+)
+```
+
+---
+
+## Strategy 3 — Mutex for Shared Mutable State
+
+```kotlin
+// ✅ Use Mutex when multiple coroutines must share mutable state
+class ConnectionPool @Inject constructor() {
+    private val mutex = Mutex()
+    private val connections = mutableListOf<Connection>()
+
+    suspend fun acquire(): Connection = mutex.withLock {
+        connections.removeFirstOrNull() ?: createNewConnection()
+    }
+
+    suspend fun release(connection: Connection) = mutex.withLock {
+        connections.add(connection)
+    }
+}
+```
+
+---
+
+## Choosing the Right Strategy
+
+```
+Is the state only read after initialization?
+  → Use val + immutable data class — no sync needed
+
+Is the state only accessed from one coroutine/dispatcher?
+  → Use confinement (limitedParallelism(1)) — no sync needed
+
+Is the state a simple counter or flag?
+  → Use AtomicInteger / AtomicBoolean — no coroutine sync needed
+
+Is the state UI state in a ViewModel?
+  → Use MutableStateFlow.update — built-in atomic update
+
+Is the state accessed by multiple coroutines concurrently?
+  → Use Mutex.withLock
+```
+
+---
+
+## Thread Confinement with limitedParallelism
+
+```kotlin
+// ✅ Single-threaded context for all operations on shared resource
+private val singleThreadContext = Dispatchers.IO.limitedParallelism(1)
+
+// All database writes serialized through single thread
+suspend fun writeData(data: List<Item>) = withContext(singleThreadContext) {
+    dao.deleteAll()
+    dao.insertAll(data)
+}
+```
+
+---
+
+## Common Race Conditions to Avoid
+
+```kotlin
+// ❌ Check-then-act race condition
+if (cache[key] == null) {           // thread A checks
+    cache[key] = expensiveCompute() // thread B also checks — both compute
+}
+
+// ✅ Fix with Mutex
+mutex.withLock {
+    if (cache[key] == null) {
+        cache[key] = expensiveCompute()
+    }
+}
+
+// ❌ Non-atomic read-modify-write
+_state.value = _state.value.copy(count = _state.value.count + 1)  // race
+
+// ✅ Fix with update
+_state.update { it.copy(count = it.count + 1) }  // atomic
+```
+
+---
+
+## Annotations for Documentation
+
+```kotlin
+// ✅ Document thread-safety expectations
+@ThreadSafe
+class SafeCache { /* ... */ }
+
+@MainThread
+fun updateUi(data: List<Item>) { /* ... */ }
+
+@WorkerThread
+suspend fun loadFromDisk(): List<Item> { /* ... */ }
+```
+
+---
+
+## Anti-Patterns
+
+- Accessing a `MutableList` from multiple coroutines without synchronization — race condition
+- Using `synchronized {}` in coroutine code — blocks the thread
+- Mutable `var` property in a class accessed from multiple dispatchers without protection
+- Reading `StateFlow.value` and writing separately — use `update {}` instead
+- Assuming coroutines on the same dispatcher are sequential — they may interleave at suspension points
+
+---
+
+## Related Skills
+
+- `mutex-strategy` — Mutex and Semaphore implementation details
+- `coroutine` — dispatcher selection and coroutine fundamentals
+- `structured-concurrency` — coroutine lifetime and cancellation
+- `stateflow` — atomic state updates with StateFlow

package/skills/Core Language/Annotation Processing/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: annotation-processing
+description: >
+  Annotation processing setup and usage for Android development.
+  Load this skill when working with KSP or KAPT, creating custom annotations,
+  configuring code generation tools (Hilt, Room, Moshi, etc.), or
+  understanding how annotation processors fit into the build pipeline.
+---
+
+# Annotation Processing
+
+## Overview
+
+Annotation processing generates code at compile time based on annotations in the source code. In Android, this powers libraries like Room, Hilt, Moshi, and Glide. KSP (Kotlin Symbol Processing) is the modern replacement for KAPT and should be preferred in all new projects.
+
+---
+
+## Core Principles
+
+- **Always prefer KSP over KAPT** — KSP is faster, Kotlin-first, and KMP-compatible
+- Use KAPT only when a library hasn't migrated to KSP yet
+- Never mix KSP and KAPT for the same library
+- Annotation processors run at **compile time** — errors are caught early
+- Generated code lives in `build/generated/` — never edit it manually
+
+---
+
+## KSP vs KAPT
+
+|                | KSP                  | KAPT                    |
+| -------------- | -------------------- | ----------------------- |
+| Speed          | Fast (Kotlin-native) | Slow (stubs generation) |
+| KMP Support    | ✅ Yes                | ❌ No                    |
+| Incremental    | ✅ Yes                | Partial                 |
+| Kotlin-first   | ✅ Yes                | ❌ Java-based            |
+| Recommendation | **Use this**         | Only if no KSP support  |
+
+---
+
+## Setup
+
+### KSP
+
+```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
+plugins {
+    alias(libs.plugins.ksp)
+}
+
+dependencies {
+    // KSP-based libraries
+    ksp(libs.hilt.compiler)
+    ksp(libs.room.compiler)
+}
+```
+
+### KAPT (legacy — only when KSP unavailable)
+
+```kotlin
+plugins {
+    kotlin("kapt")
+}
+
+dependencies {
+    kapt(libs.some.legacy.compiler)
+}
+```
+
+---
+
+## Common Libraries and Their Processor
+
+| Library     | Processor Type | Dependency                       |
+| ----------- | -------------- | -------------------------------- |
+| Hilt        | KSP            | `ksp(libs.hilt.compiler)`        |
+| Room        | KSP            | `ksp(libs.room.compiler)`        |
+| Moshi       | KSP            | `ksp(libs.moshi.kotlin.codegen)` |
+| Glide       | KAPT           | `kapt(libs.glide.compiler)`      |
+| DataBinding | Built-in       | No extra setup                   |
+
+---
+
+## Custom Annotations
+
+```kotlin
+// ✅ Define annotation
+@Target(AnnotationTarget.CLASS)
+@Retention(AnnotationRetention.SOURCE)
+annotation class AutoFactory
+
+// ✅ Define annotation with parameters
+@Target(AnnotationTarget.FUNCTION)
+@Retention(AnnotationRetention.RUNTIME)
+annotation class RequiresPermission(val value: String)
+```
+
+---
+
+## Custom KSP Processor
+
+```kotlin
+// ✅ Implement SymbolProcessor
+class AutoFactoryProcessor(
+    private val codeGenerator: CodeGenerator,
+    private val logger: KSPLogger
+) : SymbolProcessor {
+
+    override fun process(resolver: Resolver): List<KSAnnotated> {
+        val symbols = resolver
+            .getSymbolsWithAnnotation(AutoFactory::class.qualifiedName!!)
+            .filterIsInstance<KSClassDeclaration>()
+
+        symbols.forEach { classDecl ->
+            generateFactory(classDecl)
+        }
+
+        return emptyList()
+    }
+
+    private fun generateFactory(classDecl: KSClassDeclaration) {
+        val packageName = classDecl.packageName.asString()
+        val className = classDecl.simpleName.asString()
+
+        codeGenerator.createNewFile(
+            dependencies = Dependencies(false, classDecl.containingFile!!),
+            packageName = packageName,
+            fileName = "${className}Factory"
+        ).use { stream ->
+            stream.write(generateFactoryCode(packageName, className).toByteArray())
+        }
+    }
+}
+
+// ✅ Register processor
+class AutoFactoryProcessorProvider : SymbolProcessorProvider {
+    override fun create(environment: SymbolProcessorEnvironment): SymbolProcessor =
+        AutoFactoryProcessor(environment.codeGenerator, environment.logger)
+}
+```
+
+```
+# Register in resources/META-INF/services/
+# com.google.devtools.ksp.processing.SymbolProcessorProvider
+com.example.processor.AutoFactoryProcessorProvider
+```
+
+---
+
+## KSP in Multi-Module Projects
+
+```kotlin
+// ✅ Apply KSP only in modules that use it
+// feature/build.gradle.kts
+plugins {
+    alias(libs.plugins.ksp)
+}
+
+// ✅ Room — schema export location per module
+ksp {
+    arg("room.schemaLocation", "$projectDir/schemas")
+    arg("room.incremental", "true")
+}
+
+// ✅ Hilt — no extra config needed per module
+```
+
+---
+
+## Incremental Processing
+
+```kotlin
+// ✅ Enable incremental annotation processing for Room
+ksp {
+    arg("room.incremental", "true")
+}
+
+// ✅ KSP is incremental by default — no extra config needed
+// ❌ KAPT incremental is unreliable — another reason to prefer KSP
+```
+
+---
+
+## Debugging Annotation Processors
+
+```bash
+# View generated code
+# build/generated/ksp/<variant>/kotlin/
+
+# Enable KSP verbose logging
+ksp {
+    arg("verbose", "true")
+}
+
+# Clean and rebuild when processor changes
+./gradlew clean assembleDebug
+```
+
+---
+
+## Anti-Patterns
+
+- Using KAPT when KSP is available for the same library
+- Mixing KAPT and KSP for the same library in the same module
+- Editing generated files in `build/generated/` — they are overwritten on rebuild
+- Applying KSP plugin to modules that don't need it — adds unnecessary compile overhead
+- Using `@Retention(RUNTIME)` when `SOURCE` is sufficient — bloats the binary
+
+---
+
+## Related Skills
+
+- `hilt` — Hilt DI with KSP setup
+- `room` — Room database with KSP compiler
+- `gradle` — build configuration and plugin setup
+- `kmp` — KSP in multiplatform modules

package/skills/Core Language/DSL/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: dsl
+description: >
+  Kotlin DSL design and implementation patterns for Android development.
+  Load this skill when designing builder APIs, configuration blocks,
+  type-safe builders, or any fluent API that leverages Kotlin's DSL capabilities.
+---
+
+# Kotlin DSL
+
+## Overview
+
+Kotlin DSLs (Domain-Specific Languages) allow expressing configuration, building objects, and defining structure in a readable, type-safe way using lambdas with receivers. Common in Gradle scripts, Compose, Ktor, and custom builders.
+
+---
+
+## Core Principles
+
+- DSLs should **read like natural language** in their domain
+- DSLs should be **type-safe** — wrong usage must fail at compile time
+- Use `@DslMarker` to prevent implicit receiver leakage
+- Keep DSL scope **focused** — one responsibility per receiver class
+
+---
+
+## Basic DSL Pattern
+
+```kotlin
+// ✅ Lambda with receiver
+class DialogBuilder {
+    var title: String = ""
+    var message: String = ""
+    private val buttons = mutableListOf<Button>()
+
+    fun button(label: String, action: () -> Unit) {
+        buttons.add(Button(label, action))
+    }
+
+    fun build(): Dialog = Dialog(title, message, buttons)
+}
+
+fun dialog(block: DialogBuilder.() -> Unit): Dialog {
+    return DialogBuilder().apply(block).build()
+}
+
+// Usage
+val dialog = dialog {
+    title = "Confirm"
+    message = "Are you sure?"
+    button("Yes") { confirm() }
+    button("No") { dismiss() }
+}
+```
+
+---
+
+## @DslMarker — Preventing Receiver Leakage
+
+```kotlin
+// ✅ Always annotate DSL scopes with @DslMarker
+@DslMarker
+annotation class DialogDsl
+
+@DialogDsl
+class DialogBuilder { ... }
+
+@DialogDsl
+class ButtonBuilder { ... }
+
+// Without @DslMarker, inner blocks can access outer receivers
+// causing confusing and hard-to-debug behavior
+```
+
+---
+
+## Type-Safe Builder Pattern
+
+```kotlin
+// ✅ Use for building structured/hierarchical data
+@DslMarker
+annotation class RouteDsl
+
+@RouteDsl
+class RouteBuilder {
+    private val routes = mutableListOf<Route>()
+
+    fun route(path: String, block: RouteConfig.() -> Unit) {
+        routes.add(RouteConfig(path).apply(block).build())
+    }
+
+    fun build(): List<Route> = routes
+}
+
+@RouteDsl
+class RouteConfig(val path: String) {
+    var requiresAuth: Boolean = false
+    var deepLink: String? = null
+
+    fun build(): Route = Route(path, requiresAuth, deepLink)
+}
+
+fun routes(block: RouteBuilder.() -> Unit): List<Route> =
+    RouteBuilder().apply(block).build()
+
+// Usage
+val appRoutes = routes {
+    route("/home") {
+        requiresAuth = true
+    }
+    route("/login") {
+        deepLink = "app://login"
+    }
+}
+```
+
+---
+
+## DSL for Configuration
+
+```kotlin
+// ✅ Common pattern for library/module configuration
+class NetworkConfig {
+    var baseUrl: String = ""
+    var timeoutMs: Long = 30_000
+    var retryCount: Int = 3
+    var enableLogging: Boolean = false
+}
+
+fun configureNetwork(block: NetworkConfig.() -> Unit): NetworkConfig =
+    NetworkConfig().apply(block)
+
+// Usage
+val config = configureNetwork {
+    baseUrl = "https://api.example.com"
+    timeoutMs = 60_000
+    enableLogging = BuildConfig.DEBUG
+}
+```
+
+---
+
+## DSL in Gradle (Convention Plugins)
+
+```kotlin
+// ✅ Expose DSL-style API in convention plugins
+fun Project.androidLibrary(block: LibraryExtension.() -> Unit) {
+    extensions.configure(LibraryExtension::class.java, block)
+}
+
+// Usage in module build.gradle.kts
+androidLibrary {
+    compileSdk = 35
+    defaultConfig {
+        minSdk = 24
+    }
+}
+```
+
+---
+
+## When to Use DSL
+
+| Use DSL                                            | Don't Use DSL                       |
+| -------------------------------------------------- | ----------------------------------- |
+| Building complex objects with many optional fields | Simple data classes with few fields |
+| Hierarchical/nested configuration                  | One-level flat configuration        |
+| Domain has natural language structure              | Technical/algorithmic code          |
+| Builder would have 5+ parameters                   | Builder has 1-2 parameters          |
+
+---
+
+## Anti-Patterns
+
+- DSL without `@DslMarker` — allows accidental outer receiver access
+- Mutable state escaping the DSL scope — DSL output should be immutable
+- DSL that requires calling methods in a specific order — use phases/staged builders instead
+- Too many nested levels — more than 3 levels deep becomes unreadable
+- Side effects inside DSL blocks — DSL should declare, not execute
+
+---
+
+## Related Skills
+
+- `kotlin` — Kotlin language fundamentals
+- `extension-functions-design` — extension functions used in DSL design
+- `gradle` — Gradle Kotlin DSL conventions