mobile-ai-agents 1.0.23

package/agents/android/compose-screen-builder/README.md

@@ -0,0 +1,95 @@
+# Android Compose Screen Builder Agent
+
+> Describe a screen. Get a complete, production-ready Jetpack Compose implementation — ViewModel, StateFlow, Navigation, Material 3, Clean Architecture wiring, and all.
+
+---
+
+## What This Agent Does
+
+Takes a plain-English screen description and returns a full, compilable Kotlin implementation including:
+
+- `@Composable` screen function with Material 3 components
+- `ViewModel` with `StateFlow`-based UI state
+- Sealed `UiState` class with `Loading`, `Success`, and `Error` states
+- `collectAsStateWithLifecycle()` for lifecycle-safe collection
+- `NavController` integration with typed navigation arguments
+- Accessibility semantics and dark-mode theming
+- `@Preview` annotations (light + dark)
+- Hilt `@HiltViewModel` dependency injection setup
+- Clean Architecture layer boundaries respected
+
+---
+
+## When to Use
+
+- Starting a new screen from scratch
+- Converting a design mockup or Figma spec into Compose code
+- Generating boilerplate so you can focus on business logic
+- Onboarding a developer to your Compose + Clean Architecture patterns
+
+---
+
+## Files
+
+| File | Purpose |
+|---|---|
+| [`agent.md`](agent.md) | Input format, output format, full system prompt |
+| [`example-input.md`](example-input.md) | Real screen description ready to paste |
+| [`example-output.md`](example-output.md) | Full generated screen implementation |
+
+---
+
+## Quick Start
+
+```
+# Claude Code session:
+Use the system prompt from agents/android/compose-screen-builder/agent.md
+Then describe your screen using the input format.
+```
+
+---
+
+## Input Format
+
+```
+SCREEN_NAME: <e.g. OrderHistoryScreen>
+DESCRIPTION: <plain-English description of the screen>
+STATE_FIELDS: <list of data fields the screen displays>
+ACTIONS: <list of user actions the screen supports>
+NAVIGATION: <where this screen navigates to, and what params it receives>
+DEPENDENCIES: <optional — Hilt modules, repository names already in your project>
+COMPOSE_VERSION: <e.g. 1.7>
+KOTLIN_VERSION: <e.g. 2.0>
+```
+
+---
+
+## What Gets Generated
+
+```
+screen/
+├── <ScreenName>Screen.kt       — @Composable screen + sub-composables + Previews
+├── <ScreenName>ViewModel.kt    — @HiltViewModel + StateFlow + use case calls
+└── <ScreenName>UiState.kt      — sealed UiState, UiEvent (optional)
+```
+
+---
+
+## Design Principles
+
+Every generated screen follows these non-negotiables:
+
+- **No business logic in Composables.** Data fetching, transformation, and decisions live in the ViewModel or below.
+- **Single source of truth.** One sealed `UiState` drives the entire screen. No parallel boolean flags (`isLoading`, `hasError`, `isEmpty`).
+- **Lifecycle-safe collection.** `collectAsStateWithLifecycle()` (not `collectAsState()`) throughout.
+- **Stable keys.** `LazyColumn` items always have `key = { it.id }`.
+- **Material 3 theming.** All colors, typography, and shapes from `MaterialTheme`. No hardcoded hex.
+- **Accessibility.** `contentDescription` on all icons, minimum 48dp tap targets, `Semantics` on custom components.
+
+---
+
+## Related Agents
+
+- [`agents/android/code-reviewer`](../code-reviewer/) — review the generated code for issues
+- [`agents/android/compose-ui-reviewer`](../compose-ui-reviewer/) — Compose-specific review
+- [`agents/android/android-crash-analyzer`](../android-crash-analyzer/) — debug crashes in generated screens

package/agents/android/compose-screen-builder/agent.md

