@mrciphersmith/keryx 0.3.3 → 0.3.5

package/src/gdskills/bundled/stacks/kotlin-android/governance/scout.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Use when implementing or extending a feature in a Kotlin/Android app with Jetpack Compose -- composable state hoisting, coroutine scopes (viewModelScope/lifecycleScope), StateFlow exposure from a ViewModel, and recomposition-safe side effects.",
+    "decision": "fork",
+    "topMatch": "kotlin-android/kotlin-android-code-review",
+    "recordedAt": "2026-09-25T15:35:02.929Z",
+    "skillName": "compose-implementation",
+    "justification": "Top match kotlin-android/kotlin-android-code-review is this same pack's read-only review skill (different intent, action verb, workflow), not a real implementation duplicate; no existing implement skill covers Compose state hoisting, coroutine scopes, or StateFlow exposure."
+  },
+  {
+    "query": "Use when a Kotlin/Android module's test suite needs writing, extending, or fixing -- runTest/TestDispatcher for suspend functions and ViewModels, ComposeTestRule semantics-based finders for UI tests, and MockK at the repository/data-source interface boundary.",
+    "decision": "fork",
+    "topMatch": "swift-ios/swift-testing",
+    "recordedAt": "2026-09-25T15:35:03.232Z",
+    "skillName": "kotlin-android-testing",
+    "justification": "Nearest match swift-ios/swift-testing tests Swift/XCTest/Swift Testing code with a different runtime and mocking library entirely; no existing test skill covers Kotlin coroutine test dispatchers, ComposeTestRule, or MockK."
+  },
+  {
+    "query": "Use when reviewing a Kotlin/Android change for coroutine, Compose, and null-safety risks -- GlobalScope usage, side effects fired directly in a composable body, forced-unwrap on external data, mutable state leaked from a ViewModel, and exported manifest components. Read-only, no edits.",
+    "decision": "fork",
+    "topMatch": "kotlin-android/compose-implementation",
+    "recordedAt": "2026-09-25T15:35:03.502Z",
+    "skillName": "kotlin-android-code-review",
+    "justification": "Top match kotlin-android/compose-implementation is this same pack's implementation skill (different intent: write code vs read-only review), not a real review duplicate; no existing review skill covers Kotlin GlobalScope, Compose recomposition, or Android manifest exposure risks."
+  },
+  {
+    "query": "Use when a Gradle Android build, ktlintCheck, detekt, or lint task fails, or a Kotlin compile/type error blocks the build -- resolves Gradle/AGP/Kotlin version mismatches, Compose Compiler mismatches, unresolved dependencies, and lint/detekt findings with the smallest root-cause fix.",
+    "decision": "fork",
+    "topMatch": "csharp-dotnet/dotnet-build-fix",
+    "recordedAt": "2026-09-25T15:35:03.780Z",
+    "skillName": "kotlin-android-build-fix",
+    "justification": "Nearest match csharp-dotnet/dotnet-build-fix fixes dotnet/NuGet/StyleCop errors, not Gradle/AGP/Kotlin/Compose Compiler/detekt findings; each build-fix skill is scoped to its own toolchain's specific failure surface."
+  }
+]

package/src/gdskills/bundled/stacks/kotlin-android/pack.json

