@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/jetpack-compose-patterns/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: jetpack-compose-patterns
+description: Android Jetpack Compose UI work centred on hoisting state into stateless composables, understanding recomposition, stability and strong skipping, choosing the right side-effect API (LaunchedEffect, DisposableEffect, rememberUpdatedState, derivedStateOf, snapshotFlow), exposing ViewModel state with collectAsStateWithLifecycle, type-safe Navigation Compose routes, and lazy-list and baseline-profile performance. Use when writing or restructuring Compose screens on Android, debugging excessive recomposition or janky LazyColumn scrolling, wiring a ViewModel to a composable, or setting up Compose navigation.
+license: MIT
+compatibility: Any Agent Skills host. Needs a JDK and the project's Gradle wrapper (./gradlew); device runs need the Android SDK and an emulator or device.
+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"
+---
+
+# Jetpack Compose patterns
+
+Write Compose UI where state lives in one place, composables skip when their inputs didn't change, and effects run exactly when intended. Kotlin language features, coroutines and Flow belong to `kotlin-patterns`; sharing code with iOS belongs to `kotlin-multiplatform`.
+
+## 0. Before you write
+
+1. Read the module's `build.gradle.kts` and `gradle/libs.versions.toml`: Kotlin version, Compose BOM, whether the `org.jetbrains.kotlin.plugin.compose` compiler plugin is applied (Kotlin 2.0+), and which navigation library is used (`androidx.navigation:navigation-compose` or Navigation 3).
+2. Find the project's DI (Hilt, Koin, manual) and how ViewModels are obtained (`hiltViewModel()`, `viewModel()`, `koinViewModel()`). Follow it.
+3. Build once (`./gradlew :app:assembleDebug` or the project's task) and run unit tests; record the result.
+
+## 1. State hoisting
+
+- Split each screen into a **stateful** route composable (gets the ViewModel, collects state) and a **stateless** screen composable that takes `state` and event lambdas: `ProfileScreen(state, onNameChange, onSave)`.
+- Hoist state to the lowest common owner of everything that reads or writes it. UI-only state (scroll, expanded, focus) can stay in the composable with `remember` / `rememberSaveable`.
+- Use `rememberSaveable` for state that must survive configuration change and process death (text input, selected tab).
+- Every reusable composable takes `modifier: Modifier = Modifier` as its first optional parameter and applies it to its root, once.
+- Never pass a ViewModel or `NavController` down into leaf composables; pass state and lambdas.
+
+## 2. Recomposition and stability
+
+- Since Kotlin 2.0.20 strong skipping is on by default: composables with unstable parameters can still skip, but unstable parameters are compared by instance (`===`), stable ones by `equals`. So a new `List` instance with the same contents still recomposes.
+- Make UI state classes immutable `data class`es with `val`s. Use `kotlinx.collections.immutable` (`ImmutableList`) or mark classes `@Immutable` / `@Stable` only when the promise is true.
+- Read state as late as possible: pass a lambda (`{ scrollState.value }`) or use lambda-based modifiers (`Modifier.offset { }`, `graphicsLayer { }`) for values that change every frame, so only layout or draw re-runs.
+- Use `derivedStateOf` when a frequently changing state produces a rarely changing result (`showButton = listState.firstVisibleItemIndex > 0`). Don't use it for a simple combination of two states.
+- `remember(key) { expensive() }` for work inside composition; never sort, filter or format large data directly in a composable body.
+- Check with Layout Inspector recomposition counts, and the Compose compiler reports (`composeCompiler { reportsDestination = ... }`) when stability is in doubt.
+
+## 3. Side effects
+
+| Need | API |
+|---|---|
+| Run suspend work when entering composition or when a key changes | `LaunchedEffect(key)` |
+| Register / unregister a listener or observer | `DisposableEffect(key) { ...; onDispose { } }` |
+| Use the latest lambda inside a long-running effect without restarting it | `rememberUpdatedState(onTimeout)` |
+| Launch coroutines from callbacks (click handlers) | `rememberCoroutineScope()` |
+| Turn Compose state into a Flow | `snapshotFlow { state.value }` |
+| Publish Compose state to non-Compose code after every successful composition | `SideEffect` |
+
+Rules: keys must be the values that should restart the effect, never `Unit` when the effect reads a changing parameter. One-off events (navigate, snackbar) come from the ViewModel as state or a `Channel`/`Flow` collected in a `LaunchedEffect`, never by calling navigation inside composition.
+
+## 4. ViewModel and lifecycle
+
+- The ViewModel exposes one `StateFlow<UiState>` built with `stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), initial)` or a `MutableStateFlow` it updates.
+- Collect it with `collectAsStateWithLifecycle()` (from `androidx.lifecycle:lifecycle-runtime-compose`), not `collectAsState()`, so collection stops when the app is in the background.
+- Business logic, network and database work live in the ViewModel and repositories, never in composables.
+- Use `SavedStateHandle` for navigation arguments and small state that must survive process death.
+
+## 5. Navigation
+
+- Navigation Compose 2.8+: define routes as `@Serializable` objects and data classes, `composable<Profile> { entry -> entry.toRoute<Profile>() }`, and navigate with `navController.navigate(Profile(id))`. Don't build string routes by hand in new code.
+- Navigation 3 (stable since late 2025) keeps the back stack as your own state. Use it only if the project already does or the user chooses it.
+- Pass IDs, not objects. Load data in the destination's ViewModel via `SavedStateHandle`.
+- Keep the `NavController` / back stack at the top-level `NavHost`; leaf screens receive `onNavigateToX` lambdas.
+- Handle system back with `BackHandler` only where you must intercept it (unsaved changes).
+
+## 6. Performance
+
+- Measure in a **release** build (R8 on, not debuggable); debug Compose is much slower.
+- `LazyColumn` / `LazyRow`: give items a stable `key = { it.id }` and a `contentType` when rows differ. Never nest a vertically scrolling lazy list inside a `Column` with `verticalScroll`.
+- Avoid allocating in item content: hoist `Modifier` chains and formatters, `remember` them.
+- Add a Baseline Profile (`androidx.baselineprofile` plugin and a Macrobenchmark module) for startup and scroll paths in production apps.
+- Use Macrobenchmark `FrameTimingMetric` to prove a jank fix.
+
+**Stop and ask the user** before switching navigation libraries, raising `minSdk`, or upgrading Kotlin or the Compose BOM as part of an unrelated change.
+
+## Never
+
+- Never launch coroutines, navigate or write to state directly in a composable body.
+- Never use `collectAsState()` for ViewModel state on Android when lifecycle-aware collection is available.
+- Never annotate a class `@Stable` or `@Immutable` that has mutable public state.
+- Never use `Unit` as an effect key when the effect depends on a parameter.
+
+## Report back
+
+End with: composables and ViewModels changed, where each new piece of state lives, Gradle tasks run with results, and whether you checked recomposition or frame timing (and how).

package/skills/jetpack-compose-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "My Compose LazyColumn recomposes every row when one item is liked",
+    "Should I use LaunchedEffect or DisposableEffect to register this location listener in a composable?",
+    "Hoist the state out of this Compose text field so the ViewModel owns it",
+    "Switch our NavHost to type-safe @Serializable routes",
+    "collectAsState vs collectAsStateWithLifecycle for my ViewModel StateFlow"
+  ],
+  "should_not_trigger": [
+    "Use Compose Multiplatform so the same UI runs on iOS and Android",
+    "Write a coroutine Flow that debounces search queries in plain Kotlin",
+    "Fix this Gradle build failure: Unresolved reference in the Kotlin module",
+    "Build a SwiftUI list with lazy loading of images",
+    "Review this Kotlin pull request for unsafe !! and leaked coroutine scopes"
+  ]
+}

