@h1dr0n/skill-pool 0.1.0

package/skills/kotlin/agents/kotlin-reviewer.md

@@ -0,0 +1,159 @@
+---
+name: kotlin-reviewer
+description: Kotlin and Android/KMP code reviewer. Reviews Kotlin code for idiomatic patterns, coroutine safety, Compose best practices, clean architecture violations, and common Android pitfalls.
+tools: ["Read", "Grep", "Glob", "Bash"]
+model: sonnet
+---
+
+You are a senior Kotlin and Android/KMP code reviewer ensuring idiomatic, safe, and maintainable code.
+
+## Your Role
+
+- Review Kotlin code for idiomatic patterns and Android/KMP best practices
+- Detect coroutine misuse, Flow anti-patterns, and lifecycle bugs
+- Enforce clean architecture module boundaries
+- Identify Compose performance issues and recomposition traps
+- You DO NOT refactor or rewrite code — you report findings only
+
+## Workflow
+
+### Step 1: Gather Context
+
+Run `git diff --staged` and `git diff` to see changes. If no diff, check `git log --oneline -5`. Identify Kotlin/KTS files that changed.
+
+### Step 2: Understand Project Structure
+
+Check for:
+- `build.gradle.kts` or `settings.gradle.kts` to understand module layout
+- `CLAUDE.md` for project-specific conventions
+- Whether this is Android-only, KMP, or Compose Multiplatform
+
+### Step 2b: Security Review
+
+Apply the Kotlin/Android security guidance before continuing:
+- exported Android components, deep links, and intent filters
+- insecure crypto, WebView, and network configuration usage
+- keystore, token, and credential handling
+- platform-specific storage and permission risks
+
+If you find a CRITICAL security issue, stop the review and hand off to `security-reviewer` before doing any further analysis.
+
+### Step 3: Read and Review
+
+Read changed files fully. Apply the review checklist below, checking surrounding code for context.
+
+### Step 4: Report Findings
+
+Use the output format below. Only report issues with >80% confidence.
+
+## Review Checklist
+
+### Architecture (CRITICAL)
+
+- **Domain importing framework** — `domain` module must not import Android, Ktor, Room, or any framework
+- **Data layer leaking to UI** — Entities or DTOs exposed to presentation layer (must map to domain models)
+- **ViewModel business logic** — Complex logic belongs in UseCases, not ViewModels
+- **Circular dependencies** — Module A depends on B and B depends on A
+
+### Coroutines & Flows (HIGH)
+
+- **GlobalScope usage** — Must use structured scopes (`viewModelScope`, `coroutineScope`)
+- **Catching CancellationException** — Must rethrow or not catch; swallowing breaks cancellation
+- **Missing `withContext` for IO** — Database/network calls on `Dispatchers.Main`
+- **StateFlow with mutable state** — Using mutable collections inside StateFlow (must copy)
+- **Flow collection in `init {}`** — Should use `stateIn()` or launch in scope
+- **Missing `WhileSubscribed`** — `stateIn(scope, SharingStarted.Eagerly)` when `WhileSubscribed` is appropriate
+
+```kotlin
+// BAD — swallows cancellation
+try { fetchData() } catch (e: Exception) { log(e) }
+
+// GOOD — preserves cancellation
+try { fetchData() } catch (e: CancellationException) { throw e } catch (e: Exception) { log(e) }
+// or use runCatching and check
+```
+
+### Compose (HIGH)
+
+- **Unstable parameters** — Composables receiving mutable types cause unnecessary recomposition
+- **Side effects outside LaunchedEffect** — Network/DB calls must be in `LaunchedEffect` or ViewModel
+- **NavController passed deep** — Pass lambdas instead of `NavController` references
+- **Missing `key()` in LazyColumn** — Items without stable keys cause poor performance
+- **`remember` with missing keys** — Computation not recalculated when dependencies change
+- **Object allocation in parameters** — Creating objects inline causes recomposition
+
+```kotlin
+// BAD — new lambda every recomposition
+Button(onClick = { viewModel.doThing(item.id) })
+
+// GOOD — stable reference
+val onClick = remember(item.id) { { viewModel.doThing(item.id) } }
+Button(onClick = onClick)
+```
+
+### Kotlin Idioms (MEDIUM)
+
+- **`!!` usage** — Non-null assertion; prefer `?.`, `?:`, `requireNotNull`, or `checkNotNull`
+- **`var` where `val` works** — Prefer immutability
+- **Java-style patterns** — Static utility classes (use top-level functions), getters/setters (use properties)
+- **String concatenation** — Use string templates `"Hello $name"` instead of `"Hello " + name`
+- **`when` without exhaustive branches** — Sealed classes/interfaces should use exhaustive `when`
+- **Mutable collections exposed** — Return `List` not `MutableList` from public APIs
+
+### Android Specific (MEDIUM)
+
+- **Context leaks** — Storing `Activity` or `Fragment` references in singletons/ViewModels
+- **Missing ProGuard rules** — Serialized classes without `@Keep` or ProGuard rules
+- **Hardcoded strings** — User-facing strings not in `strings.xml` or Compose resources
+- **Missing lifecycle handling** — Collecting Flows in Activities without `repeatOnLifecycle`
+
+### Security (CRITICAL)
+
+- **Exported component exposure** — Activities, services, or receivers exported without proper guards
+- **Insecure crypto/storage** — Homegrown crypto, plaintext secrets, or weak keystore usage
+- **Unsafe WebView/network config** — JavaScript bridges, cleartext traffic, permissive trust settings
+- **Sensitive logging** — Tokens, credentials, PII, or secrets emitted to logs
+
+If any CRITICAL security issue is present, stop and escalate to `security-reviewer`.
+
+### Gradle & Build (LOW)
+
+- **Version catalog not used** — Hardcoded versions instead of `libs.versions.toml`
+- **Unnecessary dependencies** — Dependencies added but not used
+- **Missing KMP source sets** — Declaring `androidMain` code that could be `commonMain`
+
+## Output Format
+
+```
+[CRITICAL] Domain module imports Android framework
+File: domain/src/main/kotlin/com/app/domain/UserUseCase.kt:3
+Issue: `import android.content.Context` — domain must be pure Kotlin with no framework dependencies.
+Fix: Move Context-dependent logic to data or platforms layer. Pass data via repository interface.
+
+[HIGH] StateFlow holding mutable list
+File: presentation/src/main/kotlin/com/app/ui/ListViewModel.kt:25
+Issue: `_state.value.items.add(newItem)` mutates the list inside StateFlow — Compose won't detect the change.
+Fix: Use `_state.update { it.copy(items = it.items + newItem) }`
+```
+
+## Summary Format
+
+End every review with:
+
+```
+## Review Summary
+
+| Severity | Count | Status |
+|----------|-------|--------|
+| CRITICAL | 0     | pass   |
+| HIGH     | 1     | block  |
+| MEDIUM   | 2     | info   |
+| LOW      | 0     | note   |
+
+Verdict: BLOCK — HIGH issues must be fixed before merge.
+```
+
+## Approval Criteria
+
+- **Approve**: No CRITICAL or HIGH issues
+- **Block**: Any CRITICAL or HIGH issues — must fix before merge

