@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/kotlin-patterns/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: kotlin-patterns
+description: Idiomatic Kotlin for JVM and Android code, covering null safety without !!, data and sealed classes with exhaustive when, restrained extension functions, structured concurrency with coroutine scopes and dispatchers, cold Flow versus StateFlow and SharedFlow, Result and exception handling, and Gradle Kotlin DSL build scripts with version catalogs. Use when writing or restructuring Kotlin code, modelling state with sealed hierarchies, choosing a coroutine scope or dispatcher, exposing data as a Flow, or editing build.gradle.kts files.
+license: MIT
+compatibility: Any Agent Skills host. Needs the project's Gradle wrapper (or Maven) and a JDK to build and test.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Kotlin patterns
+
+Write Kotlin that the compiler can check: nullability in the types, states in sealed hierarchies, concurrency tied to a scope. Follow the project's existing style first; these rules settle what it does not.
+
+## 0. Before you write
+
+1. Find the Kotlin version, JVM target and build tool: search `gradle/libs.versions.toml`, `build.gradle.kts` and `settings.gradle.kts`. Do not use language or library features newer than that version.
+2. Check whether the code is Android (an `com.android.*` plugin is applied) or plain JVM. Android code must never block the main thread.
+3. Find the existing conventions: error type (exceptions, `Result`, a sealed `Outcome`), DI framework, coroutine scopes in use, and the lint/format tool (ktlint, detekt, Spotless). Match them.
+
+## 1. Null safety
+
+- Model absence in the type (`String?`) only when absence is a real state. Otherwise make it non-null and validate at the boundary.
+- Never use `!!` in new code. Replace it with, in order of preference:
+  1. a non-null type, so the question never arises;
+  2. `?: return`, `?: continue` or `?: throw IllegalStateException("why")` with a message;
+  3. `requireNotNull(x) { "message" }` for arguments, `checkNotNull(x) { "message" }` for state.
+- Use `?.let { }` for a short side effect, not as a general `if`. Two nested `?.let` blocks mean an early return reads better.
+- `lateinit var` only for values a framework sets before first use (DI fields, test setup). Never for values that can legitimately be missing.
+- Java interop: values from unannotated Java APIs are platform types (`String!`). Give them an explicit Kotlin type at the call site (`val name: String? = javaObj.name`) so a null fails where it enters, not three calls later. For strict JSR-305 annotations, the compiler flag is `-Xjsr305=strict`.
+
+## 2. Data, value and sealed types
+
+- `data class` for value holders with structural equality. Keep properties `val`; use `copy()` to change them. Do not put mutable collections in them.
+- `@JvmInline value class` to give a primitive a meaning (`UserId(val raw: String)`) without allocation.
+- `sealed interface` (or `sealed class` when subtypes share state) for closed sets of states or results:
+
+```kotlin
+sealed interface LoadState<out T> {
+    data object Loading : LoadState<Nothing>
+    data class Loaded<T>(val value: T) : LoadState<T>
+    data class Failed(val cause: Throwable) : LoadState<Nothing>
+}
+
+fun render(state: LoadState<User>) = when (state) {
+    LoadState.Loading -> showSpinner()
+    is LoadState.Loaded -> show(state.value)
+    is LoadState.Failed -> showError(state.cause)
+}
+```
+
+- `data object` needs Kotlin 1.9 or later; on older versions use a plain `object`.
+- Use `when` as an expression over a sealed type with no `else` branch, so adding a subtype is a compile error at every call site.
+- `enum class` when the cases carry no per-instance data.
+
+## 3. Functions and extensions
+
+- Prefer expression bodies for one-expression functions, named and default arguments over overloads, and `val` over `var`.
+- Write an extension function only when it reads as a natural operation on that type and is used in more than one place. Keep it `private` or `internal` unless it is part of a public API. Never add extensions on `Any`, `String` or other broad types for one call site.
+- Scope functions: `apply` to configure an object, `also` for a side effect, `let` for a nullable or a transform, `run`/`with` sparingly. Do not nest them.
+- Collections: return read-only `List`/`Map` types; keep `MutableList` private. Use `Sequence` only for long pipelines over large inputs.
+
+## 4. Coroutines and structured concurrency
+
+Rules that prevent leaks and freezes:
+
+1. Every coroutine has an owner scope with a lifecycle: `viewModelScope`, `lifecycleScope`, a scope injected into a class that cancels it on shutdown, or `coroutineScope { }` inside a suspend function.
+2. Never use `GlobalScope` in production code. Never create `CoroutineScope(Job())` in a class without a matching `cancel()`.
+3. Suspend functions are main-safe: the function that blocks switches dispatcher itself with `withContext(Dispatchers.IO)` (blocking I/O) or `withContext(Dispatchers.Default)` (CPU work). Callers never have to know.
+4. Inject dispatchers (constructor parameter with a default) so tests can replace them.
+5. Never call `runBlocking` on the main thread or inside a coroutine. It is for `main()` and bridging blocking APIs at the edge.
+6. Never swallow `CancellationException`. If you catch `Exception` or `Throwable` in suspend code, rethrow cancellation:
+
+```kotlin
+try { repo.sync() }
+catch (e: CancellationException) { throw e }
+catch (e: IOException) { log.warn("sync failed", e) }
+```
+
+7. Use `coroutineScope` when one child failing should cancel siblings, and `supervisorScope` when children are independent. Parallel work: `coroutineScope { val a = async { f() }; val b = async { g() }; a.await() to b.await() }`.
+8. Long loops must be cancellable: call `ensureActive()` or a suspending function each iteration.
+
+## 5. Flow
+
+- A `Flow` is cold: it runs once per collector. Expose `Flow` from repositories, `StateFlow` for UI state, `SharedFlow` for events.
+- Keep mutable flows private: `private val _state = MutableStateFlow(UiState())` and `val state: StateFlow<UiState> = _state.asStateFlow()`. Update with `_state.update { it.copy(...) }`, never read-modify-write.
+- Convert cold to hot with `stateIn(scope, SharingStarted.WhileSubscribed(5_000), initial)` so the upstream stops when nobody listens.
+- Move upstream work off the main thread with `flowOn(Dispatchers.IO)`. Never call `emit` from inside `withContext` or `launch` within `flow { }`: it throws `IllegalStateException` (Flow invariant is violated). Use `flowOn`, or `channelFlow` when you need concurrent emitters. A `withContext` that returns a value you then emit outside it is fine.
+- Collect on Android with `repeatOnLifecycle(Lifecycle.State.STARTED)` (or `collectAsStateWithLifecycle()` in Compose) so collection stops in the background.
+- `collect` suspends until the flow ends. Two `collect` calls in a row in one coroutine means the second never runs for an infinite flow: launch each in its own coroutine.
+- Pick the operator on purpose: `map`, `filter`, `combine`, `flatMapLatest` (cancel previous), `debounce`, `distinctUntilChanged`. Handle errors with `catch { }` upstream of `collect`.
+
+## 6. Error handling
+
+- Exceptions for programming errors and truly unexpected failures; `require`/`check`/`error()` for preconditions.
+- For expected domain failures, return a sealed result type the caller must handle. Use the project's existing type if there is one.
+- `runCatching` also catches `CancellationException`; do not use it around suspend calls unless you rethrow cancellation.
+- Never catch and ignore. Log with context or convert to a domain error.
+
+## 7. Gradle Kotlin DSL
+
+- Keep versions in `gradle/libs.versions.toml` and reference them as `libs.foo`, `alias(libs.plugins.foo)`. Do not hard-code versions in module scripts.
+- Set the JDK with `kotlin { jvmToolchain(17) }` (use the project's version) rather than `sourceCompatibility` alone.
+- Compiler options go in `kotlin { compilerOptions { ... } }`, for example `freeCompilerArgs.add("-Xjsr305=strict")` or `allWarningsAsErrors.set(true)`.
+- Shared build logic goes in convention plugins (`build-logic/` or `buildSrc/`), not copy-pasted blocks.
+- Prefer KSP (`com.google.devtools.ksp`, `ksp(...)`) over kapt for processors that support it.
+- Keep the Kotlin Gradle plugin, KSP, Compose compiler and Android Gradle Plugin versions compatible; check the official compatibility tables before bumping one.
+- Run builds through the wrapper: `./gradlew build`.
+
+## 8. Check your work
+
+1. Build and test: `./gradlew build` (or the module task, e.g. `./gradlew :app:testDebugUnitTest`).
+2. Run the project's linter if configured (`./gradlew ktlintCheck`, `./gradlew detekt`, `./gradlew spotlessCheck`).
+3. Search your diff for `!!`, `GlobalScope`, `runBlocking` and `catch (e: Exception)` and justify or remove each.
+
+## Stop and ask the user
+
+- Before changing a public API signature other modules or apps call.
+- Before bumping the Kotlin, AGP or Gradle version to use a feature.
+- When the project mixes error styles and you would have to pick one for a new module.
+
+## Report back
+
+List the files changed, the build and lint commands you ran with their result, and any `!!`, `runBlocking` or broad catch you kept, with the reason.
+
+For tests, use the `kotlin-testing` skill. For a review of existing changes, the `kotlin-reviewer` agent. For compile or Gradle failures, the `kotlin-build-resolver` agent.

package/skills/kotlin-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Model the checkout screen state in Kotlin as a sealed interface with loading, success and error cases",
+    "This Kotlin repository class has !! everywhere, rewrite it with proper null safety",
+    "Which dispatcher should my suspend function use for the database call, and who should own the coroutine scope?",
+    "Expose the user list from my Android ViewModel as a StateFlow instead of LiveData",
+    "Move our hard-coded dependency versions in build.gradle.kts into a libs.versions.toml catalog"
+  ],
+  "should_not_trigger": [
+    "Add a test that checks my Kotlin repository retries twice before failing",
+    "Go through the Kotlin PR my teammate opened and flag any risky coroutine code",
+    "The Android build broke with a Duplicate class error after adding a library",
+    "Build the settings screen in Jetpack Compose with a lazy list",
+    "Share the networking layer between Android and iOS with Kotlin Multiplatform"
+  ]
+}

