android-sdd 1.0.0

package/skills/Core Language/Extension Functions Design/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: extension-functions-design
+description: >
+  Design principles and patterns for Kotlin extension functions in Android.
+  Load this skill when deciding whether to use an extension function,
+  where to place it, how to scope it, and how to avoid common misuse patterns.
+---
+
+# Extension Functions Design
+
+## Overview
+
+Extension functions add behavior to existing types without inheritance or modification. They are one of Kotlin's most powerful features but must be used with discipline — overuse leads to scattered, hard-to-discover code.
+
+---
+
+## Core Principles
+
+- Extensions are **discoverable utilities**, not replacements for proper design
+- Only extend types **you don't own** or when inheritance is impossible
+- If you own the type, **add the method directly** — don't use an extension
+- Extensions must be **stateless and pure** — no side effects, no hidden dependencies
+- Place extensions **close to where they're used** — not in a global utils file
+
+---
+
+## When to Use Extension Functions
+
+| Situation                                                        | Use Extension?                     |
+| ---------------------------------------------------------------- | ---------------------------------- |
+| Adding utility to stdlib types (`String`, `List`, `Int`)         | ✅ Yes                              |
+| Adding Android-specific helpers to `Context`, `View`, `Fragment` | ✅ Yes                              |
+| Adding behavior to a class you own                               | ❌ No — add method directly         |
+| Replacing a utility class method                                 | ✅ Yes                              |
+| Adding domain logic to a domain model                            | ❌ No — add to the class or UseCase |
+| Bypassing encapsulation to access internals                      | ❌ Never                            |
+
+---
+
+## Placement Strategy
+
+```
+// ✅ Place extensions next to the type they extend
+// If extending Context → ContextExtensions.kt
+// If extending String → StringExtensions.kt
+// If extending View  → ViewExtensions.kt
+
+// ✅ Place feature-specific extensions inside the feature package
+// feature/auth/AuthExtensions.kt — extensions only used in auth
+// NOT in a global utils/Extensions.kt that grows forever
+```
+
+---
+
+## Stdlib Extensions
+
+```kotlin
+// ✅ String utilities
+fun String.toSlug(): String =
+    lowercase().replace(" ", "-").replace(Regex("[^a-z0-9-]"), "")
+
+fun String.isValidEmail(): Boolean =
+    android.util.Patterns.EMAIL_ADDRESS.matcher(this).matches()
+
+fun String?.orEmpty(): String = this ?: ""
+
+// ✅ Number formatting
+fun Int.toPx(context: Context): Int =
+    (this * context.resources.displayMetrics.density).toInt()
+
+fun Long.toFormattedDate(): String =
+    SimpleDateFormat("yyyy-MM-dd", Locale.getDefault()).format(Date(this))
+
+// ✅ Collection utilities
+fun <T> List<T>.second(): T = this[1]
+fun <T> List<T>.indexOfFirstOrNull(predicate: (T) -> Boolean): Int? =
+    indexOfFirst(predicate).takeIf { it >= 0 }
+```
+
+---
+
+## Android Platform Extensions
+
+```kotlin
+// ✅ Context extensions
+fun Context.showToast(message: String, duration: Int = Toast.LENGTH_SHORT) {
+    Toast.makeText(this, message, duration).show()
+}
+
+fun Context.getColorCompat(@ColorRes colorRes: Int): Int =
+    ContextCompat.getColor(this, colorRes)
+
+fun Context.dpToPx(dp: Float): Int =
+    TypedValue.applyDimension(TypedValue.COMPLEX_UNIT_DIP, dp, resources.displayMetrics).toInt()
+
+// ✅ View extensions
+fun View.show() { visibility = View.VISIBLE }
+fun View.hide() { visibility = View.GONE }
+fun View.invisible() { visibility = View.INVISIBLE }
+
+fun View.setOnSingleClickListener(action: () -> Unit) {
+    var lastClickTime = 0L
+    setOnClickListener {
+        val now = System.currentTimeMillis()
+        if (now - lastClickTime > 500) {
+            lastClickTime = now
+            action()
+        }
+    }
+}
+
+// ✅ Fragment extensions
+fun Fragment.hideKeyboard() {
+    val imm = requireContext().getSystemService(InputMethodManager::class.java)
+    imm.hideSoftInputFromWindow(requireView().windowToken, 0)
+}
+```
+
+---
+
+## Flow / Coroutine Extensions
+
+```kotlin
+// ✅ Lifecycle-aware collection helper
+fun <T> Flow<T>.collectWithLifecycle(
+    lifecycleOwner: LifecycleOwner,
+    state: Lifecycle.State = Lifecycle.State.STARTED,
+    block: suspend (T) -> Unit
+) {
+    lifecycleOwner.lifecycleScope.launch {
+        lifecycleOwner.repeatOnLifecycle(state) {
+            collect { block(it) }
+        }
+    }
+}
+
+// ✅ Result extensions
+fun <T> Result<T>.onSuccess(action: (T) -> Unit): Result<T> {
+    if (isSuccess) action(getOrThrow())
+    return this
+}
+```
+
+---
+
+## Scoping with Companion Objects
+
+```kotlin
+// ✅ Scope extension to a specific context using companion object
+class UserValidator {
+    companion object  // empty companion — allows scoped extensions
+}
+
+fun UserValidator.Companion.isValidAge(age: Int): Boolean = age in 18..120
+
+// Usage
+UserValidator.isValidAge(25)
+```
+
+---
+
+## Anti-Patterns
+
+```kotlin
+// ❌ Extending a class you own — add the method directly
+class User(val name: String)
+fun User.displayName() = name.trim()  // wrong — add to User class
+
+// ❌ Extension that accesses internal state via reflection or casting
+fun Any.forceGetField(name: String): Any? { ... }  // bypasses encapsulation
+
+// ❌ Extension with hidden dependencies
+fun String.sendToAnalytics() {
+    AnalyticsSingleton.track(this)  // hidden side effect — not obvious from signature
+}
+
+// ❌ Giant global Extensions.kt file
+// utils/Extensions.kt with 500 lines of unrelated extensions
+// → split by type and feature
+
+// ❌ Extension that duplicates stdlib
+fun List<Int>.mySum() = reduce { acc, i -> acc + i }  // use sum() instead
+```
+
+---
+
+## Related Skills
+
+- `kotlin` — core Kotlin language conventions
+- `dsl` — extension functions as DSL building blocks
+- `reactive-streams` — Flow extension patterns

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

