agy-superpowers 5.0.8 → 5.0.9

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

@@ -0,0 +1,422 @@
+---
+name: compose-navigation
+description: Implement navigation in Jetpack Compose using Navigation Compose. Use when asked to set up navigation, pass arguments between screens, handle deep links, or structure multi-screen apps.
+---
+
+# Compose Navigation
+
+## Overview
+
+Implement type-safe navigation in Jetpack Compose applications using the Navigation Compose library. This skill covers NavHost setup, argument passing, deep links, nested graphs, adaptive navigation, and testing.
+
+## Setup
+
+Add the Navigation Compose dependency:
+
+```kotlin
+// build.gradle.kts
+dependencies {
+    implementation("androidx.navigation:navigation-compose:2.8.5")
+    
+    // For type-safe navigation (recommended)
+    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3")
+}
+
+// Enable serialization plugin
+plugins {
+    kotlin("plugin.serialization") version "2.0.21"
+}
+```
+
+---
+
+## Core Concepts
+
+### 1. Define Routes (Type-Safe)
+
+Use `@Serializable` data classes/objects for type-safe routes:
+
+```kotlin
+import kotlinx.serialization.Serializable
+
+// Simple screen (no arguments)
+@Serializable
+object Home
+
+// Screen with required argument
+@Serializable
+data class Profile(val userId: String)
+
+// Screen with optional argument
+@Serializable
+data class Settings(val section: String? = null)
+
+// Screen with multiple arguments
+@Serializable
+data class ProductDetail(val productId: String, val showReviews: Boolean = false)
+```
+
+### 2. Create NavController
+
+```kotlin
+@Composable
+fun MyApp() {
+    val navController = rememberNavController()
+    
+    AppNavHost(navController = navController)
+}
+```
+
+### 3. Create NavHost
+
+```kotlin
+@Composable
+fun AppNavHost(
+    navController: NavHostController,
+    modifier: Modifier = Modifier
+) {
+    NavHost(
+        navController = navController,
+        startDestination = Home,
+        modifier = modifier
+    ) {
+        composable<Home> {
+            HomeScreen(
+                onNavigateToProfile = { userId ->
+                    navController.navigate(Profile(userId))
+                }
+            )
+        }
+        
+        composable<Profile> { backStackEntry ->
+            val profile: Profile = backStackEntry.toRoute()
+            ProfileScreen(userId = profile.userId)
+        }
+        
+        composable<Settings> { backStackEntry ->
+            val settings: Settings = backStackEntry.toRoute()
+            SettingsScreen(section = settings.section)
+        }
+    }
+}
+```
+
+---
+
+## Navigation Patterns
+
+### Basic Navigation
+
+```kotlin
+// Navigate forward
+navController.navigate(Profile(userId = "user123"))
+
+// Navigate and pop current screen
+navController.navigate(Home) {
+    popUpTo<Home> { inclusive = true }
+}
+
+// Navigate back
+navController.popBackStack()
+
+// Navigate back to specific destination
+navController.popBackStack<Home>(inclusive = false)
+```
+
+### Navigate with Options
+
+```kotlin
+navController.navigate(Profile(userId = "user123")) {
+    // Pop up to destination (clear back stack)
+    popUpTo<Home> {
+        inclusive = false  // Keep Home in stack
+        saveState = true   // Save state of popped screens
+    }
+    
+    // Avoid multiple copies of same destination
+    launchSingleTop = true
+    
+    // Restore state when navigating to this destination
+    restoreState = true
+}
+```
+
+### Bottom Navigation Pattern
+
+```kotlin
+@Composable
+fun MainScreen() {
+    val navController = rememberNavController()
+    
+    Scaffold(
+        bottomBar = {
+            NavigationBar {
+                val navBackStackEntry by navController.currentBackStackEntryAsState()
+                val currentDestination = navBackStackEntry?.destination
+                
+                NavigationBarItem(
+                    icon = { Icon(Icons.Default.Home, contentDescription = "Home") },
+                    label = { Text("Home") },
+                    selected = currentDestination?.hasRoute<Home>() == true,
+                    onClick = {
+                        navController.navigate(Home) {
+                            popUpTo(navController.graph.findStartDestination().id) {
+                                saveState = true
+                            }
+                            launchSingleTop = true
+                            restoreState = true
+                        }
+                    }
+                )
+                // Add more items...
+            }
+        }
+    ) { innerPadding ->
+        AppNavHost(
+            navController = navController,
+            modifier = Modifier.padding(innerPadding)
+        )
+    }
+}
+```
+
+---
+
+## Argument Handling
+
+### Retrieve Arguments in Composable
+
+```kotlin
+composable<Profile> { backStackEntry ->
+    val profile: Profile = backStackEntry.toRoute()
+    ProfileScreen(userId = profile.userId)
+}
+```
+
+### Retrieve Arguments in ViewModel
+
+```kotlin
+@HiltViewModel
+class ProfileViewModel @Inject constructor(
+    savedStateHandle: SavedStateHandle,
+    private val userRepository: UserRepository
+) : ViewModel() {
+    
+    private val profile: Profile = savedStateHandle.toRoute<Profile>()
+    
+    val user: StateFlow<User?> = userRepository
+        .getUser(profile.userId)
+        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), null)
+}
+```
+
+### Complex Data: Pass IDs, Not Objects
+
+```kotlin
+// CORRECT: Pass only the ID
+navController.navigate(Profile(userId = "user123"))
+
+// In ViewModel, fetch from repository
+class ProfileViewModel(savedStateHandle: SavedStateHandle) : ViewModel() {
+    private val profile = savedStateHandle.toRoute<Profile>()
+    val user = userRepository.getUser(profile.userId)
+}
+
+// INCORRECT: Don't pass complex objects
+// navController.navigate(Profile(user = complexUserObject)) // BAD!
+```
+
+---
+
+## Deep Links
+
+### Define Deep Links
+
+```kotlin
+@Serializable
+data class Profile(val userId: String)
+
+composable<Profile>(
+    deepLinks = listOf(
+        navDeepLink<Profile>(basePath = "https://example.com/profile")
+    )
+) { backStackEntry ->
+    val profile: Profile = backStackEntry.toRoute()
+    ProfileScreen(userId = profile.userId)
+}
+```
+
+### Manifest Configuration
+
+```xml
+<activity android:name=".MainActivity">
+    <intent-filter>
+        <action android:name="android.intent.action.VIEW" />
+        <category android:name="android.intent.category.DEFAULT" />
+        <category android:name="android.intent.category.BROWSABLE" />
+        <data android:scheme="https" android:host="example.com" />
+    </intent-filter>
+</activity>
+```
+
+### Create PendingIntent for Notifications
+
+```kotlin
+val context = LocalContext.current
+val deepLinkIntent = Intent(
+    Intent.ACTION_VIEW,
+    "https://example.com/profile/user123".toUri(),
+    context,
+    MainActivity::class.java
+)
+
+val pendingIntent = TaskStackBuilder.create(context).run {
+    addNextIntentWithParentStack(deepLinkIntent)
+    getPendingIntent(0, PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE)
+}
+```
+
+---
+
+## Nested Navigation
+
+### Create Nested Graph
+
+```kotlin
+NavHost(navController = navController, startDestination = Home) {
+    composable<Home> { HomeScreen() }
+    
+    // Nested graph for authentication flow
+    navigation<AuthGraph>(startDestination = Login) {
+        composable<Login> {
+            LoginScreen(
+                onLoginSuccess = {
+                    navController.navigate(Home) {
+                        popUpTo<AuthGraph> { inclusive = true }
+                    }
+                }
+            )
+        }
+        composable<Register> { RegisterScreen() }
+        composable<ForgotPassword> { ForgotPasswordScreen() }
+    }
+}
+
+// Route definitions
+@Serializable object AuthGraph
+@Serializable object Login
+@Serializable object Register
+@Serializable object ForgotPassword
+```
+
+---
+
+## Adaptive Navigation
+
+Use `NavigationSuiteScaffold` for responsive navigation (bottom bar on phones, rail on tablets):
+
+```kotlin
+@Composable
+fun AdaptiveApp() {
+    val navController = rememberNavController()
+    val navBackStackEntry by navController.currentBackStackEntryAsState()
+    val currentDestination = navBackStackEntry?.destination
+    
+    NavigationSuiteScaffold(
+        navigationSuiteItems = {
+            item(
+                icon = { Icon(Icons.Default.Home, contentDescription = "Home") },
+                label = { Text("Home") },
+                selected = currentDestination?.hasRoute<Home>() == true,
+                onClick = { navController.navigate(Home) }
+            )
+            item(
+                icon = { Icon(Icons.Default.Settings, contentDescription = "Settings") },
+                label = { Text("Settings") },
+                selected = currentDestination?.hasRoute<Settings>() == true,
+                onClick = { navController.navigate(Settings()) }
+            )
+        }
+    ) {
+        AppNavHost(navController = navController)
+    }
+}
+```
+
+---
+
+## Testing
+
+### Setup
+
+```kotlin
+// build.gradle.kts
+androidTestImplementation("androidx.navigation:navigation-testing:2.8.5")
+```
+
+### Test Navigation
+
+```kotlin
+class NavigationTest {
+    @get:Rule
+    val composeTestRule = createComposeRule()
+    
+    private lateinit var navController: TestNavHostController
+    
+    @Before
+    fun setup() {
+        composeTestRule.setContent {
+            navController = TestNavHostController(LocalContext.current)
+            navController.navigatorProvider.addNavigator(ComposeNavigator())
+            AppNavHost(navController = navController)
+        }
+    }
+    
+    @Test
+    fun verifyStartDestination() {
+        composeTestRule
+            .onNodeWithText("Welcome")
+            .assertIsDisplayed()
+    }
+    
+    @Test
+    fun navigateToProfile_displaysProfileScreen() {
+        composeTestRule
+            .onNodeWithText("View Profile")
+            .performClick()
+        
+        assertTrue(
+            navController.currentBackStackEntry?.destination?.hasRoute<Profile>() == true
+        )
+    }
+}
+```
+
+---
+
+## Critical Rules
+
+### DO
+
+- Use `@Serializable` routes for type safety
+- Pass only IDs/primitives as arguments
+- Use `popUpTo` with `launchSingleTop` for bottom navigation
+- Extract `NavHost` to a separate composable for testability
+- Use `SavedStateHandle.toRoute<T>()` in ViewModels
+
+### DON'T
+
+- Pass complex objects as navigation arguments
+- Create `NavController` inside `NavHost`
+- Navigate in `LaunchedEffect` without proper keys
+- Forget `FLAG_IMMUTABLE` for PendingIntents (Android 12+)
+- Use string-based routes (legacy pattern)
+
+---
+
+## References
+
+- [Navigation with Compose](https://developer.android.com/develop/ui/compose/navigation)
+- [Type-Safe Navigation](https://developer.android.com/guide/navigation/design#compose)
+- [Pass Data Between Destinations](https://developer.android.com/guide/navigation/navigation-pass-data)
+- [Test Navigation](https://developer.android.com/guide/navigation/navigation-testing)

package/template/agent/skills/mobile-developer/references/android-rules/compose-performance-audit.md

@@ -0,0 +1,199 @@
+---
+name: compose-performance-audit
+description: Audit and improve Jetpack Compose runtime performance from code review and architecture. Use when asked to diagnose slow rendering, janky scrolling, excessive recompositions, or performance issues in Compose UI.
+---
+
+# Compose Performance Audit
+
+## Overview
+
+Audit Jetpack Compose view performance end-to-end, from instrumentation and baselining to root-cause analysis and concrete remediation steps.
+
+## Workflow Decision Tree
+
+- If the user provides code, start with "Code-First Review."
+- If the user only describes symptoms, ask for minimal code/context, then do "Code-First Review."
+- If code review is inconclusive, go to "Guide the User to Profile" and ask for Layout Inspector output or Perfetto traces.
+
+## 1. Code-First Review
+
+Collect:
+- Target Composable code.
+- Data flow: state, remember, derived state, ViewModel connections.
+- Symptoms and reproduction steps.
+
+Focus on:
+- **Recomposition storms** from unstable parameters or broad state changes.
+- **Unstable keys** in `LazyColumn`/`LazyRow` (`key` churn, missing keys).
+- **Heavy work in composition** (formatting, sorting, filtering, object allocation).
+- **Unnecessary recompositions** (missing `remember`, unstable classes, lambdas).
+- **Large images** without proper sizing or async loading.
+- **Layout thrash** (deep nesting, intrinsic measurements, `SubcomposeLayout` misuse).
+
+Provide:
+- Likely root causes with code references.
+- Suggested fixes and refactors.
+- If needed, a minimal repro or instrumentation suggestion.
+
+## 2. Guide the User to Profile
+
+Explain how to collect data:
+- Use **Layout Inspector** in Android Studio to see recomposition counts.
+- Enable **Recomposition Highlights** in Compose tooling.
+- Use **Perfetto** or **System Trace** for frame timing analysis.
+- Check **Macrobenchmark** results for startup/scroll metrics.
+
+Ask for:
+- Layout Inspector screenshot showing recomposition counts.
+- Perfetto trace or System Trace export.
+- Device/OS/build configuration (debug vs release).
+
+> **Important**: Ensure profiling is done on a **release build** with R8 enabled. Debug builds have significant overhead.
+
+## 3. Analyze and Diagnose
+
+Prioritize likely Compose culprits:
+- **Recomposition storms** from unstable parameters or broad state changes.
+- **Unstable keys** in lazy lists (`key` churn, index-based keys).
+- **Heavy work in composition** (formatting, sorting, object allocation).
+- **Missing `remember`** causing recreations on every recomposition.
+- **Large images** without `Modifier.size()` constraints.
+- **Unnecessary state reads** in wrong composition phases.
+
+Summarize findings with evidence from traces/Layout Inspector.
+
+## 4. Remediate
+
+Apply targeted fixes:
+- **Stabilize parameters**: Use `@Stable` or `@Immutable` annotations on data classes.
+- **Stabilize keys**: Use stable, unique IDs for `LazyColumn`/`LazyRow` items.
+- **Defer state reads**: Use `derivedStateOf`, lambda-based modifiers, or `Modifier.drawBehind`.
+- **Remember expensive computations**: Wrap in `remember { }` or `remember(key) { }`.
+- **Skip recomposition**: Extract stable composables, use `key()` to control identity.
+- **Async image loading**: Use Coil/Glide with proper sizing constraints.
+- **Reduce layout complexity**: Flatten hierarchies, avoid deep nesting.
+
+## Common Code Smells (and Fixes)
+
+### Unstable lambda captures
+
+```kotlin
+// BAD: New lambda instance every recomposition
+Button(onClick = { viewModel.doSomething(item) }) { ... }
+
+// GOOD: Use remember or method reference
+val onClick = remember(item) { { viewModel.doSomething(item) } }
+Button(onClick = onClick) { ... }
+```
+
+### Expensive work in composition
+
+```kotlin
+// BAD: Sorting on every recomposition
+@Composable
+fun ItemList(items: List<Item>) {
+    val sorted = items.sortedBy { it.name } // Runs every recomposition
+    LazyColumn { items(sorted) { ... } }
+}
+
+// GOOD: Use remember with key
+@Composable
+fun ItemList(items: List<Item>) {
+    val sorted = remember(items) { items.sortedBy { it.name } }
+    LazyColumn { items(sorted) { ... } }
+}
+```
+
+### Missing keys in LazyColumn
+
+```kotlin
+// BAD: Index-based identity (causes recomposition on list changes)
+LazyColumn {
+    items(items) { item -> ItemRow(item) }
+}
+
+// GOOD: Stable key-based identity
+LazyColumn {
+    items(items, key = { it.id }) { item -> ItemRow(item) }
+}
+```
+
+### Unstable data classes
+
+```kotlin
+// BAD: Unstable (contains List, which is not stable)
+data class UiState(
+    val items: List<Item>,
+    val isLoading: Boolean
+)
+
+// GOOD: Mark as Immutable if truly immutable
+@Immutable
+data class UiState(
+    val items: ImmutableList<Item>, // kotlinx.collections.immutable
+    val isLoading: Boolean
+)
+```
+
+### Reading state too early
+
+```kotlin
+// BAD: State read during composition (recomposes whole tree)
+@Composable
+fun AnimatedBox(scrollState: ScrollState) {
+    val offset = scrollState.value // Recomposes on every scroll
+    Box(modifier = Modifier.offset(y = offset.dp)) { ... }
+}
+
+// GOOD: Defer state read to layout/draw phase
+@Composable
+fun AnimatedBox(scrollState: ScrollState) {
+    Box(modifier = Modifier.offset {
+        IntOffset(0, scrollState.value) // Read in layout phase
+    }) { ... }
+}
+```
+
+### Object allocation in composition
+
+```kotlin
+// BAD: Creates new Modifier chain every recomposition
+Box(modifier = Modifier.padding(16.dp).background(Color.Red))
+
+// GOOD for dynamic modifiers: Remember the modifier
+val modifier = remember { Modifier.padding(16.dp).background(Color.Red) }
+Box(modifier = modifier)
+```
+
+## Stability Checklist
+
+| Type | Stable by Default? | Fix |
+|------|-------------------|-----|
+| Primitives (`Int`, `String`, `Boolean`) | Yes | N/A |
+| `data class` with stable fields | Yes* | Ensure all fields are stable |
+| `List`, `Map`, `Set` | **No** | Use `ImmutableList` from kotlinx |
+| Classes with `var` properties | **No** | Use `@Stable` if externally stable |
+| Lambdas | **No** | Use `remember { }` |
+
+## 5. Verify
+
+Ask the user to:
+- Re-run Layout Inspector and compare recomposition counts.
+- Run Macrobenchmark and compare frame timing.
+- Test on a real device with release build.
+
+Summarize the delta (recomposition count, frame drops, jank) if provided.
+
+## Outputs
+
+Provide:
+- A short metrics table (before/after if available).
+- Top issues (ordered by impact).
+- Proposed fixes with estimated effort.
+
+## References
+
+- [Jetpack Compose Performance](https://developer.android.com/develop/ui/compose/performance)
+- [Compose Stability Explained](https://developer.android.com/develop/ui/compose/performance/stability)
+- [Debugging Recomposition](https://developer.android.com/develop/ui/compose/tooling/layout-inspector)
+- [Macrobenchmark](https://developer.android.com/topic/performance/benchmarking/macrobenchmark-overview)

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

@@ -0,0 +1,49 @@
+---
+name: compose-ui
+description: Best practices for building UI with Jetpack Compose, focusing on state hoisting, detailed performance optimizations, and theming. Use this when writing or refactoring Composable functions.
+---
+
+# Jetpack Compose Best Practices
+
+## Instructions
+
+Follow these guidelines to create performant, reusable, and testable Composables.
+
+### 1. State Hoisting (Unidirectional Data Flow)
+Make Composables **stateless** whenever possible by moving state to the caller.
+
+*   **Pattern**: Function signature should usually look like:
+    ```kotlin
+    @Composable
+    fun MyComponent(
+        value: String,              // State flows down
+        onValueChange: (String) -> Unit, // Events flow up
+        modifier: Modifier = Modifier // Standard modifier parameter
+    )
+    ```
+*   **Benefit**: Decouples the UI from simple state storage, making it easier to preview and test.
+*   **ViewModel Integration**: The screen-level Composable retrieves state from the ViewModel (`viewModel.uiState.collectAsStateWithLifecycle()`) and passes it down.
+
+### 2. Modifiers
+*   **Default Parameter**: Always provide a `modifier: Modifier = Modifier` as the first optional parameter.
+*   **Application**: Apply this `modifier` to the *root* layout element of your Composable.
+*   **Ordering matters**: `padding().clickable()` is different from `clickable().padding()`. Generally apply layout-affecting modifiers (like padding) *after* click listeners if you want the padding to be clickable.
+
+### 3. Performance Optimization
+*   **`remember`**: Use `remember { ... }` to cache expensive calculations across recompositions.
+*   **`derivedStateOf`**: Use `derivedStateOf { ... }` when a state changes frequently (like scroll position) but the UI only needs to react to a threshold or summary (e.g., show "Jump to Top" button). This prevents unnecessary recompositions.
+    ```kotlin
+    val showButton by remember {
+        derivedStateOf { listState.firstVisibleItemIndex > 0 }
+    }
+    ```
+*   **Lambda Stability**: Prefer method references (e.g., `viewModel::onEvent`) or remembered lambdas to prevent unstable types from triggering recomposition of children.
+
+### 4. Theming and Resources
+*   Use `MaterialTheme.colorScheme` and `MaterialTheme.typography` instead of hardcoded colors or text styles.
+*   Organize simple UI components into specific files (e.g., `DesignSystem.kt` or `Components.kt`) if they are shared across features.
+
+### 5. Previews
+*   Create a private preview function for every public Composable.
+*   Use `@Preview(showBackground = true)` and include Light/Dark mode previews if applicable.
+*   Pass dummy data (static) to the stateless Composable for the preview.