package/skills/kotlin/manifest.yaml

@@ -0,0 +1,17 @@
+name: kotlin
+version: 0.1.0
+description: Idiomatic Kotlin patterns, coroutines, testing with Kotest/MockK, and build tooling for Android/KMP projects
+depends:
+  - common
+tags:
+  - kotlin
+  - android
+  - kmp
+rules: []
+skills:
+  - skills/kotlin-patterns.md
+  - skills/kotlin-testing.md
+  - skills/kotlin-coroutines-flows.md
+agents:
+  - agents/kotlin-reviewer.md
+  - agents/kotlin-build-resolver.md

package/skills/kotlin/skills/kotlin-coroutines-flows.md

@@ -0,0 +1,284 @@
+---
+name: kotlin-coroutines-flows
+description: Kotlin Coroutines and Flow patterns for Android and KMP — structured concurrency, Flow operators, StateFlow, error handling, and testing.
+origin: ECC
+---
+
+# Kotlin Coroutines & Flows
+
+Patterns for structured concurrency, Flow-based reactive streams, and coroutine testing in Android and Kotlin Multiplatform projects.
+
+## When to Activate
+
+- Writing async code with Kotlin coroutines
+- Using Flow, StateFlow, or SharedFlow for reactive data
+- Handling concurrent operations (parallel loading, debounce, retry)
+- Testing coroutines and Flows
+- Managing coroutine scopes and cancellation
+
+## Structured Concurrency
+
+### Scope Hierarchy
+
+```
+Application
+  └── viewModelScope (ViewModel)
+        └── coroutineScope { } (structured child)
+              ├── async { } (concurrent task)
+              └── async { } (concurrent task)
+```
+
+Always use structured concurrency — never `GlobalScope`:
+
+```kotlin
+// BAD
+GlobalScope.launch { fetchData() }
+
+// GOOD — scoped to ViewModel lifecycle
+viewModelScope.launch { fetchData() }
+
+// GOOD — scoped to composable lifecycle
+LaunchedEffect(key) { fetchData() }
+```
+
+### Parallel Decomposition
+
+Use `coroutineScope` + `async` for parallel work:
+
+```kotlin
+suspend fun loadDashboard(): Dashboard = coroutineScope {
+    val items = async { itemRepository.getRecent() }
+    val stats = async { statsRepository.getToday() }
+    val profile = async { userRepository.getCurrent() }
+    Dashboard(
+        items = items.await(),
+        stats = stats.await(),
+        profile = profile.await()
+    )
+}
+```
+
+### SupervisorScope
+
+Use `supervisorScope` when child failures should not cancel siblings:
+
+```kotlin
+suspend fun syncAll() = supervisorScope {
+    launch { syncItems() }       // failure here won't cancel syncStats
+    launch { syncStats() }
+    launch { syncSettings() }
+}
+```
+
+## Flow Patterns
+
+### Cold Flow — One-Shot to Stream Conversion
+
+```kotlin
+fun observeItems(): Flow<List<Item>> = flow {
+    // Re-emits whenever the database changes
+    itemDao.observeAll()
+        .map { entities -> entities.map { it.toDomain() } }
+        .collect { emit(it) }
+}
+```
+
+### StateFlow for UI State
+
+```kotlin
+class DashboardViewModel(
+    observeProgress: ObserveUserProgressUseCase
+) : ViewModel() {
+    val progress: StateFlow<UserProgress> = observeProgress()
+        .stateIn(
+            scope = viewModelScope,
+            started = SharingStarted.WhileSubscribed(5_000),
+            initialValue = UserProgress.EMPTY
+        )
+}
+```
+
+`WhileSubscribed(5_000)` keeps the upstream active for 5 seconds after the last subscriber leaves — survives configuration changes without restarting.
+
+### Combining Multiple Flows
+
+```kotlin
+val uiState: StateFlow<HomeState> = combine(
+    itemRepository.observeItems(),
+    settingsRepository.observeTheme(),
+    userRepository.observeProfile()
+) { items, theme, profile ->
+    HomeState(items = items, theme = theme, profile = profile)
+}.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), HomeState())
+```
+
+### Flow Operators
+
+```kotlin
+// Debounce search input
+searchQuery
+    .debounce(300)
+    .distinctUntilChanged()
+    .flatMapLatest { query -> repository.search(query) }
+    .catch { emit(emptyList()) }
+    .collect { results -> _state.update { it.copy(results = results) } }
+
+// Retry with exponential backoff
+fun fetchWithRetry(): Flow<Data> = flow { emit(api.fetch()) }
+    .retryWhen { cause, attempt ->
+        if (cause is IOException && attempt < 3) {
+            delay(1000L * (1 shl attempt.toInt()))
+            true
+        } else {
+            false
+        }
+    }
+```
+
+### SharedFlow for One-Time Events
+
+```kotlin
+class ItemListViewModel : ViewModel() {
+    private val _effects = MutableSharedFlow<Effect>()
+    val effects: SharedFlow<Effect> = _effects.asSharedFlow()
+
+    sealed interface Effect {
+        data class ShowSnackbar(val message: String) : Effect
+        data class NavigateTo(val route: String) : Effect
+    }
+
+    private fun deleteItem(id: String) {
+        viewModelScope.launch {
+            repository.delete(id)
+            _effects.emit(Effect.ShowSnackbar("Item deleted"))
+        }
+    }
+}
+
+// Collect in Composable
+LaunchedEffect(Unit) {
+    viewModel.effects.collect { effect ->
+        when (effect) {
+            is Effect.ShowSnackbar -> snackbarHostState.showSnackbar(effect.message)
+            is Effect.NavigateTo -> navController.navigate(effect.route)
+        }
+    }
+}
+```
+
+## Dispatchers
+
+```kotlin
+// CPU-intensive work
+withContext(Dispatchers.Default) { parseJson(largePayload) }
+
+// IO-bound work
+withContext(Dispatchers.IO) { database.query() }
+
+// Main thread (UI) — default in viewModelScope
+withContext(Dispatchers.Main) { updateUi() }
+```
+
+In KMP, use `Dispatchers.Default` and `Dispatchers.Main` (available on all platforms). `Dispatchers.IO` is JVM/Android only — use `Dispatchers.Default` on other platforms or provide via DI.
+
+## Cancellation
+
+### Cooperative Cancellation
+
+Long-running loops must check for cancellation:
+
+```kotlin
+suspend fun processItems(items: List<Item>) = coroutineScope {
+    for (item in items) {
+        ensureActive()  // throws CancellationException if cancelled
+        process(item)
+    }
+}
+```
+
+### Cleanup with try/finally
+
+```kotlin
+viewModelScope.launch {
+    try {
+        _state.update { it.copy(isLoading = true) }
+        val data = repository.fetch()
+        _state.update { it.copy(data = data) }
+    } finally {
+        _state.update { it.copy(isLoading = false) }  // always runs, even on cancellation
+    }
+}
+```
+
+## Testing
+
+### Testing StateFlow with Turbine
+
+```kotlin
+@Test
+fun `search updates item list`() = runTest {
+    val fakeRepository = FakeItemRepository().apply { emit(testItems) }
+    val viewModel = ItemListViewModel(GetItemsUseCase(fakeRepository))
+
+    viewModel.state.test {
+        assertEquals(ItemListState(), awaitItem())  // initial
+
+        viewModel.onSearch("query")
+        val loading = awaitItem()
+        assertTrue(loading.isLoading)
+
+        val loaded = awaitItem()
+        assertFalse(loaded.isLoading)
+        assertEquals(1, loaded.items.size)
+    }
+}
+```
+
+### Testing with TestDispatcher
+
+```kotlin
+@Test
+fun `parallel load completes correctly`() = runTest {
+    val viewModel = DashboardViewModel(
+        itemRepo = FakeItemRepo(),
+        statsRepo = FakeStatsRepo()
+    )
+
+    viewModel.load()
+    advanceUntilIdle()
+
+    val state = viewModel.state.value
+    assertNotNull(state.items)
+    assertNotNull(state.stats)
+}
+```
+
+### Faking Flows
+
+```kotlin
+class FakeItemRepository : ItemRepository {
+    private val _items = MutableStateFlow<List<Item>>(emptyList())
+
+    override fun observeItems(): Flow<List<Item>> = _items
+
+    fun emit(items: List<Item>) { _items.value = items }
+
+    override suspend fun getItemsByCategory(category: String): Result<List<Item>> {
+        return Result.success(_items.value.filter { it.category == category })
+    }
+}
+```
+
+## Anti-Patterns to Avoid
+
+- Using `GlobalScope` — leaks coroutines, no structured cancellation
+- Collecting Flows in `init {}` without a scope — use `viewModelScope.launch`
+- Using `MutableStateFlow` with mutable collections — always use immutable copies: `_state.update { it.copy(list = it.list + newItem) }`
+- Catching `CancellationException` — let it propagate for proper cancellation
+- Using `flowOn(Dispatchers.Main)` to collect — collection dispatcher is the caller's dispatcher
+- Creating `Flow` in `@Composable` without `remember` — recreates the flow every recomposition
+
+## References
+
+See skill: `compose-multiplatform-patterns` for UI consumption of Flows.
+See skill: `android-clean-architecture` for where coroutines fit in layers.