package/skills/jira-integration/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: jira-integration
+description: Connects code to Jira Cloud through the REST API v3, from picking basic auth with an Atlassian API token or OAuth 2.0 (3LO) with a cloudId, through enhanced JQL search on /rest/api/3/search/jql with nextPageToken paging, creating issues with Atlassian Document Format bodies, looking up custom field IDs and running workflow transitions, to registering webhooks and coping with 429 burst and points-based quotas. Use when building a Jira sync, bot or importer, moving off the removed /rest/api/3/search endpoint, setting custom fields or transitions from code, or handling Jira webhooks and rate limits.
+license: MIT
+compatibility: Any Agent Skills host. Live calls need network access to <site>.atlassian.net or api.atlassian.com. Covers Jira Cloud only; Jira Data Center and Server have a different API surface and auth.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: integrations
+  kete-loom/risk: network
+  kete-loom/requires: "curl"
+  kete-loom/owner: "Kete-org"
+---
+
+# Jira Cloud integration
+
+Build a Jira integration that authenticates with the right credential, finds issues with paged JQL, writes fields Jira accepts, moves issues through the real workflow, and slows down when Jira says so.
+
+## Ground rules
+
+1. **Jira Cloud, REST v3.** Base URL `https://<site>.atlassian.net/rest/api/3/` for API-token calls, or `https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/` for OAuth 2.0 and scoped tokens. If the user is on Data Center or Server, stop: this skill does not cover it.
+2. **Credentials from the environment.** Never commit an API token or client secret, never log the `Authorization` header.
+3. **Never hard-code IDs** for custom fields, issue types or transitions. They differ per site and per project; look them up and cache them.
+4. **People are account IDs.** Set assignee and reporter with `accountId`; usernames and email lookups are not reliable in Cloud.
+5. **Text fields in v3 are ADF** (Atlassian Document Format) JSON, not plain strings or wiki markup.
+
+## Choose the auth
+
+| Situation | Use |
+|---|---|
+| Script or internal service for one site | Basic auth: `email:api_token` base64-encoded in `Authorization: Basic ...`. Tokens are created at id.atlassian.com, expire (1 to 365 days) and act as that user |
+| Narrower internal access | A scoped API token, called through `api.atlassian.com/ex/jira/{cloudId}` |
+| App other people's sites install, acting as each user | OAuth 2.0 (3LO) |
+| Code running inside Jira (UI, triggers) | Forge app; out of scope here |
+
+Use a dedicated service account for shared integrations, not a person's token. Stop and ask the user before using an admin's token.
+
+### OAuth 2.0 (3LO)
+
+1. Register the app in the Atlassian developer console; add the Jira API scopes you need (classic `read:jira-work`, `write:jira-work`, `read:jira-user`, or granular scopes) plus `offline_access` for refresh tokens.
+2. Send the user to `https://auth.atlassian.com/authorize?audience=api.atlassian.com&client_id=...&scope=...&redirect_uri=...&state=...&response_type=code&prompt=consent`. Check `state` on return.
+3. Exchange the code at `POST https://auth.atlassian.com/oauth/token`. Refresh tokens rotate: store the new refresh token every time you refresh.
+4. `GET https://api.atlassian.com/oauth/token/accessible-resources` lists the sites the token can reach; store each `id` as the `cloudId` and call `api.atlassian.com/ex/jira/{cloudId}/...`.
+
+## Search with JQL
+
+- `GET/POST /rest/api/3/search` was removed from Jira Cloud. Use `POST /rest/api/3/search/jql` with `{ "jql": "...", "fields": [...], "maxResults": 100, "nextPageToken": "..." }`.
+- Always pass `fields` explicitly; ask for only what you use.
+- Page by sending back `nextPageToken` until the response has none (or `isLast` is true). There is no `startAt` and no `total`; for a count, use `POST /rest/api/3/search/approximate-count`.
+- Always bound JQL (`project = ABC AND updated >= -1d ORDER BY updated ASC`). An unbounded query on a large site is slow and burns quota.
+- Quote values with spaces or reserved words, and build JQL from validated values, never by pasting user input into the string.
+- For incremental sync, store the last `updated` you processed and query `updated >= "<timestamp>"`, then dedupe by issue ID (JQL date precision is minutes).
+
+## Create and update issues
+
+1. Discover fields for the target: `GET /rest/api/3/issue/createmeta/{projectIdOrKey}/issuetypes` then `.../issuetypes/{issueTypeId}` for required fields and allowed values. `GET /rest/api/3/field` maps custom field names to IDs (`customfield_10042`); cache by name, look up once per site.
+2. `POST /rest/api/3/issue` with `fields`: `project: {key}`, `issuetype: {id}`, `summary`, `description` as ADF, plus required custom fields in their type's shape (select: `{ "value": "High" }` or `{ "id": "..." }`; user: `{ "accountId": "..." }`; number and date as plain values).
+3. Minimal ADF: `{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"..."}]}]}`.
+4. Update with `PUT /rest/api/3/issue/{key}` using `fields` (set) or `update` (add/remove on multi-value fields such as labels). Add `notifyUsers=false` only if the user asks; it needs the Administer Jira or Administer Projects permission.
+5. Comments: `POST /rest/api/3/issue/{key}/comment` with an ADF `body`.
+6. Make creates idempotent yourself: Jira has no idempotency key. Store your external ID in an issue property or a label and search for it before creating.
+7. Read the 400 response `errors` object; it names each field that failed.
+
+## Transitions
+
+1. `GET /rest/api/3/issue/{key}/transitions` lists transitions available **now** for that issue and user (add `expand=transitions.fields` to see screen fields).
+2. Pick by target status (`to.name` or `to.id`), not by transition name or a hard-coded ID; workflows differ per project.
+3. `POST /rest/api/3/issue/{key}/transitions` with `{ "transition": { "id": "31" }, "fields": { "resolution": { "name": "Done" } } }` when the screen requires fields.
+4. If the target is not listed, the workflow does not allow it from the current status or the user lacks permission. Report that; do not try other transitions to get there unless the user asks.
+
+## Webhooks
+
+- Admin-created webhooks (Jira settings or `/rest/webhooks/1.0/webhook`): set a `secret`; Jira then sends `X-Hub-Signature: sha256=<hex HMAC of the raw body>`. Verify on the raw bytes with a constant-time compare.
+- OAuth 2.0 and Connect apps register dynamic webhooks with `POST /rest/api/3/webhook` (JQL filter limited to fields such as `project`, `issuetype`, `status`, `assignee`). They expire after 30 days: refresh with `PUT /rest/api/3/webhook/refresh` and `{ "webhookIds": [...] }` on a schedule. An OAuth app can register 5 per user per site. OAuth apps receive a JWT in `Authorization` signed with the client secret; verify it.
+- Jira retries failed deliveries (408, 409, 425, 429, 5xx, timeouts) up to five times. Dedupe on `X-Atlassian-Webhook-Identifier`; `X-Atlassian-Webhook-Retry` gives the attempt number.
+- Acknowledge fast and process from a queue. The payload may be stale; re-fetch the issue if you need current state.
+
+## Rate limits
+
+- Jira returns `429` with `Retry-After` (seconds) and `RateLimit-Reason` (`jira-burst-based`, `jira-quota-global-based`, `jira-quota-tenant-based`, `jira-per-issue-on-write`). Watch `X-RateLimit-NearLimit: true`.
+- Limits: per-second burst limits per endpoint, an hourly points quota for apps (enforced from March 2026; API-token traffic stays under burst limits), and per-issue write limits (20 writes per 2 seconds, 100 per 30 seconds on one issue).
+- Wait at least `Retry-After`, then exponential backoff with jitter, capped at a few retries; retry only idempotent requests. On quota reasons pause all calls; on burst slow that endpoint; on per-issue space out writes to that issue.
+- Batch where Jira offers it (bulk create `POST /rest/api/3/issue/bulk`, up to 50 issues) and fetch only needed fields.
+
+## Stop and ask the user
+
+- Before bulk edits, bulk transitions or deletes on more than a handful of issues; show the JQL and the count first.
+- Before creating webhooks, custom fields or workflow changes on a production site.
+- If required fields or the workflow make the requested change impossible, rather than guessing values.
+
+## Before you finish
+
+Test against a sandbox site or a throwaway project: a search that spans more than one page, a create with every required custom field, a transition that needs a screen field, a duplicate create (no second issue), a webhook with a bad signature (rejected), and a forced 429 handled with backoff. Atlassian's REST v3 reference at developer.atlassian.com is the final word on endpoints and payloads.

