android-sdd 1.0.0

package/skills/Concurrency/SharedFlow/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: sharedflow
+description: >
+  SharedFlow for hot event streams in Android with Kotlin coroutines.
+  Load this skill when broadcasting events to multiple collectors,
+  implementing one-time UI events (navigation, toasts, snackbars),
+  sharing a stream between multiple observers, or replacing LiveData events.
+---
+
+# SharedFlow
+
+## Overview
+
+`SharedFlow` is a hot Flow that broadcasts values to all active collectors. Unlike `StateFlow`, it has no initial value and does not replay the last value by default. It is the correct tool for one-time events (navigation, toasts) and shared event buses.
+
+---
+
+## Core Principles
+
+- Use `SharedFlow` for **events** — things that happen once and don't have a current value
+- Use `StateFlow` for **state** — things that have a current value that persists
+- Default `replay = 0` is correct for one-time events — never replay navigation events
+- Use `Channel` as an alternative for guaranteed delivery when the collector may not be active
+- `MutableSharedFlow` is the writable version — expose as `SharedFlow` to consumers
+
+---
+
+## Basic SharedFlow
+
+```kotlin
+// ✅ One-time event stream
+class UserViewModel : ViewModel() {
+
+    private val _events = MutableSharedFlow<UserEvent>()
+    val events: SharedFlow<UserEvent> = _events.asSharedFlow()
+
+    fun onDeleteSuccess() {
+        viewModelScope.launch {
+            _events.emit(UserEvent.NavigateBack)
+        }
+    }
+
+    fun onError(message: String) {
+        viewModelScope.launch {
+            _events.emit(UserEvent.ShowToast(message))
+        }
+    }
+}
+
+sealed interface UserEvent {
+    data object NavigateBack : UserEvent
+    data class ShowToast(val message: String) : UserEvent
+}
+```
+
+---
+
+## Collecting SharedFlow in Compose
+
+```kotlin
+// ✅ Collect one-time events in LaunchedEffect
+@Composable
+fun UserScreen(
+    onNavigateBack: () -> Unit,
+    viewModel: UserViewModel = hiltViewModel()
+) {
+    val context = LocalContext.current
+
+    LaunchedEffect(Unit) {
+        viewModel.events.collect { event ->
+            when (event) {
+                is UserEvent.NavigateBack -> onNavigateBack()
+                is UserEvent.ShowToast   -> Toast.makeText(context, event.message, Toast.LENGTH_SHORT).show()
+            }
+        }
+    }
+}
+```
+
+---
+
+## Replay and Buffer Configuration
+
+```kotlin
+// ✅ replay = 0 — no replay, new collectors miss past events (correct for one-time events)
+val events = MutableSharedFlow<Event>(replay = 0)
+
+// ✅ replay = 1 — new collectors get the last event (use for "current status" broadcasts)
+val connectionStatus = MutableSharedFlow<ConnectionStatus>(replay = 1)
+
+// ✅ extraBufferCapacity — don't drop events when collectors are slow
+val events = MutableSharedFlow<Event>(
+    replay = 0,
+    extraBufferCapacity = 64,
+    onBufferOverflow = BufferOverflow.DROP_OLDEST
+)
+```
+
+---
+
+## Shared Event Bus
+
+```kotlin
+// ✅ App-wide event bus for cross-feature communication
+@Singleton
+class AppEventBus @Inject constructor() {
+
+    private val _events = MutableSharedFlow<AppEvent>(
+        extraBufferCapacity = 32,
+        onBufferOverflow = BufferOverflow.DROP_OLDEST
+    )
+    val events: SharedFlow<AppEvent> = _events.asSharedFlow()
+
+    suspend fun emit(event: AppEvent) {
+        _events.emit(event)
+    }
+}
+
+sealed interface AppEvent {
+    data object UserLoggedOut : AppEvent
+    data class PushNotificationReceived(val data: Map<String, String>) : AppEvent
+}
+```
+
+---
+
+## SharedFlow vs Channel vs StateFlow
+
+|                     | SharedFlow       | Channel                    | StateFlow  |
+| ------------------- | ---------------- | -------------------------- | ---------- |
+| Hot/Cold            | Hot              | Hot                        | Hot        |
+| Initial value       | No               | No                         | Yes        |
+| Replay              | Configurable     | No                         | Last value |
+| Multiple collectors | Yes              | No (one consumer)          | Yes        |
+| Delivery guarantee  | No (can miss)    | Yes (buffered)             | N/A        |
+| Use for             | Broadcast events | Guaranteed single delivery | UI state   |
+
+---
+
+## tryEmit vs emit
+
+```kotlin
+// ✅ emit — suspends if buffer is full (use in coroutines)
+viewModelScope.launch {
+    _events.emit(UserEvent.NavigateBack)
+}
+
+// ✅ tryEmit — returns false if buffer full (use outside coroutines)
+val sent = _events.tryEmit(UserEvent.NavigateBack)
+if (!sent) Timber.w("Event dropped — buffer full")
+```
+
+---
+
+## Anti-Patterns
+
+- Using `SharedFlow` with `replay = 1` for navigation events — navigates again on resubscription
+- Using `StateFlow` for one-time events — replays the event on recomposition
+- Not setting `extraBufferCapacity` for high-frequency events — events dropped silently
+- Collecting `SharedFlow` without lifecycle awareness in Android UI
+- Using an app-wide event bus for everything — creates hidden coupling between features
+
+---
+
+## Related Skills
+
+- `stateflow` — hot state holder with current value
+- `channel` — guaranteed single-consumer delivery
+- `flow` — cold stream fundamentals
+- `coroutine` — coroutine scopes for emitting events
+- `mvvm` — event pattern in ViewModel

