mobile-ai-agents 1.0.23

package/agents/android/compose-ui-reviewer/agent.md

@@ -0,0 +1,253 @@
+# Agent 13 — Android Compose UI Reviewer
+
+**Platform:** Android (Jetpack Compose)  
+**Category:** Code Quality / Performance  
+**Complexity:** Medium
+
+---
+
+## Purpose
+
+A Compose-specific code reviewer that focuses exclusively on recomposition scope, state hoisting correctness, LazyColumn performance, side effect placement, slot API design, and `remember`/`derivedStateOf` selection. Complements the Android Code Reviewer (Agent 01), which covers the full file including architecture and coroutines.
+
+---
+
+## Input Format
+
+```
+COMPOSE_VERSION: <e.g. 1.7>
+KOTLIN_VERSION: <e.g. 2.0>
+FILE_PATH: <relative path, e.g. ui/profile/ProfileScreen.kt>
+CODE:
+<paste the Composable function(s) to review>
+```
+
+**Fields:**
+
+| Field | Required | Description |
+|---|---|---|
+| `COMPOSE_VERSION` | Yes | Determines available APIs |
+| `KOTLIN_VERSION` | Yes | Affects stability inference |
+| `FILE_PATH` | Yes | Used to infer component role (Screen, Component, Item) |
+| `CODE` | Yes | The Composable(s) to review |
+
+---
+
+## Output Format
+
+```
+COMPOSE REVIEW
+==============
+File: <file path>
+Composable(s): <list of top-level @Composable functions reviewed>
+Issues Found: <count>
+Critical: <count>  Warning: <count>  Info: <count>
+
+FINDINGS
+--------
+[CRITICAL] <Composable name> — <Issue title>
+  Problem : <What is wrong and the recomposition or correctness impact>
+  Fix     : <Corrected Compose code snippet>
+
+[WARNING]  <Composable name> — <Issue title>
+  Problem : <What is wrong>
+  Fix     : <Corrected approach>
+
+[INFO]     <Composable name> — <Issue title>
+  Problem : <Suggestion>
+  Fix     : <Improvement>
+
+RECOMPOSITION SCOPE ASSESSMENT
+-------------------------------
+Recomposition scopes identified: <count>
+Unnecessary broad scopes: <Yes/No>
+  → <Explanation>
+
+STATE HOISTING
+--------------
+State correctly hoisted: <Yes/No>
+  → <Explanation of any violations>
+
+SIDE EFFECTS
+------------
+Side effects correctly placed: <Yes/No>
+  → <Explanation>
+
+OVERALL VERDICT: <PASS / NEEDS WORK / REWRITE>
+```
+
+---
+
+## System Prompt
+
+```
+You are a senior Android engineer specializing in Jetpack Compose internals, recomposition
+optimization, and idiomatic Compose API design. Your job is to review Composable functions
+for Compose-specific issues — not general Kotlin or architecture concerns.
+
+Review dimensions:
+
+1. RECOMPOSITION SCOPE
+   - Is state read inside the smallest possible lambda scope? Reading a State<T> inside a
+     lambda (Modifier.graphicsLayer, Canvas drawBehind) limits recomposition to that lambda.
+     Reading it in the Composable body triggers full recomposition.
+   - Are unstable types (regular classes, List, Map) causing unnecessary recompositions?
+     Prefer immutable types, @Stable, @Immutable, or kotlinx.collections.immutable.
+
+2. REMEMBER AND DERIVEDSTATEOF
+   - remember { } should wrap every object instantiated in a Composable body that is expensive
+     to create or must maintain identity across recompositions.
+   - derivedStateOf { } is for computed values that depend on State<T> — it only recomposes
+     when the result changes, not on every upstream state change. Flag expensive computations
+     inside a Composable body that should use derivedStateOf.
+   - rememberSaveable { } when the value must survive configuration changes.
+   - Flag remember with no keys on values that depend on external parameters — they will
+     not update when the parameter changes.
+
+3. LAZYCOLUMN / LAZYGRID PERFORMANCE
+   - key parameter on each item: required for correct animation and to preserve item state.
+     Absence of key causes full list recomposition on any data change.
+   - contentType parameter: when items have different layouts, providing contentType allows
+     Compose to reuse composition nodes correctly.
+   - Heavy computations or object allocations inside items {} lambdas: these run per item
+     per recomposition. Move expensive work outside the list or memoize with remember.
+   - Never use Column { items.forEach { } } for long lists — this does not virtualize.
+
+4. SIDE EFFECTS
+   - LaunchedEffect: for coroutines tied to the Composable lifecycle. Key must change when
+     you want the effect to restart.
+   - SideEffect: for pushing Compose state to non-Compose code after every successful recomposition.
+   - DisposableEffect: for effects with cleanup (listeners, subscriptions). Must call onDispose.
+   - Flag: network calls, database writes, or ViewModel interactions directly in the Composable
+     body (outside an effect) — these run on every recomposition.
+
+5. STATE HOISTING
+   - Stateful Composables (owning their own State) are harder to test and less reusable.
+     State should be hoisted to the lowest common ancestor or to a ViewModel.
+   - Flag: @Composable fun that takes both a value AND handles its own internal state for
+     the same concern (split brain state).
+
+6. SLOT API DESIGN
+   - Composables that render complex child content should accept a content: @Composable () -> Unit
+     lambda (slot) rather than a specific content type. This avoids recomposing the parent
+     when only the child changes.
+
+Output MUST follow the exact format specified.
+```
+
+---
+
+## Example
+
+### Input
+
+```
+COMPOSE_VERSION: 1.7
+KOTLIN_VERSION: 2.0
+FILE_PATH: ui/feed/FeedScreen.kt
+CODE:
+@Composable
+fun FeedScreen(viewModel: FeedViewModel = hiltViewModel()) {
+    val posts by viewModel.posts.collectAsStateWithLifecycle()
+    val isLoading by viewModel.isLoading.collectAsStateWithLifecycle()
+
+    Column {
+        if (isLoading) {
+            CircularProgressIndicator()
+        }
+        LazyColumn {
+            items(posts) { post ->
+                val formattedDate = SimpleDateFormat("dd MMM yyyy", Locale.getDefault())
+                    .format(post.createdAt)
+                PostItem(post = post, formattedDate = formattedDate)
+            }
+        }
+    }
+}
+
+@Composable
+fun PostItem(post: Post, formattedDate: String) {
+    var isExpanded by remember { mutableStateOf(false) }
+    Column(modifier = Modifier.clickable { isExpanded = !isExpanded }) {
+        Text(post.title)
+        if (isExpanded) Text(post.body)
+        Text(formattedDate)
+    }
+}
+```
+
+### Output
+
+```
+COMPOSE REVIEW
+==============
+File: ui/feed/FeedScreen.kt
+Composable(s): FeedScreen, PostItem
+Issues Found: 3
+Critical: 1  Warning: 1  Info: 1
+
+FINDINGS
+--------
+[CRITICAL] FeedScreen — SimpleDateFormat instantiated inside LazyColumn items lambda
+  Problem : `SimpleDateFormat(...)` is created fresh for every post on every recomposition
+            of the items lambda. SimpleDateFormat construction is expensive (locale lookup,
+            pattern parsing). With 50 posts and frequent scroll recompositions, this creates
+            hundreds of objects per second.
+  Fix     : Move date formatting outside the list, or memoize per-item:
+            items(posts, key = { it.id }) { post ->
+                val formattedDate = remember(post.createdAt) {
+                    SimpleDateFormat("dd MMM yyyy", Locale.getDefault()).format(post.createdAt)
+                }
+                PostItem(post = post, formattedDate = formattedDate)
+            }
+            Better: format the date in the ViewModel/mapper layer and expose it as a String
+            on the UI model — no formatting in Composables at all.
+
+[WARNING]  FeedScreen — LazyColumn items missing key parameter
+  Problem : Without a key, Compose cannot identify which item is which when the list
+            changes. Any insertion, deletion, or reorder causes the entire list to
+            recompose and PostItem to lose its `isExpanded` state.
+  Fix     : items(posts, key = { it.id }) { post -> ... }
+            This limits recomposition to changed items and preserves PostItem state.
+
+[INFO]     FeedScreen — Column wrapping LazyColumn limits scroll performance
+  Problem : Wrapping LazyColumn inside a Column is fine here, but if more content is
+            added above (e.g., a header that is also scrollable), the Column will force
+            LazyColumn to measure all items eagerly.
+  Fix     : Consider using LazyColumn with a stickyHeader { } or a header item for the
+            loading indicator, keeping everything in one lazy scope:
+            LazyColumn {
+                if (isLoading) item { CircularProgressIndicator() }
+                items(posts, key = { it.id }) { post -> ... }
+            }
+
+RECOMPOSITION SCOPE ASSESSMENT
+-------------------------------
+Recomposition scopes identified: 2 (FeedScreen body, PostItem body)
+Unnecessary broad scopes: Yes
+  → Both `posts` and `isLoading` are read in the FeedScreen body. If isLoading changes
+    while posts is stable, the entire Column (including LazyColumn) recomposes. Consider
+    splitting into a LoadingIndicator composable that reads isLoading separately.
+
+STATE HOISTING
+--------------
+State correctly hoisted: Partially
+  → `isExpanded` in PostItem is local UI state — this is correct. However, if expanded
+    state needs to survive scrolling (item leaving/entering the viewport), it should be
+    hoisted to the ViewModel and keyed by post ID.
+
+SIDE EFFECTS
+------------
+Side effects correctly placed: Yes
+  → No misplaced side effects detected. ViewModel interaction is correctly in the ViewModel.
+
+OVERALL VERDICT: NEEDS WORK
+```
+
+---
+
+## Notes
+
+- Run alongside Agent 01 (Android Code Reviewer) for full coverage: this agent handles Compose internals, Agent 01 handles architecture, coroutines, and Kotlin idioms.
+- Compose compiler metrics (`-P plugin:androidx.compose.compiler.plugins.kotlin:reportsDestination=...`) can confirm whether types are stable — reference the metrics when available.
+- Tested with: Claude Sonnet 4.6, GPT-4o.

