agy-superpowers 5.0.8 → 5.0.9

package/template/agent/skills/mobile-developer/references/android-rules/android-data-layer.md

@@ -0,0 +1,51 @@
+---
+name: android-data-layer
+description: Guidance on implementing the Data Layer using Repository pattern, Room (Local), and Retrofit (Remote) with offline-first synchronization.
+---
+
+# Android Data Layer & Offline-First
+
+## Instructions
+
+The Data Layer coordinates data from multiple sources.
+
+### 1. Repository Pattern
+*   **Role**: Single Source of Truth (SSOT).
+*   **Logic**: The repository decides whether to return cached data or fetch fresh data.
+*   **Implementation**:
+    ```kotlin
+    class NewsRepository @Inject constructor(
+        private val newsDao: NewsDao,
+        private val newsApi: NewsApi
+    ) {
+        // Expose data from Local DB as the source of truth
+        val newsStream: Flow<List<News>> = newsDao.getAllNews()
+
+        // Sync operation
+        suspend fun refreshNews() {
+            val remoteNews = newsApi.fetchLatest()
+            newsDao.insertAll(remoteNews)
+        }
+    }
+    ```
+
+### 2. Local Persistence (Room)
+*   **Usage**: Primary cache and offline storage.
+*   **Entities**: Define `@Entity` data classes.
+*   **DAOs**: Return `Flow<T>` for observable data.
+
+### 3. Remote Data (Retrofit)
+*   **Usage**: Fetching data from backend.
+*   **Response**: Use `suspend` functions in interfaces.
+*   **Error Handling**: Wrap network calls in `try-catch` blocks or a `Result` wrapper to handle exceptions (NoInternet, 404, etc.) gracefully.
+
+### 4. Synchronization
+*   **Read**: "Stale-While-Revalidate". Show local data immediately, trigger a background refresh.
+*   **Write**: "Outbox Pattern" (Advanced). Save local change immediately, mark as "unsynced", use `WorkManager` to push changes to server.
+
+### 5. Dependency Injection
+*   Bind Repository interfaces to implementations in a Hilt Module.
+    ```kotlin
+    @Binds
+    abstract fun bindNewsRepository(impl: OfflineFirstNewsRepository): NewsRepository
+    ```

package/template/agent/skills/mobile-developer/references/android-rules/android-emulator-skill.md

