@mmerterden/multi-agent-pipeline 20.0.0 → 20.2.0

package/pipeline/skills/shared/external/android-design-tokens-codegen/references/patterns.md

@@ -0,0 +1,270 @@
+# Android Design Tokens Codegen - Patterns
+
+Copy-ready Gradle and Kotlin for the schema-to-typed-code pipeline. Each heading
+mirrors a section in `SKILL.md`. All input is a local JSON schema; all output is
+generated Kotlin under the build directory. Names are illustrative and generic.
+
+## Task wrapper
+
+A typed task whose only job is declaring inputs/outputs and invoking a generator.
+
+```kotlin
+abstract class GenerateFromSchemaTask : DefaultTask() {
+
+    @get:InputFile
+    @get:PathSensitive(PathSensitivity.RELATIVE)
+    abstract val schema: RegularFileProperty
+
+    @get:Classpath
+    abstract val generatorClasspath: ConfigurableFileCollection
+
+    @get:Input
+    abstract val packageName: Property<String>
+
+    @get:Input
+    abstract val checkMode: Property<Boolean>
+
+    @get:OutputDirectory
+    abstract val outputDir: DirectoryProperty
+
+    @get:Inject
+    abstract val execOps: ExecOperations
+
+    @TaskAction
+    fun run() {
+        execOps.javaexec {
+            classpath = generatorClasspath
+            mainClass.set("com.example.codegen.MainKt")
+            args(
+                "--schema", schema.get().asFile.absolutePath,
+                "--package", packageName.get(),
+                "--out", outputDir.get().asFile.absolutePath,
+            )
+            if (checkMode.get()) args("--check")
+        }
+    }
+}
+```
+
+### Registration with a resolvable generator configuration
+
+```kotlin
+val codegen: Configuration by configurations.creating { isCanBeConsumed = false }
+
+dependencies {
+    codegen("com.example:token-codegen:1.4.0")
+}
+
+fun registerGenerator(name: String, schemaPath: String, out: String, pkg: String) =
+    tasks.register<GenerateFromSchemaTask>(name) {
+        schema.set(layout.projectDirectory.file(schemaPath))
+        generatorClasspath.from(codegen)
+        packageName.set(pkg)
+        outputDir.set(layout.buildDirectory.dir("generated/source/$name"))
+        checkMode.set(providers.gradleProperty("codegen.check").isPresent)
+    }
+```
+
+### WorkAction isolation (generator runs in a worker, keeps daemon clean)
+
+```kotlin
+interface GenerateParams : WorkParameters {
+    val schema: RegularFileProperty
+    val outputDir: DirectoryProperty
+    val checkMode: Property<Boolean>
+}
+
+abstract class GenerateAction : WorkAction<GenerateParams> {
+    override fun execute() {
+        val out = parameters.outputDir.get().asFile
+        // parse parameters.schema, emit into out, or compare when checkMode is set
+    }
+}
+
+// inside @TaskAction:
+workerExecutor.classLoaderIsolation { classpath.from(generatorClasspath) }
+    .submit(GenerateAction::class.java) {
+        schema.set(this@GenerateFromSchemaTask.schema)
+        outputDir.set(this@GenerateFromSchemaTask.outputDir)
+        checkMode.set(this@GenerateFromSchemaTask.checkMode)
+    }
+```
+
+## preBuild wiring
+
+Register every generator's output as a variant generated-source directory and
+make `preBuild` depend on all of them.
+
+```kotlin
+val generators = listOf(
+    registerGenerator("generateDesignTokens", "schema/tokens.json",    "gen/tokens",    "com.example.tokens"),
+    registerGenerator("generateTestIds",      "schema/test-ids.json",  "gen/testids",   "com.example.testids"),
+    registerGenerator("generateAnalytics",    "schema/analytics.json", "gen/analytics", "com.example.analytics"),
+    registerGenerator("generateDeeplinks",    "schema/deeplinks.json", "gen/deeplinks", "com.example.deeplinks"),
+)
+
+androidComponents.onVariants { variant ->
+    generators.forEach { gen ->
+        variant.sources.java?.addGeneratedSourceDirectory(gen, GenerateFromSchemaTask::outputDir)
+    }
+}
+
+tasks.named("preBuild").configure { dependsOn(generators) }
+```
+
+Ordering when a KSP or annotation processor consumes generated types: the
+`addGeneratedSourceDirectory` call already wires KSP/kapt to depend on the
+generator, so generated tokens are visible to processors without extra
+`mustRunAfter`. Only add explicit ordering if a generator reads another
+generator's output, which is an anti-pattern to avoid.
+
+## Check mode
+
+The check task regenerates into a temp dir and compares, failing on any diff.
+Prefer building this into the generator binary (`--check`) so the same code path
+produces and verifies. A Gradle-side comparison when the binary lacks it:
+
+```kotlin
+abstract class VerifyCodegenTask : DefaultTask() {
+
+    @get:InputDirectory abstract val committed: DirectoryProperty
+    @get:InputDirectory abstract val regenerated: DirectoryProperty
+
+    @TaskAction
+    fun verify() {
+        val a = committed.get().asFile
+        val b = regenerated.get().asFile
+        val diffs = a.walkTopDown().filter { it.isFile }.mapNotNull { file ->
+            val other = b.resolve(file.relativeTo(a).path)
+            if (!other.exists() || other.readText() != file.readText()) file.path else null
+        }.toList()
+        if (diffs.isNotEmpty()) {
+            throw GradleException(
+                "Generated code is stale. Run ./gradlew generateDesignTokens generateTestIds " +
+                "generateAnalytics generateDeeplinks and commit. Drifted:\n" +
+                diffs.joinToString("\n") { "  - $it" }
+            )
+        }
+    }
+}
+```
+
+Wire the aggregate into the verification lifecycle:
+
+```kotlin
+val checkCodegenFresh = tasks.register("checkCodegenFresh") {
+    dependsOn(generators.map { it.map { t -> t.name } })
+    // in committed-output repos, run each generator with -Pcodegen.check
+}
+tasks.named("check").configure { dependsOn(checkCodegenFresh) }
+```
+
+### Determinism checklist for the generator
+
+- Sort every emitted map/list by a stable key before writing.
+- No timestamps, build numbers, machine names, or absolute paths in output.
+- Fixed formatter (e.g. a pinned KotlinPoet version) and fixed indentation.
+- Stable file naming; one deterministic file per logical group.
+- Same JSON in, byte-identical Kotlin out, on any machine.
+
+## Caching
+
+```kotlin
+@CacheableTask
+abstract class GenerateFromSchemaTask : DefaultTask() {
+
+    @get:InputFile
+    @get:PathSensitive(PathSensitivity.RELATIVE)
+    abstract val schema: RegularFileProperty
+
+    @get:Classpath
+    abstract val generatorClasspath: ConfigurableFileCollection
+
+    @get:Input
+    abstract val generatorVersion: Property<String>
+
+    @get:OutputDirectory
+    abstract val outputDir: DirectoryProperty
+}
+```
+
+`@Classpath` on the generator artifact and `@Input` on its version mean a
+generator upgrade invalidates the cached output; a schema edit invalidates via
+`@InputFile`; an unchanged build is `UP-TO-DATE` or `FROM-CACHE`.
+
+`gradle.properties`:
+
+```properties
+org.gradle.caching=true
+org.gradle.configuration-cache=true
+org.gradle.parallel=true
+```
+
+## Generated shapes
+
+Illustrative target Kotlin per domain. Structure is the point; the specific
+tokens, tags, events, and routes come from each repo's own schema.
+
+### Design tokens (semantic data class, consumed by the Theme layer)
+
+```kotlin
+data class SemanticColors(
+    val surface: Long,
+    val onSurface: Long,
+    val accent: Long,
+)
+
+val lightColors = SemanticColors(surface = 0xFFFFFFFF, onSurface = 0xFF1A1A1A, accent = 0xFF2962FF)
+val darkColors  = SemanticColors(surface = 0xFF121212, onSurface = 0xFFEDEDED, accent = 0xFF82B1FF)
+
+object Spacing { const val xs = 4; const val sm = 8; const val md = 16; const val lg = 24 }
+```
+
+### UI-test identifiers (one typed constant per tag)
+
+```kotlin
+object TestTags {
+    const val PrimaryButton = "primary_button"
+    const val EmailField = "email_field"
+    const val ErrorBanner = "error_banner"
+}
+
+// UI:   Modifier.testTag(TestTags.PrimaryButton)
+// Test: onNodeWithTag(TestTags.PrimaryButton).assertIsDisplayed()
+```
+
+### Analytics events (name plus typed parameters)
+
+```kotlin
+sealed interface AnalyticsEvent {
+    val name: String
+    val params: Map<String, String>
+
+    data class ScreenViewed(val screen: String) : AnalyticsEvent {
+        override val name = "screen_viewed"
+        override val params get() = mapOf("screen" to screen)
+    }
+
+    data class ItemSelected(val itemId: String, val position: Int) : AnalyticsEvent {
+        override val name = "item_selected"
+        override val params get() = mapOf("item_id" to itemId, "position" to position.toString())
+    }
+}
+```
+
+### Deeplink manifest (routes plus typed parameters)
+
+```kotlin
+enum class Deeplink(val path: String) {
+    Home("/home"),
+    ItemDetail("/item/{id}"),
+    Settings("/settings");
+
+    companion object {
+        fun match(path: String): Deeplink? = entries.firstOrNull { it.matches(path) }
+    }
+
+    private fun matches(candidate: String): Boolean =
+        path.toRegex().matches(candidate) // generated from a stable path template
+}
+```

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