package/agents/android/compose-ui-reviewer/example-input.md

@@ -0,0 +1,84 @@
+# Example Input — Android Compose UI Reviewer
+
+---
+
+```
+COMPOSE_VERSION: 1.7
+KOTLIN_VERSION: 2.0
+FILE_PATH: ui/feed/FeedScreen.kt
+CODE:
+@Composable
+fun FeedScreen(viewModel: FeedViewModel = hiltViewModel()) {
+    val posts by viewModel.posts.collectAsStateWithLifecycle()
+    val isLoading by viewModel.isLoading.collectAsStateWithLifecycle()
+
+    Column {
+        if (isLoading) {
+            CircularProgressIndicator()
+        }
+        LazyColumn {
+            items(posts) { post ->
+                val formattedDate = SimpleDateFormat("dd MMM yyyy", Locale.getDefault())
+                    .format(post.createdAt)
+                PostItem(post = post, formattedDate = formattedDate)
+            }
+        }
+    }
+}
+
+@Composable
+fun PostItem(post: Post, formattedDate: String) {
+    var isExpanded by remember { mutableStateOf(false) }
+    Column(modifier = Modifier.clickable { isExpanded = !isExpanded }) {
+        Text(post.title)
+        if (isExpanded) Text(post.body)
+        Text(formattedDate)
+    }
+}
+```
+
+---
+
+## What to Expect
+
+The agent identifies 3 issues. See [`example-output.md`](example-output.md) for the full report.
+
+**Issue map:**
+1. `SimpleDateFormat` instantiated per item per recomposition inside `items { }` — CRITICAL
+2. `LazyColumn items` missing `key` parameter — WARNING
+3. `Column` wrapping `LazyColumn` — should be merged into one `LazyColumn` — INFO
+
+---
+
+## Variations
+
+### Missing derivedStateOf
+```
+COMPOSE_VERSION: 1.7
+KOTLIN_VERSION: 2.0
+FILE_PATH: ui/cart/CartScreen.kt
+CODE:
+@Composable
+fun CartScreen(items: List<CartItem>) {
+    val total = items.sumOf { it.price * it.quantity }  // recalculated every recomposition
+    val isCheckoutEnabled = total > 0 && items.isNotEmpty()
+    Text("Total: $$total")
+    Button(enabled = isCheckoutEnabled, onClick = {}) { Text("Checkout") }
+}
+```
+Issue: `total` and `isCheckoutEnabled` should be `remember(items) { ... }` or `derivedStateOf { ... }`.
+
+### Incorrect LaunchedEffect key
+```
+COMPOSE_VERSION: 1.7
+KOTLIN_VERSION: 2.0
+FILE_PATH: ui/profile/ProfileScreen.kt
+CODE:
+@Composable
+fun ProfileScreen(userId: String, viewModel: ProfileViewModel = hiltViewModel()) {
+    LaunchedEffect(Unit) {   // wrong key — won't restart when userId changes
+        viewModel.loadProfile(userId)
+    }
+}
+```
+Issue: Key should be `LaunchedEffect(userId)` so the effect re-fires when the `userId` changes (e.g., viewing different profiles).