@@ -0,0 +1,170 @@
+# Agent — Android Compose Screen Builder
+
+**Platform:** Android (Kotlin / Jetpack Compose / Material 3)  
+**Category:** UI & Design / Code Generation  
+**Complexity:** High  
+**Tested With:** Claude Sonnet 4.6, GPT-4o
+
+---
+
+## Purpose
+
+Generates a complete, production-ready Jetpack Compose screen implementation from a plain-English description. Output includes the `@Composable` screen function, `@HiltViewModel`, sealed `UiState`, navigation wiring, previews, and Clean Architecture layer boundaries.
+
+---
+
+## Input Format
+
+```
+SCREEN_NAME: <PascalCase screen name, e.g. OrderHistoryScreen>
+DESCRIPTION:
+<Plain-English description of the screen. Include:
+  - What data is displayed (lists, cards, text fields, images)
+  - What interactive elements exist (buttons, swipe, pull-to-refresh, FAB)
+  - Loading, empty, and error states
+  - Any animations or transitions>
+STATE_FIELDS:
+<List of data fields the screen displays. Each on its own line:
+  - fieldName: Type — description>
+ACTIONS:
+<List of user actions the screen handles. Each on its own line:
+  - Action name — what it does>
+NAVIGATION:
+<Describe navigation. Examples:
+  - Receives: userId: String from the previous screen
+  - Navigates to: OrderDetailScreen(orderId: String) on item tap
+  - Navigates up: on toolbar back press>
+DEPENDENCIES:
+<optional — names of repositories, use cases, or Hilt modules already in the project>
+COMPOSE_VERSION: <e.g. 1.7>
+KOTLIN_VERSION: <e.g. 2.0>
+```
+
+---
+
+## Output Format
+
+The agent returns three complete Kotlin files:
+
+````
+## File: <ScreenName>UiState.kt
+```kotlin
+<sealed UiState class + data classes>
+```
+
+## File: <ScreenName>ViewModel.kt
+```kotlin
+<@HiltViewModel with StateFlow, use case injection, and event handling>
+```
+
+## File: <ScreenName>Screen.kt
+```kotlin
+<@Composable screen + all sub-composables + @Preview annotations>
+```
+
+## Navigation Registration
+```kotlin
+<NavHost composable { } block to add to your NavGraph>
+```
+
+## Gradle Dependencies
+<Any new dependencies required, or "No new dependencies required">
+````
+
+---
+
+## System Prompt
+
+```
+You are a senior Android engineer specializing in Jetpack Compose, Material 3, Hilt, and
+Clean Architecture. Your job is to generate complete, production-ready Android Compose screen
+implementations from plain-English descriptions.
+
+OUTPUT: Three complete Kotlin files:
+1. <ScreenName>UiState.kt — sealed state class
+2. <ScreenName>ViewModel.kt — @HiltViewModel
+3. <ScreenName>Screen.kt — @Composable screen
+
+RULES FOR UiState.kt:
+- Use a single sealed class with exactly these variants unless the screen requires more:
+  sealed class <Name>UiState {
+      object Loading : <Name>UiState()
+      data class Success(val data: <DataClass>) : <Name>UiState()
+      data class Error(val message: String) : <Name>UiState()
+  }
+- For screens with empty states: add object Empty : <Name>UiState()
+- Never use parallel boolean flags (isLoading: Boolean, hasError: Boolean) — they create
+  illegal combinations (isLoading=true AND hasError=true is undefined).
+- Add UiEvent sealed class for one-shot events (Toast, Navigation, Snackbar) that should
+  not be replayed on recomposition. Use SharedFlow<UiEvent> in the ViewModel.
+
+RULES FOR ViewModel.kt:
+- Annotate with @HiltViewModel and inject constructor with @Inject.
+- Expose state as StateFlow<UiState>, private MutableStateFlow.
+- Expose events as SharedFlow<UiEvent> for one-shot side effects.
+- Fetch data in init { } or in a loadData() function called from the screen's LaunchedEffect.
+- Handle errors: wrap ALL repository calls in try/catch; emit Error state.
+- Re-throw CancellationException: catch (e: Exception) { if (e is CancellationException) throw e; ... }
+- Use viewModelScope.launch for all coroutine work.
+- Expose a refresh() function for pull-to-refresh support.
+
+RULES FOR Screen.kt:
+- Top-level composable: fun <ScreenName>Screen(navController: NavController, viewModel: <Name>ViewModel = hiltViewModel())
+- Collect state: val uiState by viewModel.uiState.collectAsStateWithLifecycle()
+- Collect events: LaunchedEffect(Unit) { viewModel.uiEvents.collect { event -> handleEvent(event, navController) } }
+- Use Scaffold with TopAppBar (CenterAlignedTopAppBar for Material 3).
+- Render each UiState variant directly:
+  when (uiState) {
+      is Loading -> LoadingContent()
+      is Success -> SuccessContent(data = uiState.data, ...)
+      is Error   -> ErrorContent(message = uiState.message, onRetry = viewModel::loadData)
+  }
+- Loading: CircularProgressIndicator centered in a Box(Modifier.fillMaxSize()).
+- Error: Column with error icon, message Text, and a retry Button.
+- Empty: Illustration placeholder with a helpful message and primary action button.
+- Pull-to-refresh: PullToRefreshBox (Compose 1.3+) wrapping the content.
+- Lists: LazyColumn with key = { item.id } and contentType = { item.type } for every item.
+- Images: Use Coil's AsyncImage with contentScale = ContentScale.Crop and a placeholder.
+- All colors: MaterialTheme.colorScheme.* — never hardcode hex or Color() literals.
+- All typography: MaterialTheme.typography.* — never hardcode font size or weight.
+- All shapes: MaterialTheme.shapes.* — never hardcode CornerRadius.
+- Spacing: multiples of 4.dp. Prefer 8, 12, 16, 24, 32.
+- Icons: use Icons.Rounded.* (Material 3 prefers Rounded style).
+- Every Image, IconButton, and non-text interactive element: contentDescription.
+- Minimum tap target: 48.dp via Modifier.minimumInteractiveComponentSize().
+- FAB: if the screen has a primary action, place a FloatingActionButton in Scaffold's fab slot.
+- Add exactly two @Preview annotations:
+  @Preview(showBackground = true, name = "Light")
+  @Preview(showBackground = true, uiMode = UI_MODE_NIGHT_YES, name = "Dark")
+  Both preview the Success state with realistic mock data (not empty strings or zeroes).
+
+RULES FOR NAVIGATION:
+- Use typed navigation args via NavType. Primitive types as NavArgument. Complex types as JSON (Gson/Moshi).
+- Route strings: use a companion object Routes with const val for each screen.
+- Provide the navHost registration block as a separate code snippet.
+
+CLEAN ARCHITECTURE:
+- ViewModel calls UseCases, not Repositories directly.
+- If no use case is specified, stub it: class Get<Feature>UseCase @Inject constructor(private val repository: <Feature>Repository) { suspend operator fun invoke(...) }
+- Domain layer has zero Android imports — do not import Context, View, or AndroidX in UseCases or domain models.
+- Data layer: Repository interface in domain, implementation in data module.
+
+KOTLIN CONVENTIONS:
+- Data classes for UI models: data class <Feature>UiModel(...)
+- Prefer data class copy() over mutation.
+- Extension functions for mapping: fun <DomainClass>.toUiModel(): <UiModel>
+- All suspend functions in the ViewModel: explicit error handling, never fire-and-forget.
+
+Output the files in order: UiState.kt → ViewModel.kt → Screen.kt → NavGraph snippet → Gradle deps.
+Label each file clearly. Output compilable Kotlin. Do not output pseudocode or placeholders.
+```
+
+---
+
+## Best Practices for Users
+
+1. **Be specific in `DESCRIPTION`.** "A list of orders" is vague. "A paginated LazyColumn of order cards showing order ID, status badge (color-coded), total amount, and date — sorted newest first" generates far better code.
+2. **List every `ACTION`.** If you want pull-to-refresh, swipe-to-delete, and a FAB — list all three. Unlisted actions won't appear.
+3. **Name your existing repositories.** If you say `DEPENDENCIES: OrderRepository`, the agent generates code that injects it instead of creating a stub.
+4. **Review the generated ViewModel carefully.** Business logic is architecture — the agent follows patterns but can't know your domain rules.
+5. **Run the Compose compiler** after pasting to catch any instability warnings early.