@@ -0,0 +1,108 @@
+---
+name: android-emulator-skill
+version: 1.0.0
+description: Production-ready scripts for Android app testing, building, and automation. Provides semantic UI navigation, build automation, log monitoring, and emulator lifecycle management. Optimized for AI agents with minimal token output.
+---
+
+# Android Emulator Skill
+
+Build, test, and automate Android applications using accessibility-driven navigation and structured data instead of pixel coordinates.
+
+## Quick Start
+
+```bash
+# 1. Check environment
+bash scripts/emu_health_check.sh
+
+# 2. Launch app
+python scripts/app_launcher.py --launch com.example.app
+
+# 3. Map screen to see elements
+python scripts/screen_mapper.py
+
+# 4. Tap button
+python scripts/navigator.py --find-text "Login" --tap
+
+# 5. Enter text
+python scripts/navigator.py --find-type EditText --enter-text "user@example.com"
+```
+
+All scripts support `--help` for detailed options and `--json` for machine-readable output.
+
+## Production Scripts
+
+### Build & Development
+
+1. **build_and_test.py** - Build Android projects, run tests, parse results
+   - Wrapper around Gradle
+   - Support for assemble, install, and connectedCheck
+   - Parse build errors and test results
+   - Options: `--task`, `--clean`, `--json`
+
+2. **log_monitor.py** - Real-time log monitoring with intelligent filtering
+   - Wrapper around `adb logcat`
+   - Filter by tag, priority, or PID
+   - Deduplicate repeated messages
+   - Options: `--package`, `--tag`, `--priority`, `--duration`, `--json`
+
+### Navigation & Interaction
+
+3. **screen_mapper.py** - Analyze current screen and list interactive elements
+   - Dump UI hierarchy using `uiautomator`
+   - Parse XML to identify buttons, text fields, etc.
+   - Options: `--verbose`, `--json`
+
+4. **navigator.py** - Find and interact with elements semantically
+   - Find by text (fuzzy matching), resource-id, or class name
+   - Interactive tapping and text entry
+   - Options: `--find-text`, `--find-id`, `--tap`, `--enter-text`, `--json`
+
+5. **gesture.py** - Perform swipes, scrolls, and other gestures
+   - Swipe up/down/left/right
+   - Scroll lists
+   - Options: `--swipe`, `--scroll`, `--duration`, `--json`
+
+6. **keyboard.py** - Key events and hardware buttons
+   - Input key events (Home, Back, Enter, Tab)
+   - Type text via ADB
+   - Options: `--key`, `--text`, `--json`
+
+7. **app_launcher.py** - App lifecycle management
+   - Launch apps (`adb shell am start`)
+   - Terminate apps (`adb shell am force-stop`)
+   - Install/Uninstall APKs
+   - List installed packages
+   - Options: `--launch`, `--terminate`, `--install`, `--uninstall`, `--list`, `--json`
+
+### Emulator Lifecycle Management
+
+8. **emulator_manage.py** - Manage Android Virtual Devices (AVDs)
+   - List available AVDs
+   - Boot emulators
+   - Shutdown emulators
+   - Options: `--list`, `--boot`, `--shutdown`, `--json`
+
+9. **emu_health_check.sh** - Verify environment is properly configured
+    - Check ADB, Emulator, Java, Gradle, ANDROID_HOME
+    - List connected devices
+
+## Common Patterns
+
+**Auto-Device Detection**: Scripts target the single connected device/emulator if only one is present, or require `-s <serial>` if multiple are connected.
+
+**Output Formats**: Default is concise human-readable output. Use `--json` for machine-readable output.
+
+## Requirements
+
+- Android SDK Platform-Tools (adb, fastboot)
+- Android Emulator
+- Java / OpenJDK
+- Python 3
+
+## Key Design Principles
+
+**Semantic Navigation**: Find elements by text, resource-id, or content-description.
+
+**Token Efficiency**: Concise default output with optional verbose and JSON modes.
+
+**Zero Configuration**: Works with standard Android SDK installation.

package/template/agent/skills/mobile-developer/references/android-rules/android-gradle-logic.md

@@ -0,0 +1,126 @@
+---
+name: android-gradle-logic
+description: Expert guidance on setting up scalable Gradle build logic using Convention Plugins and Version Catalogs.
+---
+
+# Android Gradle Build Logic & Convention Plugins
+
+This skill helps you configure a scalable, maintainable build system for Android apps using **Gradle Convention Plugins** and **Version Catalogs**, following the "Now in Android" (NiA) architecture.
+
+## Goal
+Stop copy-pasting code between `build.gradle.kts` files. Centralize build logic (Compose setup, Kotlin options, Hilt, etc.) in reusable plugins.
+
+## Project Structure
+
+Ensure your project has a `build-logic` directory included in `settings.gradle.kts` as a composite build.
+
+```text
+root/
+├── build-logic/
+│   ├── convention/
+│   │   ├── src/main/kotlin/
+│   │   │   └── AndroidApplicationConventionPlugin.kt
+│   │   └── build.gradle.kts
+│   ├── build.gradle.kts
+│   └── settings.gradle.kts
+├── gradle/
+│   └── libs.versions.toml
+├── app/
+│   └── build.gradle.kts
+└── settings.gradle.kts
+```
+
+## Step 1: Configure `settings.gradle.kts`
+
+Include the `build-logic` as a plugin management source.
+
+```kotlin
+// settings.gradle.kts
+pluginManagement {
+    includeBuild("build-logic")
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+```
+
+## Step 2: Define Dependencies in `libs.versions.toml`
+
+Use the Version Catalog for both libraries *and* plugins.
+
+```toml
+[versions]
+androidGradlePlugin = "8.2.0"
+kotlin = "1.9.20"
+
+[libraries]
+# ...
+
+[plugins]
+android-application = { id = "com.android.application", version.ref = "androidGradlePlugin" }
+android-library = { id = "com.android.library", version.ref = "androidGradlePlugin" }
+kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
+# Define your own plugins here
+nowinandroid-android-application = { id = "nowinandroid.android.application", version = "unspecified" }
+```
+
+## Step 3: Create a Convention Plugin
+
+Inside `build-logic/convention/src/main/kotlin/AndroidApplicationConventionPlugin.kt`:
+
+```kotlin
+import com.android.build.api.dsl.ApplicationExtension
+import org.gradle.api.Plugin
+import org.gradle.api.Project
+import org.gradle.kotlin.dsl.configure
+
+class AndroidApplicationConventionPlugin : Plugin<Project> {
+    override fun apply(target: Project) {
+        with(target) {
+            with(pluginManager) {
+                apply("com.android.application")
+                apply("org.jetbrains.kotlin.android")
+            }
+
+            extensions.configure<ApplicationExtension> {
+                defaultConfig.targetSdk = 34
+                // Configure common options here
+            }
+        }
+    }
+}
+```
+
+Don't forget to register it in `build-logic/convention/build.gradle.kts`:
+
+```kotlin
+gradlePlugin {
+    plugins {
+        register("androidApplication") {
+            id = "nowinandroid.android.application"
+            implementationClass = "AndroidApplicationConventionPlugin"
+        }
+    }
+}
+```
+
+## Usage
+
+Apply your custom plugin in your modules (e.g., `app/build.gradle.kts`):
+
+```kotlin
+plugins {
+    alias(libs.plugins.nowinandroid.android.application)
+}
+```
+
+This drastically cleans up module-level build files.