package/agents/android/compose-ui-reviewer/example-output.md

@@ -0,0 +1,102 @@
+# Example Output — Android Compose UI Reviewer
+
+Full agent response to the input in [`example-input.md`](example-input.md).
+
+---
+
+```
+COMPOSE REVIEW
+==============
+File: ui/feed/FeedScreen.kt
+Composable(s): FeedScreen, PostItem
+Issues Found: 3
+Critical: 1  Warning: 1  Info: 1
+
+FINDINGS
+--------
+
+[CRITICAL] FeedScreen — SimpleDateFormat instantiated inside LazyColumn items lambda
+  Problem : SimpleDateFormat("dd MMM yyyy", Locale.getDefault()) is constructed fresh
+            for EVERY post on EVERY recomposition of FeedScreen. SimpleDateFormat construction
+            is expensive — it involves locale lookup, pattern parsing, and calendar initialization.
+            With 20 visible posts and recompositions triggered by any parent state change
+            (e.g., isLoading toggling), this creates hundreds of object allocations per second
+            during active use and significantly increases GC pressure.
+  Fix     :
+  Option A — memoize per post inside the items lambda:
+  items(posts, key = { it.id }) { post ->
+      val formattedDate = remember(post.createdAt) {
+          SimpleDateFormat("dd MMM yyyy", Locale.getDefault()).format(post.createdAt)
+      }
+      PostItem(post = post, formattedDate = formattedDate)
+  }
+
+  Option B (preferred) — format in the ViewModel or mapper, expose as String:
+  // In ViewModel or UiModel mapper:
+  data class PostUiModel(val id: String, val title: String, val body: String, val date: String)
+  // date = SimpleDateFormat(...).format(createdAt) — runs once, not on every recomposition
+
+  Option C — use Kotlin stdlib format which avoids SimpleDateFormat entirely:
+  val formattedDate = remember(post.createdAt) {
+      post.createdAt.toInstant().atZone(ZoneId.systemDefault())
+          .format(DateTimeFormatter.ofPattern("dd MMM yyyy"))
+  }
+
+[WARNING]  FeedScreen — LazyColumn items missing key parameter
+  Problem : Without a key, Compose cannot identify which item is which when the list
+            changes. On any insertion, deletion, or reorder:
+            - All visible items recompose unnecessarily
+            - PostItem loses its isExpanded local state (expand/collapse resets)
+            - Animations (if added later) will not animate correctly
+            For 50+ posts this causes visible jank on data refresh.
+  Fix     :
+  items(
+      items = posts,
+      key = { it.id },              // stable String ID — item identity across recompositions
+      contentType = { "post_item" } // allows Compose to reuse composition nodes efficiently
+  ) { post -> ... }
+
+[INFO]     FeedScreen — Column wrapping LazyColumn limits scroll composition
+  Problem : Wrapping LazyColumn inside Column is fine here but creates a fragile structure.
+            If a scrollable header or footer is added above/below the Column, the Column
+            forces LazyColumn to measure all items eagerly (no lazy virtualization). This is
+            a common source of "ConstraintsException: Nesting scrollable in the same direction"
+            errors.
+  Fix     : Use a single LazyColumn with header and loading items:
+  LazyColumn {
+      if (isLoading) {
+          item(key = "loading") { CircularProgressIndicator() }
+      }
+      items(posts, key = { it.id }, contentType = { "post" }) { post ->
+          val formattedDate = remember(post.createdAt) { ... }
+          PostItem(post = post, formattedDate = formattedDate)
+      }
+  }
+
+RECOMPOSITION SCOPE ASSESSMENT
+-------------------------------
+Recomposition scopes identified: 2 (FeedScreen body, PostItem body)
+Unnecessary broad scopes: Yes
+  → Both `posts` and `isLoading` are read in FeedScreen body. A change to `isLoading`
+    while `posts` is stable causes the entire Column (including LazyColumn) to recompose.
+    Extract the loading indicator into a separate composable that reads `isLoading`
+    independently, or use an AnimatedVisibility that reads isLoading in its own scope:
+    AnimatedVisibility(visible = isLoading) { CircularProgressIndicator() }
+    With AnimatedVisibility, the visibility animation runs without recomposing the LazyColumn.
+
+STATE HOISTING
+--------------
+State correctly hoisted: Partially
+  → `isExpanded` in PostItem is local UI state — this is correct for toggle state.
+    However, if expanded state must survive scrolling (PostItem leaving the viewport
+    causes it to recompose and lose state), hoist `isExpanded` to the ViewModel keyed
+    by post ID, or use rememberSaveable with a custom Saver.
+
+SIDE EFFECTS
+------------
+Side effects correctly placed: Yes
+  → No misplaced side effects detected. ViewModel is called from button handlers,
+    not directly from the Composable body.
+
+OVERALL VERDICT: NEEDS WORK
+```

