@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/shared/external/android-architecture/SKILL.md

@@ -0,0 +1,407 @@
+---
+name: android-architecture
+description: "Design and implement Clean Architecture with multi-module structure on Android. Covers domain/data/presentation layers, Hilt dependency injection with @Module/@Provides/@Binds, UseCase pattern with operator invoke, Repository pattern with Kotlin Flow, and mapper pattern between layers. Use when structuring a new Android project, adding feature modules, setting up DI, or reviewing architecture compliance."
+---
+
+# Android Clean Architecture
+
+Guidance for structuring Android apps with Clean Architecture, multi-module
+builds, Hilt DI, and idiomatic Kotlin patterns. Targets Kotlin 2.0+, AGP 8.x,
+and Jetpack libraries from 2024-2025.
+
+## Contents
+
+- [Multi-Module Structure](#multi-module-structure)
+- [Domain Layer](#domain-layer)
+- [Data Layer](#data-layer)
+- [Presentation Layer](#presentation-layer)
+- [Hilt Dependency Injection](#hilt-dependency-injection)
+- [Mapper Pattern](#mapper-pattern)
+- [Do's and Don'ts](#dos-and-donts)
+- [Troubleshooting](#troubleshooting)
+- [Review Checklist](#review-checklist)
+
+## Multi-Module Structure
+
+Organize by feature and layer. Each feature module depends on `:core` modules
+but never on other feature modules.
+
+```
+:app                          # Application class, NavHost, Hilt setup
+:core:model                   # Domain models shared across features
+:core:data                    # Repository interfaces, data source contracts
+:core:network                 # Retrofit setup, API service interfaces
+:core:database                # Room setup, DAOs, entities
+:core:common                  # Extensions, Result wrapper, DispatcherProvider
+:core:ui                      # Shared Compose components, theme
+:core:testing                 # Test doubles, rules, helpers
+:feature:home                 # Home screen: UI + ViewModel
+:feature:search               # Search screen: UI + ViewModel
+:feature:detail               # Detail screen: UI + ViewModel
+```
+
+### Module Dependency Rules
+
+```kotlin
+// feature:home/build.gradle.kts
+dependencies {
+    implementation(project(":core:model"))
+    implementation(project(":core:data"))
+    implementation(project(":core:ui"))
+    implementation(project(":core:common"))
+    // NEVER depend on another :feature module
+}
+```
+
+### settings.gradle.kts
+
+```kotlin
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+include(":app")
+include(":core:model")
+include(":core:data")
+include(":core:network")
+include(":core:database")
+include(":core:common")
+include(":core:ui")
+include(":core:testing")
+include(":feature:home")
+include(":feature:search")
+include(":feature:detail")
+```
+
+## Domain Layer
+
+The domain layer contains business logic with zero Android dependencies. It
+lives in `:core:model` (models) and feature modules (use cases).
+
+### Domain Models
+
+```kotlin
+// :core:model
+data class Flight(
+    val id: String,
+    val origin: Airport,
+    val destination: Airport,
+    val departureTime: Instant,
+    val arrivalTime: Instant,
+    val price: Price,
+    val status: FlightStatus,
+)
+
+enum class FlightStatus { SCHEDULED, DELAYED, CANCELLED, LANDED }
+
+data class Price(val amount: Double, val currency: String)
+```
+
+### UseCase with operator invoke
+
+Each use case has a single responsibility. Use `operator fun invoke` so call
+sites read like function calls.
+
+```kotlin
+class GetFlightsUseCase @Inject constructor(
+    private val flightRepository: FlightRepository,
+) {
+    operator fun invoke(origin: String, destination: String): Flow<List<Flight>> =
+        flightRepository.getFlights(origin, destination)
+}
+```
+
+For use cases with parameters, define a data class or use function parameters:
+
+```kotlin
+class SearchFlightsUseCase @Inject constructor(
+    private val repository: FlightRepository,
+) {
+    operator fun invoke(params: Params): Flow<Result<List<Flight>>> =
+        repository.searchFlights(params.query, params.date)
+            .map { Result.success(it) }
+            .catch { emit(Result.failure(it)) }
+
+    data class Params(val query: String, val date: LocalDate)
+}
+```
+
+### Repository Interface (Domain Contract)
+
+```kotlin
+// :core:data
+interface FlightRepository {
+    fun getFlights(origin: String, destination: String): Flow<List<Flight>>
+    fun searchFlights(query: String, date: LocalDate): Flow<List<Flight>>
+    suspend fun bookFlight(flightId: String): Result<Booking>
+}
+```
+
+## Data Layer
+
+The data layer implements repository interfaces. It coordinates between remote
+(API) and local (Room) data sources.
+
+### Repository Implementation
+
+```kotlin
+class FlightRepositoryImpl @Inject constructor(
+    private val remoteDataSource: FlightRemoteDataSource,
+    private val localDataSource: FlightLocalDataSource,
+    private val flightMapper: FlightMapper,
+) : FlightRepository {
+
+    override fun getFlights(origin: String, destination: String): Flow<List<Flight>> =
+        localDataSource.getFlights(origin, destination)
+            .map { entities -> entities.map(flightMapper::toDomain) }
+
+    override fun searchFlights(query: String, date: LocalDate): Flow<List<Flight>> = flow {
+        val dtos = remoteDataSource.searchFlights(query, date.toString())
+        localDataSource.insertFlights(dtos.map(flightMapper::toEntity))
+        emitAll(
+            localDataSource.getFlights(query, query)
+                .map { entities -> entities.map(flightMapper::toDomain) }
+        )
+    }
+
+    override suspend fun bookFlight(flightId: String): Result<Booking> = runCatching {
+        val response = remoteDataSource.bookFlight(flightId)
+        flightMapper.toBookingDomain(response)
+    }
+}
+```
+
+### Data Sources
+
+```kotlin
+// Remote
+class FlightRemoteDataSource @Inject constructor(
+    private val api: FlightApiService,
+) {
+    suspend fun searchFlights(query: String, date: String): List<FlightDto> =
+        api.searchFlights(query, date)
+
+    suspend fun bookFlight(flightId: String): BookingResponse =
+        api.bookFlight(BookingRequest(flightId))
+}
+
+// Local
+class FlightLocalDataSource @Inject constructor(
+    private val dao: FlightDao,
+) {
+    fun getFlights(origin: String, destination: String): Flow<List<FlightEntity>> =
+        dao.getFlights(origin, destination)
+
+    suspend fun insertFlights(entities: List<FlightEntity>) =
+        dao.upsertFlights(entities)
+}
+```
+
+## Presentation Layer
+
+ViewModels expose UI state as `StateFlow` and handle user actions.
+
+```kotlin
+@HiltViewModel
+class HomeViewModel @Inject constructor(
+    private val getFlightsUseCase: GetFlightsUseCase,
+) : ViewModel() {
+
+    private val _uiState = MutableStateFlow<HomeUiState>(HomeUiState.Loading)
+    val uiState: StateFlow<HomeUiState> = _uiState.asStateFlow()
+
+    fun loadFlights(origin: String, destination: String) {
+        viewModelScope.launch {
+            getFlightsUseCase(origin, destination)
+                .map<List<Flight>, HomeUiState> { HomeUiState.Success(it) }
+                .catch { emit(HomeUiState.Error(it.message ?: "Unknown error")) }
+                .collect { _uiState.value = it }
+        }
+    }
+}
+
+sealed interface HomeUiState {
+    data object Loading : HomeUiState
+    data class Success(val flights: List<Flight>) : HomeUiState
+    data class Error(val message: String) : HomeUiState
+}
+```
+
+## Hilt Dependency Injection
+
+### Application Setup
+
+```kotlin
+// :app
+@HiltAndroidApp
+class MyApplication : Application()
+
+// MainActivity
+@AndroidEntryPoint
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContent { AppNavHost() }
+    }
+}
+```
+
+### Module with @Binds (Interface Binding)
+
+```kotlin
+@Module
+@InstallIn(SingletonComponent::class)
+abstract class RepositoryModule {
+
+    @Binds
+    @Singleton
+    abstract fun bindFlightRepository(
+        impl: FlightRepositoryImpl,
+    ): FlightRepository
+}
+```
+
+### Module with @Provides (Instance Creation)
+
+```kotlin
+@Module
+@InstallIn(SingletonComponent::class)
+object NetworkModule {
+
+    @Provides
+    @Singleton
+    fun provideOkHttpClient(): OkHttpClient =
+        OkHttpClient.Builder()
+            .connectTimeout(30, TimeUnit.SECONDS)
+            .readTimeout(30, TimeUnit.SECONDS)
+            .addInterceptor(HttpLoggingInterceptor().apply {
+                level = HttpLoggingInterceptor.Level.BODY
+            })
+            .build()
+
+    @Provides
+    @Singleton
+    fun provideRetrofit(client: OkHttpClient): Retrofit =
+        Retrofit.Builder()
+            .baseUrl(BuildConfig.BASE_URL)
+            .client(client)
+            .addConverterFactory(Json.asConverterFactory("application/json".toMediaType()))
+            .build()
+
+    @Provides
+    @Singleton
+    fun provideFlightApiService(retrofit: Retrofit): FlightApiService =
+        retrofit.create(FlightApiService::class.java)
+}
+```
+
+### DispatcherProvider (Testable Dispatchers)
+
+```kotlin
+// :core:common
+interface DispatcherProvider {
+    val main: CoroutineDispatcher
+    val io: CoroutineDispatcher
+    val default: CoroutineDispatcher
+}
+
+class DefaultDispatcherProvider @Inject constructor() : DispatcherProvider {
+    override val main: CoroutineDispatcher = Dispatchers.Main
+    override val io: CoroutineDispatcher = Dispatchers.IO
+    override val default: CoroutineDispatcher = Dispatchers.Default
+}
+
+@Module
+@InstallIn(SingletonComponent::class)
+abstract class DispatcherModule {
+    @Binds
+    @Singleton
+    abstract fun bindDispatcherProvider(impl: DefaultDispatcherProvider): DispatcherProvider
+}
+```
+
+## Mapper Pattern
+
+Mappers isolate layer boundaries. Each layer has its own model type.
+
+```kotlin
+class FlightMapper @Inject constructor() {
+
+    fun toDomain(entity: FlightEntity): Flight = Flight(
+        id = entity.id,
+        origin = Airport(entity.originCode, entity.originName),
+        destination = Airport(entity.destinationCode, entity.destinationName),
+        departureTime = Instant.parse(entity.departureTime),
+        arrivalTime = Instant.parse(entity.arrivalTime),
+        price = Price(entity.priceAmount, entity.priceCurrency),
+        status = FlightStatus.valueOf(entity.status),
+    )
+
+    fun toEntity(dto: FlightDto): FlightEntity = FlightEntity(
+        id = dto.id,
+        originCode = dto.origin.code,
+        originName = dto.origin.name,
+        destinationCode = dto.destination.code,
+        destinationName = dto.destination.name,
+        departureTime = dto.departureTime,
+        arrivalTime = dto.arrivalTime,
+        priceAmount = dto.price.amount,
+        priceCurrency = dto.price.currency,
+        status = dto.status,
+    )
+
+    fun toBookingDomain(response: BookingResponse): Booking = Booking(
+        id = response.bookingId,
+        confirmationCode = response.confirmationCode,
+        status = BookingStatus.valueOf(response.status),
+    )
+}
+```
+
+## Do's and Don'ts
+
+### Do's
+- Keep domain layer free of Android dependencies (no Context, no R references)
+- Use `operator fun invoke` on use cases for clean call sites
+- Expose `StateFlow` from ViewModels, not `LiveData` in new Compose projects
+- Use `@Binds` for interface-to-implementation binding (generates less code than `@Provides`)
+- Define a `DispatcherProvider` interface for testable coroutine dispatchers
+- One use case per business operation
+- Use `sealed interface` for UI state to guarantee exhaustive `when` handling
+
+### Don'ts
+- Do not let feature modules depend on each other directly
+- Do not put Android framework classes in the domain layer
+- Do not expose `MutableStateFlow` from ViewModels (expose read-only `StateFlow`)
+- Do not inject `Activity` or `Fragment` into ViewModels
+- Do not use `GlobalScope` -- always use `viewModelScope` or a structured scope
+- Do not put business logic in ViewModels -- delegate to use cases
+- Do not use `LiveData` for new Compose-first projects
+
+## Troubleshooting
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| `MissingBinding` Hilt error | Missing `@Binds` or `@Provides` for a dependency | Add the binding in the correct Hilt module |
+| `ComponentProcessingStep was unable to process` | Circular dependency or missing `@InstallIn` | Check module annotations and break circular chains with `@Lazy` or Provider |
+| ViewModel not injected | Missing `@HiltViewModel` or `@AndroidEntryPoint` | Add both annotations |
+| `IllegalStateException: LifecycleOwner` | Accessing lifecycle before `onCreate` | Collect flows in `repeatOnLifecycle` or use Compose's `collectAsStateWithLifecycle` |
+| Module not found in multi-module | Missing `implementation(project(":core:..."))` | Add module dependency in `build.gradle.kts` |
+| KSP not running Hilt processor | Missing KSP plugin or Hilt compiler dependency | Add `id("com.google.devtools.ksp")` and `ksp(libs.hilt.compiler)` |
+
+## Review Checklist
+
+- [ ] Domain models have no Android imports
+- [ ] Use cases have single responsibility with `operator fun invoke`
+- [ ] Repository interfaces are in domain/core, implementations in data
+- [ ] ViewModels expose `StateFlow`, not `MutableStateFlow`
+- [ ] UI state is a `sealed interface` with Loading/Success/Error
+- [ ] Hilt modules use `@Binds` for interfaces, `@Provides` for instances
+- [ ] Feature modules do not depend on each other
+- [ ] Mappers separate DTO/Entity/Domain models
+- [ ] Coroutine dispatchers are injectable via `DispatcherProvider`
+- [ ] No `GlobalScope` usage; all coroutines use structured concurrency

package/pipeline/skills/shared/external/android-jetpack-compose-expert/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: android-jetpack-compose-expert
+description: "Expert guidance for building modern Android UIs with Jetpack Compose, covering state management, navigation, performance, and Material Design 3."
+risk: safe
+source: community
+date_added: "2026-02-27"
+---
+
+# Android Jetpack Compose Expert
+
+## Overview
+
+A comprehensive guide for building production-quality Android applications using Jetpack Compose. This skill covers architectural patterns, state management with ViewModels, navigation type-safety, and performance optimization techniques.
+
+## When to Use This Skill
+
+- Use when starting a new Android project with Jetpack Compose.
+- Use when migrating legacy XML layouts to Compose.
+- Use when implementing complex UI state management and side effects.
+- Use when optimizing Compose performance (recomposition counts, stability).
+- Use when setting up Navigation with type safety.
+
+## Step-by-Step Guide
+
+### 1. Project Setup & Dependencies
+
+Ensure your `libs.versions.toml` includes the necessary Compose BOM and libraries.
+
+```kotlin
+[versions]
+composeBom = "2024.02.01"
+activityCompose = "1.8.2"
+
+[libraries]
+androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "composeBom" }
+androidx-ui = { group = "androidx.compose.ui", name = "ui" }
+androidx-ui-graphics = { group = "androidx.compose.ui", name = "ui-graphics" }
+androidx-ui-tooling-preview = { group = "androidx.compose.ui", name = "ui-tooling-preview" }
+androidx-material3 = { group = "androidx.compose.material3", name = "material3" }
+androidx-activity-compose = { group = "androidx.activity", name = "activity-compose", version.ref = "activityCompose" }
+```
+
+### 2. State Management Pattern (MVI/MVVM)
+
+Use `ViewModel` with `StateFlow` to expose UI state. Avoid exposing `MutableStateFlow`.
+
+```kotlin
+// UI State Definition
+data class UserUiState(
+    val isLoading: Boolean = false,
+    val user: User? = null,
+    val error: String? = null
+)
+
+// ViewModel
+class UserViewModel @Inject constructor(
+    private val userRepository: UserRepository
+) : ViewModel() {
+
+    private val _uiState = MutableStateFlow(UserUiState())
+    val uiState: StateFlow<UserUiState> = _uiState.asStateFlow()
+
+    fun loadUser() {
+        viewModelScope.launch {
+            _uiState.update { it.copy(isLoading = true) }
+            try {
+                val user = userRepository.getUser()
+                _uiState.update { it.copy(user = user, isLoading = false) }
+            } catch (e: Exception) {
+                _uiState.update { it.copy(error = e.message, isLoading = false) }
+            }
+        }
+    }
+}
+```
+
+### 3. Creating the Screen Composable
+
+Consume the state in a "Screen" composable and pass data down to stateless components.
+
+```kotlin
+@Composable
+fun UserScreen(
+    viewModel: UserViewModel = hiltViewModel()
+) {
+    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
+
+    UserContent(
+        uiState = uiState,
+        onRetry = viewModel::loadUser
+    )
+}
+
+@Composable
+fun UserContent(
+    uiState: UserUiState,
+    onRetry: () -> Unit
+) {
+    Scaffold { padding ->
+        Box(modifier = Modifier.padding(padding)) {
+            when {
+                uiState.isLoading -> CircularProgressIndicator()
+                uiState.error != null -> ErrorView(uiState.error, onRetry)
+                uiState.user != null -> UserProfile(uiState.user)
+            }
+        }
+    }
+}
+```
+
+## Examples
+
+### Example 1: Type-Safe Navigation
+
+Using the new Navigation Compose Type Safety (available in recent versions).
+
+```kotlin
+// Define Destinations
+@Serializable
+object Home
+
+@Serializable
+data class Profile(val userId: String)
+
+// Setup NavHost
+@Composable
+fun AppNavHost(navController: NavHostController) {
+    NavHost(navController, startDestination = Home) {
+        composable<Home> {
+            HomeScreen(onNavigateToProfile = { id ->
+                navController.navigate(Profile(userId = id))
+            })
+        }
+        composable<Profile> { backStackEntry ->
+            val profile: Profile = backStackEntry.toRoute()
+            ProfileScreen(userId = profile.userId)
+        }
+    }
+}
+```
+
+## Best Practices
+
+- ✅ **Do:** Use `remember` and `derivedStateOf` to minimize unnecessary calculations during recomposition.
+- ✅ **Do:** Mark data classes used in UI state as `@Immutable` or `@Stable` if they contain `List` or other unstable types to enable smart recomposition skipping.
+- ✅ **Do:** Use `LaunchedEffect` for one-off side effects (like showing a Snackbar) triggered by state changes.
+- ❌ **Don't:** Perform expensive operations (like sorting a list) directly inside the Composable function body without `remember`.
+- ❌ **Don't:** Pass `ViewModel` instances down to child components. Pass only the data (state) and lambda callbacks (events).
+
+## Troubleshooting
+
+**Problem:** Infinite Recomposition loop.
+**Solution:** Check if you are creating new object instances (like `List` or `Modifier`) inside the composition without `remember`, or if you are updating state inside the composition phase instead of a side-effect or callback. Use Layout Inspector to debug recomposition counts.