agy-superpowers 5.0.8 → 5.0.9

package/template/agent/skills/mobile-developer/SKILL.md

@@ -140,3 +140,55 @@ What are you building?
 ```
 
 Primary CTAs belong in the **bottom 40%** of the screen.
+
+---
+
+## Platform References
+
+When this skill is invoked, detect the project's platform stack and read
+the matching reference file(s) from `references/` before proceeding:
+
+| Stack indicator                       | Reference file                |
+|---------------------------------------|-------------------------------|
+| `package.json` with `react-native`    | `references/react-native.md`  |
+| `pubspec.yaml`                        | `references/flutter.md`       |
+| `*.xcodeproj` or `Package.swift`      | `references/ios-native.md`    |
+| `build.gradle.kts` or `build.gradle`  | `references/android-native.md`|
+
+If the project uses multiple stacks (e.g., React Native with native
+modules), read ALL matching references.
+
+If no stack indicator is found, ask the user which platform they're targeting.
+
+### Granular Rules (React Native)
+
+For React Native projects, `references/react-native-rules/` contains 36
+individual rule files from [Vercel's agent-skills](https://github.com/vercel-labs/agent-skills).
+Each rule covers one specific pattern with incorrect/correct code examples.
+
+Read `references/react-native-rules/_sections.md` for the full index
+organized by priority (CRITICAL → LOW). Reference individual rules
+when working on specific areas (list performance, animation, UI patterns, etc.).
+
+### Granular Rules (Flutter/Dart)
+
+For Flutter projects, `references/flutter-rules/` contains 8 Dart skill
+files from [kevmoo/dash_skills](https://github.com/kevmoo/dash_skills),
+covering Dart language best practices, modern features, testing patterns,
+and package maintenance.
+
+### Granular Rules (Android)
+
+For Android projects, `references/android-rules/` contains 17 skill
+files from [awesome-android-agent-skills](https://github.com/new-silvermoon/awesome-android-agent-skills),
+covering: Clean Architecture, Compose UI/Performance/Navigation,
+ViewModel patterns, Retrofit networking, Kotlin Coroutines, Gradle
+optimization, testing, and XML-to-Compose migration.
+
+### Granular Rules (iOS/SwiftUI)
+
+For iOS projects, `references/ios-rules/` contains 19 SwiftUI reference
+files from [AvdLee/SwiftUI-Agent-Skill](https://github.com/AvdLee/SwiftUI-Agent-Skill),
+covering: state management, view composition, performance, animations
+(basics/advanced/transitions), navigation, Swift Charts, macOS support,
+Liquid Glass (iOS 26+), and accessibility.

package/template/agent/skills/mobile-developer/references/android-native.md

@@ -0,0 +1,396 @@
+# Android Native (Kotlin / Jetpack Compose) Reference
+
+> **Philosophy:** Material Design, Kotlin-first, Compose-first.
+> Lifecycle-aware, configuration-change-safe, backwards-compatible.
+
+---
+
+## Project Setup & Detection
+
+**Stack indicators:** `build.gradle.kts` or `build.gradle`, `AndroidManifest.xml`, `settings.gradle.kts`.
+
+**Key config files:**
+
+| File | Purpose |
+|------|---------|
+| `build.gradle.kts` (app module) | App dependencies, minSdk, targetSdk, signing |
+| `build.gradle.kts` (project) | Plugin versions, repositories |
+| `settings.gradle.kts` | Module declarations, version catalog |
+| `gradle/libs.versions.toml` | Gradle Version Catalog (centralized dependency versions) |
+| `AndroidManifest.xml` | Permissions, components, intent filters |
+| `proguard-rules.pro` | R8/ProGuard minification rules |
+
+**Recommended project structure (feature-based, multi-module):**
+
+```
+app/
+  src/main/
+    java/com/example/myapp/
+      MyApp.kt                      # Application class
+      MainActivity.kt               # Single Activity
+      navigation/
+        AppNavigation.kt            # NavHost setup
+    res/
+      values/themes.xml
+feature/
+  auth/
+    src/main/java/.../auth/
+      ui/LoginScreen.kt
+      LoginViewModel.kt
+      data/AuthRepository.kt
+  home/
+    src/main/java/.../home/
+      ui/HomeScreen.kt
+      HomeViewModel.kt
+core/
+  data/                             # Shared data layer
+  ui/                               # Shared Compose components
+  network/                          # Retrofit setup, API definitions
+```
+
+---
+
+## Architecture Patterns
+
+### MVVM with ViewModel + StateFlow
+
+```kotlin
+class ProfileViewModel @Inject constructor(
+    private val userRepository: UserRepository,
+) : ViewModel() {
+
+    private val _uiState = MutableStateFlow<ProfileUiState>(ProfileUiState.Loading)
+    val uiState: StateFlow<ProfileUiState> = _uiState.asStateFlow()
+
+    init { loadProfile() }
+
+    private fun loadProfile() {
+        viewModelScope.launch {
+            _uiState.value = ProfileUiState.Loading
+            userRepository.getProfile()
+                .onSuccess { _uiState.value = ProfileUiState.Success(it) }
+                .onFailure { _uiState.value = ProfileUiState.Error(it.message) }
+        }
+    }
+}
+
+sealed interface ProfileUiState {
+    data object Loading : ProfileUiState
+    data class Success(val user: User) : ProfileUiState
+    data class Error(val message: String?) : ProfileUiState
+}
+```
+
+### Dependency Injection
+
+| Framework | Use When |
+|-----------|----------|
+| **Hilt** (recommended) | Most apps — Google-supported, integrates with ViewModel, WorkManager |
+| **Koin** | Lightweight, no annotation processing, multiplatform support |
+
+```kotlin
+// Hilt module
+@Module
+@InstallIn(SingletonComponent::class)
+object NetworkModule {
+    @Provides @Singleton
+    fun provideRetrofit(): Retrofit = Retrofit.Builder()
+        .baseUrl("https://api.example.com/")
+        .addConverterFactory(MoshiConverterFactory.create())
+        .build()
+}
+
+// ViewModel injection
+@HiltViewModel
+class HomeViewModel @Inject constructor(
+    private val repository: ItemRepository,
+) : ViewModel()
+```
+
+### Navigation
+
+**Navigation Compose** — type-safe with Kotlin serialization:
+
+```kotlin
+@Serializable data class Profile(val id: String)
+
+NavHost(navController, startDestination = Home) {
+    composable<Home> { HomeScreen(onNavigate = { navController.navigate(Profile(it)) }) }
+    composable<Profile> { backStackEntry ->
+        val profile: Profile = backStackEntry.toRoute()
+        ProfileScreen(id = profile.id)
+    }
+}
+```
+
+- Use **single-Activity** architecture with Compose Navigation
+- Use `NavBackStackEntry.toRoute()` for type-safe argument extraction
+- Handle deep links via `deepLinks` parameter in `composable()`
+
+---
+
+## Performance Optimization
+
+### Critical Thresholds
+
+| Metric | Target | Investigate |
+|--------|--------|-------------|
+| Cold start | < 1s | > 2s |
+| Frame rendering | 16ms (60fps) | > 32ms |
+| APK/AAB size | < 20MB | > 50MB |
+| Memory (foreground) | < 150MB | > 300MB |
+
+### Compose Performance
+
+1. **Stability matters** — Compose skips recomposition for stable parameters. Unstable types (lists, lambdas) prevent skipping.
+
+```kotlin
+// ❌ Bad: List<Item> is unstable, recomposes every time
+@Composable fun ItemList(items: List<Item>) { ... }
+
+// ✅ Good: ImmutableList is stable, skips recomposition when data unchanged
+@Composable fun ItemList(items: ImmutableList<Item>) { ... }
+```
+
+2. **`@Stable` and `@Immutable` annotations** — tell Compose your types are stable.
+
+```kotlin
+@Immutable
+data class UserProfile(val id: String, val name: String, val avatarUrl: String)
+```
+
+3. **`LazyColumn` with stable keys** — always provide unique keys for correct recomposition and animation.
+
+```kotlin
+LazyColumn {
+    items(items, key = { it.id }) { item ->
+        ItemRow(item = item)
+    }
+}
+```
+
+4. **`remember` wisely** — use `remember` for expensive computations, not simple derivations. Don't use `remember` with unstable keys.
+
+5. **Baseline Profiles** — pre-compile hot paths at install time, reducing cold start time by 30-50%.
+
+```kotlin
+// benchmark/src/main/java/BaselineProfileGenerator.kt
+@RunWith(AndroidJUnit4::class)
+class BaselineProfileGenerator {
+    @get:Rule val rule = BaselineProfileRule()
+
+    @Test
+    fun generate() {
+        rule.collect("com.example.myapp") {
+            pressHome()
+            startActivityAndWait()
+            // Navigate through critical flows
+        }
+    }
+}
+```
+
+6. **R8 minification** — always enable for release builds. Removes unused code and obfuscates.
+
+7. **StrictMode** — enable in debug to catch disk/network on main thread:
+
+```kotlin
+if (BuildConfig.DEBUG) {
+    StrictMode.setThreadPolicy(StrictMode.ThreadPolicy.Builder()
+        .detectAll().penaltyLog().build())
+}
+```
+
+---
+
+## Common Libraries Ecosystem
+
+| Category | Recommended | Alternative |
+|----------|-------------|-------------|
+| **Networking** | `Retrofit` + `OkHttp` | `Ktor` |
+| **JSON** | `Moshi` / `Kotlin Serialization` | `Gson` (legacy) |
+| **Database** | `Room` | `SQLDelight` |
+| **Preferences** | `DataStore` | `SharedPreferences` (legacy) |
+| **Secure Storage** | `EncryptedSharedPreferences` | `Tink` |
+| **Images** | `Coil` (Compose-native) | `Glide` |
+| **DI** | `Hilt` | `Koin` |
+| **UI** | Material 3 (`material3`) | — |
+| **Async** | Kotlin `Flow` + `Coroutines` | RxJava (legacy) |
+| **Paging** | `Paging 3` | — |
+| **Work** | `WorkManager` | — |
+| **Testing** | `JUnit 5` + `MockK` | `Mockito-Kotlin` |
+| **Compose Testing** | `compose-test` | — |
+| **Analytics** | Firebase Analytics | Amplitude |
+
+---
+
+## Anti-Patterns & Gotchas
+
+| ❌ Don't | Why | ✅ Do Instead |
+|----------|-----|---------------|
+| Unstable lambdas in Compose | Prevents recomposition skipping | Extract to ViewModel, hoist to caller, or use `remember` |
+| `MutableList`/`List` parameters | Unstable in Compose, always recomposes | `ImmutableList` from `kotlinx.collections.immutable` |
+| `remember { mutableStateOf() }` for ViewModel state | ViewModel outlives Compose, wrong lifecycle | `StateFlow` in ViewModel, `collectAsStateWithLifecycle` in UI |
+| Blocking main thread | ANR (Application Not Responding) | Coroutines with `Dispatchers.IO` |
+| Missing ProGuard rules | Crashes in release (reflection-based libs) | Add keep rules for Retrofit, Moshi, Room models |
+| Hardcoded dp/sp values everywhere | Inconsistent across screens | Design tokens / theme values |
+| `GlobalScope.launch` | Lifecycle leak, no cancellation | `viewModelScope`, `lifecycleScope`, or custom scope |
+| `SharedPreferences` for complex data | Race conditions, no type safety | `DataStore` with Proto or Preferences |
+| Multiple Activities for navigation | Complex backstack, state loss | Single Activity + Compose Navigation |
+| `@Preview` without sample data | Previews are useless | Use `@PreviewParameter` with sample providers |
+
+### Compose-Specific Pitfalls
+
+- **`derivedStateOf`** — use for expensive computations that depend on state. Don't use for simple reads.
+- **`LaunchedEffect` vs `SideEffect`** — `LaunchedEffect` for suspend functions (runs once per key), `SideEffect` for every recomposition.
+- **`rememberSaveable`** — survives configuration changes and process death. Use for user input, scroll position.
+
+---
+
+## Testing
+
+| Layer | Tool | Purpose |
+|-------|------|---------|
+| **Unit** | JUnit 5 + MockK | ViewModel, Repository, UseCase |
+| **Compose UI** | `createComposeRule()` | Component rendering and interaction |
+| **Integration** | Espresso (+ Compose) | Full screen flows |
+| **Robolectric** | JVM-based Android tests | Fast feedback, no emulator needed |
+| **Screenshot** | Compose Preview Screenshot Testing | Visual regression |
+
+**Testing Compose:**
+
+```kotlin
+@get:Rule val composeTestRule = createComposeRule()
+
+@Test
+fun showsLoginButton() {
+    composeTestRule.setContent { LoginScreen() }
+    composeTestRule.onNodeWithText("Log In").assertIsDisplayed()
+}
+
+@Test
+fun submitForm() {
+    composeTestRule.setContent { LoginScreen() }
+    composeTestRule.onNodeWithTag("email_input").performTextInput("test@example.com")
+    composeTestRule.onNodeWithText("Log In").performClick()
+    composeTestRule.onNodeWithText("Welcome").assertIsDisplayed()
+}
+```
+
+**ViewModel testing:**
+
+```kotlin
+@Test
+fun loadProfile_success() = runTest {
+    val repo = mockk<UserRepository> {
+        coEvery { getProfile() } returns Result.success(testUser)
+    }
+    val vm = ProfileViewModel(repo)
+    vm.uiState.test {
+        assertThat(awaitItem()).isEqualTo(ProfileUiState.Loading)
+        assertThat(awaitItem()).isEqualTo(ProfileUiState.Success(testUser))
+    }
+}
+```
+
+---
+
+## Deployment & Distribution
+
+### Build Commands
+
+```bash
+# Debug build
+./gradlew assembleDebug
+
+# Release APK
+./gradlew assembleRelease
+
+# Release AAB (Play Store required format)
+./gradlew bundleRelease
+
+# Run tests
+./gradlew test                    # Unit tests
+./gradlew connectedAndroidTest    # Instrumented tests
+```
+
+### Distribution Channels
+
+| Channel | Use When |
+|---------|----------|
+| **Google Play Internal Testing** | Fast internal feedback (up to 100 testers) |
+| **Google Play Closed Testing** | Beta testing with larger groups |
+| **Google Play Production** | Public release (staged rollout recommended) |
+| **Firebase App Distribution** | Ad hoc testing, no Play Store needed |
+
+### Signing Configuration
+
+```kotlin
+// build.gradle.kts
+android {
+    signingConfigs {
+        create("release") {
+            storeFile = file(System.getenv("KEYSTORE_PATH"))
+            storePassword = System.getenv("KEYSTORE_PASSWORD")
+            keyAlias = System.getenv("KEY_ALIAS")
+            keyPassword = System.getenv("KEY_PASSWORD")
+        }
+    }
+    buildTypes {
+        release {
+            signingConfig = signingConfigs.getByName("release")
+            isMinifyEnabled = true
+            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
+        }
+    }
+}
+```
+
+### App Size Optimization
+- Enable R8 minification (`isMinifyEnabled = true`)
+- Use Android App Bundle (`.aab`) — Google Play delivers optimized APK per device
+- Remove unused resources with `shrinkResources = true`
+- Use WebP for images (30% smaller than PNG)
+- Split APKs by ABI if distributing outside Play Store
+
+---
+
+## Quick Reference — Granular Rules
+
+Individual skill files in `android-rules/` with detailed patterns, code
+examples, and audit workflows for Android/Kotlin/Compose development.
+
+> Source: [awesome-android-agent-skills](https://github.com/new-silvermoon/awesome-android-agent-skills)
+
+### Architecture & Core
+
+- [android-architecture.md](android-rules/android-architecture.md) — Clean Architecture, modularization, Hilt DI
+- [android-viewmodel.md](android-rules/android-viewmodel.md) — ViewModel + StateFlow/SharedFlow patterns
+- [android-data-layer.md](android-rules/android-data-layer.md) — Repository pattern, offline-first sync
+- [kotlin-concurrency-expert.md](android-rules/kotlin-concurrency-expert.md) — Coroutines triage & structured concurrency
+- [android-coroutines.md](android-rules/android-coroutines.md) — Coroutines patterns
+
+### Compose UI & Performance
+
+- [compose-ui.md](android-rules/compose-ui.md) — Stateless composables, state hoisting, theming
+- [compose-performance-audit.md](android-rules/compose-performance-audit.md) — Recomposition storms, unstable keys audit
+- [compose-navigation.md](android-rules/compose-navigation.md) — Type-safe navigation, deep links, nested graphs
+- [coil-compose.md](android-rules/coil-compose.md) — Coil image loading in Compose
+
+### Networking & Data
+
+- [android-retrofit.md](android-rules/android-retrofit.md) — Retrofit, OkHttp, serialization, interceptors
+- [android-accessibility.md](android-rules/android-accessibility.md) — Content descriptions, touch targets, contrast
+
+### Testing & Build
+
+- [android-testing.md](android-rules/android-testing.md) — Unit, Hilt, screenshot testing (Roborazzi)
+- [android-gradle-logic.md](android-rules/android-gradle-logic.md) — Convention plugins, version catalogs
+- [gradle-build-performance.md](android-rules/gradle-build-performance.md) — Build time optimization (12 patterns)
+- [android-emulator-skill.md](android-rules/android-emulator-skill.md) — ADB, emulator automation
+
+### Migration
+
+- [xml-to-compose-migration.md](android-rules/xml-to-compose-migration.md) — XML to Compose mapping tables
+- [rxjava-to-coroutines-migration.md](android-rules/rxjava-to-coroutines-migration.md) — RxJava to Coroutines/Flow
+

package/template/agent/skills/mobile-developer/references/android-rules/android-accessibility.md

@@ -0,0 +1,36 @@
+---
+name: android-accessibility
+description: Expert checklist and prompts for auditing and fixing Android accessibility issues, especially in Jetpack Compose.
+---
+
+# Android Accessibility Checklist
+
+## Instructions
+
+Analyze the provided component or screen for the following accessibility aspects.
+
+### 1. Content Descriptions
+*   **Check**: Do `Image` and `Icon` composables have a meaningful `contentDescription`?
+*   **Decorative**: If an image is purely decorative, use `contentDescription = null`.
+*   **Actionable**: If an element is clickable, the description should describe the *action* (e.g., "Play music"), not the icon (e.g., "Triangle").
+
+### 2. Touch Target Size
+*   **Standard**: Minimum **48x48dp** for all interactive elements.
+*   **Fix**: Use `MinTouchTargetSize` or wrap in `Box` with appropriate padding if the visual icon is smaller.
+
+### 3. Color Contrast
+*   **Standard**: WCAG AA requires **4.5:1** for normal text and **3.0:1** for large text/icons.
+*   **Tool**: Verify colors against backgrounds using contrast logic.
+
+### 4. Focus & Semantics
+*   **Focus Order**: Ensure keyboard/screen-reader focus moves logically (e.g., Top-Start to Bottom-End).
+*   **Grouping**: Use `Modifier.semantics(mergeDescendants = true)` for complex items (like a row with text and icon) so they are announced as a single item.
+*   **State descriptions**: Use `stateDescription` to describe custom states (e.g., "Selected", "Checked") if standard semantics aren't enough.
+
+### 5. Headings
+*   **Traversal**: Mark title texts with `Modifier.semantics { heading() }` to allow screen reader users to jump between sections.
+
+## Example Prompts for Agent Usage
+*   "Analyze the content description of this Image. Is it appropriate?"
+*   "Check if the touch target size of this button is at least 48dp."
+*   "Does this custom toggle button report its 'Checked' state to TalkBack?"

package/template/agent/skills/mobile-developer/references/android-rules/android-architecture.md

@@ -0,0 +1,52 @@
+---
+name: android-architecture
+description: Expert guidance on setting up and maintaining a modern Android application architecture using Clean Architecture and Hilt. Use this when asked about project structure, module setup, or dependency injection.
+---
+
+# Android Modern Architecture & Modularization
+
+## Instructions
+
+When designing or refactoring an Android application, adhere to the **Guide to App Architecture** and **Clean Architecture** principles.
+
+### 1. High-Level Layers
+Structure the application into three primary layers. Dependencies must strictly flow **inwards** (or downwards) to the core logic.
+
+*   **UI Layer (Presentation)**:
+    *   **Responsibility**: Displaying data and handling user interactions.
+    *   **Components**: Activities, Fragments, Composables, ViewModels.
+    *   **Dependencies**: Depends on the Domain Layer (or Data Layer if simple). **Never** depends on the Data Layer implementation details directly.
+*   **Domain Layer (Business Logic) [Optional but Recommended]**:
+    *   **Responsibility**: Encapsulating complex business rules and reuse.
+    *   **Components**: Use Cases (e.g., `GetLatestNewsUseCase`), Domain Models (pure Kotlin data classes).
+    *   **Pure Kotlin**: Must NOT contain any Android framework dependencies (no `android.*` imports).
+    *   **Dependencies**: Depends on Repository Interfaces.
+*   **Data Layer**:
+    *   **Responsibility**: Managing application data (fetching, caching, saving).
+    *   **Components**: Repositories (implementations), Data Sources (Retrofit APIs, Room DAOs).
+    *   **Dependencies**: Depends only on external sources and libraries.
+
+### 2. Dependency Injection with Hilt
+Use **Hilt** for all dependency injection.
+
+*   **@HiltAndroidApp**: Annotate the `Application` class.
+*   **@AndroidEntryPoint**: Annotate Activities and Fragments.
+*   **@HiltViewModel**: Annotate ViewModels; use standard `constructor` injection.
+*   **Modules**:
+    *   Use `@Module` and `@InstallIn(SingletonComponent::class)` for app-wide singletons (e.g., Network, Database).
+    *   Use `@Binds` in an abstract class to bind interface implementations (cleaner than `@Provides`).
+
+### 3. Modularization Strategy
+For production apps, use a multi-module strategy to improve build times and separation of concerns.
+
+*   **:app**: The main entry point, connects features.
+*   **:core:model**: Shared domain models (Pure Kotlin).
+*   **:core:data**: Repositories, Data Sources, Database, Network.
+*   **:core:domain**: Use Cases and Repository Interfaces.
+*   **:core:ui**: Shared Composables, Theme, Resources.
+*   **:feature:[name]**: Standalone feature modules containing their own UI and ViewModels. Depends on `:core:domain` and `:core:ui`.
+
+### 4. Checklist for implementation
+- [ ] Ensure `Domain` layer has no Android dependencies.
+- [ ] Repositories should default to main-safe suspend functions (use `Dispatchers.IO` internally if needed).
+- [ ] ViewModels should interact with the UI layer via `StateFlow` (see `android-viewmodel` skill).

package/template/agent/skills/mobile-developer/references/android-rules/android-coroutines.md

@@ -0,0 +1,139 @@
+---
+name: android-coroutines
+description: Authoritative rules and patterns for production-quality Kotlin Coroutines onto Android. Covers structured concurrency, lifecycle integration, and reactive streams.
+---
+
+# Android Coroutines Expert Skill
+
+This skill provides authoritative rules and patterns for writing production-quality Kotlin Coroutines code on Android. It enforces structured concurrency, lifecycle safety, and modern best practices (2025 standards).
+
+## Responsibilities
+
+*   **Asynchronous Logic**: Implementing suspend functions, Dispatcher management, and parallel execution.
+*   **Reactive Streams**: Implementing `Flow`, `StateFlow`, `SharedFlow`, and `callbackFlow`.
+*   **Lifecycle Integration**: Managing scopes (`viewModelScope`, `lifecycleScope`) and safe collection (`repeatOnLifecycle`).
+*   **Error Handling**: Implementing `CoroutineExceptionHandler`, `SupervisorJob`, and proper `try-catch` hierarchies.
+*   **Cancellability**: Ensuring long-running operations are cooperative using `ensureActive()`.
+*   **Testing**: Setting up `TestDispatcher` and `runTest`.
+
+## Applicability
+
+Activate this skill when the user asks to:
+*   "Fetch data from an API/Database."
+*   "Perform background processing."
+*   "Fix a memory leak" related to threads/tasks.
+*   "Convert a listener/callback to Coroutines."
+*   "Implement a ViewModel."
+*   "Handle UI state updates."
+
+## Critical Rules & Constraints
+
+### 1. Dispatcher Injection (Testability)
+*   **NEVER** hardcode Dispatchers (e.g., `Dispatchers.IO`, `Dispatchers.Default`) inside classes.
+*   **ALWAYS** inject a `CoroutineDispatcher` via the constructor.
+*   **DEFAULT** to `Dispatchers.IO` in the constructor argument for convenience, but allow it to be overridden.
+
+```kotlin
+// CORRECT
+class UserRepository(
+    private val ioDispatcher: CoroutineDispatcher = Dispatchers.IO
+) { ... }
+
+// INCORRECT
+class UserRepository {
+    fun getData() = withContext(Dispatchers.IO) { ... }
+}
+```
+
+### 2. Main-Safety
+*   All suspend functions defined in the Data or Domain layer must be **main-safe**.
+*   **One-shot calls** should be exposed as `suspend` functions.
+*   **Data changes** should be exposed as `Flow`.
+*   The caller (ViewModel) should be able to call them from `Dispatchers.Main` without blocking the UI.
+*   Use `withContext(dispatcher)` inside the repository implementation to move execution to the background.
+
+### 3. Lifecycle-Aware Collection
+*   **NEVER** collect a flow directly in `lifecycleScope.launch` or `launchWhenStarted` (deprecated/unsafe).
+*   **ALWAYS** use `repeatOnLifecycle(Lifecycle.State.STARTED)` for collecting flows in Activities or Fragments.
+
+```kotlin
+// CORRECT
+viewLifecycleOwner.lifecycleScope.launch {
+    viewLifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
+        viewModel.uiState.collect { ... }
+    }
+}
+```
+
+### 4. ViewModel Scope Usage
+*   Use `viewModelScope` for initiating coroutines in ViewModels.
+*   Do not expose suspend functions from the ViewModel to the View. The ViewModel should expose `StateFlow` or `SharedFlow` that the View observes.
+
+### 5. Mutable State Encapsulation
+*   **NEVER** expose `MutableStateFlow` or `MutableSharedFlow` publicly.
+*   Expose them as read-only `StateFlow` or `Flow` using `.asStateFlow()` or upcasting.
+
+### 6. GlobalScope Prohibition
+*   **NEVER** use `GlobalScope`. It breaks structured concurrency and leads to leaks.
+*   If a task must survive the current scope, use an injected `applicationScope` (a custom scope tied to the Application lifecycle).
+
+### 7. Exception Handling
+*   **NEVER** catch `CancellationException` in a generic `catch (e: Exception)` block without rethrowing it.
+*   Use `runCatching` only if you explicitly rethrow `CancellationException`.
+*   Use `CoroutineExceptionHandler` only for top-level coroutines (inside `launch`). It has no effect inside `async` or child coroutines.
+
+### 8. Cancellability
+*   Coroutines feature **cooperative cancellation**. They don't stop immediately unless they check for cancellation.
+*   **ALWAYS** call `ensureActive()` or `yield()` in tight loops (e.g., processing a large list, reading files) to check for cancellation.
+*   Standard functions like `delay()` and `withContext()` are already cancellable.
+
+### 9. Callback Conversion
+*   Use `callbackFlow` to convert callback-based APIs to Flow.
+*   **ALWAYS** use `awaitClose` at the end of the `callbackFlow` block to unregister listeners.
+
+## Code Patterns
+
+### Repository Pattern with Flow
+
+```kotlin
+class NewsRepository(
+    private val remoteDataSource: NewsRemoteDataSource,
+    private val externalScope: CoroutineScope, // For app-wide events
+    private val ioDispatcher: CoroutineDispatcher = Dispatchers.IO
+) {
+    val newsUpdates: Flow<List<News>> = flow {
+        val news = remoteDataSource.fetchLatestNews()
+        emit(news)
+    }.flowOn(ioDispatcher) // Upstream executes on IO
+}
+```
+
+### Parallel Execution
+
+```kotlin
+suspend fun loadDashboardData() = coroutineScope {
+    val userDeferred = async { userRepo.getUser() }
+    val feedDeferred = async { feedRepo.getFeed() }
+    
+    // Wait for both
+    DashboardData(
+        user = userDeferred.await(),
+        feed = feedDeferred.await()
+    )
+}
+```
+
+### Testing with runTest
+
+```kotlin
+@Test
+fun testViewModel() = runTest {
+    val testDispatcher = StandardTestDispatcher(testScheduler)
+    val viewModel = MyViewModel(testDispatcher)
+    
+    viewModel.loadData()
+    advanceUntilIdle() // Process coroutines
+    
+    assertEquals(expectedState, viewModel.uiState.value)
+}
+```