package/skills/Concurrency/StateFlow/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: stateflow
+description: >
+  StateFlow for UI state management in Android with Kotlin coroutines.
+  Load this skill when holding and exposing UI state from a ViewModel,
+  converting cold flows to StateFlow, managing state updates safely,
+  or replacing LiveData with StateFlow.
+---
+
+# StateFlow
+
+## Overview
+`StateFlow` is a hot Flow that always holds a current value and replays it to new collectors. It is the standard replacement for `LiveData` in Kotlin-first Android development. ViewModels expose `StateFlow` for UI state, and Compose collects it with `collectAsStateWithLifecycle`.
+
+---
+
+## Core Principles
+
+- Every ViewModel exposes **one** `StateFlow<UiState>` per screen — not multiple separate flows
+- `MutableStateFlow` is private — expose as `StateFlow` to prevent external mutation
+- Update state atomically with `update {}` — never read-then-write separately
+- Use `stateIn` to convert a cold `Flow` from the repository into a `StateFlow`
+- `StateFlow` replays the current value — do not use it for one-time events
+
+---
+
+## Basic StateFlow
+
+```kotlin
+// ✅ Private mutable, public immutable
+class UserViewModel : ViewModel() {
+
+    private val _state = MutableStateFlow<UserUiState>(UserUiState.Loading)
+    val state: StateFlow<UserUiState> = _state.asStateFlow()
+
+    fun loadUser(id: String) {
+        viewModelScope.launch {
+            _state.value = UserUiState.Loading
+            repository.getUser(id).fold(
+                onSuccess = { _state.value = UserUiState.Success(it) },
+                onFailure = { _state.value = UserUiState.Error(it.message ?: "Error") }
+            )
+        }
+    }
+}
+```
+
+---
+
+## Atomic State Updates
+
+```kotlin
+// ✅ update {} — thread-safe atomic update
+private val _state = MutableStateFlow(UserListState())
+
+fun onSearchQueryChanged(query: String) {
+    _state.update { current ->
+        current.copy(searchQuery = query)
+    }
+}
+
+fun onUserDeleted(userId: String) {
+    _state.update { current ->
+        current.copy(users = current.users.filter { it.id != userId })
+    }
+}
+
+// ❌ Non-atomic — race condition possible
+_state.value = _state.value.copy(searchQuery = query)
+```
+
+---
+
+## stateIn — Convert Repository Flow to StateFlow
+
+```kotlin
+// ✅ Convert cold Flow from Room/repository to StateFlow
+class UserListViewModel @Inject constructor(
+    private val userRepository: UserRepository
+) : ViewModel() {
+
+    val state: StateFlow<UserListUiState> = userRepository
+        .getUsersFlow()
+        .map { users -> UserListUiState(users = users) }
+        .catch { emit(UserListUiState(error = it.message)) }
+        .stateIn(
+            scope = viewModelScope,
+            started = SharingStarted.WhileSubscribed(5_000),  // ✅ stop 5s after last collector
+            initialValue = UserListUiState(isLoading = true)
+        )
+}
+```
+
+---
+
+## SharingStarted Options
+
+```kotlin
+// ✅ WhileSubscribed(5_000) — recommended for UI state
+// Stops upstream 5s after last collector unsubscribes
+// Survives configuration changes (Activity recreated within 5s)
+.stateIn(
+    scope = viewModelScope,
+    started = SharingStarted.WhileSubscribed(5_000),
+    initialValue = initialState
+)
+
+// ✅ Eagerly — starts immediately, never stops
+// Use for state that must always be fresh
+.stateIn(scope = viewModelScope, started = SharingStarted.Eagerly, initialValue = initialState)
+
+// ✅ Lazily — starts on first collector, never stops
+.stateIn(scope = viewModelScope, started = SharingStarted.Lazily, initialValue = initialState)
+```
+
+---
+
+## Collecting in Compose
+
+```kotlin
+// ✅ collectAsStateWithLifecycle — stops collection when lifecycle is below STARTED
+@Composable
+fun UserListScreen(viewModel: UserListViewModel = hiltViewModel()) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+
+    when (state) {
+        is UserListUiState.Loading -> LoadingIndicator()
+        is UserListUiState.Success -> UserList(state.users)
+        is UserListUiState.Error   -> ErrorMessage(state.message)
+    }
+}
+
+// ❌ collectAsState — doesn't respect lifecycle
+val state by viewModel.state.collectAsState()
+```
+
+---
+
+## Derived State
+
+```kotlin
+// ✅ Derive secondary StateFlow from primary
+class UserListViewModel : ViewModel() {
+    private val _state = MutableStateFlow(UserListState())
+
+    val filteredUsers: StateFlow<List<User>> = _state
+        .map { state ->
+            state.users.filter { it.name.contains(state.searchQuery, ignoreCase = true) }
+        }
+        .stateIn(
+            scope = viewModelScope,
+            started = SharingStarted.WhileSubscribed(5_000),
+            initialValue = emptyList()
+        )
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Using `StateFlow` for one-time events (navigation, toasts) — replays on resubscription
+- Exposing `MutableStateFlow` publicly — external code can mutate state
+- Non-atomic state updates with `_state.value = _state.value.copy(...)` — race conditions
+- Using `SharingStarted.Eagerly` for all flows — keeps upstream alive unnecessarily
+- Multiple `StateFlow` properties for one screen — use one state data class
+
+---
+
+## Related Skills
+- `sharedflow` — for one-time events that must not replay
+- `flow` — cold stream fundamentals and operators
+- `mvvm` — ViewModel pattern using StateFlow
+- `mvi` — reducer pattern with StateFlow
+- `lifecycle` — lifecycle-aware collection

package/skills/Concurrency/Structured Concurrency/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: structured-concurrency
+description: >
+  Structured concurrency principles and patterns in Kotlin coroutines.
+  Load this skill when managing parent-child coroutine relationships,
+  understanding cancellation propagation, using coroutineScope vs
+  supervisorScope, or designing components with proper coroutine lifecycle.
+---
+
+# Structured Concurrency
+
+## Overview
+
+Structured concurrency ensures that coroutines have a defined lifetime tied to a scope. Every coroutine has a parent, and when the parent is cancelled, all children are cancelled. This prevents coroutine leaks and makes async code predictable and safe.
+
+---
+
+## Core Principles
+
+- Every coroutine has a **parent scope** — no orphan coroutines
+- Cancellation flows **downward** — parent cancelled → all children cancelled
+- Failure flows **upward** — child exception cancels the parent (unless `SupervisorJob`)
+- A scope does not complete until **all children complete**
+- Use `coroutineScope` for all-or-nothing operations, `supervisorScope` for independent children
+
+---
+
+## Parent-Child Relationship
+
+```
+CoroutineScope (viewModelScope)
+    └── Job (root)
+         ├── Coroutine A (launch)
+         │    └── Coroutine A1 (launch inside A)
+         └── Coroutine B (launch)
+
+Cancel viewModelScope → A, A1, B all cancelled
+Exception in B → cancels scope → A, A1 also cancelled (unless SupervisorJob)
+```
+
+---
+
+## coroutineScope vs supervisorScope
+
+```kotlin
+// ✅ coroutineScope — all children must succeed, any failure cancels all
+suspend fun loadRequiredData(): DashboardData = coroutineScope {
+    val user = async { userRepository.getUser() }    // required
+    val config = async { configRepository.get() }    // required
+
+    DashboardData(
+        user = user.await(),      // if either throws, both cancelled
+        config = config.await()
+    )
+}
+
+// ✅ supervisorScope — children are independent, one failure doesn't cancel others
+suspend fun loadOptionalData(): DashboardExtras = supervisorScope {
+    val recommendations = async { recommendationRepository.get() }  // optional
+    val ads = async { adsRepository.get() }                          // optional
+
+    DashboardExtras(
+        recommendations = runCatching { recommendations.await() }.getOrDefault(emptyList()),
+        ads = runCatching { ads.await() }.getOrDefault(emptyList())
+    )
+}
+```
+
+---
+
+## SupervisorJob in Custom Scopes
+
+```kotlin
+// ✅ SupervisorJob — child failures don't cancel the scope
+@Singleton
+class BackgroundSyncManager @Inject constructor() {
+
+    // SupervisorJob: one sync failure doesn't cancel all other syncs
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
+
+    fun syncUsers() {
+        scope.launch {
+            userRepository.sync()  // failure here won't cancel syncOrders
+        }
+    }
+
+    fun syncOrders() {
+        scope.launch {
+            orderRepository.sync()
+        }
+    }
+
+    fun cancel() {
+        scope.cancel()
+    }
+}
+
+// ✅ viewModelScope already uses SupervisorJob internally
+// Each launch{} in ViewModel is independent
+```
+
+---
+
+## Cancellation Propagation
+
+```kotlin
+// ✅ CancellationException must NOT be caught and swallowed
+suspend fun doWork() {
+    try {
+        delay(1_000)
+        fetchData()
+    } catch (e: CancellationException) {
+        throw e  // ✅ always rethrow CancellationException
+    } catch (e: Exception) {
+        handleError(e)
+    }
+}
+
+// ✅ runCatching re-throws CancellationException automatically
+val result = runCatching { fetchData() }  // safe — cancellation propagates correctly
+
+// ❌ Swallowing CancellationException — breaks structured concurrency
+try {
+    delay(1_000)
+} catch (e: Exception) {
+    // catches CancellationException too — coroutine won't cancel properly
+}
+```
+
+---
+
+## Scope Completion
+
+```kotlin
+// ✅ coroutineScope suspends until all children complete
+suspend fun processAll(items: List<Item>) = coroutineScope {
+    items.forEach { item ->
+        launch { processItem(item) }
+    }
+    // resumes here only when all launches have completed
+}
+
+// ✅ joinAll — wait for specific jobs
+suspend fun waitForAll() {
+    val jobs = listOf(
+        viewModelScope.launch { task1() },
+        viewModelScope.launch { task2() }
+    )
+    jobs.joinAll()  // suspends until both complete
+}
+```
+
+---
+
+## Scope in Non-Lifecycle Components
+
+```kotlin
+// ✅ Inject and cancel scope explicitly in non-ViewModel classes
+class DataSyncService @Inject constructor(
+    private val repository: DataRepository
+) {
+    private val job = SupervisorJob()
+    private val scope = CoroutineScope(job + Dispatchers.IO)
+
+    fun start() {
+        scope.launch {
+            while (isActive) {
+                repository.sync()
+                delay(60_000)
+            }
+        }
+    }
+
+    fun stop() {
+        job.cancel()  // cancels all children, scope is still reusable with new children
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- `GlobalScope.launch` — no parent, lives forever, can't be cancelled
+- Catching `CancellationException` without rethrowing — breaks cancellation
+- Creating a `CoroutineScope` without `SupervisorJob` in a manager class — one failure kills all tasks
+- Not calling `scope.cancel()` in `onCleared()` or equivalent — coroutine leak
+- Using `launch` inside `suspend fun` without a scope — use `coroutineScope {}` instead
+
+---
+
+## Related Skills
+
+- `coroutine` — coroutine fundamentals and dispatcher selection
+- `flow` — structured cancellation with flows
+- `lifecycle` — viewModelScope and lifecycleScope internals
+- `background-processing` — long-running work with structured scopes