package/skills/jira-integration/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Our Jira sync broke because /rest/api/3/search now returns 410, move it to the new JQL search endpoint",
+    "Create Jira issues from our support tool and fill the Severity custom field from code",
+    "Move a Jira ticket to Done through the REST API when the related PR merges",
+    "Set up OAuth 2.0 3LO so customers can connect their Jira Cloud site to our app",
+    "The Jira importer keeps getting 429 with RateLimit-Reason jira-burst-based, add proper backoff",
+    "Verify the X-Hub-Signature on webhooks coming from our Jira Cloud admin webhook"
+  ],
+  "should_not_trigger": [
+    "Create Linear issues from our error tracker using the GraphQL API",
+    "Write a JQL filter in the Jira UI that shows my team's overdue bugs",
+    "Estimate how many sprints the checkout rewrite will take",
+    "Open a GitHub issue automatically when the nightly job fails",
+    "Write the incident postmortem for last night's outage"
+  ]
+}

package/skills/jpa-hibernate/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: jpa-hibernate
+description: Jakarta Persistence and Hibernate ORM data-layer rules for entity and association mapping, LAZY-by-default fetch plans, finding and fixing N+1 selects with JOIN FETCH, entity graphs or batch fetching, transaction scope and LazyInitializationException, @Version optimistic locking, and evolving the schema through Flyway or Liquibase rather than ddl-auto. Use when mapping JPA entities, chasing slow or repeated SQL from Hibernate, fixing lazy loading or stale-update errors, or adding a database migration in a Java or Kotlin JVM project.
+license: MIT
+compatibility: Any Agent Skills host. Needs a JDK and the project's build wrapper. Written for Jakarta Persistence 3.x with Hibernate ORM 6.x; applies under Spring Boot, Quarkus or plain Jakarta EE.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: data
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "java"
+  kete-loom/owner: "Kete-org"
+---
+
+# JPA and Hibernate
+
+Hibernate hides SQL, which is why most of its bugs are invisible until production. Make the SQL visible, load exactly what each use case needs, and let migrations own the schema. Mapping examples are in `references/mapping.md`.
+
+## 0. Before you start
+
+1. Find the Hibernate version (Hibernate 6 uses `jakarta.persistence`; 5 and older use `javax.persistence`) and the framework (Spring Data JPA, Quarkus Panache, plain `EntityManager`).
+2. Find the migration tool: `db/migration/V*__*.sql` (Flyway) or a `db.changelog-master` file (Liquibase). If neither exists and the schema comes from `ddl-auto`, tell the user and propose adding one before changing tables.
+3. Turn on SQL logging in dev or tests so you can count statements: `spring.jpa.show-sql=true` / `quarkus.hibernate-orm.log.sql=true`, or log `org.hibernate.SQL` at DEBUG. Add `hibernate.generate_statistics=true` when chasing N+1.
+
+## 1. Entity mapping rules
+
+- Every entity has a surrogate id. Use `GenerationType.SEQUENCE` (or `IDENTITY` on MySQL). `IDENTITY` disables JDBC insert batching; prefer sequences where the database supports them.
+- `equals`/`hashCode`: base them on a natural business key, or on the id with a constant `hashCode()` (`getClass().hashCode()`). Never include associations or lazy fields. In Kotlin, never use a `data class` for an entity.
+- Map enums with `@Enumerated(EnumType.STRING)`, never the default `ORDINAL`.
+- Money: `BigDecimal` with explicit `precision` and `scale`, or integer minor units. Never `double`.
+- Time: `Instant` or `OffsetDateTime` for points in time; store in UTC (`hibernate.jdbc.time_zone=UTC`; in Spring Boot `spring.jpa.properties.hibernate.jdbc.time_zone=UTC`).
+- Entities need a no-arg constructor (protected is fine) and must not be `final` if they are proxied lazily (Kotlin: use the `kotlin-jpa` and `allopen` compiler plugins).
+
+## 2. Associations and fetch strategy
+
+- **Make every association LAZY.** `@ManyToOne` and `@OneToOne` are EAGER by default: always write `fetch = FetchType.LAZY`. Collections are already lazy.
+- Prefer unidirectional `@ManyToOne` from child to parent. Add the `@OneToMany(mappedBy = ...)` side only when you really navigate it, and keep both sides in sync with helper methods (`addItem`, `removeItem`).
+- Avoid `@ManyToMany` when the join has attributes or might gain them; model the join table as its own entity.
+- Use `Set` or `List` deliberately: fetching two `List` collections with `JOIN FETCH` in one query throws `MultipleBagFetchException`. Fetch one collection per query, or use `Set`.
+- `cascade = ALL` and `orphanRemoval = true` belong only on true parent-owned children (order → order lines), never on references to shared entities (order → customer).
+
+## 3. Finding and fixing N+1
+
+Symptom: one query for the list, then one more per row. Confirm by counting statements in the SQL log or statistics before changing anything.
+
+Fix with the narrowest tool:
+
+1. **Fetch join** for a use case that always needs the association: `select o from Order o join fetch o.customer where o.status = :s`.
+2. **Entity graph** to choose fetches per query without rewriting JPQL: `@EntityGraph(attributePaths = {"customer", "lines"})` on a Spring Data method, or a `jakarta.persistence.fetchgraph` hint.
+3. **Batch fetching** to turn N queries into N/size: `@BatchSize(size = 50)` on the association or `hibernate.default_batch_fetch_size=50` globally. Good default for collections you can't fetch-join.
+4. **DTO projection** for read-only screens: `select new com.acme.OrderRow(o.id, c.name) from Order o join o.customer c`, or a Spring Data interface/record projection. No entities, no dirty checking, no lazy surprises.
+
+Don't fix N+1 by switching to `FetchType.EAGER`; that loads the association everywhere and often causes more queries.
+
+Paging with collection fetch joins makes Hibernate load every row and page in memory (it logs a warning about applying the limit in memory). Page the ids first, then fetch the entities with their collections by id. Set `hibernate.query.fail_on_pagination_over_collection_fetch=true` so this fails in tests instead of silently loading everything.
+
+## 4. Transactions and lazy loading
+
+- Load and use entities inside one transaction, at the service layer. `LazyInitializationException` means a lazy field was touched after the session closed; fix it by fetching what the use case needs (section 3) or mapping to a DTO inside the transaction.
+- **Do not** fix it with `hibernate.enable_lazy_load_no_trans` or by enabling open-session-in-view; both hide extra queries and run them outside a transaction. In Spring Boot set `spring.jpa.open-in-view=false`.
+- Changes to managed entities are flushed automatically at commit (dirty checking). Calling `save()` on an already managed entity is unnecessary.
+- Use read-only transactions for queries (`@Transactional(readOnly = true)` in Spring) so Hibernate skips dirty checking.
+- Bulk `update`/`delete` JPQL bypasses the persistence context; clear it afterwards (`@Modifying(clearAutomatically = true)` in Spring Data) or reload entities.
+- For large batch jobs: set `hibernate.jdbc.batch_size`, and `flush()` plus `clear()` every N entities so memory stays flat.
+
+## 5. Optimistic locking
+
+- Add `@Version private long version;` (or `Long`/`Integer`) to entities edited concurrently by users or jobs. Hibernate adds `where version = ?` to updates and throws `OptimisticLockException` (Spring: `ObjectOptimisticLockingFailureException`) when another transaction got there first.
+- Expose the version to clients (an `ETag` header or a field in the DTO) and send it back on update, so a stale form fails instead of overwriting someone's change. Map the exception to HTTP 409 or 412.
+- Retry only when the operation is safe to repeat (for example a counter increment), reloading the entity each time, with a small retry limit.
+- Use pessimistic locks (`LockModeType.PESSIMISTIC_WRITE`, `select ... for update`) only for short critical sections such as allocating stock, and always inside a transaction with a lock timeout.
+- Never set the version field by hand.
+
+## 6. Migrations (Flyway or Liquibase)
+
+- The schema is owned by migrations. Set schema generation (`spring.jpa.hibernate.ddl-auto`; Quarkus `quarkus.hibernate-orm.schema-management.strategy`, called `database.generation` before 3.23) to `validate` or `none` everywhere except throwaway local experiments.
+- Flyway: versioned files `V<version>__<description>.sql` under `db/migration`, applied in order and checksummed. **Never edit a migration that has run anywhere shared**; add a new one. Repeatable `R__` scripts are for views and functions.
+- Liquibase: changesets identified by `id` + `author` + file; same rule, never change an applied changeset.
+- Write backward-compatible migrations so old and new app versions can run during a rolling deploy (expand, migrate data, then contract in a later release). Example: add a nullable column, backfill, then add `NOT NULL` later.
+- Add indexes for every foreign key and for columns in frequent `where`/`order by`. On large PostgreSQL tables use `create index concurrently` (in Flyway, put it in its own migration so it runs outside a transaction; Flyway cannot mix it with transactional statements; if the migration hangs on Flyway's lock, set `flyway.postgresql.transactional.lock=false`).
+- **Stop and ask the user** before any migration that drops or renames columns or tables, rewrites a large table, or deletes data.
+- Test migrations against the real database engine (Testcontainers), not H2, and run `validate` in CI.
+
+## Never
+
+- EAGER fetching to silence a lazy loading error, or `enable_lazy_load_no_trans`.
+- `ddl-auto=update` in production, or editing an applied migration.
+- Entities serialised directly to JSON.
+- `ORDINAL` enums, `double` money, or `equals` over lazy associations.
+
+## Before you finish
+
+Run the test suite with SQL logging on for the changed queries. Report: entities and mappings changed, the statement count before and after for any N+1 fix, migrations added (file names), whether they are backward compatible, and the final test counts.

package/skills/jpa-hibernate/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Our Hibernate entities trigger hundreds of selects when loading the order list, fix the N+1",
+    "Getting LazyInitializationException: could not initialize proxy - no Session when mapping to DTO",
+    "Add @Version optimistic locking to the JPA Account entity and return 409 on conflicts",
+    "How should I map a one-to-many between Order and OrderLine in JPA with cascade and orphan removal?",
+    "Replace spring.jpa.hibernate.ddl-auto=update with Flyway migrations for our entities",
+    "MultipleBagFetchException when I join fetch two lists in a JPQL query"
+  ],
+  "should_not_trigger": [
+    "Add a new REST endpoint to our Spring Boot order service with request validation and proper 404 responses",
+    "Tune this slow PostgreSQL query plan and suggest indexes",
+    "Set up Prisma schema and migrations for our Node backend",
+    "Configure EF Core migrations and fix the tracking issue in our ASP.NET Core app",
+    "Plan a zero-downtime schema migration strategy for our Rails app",
+    "Write an Exposed DSL query in our Ktor service to list users"
+  ]
+}

