mobile-ai-agents 1.0.23

package/agents/android/code-reviewer/example-output.md

@@ -0,0 +1,115 @@
+# Example Output — Android Code Reviewer
+
+Full agent response to the input in [`example-input.md`](example-input.md).
+
+---
+
+```
+REVIEW SUMMARY
+==============
+File: app/src/main/java/com/example/socialapp/ui/profile/ProfileViewModel.kt
+Layer: ViewModel
+Issues Found: 7
+Critical: 4  Warning: 2  Info: 1
+
+FINDINGS
+--------
+
+[CRITICAL] Line 19 — GlobalScope used instead of viewModelScope
+  Problem : GlobalScope is not tied to the ViewModel's lifecycle. When the ViewModel
+            is cleared (screen navigated away, process death), the coroutine continues
+            running, holding references to the ViewModel's LiveData and potentially the
+            Fragment. This is a guaranteed scope leak.
+  Fix     : Replace both GlobalScope.launch calls with viewModelScope.launch:
+            fun loadUser(userId: String) {
+                viewModelScope.launch {
+                    ...
+                }
+            }
+
+[CRITICAL] Line 20 — LiveData.value assigned from a background coroutine thread
+  Problem : GlobalScope.launch uses Dispatchers.Default by default. Calling
+            isLoading.value = true on a non-Main thread throws CalledFromWrongThreadException
+            in debug builds and causes silent data races in release builds.
+            LiveData.value can only be set from the Main thread; LiveData.postValue
+            is the background-safe alternative, but it introduces a delivery delay.
+  Fix     : Either switch the coroutine to the Main dispatcher:
+            viewModelScope.launch(Dispatchers.Main) { isLoading.value = true; ... }
+            Or migrate isLoading to MutableStateFlow and update it from any thread via .value.
+            The cleanest solution is viewModelScope.launch, which defaults to Main.
+
+[CRITICAL] Lines 22 & 42 — UserRepository instantiated directly inside ViewModel
+  Problem : new UserRepository() (or UserRepository() in Kotlin) constructs a concrete
+            dependency inside the ViewModel. This:
+            (1) makes the class impossible to unit-test without the real network/database,
+            (2) violates the Dependency Inversion Principle,
+            (3) creates a new repository instance on every function call, bypassing any
+                caching or connection pooling in the repository.
+  Fix     : Inject UserRepository via the constructor. With Hilt:
+            @HiltViewModel
+            class ProfileViewModel @Inject constructor(
+                private val userRepository: UserRepository
+            ) : ViewModel() { ... }
+            Then use userRepository.getUser(userId) instead of UserRepository().getUser(userId).
+
+[CRITICAL] Lines 36 & 38 — !! force-unwrap on user.value
+  Problem : user.value!! will throw NullPointerException if saveProfile() is called before
+            loadUser() completes, or if loadUser() failed with an error. The !! operator
+            should be treated as a code smell in production ViewModel code — it converts a
+            compile-time nullable into a runtime crash.
+  Fix     : Use safe navigation and an early return:
+            val currentUser = user.value ?: run {
+                errorMessage.value = "No user loaded"
+                return
+            }
+            val updated = User(id = currentUser.id, name = name, bio = bio,
+                               avatarUrl = currentUser.avatarUrl)
+
+[WARNING]  Line 34 — null check on non-nullable String (always false)
+  Problem : name == null is always false because name: String is non-nullable in Kotlin.
+            The compiler treats this as a warning. The intent was to guard against an empty
+            string, but the null check is dead code that misleads future readers.
+  Fix     : Replace with:
+            if (name.isBlank()) return
+            isBlank() checks for both empty and whitespace-only strings, which is the
+            correct guard for a user-facing name field.
+
+[WARNING]  Lines 13–15 — MutableLiveData exposed directly as public properties
+  Problem : Exposing MutableLiveData publicly allows any observer to call .value = ...
+            from outside the ViewModel, breaking the single-source-of-truth pattern and
+            making state mutations untraceable.
+  Fix     : Follow the backing property pattern:
+            private val _user = MutableLiveData<User>()
+            val user: LiveData<User> = _user
+
+            private val _isLoading = MutableLiveData<Boolean>()
+            val isLoading: LiveData<Boolean> = _isLoading
+
+[INFO]     Lines 13–15 — Consider migrating from LiveData to StateFlow
+  Problem : LiveData is lifecycle-aware but less composable than StateFlow and requires
+            Android framework classes (LifecycleOwner) to observe. For new ViewModels,
+            StateFlow + collectAsStateWithLifecycle() is the idiomatic Kotlin choice and
+            integrates directly with Jetpack Compose.
+  Fix     : private val _user = MutableStateFlow<User?>(null)
+            val user: StateFlow<User?> = _user.asStateFlow()
+            In the Fragment: collect with repeatOnLifecycle(STARTED).
+
+CLEAN ARCHITECTURE ASSESSMENT
+------------------------------
+Layer boundary respected: No
+  → UserRepository() is instantiated directly inside ViewModel. The ViewModel should
+    depend on an abstraction (interface), not a concrete repository implementation.
+    Inject via Hilt constructor injection.
+
+COROUTINE SAFETY
+----------------
+Scope leaks detected: Yes
+  → Two GlobalScope.launch calls (lines 19 and 41). Both must be replaced with
+    viewModelScope.launch. viewModelScope is automatically cancelled in onCleared().
+
+TESTABILITY SCORE: 1/10
+  → Direct UserRepository instantiation and GlobalScope make this class effectively
+    untestable. After applying the fixes, testability rises to ~8/10.
+
+OVERALL VERDICT: NEEDS WORK
+```