@@ -0,0 +1,38 @@
+{
+  "id": "kotlin-android",
+  "family": "framework",
+  "modules": ["kotlin-android-rules", "kotlin-android-skills"],
+  "detectionMarkers": ["android"],
+  "provenance": { "origin": "authored", "sourceRef": "flow 336, Wave 4 batch 4" },
+  "stability": "experimental",
+  "skills": {
+    "implement": ["compose-implementation"],
+    "test": ["kotlin-android-testing"],
+    "review": ["kotlin-android-code-review"],
+    "build-fix": ["kotlin-android-build-fix"],
+    "migrate": []
+  },
+  "agentProfile": {
+    "displayName": "Kotlin/Android",
+    "auditFocus": [
+      "`!!` forced-unwrap on a value from an external source (network response, Intent extra, savedInstanceState) instead of a safe call (`?.`) or explicit null handling",
+      "`GlobalScope.launch`/`GlobalScope.async` inside a ViewModel or composable instead of `viewModelScope`/`lifecycleScope`, losing structured cancellation",
+      "state read or mutated directly inside a composable body instead of via `remember`/`rememberSaveable`/hoisted state, causing recomposition to re-run side effects",
+      "a suspend call, `Toast`, navigation, or analytics event fired directly in a composable body instead of inside `LaunchedEffect`/`DisposableEffect`/a callback",
+      "a ViewModel exposing `MutableStateFlow`/`MutableLiveData` directly to the UI layer instead of a read-only `StateFlow`/`LiveData` view",
+      "secrets or API keys stored in plain `SharedPreferences`, `BuildConfig` fields committed to source, or a manifest component left `exported=\"true\"` with no permission"
+    ],
+    "buildCommands": [
+      "./gradlew assembleDebug",
+      "./gradlew testDebugUnitTest",
+      "./gradlew lint",
+      "./gradlew ktlintCheck || ./gradlew detekt"
+    ],
+    "fixGuardrails": [
+      "never add `!!` or a blanket `@Suppress` annotation to silence a null-safety or lint warning instead of fixing the underlying nullability or logic",
+      "never widen a Gradle/AGP/Kotlin version pin or disable a lint/detekt rule repo-wide just to make one failure disappear without saying so in the report",
+      "never move a `LaunchedEffect`/`DisposableEffect` body directly into the composable function to work around a recomposition bug -- fix the key or hoist the state instead",
+      "never delete or weaken a failing test's assertion to reach a green build; fix the root cause or say the test caught a real bug"
+    ]
+  }
+}

package/src/gdskills/bundled/stacks/kotlin-android/rules/coding-style.mdc

@@ -0,0 +1,89 @@
+---
+extends: common
+paths: ["**/*.kt", "**/*.kts"]
+metadata:
+  origin: authored
+---
+
+# Kotlin/Android coding style
+
+Narrows `core-common-rules`' stack-agnostic style rules to modern
+Kotlin/Android idiom. Applies only to `*.kt`/`*.kts` files — everything
+not Kotlin-specific still comes from the common rules this file `extends`.
+
+## Naming and structure
+
+- `PascalCase` for classes, objects, and composables (a `@Composable`
+  function that emits UI is named as a noun, `UserProfileCard`, not a verb);
+  `camelCase` for functions, properties, and local variables; `SCREAMING_SNAKE_CASE`
+  only for `const val` compile-time constants.
+- A `@Composable` function that returns a value instead of emitting UI
+  (e.g. `rememberX`) still reads as a normal function name, not a noun —
+  reserve the noun-style name for functions that actually emit UI.
+- Keep a file's top-level surface small: one primary class/object per
+  file named after it, with small private helpers colocated rather than
+  scattered into a shared `Utils.kt`.
+- Package names are all lowercase, no underscores, matching the directory
+  layout (`com.example.feature.profile`, not `com.example.Feature.Profile`).
+
+## Data classes vs regular classes
+
+- Use `data class` for a type whose identity is its held values (a DTO, a
+  UI state holder, a value object needing `equals`/`hashCode`/`copy`) —
+  never a `data class` for something with real identity or mutable
+  reference semantics (an Android `Activity`, a repository, a singleton
+  manager).
+- Prefer `copy()` with named parameters to produce a modified instance
+  over building a fresh constructor call by hand; it keeps every unrelated
+  field unchanged and the diff at a call site small when a new field is
+  added later.
+- A `data class` holding UI state should default every field to a sane
+  initial value so `State()` (or `UiState()`) alone is a valid starting
+  point.
+
+## Null-safety idiom
+
+- Prefer a safe call (`?.`) or the Elvis operator (`?:`) over `!!`; a
+  forced-unwrap should be reserved for a value the type system cannot
+  express as non-null but that a prior check (or the language, e.g. inside
+  a `requireNotNull` block) has already proven non-null at that point —
+  never as a shortcut past a compiler nullability warning.
+- Use `let` for a null-checked scope over a nullable receiver
+  (`value?.let { ... }`) when the block needs the unwrapped value once;
+  avoid chaining several `?.let` calls where a single `if (value != null)`
+  smart-cast reads more clearly.
+- Prefer `requireNotNull(x) { "why x must be non-null here" }` over `x!!`
+  at a boundary (constructor, public function entry) — it fails with a
+  message that explains the invariant instead of a bare
+  `NullPointerException`.
+- Model "value or absent" with a nullable type or a sealed result type,
+  not a sentinel value (`-1`, `""`) that callers have to remember to check
+  for.
+
+## Sealed classes/interfaces for state modeling
+
+- Model a UI or domain state with a `sealed interface`/`sealed class`
+  hierarchy (`Loading`, `Success(data)`, `Error(throwable)`) rather than a
+  single class with several nullable fields and a separate `isLoading`
+  boolean — the compiler then forces an exhaustive `when` at every call
+  site, so a new state can't be silently unhandled.
+- Prefer a `sealed interface` over `sealed class` when a variant needs no
+  shared state or behavior; reach for `sealed class` only when the
+  variants share a common property or method implementation.
+- Keep a sealed hierarchy's variants in the same file (or a `sealed`-file
+  group) as the parent — Kotlin does not require this, but scattering
+  variants across files makes the exhaustiveness check hard to audit by
+  reading.
+
+## Extension functions
+
+- Add an extension function to attach behavior to a type this module does
+  not own (or to keep a small, focused helper out of a growing class) —
+  not to route around giving a type a proper method when the type is
+  already yours to edit.
+- Keep an extension's receiver type narrow and its name unambiguous
+  (`String.toDisplayDate()`, not a generic `Any.format()`); an extension
+  with a vague name invites collisions and surprises at the call site.
+- Avoid extension-function sprawl on core types (`String`, `Int`, `List`)
+  for one-off, feature-specific logic — a feature-scoped extension on a
+  feature-scoped type keeps the change's blast radius visible.