package/template/agent/skills/mobile-developer/references/android-rules/android-retrofit.md

@@ -0,0 +1,142 @@
+---
+name: android-retrofit
+description: Expert guidance on setting up and using Retrofit for type-safe HTTP networking in Android. Covers service definitions, coroutines, OkHttp configuration, and Hilt integration.
+---
+
+# Android Networking with Retrofit
+
+## Instructions
+
+When implementing network layers using **Retrofit**, follow these modern Android best practices (2025).
+
+### 1. URL Manipulation
+Retrofit allows dynamic URL updates through replacement blocks and query parameters.
+
+*   **Dynamic Paths**: Use `{name}` in the relative URL and `@Path("name")` in parameters.
+*   **Query Parameters**: Use `@Query("key")` for individual parameters.
+*   **Complex Queries**: Use `@QueryMap Map<String, String>` for dynamic sets of parameters.
+
+```kotlin
+interface SearchService {
+    @GET("group/{id}/users")
+    suspend fun groupList(
+        @Path("id") groupId: Int,
+        @Query("sort") sort: String?,
+        @QueryMap options: Map<String, String> = emptyMap()
+    ): List<User>
+}
+```
+
+### 2. Request Body & Form Data
+You can send objects as JSON bodies or use form-encoded/multipart formats.
+
+*   **@Body**: Serializes an object using the configured converter (JSON).
+*   **@FormUrlEncoded**: Sends data as `application/x-www-form-urlencoded`. Use `@Field`.
+*   **@Multipart**: Sends data as `multipart/form-data`. Use `@Part`.
+
+```kotlin
+interface UserService {
+    @POST("users/new")
+    suspend fun createUser(@Body user: User): User
+
+    @FormUrlEncoded
+    @POST("user/edit")
+    suspend fun updateUser(
+        @Field("first_name") first: String,
+        @Field("last_name") last: String
+    ): User
+
+    @Multipart
+    @PUT("user/photo")
+    suspend fun uploadPhoto(
+        @Part("description") description: RequestBody,
+        @Part photo: MultipartBody.Part
+    ): User
+}
+```
+
+### 3. Header Manipulation
+Headers can be set statically for a method or dynamically via parameters.
+
+*   **Static Headers**: Use `@Headers`.
+*   **Dynamic Headers**: Use `@Header`.
+*   **Header Maps**: Use `@HeaderMap`.
+*   **Global Headers**: Use an OkHttp **Interceptor**.
+
+```kotlin
+interface WidgetService {
+    @Headers("Cache-Control: max-age=640000")
+    @GET("widget/list")
+    suspend fun widgetList(): List<Widget>
+
+    @GET("user")
+    suspend fun getUser(@Header("Authorization") token: String): User
+}
+```
+
+### 4. Kotlin Support & Response Handling
+When using `suspend` functions, you have two choices for return types:
+
+1.  **Direct Body (`User`)**: Returns the deserialized body. Throws `HttpException` for non-2xx responses.
+2.  **`Response<User>`**: Provides access to the status code, headers, and error body. Does NOT throw on non-2xx results.
+
+```kotlin
+@GET("users")
+suspend fun getUsers(): List<User> // Throws on error
+
+@GET("users")
+suspend fun getUsersResponse(): Response<List<User>> // Manual check
+```
+
+### 5. Hilt & Serialization Configuration
+Provide your Retrofit instances as singletons in a Hilt module.
+
+```kotlin
+@Module
+@InstallIn(SingletonComponent::class)
+object NetworkModule {
+
+    @Provides
+    @Singleton
+    fun provideJson(): Json = Json {
+        ignoreUnknownKeys = true
+        coerceInputValues = true
+    }
+
+    @Provides
+    @Singleton
+    fun provideOkHttpClient(): OkHttpClient = OkHttpClient.Builder()
+        .addInterceptor(HttpLoggingInterceptor().apply { level = HttpLoggingInterceptor.Level.BODY })
+        .connectTimeout(30, TimeUnit.SECONDS)
+        .build()
+
+    @Provides
+    @Singleton
+    fun provideRetrofit(okHttpClient: OkHttpClient, json: Json): Retrofit = Retrofit.Builder()
+        .baseUrl("https://api.github.com/")
+        .client(okHttpClient)
+        .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))
+        .build()
+}
+```
+
+### 6. Error Handling in Repositories
+Always handle network exceptions in the Repository layer to keep the UI state clean.
+
+```kotlin
+class GitHubRepository @Inject constructor(private val service: GitHubService) {
+    suspend fun getRepos(username: String): Result<List<Repo>> = runCatching {
+        // Direct body call throws HttpException on 4xx/5xx
+        service.listRepos(username)
+    }.onFailure { exception ->
+        // Handle specific exceptions like UnknownHostException or SocketTimeoutException
+    }
+}
+```
+
+### 7. Checklist
+- [ ] Use `suspend` functions for all network calls.
+- [ ] Prefer `Response<T>` if you need to handle specific status codes (e.g., 401 Unauthorized).
+- [ ] Use `@Path` and `@Query` instead of manual string concatenation for URLs.
+- [ ] Configure `OkHttpClient` with logging (for debug) and sensible timeouts.
+- [ ] Map API DTOs to Domain models to decouple layers.

