agy-superpowers 5.0.7 → 5.0.9

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

@@ -0,0 +1,346 @@
+---
+name: gradle-build-performance
+description: Debug and optimize Android/Gradle build performance. Use when builds are slow, investigating CI/CD performance, analyzing build scans, or identifying compilation bottlenecks.
+---
+
+# Gradle Build Performance
+
+## When to Use
+
+- Build times are slow (clean or incremental)
+- Investigating build performance regressions
+- Analyzing Gradle Build Scans
+- Identifying configuration vs execution bottlenecks
+- Optimizing CI/CD build times
+- Enabling Gradle Configuration Cache
+- Reducing unnecessary recompilation
+- Debugging kapt/KSP annotation processing
+
+## Example Prompts
+
+- "My builds are slow, how can I speed them up?"
+- "How do I analyze a Gradle build scan?"
+- "Why is configuration taking so long?"
+- "Why does my project always recompile everything?"
+- "How do I enable configuration cache?"
+- "Why is kapt so slow?"
+
+---
+
+## Workflow
+
+1. **Measure Baseline** — Clean build + incremental build times
+2. **Generate Build Scan** — `./gradlew assembleDebug --scan`
+3. **Identify Phase** — Configuration? Execution? Dependency resolution?
+4. **Apply ONE optimization** — Don't batch changes
+5. **Measure Improvement** — Compare against baseline
+6. **Verify in Build Scan** — Visual confirmation
+
+---
+
+## Quick Diagnostics
+
+### Generate Build Scan
+
+```bash
+./gradlew assembleDebug --scan
+```
+
+### Profile Build Locally
+
+```bash
+./gradlew assembleDebug --profile
+# Opens report in build/reports/profile/
+```
+
+### Build Timing Summary
+
+```bash
+./gradlew assembleDebug --info | grep -E "^\:.*"
+# Or view in Android Studio: Build > Analyze APK Build
+```
+
+---
+
+## Build Phases
+
+| Phase | What Happens | Common Issues |
+|-------|--------------|---------------|
+| **Initialization** | `settings.gradle.kts` evaluated | Too many `include()` statements |
+| **Configuration** | All `build.gradle.kts` files evaluated | Expensive plugins, eager task creation |
+| **Execution** | Tasks run based on inputs/outputs | Cache misses, non-incremental tasks |
+
+### Identify the Bottleneck
+
+```
+Build scan → Performance → Build timeline
+```
+
+- **Long configuration phase**: Focus on plugin and buildscript optimization
+- **Long execution phase**: Focus on task caching and parallelization
+- **Dependency resolution slow**: Focus on repository configuration
+
+---
+
+## 12 Optimization Patterns
+
+### 1. Enable Configuration Cache
+
+Caches configuration phase across builds (AGP 8.0+):
+
+```properties
+# gradle.properties
+org.gradle.configuration-cache=true
+org.gradle.configuration-cache.problems=warn
+```
+
+### 2. Enable Build Cache
+
+Reuses task outputs across builds and machines:
+
+```properties
+# gradle.properties
+org.gradle.caching=true
+```
+
+### 3. Enable Parallel Execution
+
+Build independent modules simultaneously:
+
+```properties
+# gradle.properties
+org.gradle.parallel=true
+```
+
+### 4. Increase JVM Heap
+
+Allocate more memory for large projects:
+
+```properties
+# gradle.properties
+org.gradle.jvmargs=-Xmx4g -XX:+UseParallelGC
+```
+
+### 5. Use Non-Transitive R Classes
+
+Reduces R class size and compilation (AGP 8.0+ default):
+
+```properties
+# gradle.properties
+android.nonTransitiveRClass=true
+```
+
+### 6. Migrate kapt to KSP
+
+KSP is 2x faster than kapt for Kotlin:
+
+```kotlin
+// Before (slow)
+kapt("com.google.dagger:hilt-compiler:2.51.1")
+
+// After (fast)
+ksp("com.google.dagger:hilt-compiler:2.51.1")
+```
+
+### 7. Avoid Dynamic Dependencies
+
+Pin dependency versions:
+
+```kotlin
+// BAD: Forces resolution every build
+implementation("com.example:lib:+")
+implementation("com.example:lib:1.0.+")
+
+// GOOD: Fixed version
+implementation("com.example:lib:1.2.3")
+```
+
+### 8. Optimize Repository Order
+
+Put most-used repositories first:
+
+```kotlin
+// settings.gradle.kts
+dependencyResolutionManagement {
+    repositories {
+        google()      // First: Android dependencies
+        mavenCentral() // Second: Most libraries
+        // Third-party repos last
+    }
+}
+```
+
+### 9. Use includeBuild for Local Modules
+
+Composite builds are faster than `project()` for large monorepos:
+
+```kotlin
+// settings.gradle.kts
+includeBuild("shared-library") {
+    dependencySubstitution {
+        substitute(module("com.example:shared")).using(project(":"))
+    }
+}
+```
+
+### 10. Enable Incremental Annotation Processing
+
+```properties
+# gradle.properties
+kapt.incremental.apt=true
+kapt.use.worker.api=true
+```
+
+### 11. Avoid Configuration-Time I/O
+
+Don't read files or make network calls during configuration:
+
+```kotlin
+// BAD: Runs during configuration
+val version = file("version.txt").readText()
+
+// GOOD: Defer to execution
+val version = providers.fileContents(file("version.txt")).asText
+```
+
+### 12. Use Lazy Task Configuration
+
+Avoid `create()`, use `register()`:
+
+```kotlin
+// BAD: Eagerly configured
+tasks.create("myTask") { ... }
+
+// GOOD: Lazily configured
+tasks.register("myTask") { ... }
+```
+
+---
+
+## Common Bottleneck Analysis
+
+### Slow Configuration Phase
+
+**Symptoms**: Build scan shows long "Configuring build" time
+
+**Causes & Fixes**:
+| Cause | Fix |
+|-------|-----|
+| Eager task creation | Use `tasks.register()` instead of `tasks.create()` |
+| buildSrc with many dependencies | Migrate to Convention Plugins with `includeBuild` |
+| File I/O in build scripts | Use `providers.fileContents()` |
+| Network calls in plugins | Cache results or use offline mode |
+
+### Slow Compilation
+
+**Symptoms**: `:app:compileDebugKotlin` takes too long
+
+**Causes & Fixes**:
+| Cause | Fix |
+|-------|-----|
+| Non-incremental changes | Avoid `build.gradle.kts` changes that invalidate cache |
+| Large modules | Break into smaller feature modules |
+| Excessive kapt usage | Migrate to KSP |
+| Kotlin compiler memory | Increase `kotlin.daemon.jvmargs` |
+
+### Cache Misses
+
+**Symptoms**: Tasks always rerun despite no changes
+
+**Causes & Fixes**:
+| Cause | Fix |
+|-------|-----|
+| Unstable task inputs | Use `@PathSensitive`, `@NormalizeLineEndings` |
+| Absolute paths in outputs | Use relative paths |
+| Missing `@CacheableTask` | Add annotation to custom tasks |
+| Different JDK versions | Standardize JDK across environments |
+
+---
+
+## CI/CD Optimizations
+
+### Remote Build Cache
+
+```kotlin
+// settings.gradle.kts
+buildCache {
+    local { isEnabled = true }
+    remote<HttpBuildCache> {
+        url = uri("https://cache.example.com/")
+        isPush = System.getenv("CI") == "true"
+        credentials {
+            username = System.getenv("CACHE_USER")
+            password = System.getenv("CACHE_PASS")
+        }
+    }
+}
+```
+
+### Gradle Enterprise / Develocity
+
+For advanced build analytics:
+
+```kotlin
+// settings.gradle.kts
+plugins {
+    id("com.gradle.develocity") version "3.17"
+}
+
+develocity {
+    buildScan {
+        termsOfUseUrl.set("https://gradle.com/help/legal-terms-of-use")
+        termsOfUseAgree.set("yes")
+        publishing.onlyIf { System.getenv("CI") != null }
+    }
+}
+```
+
+### Skip Unnecessary Tasks in CI
+
+```bash
+# Skip tests for UI-only changes
+./gradlew assembleDebug -x test -x lint
+
+# Only run affected module tests
+./gradlew :feature:login:test
+```
+
+---
+
+## Android Studio Settings
+
+### File → Settings → Build → Gradle
+
+- **Gradle JDK**: Match your project's JDK
+- **Build and run using**: Gradle (not IntelliJ)
+- **Run tests using**: Gradle
+
+### File → Settings → Build → Compiler
+
+- **Compile independent modules in parallel**: ✅ Enabled
+- **Configure on demand**: ❌ Disabled (deprecated)
+
+---
+
+## Verification Checklist
+
+After optimizations, verify:
+
+- [ ] Configuration cache enabled and working
+- [ ] Build cache hit rate > 80% (check build scan)
+- [ ] No dynamic dependency versions
+- [ ] KSP used instead of kapt where possible
+- [ ] Parallel execution enabled
+- [ ] JVM memory tuned appropriately
+- [ ] CI remote cache configured
+- [ ] No configuration-time I/O
+
+---
+
+## References
+
+- [Optimize Build Speed](https://developer.android.com/build/optimize-your-build)
+- [Gradle Configuration Cache](https://docs.gradle.org/current/userguide/configuration_cache.html)
+- [Gradle Build Cache](https://docs.gradle.org/current/userguide/build_cache.html)
+- [Migrate from kapt to KSP](https://developer.android.com/build/migrate-to-ksp)
+- [Gradle Build Scans](https://scans.gradle.com/)

package/template/agent/skills/mobile-developer/references/android-rules/kotlin-concurrency-expert.md

@@ -0,0 +1,169 @@
+---
+name: kotlin-concurrency-expert
+description: Kotlin Coroutines review and remediation for Android. Use when asked to review concurrency usage, fix coroutine-related bugs, improve thread safety, or resolve lifecycle issues in Kotlin/Android code.
+---
+
+# Kotlin Concurrency Expert
+
+## Overview
+
+Review and fix Kotlin Coroutines issues in Android codebases by applying structured concurrency, lifecycle safety, proper scoping, and modern best practices with minimal behavior changes.
+
+## Workflow
+
+### 1. Triage the Issue
+
+- Capture the exact error, crash, or symptom (ANR, memory leak, race condition, incorrect state).
+- Check project coroutines setup: `kotlinx-coroutines-android` version, `lifecycle-runtime-ktx` version.
+- Identify the current scope context (`viewModelScope`, `lifecycleScope`, custom scope, or none).
+- Confirm whether the code is UI-bound (`Dispatchers.Main`) or intended to run off the main thread (`Dispatchers.IO`, `Dispatchers.Default`).
+- Verify Dispatcher injection patterns for testability.
+
+### 2. Apply the Smallest Safe Fix
+
+Prefer edits that preserve existing behavior while satisfying structured concurrency and lifecycle safety.
+
+Common fixes:
+
+- **ANR / Main thread blocking**: Move heavy work to `withContext(Dispatchers.IO)` or `Dispatchers.Default`; ensure suspend functions are main-safe.
+- **Memory leaks / zombie coroutines**: Replace `GlobalScope` with a lifecycle-bound scope (`viewModelScope`, `lifecycleScope`, or injected `applicationScope`).
+- **Lifecycle collection issues**: Replace deprecated `launchWhenStarted` with `repeatOnLifecycle(Lifecycle.State.STARTED)`.
+- **State exposure**: Encapsulate `MutableStateFlow` / `MutableSharedFlow`; expose read-only `StateFlow` or `Flow`.
+- **CancellationException swallowing**: Ensure generic `catch (e: Exception)` blocks rethrow `CancellationException`.
+- **Non-cooperative cancellation**: Add `ensureActive()` or `yield()` in tight loops for cooperative cancellation.
+- **Callback APIs**: Convert listeners to `callbackFlow` with proper `awaitClose` cleanup.
+- **Hardcoded Dispatchers**: Inject `CoroutineDispatcher` via constructor for testability.
+
+## Critical Rules
+
+### Dispatcher Injection (Testability)
+
+```kotlin
+// CORRECT: Inject dispatcher
+class UserRepository(
+    private val ioDispatcher: CoroutineDispatcher = Dispatchers.IO
+) {
+    suspend fun fetchUser() = withContext(ioDispatcher) { ... }
+}
+
+// INCORRECT: Hardcoded dispatcher
+class UserRepository {
+    suspend fun fetchUser() = withContext(Dispatchers.IO) { ... }
+}
+```
+
+### Lifecycle-Aware Collection
+
+```kotlin
+// CORRECT: Use repeatOnLifecycle
+viewLifecycleOwner.lifecycleScope.launch {
+    viewLifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
+        viewModel.uiState.collect { state -> updateUI(state) }
+    }
+}
+
+// INCORRECT: Direct collection (unsafe, deprecated)
+lifecycleScope.launchWhenStarted {
+    viewModel.uiState.collect { state -> updateUI(state) }
+}
+```
+
+### State Encapsulation
+
+```kotlin
+// CORRECT: Expose read-only StateFlow
+class MyViewModel : ViewModel() {
+    private val _uiState = MutableStateFlow(UiState())
+    val uiState: StateFlow<UiState> = _uiState.asStateFlow()
+}
+
+// INCORRECT: Exposed mutable state
+class MyViewModel : ViewModel() {
+    val uiState = MutableStateFlow(UiState()) // Leaks mutability
+}
+```
+
+### Exception Handling
+
+```kotlin
+// CORRECT: Rethrow CancellationException
+try {
+    doSuspendWork()
+} catch (e: CancellationException) {
+    throw e // Must rethrow!
+} catch (e: Exception) {
+    handleError(e)
+}
+
+// INCORRECT: Swallows cancellation
+try {
+    doSuspendWork()
+} catch (e: Exception) {
+    handleError(e) // CancellationException swallowed!
+}
+```
+
+### Cooperative Cancellation
+
+```kotlin
+// CORRECT: Check for cancellation in tight loops
+suspend fun processLargeList(items: List<Item>) {
+    items.forEach { item ->
+        ensureActive() // Check cancellation
+        processItem(item)
+    }
+}
+
+// INCORRECT: Non-cooperative (ignores cancellation)
+suspend fun processLargeList(items: List<Item>) {
+    items.forEach { item ->
+        processItem(item) // Never checks cancellation
+    }
+}
+```
+
+### Callback Conversion
+
+```kotlin
+// CORRECT: callbackFlow with awaitClose
+fun locationUpdates(): Flow<Location> = callbackFlow {
+    val listener = LocationListener { location ->
+        trySend(location)
+    }
+    locationManager.requestLocationUpdates(listener)
+    
+    awaitClose { locationManager.removeUpdates(listener) }
+}
+```
+
+## Scope Guidelines
+
+| Scope | Use When | Lifecycle |
+|-------|----------|-----------|
+| `viewModelScope` | ViewModel operations | Cleared with ViewModel |
+| `lifecycleScope` | UI operations in Activity/Fragment | Destroyed with lifecycle owner |
+| `repeatOnLifecycle` | Flow collection in UI | Started/Stopped with lifecycle state |
+| `applicationScope` (injected) | App-wide background work | Application lifetime |
+| `GlobalScope` | **NEVER USE** | Breaks structured concurrency |
+
+## Testing Pattern
+
+```kotlin
+@Test
+fun `loading data updates state`() = runTest {
+    val testDispatcher = StandardTestDispatcher(testScheduler)
+    val repository = FakeRepository()
+    val viewModel = MyViewModel(repository, testDispatcher)
+    
+    viewModel.loadData()
+    advanceUntilIdle()
+    
+    assertEquals(UiState.Success(data), viewModel.uiState.value)
+}
+```
+
+## Reference Material
+
+- [Kotlin Coroutines Best Practices](https://developer.android.com/kotlin/coroutines/coroutines-best-practices)
+- [StateFlow and SharedFlow](https://developer.android.com/kotlin/flow/stateflow-and-sharedflow)
+- [repeatOnLifecycle API](https://developer.android.com/topic/libraries/architecture/coroutines#repeatOnLifecycle)

package/template/agent/skills/mobile-developer/references/android-rules/rxjava-to-coroutines-migration.md

@@ -0,0 +1,101 @@
+---
+name: rxjava-to-coroutines-migration
+description: Guide and execute the migration of asynchronous code from RxJava to Kotlin Coroutines and Flow. Use this skill when a user asks to convert RxJava (Observables, Singles, Completables, Subjects) to Coroutines (suspend functions, Flows, StateFlows).
+---
+
+# RxJava to Kotlin Coroutines Migration Skill
+
+A specialized skill designed to safely and idiomatically refactor Android or Kotlin codebases from RxJava to Kotlin Coroutines and Flow.
+
+## Migration Mapping Guide
+
+When migrating RxJava components to Kotlin Coroutines, use the following standard mappings:
+
+### 1. Base Types
+- **`Single<T>`** -> `suspend fun ...(): T`
+  - A single asynchronous value.
+- **`Maybe<T>`** -> `suspend fun ...(): T?`
+  - A single asynchronous value that might not exist.
+- **`Completable`** -> `suspend fun ...()`
+  - An asynchronous operation that completes without a value.
+- **`Observable<T>`** -> `Flow<T>`
+  - A cold stream of values.
+- **`Flowable<T>`** -> `Flow<T>`
+  - Coroutines Flow natively handles backpressure.
+
+### 2. Subjects to Hot Flows
+- **`PublishSubject<T>`** -> `MutableSharedFlow<T>`
+  - Broadcasts events to multiple subscribers. Use `MutableSharedFlow(extraBufferCapacity = ...)` if buffering is needed.
+- **`BehaviorSubject<T>`** -> `MutableStateFlow<T>`
+  - Holds state and emits the current/latest value to new subscribers. Requires an initial value.
+- **`ReplaySubject<T>`** -> `MutableSharedFlow<T>(replay = N)`
+  - Replays the last N emitted values to new subscribers.
+
+### 3. Schedulers to Dispatchers
+- **`Schedulers.io()`** -> `Dispatchers.IO`
+- **`Schedulers.computation()`** -> `Dispatchers.Default`
+- **`AndroidSchedulers.mainThread()`** -> `Dispatchers.Main`
+- *Context Switching*: `subscribeOn` and `observeOn` are typically replaced by `withContext(Dispatcher)` or `flowOn(Dispatcher)` for Flows.
+
+### 4. Operators
+- **`map`** -> `map`
+- **`filter`** -> `filter`
+- **`flatMap`** -> `flatMapMerge` (concurrent) or `flatMapConcat` (sequential)
+- **`switchMap`** -> `flatMapLatest`
+- **`doOnNext` / `doOnSuccess`** -> `onEach`
+- **`onErrorReturn` / `onErrorResumeNext`** -> `catch { emit(...) }`
+- **`startWith`** -> `onStart { emit(...) }`
+- **`combineLatest`** -> `combine`
+- **`zip`** -> `zip`
+- **`delay`** -> `delay` (suspend function) or `onEach { delay(...) }`
+
+### 5. Execution and Lifecycle
+- **`subscribe()`** -> `collect {}` (for Flows) or direct invocation (for suspend functions) inside a `CoroutineScope`.
+- **`Disposable.dispose()`** -> `Job.cancel()`
+- **`CompositeDisposable.clear()`** -> Cancel the parent `CoroutineScope` or `Job`.
+
+## Execution Steps
+
+1. **Analyze the RxJava Chain**: Identify the source type (Single, Observable, etc.), operators used, and where the subscription happens.
+2. **Convert the Source**: Change the return type in the repository or data source layer first. Convert to `suspend` functions for one-shot operations, and `Flow` for streams.
+3. **Rewrite Operators**: Translate the RxJava operators to their Flow or Coroutine equivalents. Note that many RxJava operators can simply be replaced by standard Kotlin collection/sequence operations inside a `map` or `onEach` block.
+4. **Update the Subscription**: Replace `.subscribe(...)` with `launch { ... }` and `.collect { ... }` in the ViewModel or Presenter. Ensure the launch is tied to the correct lifecycle scope (e.g., `viewModelScope`).
+5. **Handle Errors**: Replace `onError` blocks with `try/catch` around suspend functions, or `.catch { }` operators on Flows.
+6. **Handle Threading**: Remove `.subscribeOn()` and `.observeOn()`. Use `withContext` where necessary, or `.flowOn()` to change the context of the upstream flow.
+
+### Example Transformation
+
+**RxJava:**
+```kotlin
+fun getUser(id: String): Single<User> { ... }
+
+disposable.add(
+    getUser("123")
+        .subscribeOn(Schedulers.io())
+        .observeOn(AndroidSchedulers.mainThread())
+        .subscribe({ user ->
+            view.showUser(user)
+        }, { error ->
+            view.showError(error)
+        })
+)
+```
+
+**Coroutines/Flow:**
+```kotlin
+suspend fun getUser(id: String): User { ... } // Internally uses withContext(Dispatchers.IO) if needed
+
+viewModelScope.launch {
+    try {
+        val user = getUser("123")
+        view.showUser(user)
+    } catch (e: Exception) {
+        view.showError(e)
+    }
+}
+```
+
+## Best Practices
+- **Favor Suspend Functions:** Default to `suspend` functions instead of `Flow` unless you actually have a stream of multiple values over time. `Single` and `Completable` almost always become `suspend` functions.
+- **State Handling:** Use `StateFlow` in ViewModels to expose state to the UI instead of `BehaviorSubject` or `LiveData`.
+- **Lifecycle Awareness:** Use `repeatOnLifecycle` or `flowWithLifecycle` in the UI layer when collecting Flows to avoid background work when the view is not visible.