package/src/gdskills/bundled/stacks/kotlin-android/rules/patterns.mdc

@@ -0,0 +1,96 @@
+---
+extends: common
+paths: ["**/*.kt", "**/*.kts"]
+metadata:
+  origin: authored
+---
+
+# Kotlin/Android patterns
+
+Narrows `core-common-rules`' stack-agnostic design guidance to idiomatic
+Kotlin coroutines and Jetpack Compose design. Applies only to
+`*.kt`/`*.kts` files.
+
+## Coroutines: structured concurrency
+
+- Launch a coroutine from a scope tied to the lifecycle that owns it —
+  `viewModelScope` inside a `ViewModel`, `lifecycleScope` inside an
+  `Activity`/`Fragment`, or a plain `coroutineScope { }`/`suspend`
+  function for work with no lifecycle owner. Never `GlobalScope.launch`/
+  `GlobalScope.async`: `GlobalScope` is unstructured — nothing cancels it
+  when the screen or the ViewModel goes away, so it outlives the UI it was
+  started for and can update state, navigate, or write to a destroyed
+  view.
+- When a function needs to run several suspend calls concurrently, wrap
+  them in `coroutineScope { }` and use `async`/`await`, not a `launch`
+  fired without an `await` point — `coroutineScope` waits for every child
+  to finish (or cancels the rest if one fails) before returning, so a
+  caller downstream never observes a half-finished fan-out.
+- Cancellation is cooperative: a long-running loop or CPU-bound block
+  inside a coroutine should call `ensureActive()`/check
+  `coroutineContext.isActive`, or use a cancellable suspending call
+  (`delay`, `yield`), so cancelling the parent scope actually stops it
+  instead of running to completion regardless.
+- Switch dispatcher with `withContext(Dispatchers.IO)` around a blocking
+  call (network client without its own suspend API, disk I/O), not by
+  launching a whole new coroutine on that dispatcher — `withContext`
+  keeps the call sequential and propagates cancellation and the result
+  back to the caller.
+
+## Compose: recomposition correctness
+
+- Strong skipping mode is the Compose compiler default since Kotlin 2.0.20:
+  every restartable composable is skippable even with an unstable
+  parameter (a plain `List`/`MutableList`, a mutable var-holding class with
+  no `@Stable`/`@Immutable` annotation) — the compiler compares unstable
+  parameters by instance identity instead of refusing to skip. Prefer
+  stable parameters anyway (a primitive, a `data class` of stable members,
+  an immutable collection) since identity comparison still recomposes on
+  every NEW instance (e.g. a `List` rebuilt each call), where a genuinely
+  stable/immutable type can compare equal and skip.
+- Hoist state to the nearest common ancestor that needs it (a caller, or
+  the owning `ViewModel`) instead of trapping it inside a leaf composable
+  when a sibling or the caller also needs to read or drive it; a leaf
+  composable with no external need for its state can still own it locally
+  via `remember`.
+- Use `remember { ... }` for state that should survive recomposition but
+  not process death or configuration change (a derived value, an
+  `Animatable`, a coroutine-backed helper); use `rememberSaveable { ... }`
+  when the value must survive activity recreation (rotation, process
+  death) — typically UI-only state a `ViewModel` does not already own.
+- Never call a suspend function, fire a one-off event (navigation,
+  `Toast`, analytics), or start a coroutine directly in a composable's
+  body — route it through `LaunchedEffect(key1, ...) { }` (re-runs when a
+  key changes) or `DisposableEffect(key) { onDispose { ... } }` (needs
+  cleanup), never as a bare statement that runs on every recomposition.
+- Under strong skipping mode (default since Kotlin 2.0.20), the compiler
+  auto-memoizes a lambda declared inside a composable by wrapping it in an
+  implicit `remember`, keyed on its captures — a lambda passed inline to a
+  hot list item no longer needs manual hoisting for identity stability in
+  the common case. Reach for `@DontMemoize` only to opt a specific lambda
+  out (e.g. one that must run fresh every recomposition), and still hoist
+  a lambda explicitly when it closes over a value from an outer scope that
+  changes on a schedule the auto-memoization's capture-based keying
+  wouldn't track correctly.
+
+## State exposure from a ViewModel
+
+- Expose state from a `ViewModel` as a read-only `StateFlow`/`SharedFlow`
+  backed by a private mutable holder — `private val _state =
+  MutableStateFlow(...)` with `val state = _state.asStateFlow()` — never
+  the mutable type itself, so only the `ViewModel` can drive state
+  changes and the UI layer can only observe.
+- Prefer `StateFlow` for "current value" UI state (a screen's latest
+  render state, always has a value) and `SharedFlow`/`Channel` for one-off
+  events (a snackbar, a navigation trigger) that should not replay a
+  stale value to a newly-subscribed collector.
+- `LiveData` is legacy for new Compose/coroutine-first code: prefer
+  `StateFlow`/`SharedFlow` exposed from the `ViewModel` and collected with
+  `collectAsStateWithLifecycle()` in Compose. Keep `LiveData` only where a
+  project has already standardized on it or where an unconverted
+  `View`-based screen still consumes it.
+- Collect a `ViewModel`'s flow in Compose with
+  `collectAsStateWithLifecycle()`, not a bare `collectAsState()` — the
+  lifecycle-aware variant stops collecting while the screen is stopped
+  instead of continuing to observe (and potentially update state) behind
+  a backgrounded UI.

