android-sdd 1.0.0

package/skills/Core Language/Reactive State Management/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: reactive-state-management
+description: >
+  Reactive state management patterns for Android using StateFlow and Flow.
+  Load this skill when designing how state is produced, transformed, and
+  consumed across ViewModel and UI layers in a reactive, observable way.
+---
+
+# Reactive State Management
+
+## Overview
+
+Reactive State Management means that UI state is modeled as an observable stream. The UI never pulls state — it reacts to state emissions. State is always immutable, flows in one direction, and is the single source of truth for what the UI renders.
+
+---
+
+## Core Principles
+
+- State is **immutable** — never mutate, always replace via `copy()`
+- State flows **one direction** — ViewModel → UI, never reverse
+- UI **observes** state — never reads it on demand
+- There is **one state object** per screen — not multiple separate fields
+- State is **complete** — the UI can render correctly from state alone
+
+---
+
+## State Modeling
+
+```kotlin
+// ✅ Single sealed state per screen
+data class UserListUiState(
+    val users: List<User> = emptyList(),
+    val isLoading: Boolean = false,
+    val error: String? = null,
+    val isEmpty: Boolean = false
+)
+
+// ✅ Use sealed class for mutually exclusive states
+sealed class ScreenState<out T> {
+    object Loading : ScreenState<Nothing>()
+    data class Success<T>(val data: T) : ScreenState<T>()
+    data class Error(val message: String) : ScreenState<Nothing>()
+}
+```
+
+---
+
+## ViewModel — Producing State
+
+```kotlin
+class UserListViewModel(
+    private val getUsersUseCase: GetUsersUseCase
+) : ViewModel() {
+
+    // ✅ Private mutable — public immutable
+    private val _state = MutableStateFlow(UserListUiState())
+    val state: StateFlow<UserListUiState> = _state.asStateFlow()
+
+    // ✅ One-off events via SharedFlow
+    private val _events = MutableSharedFlow<UserListEvent>()
+    val events: SharedFlow<UserListEvent> = _events.asSharedFlow()
+
+    init {
+        loadUsers()
+    }
+
+    fun loadUsers() {
+        viewModelScope.launch {
+            _state.update { it.copy(isLoading = true, error = null) }
+            getUsersUseCase()
+                .onSuccess { users ->
+                    _state.update {
+                        it.copy(
+                            isLoading = false,
+                            users = users,
+                            isEmpty = users.isEmpty()
+                        )
+                    }
+                }
+                .onFailure { error ->
+                    _state.update {
+                        it.copy(isLoading = false, error = error.message)
+                    }
+                }
+        }
+    }
+
+    fun onUserClicked(userId: String) {
+        viewModelScope.launch {
+            _events.emit(UserListEvent.NavigateToDetail(userId))
+        }
+    }
+}
+
+// ✅ Events for one-time side effects
+sealed class UserListEvent {
+    data class NavigateToDetail(val userId: String) : UserListEvent()
+    data class ShowSnackbar(val message: String) : UserListEvent()
+}
+```
+
+---
+
+## Deriving State from Flow
+
+```kotlin
+// ✅ stateIn — derive StateFlow from upstream Flow
+class UserListViewModel(repository: UserRepository) : ViewModel() {
+
+    val state: StateFlow<UserListUiState> = repository
+        .observeUsers()
+        .map { users ->
+            UserListUiState(
+                users = users,
+                isEmpty = users.isEmpty()
+            )
+        }
+        .stateIn(
+            scope = viewModelScope,
+            started = SharingStarted.WhileSubscribed(5_000),
+            initialValue = UserListUiState(isLoading = true)
+        )
+}
+```
+
+---
+
+## Combining Multiple Sources
+
+```kotlin
+// ✅ combine — merge multiple streams into one state
+class DashboardViewModel(
+    userRepository: UserRepository,
+    settingsRepository: SettingsRepository
+) : ViewModel() {
+
+    val state: StateFlow<DashboardUiState> = combine(
+        userRepository.observeCurrentUser(),
+        settingsRepository.observeSettings()
+    ) { user, settings ->
+        DashboardUiState(
+            userName = user.name,
+            isDarkMode = settings.isDarkMode
+        )
+    }.stateIn(
+        scope = viewModelScope,
+        started = SharingStarted.WhileSubscribed(5_000),
+        initialValue = DashboardUiState()
+    )
+}
+```
+
+---
+
+## UI — Consuming State
+
+```kotlin
+// ✅ Compose — collect state
+@Composable
+fun UserListScreen(viewModel: UserListViewModel = hiltViewModel()) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+
+    // ✅ Collect one-time events
+    val lifecycleOwner = LocalLifecycleOwner.current
+    LaunchedEffect(Unit) {
+        viewModel.events
+            .flowWithLifecycle(lifecycleOwner.lifecycle)
+            .collect { event ->
+                when (event) {
+                    is UserListEvent.NavigateToDetail -> navController.navigate(...)
+                    is UserListEvent.ShowSnackbar -> snackbarHostState.showSnackbar(...)
+                }
+            }
+    }
+
+    UserListContent(state = state, onUserClick = viewModel::onUserClicked)
+}
+
+// ✅ Fragment — collect with repeatOnLifecycle
+viewLifecycleOwner.lifecycleScope.launch {
+    repeatOnLifecycle(Lifecycle.State.STARTED) {
+        viewModel.state.collect { state ->
+            renderState(state)
+        }
+    }
+}
+```
+
+---
+
+## State vs Events
+
+| Type      | Use for                                    | Implementation |
+| --------- | ------------------------------------------ | -------------- |
+| **State** | Persistent UI data (list, loading, error)  | `StateFlow`    |
+| **Event** | One-time actions (navigate, toast, dialog) | `SharedFlow`   |
+
+```kotlin
+// ✅ State — persists, survives recomposition
+val isLoading: StateFlow<Boolean>
+
+// ✅ Event — fires once, not replayed
+val navigationEvent: SharedFlow<NavigationEvent>
+
+// ❌ Don't model navigation in state — it replays on rotation
+data class UiState(val navigateTo: String?)  // wrong
+```
+
+---
+
+## Anti-Patterns
+
+- Multiple separate `StateFlow` fields per screen — use one state object
+- Exposing `MutableStateFlow` from ViewModel — always expose as `StateFlow`
+- Collecting state with `lifecycleScope.launch {}` without `repeatOnLifecycle` — leaks in background
+- Modeling one-time events as state — use `SharedFlow` for events
+- Calling `stateFlow.value` in UI to read state imperatively — always collect reactively
+- Triggering side effects inside `map {}` or `combine {}` — use `onEach` or handle in ViewModel
+
+---
+
+## Related Skills
+
+- `stateflow` — StateFlow internals and patterns
+- `sharedflow` — SharedFlow for one-time events
+- `reactive-streams` — Flow operators and transformation
+- `mvvm` — ViewModel and state ownership
+- `side-effect-management` — handling side effects in reactive pipelines