@@ -74,6 +74,24 @@ class UserViewModel @Inject constructor(
 }
 ```
 
+Reduce state with `.update { copy(...) }` (atomic read-modify-write; safe under concurrent emissions) rather than assigning `_uiState.value = ...`.
+
+For a stream-backed screen, expose the state with `.stateIn` and let the first load fire lazily from `onStart` instead of `init {}`. `onStart` runs when the UI actually starts collecting, so a screen that is created but never shown does no work, and the fetch restarts correctly with the subscription.
+
+```kotlin
+private val _uiState = MutableStateFlow(UserUiState())
+
+val uiState: StateFlow<UserUiState> = _uiState
+    .onStart { loadInitialData() }
+    .stateIn(
+        scope = viewModelScope,
+        started = SharingStarted.WhileSubscribed(5_000),
+        initialValue = UserUiState()
+    )
+```
+
+Prefer `WhileSubscribed(5_000)` over `Lazily` or `Eagerly`. The 5-second stop timeout keeps the upstream alive across a configuration change (rotation, night-mode toggle) so the flow is not torn down and re-collected for a transient loss of subscribers, while still cancelling upstream work when the screen truly goes away. `Eagerly`/`Lazily` never stop, so they hold upstream resources for the ViewModel's whole life.
+
 ### 3. Creating the Screen Composable
 
 Consume the state in a "Screen" composable and pass data down to stateless components.
@@ -139,6 +157,50 @@ fun AppNavHost(navController: NavHostController) {
 }
 ```
 