package/src/gdskills/bundled/stacks/kotlin-android/rules/security.mdc

@@ -0,0 +1,90 @@
+---
+extends: common
+paths: ["**/*.kt", "**/*.kts"]
+metadata:
+  origin: authored
+---
+
+# Kotlin/Android security
+
+Narrows `core-common-rules`' stack-agnostic security rules to Android-
+specific, OWASP Mobile-relevant risks. Applies only to `*.kt`/`*.kts`
+files.
+
+## Secrets and credential storage
+
+- Never store a credential, auth token, or API secret in plain
+  `SharedPreferences` — plain `SharedPreferences` is an unencrypted XML
+  file readable on a rooted device or via backup extraction. Prefer the
+  Android Keystore directly (generate/store the key in the Keystore, use
+  it to encrypt the value yourself) over `EncryptedSharedPreferences`
+  (Jetpack `androidx.security:security-crypto`) for new code — that
+  library has known, unresolved reliability issues (a corrupted-keyset
+  failure mode with no clean recovery path) and Google's own guidance has
+  moved toward not recommending it for new applications; verify the
+  library's current status in the Android docs before reaching for it in
+  an existing codebase that already depends on it.
+- Never hard-code an API key, client secret, or signing credential as a
+  Kotlin string literal or a `BuildConfig` field, whether the value is
+  committed or injected at build time from a local, untracked properties
+  file (`local.properties`) or a CI secret — either way, a `BuildConfig`
+  field is compiled into the APK exactly like a string literal and is
+  just as recoverable by decompiling it. Keeping the value out of source
+  control (via `local.properties`/a CI secret) only stops it leaking
+  through the repository; it does not keep it off the device. For a
+  value that must actually stay off the device, fetch it from a backend
+  at runtime instead of baking it into the build at all.
+- Generate and store cryptographic keys through `AndroidKeyStore`
+  (`KeyGenParameterSpec`) rather than deriving or hard-coding a key in
+  application code — the Keystore keeps key material out of the app's
+  own process memory and out of extractable storage.
+
+## Manifest and component exposure
+
+- Every `<activity>`, `<service>`, `<receiver>`, and `<provider>` in
+  `AndroidManifest.xml` that does not need to be reachable from other
+  apps should have `android:exported="false"` (or no `exported`
+  attribute with no intent-filter, matching the modern default); a
+  component left `exported="true"` with no permission check is callable
+  by any app on the device, including one crafted to pass malformed
+  input.
+- An exported component that must stay exported (a deep-link entry point,
+  a share target) validates every piece of the incoming `Intent` before
+  acting on it — never trusts an extra, a URI path segment, or a
+  `ContentProvider` query purely because the intent-filter matched.
+- Guard a `ContentProvider` and any exported component with a
+  signature-level custom permission when the caller is meant to be your
+  own other app, not "any app that asks."
+
+## Secure intent and deep-link handling
+
+- Treat every value pulled from an incoming `Intent` (extras, deep-link
+  URI segments/query params, a `ClipData` from a share) as untrusted
+  input — validate its shape and range before using it to navigate, query
+  a database, or construct a file path; do not assume it matches what
+  your own app would have sent.
+- Prefer an explicit `Intent` (naming the target component) for
+  inter-component communication within your own app; use an implicit
+  `Intent` only when you genuinely need another app to handle it, and
+  set the package (`setPackage`) when you only want your own app to
+  respond, to avoid intent interception by another installed app.
+- Validate a deep-link's scheme/host/path against an allowlist before
+  using any part of it to load content or trigger an action —
+  `App Links`/verified `https` deep links reduce but do not eliminate
+  this: a query parameter or path segment can still carry attacker-
+  controlled data even through a verified link.
+
+## Data and transport
+
+- Use `HttpsURLConnection`/an HTTP client configured to require TLS for
+  every network call carrying credentials or personal data; do not add a
+  custom `TrustManager`/`HostnameVerifier` that accepts all certificates
+  outside of a short-lived local debug build, and never ship one that
+  way.
+- Mark a view/field that must not appear in screenshots or the recent-
+  apps app-switcher preview (a PIN entry, payment details) with
+  `FLAG_SECURE` on the window, rather than relying on the OS default.
+- Avoid logging PII, tokens, or full request/response bodies with
+  `Log.d`/`Log.i` in release builds — strip or gate verbose logging
+  behind a debug-only build flag so production logs (which can be pulled
+  from a device or bug report) do not leak sensitive data.