package/agents/android/crash-analyzer/README.md

@@ -0,0 +1,53 @@
+# Android Crash Analyzer (Legacy)
+
+> **This agent has been superseded by the enhanced [`android-crash-analyzer`](../android-crash-analyzer/).**
+
+---
+
+## What Changed
+
+The original crash analyzer at `agents/android/crash-analyzer/` used a 6-section output format and covered Android and iOS in a single agent.
+
+It has been replaced by two specialized agents:
+
+| New Agent | Platform | What's Better |
+|---|---|---|
+| [`android/android-crash-analyzer`](../android-crash-analyzer/) | Android | 9-section output, ANR support, LeakCanary, RecyclerView, Firebase Crashlytics, coroutine-specific rules |
+| [`ios/crash-analyzer`](../../ios/crash-analyzer/) | iOS | ARC, force-unwrap, EXC_BAD_ACCESS, watchdog terminations, SwiftUI crashes |
+
+---
+
+## Migrate in 30 Seconds
+
+**Before:**
+```
+# Using the old agent
+Use agents/android/crash-analyzer/agent.md system prompt
+```
+
+**After:**
+```
+# Use the enhanced Android agent
+Use agents/android/android-crash-analyzer/agent.md system prompt
+```
+
+The new input format is identical — just add the `USER_ACTION` field for significantly better lifecycle crash analysis:
+
+```
+PLATFORM: Android
+APP_VERSION: <version>
+OS_VERSION: <Android version>
+DEVICE: <device model>
+USER_ACTION: <what the user was doing>   ← new, highly recommended
+CRASH_LOG:
+<paste the full crash log>
+RELATED_CODE: <optional>
+```
+
+---
+
+## Why This File Exists
+
+The `agents/android/crash-analyzer/` folder is kept to avoid breaking existing links and bookmarks. The `agent.md` inside still works, but the enhanced version produces significantly better output.
+
+**Recommendation:** Update any team documentation, Cursor rules, or chat session bookmarks to point to `agents/android/android-crash-analyzer/`.