+### Example 2: One-Shot Events (Navigation, Toast, Snackbar)
+
+Keep navigation commands, snackbars and toasts out of the state class. State is a value that survives and is re-read on every recomposition, so an event stored in state fires again after a config change (a duplicated navigation, a re-shown snackbar). Model one-shot events as a `Channel` and expose them as a flow.
+
+```kotlin
+sealed interface UserEvent {
+    data class ShowMessage(val text: String) : UserEvent
+    data class NavigateToProfile(val userId: String) : UserEvent
+}
+
+private val _events = Channel<UserEvent>(Channel.RENDEZVOUS)
+val events: Flow<UserEvent> = _events.receiveAsFlow()
+
+fun onSaved(userId: String) {
+    viewModelScope.launch {
+        _events.send(UserEvent.NavigateToProfile(userId))
+    }
+}
+```
+
+Collect lifecycle-aware so events are only delivered while the screen is at least `STARTED`.
+
+```kotlin
+@Composable
+fun UserScreen(viewModel: UserViewModel = hiltViewModel()) {
+    val lifecycleOwner = LocalLifecycleOwner.current
+    LaunchedEffect(Unit) {
+        lifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
+            viewModel.events.collect { event ->
+                when (event) {
+                    is UserEvent.ShowMessage -> snackbarHostState.showSnackbar(event.text)
+                    is UserEvent.NavigateToProfile -> onNavigateToProfile(event.userId)
+                }
+            }
+        }
+    }
+    // ...
+}
+```
+
+A `Channel` with `RENDEZVOUS` capacity buffers events while there is no active collector and hands each to exactly one consumer, so nothing is lost and nothing is replayed. `SharedFlow(replay = 0)` drops any event emitted while the collector is paused (for example during a config change), which loses one-shot events; that is why the channel is the safer default here.
+
+For the full MVI base-ViewModel pattern (intent reduction, effect plumbing, a reusable base class), see the `android-mvi-viewmodel` skill.
+
 ## Best Practices
 
 - ✅ **Do:** Use `remember` and `derivedStateOf` to minimize unnecessary calculations during recomposition.

