@shaykec/app-agent 1.0.0

package/templates/android/GameTemplate/README.md

@@ -0,0 +1,209 @@
+# GameTemplate - Casual Game Android App Template
+
+A complete, production-ready casual game Android app template built with Kotlin and Jetpack Compose. This template provides everything you need to create a gamified app with scoring, levels, achievements, leaderboards, and in-game purchases.
+
+## Features
+
+### Core Gameplay
+- 🎮 **Game Sessions** - Start, play, pause, and complete game sessions
+- 📊 **Score Tracking** - Real-time score display with high-score persistence
+- 🎯 **Levels** - Progressive level system with unlock requirements
+- ⭐ **Star Ratings** - Performance-based star ratings (1-3 stars)
+- ⏱️ **Timer** - Game timer with pause/resume functionality
+
+### Gamification
+- 🏆 **Achievements** - Unlockable achievements with rarity tiers (Common, Rare, Epic, Legendary)
+- 📈 **Leaderboard** - Daily, weekly, and all-time leaderboards
+- 🛒 **In-Game Shop** - Purchase power-ups and items with coins/gems
+- 💰 **Currency System** - Coins and gems with earning/spending mechanics
+- 🔄 **Daily Challenges** - Daily challenges with rewards and expiration
+- ❤️ **Lives System** - Lives with regeneration timers (optional)
+
+### User Features
+- 👤 **Player Profile** - Level, XP, total score, achievements, currency
+- 📊 **Progress Tracking** - Level progress bars, XP system
+- 🎨 **Customization** - Theme colors, sound effects, haptic feedback
+- 📱 **Onboarding** - First-time user onboarding flow
+
+## Requirements
+
+- Android Studio Hedgehog (2023.1.1) or later
+- Android SDK 24+ (Android 7.0)
+- Kotlin 1.9.20+
+- Gradle 8.2+
+
+## Quick Start
+
+1. **Clone the template:**
+   ```bash
+   cp -R templates/android/GameTemplate ~/MyGameApp
+   cd ~/MyGameApp
+   ```
+
+2. **Open in Android Studio:**
+   - Open Android Studio
+   - Select "Open an Existing Project"
+   - Navigate to the cloned directory
+
+3. **Update Package Name:**
+   - Right-click `app/src/main/kotlin/com/appship/game`
+   - Select "Refactor" → "Rename"
+   - Change to your package name (e.g., `com.yourcompany.yourapp`)
+
+4. **Customize the app:**
+   - Edit `AppConfig.kt` to change app name, colors, API endpoints
+   - Replace mock data in `MockDataProvider.kt` with your API calls
+
+5. **Run the app:**
+   - Select an emulator or device
+   - Press Shift+F10 to build and run
+
+## Customization Guide
+
+### Branding (AppConfig.kt)
+
+```kotlin
+// Change app identity
+const val APP_NAME = "Your Game"
+const val PACKAGE_NAME = "com.yourcompany.game"
+
+// Change theme colors in Theme.kt
+val Primary = Color(0xFF4370E5)
+val Accent = Color(0xFFFF9800)
+```
+
+### Feature Flags
+
+Enable/disable features in `AppConfig.Features`:
+
+```kotlin
+const val ENABLE_LEADERBOARD = true        // Leaderboard feature
+const val ENABLE_MULTIPLAYER = false        // Multiplayer support
+const val ENABLE_SHOP = true                // In-game shop
+const val ENABLE_ACHIEVEMENTS = true       // Achievement system
+const val ENABLE_DAILY_CHALLENGE = true     // Daily challenges
+const val ENABLE_LIVES = true               // Lives system
+const val ENABLE_SOUND_EFFECTS = true      // Sound effects
+const val ENABLE_GAME_CENTER = false       // Game Center integration
+const val ENABLE_TUTORIAL = true           // Tutorial/onboarding
+```
+
+### Business Rules
+
+Configure game mechanics in `AppConfig.Business`:
+
+```kotlin
+const val STARTING_LIVES = 5               // Starting lives count
+const val LIVES_REGEN_MINUTES = 30        // Minutes to regenerate one life
+const val STARTING_COINS = 100            // Starting coins
+const val STARTING_GEMS = 10              // Starting gems
+const val MAX_LEVEL = 50                  // Maximum level
+```
+
+### API Integration
+
+Replace mock data with real API calls:
+
+1. Edit `MockDataProvider.kt` methods to call your API endpoints
+2. Update `AppConfig.Api` with your backend URLs
+3. Add authentication tokens if required
+
+### Customization Markers
+
+Look for `// CUSTOMIZE:` comments throughout the code:
+- `// CUSTOMIZE:BRANDING` - App name, colors, logo
+- `// CUSTOMIZE:FEATURES` - Enable/disable features
+- `// CUSTOMIZE:API` - Backend endpoints
+- `// CUSTOMIZE:BUSINESS` - Game mechanics and rules
+- `// CUSTOMIZE:CONTENT` - App copy and links
+- `// CUSTOMIZE:THEME` - Colors and typography
+
+## Project Structure
+
+```
+GameTemplate/
+├── app/
+│   ├── src/
+│   │   ├── main/
+│   │   │   ├── kotlin/com/appship/game/
+│   │   │   │   ├── AppConfig.kt              # Central configuration
+│   │   │   │   ├── MainActivity.kt           # App entry point
+│   │   │   │   ├── data/
+│   │   │   │   │   └── Models.kt             # All data models
+│   │   │   │   ├── core/
+│   │   │   │   │   ├── managers/
+│   │   │   │   │   │   ├── GameManager.kt    # Game session management
+│   │   │   │   │   │   └── PlayerManager.kt  # Player state management
+│   │   │   │   │   └── theme/
+│   │   │   │   │       ├── Theme.kt          # Material3 theme
+│   │   │   │   │       └── Type.kt           # Typography
+│   │   │   │   ├── features/
+│   │   │   │   │   ├── home/
+│   │   │   │   │   │   └── HomeMenuScreen.kt
+│   │   │   │   │   ├── game/
+│   │   │   │   │   │   └── GameScreen.kt
+│   │   │   │   │   ├── results/
+│   │   │   │   │   │   └── ResultsScreen.kt
+│   │   │   │   │   ├── leaderboard/
+│   │   │   │   │   │   └── LeaderboardScreen.kt
+│   │   │   │   │   ├── shop/
+│   │   │   │   │   │   └── ShopScreen.kt
+│   │   │   │   │   ├── achievements/
+│   │   │   │   │   │   └── AchievementsScreen.kt
+│   │   │   │   │   ├── profile/
+│   │   │   │   │   │   └── ProfileScreen.kt
+│   │   │   │   │   ├── settings/
+│   │   │   │   │   │   └── SettingsScreen.kt
+│   │   │   │   │   └── navigation/
+│   │   │   │   │       └── Navigation.kt      # Navigation graph
+│   │   │   │   └── mock/
+│   │   │   │       └── MockDataProvider.kt   # Mock data with CRUD
+│   │   │   ├── res/
+│   │   │   │   └── values/
+│   │   │   │       ├── strings.xml
+│   │   │   │       ├── colors.xml
+│   │   │   │       └── themes.xml
+│   │   │   └── AndroidManifest.xml
+│   │   └── test/
+│   │       └── kotlin/com/appship/game/
+│   │           ├── MockDataProviderTest.kt
+│   │           └── ModelsTest.kt
+│   └── build.gradle.kts
+├── tests/
+│   └── *.yaml                                # Maestro test files
+├── build.gradle.kts
+├── settings.gradle.kts
+├── gradle.properties
+└── gradle/libs.versions.toml
+```
+
+## Testing
+
+The template includes 8 Maestro test files covering:
+1. App launch and home screen
+2. Tab navigation
+3. Game play flow
+4. Leaderboard interaction
+5. Shop purchases
+6. Achievements viewing
+7. Profile and settings
+8. Full end-to-end journey
+
+Run tests with:
+```bash
+maestro test tests/
+```
+
+## Next Steps
+
+1. **Customize game mechanics** - Update `AppConfig.Business` for your game rules
+2. **Add game content** - Replace placeholder questions/challenges in `GameScreen`
+3. **Design levels** - Update levels in `MockDataProvider.defaultLevels`
+4. **Create achievements** - Customize achievements in `MockDataProvider.defaultAchievements`
+5. **Integrate backend** - Replace `MockDataProvider` with API calls
+6. **Add Game Center** - Enable Game Center integration if needed
+7. **Customize theme** - Update colors in `Theme.kt` and `colors.xml`
+
+## License
+
+This template is provided as-is for use in your projects.

