android-sdd 1.0.0

package/skills/Architecture/MVI/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: mvi
+description: >
+  Model-View-Intent pattern for Android with Jetpack Compose.
+  Load this skill when implementing strict unidirectional data flow,
+  modeling all user interactions as Intents, using a single immutable
+  state per screen, or managing side effects as Effects separate from state.
+---
+
+# MVI
+
+## Overview
+
+MVI enforces strict unidirectional data flow: the View emits **Intents**, the ViewModel processes them and produces a new immutable **State**, and one-time **Effects** handle side effects like navigation or toasts. Unlike MVVM, all user interactions are modeled as a sealed `Intent` class — nothing is called imperatively.
+
+---
+
+## Core Principles
+
+- **One immutable State** per screen — never partial updates
+- All user actions are **Intents** — sealed class, no direct function calls from UI
+- **Effects** are one-time events (navigation, toast) — separate from State
+- State transitions are **pure** — `reduce(currentState, intent) → newState`
+- ViewModel processes intents sequentially — no race conditions on state
+
+---
+
+## Contract (State + Intent + Effect)
+
+```kotlin
+// ✅ Define the full screen contract in one place
+object UserListContract {
+
+    data class State(
+        val isLoading: Boolean = false,
+        val users: List<User> = emptyList(),
+        val error: String? = null,
+        val searchQuery: String = ""
+    )
+
+    sealed interface Intent {
+        data object LoadUsers : Intent
+        data class SearchChanged(val query: String) : Intent
+        data class UserClicked(val userId: String) : Intent
+        data class DeleteUser(val userId: String) : Intent
+    }
+
+    sealed interface Effect {
+        data class NavigateToDetail(val userId: String) : Effect
+        data class ShowSnackbar(val message: String) : Effect
+    }
+}
+```
+
+---
+
+## ViewModel
+
+```kotlin
+// ✅ MVI ViewModel — processes intents, emits state and effects
+@HiltViewModel
+class UserListViewModel @Inject constructor(
+    private val getUsersUseCase: GetUsersUseCase,
+    private val deleteUserUseCase: DeleteUserUseCase
+) : ViewModel() {
+
+    private val _state = MutableStateFlow(UserListContract.State())
+    val state: StateFlow<UserListContract.State> = _state.asStateFlow()
+
+    private val _effects = Channel<UserListContract.Effect>(Channel.BUFFERED)
+    val effects: Flow<UserListContract.Effect> = _effects.receiveAsFlow()
+
+    fun handleIntent(intent: UserListContract.Intent) {
+        when (intent) {
+            is UserListContract.Intent.LoadUsers       -> loadUsers()
+            is UserListContract.Intent.SearchChanged   -> onSearchChanged(intent.query)
+            is UserListContract.Intent.UserClicked     -> onUserClicked(intent.userId)
+            is UserListContract.Intent.DeleteUser      -> deleteUser(intent.userId)
+        }
+    }
+
+    private fun loadUsers() {
+        viewModelScope.launch {
+            _state.update { it.copy(isLoading = true, error = null) }
+            getUsersUseCase().fold(
+                onSuccess = { users ->
+                    _state.update { it.copy(isLoading = false, users = users) }
+                },
+                onFailure = { error ->
+                    _state.update { it.copy(isLoading = false, error = error.message) }
+                }
+            )
+        }
+    }
+
+    private fun onSearchChanged(query: String) {
+        _state.update { it.copy(searchQuery = query) }
+    }
+
+    private fun onUserClicked(userId: String) {
+        viewModelScope.launch {
+            _effects.send(UserListContract.Effect.NavigateToDetail(userId))
+        }
+    }
+
+    private fun deleteUser(userId: String) {
+        viewModelScope.launch {
+            deleteUserUseCase(userId).fold(
+                onSuccess = {
+                    loadUsers()
+                    _effects.send(UserListContract.Effect.ShowSnackbar("User deleted"))
+                },
+                onFailure = {
+                    _effects.send(UserListContract.Effect.ShowSnackbar("Delete failed"))
+                }
+            )
+        }
+    }
+}
+```
+
+---
+
+## Composable
+
+```kotlin
+// ✅ View sends intents — never calls ViewModel functions directly
+@Composable
+fun UserListScreen(
+    onNavigateToDetail: (String) -> Unit,
+    viewModel: UserListViewModel = hiltViewModel()
+) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+    val snackbarHostState = remember { SnackbarHostState() }
+
+    // ✅ Collect one-time effects
+    LaunchedEffect(Unit) {
+        viewModel.effects.collect { effect ->
+            when (effect) {
+                is UserListContract.Effect.NavigateToDetail ->
+                    onNavigateToDetail(effect.userId)
+                is UserListContract.Effect.ShowSnackbar ->
+                    snackbarHostState.showSnackbar(effect.message)
+            }
+        }
+    }
+
+    // ✅ Trigger initial load via intent
+    LaunchedEffect(Unit) {
+        viewModel.handleIntent(UserListContract.Intent.LoadUsers)
+    }
+
+    Scaffold(snackbarHost = { SnackbarHost(snackbarHostState) }) { padding ->
+        UserListContent(
+            state = state,
+            onIntent = viewModel::handleIntent,
+            modifier = Modifier.padding(padding)
+        )
+    }
+}
+
+// ✅ Content composable receives state and onIntent — no ViewModel reference
+@Composable
+private fun UserListContent(
+    state: UserListContract.State,
+    onIntent: (UserListContract.Intent) -> Unit,
+    modifier: Modifier = Modifier
+) {
+    Column(modifier = modifier) {
+        SearchBar(
+            query = state.searchQuery,
+            onQueryChange = { onIntent(UserListContract.Intent.SearchChanged(it)) }
+        )
+
+        when {
+            state.isLoading -> LoadingState()
+            state.error != null -> ErrorState(
+                message = state.error,
+                onRetry = { onIntent(UserListContract.Intent.LoadUsers) }
+            )
+            state.users.isEmpty() -> EmptyState()
+            else -> UserList(
+                users = state.users,
+                onUserClick = { onIntent(UserListContract.Intent.UserClicked(it)) },
+                onDeleteClick = { onIntent(UserListContract.Intent.DeleteUser(it)) }
+            )
+        }
+    }
+}
+```
+
+---
+
+## MVI vs MVVM — When to Use Each
+
+| Concern        | MVVM                         | MVI                                    |
+| -------------- | ---------------------------- | -------------------------------------- |
+| Complexity     | Simple to medium screens     | Complex screens with many interactions |
+| State tracing  | Multiple StateFlows possible | Single immutable State — easy to trace |
+| Testability    | Test individual functions    | Test intent → state transitions        |
+| Boilerplate    | Less                         | More (Contract class)                  |
+| Predictability | Good                         | Excellent                              |
+
+Use **MVVM** as the default. Reach for **MVI** when a screen has many concurrent interactions and state bugs are hard to trace.
+
+---
+
+## Anti-Patterns
+
+- Calling ViewModel functions directly from UI — use `handleIntent()`
+- Mutable state fields inside the State data class — keep State fully immutable
+- Sending navigation as State change — navigation is an Effect, not State
+- Multiple state flows per screen — one `StateFlow<State>` only
+- Processing intents with side effects inside `reduce()` — `reduce()` must be pure if used
+
+---
+
+## Related Skills
+
+- `mvvm` — simpler alternative for straightforward screens
+- `unidirectional-data-flow` — the underlying pattern MVI is built on
+- `state-management` — state patterns and tools
+- `side-effect-management` — handling effects correctly
+- `compose` — collecting state in Compose UI

