@ketecode/loom 0.0.0-stage → 0.2.0

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"
+  ]
+}

package/skills/kubernetes-patterns/references/manifests.md

@@ -0,0 +1,115 @@
+# Kubernetes manifest examples
+
+Annotated starting points. Replace names, image, ports and numbers with the project's real values.
+
+## Deployment
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: web
+  labels: { app.kubernetes.io/name: web }
+spec:
+  # replicas omitted: the HPA below owns the count
+  revisionHistoryLimit: 5
+  progressDeadlineSeconds: 600
+  selector:
+    matchLabels: { app.kubernetes.io/name: web }   # immutable after creation
+  strategy:
+    type: RollingUpdate
+    rollingUpdate: { maxUnavailable: 0, maxSurge: 1 }
+  template:
+    metadata:
+      labels: { app.kubernetes.io/name: web }
+    spec:
+      serviceAccountName: web
+      automountServiceAccountToken: false
+      terminationGracePeriodSeconds: 30
+      securityContext:
+        runAsNonRoot: true
+        seccompProfile: { type: RuntimeDefault }
+      containers:
+        - name: web
+          image: registry.example.com/web:1.4.2
+          ports: [{ name: http, containerPort: 8080 }]
+          envFrom:
+            - configMapRef: { name: web-config }
+            - secretRef: { name: web-secrets }
+          resources:
+            requests: { cpu: 100m, memory: 256Mi }
+            limits: { memory: 512Mi }
+          startupProbe:
+            httpGet: { path: /healthz, port: http }
+            periodSeconds: 5
+            failureThreshold: 24          # up to 2 minutes to start
+          readinessProbe:
+            httpGet: { path: /readyz, port: http }
+            periodSeconds: 5
+          livenessProbe:
+            httpGet: { path: /healthz, port: http }
+            periodSeconds: 10
+            failureThreshold: 3
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true
+            capabilities: { drop: ["ALL"] }
+          volumeMounts:
+            - { name: tmp, mountPath: /tmp }
+      volumes:
+        - { name: tmp, emptyDir: {} }
+```
+
+## Service
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: web
+spec:
+  selector: { app.kubernetes.io/name: web }   # must match pod labels
+  ports:
+    - { name: http, port: 80, targetPort: http }
+```
+
+## HorizontalPodAutoscaler
+
+```yaml
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: web
+spec:
+  scaleTargetRef: { apiVersion: apps/v1, kind: Deployment, name: web }
+  minReplicas: 2
+  maxReplicas: 10
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target: { type: Utilization, averageUtilization: 70 }   # % of the CPU request
+  behavior:
+    scaleDown:
+      stabilizationWindowSeconds: 300
+```
+
+## PodDisruptionBudget
+
+```yaml
+apiVersion: policy/v1
+kind: PodDisruptionBudget
+metadata:
+  name: web
+spec:
+  minAvailable: 1          # must be below the replica count
+  selector:
+    matchLabels: { app.kubernetes.io/name: web }
+```
+
+## Probe sizing rules of thumb
+
+- `startupProbe`: `failureThreshold × periodSeconds` ≥ worst observed startup time, with margin.
+- `readinessProbe`: short period (5s) so pods leave endpoints quickly when unhealthy.
+- `livenessProbe`: conservative (`failureThreshold` 3 or more) so a GC pause or a brief spike doesn't restart the pod.
+- Use separate endpoints for readiness (may check dependencies) and liveness (process-local only) when the app can offer them.