package/templates/android/GameTemplate/TESTING_MANIFEST.md

@@ -0,0 +1,221 @@
+# Testing Manifest - GameTemplate Android
+
+This document catalogs all screens, navigation paths, and test IDs for the GameTemplate Android app. Every interactive element has a stable test ID using `Modifier.testTag()` following the `{screen}_{element}_{role}` naming convention.
+
+## Tab Structure
+
+The app uses a `NavigationBar` with 4 tabs:
+
+| Tab | Test ID | Screen |
+|-----|---------|--------|
+| Play | `tab_bar_play` | HomeMenuScreen |
+| Leaderboard | `tab_bar_leaderboard` | LeaderboardScreen |
+| Shop | `tab_bar_shop` | ShopScreen |
+| Profile | `tab_bar_profile` | ProfileScreen |
+
+## Screen Inventory
+
+### 1. HomeMenuScreen (`home_*`)
+
+**Navigation Path:** Tab 0 (Play)
+
+**Interactive Elements:**
+- `home_play_button` - Main play button
+- `home_daily_challenge_card` - Daily challenge card (if enabled)
+- `home_level_text` - Current level display
+- `home_lives_indicator` - Lives indicator (if enabled)
+- Level cards (tap to start game)
+
+**Element Count:** ~15-20+ (depends on levels)
+
+---
+
+### 2. GameScreen (`game_*`)
+
+**Navigation Path:** From HomeMenuScreen level selection
+
+**Interactive Elements:**
+- `game_score_text` - Current score display
+- `game_timer_text` - Game timer display
+- `game_option_{index}_button` - Answer/option buttons (0-3)
+- `game_pause_button` - Pause game button
+
+**Element Count:** ~5-8
+
+---
+
+### 3. ResultsScreen (`results_*`)
+
+**Navigation Path:** After completing a game session
+
+**Interactive Elements:**
+- `results_score_text` - Final score display
+- `results_stars_text` - Star rating display
+- `results_replay_button` - Replay button
+- `results_next_level_button` - Next level button
+
+**Element Count:** ~4-6
+
+---
+
+### 4. LeaderboardScreen (`leaderboard_*`)
+
+**Navigation Path:** Tab 1 (Leaderboard)
+
+**Interactive Elements:**
+- `leaderboard_filter_picker` - Filter picker (Daily/Weekly/All Time)
+- `leaderboard_entry_{index}_card` - Leaderboard entry rows
+
+**Element Count:** ~10-20+ (depends on entries)
+
+---
+
+### 5. ShopScreen (`shop_*`)
+
+**Navigation Path:** Tab 2 (Shop)
+
+**Interactive Elements:**
+- `shop_coins_text` - Coins display
+- `shop_item_{index}_card` - Shop item cards
+- `shop_item_{index}_buy_button` - Buy buttons for items
+
+**Element Count:** ~5-15+ (depends on items)
+
+---
+
+### 6. AchievementsScreen (`achievement_*`)
+
+**Navigation Path:** From ProfileScreen
+
+**Interactive Elements:**
+- `achievement_{index}_card` - Achievement rows
+- `achievement_{index}_lock_icon` - Lock icon for locked achievements
+
+**Element Count:** ~8-15+ (depends on achievements)
+
+---
+
+### 7. ProfileScreen (`profile_*`)
+
+**Navigation Path:** Tab 3 (Profile)
+
+**Interactive Elements:**
+- `profile_level_text` - Player level display
+- `profile_total_score_text` - Total score display
+- `profile_achievements_count_text` - Achievements count display
+- `profile_achievements_link` - Navigation link to Achievements
+- `profile_shop_link` - Navigation link to Shop
+- `profile_settings_link` - Navigation link to Settings
+
+**Element Count:** ~8-12
+
+---
+
+### 8. SettingsScreen (`settings_*`)
+
+**Navigation Path:** From ProfileScreen
+
+**Interactive Elements:**
+- `settings_sound_toggle` - Sound effects toggle
+- `settings_haptic_toggle` - Haptic feedback toggle
+- `settings_reset_button` - Reset progress button
+- Links to Privacy Policy, Terms, Support
+
+**Element Count:** ~6-10
+
+---
+
+## Summary Statistics
+
+- **Total Screens:** 8 main screens
+- **Total Test IDs:** ~80+ unique identifiers
+- **Tab Bar Items:** 4
+- **Navigation Patterns:** Bottom navigation bar with Navigation Compose for screen navigation
+
+## Test ID Naming Conventions
+
+All test IDs follow the pattern: `{screen}_{element}_{role}`
+
+- **screen**: snake_case screen name (e.g., `home`, `game`, `results`)
+- **element**: descriptive element name (e.g., `play_button`, `score_text`, `option`)
+- **role**: element type (`button`, `text`, `card`, `picker`)
+
+For dynamic lists, indices are used: `{screen}_{item}_{index}_{role}` (e.g., `leaderboard_entry_0_card`)
+
+## Maestro Test Coverage
+
+See `tests/` directory for 8 comprehensive Maestro test files covering:
+
+1. **01_launch_home.yaml** - App launch and home screen verification
+2. **02_tab_navigation.yaml** - Tab navigation across all tabs
+3. **03_game_play.yaml** - Game play flow (start game, play, view results)
+4. **04_leaderboard.yaml** - Leaderboard interaction
+5. **05_shop.yaml** - Shop purchase flow
+6. **06_achievements.yaml** - Achievements viewing
+7. **07_profile_settings.yaml** - Profile and settings navigation
+8. **08_full_e2e.yaml** - Full end-to-end user journey
+
+## Running Tests
+
+```bash
+# Run all tests
+maestro test tests/
+
+# Run specific test
+maestro test tests/01_launch_home.yaml
+
+# Run with app ID
+maestro test tests/ --env APP_PACKAGE_NAME=com.appship.game
+```
+
+## Test ID Reference
+
+### Home Screen
+- `home_play_button`
+- `home_level_text`
+- `home_lives_indicator`
+- `home_daily_challenge_card`
+
+### Game Screen
+- `game_score_text`
+- `game_timer_text`
+- `game_option_0_button` through `game_option_3_button`
+- `game_pause_button`
+
+### Results Screen
+- `results_score_text`
+- `results_stars_text`
+- `results_replay_button`
+- `results_next_level_button`
+
+### Leaderboard Screen
+- `leaderboard_filter_picker`
+- `leaderboard_entry_0_card` through `leaderboard_entry_N_card`
+
+### Shop Screen
+- `shop_coins_text`
+- `shop_item_0_card` through `shop_item_N_card`
+- `shop_item_0_buy_button` through `shop_item_N_buy_button`
+
+### Achievements Screen
+- `achievement_0_card` through `achievement_N_card`
+- `achievement_0_lock_icon` through `achievement_N_lock_icon`
+
+### Profile Screen
+- `profile_level_text`
+- `profile_total_score_text`
+- `profile_achievements_count_text`
+- `profile_achievements_link`
+- `profile_shop_link`
+- `profile_settings_link`
+
+### Settings Screen
+- `settings_sound_toggle`
+- `settings_haptic_toggle`
+- `settings_reset_button`
+
+### Tab Bar
+- `tab_bar_play`
+- `tab_bar_leaderboard`
+- `tab_bar_shop`
+- `tab_bar_profile`