package/skills/jpa-hibernate/references/mapping.md

@@ -0,0 +1,99 @@
+# JPA mapping examples
+
+Jakarta Persistence 3.x / Hibernate 6. Adjust imports to `javax.persistence` on Hibernate 5.
+
+## Parent with owned children
+
+```java
+@Entity
+@Table(name = "orders")
+public class Order {
+    @Id
+    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "orders_seq")
+    @SequenceGenerator(name = "orders_seq", sequenceName = "orders_seq", allocationSize = 50)
+    private Long id;
+
+    @Version
+    private long version;
+
+    @Enumerated(EnumType.STRING)
+    @Column(nullable = false, length = 20)
+    private OrderStatus status;
+
+    @Column(nullable = false, precision = 19, scale = 2)
+    private BigDecimal total;
+
+    @ManyToOne(fetch = FetchType.LAZY, optional = false)
+    @JoinColumn(name = "customer_id", nullable = false)
+    private Customer customer;
+
+    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
+    private Set<OrderLine> lines = new HashSet<>();
+
+    protected Order() {}
+
+    public void addLine(OrderLine line) { lines.add(line); line.setOrder(this); }
+    public void removeLine(OrderLine line) { lines.remove(line); line.setOrder(null); }
+
+    @Override public boolean equals(Object o) {
+        if (this == o) return true;
+        if (!(o instanceof Order other)) return false;
+        return id != null && id.equals(other.id);
+    }
+    @Override public int hashCode() { return getClass().hashCode(); }
+}
+```
+
+`allocationSize` must match the sequence's `INCREMENT BY` in the migration, or ids collide or Hibernate fails validation.
+
+## Matching Flyway migration
+
+```sql
+-- V3__create_orders.sql
+create sequence orders_seq start with 1 increment by 50;
+
+create table orders (
+    id          bigint primary key,
+    version     bigint not null default 0,
+    status      varchar(20) not null,
+    total       numeric(19, 2) not null,
+    customer_id bigint not null references customers (id)
+);
+create index idx_orders_customer_id on orders (customer_id);
+```
+
+## Spring Data: entity graph and projection
+
+```java
+public interface OrderRepository extends JpaRepository<Order, Long> {
+
+    @EntityGraph(attributePaths = {"customer", "lines"})
+    Optional<Order> findWithLinesById(Long id);
+
+    @Query("select new com.acme.orders.OrderRow(o.id, c.name, o.total) " +
+           "from Order o join o.customer c where o.status = :status")
+    Page<OrderRow> findRows(@Param("status") OrderStatus status, Pageable pageable);
+}
+```
+
+## Paging a collection fetch without in-memory paging
+
+```java
+List<Long> ids = em.createQuery(
+        "select o.id from Order o where o.status = :status order by o.id", Long.class)
+    .setParameter("status", status)
+    .setFirstResult(page * size)
+    .setMaxResults(size)
+    .getResultList();
+
+List<Order> orders = em.createQuery(
+        "select distinct o from Order o join fetch o.lines where o.id in :ids order by o.id", Order.class)
+    .setParameter("ids", ids)
+    .getResultList();
+```
+
+## Kotlin notes
+
+- Apply the `kotlin("plugin.jpa")` (no-arg) and `kotlin("plugin.allopen")` plugins, with `allOpen { annotation("jakarta.persistence.Entity") }` so lazy proxies work.
+- Use a regular `class` with `var` properties, not a `data class`.
+- Collections: `val lines: MutableSet<OrderLine> = mutableSetOf()`.