@@ -0,0 +1,156 @@
+---
+name: immutability
+description: >
+  Immutability patterns and enforcement for Android/Kotlin development.
+  Load this skill when designing data models, state classes, collections,
+  or any shared data structure to ensure thread safety and predictable behavior.
+---
+
+# Immutability
+
+## Overview
+
+Immutability means that once an object is created, its state cannot change. In Android development, immutability is critical for thread safety, predictable UI state, and preventing hard-to-debug side effects.
+
+---
+
+## Core Principles
+
+- Default to `val` — only use `var` when mutation is genuinely required
+- Default to immutable collections — only use mutable when building
+- State should flow in one direction — never mutate state from outside
+- Shared data across threads must always be immutable
+
+---
+
+## Properties
+
+```kotlin
+// ✅ val by default
+data class User(val id: String, val name: String, val email: String)
+
+// ✅ var only when genuinely needed (e.g., local accumulator)
+var count = 0
+repeat(10) { count++ }
+
+// ❌ var on a data class field shared across layers
+data class User(var name: String)  // mutability leaks outside
+```
+
+---
+
+## Data Classes and copy()
+
+```kotlin
+// ✅ Use copy() to produce new state — never mutate
+data class UiState(
+    val isLoading: Boolean = false,
+    val items: List<Item> = emptyList(),
+    val error: String? = null
+)
+
+// In ViewModel
+_uiState.update { it.copy(isLoading = true) }
+_uiState.update { it.copy(isLoading = false, items = newItems) }
+
+// ❌ Never do this
+_uiState.value.items = newItems  // not possible with val, but don't expose mutable state
+```
+
+---
+
+## Collections
+
+```kotlin
+// ✅ Expose immutable collections from all public APIs
+class UserRepository {
+    fun getUsers(): List<User> = _users.toList()  // defensive copy
+}
+
+// ✅ Build with mutable, expose as immutable
+val users: List<User> = buildList {
+    add(User("1", "Ali"))
+    add(User("2", "Sara"))
+}
+
+// ✅ StateFlow always holds immutable state
+private val _uiState = MutableStateFlow(UiState())
+val uiState: StateFlow<UiState> = _uiState.asStateFlow()
+
+// ❌ Never expose MutableStateFlow or MutableList
+val uiState = MutableStateFlow(UiState())  // external code can modify
+```
+
+---
+
+## Immutable State in ViewModel
+
+```kotlin
+// ✅ Correct pattern — immutable state, controlled updates
+class UserViewModel : ViewModel() {
+
+    private val _state = MutableStateFlow(UserUiState())
+    val state: StateFlow<UserUiState> = _state.asStateFlow()
+
+    fun onNameChanged(name: String) {
+        _state.update { it.copy(name = name) }
+    }
+}
+
+// ✅ State class — all vals
+data class UserUiState(
+    val name: String = "",
+    val isLoading: Boolean = false,
+    val error: String? = null
+)
+```
+
+---
+
+## Immutability Across Layers
+
+| Layer                   | Rule                                             |
+| ----------------------- | ------------------------------------------------ |
+| Domain models           | Always immutable (`data class` with `val`)       |
+| DTOs                    | Always immutable (`data class` with `val`)       |
+| UI State                | Always immutable — update via `copy()`           |
+| Repository return types | Return `List<T>` not `MutableList<T>`            |
+| Exposed flows           | Always `StateFlow`/`Flow` not `MutableStateFlow` |
+
+---
+
+## Thread Safety Through Immutability
+
+```kotlin
+// ✅ Immutable objects are safe to share across coroutines
+data class Config(val baseUrl: String, val timeout: Long)
+
+// Safe — no synchronization needed
+val config = Config("https://api.example.com", 30_000)
+launch(Dispatchers.IO) { fetchData(config) }
+launch(Dispatchers.Default) { processData(config) }
+
+// ❌ Mutable shared state requires synchronization
+class Config {
+    var baseUrl: String = ""  // race condition if accessed from multiple threads
+}
+```
+
+---
+
+## Anti-Patterns
+
+- `var` properties on domain models or state classes
+- Exposing `MutableList`, `MutableMap`, or `MutableStateFlow` from public APIs
+- Mutating a list after exposing it — always return a defensive copy
+- Using `apply {}` to mutate an object after it's been shared
+- Casting `List<T>` to `MutableList<T>` — breaks immutability contract
+
+---
+
+## Related Skills
+
+- `kotlin` — `val`/`var` and data class conventions
+- `state-management` — UI state modeling with immutable data
+- `coroutine` — thread safety with immutable shared state
+- `repository-pattern` — immutable return types from repositories

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

