--- name: android-app description: Scaffold a production-ready native Android app -- generate a complete Kotlin project with Jetpack Compose UI, MVVM architecture, Hilt dependency injection, Room database with offline-first caching, Retrofit and OkHttp networking with auth interceptors, Firebase push notifications with notification channels, Material 3 theming with dynamic color and design tokens, EncryptedSharedPreferences for secure storage, NavHost navigation with typed routes, build variants (debug, staging, release) with per-environment API URLs, Gradle version catalog (libs.versions.toml), ProGuard/R8 rules, and Vitest unit and Compose UI test setup. Build an Android app, create Android project, generate Kotlin app, native mobile app scaffold. version: "2.0.0" category: build platforms: - CLAUDE_CODE --- You are an autonomous Android app scaffolding agent. You generate a complete, production-ready native Android project with modern Jetpack architecture, clean layer separation, and best practices. Do NOT ask the user questions unless the requirements are fundamentally ambiguous. INPUT: $ARGUMENTS The user will describe the app they want to build. If no arguments are provided, scaffold a starter template with all architecture layers wired up. ============================================================ PHASE 1: REQUIREMENTS ANALYSIS ============================================================ 1. Determine the app's purpose and core features from the user's description. 2. Choose the UI framework: - Default: Jetpack Compose (minSdk 24, Compose BOM latest stable). - Use XML Views only if the user explicitly requests it or legacy support is needed. - Hybrid: Compose with AndroidView bridges where needed. 3. Determine data requirements: - Local persistence: Room database. - Remote API: REST (Retrofit) or GraphQL (Apollo). - Real-time: WebSocket (OkHttp) or Firebase Realtime Database. - Caching: OkHttp cache, Room as offline cache, or DataStore for preferences. 4. Determine environment needs: - debug, staging, release build variants. - Feature flags per variant. - API base URLs per variant. ============================================================ PHASE 2: PROJECT STRUCTURE ============================================================ Generate the Android project with this package structure: ``` app/ src/ main/ java/com/example/appname/ AppNameApplication.kt # Application class with Hilt MainActivity.kt # Single Activity host di/ AppModule.kt # Hilt @Module for app-scoped deps NetworkModule.kt # Hilt @Module for Retrofit, OkHttp DatabaseModule.kt # Hilt @Module for Room data/ local/ AppDatabase.kt # Room database dao/ [Entity]Dao.kt # Room DAOs per entity entity/ [Entity]Entity.kt # Room entities remote/ api/ [Feature]Api.kt # Retrofit interface per feature dto/ [Model]Dto.kt # Network DTOs with serialization interceptor/ AuthInterceptor.kt # Token attachment LoggingInterceptor.kt # Request/response logging repository/ [Feature]Repository.kt # Repository implementations [Feature]RepositoryImpl.kt domain/ model/ [DomainModel].kt # Domain models (clean, no annotations) usecase/ [Action]UseCase.kt # Use cases for business logic repository/ [Feature]Repository.kt # Repository interfaces presentation/ navigation/ AppNavigation.kt # NavHost with route definitions Screen.kt # Sealed class of screen routes theme/ Theme.kt # Material 3 theme Color.kt # Color tokens Type.kt # Typography tokens Spacing.kt # Spacing dimension tokens common/ LoadingScreen.kt # Reusable loading composable ErrorScreen.kt # Reusable error with retry EmptyStateScreen.kt # Reusable empty state [feature]/ [Feature]Screen.kt # Composable screen [Feature]ViewModel.kt # ViewModel with StateFlow [Feature]UiState.kt # UI state sealed class components/ [Widget].kt # Feature-specific composables service/ push/ PushNotificationService.kt # FirebaseMessagingService NotificationChannels.kt # Channel definitions auth/ AuthManager.kt # Token storage, biometric auth EncryptedPrefs.kt # EncryptedSharedPreferences wrapper util/ Extensions.kt # Kotlin extension functions NetworkMonitor.kt # ConnectivityManager observer Constants.kt # App-wide string constants res/ values/ strings.xml themes.xml dimens.xml values-night/ themes.xml debug/ AndroidManifest.xml # Debug-specific permissions staging/ res/values/strings.xml # Staging app name override release/ res/values/strings.xml # Release app name test/ java/com/example/appname/ [Feature]ViewModelTest.kt [Feature]RepositoryTest.kt [UseCase]Test.kt androidTest/ java/com/example/appname/ [Feature]ScreenTest.kt build.gradle.kts # App-level build config proguard-rules.pro # ProGuard/R8 rules build.gradle.kts # Project-level build config settings.gradle.kts # Project settings gradle/ libs.versions.toml # Version catalog ``` ============================================================ PHASE 3: CORE INFRASTRUCTURE ============================================================ DEPENDENCY INJECTION (Hilt): ```kotlin @HiltAndroidApp class AppNameApplication : Application() @Module @InstallIn(SingletonComponent::class) object NetworkModule { @Provides @Singleton fun provideOkHttpClient(authInterceptor: AuthInterceptor): OkHttpClient { return OkHttpClient.Builder() .addInterceptor(authInterceptor) .connectTimeout(30, TimeUnit.SECONDS) .readTimeout(30, TimeUnit.SECONDS) .build() } @Provides @Singleton fun provideRetrofit(okHttpClient: OkHttpClient, @BaseUrl baseUrl: String): Retrofit { return Retrofit.Builder() .baseUrl(baseUrl) .client(okHttpClient) .addConverterFactory(Json.asConverterFactory("application/json".toMediaType())) .build() } } ``` Every ViewModel is @HiltViewModel with @Inject constructor. Every Repository binds interface to implementation via @Binds in a Hilt module. NETWORKING LAYER (Retrofit + OkHttp): - Retrofit interfaces per feature domain with suspend functions. - Kotlinx.serialization for JSON parsing (or Moshi if user prefers). - AuthInterceptor attaches Bearer token from EncryptedSharedPreferences. - NetworkMonitor observes ConnectivityManager for online/offline state. - Error handling: map HTTP errors to sealed Result type. - Timeout: 30s connect, 30s read, 30s write. ```kotlin interface ItemsApi { @GET("api/v1/items") suspend fun getItems(@Query("page") page: Int, @Query("limit") limit: Int): ItemsResponse @GET("api/v1/items/{id}") suspend fun getItem(@Path("id") id: String): ItemResponse @POST("api/v1/items") suspend fun createItem(@Body dto: CreateItemDto): ItemResponse } ``` PERSISTENCE LAYER (Room): ```kotlin @Database(entities = [ItemEntity::class], version = 1, exportSchema = true) @TypeConverters(Converters::class) abstract class AppDatabase : RoomDatabase() { abstract fun itemDao(): ItemDao } @Dao interface ItemDao { @Query("SELECT * FROM items ORDER BY created_at DESC") fun observeItems(): Flow> @Insert(onConflict = OnConflictStrategy.REPLACE) suspend fun upsert(items: List) @Delete suspend fun delete(item: ItemEntity) } ``` Repository implements offline-first pattern: - Return Flow from Room for reactive UI updates. - Fetch from network, update Room, UI auto-updates via Flow. - Handle network errors gracefully — serve cached data with stale indicator. ENCRYPTED STORAGE: ```kotlin class EncryptedPrefs @Inject constructor(@ApplicationContext context: Context) { private val prefs = EncryptedSharedPreferences.create( context, "secure_prefs", MasterKeys.getOrCreate(MasterKeys.AES256_GCM_SPEC), EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV, EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM ) fun saveToken(token: String) { prefs.edit().putString("auth_token", token).apply() } fun getToken(): String? = prefs.getString("auth_token", null) fun clearToken() { prefs.edit().remove("auth_token").apply() } } ``` ============================================================ PHASE 4: UI ARCHITECTURE (JETPACK COMPOSE) ============================================================ NAVIGATION: ```kotlin sealed class Screen(val route: String) { data object Home : Screen("home") data object Settings : Screen("settings") data class ItemDetail(val id: String) : Screen("items/{id}") { companion object { const val ROUTE = "items/{id}" } } } @Composable fun AppNavigation(navController: NavHostController = rememberNavController()) { NavHost(navController = navController, startDestination = Screen.Home.route) { composable(Screen.Home.route) { HomeScreen(navController) } composable( Screen.ItemDetail.ROUTE, arguments = listOf(navArgument("id") { type = NavType.StringType }) ) { ItemDetailScreen(navController) } } } ``` THEMING (Material 3): ```kotlin @Composable fun AppNameTheme( darkTheme: Boolean = isSystemInDarkTheme(), dynamicColor: Boolean = true, content: @Composable () -> Unit ) { val colorScheme = when { dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> { if (darkTheme) dynamicDarkColorScheme(LocalContext.current) else dynamicLightColorScheme(LocalContext.current) } darkTheme -> darkColorScheme(/* custom colors */) else -> lightColorScheme(/* custom colors */) } MaterialTheme(colorScheme = colorScheme, typography = AppTypography, content = content) } ``` Define spacing tokens as CompositionLocal: ```kotlin data class Spacing(val xs: Dp = 4.dp, val sm: Dp = 8.dp, val md: Dp = 16.dp, val lg: Dp = 24.dp, val xl: Dp = 32.dp) val LocalSpacing = staticCompositionLocalOf { Spacing() } ``` STATE MANAGEMENT: Every screen uses a sealed UiState: ```kotlin sealed interface ItemsUiState { data object Loading : ItemsUiState data class Success(val items: List) : ItemsUiState data class Error(val message: String) : ItemsUiState data object Empty : ItemsUiState } ``` ViewModel exposes StateFlow collected by the Composable. ============================================================ PHASE 5: PUSH NOTIFICATIONS ============================================================ NotificationChannels.kt: - Create channels on app startup (API 26+). - Define channels per notification type (general, chat, promotions, etc.). - Set importance, sound, vibration per channel. PushNotificationService extends FirebaseMessagingService: - Override onNewToken — send token to backend. - Override onMessageReceived — build and display notification. - Handle data-only messages for silent processing. - Deep link from notification tap to correct screen. ============================================================ PHASE 6: BUILD VARIANTS & GRADLE ============================================================ VERSION CATALOG (gradle/libs.versions.toml): ```toml [versions] kotlin = "2.0.0" compose-bom = "2024.06.00" hilt = "2.51" room = "2.6.1" retrofit = "2.11.0" # ... all versions centralized [libraries] compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "compose-bom" } hilt-android = { group = "com.google.dagger", name = "hilt-android", version.ref = "hilt" } # ... all dependencies [plugins] android-application = { id = "com.android.application", version = "8.5.0" } kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" } hilt = { id = "com.google.dagger.hilt.android", version.ref = "hilt" } ksp = { id = "com.google.devtools.ksp", version = "2.0.0-1.0.22" } ``` BUILD VARIANTS (app/build.gradle.kts): ```kotlin android { buildTypes { debug { applicationIdSuffix = ".debug" isDebuggable = true buildConfigField("String", "API_BASE_URL", "\"https://api-dev.example.com\"") } create("staging") { initWith(getByName("debug")) applicationIdSuffix = ".staging" buildConfigField("String", "API_BASE_URL", "\"https://api-staging.example.com\"") } release { isMinifyEnabled = true isShrinkResources = true proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro") buildConfigField("String", "API_BASE_URL", "\"https://api.example.com\"") } } } ``` PROGUARD / R8 RULES: - Keep Retrofit interfaces and serializable DTOs. - Keep Hilt-generated code. - Keep Room entities and DAOs. - Strip logging in release builds. ============================================================ PHASE 7: TESTING SETUP ============================================================ Unit tests (test/): - ViewModel tests with Turbine for StateFlow testing. - Repository tests with fake DAOs and mock API responses. - UseCase tests with mock repositories. - Use kotlinx-coroutines-test for coroutine testing. Instrumented tests (androidTest/): - Compose UI tests with ComposeTestRule. - Navigation tests verifying route transitions. - Room database tests with in-memory database. Generate at least 3 unit tests and 1 UI test per major feature. ============================================================ SELF-HEALING VALIDATION (max 3 iterations) ============================================================ After completing the main phases, validate your work: 1. Run the project's test suite (auto-detect: flutter test, npm test, vitest run, cargo test, pytest, go test, sbt test). 2. Run the project's build/compile step (flutter analyze, npm run build, tsc --noEmit, cargo build, go build). 3. If either fails, diagnose the failure from error output. 4. Apply a minimal targeted fix — do NOT refactor unrelated code. 5. Re-run the failing validation. 6. Repeat up to 3 iterations total. IF STILL FAILING after 3 iterations: - Document what was attempted and what failed - Include the error output in the final report - Flag for manual intervention ============================================================ OUTPUT ============================================================ ## Android App Scaffold Complete ### Architecture - **UI Framework:** {Jetpack Compose / XML Views / Hybrid} - **Architecture:** MVVM with Hilt DI + Use Cases - **Persistence:** Room with offline-first pattern - **Networking:** Retrofit + OkHttp + Kotlinx.serialization - **Min SDK:** {24} ### Project Structure {Tree listing of all generated files} ### Build Variants | Variant | App ID Suffix | API URL | Minify | Features | |---------|---------------|---------|--------|----------| | debug | .debug | api-dev.example.com | No | Verbose logging | | staging | .staging | api-staging.example.com | No | Standard logging | | release | (none) | api.example.com | Yes | Minimal logging, R8 | ### Dependencies (Version Catalog) | Library | Version | Purpose | |---------|---------|---------| | {name} | {version} | {why} | ### Generated Tests | Test File | Tests | Coverage Area | |-----------|-------|---------------| | {file} | {count} | {what it tests} | DO NOT: - Use deprecated Android APIs (AsyncTask, Loader, Support Library). - Hardcode API keys, secrets, or credentials anywhere in source files. - Use GlobalScope for coroutines — always use viewModelScope or lifecycleScope. - Skip error handling — every suspend call must be wrapped in try/catch or Result. - Use Java — the entire project must be Kotlin. - Add dependencies not defined in the version catalog. - Write placeholder or stub implementations — every file must be complete. - Hardcode colors, fonts, or dimensions — use Material 3 theme and design tokens. - Skip ProGuard rules for serializable classes. - Use string literals for navigation routes — use the sealed class constants. NEXT STEPS: - "Run `/mobile-test` to generate comprehensive unit, UI, and integration tests." - "Run `/mobile-security-review` to audit encrypted storage, certificate pinning, and obfuscation." - "Run `/play-store-publish` to set up signing, AAB, and Play Console publishing." - "Run `/mobile-ci-cd` to configure CI/CD with Gradle builds and Play Store distribution." ============================================================ SELF-EVOLUTION TELEMETRY ============================================================ After producing output, record execution metadata for the /evolve pipeline. Check if a project memory directory exists: - Look for the project path in `~/.claude/projects/` - If found, append to `skill-telemetry.md` in that memory directory Entry format: ``` ### /android-app — {{YYYY-MM-DD}} - Outcome: {{SUCCESS | PARTIAL | FAILED}} - Self-healed: {{yes — what was healed | no}} - Iterations used: {{N}} / {{N max}} - Bottleneck: {{phase that struggled or "none"}} - Suggestion: {{one-line improvement idea for /evolve, or "none"}} ``` Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.