package/templates/android/GameTemplate/app/build.gradle.kts

@@ -0,0 +1,67 @@
+plugins {
+    alias(libs.plugins.android.application)
+    alias(libs.plugins.kotlin.android)
+}
+
+android {
+    namespace = "com.appship.game"
+    compileSdk = 34
+
+    defaultConfig {
+        applicationId = "com.appship.game"
+        minSdk = 24
+        targetSdk = 34
+        versionCode = 1
+        versionName = "1.0.0"
+
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+        vectorDrawables {
+            useSupportLibrary = true
+        }
+    }
+
+    buildTypes {
+        release {
+            isMinifyEnabled = false
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro"
+            )
+        }
+    }
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+    kotlinOptions {
+        jvmTarget = "17"
+    }
+    buildFeatures {
+        compose = true
+    }
+    composeOptions {
+        kotlinCompilerExtensionVersion = "1.5.4"
+    }
+    packaging {
+        resources {
+            excludes += "/META-INF/{AL2.0,LGPL2.1}"
+        }
+    }
+}
+
+dependencies {
+    implementation(libs.androidx.core.ktx)
+    implementation(libs.lifecycle.runtime.ktx)
+    implementation(libs.activity.compose)
+    implementation(platform(libs.compose.bom))
+    implementation(libs.bundles.compose)
+    implementation(libs.navigation.compose)
+    
+    testImplementation(libs.junit)
+    androidTestImplementation(libs.junit.ext)
+    androidTestImplementation(libs.espresso.core)
+    androidTestImplementation(platform(libs.compose.bom))
+    androidTestImplementation(libs.compose.ui.test.junit4)
+    debugImplementation(libs.compose.ui.tooling)
+    debugImplementation(libs.compose.ui.test.manifest)
+}

