@shaykec/app-agent 1.0.0

package/.claude/skills/ui-tester/SKILL.md

@@ -0,0 +1,449 @@
+---
+name: ui-tester
+description: Launches the generated app on a simulator/emulator using ai-tester MCP tools, exhaustively tests EVERY screen and EVERY interactive element, generates comprehensive Maestro regression tests, and runs them. Fixes any app bugs found during testing. Use after build-tester confirms the app compiles.
+---
+
+# UI Tester Skill
+
+Use this skill to test the generated app on a real simulator. You must exhaustively test every screen and every interactive element, fix any bugs you find, generate comprehensive Maestro regression tests, and run them all to pass.
+
+## When to Use
+
+- At Steps 8-10 of the AppAgent workflow (the final phase)
+- After the build succeeds and the build artifact path is known
+- After the security audit and validation pass
+- This step is **MANDATORY** — do not skip it
+
+## Execution Modes
+
+### Full Mode (single simulator — legacy)
+
+Used when no customization manifest exists or when running as the sole testing agent. One simulator tests all screens and runs all Maestro tests sequentially.
+
+### Batch Mode (multi-simulator — parallel)
+
+Used when the `customization-manifest.md` defines **UI Testing Batches** and **Maestro Test Batches**. The main agent:
+1. Boots 2-3 simulators
+2. Installs the app on all simulators
+3. Dispatches 2-3 parallel `Task` subagents for interactive testing (Phase 1)
+4. Dispatches 2-3 parallel `Task` subagents for Maestro execution (Phase 3)
+
+**When running as a batch subagent, you will receive:**
+- **Batch assignment** — which screens to test interactively, OR which Maestro YAMLs to run
+- **Simulator name** — the `deviceName` for your dedicated simulator
+- **Build artifact path** — already installed on your simulator
+- **Bundle ID / Package name** — for launch
+
+**Batch mode rules:**
+- ONLY test the screens assigned to your batch (for interactive testing)
+- ONLY run the Maestro YAMLs assigned to your batch (for Maestro execution)
+- Use your assigned `deviceName` in all ai-tester MCP calls
+- Report results back to the main agent
+
+## Context You Need
+
+- **App directory** — path under `output/` (e.g., `output/gigwallet-ios/`)
+- **Platform** — `ios` or `android`
+- **App name** — display name (e.g., "GigWallet")
+- **Bundle ID / Package name** — e.g., `com.gigwallet.app`
+- **Build artifact path** — `.app` bundle (iOS) or `.apk` file (Android) from the build-tester skill
+- **Customization manifest** (if available) — for UI testing and Maestro test batches
+- **Batch assignment** (batch mode only) — which screens/tests this subagent owns
+- **Simulator name** (batch mode only) — `deviceName` for this subagent's simulator
+
+Before starting:
+
+1. **Read `TESTING_MANIFEST.md`** — every template includes a testing manifest that documents all screens, navigation paths, test IDs, and element counts. This is your primary reference. It tells you exactly what to test and what selectors to use.
+2. **Read `AppConfig` and `MockDataProvider`** — to understand the domain content for assertion text.
+3. **Read `customization-manifest.md`** (if it exists) — for batch assignments and screen groupings.
+
+From the testing manifest, build a **complete inventory** of:
+- All tab names, test IDs, and navigation structure
+- All screens reachable from each tab (or just your batch in batch mode)
+- All interactive elements per screen with their **test IDs** (used as Maestro `id:` selectors)
+- Expected element counts per screen (for verification)
+
+## Instructions
+
+### Phase 1 — Exhaustive Interactive Testing with ai-tester MCP
+
+You MUST use the **ai-tester** MCP server tools for ALL device interaction. Do NOT use shell commands like `xcrun simctl`.
+
+#### Step 1 — Boot, Install, Launch
+
+**Full mode (single simulator):**
+```
+list_devices({ platform: "{platform}" })     → Find available device
+boot_simulator({ platform, deviceName })      → Boot the simulator
+install_app({ platform, appPath })            → Install the build artifact
+launch_app({ platform, app: "{bundleId}" })   → Launch the app
+```
+
+**Batch mode (multi-simulator — main agent sets up, subagents test):**
+
+The main agent boots 2-3 simulators and installs the app on each:
+```
+device({ action: "list", platform: "{platform}" })
+device({ action: "boot", platform: "{platform}", deviceId: "iPhone 16" })
+device({ action: "boot", platform: "{platform}", deviceId: "iPhone 15" })
+device({ action: "boot", platform: "{platform}", deviceId: "iPhone SE" })
+device({ action: "install", platform: "{platform}", appPath: "{artifactPath}" })
+```
+
+Then dispatches parallel subagents. Each subagent uses its assigned `deviceName` in all calls:
+```
+launch_app({ platform: "{platform}", app: "{bundleId}", deviceName: "{assignedSim}" })
+inspect({ platform: "{platform}", deviceName: "{assignedSim}", recordVideo: false })
+```
+
+Wait 3-5 seconds after launch for the app to fully render.
+
+#### Step 2 — Test Every Screen Exhaustively
+
+For **EACH** screen in the app (every tab, every detail screen, every modal), you must:
+
+1. **Navigate** to the screen (tap the tab, tap a list item, tap a button, etc.)
+2. **Inspect** the screen — get screenshot + element tree
+3. **Audit the element tree** — identify EVERY interactive element on the screen:
+   - Buttons (navigation bar buttons, action buttons, CTAs)
+   - List items / tappable rows
+   - Toggles, switches, checkboxes
+   - Text fields, search bars
+   - Floating action buttons (FABs)
+   - Tab bar items
+   - Swipe-able elements
+   - Pull-to-refresh (if ScrollView present)
+4. **Test EVERY interactive element** — tap/interact with each one and verify the result:
+   - Buttons: tap and verify the expected action (navigation, modal, state change)
+   - List items: tap and verify detail screen opens with correct data
+   - Toggles/switches: tap and verify state changes
+   - Text fields: tap, type sample text, verify input is accepted
+   - FABs: tap and verify the expected screen/modal opens
+   - Back/close buttons: tap and verify return to previous screen
+5. **Scroll to bottom** of any scrollable content to verify all lazy-loaded items render
+6. **AI Vision check** — use `vision_describe_screen` and verify:
+   - The description matches the app's domain (no template-generic descriptions)
+   - No overlapping text, cut-off elements, or broken layouts
+   - No placeholder images or missing content
+7. **Template leftover check** — `get_source` and search for leftover text: "FinanceTemplate", "ShopTemplate", "SocialTemplate", "HealthTemplate", "Lorem ipsum", "Template", any original template name
+
+#### Per-Screen Checklist
+
+On every screen, verify ALL of the following that apply:
+
+- [ ] **Tab bar items** — tap each tab, verify correct screen loads
+- [ ] **Navigation bar buttons** — tap back, close, edit, add, settings, etc.
+- [ ] **All list items** — tap into at least 2 items per list (or all if fewer than 3)
+- [ ] **Action buttons** — tap every visible action button (like, share, follow, delete, save, bookmark, reply, repost, etc.)
+- [ ] **Form inputs** — tap text fields, type sample text; tap toggles and pickers
+- [ ] **FABs / compose buttons** — tap and verify the compose/create screen opens
+- [ ] **Pull-to-refresh** — swipe down on scrollable content if present
+- [ ] **Scroll to bottom** — scroll down to verify content loads beyond the fold
+- [ ] **Modals / sheets** — if any button triggers a modal or action sheet, verify it appears and can be dismissed
+- [ ] **Empty states** — if a screen can show an empty state, verify the message is domain-appropriate
+- [ ] **Search** — if a search bar exists, tap it, type a query, verify results or "no results" state
+
+#### Step 3 — Screen Coverage Verification
+
+After testing all screens, verify you have covered:
+- Every tab in the tab bar (100% tab coverage)
+- At least one detail screen from every list
+- Every compose/create flow
+- Every settings screen
+- The profile screen (if present)
+- The onboarding flow (if it appears on first launch)
+
+Count the total interactive elements found across all screens and confirm in your report that each was tested.
+
+### Phase 1.5 — Fix App Bugs (Fix-Rebuild-Retest Loop)
+
+If interactive testing reveals ANY of the following, you MUST fix them before proceeding:
+
+- **Broken layout** — overlapping text, cut-off elements, elements overflowing screen bounds
+- **Non-functional button** — button that does nothing when tapped or navigates to wrong screen
+- **Crash** — app crashes on tap or navigation
+- **Missing content** — screen shows no data when mock data should be displayed
+- **Wrong data** — screen shows data from wrong domain or template leftover content
+- **Broken navigation** — back button doesn't work, tab doesn't switch, modal can't be dismissed
+
+#### Fix Loop Steps
+
+1. **Document** the bug — note the screen, element, expected behavior, actual behavior
+2. **Fix** the Swift/Kotlin source code in `output/{app-name}/`
+3. **Rebuild** — run the same build command from the build-tester skill
+4. **Re-install** on the simulator — `install_app` with the new artifact
+5. **Re-launch** — `launch_app`
+6. **Re-test** the fixed screen to verify the fix works
+7. **Repeat** until the bug is resolved
+
+**Limits:**
+- Maximum **3 fix-rebuild cycles** total to prevent infinite loops
+- If a bug cannot be fixed in 3 cycles, document it as a known issue and continue
+- After each cycle, re-test ALL previously passing screens to ensure no regressions
+
+#### What to Report
+
+For each bug found and fixed, record:
+- Screen and element where the bug occurred
+- Description of the bug
+- File(s) modified to fix it
+- Whether the fix was verified
+
+### Phase 2 — Generate Maestro Tests (Comprehensive Coverage)
+
+The template includes **skeleton Maestro test files** in `tests/`. Adapt these rather than writing from scratch:
+
+1. **Copy** the skeleton tests from the cloned template's `tests/` directory to `output/{app-name}/tests/`
+2. **Replace** the placeholder app ID (`${APP_BUNDLE_ID}` or `${APP_PACKAGE_NAME}`) with the actual bundle ID / package name
+3. **Update assertion text** to match the new domain content (e.g., "Espresso" instead of "Product 1")
+4. **Add/remove steps** if features were toggled on/off during customization
+5. **Rename test IDs** in selectors if screens/entities were renamed during customization
+
+If skeleton tests don't exist or need supplementing, generate at least **8** Maestro YAML test files under `output/{app-name}/tests/`.
+
+**CRITICAL: Use `id:` selectors (test IDs) as the primary selector strategy.** All interactive elements have `accessibilityIdentifier` (iOS) or `testTag` (Android). Reference `TESTING_MANIFEST.md` for the full list of test IDs.
+
+```yaml
+appId: {bundleId}
+---
+- launchApp
+- assertVisible:
+    id: "tab_bar_home"
+- tapOn:
+    id: "home_search_field"
+- inputText: "Espresso"
+```
+
+Only use text selectors as a fallback for **content assertions** where you're verifying specific domain text appears:
+
+```yaml
+- assertVisible: "Espresso"    # Verify domain content — text selector OK here
+```
+
+#### Required Maestro Commands
+
+Use these Maestro commands throughout your tests (not just `assertVisible` and `tapOn`):
+
+- `launchApp` — start the app
+- `assertVisible` — verify an element is on screen
+- `assertNotVisible` — verify an element is NOT on screen (for navigation verification)
+- `tapOn` — tap buttons, tabs, list items
+- `inputText` — type into text fields and search bars
+- `scrollUntilVisible` — scroll to find elements below the fold
+- `back` — navigate back (Android) or tap back button
+- `swipe` — swipe gestures (pull-to-refresh, dismiss sheets)
+- `clearState` — reset app state between independent tests
+
+#### Required Test Files (minimum 8)
+
+Generate at least these tests:
+
+1. **App launch + home screen** — launch, verify ALL key sections on the home screen (not just the title — verify list items, action buttons, navigation elements)
+2. **Tab navigation (all tabs)** — tap every tab, verify each screen's title AND at least 2 content elements per tab
+3. **Detail screen from tab 1** — tap a list item, verify detail content (title, description, images, action buttons), navigate back
+4. **Detail screen from tab 2** — tap a list item from a different tab, verify detail content, navigate back
+5. **Compose/create flow** — navigate to compose screen, verify all form elements, type into text fields with `inputText`, tap submit (if safe), verify result
+6. **Search/filter flow** — tap search, type a query with `inputText`, verify results or empty state
+7. **Profile/settings screen** — navigate to profile or settings, verify all sections, tap toggles or options, verify state changes
+8. **Full end-to-end flow** — navigate through ALL tabs, open one detail per tab, use compose, use search, verify return to home — this test should have 20+ steps
+
+#### Per-Test Quality Requirements
+
+Each test must:
+- Have at least **5 steps** (small tests) to **25+ steps** (full flow tests)
+- Assert **content elements** (mock data names, descriptions) not just screen titles
+- Use `tapOn` for EVERY button visible on the screen being tested
+- Use `inputText` for any text field on the screen being tested
+- Use `scrollUntilVisible` when content extends below the fold
+- Verify navigation BACK works (assert previous screen is visible after going back)
+
+### Phase 3 — Run All Maestro Tests and Fix Failures
+
+After generating the YAML files, **run every single one** using ai-tester MCP.
+
+**Full mode (single simulator):**
+```
+run_test({ testFile: "output/{app-name}/tests/{test-file}.yaml", platform: "{platform}" })
+```
+
+**Batch mode (parallel across simulators):**
+
+The main agent dispatches 2-3 parallel `Task` subagents. Each subagent runs its assigned batch of Maestro tests on its own simulator:
+```
+run_test({ paths: ["tests/01_launch_home.yaml", "tests/02_tab_nav.yaml", ...], platform: "{platform}", deviceName: "{assignedSim}" })
+```
+
+The manifest's **Maestro Test Batches** defines which tests go to which simulator. Each subagent reports pass/fail results back.
+
+#### Failure Handling
+
+If a test fails, diagnose and fix:
+
+1. **YAML selector issue** (wrong text, wrong element ID):
+   - Fix the YAML file with the correct selector
+   - Re-run the test
+
+2. **App bug** (button doesn't work, wrong screen loads, crash):
+   - Fix the Swift/Kotlin source code
+   - Rebuild the app (follow build-tester instructions)
+   - Re-install on the simulator: `install_app`
+   - Re-launch: `launch_app`
+   - Re-run the failed test AND all previously passing tests (regression check)
+
+3. **Timing issue** (element not yet visible):
+   - Add a wait step or `scrollUntilVisible` before the assertion
+   - Re-run the test
+
+**Every generated test must pass before reporting success.**
+
+Maximum **3 fix-rebuild cycles** across Phase 1.5 and Phase 3 combined.
+
+### Phase 4 — Screenshot Collection for GitHub
+
+After tests complete, capture one clean screenshot per main screen for the GitHub repo and PRs.
+
+1. Create `output/{app-name}/screenshots/` directory
+2. Navigate to each main tab and capture with ai-tester:
+   ```
+   inspect({ platform: "{platform}", app: "{bundleId}", saveBaseline: "home", label: "Home" })
+   inspect({ platform: "{platform}", app: "{bundleId}", saveBaseline: "explore", label: "Explore" })
+   inspect({ platform: "{platform}", app: "{bundleId}", saveBaseline: "favorites", label: "Favorites" })
+   inspect({ platform: "{platform}", app: "{bundleId}", saveBaseline: "profile", label: "Profile" })
+   ```
+3. Capture one detail screen: tap a list item, then `inspect` with `saveBaseline: "detail"`
+4. Copy baseline PNGs to `output/{app-name}/screenshots/{name}.png`
+5. One screenshot per tab — curated overview, clean state (no modals, no keyboard, scrolled to top)
+6. In batch mode, only the main agent performs screenshot collection
+
+### Cleanup
+
+When done (pass or fail), shut down all simulators:
+
+**Full mode:**
+```
+shutdown_simulator({ platform: "{platform}" })
+```
+
+**Batch mode (main agent shuts down all simulators after all subagents complete):**
+```
+device({ action: "shutdown", platform: "{platform}" })
+```
+
+## Report Output
+
+Write the report to `output/{app-name}/reports/09-ui-testing.md`:
+
+```markdown
+# UI Testing Report
+
+**Step:** 8
+**Skill:** ui-tester
+**Timestamp:** {ISO 8601}
+**Result:** PASS | FAIL
+
+## Device
+
+**Platform:** {platform}
+**Device:** {device name}
+**Simulator/Emulator:** {version}
+
+## Interactive Testing (Phase 1)
+
+**Screens Tested:** {count}
+**Interactive Elements Found:** {total count across all screens}
+**Interactive Elements Tested:** {count tested}
+**Template Leftovers Found:** yes | no
+**AI Vision Checks:** {count} screens
+
+### Screen-by-Screen Results
+
+| # | Screen | Tab | Elements Found | Elements Tested | Status | Notes |
+|---|--------|-----|----------------|-----------------|--------|-------|
+| 1 | {name} | {tab} | {count} | {count} | PASS | {notes} |
+
+### Element Coverage by Type
+
+| Element Type | Found | Tested | Coverage |
+|--------------|-------|--------|----------|
+| Buttons | {n} | {n} | {%} |
+| List items | {n} | {n} | {%} |
+| Text fields | {n} | {n} | {%} |
+| Toggles | {n} | {n} | {%} |
+| Navigation | {n} | {n} | {%} |
+
+## Bugs Found and Fixed (Phase 1.5)
+
+**Fix-Rebuild Cycles Used:** {0-3}
+
+| # | Screen | Bug Description | Fix Applied | File(s) Changed | Verified |
+|---|--------|-----------------|-------------|-----------------|----------|
+| 1 | {screen} | {description} | {fix} | {files} | Yes/No |
+
+## Maestro Tests (Phase 2 + 3)
+
+**Generated:** {count} test files
+**Total Steps:** {count}
+**Passed:** {count}/{total}
+**Failed:** {count}
+
+### Test Results
+
+| # | Test File | Steps | Duration | Result | Error |
+|---|-----------|-------|----------|--------|-------|
+| 1 | {filename}.yaml | {passed}/{total} | {time} | PASS | — |
+| 2 | {filename}.yaml | {passed}/{total} | {time} | FAIL | {error} |
+
+## Issues Found
+
+- [{SEVERITY}] {description} — {fixed | known issue}
+
+## Summary
+
+{overall assessment including: screens tested, element coverage percentage, bugs fixed, Maestro pass rate}
+```
+
+Update `output/{app-name}/reports/summary.json` — read the file, append this step and finalize.
+
+**Timing:** Record the current timestamp when you begin this skill. When writing the step entry, set `"startedAt"` to that timestamp (ISO 8601) and `"durationSeconds"` to the elapsed seconds.
+
+```json
+{
+  "step": 8,
+  "name": "ui-testing",
+  "startedAt": "{ISO 8601 timestamp}",
+  "durationSeconds": 0,
+  "result": "PASS|FAIL",
+  "reportFile": "09-ui-testing.md",
+  "interactiveScreens": 0,
+  "interactiveElements": { "found": 0, "tested": 0 },
+  "bugsFixed": 0,
+  "fixRebuildCycles": 0,
+  "maestroTests": 0,
+  "maestroSteps": 0,
+  "maestroStepsPassed": 0,
+  "templateLeftovers": false,
+  "screenshotsCaptured": 0,
+  "screenshotPaths": []
+}
+```
+
+**IMPORTANT:** Since this is the last step, also finalize summary.json:
+- Set `"overallResult"` to "PASS" if all steps passed, "FAIL" if any step failed
+- Set `"filesWritten"` to the total count of files created/modified
+- Set `"duration"` to the total elapsed time
+
+## Important Rules
+
+- ONLY use ai-tester MCP tools for device interaction — NOT shell commands like `xcrun simctl`
+- Test EVERY interactive element on EVERY screen — not just tabs and headers
+- After `inspect`, audit the element tree to count interactive elements before testing them
+- Use `vision_describe_screen` on EVERY distinct screen
+- Generate at least 8 Maestro tests — one per screen/feature, with comprehensive step coverage
+- Every Maestro test must use more than just `assertVisible` and `tapOn` — use `inputText`, `scrollUntilVisible`, `back`, `assertNotVisible`, `swipe` where applicable
+- RUN every generated test — do not just create YAML files
+- FIX app bugs found during testing — modify source code, rebuild, re-install, retest (max 3 cycles)
+- FIX Maestro YAML failures — correct selectors, add waits, re-run
+- ALL Maestro tests must pass before reporting PASS
+- Always shut down the simulator when done
+- ALWAYS collect screenshots (Phase 4) before shutting down simulators — they are used in GitHub repos and PRs
+- If ai-tester MCP is not available, write the report noting "UI testing skipped — ai-tester MCP not configured" and set result to "SKIPPED"

package/.cursor/agents/README.md

@@ -0,0 +1,27 @@
+# Agent Definitions (Fallback)
+
+These agent definition files (`.md`) are **preserved as a fallback** for when Cursor CLI improves subagent support via the Task tool.
+
+## Current Status
+
+**Skills are the primary mechanism.** All workflow steps now reference skills in `.cursor/skills/` instead of these agent files. The agent executes skill instructions inline, which is more reliable in Cursor CLI headless mode (`cursor agent -p`).
+
+## Migration Map
+
+| Agent File | Replaced By Skill |
+|---|---|
+| `security-auditor.md` (Phase 1) | `.cursor/skills/prompt-validator/SKILL.md` |
+| `security-auditor.md` (Phase 2) | `.cursor/skills/code-auditor/SKILL.md` |
+| `template-selector.md` | `.cursor/skills/template-selector/SKILL.md` |
+| `design-selector.md` | `.cursor/skills/design-selector/SKILL.md` |
+| `ios-customizer.md` | `.cursor/skills/ios-customizer/SKILL.md` |
+| `android-customizer.md` | `.cursor/skills/android-customizer/SKILL.md` |
+| `build-tester.md` | `.cursor/skills/build-tester/SKILL.md` |
+| `validator.md` | `.cursor/skills/output-validator/SKILL.md` |
+| `ui-tester.md` | `.cursor/skills/ui-tester/SKILL.md` |
+
+## Why Keep These?
+
+- Subagent spawning may improve in future Cursor CLI versions
+- Agent files provide tool restrictions (`readonly: true`) that skills cannot enforce
+- These serve as documentation of the original architecture

package/.cursor/agents/android-customizer.md

@@ -0,0 +1,159 @@
+---
+name: android-customizer
+description: Specialized Android/Kotlin subagent for customizing Jetpack Compose app templates. Use when the target platform is Android and the main agent needs to perform deep Compose customization — updating Gradle configs, rewriting Compose screens, adjusting Hilt DI, configuring navigation, and handling Android-specific features.
+tools:
+  - Read
+  - Edit
+  - Write
+  - Grep
+  - Glob
+  - LS
+  - Shell
+---
+
+# Android Customizer
+
+You are an expert Android developer specializing in Jetpack Compose and modern Kotlin development. You handle all Android-specific customization tasks for the AppAgent pipeline.
+
+## Context You Receive
+
+The main agent passes you:
+- **App name** — display name (e.g., "GigWallet")
+- **App directory** — path under `output/` (e.g., `output/gigwallet-android/`)
+- **Platform** — `android`
+- **App description** — what the app does
+- **What has been done** — renaming, AppConfig, mock data updates already completed
+- **Design brief** (from design-system skill) — color palette (light + dark hex codes), Material Icon mapping, visual tone (playful/professional/minimal/bold), corner radius, and typography intent. Apply these tokens to `Theme.kt`, navigation icons, and layout values.
+- **Content brief** (from content-writer skill) — onboarding text, tab labels, section headers, empty state messages, button labels, search placeholders, and error messages. Apply these strings to Compose screens.
+
+## Logging Protocol (MANDATORY)
+
+When you start, print:
+`[SUBAGENT:android-customizer] Starting — Android customization for {app-name}`
+
+When you finish, print:
+`[SUBAGENT:android-customizer] Completed — {count} files modified`
+
+## Your Expertise
+
+- Jetpack Compose (Material Design 3), Kotlin 1.9+, Coroutines + Flow
+- Gradle build system (Kotlin DSL, version catalogs)
+- Hilt dependency injection (@HiltViewModel, @AndroidEntryPoint, @Inject)
+- MVVM architecture with StateFlow and sealed UI state classes
+- Android frameworks: Google Maps, CameraX, Room, WorkManager, DataStore
+
+## Tasks You Handle
+
+### Gradle & Package Renaming
+When renaming an Android app:
+1. Update `settings.gradle.kts` — change `rootProject.name`
+2. Update `app/build.gradle.kts` — change `namespace` and `applicationId`
+3. Update `AndroidManifest.xml` — change `android:label`, verify package attribute
+4. Rename package directories: `app/src/main/kotlin/com/appship/{oldname}/` to new package path
+5. Update `package` declaration at the top of EVERY `.kt` file
+6. Update `import` statements across all files that reference the old package
+7. Update `{OldName}Application.kt` — rename file and class, keep `@HiltAndroidApp`
+8. Update `gradle/libs.versions.toml` if app-specific entries exist
+
+### Gradle Version Catalog
+Templates use `gradle/libs.versions.toml` for dependency management:
+```toml
+[versions]
+compose-bom = "2024.02.00"
+hilt = "2.50"
+
+[libraries]
+compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "compose-bom" }
+
+[plugins]
+hilt = { id = "com.google.dagger.hilt.android", version.ref = "hilt" }
+```
+- Do NOT change library versions unless necessary
+- Do NOT add new dependencies — work within existing ones
+
+### Compose Screen Customization
+When modifying screens:
+- Use `@Composable` functions with PascalCase names
+- Use `Scaffold` with `TopAppBar` and `BottomNavigation` / `NavigationBar`
+- Use `LazyColumn` / `LazyRow` for lists (never `Column` with `forEach`)
+- Use `remember { mutableStateOf() }` for local UI state
+- Use `viewModel.uiState.collectAsStateWithLifecycle()` for ViewModel state
+- Use `MaterialTheme.colorScheme` and `MaterialTheme.typography` for theming
+
+### Navigation Structure
+Templates use Compose Navigation with a sealed route class:
+```kotlin
+sealed class Screen(val route: String) {
+    object Home : Screen("home")
+    object Profile : Screen("profile")
+    // ...
+}
+```
+When adding/removing/renaming screens:
+- Update the sealed `Screen` class
+- Update `NavHost` composable with `composable(Screen.X.route) { ... }`
+- Update `BottomNavigation` items
+- Ensure screen composables receive `navController: NavController`
+
+### Hilt Dependency Injection
+Templates use Hilt for DI:
+```kotlin
+@HiltViewModel
+class HomeViewModel @Inject constructor() : ViewModel() {
+    private val _uiState = MutableStateFlow<HomeUiState>(HomeUiState.Loading)
+    val uiState: StateFlow<HomeUiState> = _uiState.asStateFlow()
+}
+```
+- Keep `@HiltViewModel` annotation on all ViewModels
+- Keep `@AndroidEntryPoint` on `MainActivity`
+- Keep `@HiltAndroidApp` on the Application class
+- Do NOT change DI structure unless adding genuinely new ViewModels
+
+### Theme Customization
+Android templates define theme in `core/theme/Theme.kt`:
+```kotlin
+private val LightColorScheme = lightColorScheme(
+    primary = Color(0xFF6200EE),
+    secondary = Color(0xFF03DAC6),
+    // ...
+)
+```
+- Update color hex values to match the app's brand
+- Provide both `lightColorScheme` and `darkColorScheme`
+- Use Material 3 color roles (primary, secondary, tertiary, surface, etc.)
+- Keep `dynamicColor` support if present
+
+### MockDataProvider Updates
+Android MockDataProvider uses companion object with functions:
+```kotlin
+object MockDataProvider {
+    fun getServices(): List<Service> = listOf(...)
+    fun getProviders(): List<Provider> = listOf(...)
+}
+```
+- Keep the same function signatures
+- Update return values with domain-specific data
+- Use `UUID.randomUUID().toString()` for IDs
+- Use `LocalDateTime.now()` and `LocalDate` for dates
+
+## Output
+
+When done, report what you changed:
+```
+FILES MODIFIED:
+- {path}: {what changed}
+- {path}: {what changed}
+
+POTENTIAL ISSUES:
+- {any concerns or items needing manual review}
+```
+
+## Rules
+
+- ONLY edit files under `output/` — never touch `templates/`
+- Ensure all `package` declarations match directory structure
+- Ensure all `import` statements resolve after renaming
+- Keep `@HiltAndroidApp`, `@HiltViewModel`, `@AndroidEntryPoint` intact
+- Keep `build.gradle.kts` syntactically valid Kotlin DSL
+- Preserve `MockDataProvider` function signatures
+- Use Material 3 components (not legacy Material 2)