package/template/agent/skills/mobile-developer/references/android-rules/android-testing.md

@@ -0,0 +1,102 @@
+---
+name: android-testing
+description: Comprehensive testing strategy involving Unit, Integration, Hilt, and Screenshot tests.
+---
+
+# Android Testing Strategies
+
+This skill provides expert guidance on testing modern Android applications, inspired by "Now in Android". It covers **Unit Tests**, **Hilt Integration Tests**, and **Screenshot Testing**.
+
+## Testing Pyramid
+
+1.  **Unit Tests**: Fast, isolate logic (ViewModels, Repositories).
+2.  **Integration Tests**: Test interactions (Room DAOs, Retrofit vs MockWebServer).
+3.  **UI/Screenshot Tests**: Verify UI correctness (Compose).
+
+## Dependencies (`libs.versions.toml`)
+
+Ensure you have the right testing dependencies.
+
+```toml
+[libraries]
+junit4 = { module = "junit:junit", version = "4.13.2" }
+kotlinx-coroutines-test = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-test", version.ref = "kotlinxCoroutines" }
+androidx-test-ext-junit = { group = "androidx.test.ext", name = "junit", version = "1.1.5" }
+espresso-core = { group = "androidx.test.espresso", name = "espresso-core", version = "3.5.1" }
+compose-ui-test = { group = "androidx.compose.ui", name = "ui-test-junit4" }
+hilt-android-testing = { group = "com.google.dagger", name = "hilt-android-testing", version.ref = "hilt" }
+roborazzi = { group = "io.github.takahirom.roborazzi", name = "roborazzi", version.ref = "roborazzi" }
+```
+
+## Screenshot Testing with Roborazzi
+
+Screenshot tests ensure your UI doesn't regress visually. NiA uses **Roborazzi** because it runs on the JVM (fast) without needing an emulator.
+
+### Setup
+
+1.  Add the plugin to `libs.versions.toml`:
+    ```toml
+    [plugins]
+    roborazzi = { id = "io.github.takahirom.roborazzi", version.ref = "roborazzi" }
+    ```
+2.  Apply it in your module's `build.gradle.kts`:
+    ```kotlin
+    plugins {
+        alias(libs.plugins.roborazzi)
+    }
+    ```
+
+### Writing a Screenshot Test
+
+```kotlin
+@RunWith(AndroidJUnit4::class)
+@GraphicsMode(GraphicsMode.Mode.NATIVE)
+@Config(sdk = [33], qualifiers = RobolectricDeviceQualifiers.Pixel5)
+class MyScreenScreenshotTest {
+
+    @get:Rule
+    val composeTestRule = createAndroidComposeRule<ComponentActivity>()
+
+    @Test
+    fun captureMyScreen() {
+        composeTestRule.setContent {
+            MyTheme {
+                MyScreen()
+            }
+        }
+
+        composeTestRule.onRoot()
+            .captureRoboImage()
+    }
+}
+```
+
+## Hilt Testing
+
+Use `HiltAndroidRule` to inject dependencies in tests.
+
+```kotlin
+@HiltAndroidTest
+class MyDaoTest {
+
+    @get:Rule
+    var hiltRule = HiltAndroidRule(this)
+
+    @Inject
+    lateinit var database: MyDatabase
+    private lateinit var dao: MyDao
+
+    @Before
+    fun init() {
+        hiltRule.inject()
+        dao = database.myDao()
+    }
+    
+    // ... tests
+}
+```
+
+## Running Tests
+
+*   **Unit**: `./gradlew test`
+*   **Screenshots**: `./gradlew recordRoborazziDebug` (to record) / `./gradlew verifyRoborazziDebug` (to verify)