package/agents/android/compose-navigation/README.md

@@ -0,0 +1,76 @@
+# Android Compose Navigation Architect
+
+> Generate or review scalable Jetpack Compose navigation with type-safe routes, nested graphs, bottom navigation, deep links, and tests.
+
+---
+
+## What It Does
+
+- Generates Navigation Compose 2.8+ type-safe routes using `@Serializable`
+- Creates root and feature-level graph-builder extensions
+- Designs nested auth, onboarding, checkout, or other subflows
+- Implements bottom navigation with state restoration
+- Handles typed arguments through `toRoute<T>()`
+- Shows `SavedStateHandle.toRoute<T>()` for ViewModels
+- Defines deep-link and authentication behavior
+- Reviews duplicate routes, unsafe arguments, incorrect `popUpTo`, and back-stack bugs
+- Generates navigation tests
+
+---
+
+## Files
+
+| File | Purpose |
+|---|---|
+| [`agent.md`](agent.md) | Input/output contract and system prompt |
+| [`example-input.md`](example-input.md) | Real app navigation requirements |
+| [`example-output.md`](example-output.md) | Complete generated navigation architecture |
+
+---
+
+## Quick Start
+
+```text
+Use the agent at agents/android/compose-navigation/agent.md.
+
+MODE: GENERATE
+PACKAGE: com.example.shop
+NAVIGATION_VERSION: 2.8.9
+KOTLIN_VERSION: 2.0
+...
+```
+
+Install only this agent:
+
+```bash
+npx mobile-ai-agents add agent compose-navigation
+```
+
+---
+
+## Design Principles
+
+- Routes are types, not strings.
+- Screens expose callbacks, not `NavController`.
+- Feature modules own their internal destinations.
+- Route arguments contain IDs, not full objects.
+- Bottom tabs preserve independent state.
+- Back-stack changes are deliberate and documented.
+- Deep links are validated before privileged navigation.
+- Navigation behavior is covered by tests.
+
+---
+
+## Related Agents
+
+- [`compose-screen-builder`](../compose-screen-builder/) for screen implementation
+- [`compose-ui-reviewer`](../compose-ui-reviewer/) for UI quality
+- [`axiom`](../axiom/) for Android architecture review
+
+---
+
+## Official References
+
+- [Navigation with Compose](https://developer.android.com/develop/ui/compose/navigation)
+- [Type safety in Kotlin DSL and Navigation Compose](https://developer.android.com/guide/navigation/design/type-safety)
+- [Test Navigation](https://developer.android.com/guide/navigation/testing)

package/agents/android/compose-navigation/agent.md

@@ -0,0 +1,121 @@
+# NAVIGATOR — Android Compose Navigation Architect
+
+**Platform:** Android (Kotlin / Jetpack Compose / Navigation Compose)  
+**Personality:** Back-stack cartographer. Every destination has a type and every pop has a reason.  
+**Category:** Architecture / Code Generation / Code Review  
+**Complexity:** High  
+**Tested With:** GPT-5.4
+
+---
+
+## Purpose
+
+Designs or reviews scalable Jetpack Compose navigation using type-safe routes, nested feature graphs, bottom navigation, deep links, authentication gates, predictable back-stack behavior, and testable screen callbacks.
+
+---
+
+## Input Format
+
+```text
+MODE: <GENERATE | REVIEW>
+PACKAGE: <base package>
+NAVIGATION_VERSION: <version, e.g. 2.8.9>
+KOTLIN_VERSION: <version>
+MODULES: <single app module or module list>
+SCREENS:
+- <screen and arguments>
+FLOWS:
+- <navigation flow>
+BOTTOM_NAVIGATION:
+- <tab destinations or "none">
+DEEP_LINKS:
+- <URI and destination or "none">
+AUTH_RULES:
+- <authentication/onboarding conditions or "none">
+EXISTING_CODE:
+<required in REVIEW mode; optional in GENERATE mode>
+```
+
+---
+
+## Output Format
+
+````
+NAVIGATION ARCHITECTURE
+=======================
+Mode:
+Verdict: PASS | NEEDS WORK | GENERATED
+
+GRAPH
+-----
+<compact graph description>
+
+FILES
+-----
+## File: <path>
+```kotlin
+<complete code>
+```
+
+BACK-STACK RULES
+----------------
+<rules>
+
+DEEP-LINK RULES
+---------------
+<rules>
+
+TEST PLAN
+---------
+<tests>
+
+REVIEW FINDINGS
+---------------
+<findings or "Not applicable">
+
+DEPENDENCIES
+------------
+<Gradle dependencies>
+````
+
+---
+
+## System Prompt
+
+```text
+You are NAVIGATOR, a senior Android navigation architect specializing in Kotlin, Jetpack Compose, Navigation Compose, modularization, deep links, and back-stack correctness.
+
+Support GENERATE and REVIEW modes.
+
+Rules:
+1. For Navigation 2.8+, use @Serializable route objects/classes, composable<T>(), navigation<T>(), navigate(route), NavBackStackEntry.toRoute<T>(), and SavedStateHandle.toRoute<T>(). Do not generate hardcoded route strings.
+2. Pass stable identifiers only. Never pass repositories, ViewModels, mutable objects, or large domain objects as arguments.
+3. Screens receive typed callbacks such as onProductClick(id); do not pass NavController into leaf screens.
+4. Put routes and graph-builder extensions outside UI screen files. Use one feature navigation contract per module.
+5. Use nested graphs for self-contained flows such as auth, onboarding, checkout, and games.
+6. Bottom navigation must use launchSingleTop, restoreState, and popUpTo with saveState. Define reselection behavior explicitly.
+7. Authentication redirects must preserve the intended destination without putting authorization decisions in Composables.
+8. Deep links must validate hosts, paths, arguments, and authentication before privileged navigation.
+9. Explain popUpTo and inclusive choices. Prevent duplicate destinations and accidental stack clearing.
+10. Include navigation tests using TestNavHostController or an equivalent testable navigation surface.
+11. In REVIEW mode, assign CRITICAL, WARNING, or INFO and provide corrected code.
+12. If the project uses Navigation below 2.8, state the limitation and provide a migration plan before type-safe code.
+
+Return complete compilable Kotlin for the requested scope. Do not invent screens or flows.
+
+Output MUST follow the exact format specified. Do not add extra sections or omit any section.
+```
+
+---
+
+## Example
+
+See [`example-input.md`](example-input.md) and [`example-output.md`](example-output.md).
+
+---
+
+## Notes
+
+- Type-safe Navigation Compose APIs require Navigation 2.8.0 or newer and Kotlin Serialization.
+- The agent targets Navigation Compose 2.x. Navigation 3 should be requested explicitly because it uses a different architecture.
+- Complex payloads belong in repositories or saved state; routes carry IDs and small primitives.

package/agents/android/compose-navigation/example-input.md

@@ -0,0 +1,49 @@
+# Example Input
+
+```text
+MODE: GENERATE
+PACKAGE: com.example.catalog
+NAVIGATION_VERSION: 2.8.9
+KOTLIN_VERSION: 2.0
+MODULES:
+- :app
+- :feature:home
+- :feature:search
+- :feature:favorites
+- :feature:profile
+- :feature:product
+
+SCREENS:
+- Home — no arguments
+- Search — optional initialQuery: String
+- Favorites — no arguments
+- Profile — no arguments
+- Settings — no arguments
+- ProductDetail — productId: String
+- SignIn — optional redirectProductId: String
+
+FLOWS:
+- Home, Search, Favorites, and Profile are top-level destinations.
+- Product cards open ProductDetail.
+- Settings opens from Profile.
+- Unauthenticated users opening ProductDetail go to SignIn, then continue to ProductDetail.
+- Back from ProductDetail returns to the previous tab.
+
+BOTTOM_NAVIGATION:
+- Home
+- Search
+- Favorites
+- Profile
+
+DEEP_LINKS:
+- https://catalog.example.com/products/{productId} -> ProductDetail
+
+AUTH_RULES:
+- Home, Search, Favorites, and Profile are public.
+- ProductDetail requires authentication.
+- Preserve productId through sign-in.
+
+EXISTING_CODE:
+None.
+```
+

package/agents/android/compose-navigation/example-output.md

@@ -0,0 +1,325 @@
+# Example Output
+
+## Navigation Architecture
+
+Mode: `GENERATE`  
+Verdict: `GENERATED`
+
+### Graph
+
+```text
+AppGraph
+├── Home
+├── Search(initialQuery?)
+├── Favorites
+├── Profile
+├── Settings
+├── AuthGraph
+│   └── SignIn(redirectProductId?)
+└── ProductDetail(productId)
+```
+
+Top-level tabs are direct destinations so each tab can save and restore its state. Authentication is a nested graph because sign-in is a self-contained flow. Product navigation goes through an authentication-aware coordinator callback in the app layer.
+
+## Files
+
+### File: `app/navigation/AppRoute.kt`
+
+```kotlin
+package com.example.catalog.navigation
+
+import kotlinx.serialization.Serializable
+
+sealed interface AppRoute {
+    @Serializable
+    data object Home : AppRoute
+
+    @Serializable
+    data class Search(val initialQuery: String? = null) : AppRoute
+
+    @Serializable
+    data object Favorites : AppRoute
+
+    @Serializable
+    data object Profile : AppRoute
+
+    @Serializable
+    data object Settings : AppRoute
+
+    @Serializable
+    data class ProductDetail(val productId: String) : AppRoute
+
+    @Serializable
+    data object AuthGraph : AppRoute
+
+    @Serializable
+    data class SignIn(val redirectProductId: String? = null) : AppRoute
+}
+```
+
+### File: `app/navigation/TopLevelDestination.kt`
+
+```kotlin
+package com.example.catalog.navigation
+
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.outlined.FavoriteBorder
+import androidx.compose.material.icons.outlined.Home
+import androidx.compose.material.icons.outlined.Person
+import androidx.compose.material.icons.outlined.Search
+import androidx.compose.ui.graphics.vector.ImageVector
+
+enum class TopLevelDestination(
+    val route: AppRoute,
+    val label: String,
+    val icon: ImageVector,
+) {
+    HOME(AppRoute.Home, "Home", Icons.Outlined.Home),
+    SEARCH(AppRoute.Search(), "Search", Icons.Outlined.Search),
+    FAVORITES(AppRoute.Favorites, "Favorites", Icons.Outlined.FavoriteBorder),
+    PROFILE(AppRoute.Profile, "Profile", Icons.Outlined.Person),
+}
+```
+
+### File: `app/navigation/NavControllerExtensions.kt`
+
+```kotlin
+package com.example.catalog.navigation
+
+import androidx.navigation.NavGraph.Companion.findStartDestination
+import androidx.navigation.NavHostController
+
+fun NavHostController.navigateToTopLevel(
+    destination: TopLevelDestination,
+) {
+    navigate(destination.route) {
+        popUpTo(graph.findStartDestination().id) {
+            saveState = true
+        }
+        launchSingleTop = true
+        restoreState = true
+    }
+}
+```
+
+### File: `app/navigation/AppNavHost.kt`
+
+```kotlin
+package com.example.catalog.navigation
+
+import androidx.compose.runtime.Composable
+import androidx.navigation.NavHostController
+import androidx.navigation.compose.NavHost
+import androidx.navigation.compose.composable
+import androidx.navigation.navigation
+import androidx.navigation.toRoute
+import com.example.catalog.feature.favorites.FavoritesScreen
+import com.example.catalog.feature.home.HomeScreen
+import com.example.catalog.feature.product.ProductDetailScreen
+import com.example.catalog.feature.profile.ProfileScreen
+import com.example.catalog.feature.profile.SettingsScreen
+import com.example.catalog.feature.search.SearchScreen
+import com.example.catalog.feature.signin.SignInScreen
+
+@Composable
+fun AppNavHost(
+    navController: NavHostController,
+    isAuthenticated: () -> Boolean,
+) {
+    fun openProduct(productId: String) {
+        val route = if (isAuthenticated()) {
+            AppRoute.ProductDetail(productId)
+        } else {
+            AppRoute.SignIn(redirectProductId = productId)
+        }
+        navController.navigate(route)
+    }
+
+    NavHost(
+        navController = navController,
+        startDestination = AppRoute.Home,
+    ) {
+        composable<AppRoute.Home> {
+            HomeScreen(onProductClick = ::openProduct)
+        }
+
+        composable<AppRoute.Search> { entry ->
+            val route = entry.toRoute<AppRoute.Search>()
+            SearchScreen(
+                initialQuery = route.initialQuery,
+                onProductClick = ::openProduct,
+            )
+        }
+
+        composable<AppRoute.Favorites> {
+            FavoritesScreen(onProductClick = ::openProduct)
+        }
+
+        composable<AppRoute.Profile> {
+            ProfileScreen(
+                onSettingsClick = {
+                    navController.navigate(AppRoute.Settings)
+                },
+            )
+        }
+
+        composable<AppRoute.Settings> {
+            SettingsScreen(onBack = navController::navigateUp)
+        }
+
+        composable<AppRoute.ProductDetail>(
+            deepLinks = listOf(
+                androidx.navigation.navDeepLink<AppRoute.ProductDetail>(
+                    basePath = "https://catalog.example.com/products",
+                ),
+            ),
+        ) { entry ->
+            val route = entry.toRoute<AppRoute.ProductDetail>()
+            ProductDetailScreen(
+                productId = route.productId,
+                onBack = navController::navigateUp,
+            )
+        }
+
+        navigation<AppRoute.AuthGraph>(
+            startDestination = AppRoute.SignIn(),
+        ) {
+            composable<AppRoute.SignIn> { entry ->
+                val route = entry.toRoute<AppRoute.SignIn>()
+                SignInScreen(
+                    onSignedIn = {
+                        val redirect = route.redirectProductId
+                        if (redirect == null) {
+                            navController.popBackStack()
+                        } else {
+                            navController.navigate(
+                                AppRoute.ProductDetail(redirect),
+                            ) {
+                                popUpTo<AppRoute.SignIn> {
+                                    inclusive = true
+                                }
+                            }
+                        }
+                    },
+                    onCancel = navController::navigateUp,
+                )
+            }
+        }
+    }
+}
+```
+
+### File: `feature/product/ProductDetailViewModel.kt`
+
+```kotlin
+package com.example.catalog.feature.product
+
+import androidx.lifecycle.SavedStateHandle
+import androidx.lifecycle.ViewModel
+import androidx.navigation.toRoute
+import com.example.catalog.navigation.AppRoute
+import dagger.hilt.android.lifecycle.HiltViewModel
+import javax.inject.Inject
+
+@HiltViewModel
+class ProductDetailViewModel @Inject constructor(
+    savedStateHandle: SavedStateHandle,
+) : ViewModel() {
+    private val route = savedStateHandle.toRoute<AppRoute.ProductDetail>()
+
+    val productId: String = route.productId
+}
+```
+
+### File: `app/navigation/AppNavigationTest.kt`
+
+```kotlin
+package com.example.catalog.navigation
+
+import androidx.compose.ui.test.junit4.createComposeTestRule
+import androidx.navigation.compose.ComposeNavigator
+import androidx.navigation.hasRoute
+import androidx.navigation.testing.TestNavHostController
+import androidx.test.core.app.ApplicationProvider
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Rule
+import org.junit.Test
+
+class AppNavigationTest {
+    @get:Rule
+    val composeRule = createComposeTestRule()
+
+    private lateinit var navController: TestNavHostController
+
+    @Before
+    fun setUp() {
+        navController = TestNavHostController(
+            ApplicationProvider.getApplicationContext(),
+        ).apply {
+            navigatorProvider.addNavigator(ComposeNavigator())
+        }
+    }
+
+    @Test
+    fun startsOnHome() {
+        composeRule.setContent {
+            AppNavHost(
+                navController = navController,
+                isAuthenticated = { true },
+            )
+        }
+
+        assertTrue(
+            navController.currentBackStackEntry
+                ?.destination
+                ?.hasRoute<AppRoute.Home>() == true,
+        )
+    }
+}
+```
+
+## Back-Stack Rules
+
+1. Top-level tab navigation saves and restores state.
+2. `launchSingleTop` prevents duplicate tab destinations.
+3. Product detail is pushed above the current tab, so back returns to that tab.
+4. Successful sign-in removes only `SignIn`, then opens the preserved product.
+5. Settings is pushed above Profile and uses `navigateUp()`.
+
+## Deep-Link Rules
+
+1. Accept only the HTTPS host `catalog.example.com`.
+2. Parse `productId` through the typed route.
+3. Validate that `productId` is non-blank before loading data.
+4. If unauthenticated, preserve the ID and enter `AuthGraph`.
+5. Do not trust client navigation as authorization; the backend must enforce access.
+
+## Test Plan
+
+- Verify the graph starts on Home.
+- Verify tapping a product opens typed `ProductDetail`.
+- Verify unauthenticated product navigation opens SignIn.
+- Verify successful sign-in removes SignIn and opens the intended product.
+- Verify switching tabs restores scroll/state and does not duplicate tabs.
+- Verify back from ProductDetail returns to the originating tab.
+- Verify the HTTPS product deep link opens the correct product.
+- Verify malformed or blank product IDs show a safe error state.
+
+## Review Findings
+
+Not applicable.
+
+## Dependencies
+
+```kotlin
+plugins {
+    kotlin("plugin.serialization")
+}
+
+dependencies {
+    implementation("androidx.navigation:navigation-compose:2.8.9")
+    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3")
+    androidTestImplementation("androidx.navigation:navigation-testing:2.8.9")
+}
+```