package/templates/android/GameTemplate/app/proguard-rules.pro

@@ -0,0 +1,30 @@
+# Add project specific ProGuard rules here.
+# You can control the set of applied configuration files using the
+# proguardFiles setting in build.gradle.kts.
+#
+# For more details, see
+#   http://developer.android.com/guide/developing/tools/proguard.html
+
+# If your project uses WebView with JS, uncomment the following
+# and specify the fully qualified class name to the JavaScript interface
+# class:
+#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
+#   public *;
+#}
+
+# Uncomment this to preserve the line number information for
+# debugging stack traces.
+#-keepattributes SourceFile,LineNumberTable
+
+# If you keep the line number information, uncomment this to
+# hide the original source file name.
+#-renamesourcefileattribute SourceFile
+
+# Keep data models
+-keep class com.appship.game.data.** { *; }
+
+# Keep managers
+-keep class com.appship.game.core.managers.** { *; }
+
+# Keep Retrofit interfaces (if using)
+-keep interface com.appship.game.api.** { *; }

package/templates/android/GameTemplate/app/src/main/AndroidManifest.xml

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+
+    <application
+        android:allowBackup="true"
+        android:dataExtractionRules="@xml/data_extraction_rules"
+        android:fullBackupContent="@xml/backup_rules"
+        android:icon="@mipmap/ic_launcher"
+        android:label="@string/app_name"
+        android:roundIcon="@mipmap/ic_launcher_round"
+        android:supportsRtl="true"
+        android:theme="@style/Theme.GameTemplate"
+        tools:targetApi="31">
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:theme="@style/Theme.GameTemplate">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+    </application>
+
+</manifest>