package/template/agent/skills/mobile-developer/references/android-rules/android-viewmodel.md

@@ -0,0 +1,43 @@
+---
+name: android-viewmodel
+description: Best practices for implementing Android ViewModels, specifically focused on StateFlow for UI state and SharedFlow for one-off events.
+---
+
+# Android ViewModel & State Management
+
+## Instructions
+
+Use `ViewModel` to hold state and business logic. It must outlive configuration changes.
+
+### 1. UI State (StateFlow)
+*   **What**: Represents the persistent state of the UI (e.g., `Loading`, `Success(data)`, `Error`).
+*   **Type**: `StateFlow<UiState>`.
+*   **Initialization**: Must have an initial value.
+*   **Exposure**: Expose as a read-only `StateFlow` backing a private `MutableStateFlow`.
+    ```kotlin
+    private val _uiState = MutableStateFlow<UiState>(UiState.Loading)
+    val uiState: StateFlow<UiState> = _uiState.asStateFlow()
+    ```
+*   **Updates**: Update state using `.update { oldState -> ... }` for thread safety.
+
+### 2. One-Off Events (SharedFlow)
+*   **What**: Transient events like "Show Toast", "Navigate to Screen", "Show Snackbar".
+*   **Type**: `SharedFlow<UiEvent>`.
+*   **Configuration**: Must use `replay = 0` to prevent events from re-triggering on screen rotation.
+    ```kotlin
+    private val _uiEvent = MutableSharedFlow<UiEvent>(replay = 0)
+    val uiEvent: SharedFlow<UiEvent> = _uiEvent.asSharedFlow()
+    ```
+*   **Sending**: Use `.emit(event)` (suspend) or `.tryEmit(event)`.
+
+### 3. Collecting in UI
+*   **Compose**: Use `collectAsStateWithLifecycle()` for `StateFlow`.
+    ```kotlin
+    val state by viewModel.uiState.collectAsStateWithLifecycle()
+    ```
+    For `SharedFlow`, use `LaunchedEffect` with `LocalLifecycleOwner`.
+*   **Views (XML)**: Use `repeatOnLifecycle(Lifecycle.State.STARTED)` within a coroutine.
+
+### 4. Scope
+*   Use `viewModelScope` for all coroutines started by the ViewModel.
+*   Ideally, specific operations should be delegated to UseCases or Repositories.