package/skills/kotlin-testing/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: kotlin-testing
+description: Writes and repairs Kotlin tests on JUnit 5 or Kotest, with MockK for coroutine-aware mocks, kotlinx-coroutines-test for runTest, virtual time and Dispatchers.setMain, and Turbine for asserting Flow and StateFlow emissions, plus a checklist for making flaky coroutine tests deterministic. Use when adding unit tests to Kotlin or Android code, testing suspend functions or ViewModels, asserting what a Flow emits, mocking with every and coEvery, or a Kotlin test passes locally but fails or hangs intermittently in CI.
+license: MIT
+compatibility: Any Agent Skills host. Needs a JDK and the project's Gradle wrapper (or Maven) to run tests.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# Kotlin testing
+
+Tests that run in milliseconds, never touch real time or the network, and fail for one reason.
+
+## 0. Find the setup
+
+1. Search the build files for the framework already in use: `junit-jupiter` (JUnit 5), `kotest-runner-junit5` (Kotest), `junit:junit` (JUnit 4, common in Android). Use what is there. Do not add a second framework.
+2. Check for `mockk`, `kotlinx-coroutines-test` and `app.cash.turbine:turbine`. If a test needs one that is missing, stop and ask the user before adding it, then add it as a `testImplementation` dependency (through `gradle/libs.versions.toml` if the project uses a version catalog).
+3. JUnit 5 on Gradle needs `tasks.test { useJUnitPlatform() }` (Kotest runs on the same platform). If tests are silently not running, check this first.
+4. Find the test command: `./gradlew test`, or for Android `./gradlew :module:testDebugUnitTest`. Run one class with `--tests "com.example.FooTest"`.
+
+## 1. Test shape
+
+- One behaviour per test. Name it for the behaviour: JUnit 5 backtick names (`` fun `returns cached user when offline`() ``) or Kotest `test("...")`.
+- Arrange, act, assert, with a blank line between. Build inputs with small factory functions with defaults, not shared mutable fixtures.
+- Assert on values, not on calls, wherever you can. Use `assertEquals` (kotlin.test or JUnit) or Kotest matchers (`shouldBe`, `shouldThrow<T> { }`).
+- Prefer a hand-written fake (an in-memory implementation of the interface) over a mock for repositories and data sources. Mock only what you cannot fake cheaply.
+
+## 2. MockK
+
+```kotlin
+val api = mockk<UserApi>()
+coEvery { api.fetch("42") } returns User("42", "Ama")   // suspend function
+every { clock.now() } returns Instant.parse("2026-01-01T00:00:00Z")
+
+// act ...
+
+coVerify(exactly = 1) { api.fetch("42") }
+confirmVerified(api)
+```
+
+- `every`/`verify` for regular functions, `coEvery`/`coVerify` for suspend functions. Mixing them up is the most common MockK error.
+- Use strict mocks by default; `mockk(relaxed = true)` hides missing stubs. Use `relaxUnitFun = true` when you only want `Unit` functions relaxed.
+- Capture arguments with `val slot = slot<Request>()` and `coEvery { api.send(capture(slot)) }`.
+- `mockkObject`, `mockkStatic` and `mockkConstructor` change global state: call `unmockkAll()` in teardown, or avoid them by injecting the dependency.
+- Never mock the class under test or data classes.
+
+## 3. Coroutines: runTest
+
+```kotlin
+@Test
+fun `loads user`() = runTest {
+    val repo = UserRepository(api, ioDispatcher = StandardTestDispatcher(testScheduler))
+    val user = repo.load("42")
+    assertEquals("Ama", user.name)
+}
+```
+
+- Wrap every test that calls suspend code in `runTest`. It skips `delay` with virtual time, so a 30-second timeout test finishes instantly.
+- Inject dispatchers into production code. In tests, pass a `StandardTestDispatcher(testScheduler)` (or `UnconfinedTestDispatcher(testScheduler)` when you want eager execution) so all coroutines share one scheduler. A hard-coded `Dispatchers.IO` escapes virtual time and makes tests flaky.
+- Code that uses `Dispatchers.Main` (ViewModels): call `Dispatchers.setMain(testDispatcher)` before each test and `Dispatchers.resetMain()` after. Put it in a JUnit 5 extension or a JUnit 4 rule the project can reuse.
+- Control time with `advanceUntilIdle()`, `advanceTimeBy(ms)` and `runCurrent()`. Read virtual time with `currentTime`.
+- Launch long-running collectors in `backgroundScope` so `runTest` cancels them at the end instead of waiting for them until its timeout fails the test.
+- Never use `runBlocking` or `Thread.sleep` in tests of coroutine code.
+
+## 4. Flow: Turbine
+
+```kotlin
+@Test
+fun `emits loading then loaded`() = runTest {
+    viewModel.state.test {
+        assertEquals(UiState.Loading, awaitItem())
+        assertEquals(UiState.Loaded(user), awaitItem())
+        cancelAndIgnoreRemainingEvents()
+    }
+}
+```
+
+- `test { }` fails if events are left unconsumed. Finish with `awaitComplete()`, `awaitError()` or `cancelAndIgnoreRemainingEvents()`.
+- `StateFlow` conflates and replays its current value: the first `awaitItem()` is the current state, and fast successive updates can merge. Assert the final state with `expectMostRecentItem()` when intermediate states do not matter.
+- Several flows at once: `turbineScope { val a = flowA.testIn(backgroundScope); ... }`, and end each with `cancel()`, `awaitComplete()` or `awaitError()`.
+- Turbine's wait timeout is wall-clock (default 3 seconds), not virtual time. A timeout usually means the code under test never emitted because its dispatcher was not advanced.
+- Without Turbine, collect a finite flow with `flow.toList()` or `flow.take(n).toList()`.
+
+## 5. Kotest specifics
+
+- Pick one spec style per project (`FunSpec`, `StringSpec`, `BehaviorSpec`) and match it.
+- Kotest test bodies are already suspend functions; you can call suspend code directly. Use `runTest` only when you need virtual time, or the project's coroutine test extension.
+- Use `beforeTest`/`afterTest` for setup and `isolationMode` deliberately: the default shares one spec instance across tests.
+
+## 6. Fixing flaky tests
+
+Work through this list in order, and run the test 20 times after each change (`./gradlew test --tests "X" --rerun-tasks` in a loop, or a repeated-test annotation) to prove it:
+
+1. Real dispatcher in production code (`Dispatchers.IO`/`Default` hard-coded): inject it and pass the test dispatcher.
+2. Multiple `TestCoroutineScheduler`s: every test dispatcher must share `testScheduler`.
+3. Missing `Dispatchers.setMain` or a missing `resetMain` leaking between tests.
+4. Real time: `System.currentTimeMillis()`, `Instant.now()`, `Thread.sleep`. Inject a clock.
+5. Shared state: companion objects, singletons, `mockkObject` without `unmockkAll`, test order dependence.
+6. StateFlow conflation making an intermediate `awaitItem()` miss a value.
+7. Real network, filesystem or database. Replace with a fake or a temp directory.
+
+Never "fix" a flaky test by adding `delay`, retries or a longer timeout.
+
+## Rules
+
+- Never delete, `@Disabled` or weaken an existing test to make the suite pass without the user's agreement.
+- No real network calls, no real clock, no sleeps.
+- Run the single test, then the whole module's tests, before you finish.
+
+## Report back
+
+Tests added or fixed (class and test names), the exact command you ran, the pass/fail counts, and for a flaky test the root cause from section 6 and how many repeated runs passed.
+
+For writing the production code itself, use the `kotlin-patterns` skill. For a test-first loop in any language, `tdd-workflow`.