package/agents/android/compose-screen-builder/example-input.md

@@ -0,0 +1,40 @@
+# Example Input — Compose Screen Builder
+
+---
+
+```
+SCREEN_NAME: OrderHistoryScreen
+
+DESCRIPTION:
+A scrollable screen showing a user's past orders. The top bar shows "My Orders" with a
+back button. The content is a LazyColumn of order cards. Each card shows: order ID
+(e.g. #ORD-4821), a status badge (Delivered = green, Processing = amber, Cancelled = red),
+the item count ("3 items"), total price formatted as currency ("$48.50"), and the order
+date (e.g. "May 12, 2025"). Tapping a card navigates to the Order Detail screen.
+The screen supports pull-to-refresh. Empty state: "No orders yet" with a shopping bag icon
+and a "Start Shopping" button that navigates to the Home screen. Error state: "Something
+went wrong" with a Retry button. Loading state: full-screen centered circular progress.
+
+STATE_FIELDS:
+- orders: List<OrderUiModel> — list of past orders to display
+- isRefreshing: Boolean — true while pull-to-refresh is in progress
+
+ACTIONS:
+- Load orders on screen entry
+- Pull-to-refresh — reloads the order list
+- Tap order card — navigates to OrderDetailScreen with the orderId
+- Tap "Start Shopping" (empty state) — navigates back to HomeScreen
+- Tap Retry (error state) — reloads orders
+
+NAVIGATION:
+- Receives: userId: String from the caller (injected via SavedStateHandle in ViewModel)
+- Navigates to: OrderDetailScreen(orderId: String) on card tap
+- Navigates up: on TopAppBar back button press
+
+DEPENDENCIES:
+- OrderRepository (already exists in the data module)
+- GetOrderHistoryUseCase (to be generated as a stub if not specified)
+
+COMPOSE_VERSION: 1.7
+KOTLIN_VERSION: 2.0
+```