package/skills/Architecture/MVVM/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: mvvm
+description: >
+  Model-View-ViewModel pattern for Android with Jetpack Compose.
+  Load this skill when structuring a screen with ViewModel, defining
+  UI state, handling user events, managing one-time side effects,
+  or wiring ViewModel to Compose UI.
+---
+
+# MVVM
+
+## Overview
+
+MVVM separates UI (View) from business logic (ViewModel) via observable state. In Compose, the ViewModel exposes `StateFlow` for UI state and a `Channel` or `SharedFlow` for one-time events. The composable observes state and delegates all actions to the ViewModel.
+
+---
+
+## Core Principles
+
+- ViewModel exposes **one UI state** as `StateFlow` — never multiple disconnected flags
+- One-time events (navigation, toasts) go through a `Channel` — not `StateFlow`
+- Composables are **stateless** — they receive state and emit events only
+- ViewModel has **no reference** to View, Context, or composable
+- User actions are modeled as a sealed `UiEvent` class — not individual functions for simple screens
+
+---
+
+## UI State Model
+
+```kotlin
+// ✅ Single sealed state per screen
+sealed interface UserDetailUiState {
+    data object Loading : UserDetailUiState
+    data class Success(val user: User) : UserDetailUiState
+    data class Error(val message: String) : UserDetailUiState
+}
+
+// ✅ Or data class for screens with multiple fields
+data class UserListUiState(
+    val isLoading: Boolean = false,
+    val users: List<User> = emptyList(),
+    val error: String? = null,
+    val searchQuery: String = ""
+)
+```
+
+---
+
+## One-Time Events
+
+```kotlin
+// ✅ Events that happen once — not persistent state
+sealed interface UserDetailEvent {
+    data object NavigateBack : UserDetailEvent
+    data class ShowToast(val message: String) : UserDetailEvent
+    data class NavigateToEdit(val userId: String) : UserDetailEvent
+}
+```
+
+---
+
+## ViewModel
+
+```kotlin
+// ✅ Standard ViewModel structure
+@HiltViewModel
+class UserDetailViewModel @Inject constructor(
+    savedStateHandle: SavedStateHandle,
+    private val getUserUseCase: GetUserUseCase,
+    private val deleteUserUseCase: DeleteUserUseCase
+) : ViewModel() {
+
+    private val userId: String = checkNotNull(savedStateHandle["userId"])
+
+    // UI state
+    private val _state = MutableStateFlow<UserDetailUiState>(UserDetailUiState.Loading)
+    val state: StateFlow<UserDetailUiState> = _state.asStateFlow()
+
+    // One-time events
+    private val _events = Channel<UserDetailEvent>(Channel.BUFFERED)
+    val events: Flow<UserDetailEvent> = _events.receiveAsFlow()
+
+    init {
+        loadUser()
+    }
+
+    fun loadUser() {
+        viewModelScope.launch {
+            _state.value = UserDetailUiState.Loading
+            getUserUseCase(userId).fold(
+                onSuccess = { _state.value = UserDetailUiState.Success(it) },
+                onFailure = { _state.value = UserDetailUiState.Error(it.message ?: "Error") }
+            )
+        }
+    }
+
+    fun onDeleteClick() {
+        viewModelScope.launch {
+            deleteUserUseCase(userId).fold(
+                onSuccess = { _events.send(UserDetailEvent.NavigateBack) },
+                onFailure = { _events.send(UserDetailEvent.ShowToast("Delete failed")) }
+            )
+        }
+    }
+
+    fun onEditClick() {
+        viewModelScope.launch {
+            _events.send(UserDetailEvent.NavigateToEdit(userId))
+        }
+    }
+}
+```
+
+---
+
+## Composable
+
+```kotlin
+// ✅ Stateless composable — observes state, delegates actions
+@Composable
+fun UserDetailScreen(
+    onNavigateBack: () -> Unit,
+    onNavigateToEdit: (String) -> Unit,
+    viewModel: UserDetailViewModel = hiltViewModel()
+) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+    val context = LocalContext.current
+
+    // ✅ Collect one-time events
+    LaunchedEffect(Unit) {
+        viewModel.events.collect { event ->
+            when (event) {
+                is UserDetailEvent.NavigateBack -> onNavigateBack()
+                is UserDetailEvent.ShowToast -> Toast.makeText(context, event.message, Toast.LENGTH_SHORT).show()
+                is UserDetailEvent.NavigateToEdit -> onNavigateToEdit(event.userId)
+            }
+        }
+    }
+
+    UserDetailContent(
+        state = state,
+        onDeleteClick = viewModel::onDeleteClick,
+        onEditClick = viewModel::onEditClick,
+        onRetryClick = viewModel::loadUser
+    )
+}
+
+// ✅ Pure content composable — no ViewModel reference
+@Composable
+private fun UserDetailContent(
+    state: UserDetailUiState,
+    onDeleteClick: () -> Unit,
+    onEditClick: () -> Unit,
+    onRetryClick: () -> Unit
+) {
+    when (state) {
+        is UserDetailUiState.Loading -> LoadingState()
+        is UserDetailUiState.Success -> UserDetailBody(state.user, onDeleteClick, onEditClick)
+        is UserDetailUiState.Error   -> ErrorState(state.message, onRetryClick)
+    }
+}
+```
+
+---
+
+## Shared ViewModel (Between Screens)
+
+```kotlin
+// ✅ Shared ViewModel scoped to NavBackStackEntry
+@Composable
+fun ParentScreen(navController: NavController) {
+    val parentEntry = remember(navController) {
+        navController.getBackStackEntry(ParentRoute)
+    }
+    val sharedViewModel: SharedViewModel = hiltViewModel(parentEntry)
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Multiple `StateFlow` properties for one screen — use a single state class
+- Using `StateFlow` for navigation events — use `Channel` instead (won't replay)
+- Passing `Context` into ViewModel — use `ApplicationContext` only when necessary via `@ApplicationContext`
+- Calling `viewModel.someFlow.collect {}` without `collectAsStateWithLifecycle` in Compose
+- Business logic inside composables — belongs in ViewModel or use case
+- ViewModel referencing a specific composable or Fragment
+
+---
+
+## Related Skills
+
+- `clean-architecture` — layer structure ViewModel sits within
+- `state-management` — advanced state patterns
+- `side-effect-management` — handling side effects from ViewModel
+- `use-case-design` — what the ViewModel delegates to
+- `savedstatehandle` — persisting ViewModel state across process death

package/skills/Architecture/Modularization/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: modularization
+description: >
+  App modularization strategy for Android projects.
+  Load this skill when deciding how to split a project into modules,
+  defining module types and responsibilities, managing module dependencies,
+  or planning build performance improvements through modularization.
+---
+
+# Modularization
+
+## Overview
+Modularization splits the app into independent Gradle modules. Each module has a single responsibility, clear API boundaries, and explicit dependencies. This improves build times (parallel compilation, build cache), enforces architecture boundaries, and enables code reuse across features.
+
+---
+
+## Core Principles
+
+- Modules depend **inward** — feature modules never depend on other feature modules
+- Each module exposes a **minimal public API** — use `internal` for implementation details
+- **No circular dependencies** between modules
+- Core/shared modules are **stable** — feature modules are volatile
+- Module boundaries enforce **architecture layers** — a `data` module cannot import a `ui` module
+
+---
+
+## Module Types
+
+```
+:app                    — entry point, wires everything together
+:core:ui                — shared Compose components, theme, design system
+:core:domain            — shared domain models and interfaces
+:core:data              — shared repository implementations, database, network
+:core:common            — utilities, extensions, base classes
+:feature:users          — users feature (presentation + domain + data for this feature)
+:feature:products       — products feature
+:feature:settings       — settings feature
+```
+
+---
+
+## Recommended Structure
+
+```
+app/
+├── app/                            # :app — Application, MainActivity, DI root
+├── core/
+│   ├── ui/                         # :core:ui — Theme, shared components
+│   ├── domain/                     # :core:domain — Shared models, base UseCases
+│   ├── data/                       # :core:data — Network, DB, shared repos
+│   ├── common/                     # :core:common — Extensions, utils, Result
+│   └── testing/                    # :core:testing — Fakes, test utilities
+└── feature/
+    ├── users/                      # :feature:users
+    │   ├── src/main/
+    │   │   ├── presentation/       # Screen, ViewModel, UiState
+    │   │   ├── domain/             # Feature-specific UseCases
+    │   │   └── data/               # Feature-specific Repository
+    │   └── build.gradle.kts
+    └── products/                   # :feature:products
+```
+
+---
+
+## Dependency Graph
+
+```
+:app
+ ├── :feature:users
+ │    ├── :core:domain
+ │    ├── :core:data
+ │    └── :core:ui
+ ├── :feature:products
+ │    ├── :core:domain
+ │    ├── :core:data
+ │    └── :core:ui
+ └── :core:common
+
+# ✅ Allowed
+:feature:users → :core:domain
+:feature:users → :core:ui
+:app → :feature:users
+
+# ❌ Not allowed
+:feature:users → :feature:products   # feature-to-feature dependency
+:core:data → :feature:users          # core depending on feature
+:core:ui → :core:data                # ui depending on data
+```
+
+---
+
+## build.gradle.kts per Module
+
+```kotlin
+// ✅ Feature module build file
+plugins {
+    alias(libs.plugins.android.library)
+    alias(libs.plugins.kotlin.android)
+    alias(libs.plugins.hilt)
+    alias(libs.plugins.ksp)
+}
+
+android {
+    namespace = "com.example.feature.users"
+    // shared config via convention plugin
+}
+
+dependencies {
+    implementation(project(":core:domain"))
+    implementation(project(":core:data"))
+    implementation(project(":core:ui"))
+    implementation(project(":core:common"))
+
+    implementation(libs.hilt.android)
+    ksp(libs.hilt.compiler)
+
+    testImplementation(project(":core:testing"))
+}
+```
+
+---
+
+## Navigation Between Modules
+
+```kotlin
+// ✅ Feature modules expose navigation routes as constants
+// :feature:users
+object UsersNavigation {
+    const val ROUTE = "users"
+    const val USER_DETAIL_ROUTE = "users/{userId}"
+
+    fun userDetailRoute(userId: String) = "users/$userId"
+}
+
+// ✅ :app wires navigation — features don't know about each other
+@Composable
+fun AppNavHost(navController: NavHostController) {
+    NavHost(navController = navController, startDestination = UsersNavigation.ROUTE) {
+        usersNavGraph(navController)
+        productsNavGraph(navController)
+    }
+}
+
+// ✅ Each feature exposes a NavGraph extension
+fun NavGraphBuilder.usersNavGraph(navController: NavController) {
+    navigation(
+        startDestination = UsersNavigation.ROUTE,
+        route = "users_graph"
+    ) {
+        composable(UsersNavigation.ROUTE) { UserListScreen(navController) }
+        composable(UsersNavigation.USER_DETAIL_ROUTE) { UserDetailScreen(navController) }
+    }
+}
+```
+
+---
+
+## Visibility Control
+
+```kotlin
+// ✅ Use internal to hide implementation from other modules
+internal class UserRepositoryImpl @Inject constructor(...) : UserRepository
+
+// ✅ Only expose what other modules need
+class GetUserUseCase @Inject constructor(...)  // public — used by presentation
+internal class UserRemoteDataSource(...)       // internal — implementation detail
+
+// ✅ Hilt: internal classes need explicit binding
+@Module
+@InstallIn(SingletonComponent::class)
+internal abstract class UserModule {
+    @Binds
+    abstract fun bindUserRepository(impl: UserRepositoryImpl): UserRepository
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Feature modules depending on each other — use `:app` or a shared `:core` module to mediate
+- Putting everything in `:core:common` — keep common truly generic; feature logic belongs in features
+- Circular dependencies — will cause Gradle build failure
+- Public classes that should be `internal` — leaks implementation details
+- One mega-module — defeats purpose of modularization; build times won't improve
+
+---
+
+## Related Skills
+- `multi-module-architecture` — detailed multi-module setup and advanced patterns
+- `hilt` — Hilt setup across modules
+- `gradle` — Gradle configuration for multi-module projects
+- `convention-plugin` — sharing build configuration across modules
+- `clean-architecture` — layer boundaries that modularization enforces