package/skills/kotlin-testing/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Write unit tests for my Kotlin ViewModel using runTest and Turbine",
+    "How do I mock a suspend function with MockK? coEvery doesn't seem to work",
+    "My Kotest spec hangs forever when the repository uses delay()",
+    "This coroutine test passes on my laptop but fails randomly in CI, help me make it deterministic",
+    "Assert that my StateFlow emits Loading and then Success in a JUnit 5 test"
+  ],
+  "should_not_trigger": [
+    "Rewrite this Kotlin service to use structured concurrency instead of GlobalScope",
+    "Review my Kotlin diff for Flow collection bugs and !! usage",
+    "kaptDebugKotlin fails after adding Room, fix the build",
+    "Write pytest fixtures for my FastAPI endpoints",
+    "Write a Playwright end-to-end test for the login page"
+  ]
+}

package/skills/ktor-patterns/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: ktor-patterns
+description: Kotlin Ktor server guidance for Application modules, the routing DSL, installing ContentNegotiation with kotlinx.serialization, Authentication (JWT, bearer, sessions), StatusPages error mapping, structured coroutines and Dispatchers.IO for blocking work, wiring dependencies with Ktor DI or Koin, and in-process tests with testApplication. Use when writing or refactoring a Ktor backend, adding routes or plugins, fixing Ktor serialization or auth errors, or testing Ktor endpoints.
+license: MIT
+compatibility: Any Agent Skills host. Needs a JDK and the project's Gradle (or Maven) wrapper. Written for Ktor 3.x; the built-in DI plugin needs a recent 3.x release.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "java"
+  kete-loom/owner: "Kete-org"
+---
+
+# Ktor server patterns
+
+Ktor gives you a small core and explicit plugins. Keep it that way: every behaviour is installed in code you can read, and every module can be started in a test.
+
+## 0. Before you start
+
+1. Find the Ktor version (`io.ktor` dependencies or `libs.versions.toml`) and the engine (`ktor-server-netty`, `-cio`, `-jetty`). Ktor 2 and 3 differ in some APIs; follow the version the project uses.
+2. Find how the app starts: `embeddedServer(...)` in `main`, or `EngineMain` with `application.conf`/`application.yaml` listing `ktor.application.modules`.
+3. Run `./gradlew test` once and record the result. If it already fails, **stop and tell the user**.
+
+## 1. Modules and structure
+
+- Split setup into extension functions on `Application`: `fun Application.configureSerialization()`, `configureSecurity()`, `configureRouting()`. The main `module()` calls them in order.
+- Keep routes in feature files as extension functions on `Route` (`fun Route.orderRoutes(service: OrderService)`), registered inside `routing { }`.
+- Routes are thin: read parameters, validate, call a service, respond. Business logic and database access live in services and repositories that don't import Ktor.
+- Read config from `environment.config` (`property("payments.baseUrl").getString()`) or env vars, never hard-coded. Secrets come from the environment.
+
+## 2. Routing
+
+- Group with `route("/orders") { get { } ; get("{id}") { } ; post { } }`.
+- Read path and query parameters defensively: `call.parameters["id"]?.toLongOrNull() ?: return@get call.respond(HttpStatusCode.BadRequest)`. Better still, throw a domain exception and map it in StatusPages.
+- For typed routes, the `Resources` plugin (`@Resource` classes) gives compile-checked paths; use it if the project already does.
+- `call.receive<CreateOrder>()` throws on malformed bodies; let StatusPages turn that into 400.
+- Respond with DTOs annotated `@Serializable`, never database rows or internal models.
+
+## 3. Plugins
+
+Install each plugin once, at application level unless it must be scoped to a route.
+
+**ContentNegotiation**
+
+```kotlin
+install(ContentNegotiation) {
+    json(Json { ignoreUnknownKeys = true; explicitNulls = false })
+}
+```
+
+Needs `ktor-server-content-negotiation`, `ktor-serialization-kotlinx-json` and the `kotlin("plugin.serialization")` Gradle plugin. A missing `@Serializable` or missing compiler plugin is the usual cause of "Serializer for class ... is not found".
+
+**StatusPages**
+
+```kotlin
+install(StatusPages) {
+    exception<NotFoundException> { call, e -> call.respond(HttpStatusCode.NotFound, ErrorBody(e.message)) }
+    exception<BadRequestException> { call, _ -> call.respond(HttpStatusCode.BadRequest, ErrorBody("Invalid request")) }
+    exception<Throwable> { call, e ->
+        call.application.log.error("Unhandled", e)
+        call.respond(HttpStatusCode.InternalServerError, ErrorBody("Internal error"))
+    }
+}
+```
+
+Map each domain exception to one status. The catch-all logs and returns a generic body; never send `e.message` or stack traces from unexpected errors to clients.
+
+**Authentication**
+
+```kotlin
+install(Authentication) {
+    jwt("auth-jwt") {
+        realm = "api"
+        verifier(JWT.require(Algorithm.HMAC256(secret)).withIssuer(issuer).withAudience(audience).build())
+        validate { cred -> if (cred.payload.subject != null) JWTPrincipal(cred.payload) else null }
+        challenge { _, _ -> call.respond(HttpStatusCode.Unauthorized) }
+    }
+}
+routing { authenticate("auth-jwt") { orderRoutes(service) } }
+```
+
+- Everything that isn't public goes inside `authenticate(...)`. Read the user with `call.principal<JWTPrincipal>()` and check ownership in the service.
+- Always verify issuer, audience and expiry. Prefer RS256 with a JWKS provider (`jwt { verifier(jwkProvider, issuer) }`) when tokens come from an identity provider.
+- **Stop and ask the user** before changing which routes are public or how tokens are verified.
+
+Other common plugins: `CallLogging` (with `callIdMdc`), `CallId`, `CORS` (list origins explicitly; never `anyHost()` in production), `Compression`, `DefaultHeaders`.
+
+## 4. Coroutines
+
+- Route handlers are `suspend` and run on the engine's threads. **Never block them**: wrap JDBC, file I/O and blocking SDK calls in `withContext(Dispatchers.IO) { }`, or use a non-blocking client.
+- Never call `runBlocking` inside a handler or service.
+- Don't start work with `GlobalScope.launch`. For fire-and-forget work tied to the app, launch in the `Application` scope (`application.launch { }`) so it is cancelled on shutdown; for durable work use a queue.
+- Let `CancellationException` propagate. Don't swallow it in a `catch (e: Exception)`; rethrow it.
+- Set timeouts on outbound calls (`HttpTimeout` in the Ktor client) so a slow dependency can't hold requests open.
+
+## 5. Dependency injection
+
+Pick one approach and keep it:
+
+- **Manual wiring** (fine for small services): build services in `module()` and pass them into route functions.
+- **Ktor DI plugin** (`ktor-server-di`): register with `dependencies { provide<OrderService>(::OrderServiceImpl) }` (constructor parameters are resolved by type) and resolve with `val service: OrderService by dependencies` or `dependencies.resolve<OrderService>()`.
+- **Koin** (`koin-ktor`): `install(Koin) { modules(appModule) }` and `val service by inject<OrderService>()` in routes. Use it when the project already does.
+
+Whatever you use, services must be constructible in a test without a running server.
+
+## 6. Testing with testApplication
+
+```kotlin
+class OrderRoutesTest {
+    @Test
+    fun `returns 404 for unknown order`() = testApplication {
+        application { module(orderService = FakeOrderService()) }
+        val client = createClient { install(ContentNegotiation) { json() } }
+        val response = client.get("/orders/999") { bearerAuth(testToken()) }
+        assertEquals(HttpStatusCode.NotFound, response.status)
+    }
+}
+```
+
+- `testApplication` runs the app in process with no real network. Load your real modules with `application { }` so the plugins under test are the real ones; with `EngineMain`, set config via `environment { config = ApplicationConfig("application-test.conf") }`.
+- The client in `createClient` is a Ktor client; install client `ContentNegotiation` to send and read JSON bodies.
+- Replace external dependencies with fakes passed into the module, or with test registrations in your DI setup. Use Testcontainers for real database tests.
+- Cover for each route: success, validation failure (400), unauthenticated (401), wrong owner (403 or 404), not found, and the StatusPages mapping.
+- Use `externalServices { }` to stub third-party HTTP APIs the app calls.
+
+## Never
+
+- Blocking I/O on request threads, `runBlocking` in handlers, or `GlobalScope`.
+- Returning exception messages from the catch-all handler.
+- `anyHost()` CORS, or protected routes outside `authenticate { }`.
+- Installing the same plugin twice (Ktor throws `DuplicatePluginException`).
+
+## Before you finish
+
+Run `./gradlew test` (and `./gradlew build` if there are other checks). Report: routes added or changed with their auth requirement, plugins installed or reconfigured, tests added, and the final test counts.