@@ -0,0 +1,182 @@
+---
+name: kmp
+description: >
+  Kotlin Multiplatform (KMP) setup, structure, and best practices.
+  Load this skill when setting up a KMP project, sharing code between
+  Android and other platforms, or deciding what belongs in shared vs
+  platform-specific modules.
+---
+
+# Kotlin Multiplatform (KMP)
+
+## Overview
+
+KMP allows sharing Kotlin code across platforms (Android, iOS, Desktop, Web) while keeping platform-specific implementations separate. The goal is to maximize shared logic while respecting platform boundaries.
+
+---
+
+## Core Principles
+
+- Share **business logic** — not UI, not platform APIs
+- Use `expect/actual` only when necessary — prefer interface + DI
+- Keep shared code free of any platform dependency
+- The `commonMain` module must never import Android or iOS specific APIs
+
+---
+
+## Module Structure
+
+```
+project/
+├── shared/
+│   ├── src/
+│   │   ├── commonMain/kotlin/     ← shared business logic
+│   │   ├── commonTest/kotlin/     ← shared unit tests
+│   │   ├── androidMain/kotlin/    ← Android actual implementations
+│   │   └── iosMain/kotlin/        ← iOS actual implementations
+├── androidApp/                    ← Android UI & entry point
+└── iosApp/                        ← iOS UI & entry point
+```
+
+---
+
+## What Goes Where
+
+| Layer                      | commonMain | androidMain / iosMain |
+| -------------------------- | ---------- | --------------------- |
+| Domain models              | ✅          | ❌                     |
+| Use cases                  | ✅          | ❌                     |
+| Repository interfaces      | ✅          | ❌                     |
+| Repository implementations | ❌          | ✅                     |
+| Network (Ktor)             | ✅          | ❌                     |
+| Database (SQLDelight)      | ✅ schema   | ✅ driver              |
+| UI                         | ❌          | ✅                     |
+| Platform APIs              | ❌          | ✅                     |
+
+---
+
+## expect / actual Pattern
+
+### Prefer interface + DI over expect/actual
+
+```kotlin
+// ✅ Preferred — interface in commonMain, implementation injected
+interface PlatformLogger {
+    fun log(message: String)
+}
+
+// androidMain
+class AndroidLogger : PlatformLogger {
+    override fun log(message: String) = Log.d("App", message)
+}
+```
+
+### Use expect/actual only for simple platform utilities
+
+```kotlin
+// commonMain
+expect fun getCurrentTimeMillis(): Long
+
+// androidMain
+actual fun getCurrentTimeMillis(): Long = System.currentTimeMillis()
+
+// iosMain
+actual fun getCurrentTimeMillis(): Long =
+    NSDate().timeIntervalSince1970.toLong() * 1000
+```
+
+---
+
+## Networking — Ktor (shared)
+
+```kotlin
+// commonMain — use Ktor, not Retrofit (Retrofit is Android-only)
+val client = HttpClient {
+    install(ContentNegotiation) {
+        json(Json { ignoreUnknownKeys = true })
+    }
+    install(HttpTimeout) {
+        requestTimeoutMillis = 30_000
+    }
+}
+```
+
+## Database — SQLDelight (shared schema)
+
+```kotlin
+// commonMain — define schema in .sq files
+// androidMain — provide AndroidSqliteDriver
+// iosMain    — provide NativeSqliteDriver
+```
+
+---
+
+## Coroutines in KMP
+
+```kotlin
+// ✅ Use kotlinx.coroutines in commonMain
+// ✅ Use Dispatchers.Default for CPU work in common code
+// ✅ Use platform dispatcher injection for UI thread
+
+// androidMain
+val uiDispatcher: CoroutineDispatcher = Dispatchers.Main
+
+// iosMain
+val uiDispatcher: CoroutineDispatcher = Dispatchers.Main
+```
+
+---
+
+## Gradle Setup (libs.versions.toml)
+
+```toml
+[versions]
+kotlin = "2.0.0"
+kmp = "2.0.0"
+
+[plugins]
+kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
+```
+
+```kotlin
+// shared/build.gradle.kts
+kotlin {
+    androidTarget()
+    iosX64()
+    iosArm64()
+    iosSimulatorArm64()
+
+    sourceSets {
+        commonMain.dependencies {
+            implementation(libs.ktor.client.core)
+            implementation(libs.kotlinx.coroutines.core)
+            implementation(libs.kotlinx.serialization.json)
+        }
+        androidMain.dependencies {
+            implementation(libs.ktor.client.okhttp)
+        }
+        iosMain.dependencies {
+            implementation(libs.ktor.client.darwin)
+        }
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Importing `android.*` in `commonMain` — breaks iOS compilation
+- Using Retrofit in shared code — it's Android-only; use Ktor
+- Putting UI logic in `commonMain` — UI must stay platform-specific
+- Overusing `expect/actual` — prefer interface + DI for testability
+- Sharing ViewModels in commonMain — keep ViewModels platform-specific
+
+---
+
+## Related Skills
+
+- `kotlin` — Kotlin language conventions
+- `coroutine` — coroutine patterns in shared and platform code
+- `serialization` — Kotlinx Serialization setup for KMP
+- `ktor` — Ktor client setup and usage

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

@@ -0,0 +1,187 @@
+---
+name: kotlin
+description: >
+  Kotlin language conventions and best practices for Android development.
+  Load this skill whenever writing, reviewing, or refactoring any Kotlin code.
+  Covers idioms, language features, and patterns that should be consistently
+  applied across the entire codebase.
+---
+
+# Kotlin
+
+## Overview
+
+Kotlin is the primary language for Android development. This skill defines which language features to use, when to use them, and which patterns to avoid.
+
+---
+
+## Core Principles
+
+- Prefer **idiomatic Kotlin** over Java-style code
+- Prefer **immutability** by default (`val` over `var`, `data class`, `copy()`)
+- Prefer **null safety** at compile time — minimize nullable types
+- Prefer **expression over statement** where it improves readability
+- Never use `!!` — always handle nullability explicitly
+
+---
+
+## Language Features
+
+### Null Safety
+
+```kotlin
+// ✅ Use safe call + elvis
+val name = user?.name ?: "Unknown"
+
+// ✅ Use let for nullable execution
+user?.let { sendEmail(it) }
+
+// ❌ Never force-unwrap
+val name = user!!.name
+```
+
+### Data Classes
+
+```kotlin
+// ✅ Use data class for value holders
+data class User(val id: String, val name: String)
+
+// ✅ Use copy() for mutation
+val updated = user.copy(name = "Ali")
+
+// ❌ Never mutate fields directly
+user.name = "Ali"
+```
+
+### Sealed Classes
+
+```kotlin
+// ✅ Use sealed class for exhaustive state modeling
+sealed class Result<out T> {
+    data class Success<T>(val data: T) : Result<T>()
+    data class Error(val exception: Throwable) : Result<Nothing>()
+    object Loading : Result<Nothing>()
+}
+
+// ✅ Always use when exhaustively — no else branch
+when (result) {
+    is Result.Success -> showData(result.data)
+    is Result.Error   -> showError(result.exception)
+    is Result.Loading -> showLoading()
+}
+```
+
+### Extension Functions
+
+```kotlin
+// ✅ Use for adding behavior to existing types without inheritance
+fun String.toFormattedDate(): String { ... }
+
+// ✅ Use for scoping utility functions to a receiver
+fun Context.showToast(message: String) {
+    Toast.makeText(this, message, Toast.LENGTH_SHORT).show()
+}
+
+// ❌ Don't use extension functions to bypass encapsulation
+// ❌ Don't define extensions on types you own — add the method directly
+```
+
+### Scope Functions
+
+```kotlin
+// ✅ let  — nullable transformation or scoped execution
+val length = text?.let { it.trim().length }
+
+// ✅ apply — object configuration / builder pattern
+val intent = Intent().apply {
+    putExtra("key", value)
+    flags = Intent.FLAG_ACTIVITY_NEW_TASK
+}
+
+// ✅ run   — transformation on receiver
+val result = user.run { "$name ($email)" }
+
+// ✅ also  — side effects (logging, debugging)
+val user = createUser().also { log("User created: $it") }
+
+// ❌ Don't nest scope functions more than 2 levels deep
+// ❌ Don't use scope functions just for style — only when they add clarity
+```
+
+### When Expression
+
+```kotlin
+// ✅ Use when as an expression
+val label = when (status) {
+    Status.ACTIVE   -> "Active"
+    Status.INACTIVE -> "Inactive"
+    Status.PENDING  -> "Pending"
+}
+
+// ✅ Always exhaustive — avoid else on sealed/enum
+// ❌ Don't use else on sealed class when — it hides new state cases
+```
+
+### Inline Classes / Value Classes
+
+```kotlin
+// ✅ Use to add type safety to primitives
+@JvmInline
+value class UserId(val value: String)
+
+@JvmInline
+value class Email(val value: String)
+
+// Prevents mixing up primitive parameters
+fun findUser(id: UserId, email: Email) { ... }
+```
+
+### Collections
+
+```kotlin
+// ✅ Use immutable collections by default
+val items: List<String> = listOf("a", "b", "c")
+val map: Map<String, Int> = mapOf("a" to 1)
+
+// ✅ Use mutableListOf() only when mutation is required
+val buffer = mutableListOf<String>()
+
+// ✅ Prefer functional operators
+val names = users.filter { it.isActive }.map { it.name }
+
+// ❌ Don't use Java stream API — use Kotlin collections API
+```
+
+---
+
+## Naming Conventions
+
+| Element  | Convention                 | Example                    |
+| -------- | -------------------------- | -------------------------- |
+| Class    | PascalCase                 | `UserRepository`           |
+| Function | camelCase                  | `getUserById()`            |
+| Property | camelCase                  | `userName`                 |
+| Constant | SCREAMING_SNAKE            | `MAX_RETRY_COUNT`          |
+| Package  | lowercase                  | `com.example.feature.auth` |
+| File     | PascalCase (matches class) | `UserRepository.kt`        |
+
+---
+
+## Anti-Patterns
+
+- `!!` — use safe calls and elvis instead
+- `lateinit var` on types that could be `val` — redesign initialization
+- `object` for classes that hold state — use class with DI instead
+- Returning `null` to signal error — use `Result<T>` or sealed class
+- Java-style getters/setters — use Kotlin properties
+- `companion object` holding mutable state — use DI or top-level properties
+- Catching `Exception` broadly — catch specific exception types
+
+---
+
+## Related Skills
+
+- `coroutine` — async/concurrency patterns
+- `extension-functions-design` — detailed extension function guidelines
+- `immutability` — immutability policy across layers
+- `serialization` — Kotlin serialization setup and usage