package/templates/android/GameTemplate/app/src/main/kotlin/com/appship/game/AppConfig.kt

@@ -0,0 +1,76 @@
+package com.appship.game
+
+// CUSTOMIZE:BRANDING - App identity and configuration
+object AppConfig {
+    const val APP_NAME = "GameTemplate"
+    const val PACKAGE_NAME = "com.appship.game"
+    const val VERSION = "1.0.0"
+    
+    // CUSTOMIZE:FEATURES - Enable/disable app features
+    object Features {
+        const val ENABLE_LEADERBOARD = true
+        const val ENABLE_MULTIPLAYER = false
+        const val ENABLE_SHOP = true
+        const val ENABLE_ACHIEVEMENTS = true
+        const val ENABLE_DAILY_CHALLENGE = true
+        const val ENABLE_LIVES = true
+        const val ENABLE_SOUND_EFFECTS = true
+        const val ENABLE_GAME_CENTER = false
+        const val ENABLE_TUTORIAL = true
+    }
+    
+    // CUSTOMIZE:API - Backend endpoints
+    object Api {
+        const val BASE_URL = "https://api.example.com"
+        const val API_VERSION = "v1"
+        const val TIMEOUT_SECONDS = 30L
+        
+        val leaderboardUrl get() = "$BASE_URL/$API_VERSION/leaderboard"
+        val achievementsUrl get() = "$BASE_URL/$API_VERSION/achievements"
+        val shopUrl get() = "$BASE_URL/$API_VERSION/shop"
+        val gameSessionUrl get() = "$BASE_URL/$API_VERSION/sessions"
+    }
+    
+    // CUSTOMIZE:BUSINESS - Business rules and game mechanics
+    object Business {
+        const val STARTING_LIVES = 5
+        const val LIVES_REGEN_MINUTES = 30
+        const val STARTING_COINS = 100
+        const val STARTING_GEMS = 10
+        const val MAX_LEVEL = 50
+        const val DAILY_CHALLENGE_REWARD_COINS = 50
+        const val DAILY_CHALLENGE_REWARD_GEMS = 5
+    }
+    
+    // CUSTOMIZE:CONTENT - App copy and links
+    object Content {
+        const val SUPPORT_EMAIL = "support@example.com"
+        const val SUPPORT_PHONE = "+1-800-123-4567"
+        const val PRIVACY_POLICY_URL = "https://example.com/privacy"
+        const val TERMS_URL = "https://example.com/terms"
+        const val FAQ_URL = "https://example.com/faq"
+    }
+    
+    // CUSTOMIZE:ONBOARDING - Onboarding slides content
+    object Onboarding {
+        data class Slide(val title: String, val subtitle: String, val icon: String)
+        
+        val slides = listOf(
+            Slide(
+                "Welcome to $APP_NAME",
+                "Start your gaming journey and compete with players worldwide",
+                "gamepad"
+            ),
+            Slide(
+                "Earn Rewards",
+                "Complete levels, unlock achievements, and collect coins",
+                "star"
+            ),
+            Slide(
+                "Climb the Leaderboard",
+                "Beat your high scores and become the champion",
+                "emoji_events"
+            )
+        )
+    }
+}

package/templates/android/GameTemplate/app/src/main/kotlin/com/appship/game/MainActivity.kt

@@ -0,0 +1,40 @@
+package com.appship.game
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.ui.Modifier
+import androidx.navigation.compose.rememberNavController
+import com.appship.game.core.managers.GameManager
+import com.appship.game.core.managers.PlayerManager
+import com.appship.game.core.theme.GameTemplateTheme
+import com.appship.game.features.navigation.GameTemplateNavigation
+
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        
+        val gameManager = GameManager(this)
+        val playerManager = PlayerManager(this)
+        
+        setContent {
+            GameTemplateTheme {
+                Surface(
+                    modifier = Modifier.fillMaxSize(),
+                    color = MaterialTheme.colorScheme.background
+                ) {
+                    val navController = rememberNavController()
+                    GameTemplateNavigation(navController = navController)
+                }
+            }
+        }
+    }
+    
+    override fun onDestroy() {
+        super.onDestroy()
+        // Cleanup managers if needed
+    }
+}