package/pipeline/skills/shared/external/android-mvi-viewmodel/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: android-mvi-viewmodel
+description: "A reusable generic BaseViewModel<State, Intent, Event> for MVI Compose apps: StateFlow state, one-shot events over a rendezvous Channel, a single intent dispatch, and a use-case executor with shared loading and error routing. Use when building or reviewing an MVI ViewModel base, intent-to-state reduction, or one-shot navigation and snackbar events."
+risk: safe
+source: multi-agent-pipeline
+date_added: "2026-09-21"
+---
+
+# Android MVI BaseViewModel
+
+A generic `BaseViewModel<State, Intent, Event>` that every screen ViewModel
+extends. It owns the MVI seam: immutable state as a `StateFlow`, one-shot
+effects as events, a single intent entry point, and centralized use-case
+execution with shared loading and error routing. Targets Kotlin 2.0+,
+`kotlinx.coroutines` 1.8+, and Compose from 2024-2025.
+
+Full copy-ready code (the assembled base class, a concrete screen, and the
+lifecycle-aware event collector) lives in
+[references/patterns.md](references/patterns.md). Load that file when you need a
+complete implementation to adapt; each heading there mirrors a section below.
+
+## Contents
+
+- [The three type parameters](#the-three-type-parameters)
+- [State as StateFlow](#state-as-stateflow)
+- [One-shot events over a rendezvous channel](#one-shot-events-over-a-rendezvous-channel)
+- [Single intent entry point](#single-intent-entry-point)
+- [Use-case executor](#use-case-executor)
+- [Reference-counted loading](#reference-counted-loading)
+- [Active job registry](#active-job-registry)
+- [Collecting state and events in Compose](#collecting-state-and-events-in-compose)
+- [Do's and Don'ts](#dos-and-donts)
+- [Related skills](#related-skills)
+
+## The three type parameters
+
+Each screen declares three types and passes an initial state up:
+
+- `State` - an `@Immutable data class`, the complete render model. One per screen.
+- `Intent` - a `sealed interface` of everything the UI can ask for (clicks,
+  text input, retry, refresh).
+- `Event` - a `sealed interface` of one-shot effects the UI consumes exactly
+  once (navigate, show snackbar/toast, dismiss keyboard).
+
+State is what the screen *is*; an event is something that *happens* once and
+must never replay on rotation.
+
+```kotlin
+abstract class BaseViewModel<State, Intent, Event>(
+    initialState: State,
+) : ViewModel() {
+    protected abstract fun handleIntent(intent: Intent)
+}
+```
+
+## State as StateFlow
+
+State lives in a private `MutableStateFlow` exposed read-only. Never expose the
+mutable flow. Update with `.update { copy(...) }` so the read-modify-write is
+atomic under concurrent coroutines - `value = value.copy()` races.
+
+```kotlin
+private val _state = MutableStateFlow(initialState)
+val state: StateFlow<State> = _state.asStateFlow()
+
+protected fun reduce(reducer: State.() -> State) {
+    _state.update { it.reducer() }
+}
+```
+
+Reduction is synchronous and pure: `reduce { copy(query = intent.text) }`. No
+suspension, no I/O, no side effects inside the reducer - those belong in the
+use-case executor.
+
+## One-shot events over a rendezvous channel
+
+Events use a `Channel(Channel.RENDEZVOUS)` exposed as `receiveAsFlow()`, not a
+`SharedFlow(replay = 0)`:
+
+```kotlin
+private val _events = Channel<Event>(Channel.RENDEZVOUS)
+val events: Flow<Event> = _events.receiveAsFlow()
+
+protected fun sendEvent(event: Event) {
+    viewModelScope.launch { _events.send(event) }
+}
+```
+
+Why rendezvous over `MutableSharedFlow(replay = 0)`:
+
+- **No collector, no loss.** `receiveAsFlow` is a cold, single-consumer stream;
+  an event emitted while the screen is in the background suspends the sender
+  until collection resumes. `SharedFlow.tryEmit` with no subscriber silently
+  drops the event - a navigation that never fires.
+- **Delivered once.** A `Channel` fans out to exactly one collector and each
+  element is received a single time. `SharedFlow` is multicast, so two active
+  collectors (e.g. an accidental double-collect) both fire the navigation.
+- **Back-pressure is correct.** `RENDEZVOUS` (zero buffer) hands off directly;
+  the emitter waits for the consumer rather than buffering a queue of stale
+  toasts.
+
+Use this for navigation, snackbar/toast, and dismiss-keyboard - anything that
+must fire once and must not survive a configuration change.
+
+## Single intent entry point
+
+The UI calls exactly one method, `processIntent`. The base logs/guards centrally
+and delegates to the subclass `handleIntent`, which is a single `when` over the
+sealed `Intent` - exhaustive, so a new intent fails to compile until handled.
+
+```kotlin
+fun processIntent(intent: Intent) = handleIntent(intent)
+
+// in a concrete ViewModel
+override fun handleIntent(intent: SearchIntent) = when (intent) {
+    is SearchIntent.QueryChanged -> reduce { copy(query = intent.text) }
+    SearchIntent.Submit -> runSearch()
+    SearchIntent.Retry -> runSearch()
+}
+```
+
+## Use-case executor
+
+A single protected helper wraps every suspending call so error handling is not
+copy-pasted per screen. It uses `runCatching`, then **rethrows
+`CancellationException` before any broad catch** - swallowing it breaks
+structured concurrency and leaves the coroutine "running" after cancellation.
+
+```kotlin
+protected fun <T> execute(
+    showLoading: Boolean = true,
+    onError: ((Throwable) -> Unit)? = null,
+    block: suspend () -> T,
+    onSuccess: (T) -> Unit,
+): Job = viewModelScope.launch {
+    if (showLoading) incrementLoading()
+    try {
+        runCatching { block() }
+            .onSuccess(onSuccess)
+            .onFailure { throwable ->
+                if (throwable is CancellationException) throw throwable
+                (onError ?: ::routeError)(throwable)
+            }
+    } finally {
+        if (showLoading) decrementLoading()
+    }
+}
+```
+
+Error routing has two tiers: a per-call `onError` for screen-specific handling,
+falling back to a global `routeError` that maps the throwable to an `Event`
+(snackbar) or an error field in state. Define `routeError` once in the base or
+override per feature. Because `CancellationException` is rethrown before either
+tier, cancellation never reaches the error UI.
+
+## Reference-counted loading
+
+Overlapping use-cases must share one spinner: if two calls each toggled a
+boolean, the first to finish would hide the indicator while the second still
+runs. Keep an integer count instead - loading is "active" while the count is
+above zero.
+
+```kotlin
+private val loadingCount = MutableStateFlow(0)
+val isLoading: StateFlow<Boolean> =
+    loadingCount
+        .map { it > 0 }
+        .stateIn(viewModelScope, SharingStarted.Eagerly, false)
+
+private fun incrementLoading() = loadingCount.update { it + 1 }
+private fun decrementLoading() = loadingCount.update { (it - 1).coerceAtLeast(0) }
+```
+
+The `execute` helper drives this in its `try/finally`, so the count is balanced
+even when a call throws. Screens observe `isLoading` (or fold it into `State`).
+
+## Active job registry
+
+Track launched jobs by a key so a screen can cancel in-flight work (a new search
+supersedes the previous one) and so everything is torn down in `onCleared`.
+
+```kotlin
+private val jobs = mutableMapOf<String, Job>()
+
+protected fun launchTracked(key: String, block: suspend () -> Unit) {
+    jobs.remove(key)?.cancel()
+    jobs[key] = viewModelScope.launch { block() }
+}
+
+protected fun cancel(key: String) {
+    jobs.remove(key)?.cancel()
+}
+```
+
+Cancelling `viewModelScope` in `onCleared` (automatic) already stops children;
+the registry adds *selective* cancel and de-duplication. Keying a search by
+`"search"` makes each keystroke cancel the prior request for free.
+
+## Collecting state and events in Compose
+
+State is collected lifecycle-aware; events are collected in a
+`LaunchedEffect` that respects lifecycle so a background screen never consumes a
+navigation. Pass **state values and lambdas** to child composables - never the
+ViewModel itself, so children stay stateless, previewable, and testable.
+
+```kotlin
+@Composable
+fun SearchRoute(viewModel: SearchViewModel = hiltViewModel(), onOpenDetail: (Id) -> Unit) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+    val isLoading by viewModel.isLoading.collectAsStateWithLifecycle()
+
+    ObserveEvents(viewModel.events) { event ->
+        when (event) {
+            is SearchEvent.OpenDetail -> onOpenDetail(event.id)
+            is SearchEvent.ShowError -> /* show snackbar */ Unit
+        }
+    }
+
+    SearchScreen(
+        state = state,
+        isLoading = isLoading,
+        onIntent = viewModel::processIntent,
+    )
+}
+```
+
+`ObserveEvents` is a small lifecycle-aware collector (`repeatOnLifecycle`); its
+full body is in [references/patterns.md](references/patterns.md).
+
+## Do's and Don'ts
+
+- **Do** expose only `asStateFlow()` / `receiveAsFlow()`; keep the mutable
+  backing fields private.
+- **Do** update state with `.update { copy(...) }`, never `value = value.copy()`.
+- **Do** rethrow `CancellationException` before any broad `catch` or
+  `onFailure`.
+- **Do** route every suspend call through the executor so loading and errors are
+  centralized.
+- **Don't** put one-shot effects (navigation, toast) in `State` - they replay on
+  rotation.
+- **Don't** use `SharedFlow(replay = 0)` for events; a background screen drops
+  them.
+- **Don't** pass the ViewModel to child composables; pass state + lambdas.
+- **Don't** toggle a boolean for loading when calls overlap; count references.
+
+## Related skills
+
+This skill owns the MVI base-ViewModel seam. For adjacent concerns, defer to:
+
+- **`android-architecture`** - module structure, the api/impl split, and
+  nav-graph aggregation that host these ViewModels.
+- **`kotlin-coroutines-expert`** - dispatcher selection, structured-concurrency
+  and `Flow` operator depth beyond the executor shown here.
+- **`android-datastore`** - persisting the state or preferences a ViewModel
+  reads and writes.