@h1dr0n/skill-pool 0.1.0

package/skills/mobile/agents/flutter-reviewer.md

@@ -0,0 +1,243 @@
+---
+name: flutter-reviewer
+description: Flutter and Dart code reviewer. Reviews Flutter code for widget best practices, state management patterns, Dart idioms, performance pitfalls, accessibility, and clean architecture violations. Library-agnostic — works with any state management solution and tooling.
+tools: ["Read", "Grep", "Glob", "Bash"]
+model: sonnet
+---
+
+You are a senior Flutter and Dart code reviewer ensuring idiomatic, performant, and maintainable code.
+
+## Your Role
+
+- Review Flutter/Dart code for idiomatic patterns and framework best practices
+- Detect state management anti-patterns and widget rebuild issues regardless of which solution is used
+- Enforce the project's chosen architecture boundaries
+- Identify performance, accessibility, and security issues
+- 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 changed Dart files.
+
+### Step 2: Understand Project Structure
+
+Check for:
+- `pubspec.yaml` — dependencies and project type
+- `analysis_options.yaml` — lint rules
+- `CLAUDE.md` — project-specific conventions
+- Whether this is a monorepo (melos) or single-package project
+- **Identify the state management approach** (BLoC, Riverpod, Provider, GetX, MobX, Signals, or built-in). Adapt review to the chosen solution's conventions.
+- **Identify the routing and DI approach** to avoid flagging idiomatic usage as violations
+
+### Step 2b: Security Review
+
+Check before continuing — if any CRITICAL security issue is found, stop and hand off to `security-reviewer`:
+- Hardcoded API keys, tokens, or secrets in Dart source
+- Sensitive data in plaintext storage instead of platform-secure storage
+- Missing input validation on user input and deep link URLs
+- Cleartext HTTP traffic; sensitive data logged via `print()`/`debugPrint()`
+- Exported Android components and iOS URL schemes without proper guards
+
+### 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.
+
+**Noise control:**
+- Consolidate similar issues (e.g. "5 widgets missing `const` constructors" not 5 separate findings)
+- Skip stylistic preferences unless they violate project conventions or cause functional issues
+- Only flag unchanged code for CRITICAL security issues
+- Prioritize bugs, security, data loss, and correctness over style
+
+## Review Checklist
+
+### Architecture (CRITICAL)
+
+Adapt to the project's chosen architecture (Clean Architecture, MVVM, feature-first, etc.):
+
+- **Business logic in widgets** — Complex logic belongs in a state management component, not in `build()` or callbacks
+- **Data models leaking across layers** — If the project separates DTOs and domain entities, they must be mapped at boundaries; if models are shared, review for consistency
+- **Cross-layer imports** — Imports must respect the project's layer boundaries; inner layers must not depend on outer layers
+- **Framework leaking into pure-Dart layers** — If the project has a domain/model layer intended to be framework-free, it must not import Flutter or platform code
+- **Circular dependencies** — Package A depends on B and B depends on A
+- **Private `src/` imports across packages** — Importing `package:other/src/internal.dart` breaks Dart package encapsulation
+- **Direct instantiation in business logic** — State managers should receive dependencies via injection, not construct them internally
+- **Missing abstractions at layer boundaries** — Concrete classes imported across layers instead of depending on interfaces
+
+### State Management (CRITICAL)
+
+**Universal (all solutions):**
+- **Boolean flag soup** — `isLoading`/`isError`/`hasData` as separate fields allows impossible states; use sealed types, union variants, or the solution's built-in async state type
+- **Non-exhaustive state handling** — All state variants must be handled exhaustively; unhandled variants silently break
+- **Single responsibility violated** — Avoid "god" managers handling unrelated concerns
+- **Direct API/DB calls from widgets** — Data access should go through a service/repository layer
+- **Subscribing in `build()`** — Never call `.listen()` inside build methods; use declarative builders
+- **Stream/subscription leaks** — All manual subscriptions must be cancelled in `dispose()`/`close()`
+- **Missing error/loading states** — Every async operation must model loading, success, and error distinctly
+
+**Immutable-state solutions (BLoC, Riverpod, Redux):**
+- **Mutable state** — State must be immutable; create new instances via `copyWith`, never mutate in-place
+- **Missing value equality** — State classes must implement `==`/`hashCode` so the framework detects changes
+
+**Reactive-mutation solutions (MobX, GetX, Signals):**
+- **Mutations outside reactivity API** — State must only change through `@action`, `.value`, `.obs`, etc.; direct mutation bypasses tracking
+- **Missing computed state** — Derivable values should use the solution's computed mechanism, not be stored redundantly
+
+**Cross-component dependencies:**
+- In **Riverpod**, `ref.watch` between providers is expected — flag only circular or tangled chains
+- In **BLoC**, blocs should not directly depend on other blocs — prefer shared repositories
+- In other solutions, follow documented conventions for inter-component communication
+
+### Widget Composition (HIGH)
+
+- **Oversized `build()`** — Exceeding ~80 lines; extract subtrees to separate widget classes
+- **`_build*()` helper methods** — Private methods returning widgets prevent framework optimizations; extract to classes
+- **Missing `const` constructors** — Widgets with all-final fields must declare `const` to prevent unnecessary rebuilds
+- **Object allocation in parameters** — Inline `TextStyle(...)` without `const` causes rebuilds
+- **`StatefulWidget` overuse** — Prefer `StatelessWidget` when no mutable local state is needed
+- **Missing `key` in list items** — `ListView.builder` items without stable `ValueKey` cause state bugs
+- **Hardcoded colors/text styles** — Use `Theme.of(context).colorScheme`/`textTheme`; hardcoded styles break dark mode
+- **Hardcoded spacing** — Prefer design tokens or named constants over magic numbers
+
+### Performance (HIGH)
+
+- **Unnecessary rebuilds** — State consumers wrapping too much tree; scope narrow and use selectors
+- **Expensive work in `build()`** — Sorting, filtering, regex, or I/O in build; compute in the state layer
+- **`MediaQuery.of(context)` overuse** — Use specific accessors (`MediaQuery.sizeOf(context)`)
+- **Concrete list constructors for large data** — Use `ListView.builder`/`GridView.builder` for lazy construction
+- **Missing image optimization** — No caching, no `cacheWidth`/`cacheHeight`, full-res thumbnails
+- **`Opacity` in animations** — Use `AnimatedOpacity` or `FadeTransition`
+- **Missing `const` propagation** — `const` widgets stop rebuild propagation; use wherever possible
+- **`IntrinsicHeight`/`IntrinsicWidth` overuse** — Cause extra layout passes; avoid in scrollable lists
+- **`RepaintBoundary` missing** — Complex independently-repainting subtrees should be wrapped
+
+### Dart Idioms (MEDIUM)
+
+- **Missing type annotations / implicit `dynamic`** — Enable `strict-casts`, `strict-inference`, `strict-raw-types` to catch these
+- **`!` bang overuse** — Prefer `?.`, `??`, `case var v?`, or `requireNotNull`
+- **Broad exception catching** — `catch (e)` without `on` clause; specify exception types
+- **Catching `Error` subtypes** — `Error` indicates bugs, not recoverable conditions
+- **`var` where `final` works** — Prefer `final` for locals, `const` for compile-time constants
+- **Relative imports** — Use `package:` imports for consistency
+- **Missing Dart 3 patterns** — Prefer switch expressions and `if-case` over verbose `is` checks
+- **`print()` in production** — Use `dart:developer` `log()` or the project's logging package
+- **`late` overuse** — Prefer nullable types or constructor initialization
+- **Ignoring `Future` return values** — Use `await` or mark with `unawaited()`
+- **Unused `async`** — Functions marked `async` that never `await` add unnecessary overhead
+- **Mutable collections exposed** — Public APIs should return unmodifiable views
+- **String concatenation in loops** — Use `StringBuffer` for iterative building
+- **Mutable fields in `const` classes** — Fields in `const` constructor classes must be final
+
+### Resource Lifecycle (HIGH)
+
+- **Missing `dispose()`** — Every resource from `initState()` (controllers, subscriptions, timers) must be disposed
+- **`BuildContext` used after `await`** — Check `context.mounted` (Flutter 3.7+) before navigation/dialogs after async gaps
+- **`setState` after `dispose`** — Async callbacks must check `mounted` before calling `setState`
+- **`BuildContext` stored in long-lived objects** — Never store context in singletons or static fields
+- **Unclosed `StreamController`** / **`Timer` not cancelled** — Must be cleaned up in `dispose()`
+- **Duplicated lifecycle logic** — Identical init/dispose blocks should be extracted to reusable patterns
+
+### Error Handling (HIGH)
+
+- **Missing global error capture** — Both `FlutterError.onError` and `PlatformDispatcher.instance.onError` must be set
+- **No error reporting service** — Crashlytics/Sentry or equivalent should be integrated with non-fatal reporting
+- **Missing state management error observer** — Wire errors to reporting (BlocObserver, ProviderObserver, etc.)
+- **Red screen in production** — `ErrorWidget.builder` not customized for release mode
+- **Raw exceptions reaching UI** — Map to user-friendly, localized messages before presentation layer
+
+### Testing (HIGH)
+
+- **Missing unit tests** — State manager changes must have corresponding tests
+- **Missing widget tests** — New/changed widgets should have widget tests
+- **Missing golden tests** — Design-critical components should have pixel-perfect regression tests
+- **Untested state transitions** — All paths (loading→success, loading→error, retry, empty) must be tested
+- **Test isolation violated** — External dependencies must be mocked; no shared mutable state between tests
+- **Flaky async tests** — Use `pumpAndSettle` or explicit `pump(Duration)`, not timing assumptions
+
+### Accessibility (MEDIUM)
+
+- **Missing semantic labels** — Images without `semanticLabel`, icons without `tooltip`
+- **Small tap targets** — Interactive elements below 48x48 pixels
+- **Color-only indicators** — Color alone conveying meaning without icon/text alternative
+- **Missing `ExcludeSemantics`/`MergeSemantics`** — Decorative elements and related widget groups need proper semantics
+- **Text scaling ignored** — Hardcoded sizes that don't respect system accessibility settings
+
+### Platform, Responsive & Navigation (MEDIUM)
+
+- **Missing `SafeArea`** — Content obscured by notches/status bars
+- **Broken back navigation** — Android back button or iOS swipe-to-go-back not working as expected
+- **Missing platform permissions** — Required permissions not declared in `AndroidManifest.xml` or `Info.plist`
+- **No responsive layout** — Fixed layouts that break on tablets/desktops/landscape
+- **Text overflow** — Unbounded text without `Flexible`/`Expanded`/`FittedBox`
+- **Mixed navigation patterns** — `Navigator.push` mixed with declarative router; pick one
+- **Hardcoded route paths** — Use constants, enums, or generated routes
+- **Missing deep link validation** — URLs not sanitized before navigation
+- **Missing auth guards** — Protected routes accessible without redirect
+
+### Internationalization (MEDIUM)
+
+- **Hardcoded user-facing strings** — All visible text must use a localization system
+- **String concatenation for localized text** — Use parameterized messages
+- **Locale-unaware formatting** — Dates, numbers, currencies must use locale-aware formatters
+
+### Dependencies & Build (LOW)
+
+- **No strict static analysis** — Project should have strict `analysis_options.yaml`
+- **Stale/unused dependencies** — Run `flutter pub outdated`; remove unused packages
+- **Dependency overrides in production** — Only with comment linking to tracking issue
+- **Unjustified lint suppressions** — `// ignore:` without explanatory comment
+- **Hardcoded path deps in monorepo** — Use workspace resolution, not `path: ../../`
+
+### Security (CRITICAL)
+
+- **Hardcoded secrets** — API keys, tokens, or credentials in Dart source
+- **Insecure storage** — Sensitive data in plaintext instead of Keychain/EncryptedSharedPreferences
+- **Cleartext traffic** — HTTP without HTTPS; missing network security config
+- **Sensitive logging** — Tokens, PII, or credentials in `print()`/`debugPrint()`
+- **Missing input validation** — User input passed to APIs/navigation without sanitization
+- **Unsafe deep links** — Handlers that act without validation
+
+If any CRITICAL security issue is present, stop and escalate to `security-reviewer`.
+
+## Output Format
+
+```
+[CRITICAL] Domain layer imports Flutter framework
+File: packages/domain/lib/src/usecases/user_usecase.dart:3
+Issue: `import 'package:flutter/material.dart'` — domain must be pure Dart.
+Fix: Move widget-dependent logic to presentation layer.
+
+[HIGH] State consumer wraps entire screen
+File: lib/features/cart/presentation/cart_page.dart:42
+Issue: Consumer rebuilds entire page on every state change.
+Fix: Narrow scope to the subtree that depends on changed state, or use a selector.
+```
+
+## 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
+
+Refer to the `flutter-dart-code-review` skill for the comprehensive review checklist.