package/src/gdskills/bundled/stacks/kotlin-android/rules/testing.mdc

@@ -0,0 +1,89 @@
+---
+extends: common
+paths: ["**/*.kt", "**/*.kts"]
+metadata:
+  origin: authored
+---
+
+# Kotlin/Android testing
+
+Narrows `core-common-rules`' stack-agnostic testing rules to Kotlin
+coroutine testing, Compose UI testing, and idiomatic mocking on Android.
+Applies only to `*.kt`/`*.kts` files.
+
+## Coroutine test dispatchers
+
+- Test a `suspend` function or a `ViewModel`'s coroutine-driven behavior
+  with `kotlinx-coroutines-test`'s `runTest { }`, not a real `delay` or a
+  blocking sleep — `runTest` runs on a `TestScope` whose virtual clock
+  skips real delay time, so a function that internally waits still runs
+  the test instantly.
+- Inject a `TestDispatcher` (`StandardTestDispatcher`/
+  `UnconfinedTestDispatcher`) in place of `Dispatchers.Main`/
+  `Dispatchers.IO` for the code under test rather than letting it resolve
+  the real platform dispatcher — set `Dispatchers.setMain(testDispatcher)`
+  in a `@Before` and `Dispatchers.resetMain()` in an `@After` (or a JUnit
+  rule that wraps this) so `viewModelScope`/`Dispatchers.Main` resolves to
+  the test dispatcher instead of throwing or running on a background
+  thread the test cannot observe.
+- Prefer `StandardTestDispatcher` (queues work, you advance it explicitly
+  with `advanceUntilIdle()`/`runCurrent()`) when a test needs to assert an
+  intermediate state (e.g. a loading state before a result arrives); use
+  `UnconfinedTestDispatcher` when the test only cares about the end state
+  and wants dispatched work to run eagerly.
+- Never synchronize a coroutine test with `Thread.sleep`/a fixed `delay`
+  in the test body waiting for background work to finish — that is
+  exactly what `runTest`'s virtual time and `advanceUntilIdle()` replace.
+
+## Compose UI testing
+
+- Drive Compose UI assertions through a `ComposeTestRule`
+  (`createComposeRule()` for a standalone composable, or
+  `createAndroidComposeRule<Activity>()` when the test needs a hosting
+  Activity) — never reach into the underlying `View` tree.
+- Find nodes with semantics-based finders
+  (`onNodeWithText`, `onNodeWithContentDescription`,
+  `onNodeWithTag(testTag)`) rather than a fragile structural/index-based
+  query; add an explicit `Modifier.testTag("...")` to a composable that
+  has no stable text/content-description to key off.
+- Call `composeTestRule.waitUntil { ... }` (or
+  `composeTestRule.awaitIdle()`/`mainClock.advanceTimeUntil { }` under
+  manual clock control) to wait for an async UI update instead of a
+  fixed-duration sleep in the test.
+- Assert both structure and behavior: a node's presence/text via a
+  semantics finder, and an interaction's effect (`performClick()` then
+  assert the resulting state/text), not just that a composable rendered
+  without throwing.
+
+## Mocking at the interface boundary
+
+- Mock a `Repository`/`ApiService`/`DataSource` interface (or another
+  clearly-owned collaborator boundary) that the class under test depends
+  on — never reach inside the class under test to stub its own private
+  methods or fields; a test that mocks internals stops testing real
+  behavior and breaks on any internal refactor.
+- Prefer MockK for Kotlin code under test — it understands Kotlin
+  constructs Mockito's Java-first API handles awkwardly (`final` classes
+  by default, coroutines via `coEvery`/`coVerify`, extension functions,
+  object mocks via `mockkObject`) — unless a project has already
+  standardized on Mockito with `mockito-kotlin`; match what the project
+  already uses rather than introducing a second mocking library.
+- Use `coEvery { repo.fetch() } returns result` /
+  `coVerify { repo.fetch() }` (MockK's coroutine-aware variants) for a
+  suspend function on a mock, not the plain `every`/`verify` forms, which
+  do not handle a `suspend` member correctly.
+- Fake network/database responses at the repository or data-source
+  interface (a fake or mocked implementation returning canned data), not
+  by hitting a real network or an on-device database from a unit test —
+  reserve a real backing store for an instrumented/integration test.
+
+## Layout and lifecycle
+
+- Unit tests for a `ViewModel`/plain Kotlin class live under
+  `src/test/`; instrumented tests needing an Android context or a real
+  device/emulator (Compose UI tests, `Instrumentation`-backed tests) live
+  under `src/androidTest/` — match whichever the project's existing
+  layout uses, do not invent a third location.
+- Use JUnit rules (`MainDispatcherRule` for coroutines,
+  `createComposeRule()` for Compose) to keep dispatcher/UI setup and
+  teardown out of every individual test method.

package/src/gdskills/bundled/stacks/kotlin-android/skills/compose-implementation/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: compose-implementation
+description: "Use when implementing or extending a feature in a Kotlin/Android app with Jetpack Compose -- composable state hoisting, coroutine scopes (viewModelScope/lifecycleScope), StateFlow exposure from a ViewModel, and recomposition-safe side effects."
+triggers:
+  - "add this screen to our Android app with Compose"
+  - "hook up this ViewModel to the new composable"
+  - "wire a network call into this Android feature"
+  - "build a form screen with validation for the app"
+  - "expose loading/error state from the ViewModel to the UI"
+  - "add a button that launches a coroutine to save data"
+  - "implement this ticket in the mobile app's feature module"
+metadata:
+  origin: authored
+  category: implement
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Kotlin/Android (Jetpack Compose) implementation
+
+Implement or extend a feature in a Kotlin/Android codebase built on
+Jetpack Compose: composable structure, state hoisting, coroutine scope
+choice, and state exposure from a `ViewModel`. Scoped to Kotlin/Android
+specifically — `rules/coding-style.mdc`, `rules/patterns.mdc`, and
+`rules/security.mdc` carry the full stack-specific rule set this skill
+draws its checklist from; read them before writing code, not just this
+summary.
+
+## Workflow
+
+### Step 1: Discover the project's own conventions
+
+1. Read the module's `build.gradle(.kts)` for the Kotlin/AGP/Compose
+   Compiler versions and which architecture libraries are already
+   dependencies (`androidx.lifecycle:lifecycle-viewmodel-compose`,
+   `kotlinx-coroutines-android`, Hilt/Koin/Dagger, Compose Navigation).
+2. Find the existing layout: is this a single-module app or a
+   feature-module setup (`:feature:profile`, `:core:ui`)? Match it; do
+   not invent a different module boundary for one change.
+3. Read 1-2 neighboring screens/`ViewModel`s in the feature you are
+   touching for: state-holder naming (`UiState`, `ViewState`), whether
+   state is exposed as `StateFlow` or still `LiveData`, the DI pattern in
+   use, and whether a design-system component set already exists to
+   reuse instead of building raw `Text`/`Button` composables.
+
+### Step 2: Design before writing
+
+- Decide, per new piece of state: does it belong in the `ViewModel`
+  (survives configuration change, drives business logic) or hoisted only
+  as far as the nearest composable ancestor that needs it (purely
+  presentational, e.g. whether a dropdown is expanded)? Do not default
+  everything into the `ViewModel` when a leaf composable's own `remember`
+  is enough, and do not trap logic-relevant state in a composable when a
+  sibling or rotation needs it to survive.
+- Model the screen's state as a `sealed interface`/`data class` (a single
+  `UiState` with a `sealed` status field, or a small sealed hierarchy for
+  distinct screens like `Loading`/`Content`/`Error`) rather than several
+  independent nullable/boolean fields the UI has to reconcile by hand.
+- Decide the coroutine scope for any new asynchronous work before writing
+  it: `viewModelScope` for anything driven from a `ViewModel`,
+  `lifecycleScope`/`rememberCoroutineScope()` only for UI-only work with
+  no `ViewModel` involved (an animation trigger, a one-off scroll). Never
+  `GlobalScope`.
+- Trace where any new side effect (navigation, a snackbar/analytics
+  event, a suspend call) needs to run from — inside a composable body it
+  belongs in `LaunchedEffect`/`DisposableEffect`, never as a bare
+  statement.
+
+### Step 3: Implement
+
+1. Expose new `ViewModel` state as `private val _state =
+   MutableStateFlow(...)` / `val state = _state.asStateFlow()`; collect
+   it in Compose with `collectAsStateWithLifecycle()`.
+2. Keep composable parameters stable (primitives, `data class`es of
+   stable members, immutable collections) — strong skipping mode (default
+   since Kotlin 2.0.20) lets the compiler skip even an unstable parameter
+   via instance-identity comparison, but only a genuinely stable/immutable
+   type can compare EQUAL across calls and actually skip when nothing
+   changed; an unstable type rebuilt fresh each call still recomposes.
+3. Hoist state per `rules/patterns.mdc`; use `remember`/`rememberSaveable`
+   for composable-local state, never a `var` mutated directly inside the
+   composable body outside of a `remember` holder.
+4. Route any new side effect through `LaunchedEffect(key1, ...) { }` (with
+   the correct key so it re-runs exactly when it should) or
+   `DisposableEffect(key) { onDispose { ... } }` when cleanup is needed.
+5. Launch new coroutine work in `viewModelScope`/`lifecycleScope` as
+   decided in Step 2; wrap concurrent suspend calls in `coroutineScope { }`
+   with `async`/`await` rather than firing untracked `launch` calls.
+6. Avoid `!!`; use `?.`/`?:`/`requireNotNull(x) { "..." }` for any value
+   that can be null (a nullable response field, an `Intent` extra, a
+   `savedStateHandle` lookup).
+
+### Step 4: Verify
+
+```bash
+./gradlew assembleDebug
+./gradlew testDebugUnitTest
+./gradlew lint
+```
+
+Run `./gradlew ktlintCheck` or `./gradlew detekt` if the project has one
+configured. Fix findings at the root cause per `rules/security.mdc` and
+`rules/coding-style.mdc`; a build/test/lint failure here is a signal to
+fix the implementation, not to reach for `kotlin-android-build-fix`'s
+scope unless the failure is purely a build/dependency/toolchain problem
+unrelated to the feature logic.
+
+### Step 5: Report
+
+```
+Implemented: feature/profile/ProfileViewModel.kt, feature/profile/ProfileScreen.kt
+  - New ProfileUiState sealed hierarchy (Loading/Content/Error)
+  - State exposed as StateFlow, collected with collectAsStateWithLifecycle()
+  - Save action launched in viewModelScope
+  - ./gradlew assembleDebug/testDebugUnitTest/lint all pass
+```
+
+## Rules
+
+- Never launch a coroutine with `GlobalScope` — use `viewModelScope`,
+  `lifecycleScope`, or a scope passed in by the caller.
+- Never call a suspend function or fire a one-off UI event directly in a
+  composable's body — use `LaunchedEffect`/`DisposableEffect`.
+- Never expose a mutable `MutableStateFlow`/`MutableLiveData` from a
+  `ViewModel`'s public surface — expose the read-only view.
+- Never use `!!` to route around a null-safety warning; use a safe call,
+  Elvis operator, or `requireNotNull` with a message.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll just launch this in GlobalScope, it's a quick one-off network call" | Nothing cancels a GlobalScope coroutine when the screen/ViewModel is destroyed; it can still update state or navigate on a gone screen |
+| "I'll call this suspend function right in the composable body, it only runs once" | A composable body can re-run on every recomposition; an uncontrolled suspend call outside LaunchedEffect can fire far more than once, or not track the right restart key |
+| "I'll add `!!` here since this value is always set by the time we get here" | "Always" is an assumption the compiler cannot verify; a safe call or `requireNotNull` with a message documents and enforces the same assumption instead of crashing silently when it's wrong |
+| "I'll just expose the MutableStateFlow directly, it saves a line" | Lets any collector outside the ViewModel push a new value, breaking the single-writer invariant the pattern exists to guarantee |
+
+## Verification
+
+Do not report the work done until all of the following hold:
+
+- `./gradlew assembleDebug`, `./gradlew testDebugUnitTest`, and
+  `./gradlew lint` all exit 0.
+- Every new coroutine launch uses `viewModelScope`/`lifecycleScope`/a
+  passed-in scope, never `GlobalScope`.
+- Every new side effect inside a composable body runs through
+  `LaunchedEffect`/`DisposableEffect`, not as a bare statement.
+- Every new/touched `ViewModel`-exposed state is read-only from the UI's
+  perspective (`StateFlow`/`SharedFlow`, not the mutable type).