package/template/agent/skills/mobile-developer/references/android-rules/coil-compose.md

@@ -0,0 +1,74 @@
+---
+name: coil-compose
+description: Expert guidance on using Coil for image loading in Jetpack Compose. Use this when asked about loading images from URLs, handling image states, or optimizing image performance in Compose.
+---
+
+# Coil for Jetpack Compose
+
+## Instructions
+
+When implementing image loading in Jetpack Compose, use **Coil** (Coroutines Image Loader). It is the recommended library for Compose due to its efficiency and seamless integration.
+
+### 1. Primary Composable: `AsyncImage`
+Use `AsyncImage` for most use cases. It handles size resolution automatically and supports standard `Image` parameters.
+
+```kotlin
+AsyncImage(
+    model = ImageRequest.Builder(LocalContext.current)
+        .data("https://example.com/image.jpg")
+        .crossfade(true)
+        .build(),
+    placeholder = painterResource(R.drawable.placeholder),
+    error = painterResource(R.drawable.error),
+    contentDescription = stringResource(R.string.description),
+    contentScale = ContentScale.Crop,
+    modifier = Modifier.clip(CircleShape)
+)
+```
+
+### 2. Low-Level Control: `rememberAsyncImagePainter`
+Use `rememberAsyncImagePainter` only when you need a `Painter` instead of a composable (e.g., for `Canvas` or `Icon`) or when you need to observe the loading state manually.
+
+> [!WARNING]
+> `rememberAsyncImagePainter` does not detect the size your image is loaded at on screen and always loads the image with its original dimensions by default. Use `AsyncImage` unless a `Painter` is strictly required.
+
+```kotlin
+val painter = rememberAsyncImagePainter(
+    model = ImageRequest.Builder(LocalContext.current)
+        .data("https://example.com/image.jpg")
+        .size(Size.ORIGINAL) // Explicitly define size if needed
+        .build()
+)
+```
+
+### 3. Slot API: `SubcomposeAsyncImage`
+Use `SubcomposeAsyncImage` when you need a custom slot API for different states (Loading, Success, Error).
+
+> [!CAUTION]
+> Subcomposition is slower than regular composition. Avoid using `SubcomposeAsyncImage` in performance-critical areas like `LazyColumn` or `LazyRow`.
+
+```kotlin
+SubcomposeAsyncImage(
+    model = "https://example.com/image.jpg",
+    contentDescription = null,
+    loading = {
+        CircularProgressIndicator()
+    },
+    error = {
+        Icon(Icons.Default.Error, contentDescription = null)
+    }
+)
+```
+
+### 4. Performance & Best Practices
+*   **Singleton ImageLoader**: Use a single `ImageLoader` instance for the entire app to share the disk/memory cache.
+*   **Main-Safe**: Coil executes image requests on a background thread automatically.
+*   **Crossfade**: Always enable `crossfade(true)` in `ImageRequest` for a smoother transition from placeholder to success.
+*   **Sizing**: Ensure `contentScale` is set appropriately to avoid loading larger images than necessary.
+
+### 5. Checklist for implementation
+- [ ] Prefer `AsyncImage` over other variants.
+- [ ] Always provide a meaningful `contentDescription` or set it to `null` for decorative images.
+- [ ] Use `crossfade(true)` for better UX.
+- [ ] Avoid `SubcomposeAsyncImage` in lists.
+- [ ] Configure `ImageRequest` for specific needs like transformations (e.g., `CircleCropTransformation`).