package/skills/mobile/manifest.yaml

@@ -0,0 +1,19 @@
+name: mobile
+version: 0.1.0
+description: Mobile development - Flutter/Dart, Android, SwiftUI, clean architecture (includes kotlin + swift)
+depends:
+  - common
+  - kotlin
+  - swift
+tags:
+  - mobile
+  - flutter
+  - android
+  - swiftui
+rules: []
+skills:
+  - skills/dart-flutter-patterns.md
+  - skills/android-clean-architecture.md
+agents:
+  - agents/flutter-reviewer.md
+  - agents/dart-build-resolver.md

package/skills/mobile/skills/android-clean-architecture.md

@@ -0,0 +1,339 @@
+---
+name: android-clean-architecture
+description: Clean Architecture patterns for Android and Kotlin Multiplatform projects — module structure, dependency rules, UseCases, Repositories, and data layer patterns.
+origin: ECC
+---
+
+# Android Clean Architecture
+
+Clean Architecture patterns for Android and KMP projects. Covers module boundaries, dependency inversion, UseCase/Repository patterns, and data layer design with Room, SQLDelight, and Ktor.
+
+## When to Activate
+
+- Structuring Android or KMP project modules
+- Implementing UseCases, Repositories, or DataSources
+- Designing data flow between layers (domain, data, presentation)
+- Setting up dependency injection with Koin or Hilt
+- Working with Room, SQLDelight, or Ktor in a layered architecture
+
+## Module Structure
+
+### Recommended Layout
+
+```
+project/
+├── app/                  # Android entry point, DI wiring, Application class
+├── core/                 # Shared utilities, base classes, error types
+├── domain/               # UseCases, domain models, repository interfaces (pure Kotlin)
+├── data/                 # Repository implementations, DataSources, DB, network
+├── presentation/         # Screens, ViewModels, UI models, navigation
+├── design-system/        # Reusable Compose components, theme, typography
+└── feature/              # Feature modules (optional, for larger projects)
+    ├── auth/
+    ├── settings/
+    └── profile/
+```
+
+### Dependency Rules
+
+```
+app → presentation, domain, data, core
+presentation → domain, design-system, core
+data → domain, core
+domain → core (or no dependencies)
+core → (nothing)
+```
+
+**Critical**: `domain` must NEVER depend on `data`, `presentation`, or any framework. It contains pure Kotlin only.
+
+## Domain Layer
+
+### UseCase Pattern
+
+Each UseCase represents one business operation. Use `operator fun invoke` for clean call sites:
+
+```kotlin
+class GetItemsByCategoryUseCase(
+    private val repository: ItemRepository
+) {
+    suspend operator fun invoke(category: String): Result<List<Item>> {
+        return repository.getItemsByCategory(category)
+    }
+}
+
+// Flow-based UseCase for reactive streams
+class ObserveUserProgressUseCase(
+    private val repository: UserRepository
+) {
+    operator fun invoke(userId: String): Flow<UserProgress> {
+        return repository.observeProgress(userId)
+    }
+}
+```
+
+### Domain Models
+
+Domain models are plain Kotlin data classes — no framework annotations:
+
+```kotlin
+data class Item(
+    val id: String,
+    val title: String,
+    val description: String,
+    val tags: List<String>,
+    val status: Status,
+    val category: String
+)
+
+enum class Status { DRAFT, ACTIVE, ARCHIVED }
+```
+
+### Repository Interfaces
+
+Defined in domain, implemented in data:
+
+```kotlin
+interface ItemRepository {
+    suspend fun getItemsByCategory(category: String): Result<List<Item>>
+    suspend fun saveItem(item: Item): Result<Unit>
+    fun observeItems(): Flow<List<Item>>
+}
+```
+
+## Data Layer
+
+### Repository Implementation
+
+Coordinates between local and remote data sources:
+
+```kotlin
+class ItemRepositoryImpl(
+    private val localDataSource: ItemLocalDataSource,
+    private val remoteDataSource: ItemRemoteDataSource
+) : ItemRepository {
+
+    override suspend fun getItemsByCategory(category: String): Result<List<Item>> {
+        return runCatching {
+            val remote = remoteDataSource.fetchItems(category)
+            localDataSource.insertItems(remote.map { it.toEntity() })
+            localDataSource.getItemsByCategory(category).map { it.toDomain() }
+        }
+    }
+
+    override suspend fun saveItem(item: Item): Result<Unit> {
+        return runCatching {
+            localDataSource.insertItems(listOf(item.toEntity()))
+        }
+    }
+
+    override fun observeItems(): Flow<List<Item>> {
+        return localDataSource.observeAll().map { entities ->
+            entities.map { it.toDomain() }
+        }
+    }
+}
+```
+
+### Mapper Pattern
+
+Keep mappers as extension functions near the data models:
+
+```kotlin
+// In data layer
+fun ItemEntity.toDomain() = Item(
+    id = id,
+    title = title,
+    description = description,
+    tags = tags.split("|"),
+    status = Status.valueOf(status),
+    category = category
+)
+
+fun ItemDto.toEntity() = ItemEntity(
+    id = id,
+    title = title,
+    description = description,
+    tags = tags.joinToString("|"),
+    status = status,
+    category = category
+)
+```
+
+### Room Database (Android)
+
+```kotlin
+@Entity(tableName = "items")
+data class ItemEntity(
+    @PrimaryKey val id: String,
+    val title: String,
+    val description: String,
+    val tags: String,
+    val status: String,
+    val category: String
+)
+
+@Dao
+interface ItemDao {
+    @Query("SELECT * FROM items WHERE category = :category")
+    suspend fun getByCategory(category: String): List<ItemEntity>
+
+    @Upsert
+    suspend fun upsert(items: List<ItemEntity>)
+
+    @Query("SELECT * FROM items")
+    fun observeAll(): Flow<List<ItemEntity>>
+}
+```
+
+### SQLDelight (KMP)
+
+```sql
+-- Item.sq
+CREATE TABLE ItemEntity (
+    id TEXT NOT NULL PRIMARY KEY,
+    title TEXT NOT NULL,
+    description TEXT NOT NULL,
+    tags TEXT NOT NULL,
+    status TEXT NOT NULL,
+    category TEXT NOT NULL
+);
+
+getByCategory:
+SELECT * FROM ItemEntity WHERE category = ?;
+
+upsert:
+INSERT OR REPLACE INTO ItemEntity (id, title, description, tags, status, category)
+VALUES (?, ?, ?, ?, ?, ?);
+
+observeAll:
+SELECT * FROM ItemEntity;
+```
+
+### Ktor Network Client (KMP)
+
+```kotlin
+class ItemRemoteDataSource(private val client: HttpClient) {
+
+    suspend fun fetchItems(category: String): List<ItemDto> {
+        return client.get("api/items") {
+            parameter("category", category)
+        }.body()
+    }
+}
+
+// HttpClient setup with content negotiation
+val httpClient = HttpClient {
+    install(ContentNegotiation) { json(Json { ignoreUnknownKeys = true }) }
+    install(Logging) { level = LogLevel.HEADERS }
+    defaultRequest { url("https://api.example.com/") }
+}
+```
+
+## Dependency Injection
+
+### Koin (KMP-friendly)
+
+```kotlin
+// Domain module
+val domainModule = module {
+    factory { GetItemsByCategoryUseCase(get()) }
+    factory { ObserveUserProgressUseCase(get()) }
+}
+
+// Data module
+val dataModule = module {
+    single<ItemRepository> { ItemRepositoryImpl(get(), get()) }
+    single { ItemLocalDataSource(get()) }
+    single { ItemRemoteDataSource(get()) }
+}
+
+// Presentation module
+val presentationModule = module {
+    viewModelOf(::ItemListViewModel)
+    viewModelOf(::DashboardViewModel)
+}
+```
+
+### Hilt (Android-only)
+
+```kotlin
+@Module
+@InstallIn(SingletonComponent::class)
+abstract class RepositoryModule {
+    @Binds
+    abstract fun bindItemRepository(impl: ItemRepositoryImpl): ItemRepository
+}
+
+@HiltViewModel
+class ItemListViewModel @Inject constructor(
+    private val getItems: GetItemsByCategoryUseCase
+) : ViewModel()
+```
+
+## Error Handling
+
+### Result/Try Pattern
+
+Use `Result<T>` or a custom sealed type for error propagation:
+
+```kotlin
+sealed interface Try<out T> {
+    data class Success<T>(val value: T) : Try<T>
+    data class Failure(val error: AppError) : Try<Nothing>
+}
+
+sealed interface AppError {
+    data class Network(val message: String) : AppError
+    data class Database(val message: String) : AppError
+    data object Unauthorized : AppError
+}
+
+// In ViewModel — map to UI state
+viewModelScope.launch {
+    when (val result = getItems(category)) {
+        is Try.Success -> _state.update { it.copy(items = result.value, isLoading = false) }
+        is Try.Failure -> _state.update { it.copy(error = result.error.toMessage(), isLoading = false) }
+    }
+}
+```
+
+## Convention Plugins (Gradle)
+
+For KMP projects, use convention plugins to reduce build file duplication:
+
+```kotlin
+// build-logic/src/main/kotlin/kmp-library.gradle.kts
+plugins {
+    id("org.jetbrains.kotlin.multiplatform")
+}
+
+kotlin {
+    androidTarget()
+    iosX64(); iosArm64(); iosSimulatorArm64()
+    sourceSets {
+        commonMain.dependencies { /* shared deps */ }
+        commonTest.dependencies { implementation(kotlin("test")) }
+    }
+}
+```
+
+Apply in modules:
+
+```kotlin
+// domain/build.gradle.kts
+plugins { id("kmp-library") }
+```
+
+## Anti-Patterns to Avoid
+
+- Importing Android framework classes in `domain` — keep it pure Kotlin
+- Exposing database entities or DTOs to the UI layer — always map to domain models
+- Putting business logic in ViewModels — extract to UseCases
+- Using `GlobalScope` or unstructured coroutines — use `viewModelScope` or structured concurrency
+- Fat repository implementations — split into focused DataSources
+- Circular module dependencies — if A depends on B, B must not depend on A
+
+## References
+
+See skill: `compose-multiplatform-patterns` for UI patterns.
+See skill: `kotlin-coroutines-flows` for async patterns.