package/skills/ktor-patterns/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Add JWT authentication and StatusPages error handling to my Ktor server",
+    "Ktor says Serializer for class OrderDto is not found when I call call.respond",
+    "Write tests for our Ktor routes with testApplication and a fake repository",
+    "Set up the Ktor DI plugin or Koin to inject services into Ktor routing",
+    "Is it ok to call JDBC directly inside a Ktor route handler or should I switch dispatchers?",
+    "Split my giant Ktor Application.module into routing, security and serialization plugins"
+  ],
+  "should_not_trigger": [
+    "Build a Quarkus REST endpoint backed by Panache and make it compile to a native image",
+    "Bind the payments.* settings in application.yml to a typed config class in Spring Boot",
+    "Explain Kotlin sealed classes and Flow operators for our Android app",
+    "Share networking code between Android and iOS with Kotlin Multiplatform and the Ktor client",
+    "Review this Kotlin pull request for coroutine misuse",
+    "Write unit tests with MockK and kotest for our Kotlin pricing module"
+  ]
+}

package/skills/kubernetes-patterns/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: kubernetes-patterns
+description: Kubernetes workload manifests and day-two operations with kubectl, covering Deployments, startup, readiness and liveness probes, CPU and memory requests and limits, ConfigMaps and Secrets, rolling updates and rollbacks, HorizontalPodAutoscaler, PodDisruptionBudgets and a step-by-step pod debugging routine. Use when writing or fixing Deployment, Service or HPA YAML, a rollout is stuck or needs undoing, or pods are in CrashLoopBackOff, Pending, OOMKilled or ImagePullBackOff.
+license: MIT
+compatibility: Any Agent Skills host. Cluster commands need kubectl configured for the target cluster; Helm or Kustomize only if the project already uses them.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "kubectl"
+  kete-loom/owner: "Kete-org"
+---
+
+# Kubernetes patterns
+
+Write workloads that start reliably, roll out without downtime, can be rolled back, and tell you why they are failing. Building the container image belongs to `docker-patterns`; provisioning the cluster itself belongs to `terraform-patterns`.
+
+## 0. Before touching anything
+
+1. Find how manifests are managed: plain YAML, Kustomize (`kustomization.yaml`), Helm (`Chart.yaml`, `values*.yaml`) or a GitOps tool (Argo CD, Flux). Edit the source of truth, never the live object, when GitOps is in use: a `kubectl edit` will be reverted.
+2. Run `kubectl config current-context` and say which cluster and namespace you are on.
+3. **Stop and ask the user before any write to a cluster** (`apply`, `delete`, `rollout undo`, `scale`, `edit`, `patch`), and always before anything in a context or namespace that looks like production. Read-only commands (`get`, `describe`, `logs`, `events`, `top`, `diff`) are fine.
+4. Prefer `kubectl diff -f <file>` before `kubectl apply -f <file>`, and show the diff.
+
+## 1. Deployment checklist
+
+Every long-running workload gets all of these. A full annotated example is in `references/manifests.md`.
+
+1. **Labels**: a stable `selector.matchLabels` (it is immutable after creation) and the same labels on the pod template. Use `app.kubernetes.io/name` and `app.kubernetes.io/instance`.
+2. **Image** pinned to an immutable tag or digest, never `latest`. `imagePullPolicy: IfNotPresent` for immutable tags.
+3. **Replicas** at least 2 for anything user-facing, unless an HPA owns the count. When an HPA manages the Deployment, remove `replicas` from the manifest so an apply does not reset it.
+4. **Resources**: set `requests` for CPU and memory on every container, and a memory `limit`. Memory over the limit gets the container OOMKilled. A CPU limit throttles rather than kills; set one only if the team's policy requires it, and know it can add latency.
+5. **Probes**, each with a distinct job:
+   - `startupProbe` for slow starters: holds off the other probes until it passes. Size `failureThreshold × periodSeconds` to the worst startup time.
+   - `readinessProbe`: "can I take traffic now". Failing it removes the pod from Service endpoints; it does not restart it. It may check critical dependencies.
+   - `livenessProbe`: "am I stuck and need a restart". Keep it cheap and local; never check the database or another service here, or one outage restarts every pod.
+6. **Graceful shutdown**: the app handles `SIGTERM`, and `terminationGracePeriodSeconds` covers in-flight requests. A short `preStop` sleep (a few seconds) helps load balancers drain, if the image has a `sleep` binary.
+7. **Security context**: `runAsNonRoot: true`, `allowPrivilegeEscalation: false`, `readOnlyRootFilesystem: true` where the app allows (mount an `emptyDir` for `/tmp`), `capabilities.drop: ["ALL"]`, `seccompProfile.type: RuntimeDefault`.
+8. **Rollout strategy**: `RollingUpdate` with `maxUnavailable: 0` and `maxSurge: 1` (or 25%) for zero downtime. Set `revisionHistoryLimit` so rollbacks are possible.
+9. **PodDisruptionBudget** for workloads with 2+ replicas, so node drains keep some pods up. `minAvailable` must be lower than the replica count, or drains block forever.
+10. **ServiceAccount**: a dedicated one, with `automountServiceAccountToken: false` unless the app calls the API.
+
+## 2. Configuration and secrets
+
+- Non-secret settings in a ConfigMap, consumed via `envFrom` or a mounted file.
+- Credentials in a Secret. A Secret is base64-encoded, not encrypted: never commit a plain Secret manifest with real values. Use what the project already has (External Secrets Operator, Sealed Secrets, SOPS, the cloud's secret store CSI driver) and stop and ask if there is nothing.
+- Pods do not restart when a ConfigMap or Secret used as env changes. Trigger a rollout (`kubectl rollout restart deployment/<name>`), or use a checksum annotation in Helm or Kustomize's `configMapGenerator` hash suffix.
+
+## 3. Rollouts and rollbacks
+
+```sh
+kubectl rollout status deployment/<name> -n <ns> --timeout=5m
+kubectl rollout history deployment/<name> -n <ns>
+kubectl rollout undo deployment/<name> -n <ns>                 # previous revision
+kubectl rollout undo deployment/<name> -n <ns> --to-revision=N
+kubectl rollout pause|resume deployment/<name> -n <ns>
+```
+
+- Set `progressDeadlineSeconds` so a stuck rollout reports `ProgressDeadlineExceeded` instead of hanging.
+- With GitOps, roll back by reverting the commit; `rollout undo` will be overwritten on the next sync.
+- A rollback does not undo database migrations. Check before rolling back past a schema change.
+
+## 4. Autoscaling
+
+- Use `autoscaling/v2` HorizontalPodAutoscaler. CPU-utilisation targets are a percentage of the **request**, so requests must be set.
+- Needs metrics-server (or a custom metrics adapter); check `kubectl top pods` works first.
+- Set `minReplicas` ≥ 2 for availability, and a `behavior.scaleDown.stabilizationWindowSeconds` to avoid flapping.
+- Don't run an HPA and a VerticalPodAutoscaler in update mode on the same CPU or memory metric.
+
+## 5. Debugging a failing pod
+
+Work in this order and stop when you find the cause:
+
+1. `kubectl get pods -n <ns> -o wide`: status, restarts, node.
+2. `kubectl describe pod <pod> -n <ns>`: read **Events** at the bottom and each container's **Last State** (reason, exit code).
+3. `kubectl logs <pod> -n <ns> -c <container>` and `--previous` for the crashed instance.
+4. `kubectl get events -n <ns> --sort-by=.lastTimestamp`.
+5. If the image has no shell: `kubectl debug -it <pod> -n <ns> --image=busybox --target=<container>`. This adds an ephemeral container to the live pod, so it is a cluster write: ask first.
+
+Common causes:
+
+| Symptom | Look at |
+|---|---|
+| `Pending` | Events: insufficient CPU/memory, unbound PVC, node selector/taints/affinity with no match |
+| `ImagePullBackOff` / `ErrImagePull` | Image name or tag typo, private registry without `imagePullSecrets`, wrong architecture |
+| `CrashLoopBackOff` | `logs --previous`; bad config or missing env var; liveness probe killing a slow start (add a startupProbe) |
+| `OOMKilled` (exit 137) | Memory limit too low for real usage, or a leak; check `kubectl top pod` |
+| Running but no traffic | Readiness failing, Service `selector` not matching pod labels, wrong `targetPort`; check `kubectl get endpointslices -l kubernetes.io/service-name=<svc>` |
+| `CreateContainerConfigError` | Referenced ConfigMap/Secret or key does not exist |
+
+Report the cause with the exact event or log line that proves it, before proposing a fix.
+
+## 6. Verify
+
+- Validate before applying: `kubectl apply --dry-run=client -f <file>` offline, or `kubectl apply --dry-run=server -f <file>` (needs cluster access; runs admission checks without persisting). If the project uses `kubeconform`, `helm lint` or `helm template`, or `kustomize build`, run them.
+- After an approved apply: `kubectl rollout status` reaches success, pods are `Ready`, and the Service has endpoints.
+
+## Never
+
+- Never `kubectl delete` a namespace, PVC or StatefulSet, or `--force --grace-period=0` a pod, without explicit user approval.
+- Never put secret values in a ConfigMap, a manifest committed to git, or a command line that ends up in shell history.
+- Never set `privileged: true`, `hostNetwork`, `hostPID` or a `hostPath` mount unless the user asks and states why.
+
+## Report back
+
+End with: cluster context and namespace used, files changed, commands run (marking which ones wrote to the cluster and that the user approved them), the rollout or debug result with the evidence line, and what you did not check.

package/skills/kubernetes-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Our api pods keep going into CrashLoopBackOff after the deploy, help me find out why",
+    "Write a Deployment and Service manifest for the web app with readiness and liveness probes",
+    "The new release is broken, how do I roll the checkout deployment back to the last revision?",
+    "Set up a HorizontalPodAutoscaler for the worker so it scales on CPU",
+    "Pods are stuck in Pending and kubectl describe mentions insufficient memory"
+  ],
+  "should_not_trigger": [
+    "Make our Dockerfile smaller and stop it running as root",
+    "Provision an EKS cluster and its node groups with Terraform",
+    "Audit our k8s manifests and Terraform for security misconfigurations and report findings",
+    "Plan a blue-green release process for the mobile backend",
+    "Our docker compose app container can't reach the database on localhost"
+  ]
+}