package/skills/kotlin-multiplatform/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: kotlin-multiplatform
+description: Sets up and evolves Kotlin Multiplatform (KMP) and Compose Multiplatform projects, covering the shared module and source-set layout (commonMain, androidMain, iosMain), expect/actual versus interfaces with injected platform implementations, choosing multiplatform-ready libraries, exporting a framework to Xcode, exposing suspend functions and Flows to Swift, and Gradle build setup for Android and iOS targets. Use when starting or restructuring a KMP shared module, deciding what code to share between Android and iOS, adding a platform-specific API behind expect/actual, wiring the shared framework into an Xcode project, or sharing UI with Compose Multiplatform.
+license: MIT
+compatibility: Any Agent Skills host. Needs a JDK and the Gradle wrapper; building iOS targets needs macOS with Xcode.
+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"
+---
+
+# Kotlin Multiplatform
+
+Share the code that is the same on every platform, keep platform code behind a small seam, and keep the iOS side pleasant to call from Swift. Single-platform Kotlin idioms belong to `kotlin-patterns`; Android-only Compose UI belongs to `jetpack-compose-patterns`; native iOS UI belongs to `swiftui-patterns`.
+
+## 0. Before you change anything
+
+1. Read `settings.gradle.kts`, the shared module's `build.gradle.kts` and `gradle/libs.versions.toml`: Kotlin version, targets declared in `kotlin { }`, Android plugin in use, and whether Compose Multiplatform (`org.jetbrains.compose`) is applied.
+2. Find how iOS consumes the shared code: a framework built by an Xcode run-script phase (`embedAndSignAppleFrameworkForXcode`), CocoaPods (`kotlin("native.cocoapods")`), or Swift Package Manager via an XCFramework.
+3. Run `./gradlew build` (or `:shared:allTests`) once and record the result. On a machine without Xcode, iOS tasks will be skipped or fail; say so in your report.
+
+## 1. What to share
+
+Decision rule:
+
+1. **Share**: domain models, business rules, validation, networking (Ktor client), persistence (SQLDelight, Room KMP), serialization (`kotlinx.serialization`), repositories and ViewModel-level presentation logic.
+2. **Share UI with Compose Multiplatform** only when the team accepts a non-native-looking iOS UI or has designed for it. Compose Multiplatform for iOS has been stable since 1.8.0.
+3. **Keep native**: platform UI the user expects (iOS system navigation, widgets, extensions), and anything that needs deep platform APIs.
+
+**Stop and ask the user** before moving existing native UI into Compose Multiplatform or moving a large existing module into shared code.
+
+## 2. Module and source-set structure
+
+```
+shared/
+  src/commonMain/kotlin/     # pure Kotlin, multiplatform libraries only
+  src/commonTest/kotlin/     # kotlin.test tests that run on every target
+  src/androidMain/kotlin/    # Android actuals, Android SDK allowed
+  src/iosMain/kotlin/        # shared by iosArm64 + iosSimulatorArm64 (+ iosX64)
+```
+
+- Rely on the default hierarchy template: declaring `iosArm64()` and `iosSimulatorArm64()` gives you an `iosMain` source set automatically. Don't hand-wire `dependsOn` unless the project already does.
+- `commonMain` must never import `android.*`, `java.*` or `platform.*`. If it needs one, that's a seam (section 3).
+- For larger apps, split by feature (`:shared:feature-auth`, `:shared:core-network`) and export only an umbrella module to iOS, because each exported framework carries its own copy of the Kotlin runtime.
+- Android: new KMP library modules use the Android-KMP library plugin (`com.android.kotlin.multiplatform.library`). Configure the Android target inside `kotlin { }` with `android { namespace = ...; compileSdk = ...; minSdk = ... }` on AGP 8.12+, or `androidLibrary { }` on older AGP (`androidLibrary` is deprecated in newer AGP). Applying `com.android.library` to a KMP module relies on AGP APIs that need an opt-in from AGP 9.0 and are planned for removal in AGP 10; migrate only when the user agrees.
+
+## 3. expect/actual vs interfaces
+
+Prefer, in this order:
+
+1. **A multiplatform library** that already wraps the API (Ktor, `kotlinx-datetime`, `multiplatform-settings`, Okio).
+2. **An interface in `commonMain`** implemented per platform and injected (Koin or constructor injection). Best for anything stateful or that needs mocking in tests; iOS implementations can even be written in Swift and passed in.
+3. **`expect fun` / `expect val`** for small, stateless platform facts (`expect fun platformName(): String`, a UUID or clock).
+4. **`expect class`** last. expect/actual classes are still Beta and need the compiler opt-in the build reports when you use them.
+
+Every `expect` needs an `actual` in each target's source set (or an intermediate set like `iosMain`). Keep actuals thin: translate and delegate, no business logic.
+
+## 4. Platform dependencies
+
+- Put each dependency in the narrowest source set: `commonMain.dependencies { }` for multiplatform libraries, `androidMain.dependencies { }` / `iosMain.dependencies { }` for platform engines (for example `ktor-client-okhttp` vs `ktor-client-darwin`).
+- Before adding a library to `commonMain`, check its published targets include every target you declare (look for iOS artifacts on Maven Central or klibs.io).
+- Use the version catalog; don't hard-code versions in build scripts.
+- Calling Apple frameworks from Kotlin goes through the `platform.*` cinterop bindings in `iosMain`; CocoaPods or custom cinterop are only for third-party native libraries.
+
+## 5. iOS interop
+
+- Configure the framework once:
+
+  ```kotlin
+  listOf(iosArm64(), iosSimulatorArm64()).forEach {
+      it.binaries.framework { baseName = "Shared"; isStatic = true }
+  }
+  ```
+- Kotlin `suspend` functions appear in Swift as async functions or completion handlers, and Flows arrive as plain objects that are awkward to collect. For a Swift-friendly API, use SKIE or KMP-NativeCoroutines if the project allows a plugin; otherwise expose a small callback wrapper (`fun watch(onEach: (T) -> Unit): Closeable`).
+- Sealed classes and enums lose exhaustiveness in Swift without such tooling. Keep the Swift-facing API small and explicit: one facade per feature.
+- Kotlin exceptions crossing into Swift crash unless declared with `@Throws`. Annotate every public suspend or throwing function exported to iOS, or return a result type.
+- Keep all shared code that touches UI-observable state on the main dispatcher when called from Swift.
+- After a shared-code change, rebuild the iOS app from Xcode (or `xcodebuild`) to prove the framework links.
+
+## 6. Build setup and checks
+
+- Use the same Kotlin version for the Kotlin, Compose compiler and serialization plugins; mismatches are the most common build failure.
+- Common tests go in `commonTest` with `kotlin.test`; run `./gradlew :shared:allTests` (or the project's task) so they run on JVM/Android and iOS simulator.
+- Commit `gradle/libs.versions.toml`, the Gradle wrapper and the Xcode project changes together.
+
+## Never
+
+- Never import a platform package from `commonMain`.
+- Never put business logic in an `actual`.
+- Never export every Gradle module to iOS as its own framework.
+- Never let an undeclared exception cross the Kotlin/Swift boundary.
+
+## Report back
+
+End with: modules and source sets changed, each new expect/actual or injected interface, Gradle tasks run (and whether iOS targets actually built on this machine), and anything the iOS team must change in Xcode.

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

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Set up a KMP shared module so our Android and iOS apps share the networking layer",
+    "How do I use expect/actual to read the device UUID on iOS and Android?",
+    "Swift can't collect the Flow exported from our Kotlin Multiplatform framework",
+    "Should we share the UI with Compose Multiplatform or keep SwiftUI on iOS?",
+    "commonMain keeps failing because it imports java.time, how should I restructure this?"
+  ],
+  "should_not_trigger": [
+    "Write a Kotlin data class with a sealed result type for this Android repository",
+    "Add a Jetpack Compose bottom sheet to the Android settings screen",
+    "Build a SwiftUI onboarding flow with a NavigationStack",
+    "Fix the Gradle error: Could not resolve com.squareup.okhttp3 in the Android app",
+    "Share business logic between iOS and Android using a Flutter plugin"
+  ]
+}