package/skills/Core Language/Reactive Streams/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: reactive-streams
+description: >
+  Reactive Streams patterns and operators for Android development.
+  Load this skill when working with data streams, chaining async operations,
+  transforming flows, combining multiple sources, or designing reactive pipelines
+  across layers.
+---
+
+# Reactive Streams
+
+## Overview
+
+Reactive Streams is a standard for asynchronous stream processing with non-blocking backpressure. In Kotlin/Android, this is implemented via `Flow`. This skill covers how to design, transform, and consume reactive streams correctly across all layers.
+
+---
+
+## Core Principles
+
+- Data flows **downward** — from data source to UI, never upward
+- Streams are **cold by default** (`Flow`) — only active when collected
+- **Never collect a Flow inside another Flow** — use operators instead
+- **Never expose `MutableStateFlow` or `MutableSharedFlow`** from public APIs
+- Transformation happens in the **middle layers** — not in UI, not in data source
+
+---
+
+## Flow Basics
+
+```kotlin
+// ✅ Cold flow — executes only when collected
+fun getUsers(): Flow<List<User>> = flow {
+    while (true) {
+        emit(repository.fetchUsers())
+        delay(30_000)
+    }
+}
+
+// ✅ Flow from suspend function
+fun getUserById(id: String): Flow<User> = flow {
+    emit(repository.getUser(id))
+}
+
+// ✅ Flow from Room (already returns Flow)
+@Query("SELECT * FROM users")
+fun observeUsers(): Flow<List<UserEntity>>
+```
+
+---
+
+## Key Operators
+
+### Transformation
+
+```kotlin
+// map — transform each emission
+val names: Flow<List<String>> = usersFlow.map { users ->
+    users.map { it.name }
+}
+
+// flatMapLatest — switch to new flow on each emission (search, user selection)
+val results: Flow<List<Result>> = queryFlow.flatMapLatest { query ->
+    repository.search(query)
+}
+
+// transform — emit multiple values per input
+val events: Flow<Event> = actionsFlow.transform { action ->
+    emit(Event.Started)
+    process(action)
+    emit(Event.Completed)
+}
+```
+
+### Filtering
+
+```kotlin
+// filter — conditional emission
+val activeUsers = usersFlow.filter { it.isActive }
+
+// distinctUntilChanged — suppress duplicate emissions
+val query = searchFlow.distinctUntilChanged()
+
+// debounce — wait for silence (search input)
+val debouncedQuery = searchFlow
+    .debounce(300)
+    .distinctUntilChanged()
+```
+
+### Combination
+
+```kotlin
+// combine — latest from each source
+val uiState: Flow<UiState> = combine(
+    usersFlow,
+    isLoadingFlow,
+    errorFlow
+) { users, isLoading, error ->
+    UiState(users = users, isLoading = isLoading, error = error)
+}
+
+// zip — pair emissions one-to-one
+val paired: Flow<Pair<A, B>> = flowA.zip(flowB) { a, b -> a to b }
+
+// merge — emit from all sources as they arrive
+val allEvents: Flow<Event> = merge(clickFlow, scrollFlow, keyboardFlow)
+```
+
+### Error Handling
+
+```kotlin
+// ✅ catch — handle errors without stopping the stream
+usersFlow
+    .catch { e -> emit(emptyList()) }
+    .collect { ... }
+
+// ✅ retry — retry on failure
+networkFlow
+    .retry(3) { e -> e is IOException }
+    .collect { ... }
+
+// ✅ retryWhen — conditional retry with backoff
+networkFlow
+    .retryWhen { cause, attempt ->
+        cause is IOException && attempt < 3
+    }
+```
+
+---
+
+## Flow Across Layers
+
+```kotlin
+// ✅ Repository — expose Flow from data source
+class UserRepository {
+    fun observeUsers(): Flow<List<User>> =
+        localDataSource.observeUsers().map { entities ->
+            entities.map { it.toDomain() }
+        }
+}
+
+// ✅ UseCase — transform and combine
+class GetActiveUsersUseCase(private val repository: UserRepository) {
+    operator fun invoke(): Flow<List<User>> =
+        repository.observeUsers()
+            .map { users -> users.filter { it.isActive } }
+            .distinctUntilChanged()
+}
+
+// ✅ ViewModel — collect into StateFlow
+class UserViewModel(useCase: GetActiveUsersUseCase) : ViewModel() {
+    val users: StateFlow<List<User>> = useCase()
+        .stateIn(
+            scope = viewModelScope,
+            started = SharingStarted.WhileSubscribed(5_000),
+            initialValue = emptyList()
+        )
+}
+
+// ✅ UI — collect with lifecycle awareness
+viewLifecycleOwner.lifecycleScope.launch {
+    repeatOnLifecycle(Lifecycle.State.STARTED) {
+        viewModel.users.collect { users ->
+            adapter.submitList(users)
+        }
+    }
+}
+```
+
+---
+
+## stateIn vs shareIn
+
+```kotlin
+// ✅ stateIn — convert Flow to StateFlow (single value, replays last)
+val state: StateFlow<T> = flow.stateIn(
+    scope = viewModelScope,
+    started = SharingStarted.WhileSubscribed(5_000),
+    initialValue = initialValue
+)
+
+// ✅ shareIn — convert Flow to SharedFlow (multicast, configurable replay)
+val shared: SharedFlow<T> = flow.shareIn(
+    scope = viewModelScope,
+    started = SharingStarted.WhileSubscribed(5_000),
+    replay = 1
+)
+
+// WhileSubscribed(5_000) — keeps upstream alive 5s after last subscriber
+// Lazy — starts only when first subscriber appears
+// Eagerly — starts immediately
+```
+
+---
+
+## Backpressure
+
+```kotlin
+// ✅ buffer — decouple producer from consumer
+fastProducerFlow
+    .buffer(capacity = 64)
+    .collect { slowConsumer(it) }
+
+// ✅ conflate — drop intermediate values, keep latest
+sensorFlow
+    .conflate()
+    .collect { render(it) }
+
+// ✅ collectLatest — cancel previous on new emission
+searchFlow.collectLatest { query ->
+    val results = repository.search(query)
+    showResults(results)
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Collecting Flow inside `viewModelScope.launch {}` directly in UI — use `repeatOnLifecycle`
+- Using `GlobalScope` to launch flow collection — always use scoped coroutines
+- Nested `collect` calls — use `flatMapLatest` or `combine` instead
+- Creating a new Flow on every recomposition in Compose — hoist to ViewModel
+- Using `flow.first()` in a loop — use operators instead
+- Ignoring backpressure on fast producers — use `buffer`, `conflate`, or `collectLatest`
+- Exposing `MutableSharedFlow` — always expose as `SharedFlow` or `Flow`
+
+---
+
+## Related Skills
+
+- `coroutine` — coroutine scope and dispatcher management
+- `stateflow` — StateFlow specific patterns
+- `sharedflow` — SharedFlow specific patterns
+- `state-management` — UI state with reactive streams
+- `repository-pattern` — exposing streams from data layer

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

@@ -0,0 +1,191 @@
+---
+name: serialization
+description: >
+  Kotlinx Serialization setup and usage for Android and KMP projects.
+  Load this skill when serializing/deserializing JSON or other formats,
+  configuring the Json instance, mapping API responses, or handling
+  custom serialization logic.
+---
+
+# Serialization
+
+## Overview
+
+Kotlinx Serialization is the standard serialization library for Kotlin/Android. It is compile-time safe, KMP-compatible, and integrates natively with Retrofit, Ktor, and DataStore.
+
+---
+
+## Core Principles
+
+- Use `@Serializable` on all data transfer objects (DTOs)
+- Never use Gson or Moshi — use Kotlinx Serialization
+- Configure a **single shared `Json` instance** per module — never create inline
+- Domain models must **not** be `@Serializable` — only DTOs
+- Use `@SerialName` when API field names differ from Kotlin naming conventions
+
+---
+
+## Setup
+
+```toml
+# libs.versions.toml
+[versions]
+kotlinx-serialization = "1.7.1"
+
+[libraries]
+kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinx-serialization" }
+
+[plugins]
+kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
+```
+
+```kotlin
+// build.gradle.kts
+plugins {
+    alias(libs.plugins.kotlin.serialization)
+}
+
+dependencies {
+    implementation(libs.kotlinx.serialization.json)
+}
+```
+
+---
+
+## Json Instance Configuration
+
+```kotlin
+// ✅ Single shared instance — define once, inject everywhere
+val json = Json {
+    ignoreUnknownKeys = true      // safe for API evolution
+    isLenient = false             // strict parsing by default
+    encodeDefaults = false        // don't serialize default values
+    prettyPrint = false           // compact output in production
+    coerceInputValues = true      // handle null → default for non-nullable
+}
+```
+
+---
+
+## DTO Design
+
+```kotlin
+// ✅ DTOs are @Serializable — domain models are not
+@Serializable
+data class UserDto(
+    @SerialName("user_id") val id: String,
+    @SerialName("full_name") val name: String,
+    @SerialName("email_address") val email: String,
+    @SerialName("is_active") val isActive: Boolean = true,
+    @SerialName("created_at") val createdAt: Long? = null
+)
+
+// ✅ Domain model — clean, no serialization annotations
+data class User(
+    val id: String,
+    val name: String,
+    val email: String,
+    val isActive: Boolean,
+    val createdAt: Long?
+)
+```
+
+---
+
+## Custom Serializers
+
+```kotlin
+// ✅ Use custom serializer for types that can't be annotated
+object UUIDSerializer : KSerializer<UUID> {
+    override val descriptor = PrimitiveSerialDescriptor("UUID", PrimitiveKind.STRING)
+    override fun serialize(encoder: Encoder, value: UUID) = encoder.encodeString(value.toString())
+    override fun deserialize(decoder: Decoder): UUID = UUID.fromString(decoder.decodeString())
+}
+
+// Apply on property
+@Serializable
+data class OrderDto(
+    @Serializable(with = UUIDSerializer::class)
+    val id: UUID
+)
+```
+
+---
+
+## Sealed Class Serialization
+
+```kotlin
+// ✅ Use @JsonClassDiscriminator for polymorphic types
+@Serializable
+@JsonClassDiscriminator("type")
+sealed class EventDto {
+    @Serializable
+    @SerialName("click")
+    data class Click(val x: Int, val y: Int) : EventDto()
+
+    @Serializable
+    @SerialName("scroll")
+    data class Scroll(val delta: Int) : EventDto()
+}
+```
+
+---
+
+## Integration with Retrofit
+
+```kotlin
+// ✅ Use kotlinx-serialization converter — not Gson
+dependencies {
+    implementation(libs.retrofit.kotlinx.serialization)
+}
+
+val retrofit = Retrofit.Builder()
+    .baseUrl(baseUrl)
+    .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))
+    .build()
+```
+
+## Integration with Ktor
+
+```kotlin
+// ✅ Use ContentNegotiation plugin
+install(ContentNegotiation) {
+    json(json) // pass the shared Json instance
+}
+```
+
+---
+
+## Handling Unknown/Dynamic Fields
+
+```kotlin
+// ✅ Use JsonObject for truly dynamic content
+@Serializable
+data class WebhookDto(
+    val event: String,
+    val payload: JsonObject  // dynamic structure
+)
+
+// Extract typed value from JsonObject
+val userId = webhook.payload["user_id"]?.jsonPrimitive?.content
+```
+
+---
+
+## Anti-Patterns
+
+- Using Gson or Moshi — not KMP-compatible, less type-safe
+- `@Serializable` on domain models — couples domain to transport layer
+- Creating `Json {}` inline at call site — inconsistent configuration
+- Missing `@SerialName` when API uses snake_case — breaks deserialization
+- Using `Any` or `Map<String, Any>` — loses type safety; use `JsonObject`
+- Ignoring `ignoreUnknownKeys = true` — crashes on API evolution
+
+---
+
+## Related Skills
+
+- `dto-mapping` — mapping between DTOs and domain models
+- `retrofit` — Retrofit setup with serialization converter
+- `ktor` — Ktor client setup with serialization plugin
+- `kmp` — shared serialization setup in multiplatform projects