@ketecode/loom 0.0.0-stage → 0.2.0

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/jvm-sql-mappers/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: jvm-sql-mappers
+description: Writes and reviews SQL-first data access on the JVM without an ORM session, using MyBatis XML or annotation mappers with dynamic SQL and resultMaps, jOOQ's generated typesafe DSL, or Kotlin Exposed DSL and DAO tables, plus explicit transaction boundaries, HikariCP pool sizing, JDBC batch inserts and loading child rows without one query per parent. Use when a Java or Kotlin service uses MyBatis, jOOQ or Exposed rather than JPA, a mapper or query builder produces the wrong or slow SQL, ${} string substitution needs auditing for injection, bulk inserts are slow, or the connection pool times out under load.
+license: MIT
+compatibility: Any Agent Skills host. Needs the project's JDK build tool (Gradle or Maven) and its test runner; integration tests need the target database, ideally through Testcontainers.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# JVM SQL mappers: MyBatis, jOOQ, Exposed
+
+You write the SQL (or a typed DSL of it) and the library maps rows to objects. No lazy loading and no dirty checking: what you query is what runs. For JPA or Hibernate entities use the JPA skill instead.
+
+## 0. Before you start
+
+1. Identify the library and version from the build file (`org.mybatis`, `mybatis-spring-boot-starter`, `org.jooq`, `org.jetbrains.exposed`) and the database and driver.
+2. Exposed 1.0 moved packages to `org.jetbrains.exposed.v1.*` (core, jdbc, r2dbc, dao). Check which the project imports and follow the docs for that major version.
+3. Find how transactions are managed: Spring `@Transactional`, jOOQ `transaction { }`, Exposed `transaction { }`, or manual `SqlSession`.
+4. Run the existing tests once. Turn on SQL logging (MyBatis `logImpl`, jOOQ `executeLogging`, Exposed `addLogger(StdOutSqlLogger)`) while you work so you see the real statements.
+
+Read `references/examples.md` for complete mapper, DSL and batching snippets.
+
+## 1. Rules for every library
+
+1. **Bind every value.** Values go in as bind parameters: MyBatis `#{param}`, jOOQ `DSL.val`/typed conditions, Exposed column comparisons. Never build SQL by string concatenation.
+2. **Identifiers that must be dynamic** (sort column, table suffix) come from an allow-list in code, never from the request. This is the only acceptable use of MyBatis `${}` or jOOQ `DSL.field(name(...))` from input.
+3. **Select only the columns you use.** No `select *` in mappers; it breaks when columns are added and wastes I/O.
+4. **One transaction per unit of work**, started at the service layer, short, and never open across a remote call or user think time.
+5. **Paginate** with keyset (`WHERE id > :last ORDER BY id LIMIT :n`) for large or deep lists; `OFFSET` only for small pages.
+6. **Schema changes** go through migrations (Flyway or Liquibase), never `SchemaUtils.create` or `ddl` at app start in production.
+
+## 2. MyBatis
+
+- Put SQL in mapper XML (namespace = mapper interface) or annotations for one-liners. Map with explicit `<resultMap>`; turn on `mapUnderscoreToCamelCase` only if the project already relies on it.
+- Dynamic SQL: `<where>` (drops leading AND/OR), `<if test>`, `<choose>/<when>/<otherwise>`, `<set>` for partial updates, `<foreach>` for `IN` lists. An empty list in `<foreach>` produces `IN ()`: guard it with `<if test="ids != null and !ids.isEmpty()">` or return early in code.
+- Audit every `${}`: each one must be an allow-listed identifier. Replace any other with `#{}`.
+- Avoid N+1: a nested `<collection select="...">` runs one query per parent. Prefer a join with a nested `<collection>` resultMap (with `<id>` columns so rows collapse correctly), or load children in a second query with `IN (...)` and group in code.
+- Batching: open the session with `ExecutorType.BATCH` (or a separate batch `SqlSessionTemplate` in Spring), call the insert in a loop, `flushStatements()` every 500 to 1000 rows, commit once. A multi-row `<foreach>` `INSERT ... VALUES` works for moderate sizes but hits parameter limits on large ones.
+- Generated keys: `useGeneratedKeys="true" keyProperty="id"`.
+
+## 3. jOOQ
+
+- Generate code from the real schema (the jOOQ codegen plugin against a migrated database, or from Flyway scripts via the DDL database) and commit the config, not hand-written table classes.
+- Use one `DSLContext` configured with the pool's `DataSource` and the correct `SQLDialect`.
+- Fetch into records or projections: `fetchInto(Dto.class)`, `fetch(Records.mapping(Dto::new))`.
+- Nested children without N+1: `multiset(select(...).from(CHILD).where(CHILD.PARENT_ID.eq(PARENT.ID)))` mapped with `convertFrom`, or a join plus `fetchGroups`.
+- Transactions: `dsl.transaction(cfg -> { DSL.using(cfg)... })`, or Spring's transaction manager if jOOQ is wired with Spring Boot's starter. Do not mix both styles in one call path.
+- Batching: `dsl.batchInsert(records)` or `dsl.batch(query).bind(...).bind(...).execute()`; for very large loads, the Loader API (`loadInto`).
+- Plain SQL templates (`DSL.field("...")`) are an escape hatch; pass values as `{0}` bind arguments, never concatenated.
+
+## 4. Kotlin Exposed
+
+- DSL: `object Users : LongIdTable("users") { val email = varchar("email", 255).uniqueIndex() }`; query with `Users.selectAll().where { Users.email eq e }`.
+- DAO: `class User(id: EntityID<Long>) : LongEntity(id) { companion object : LongEntityClass<User>(Users) }`. DAO references are lazy: load children eagerly with `.with(User::orders)` or `load(...)` to avoid N+1.
+- Every query runs inside `transaction(db) { }`. With coroutines on JDBC, use `suspendTransaction { }` on Exposed 1.x (`newSuspendedTransaction` on 0.x, deprecated in 1.0). It takes no `CoroutineContext`, so call it inside `withContext(Dispatchers.IO) { }`; blocking JDBC must not run on `Dispatchers.Default` or the main thread. For non-blocking drivers use the `exposed-r2dbc` module.
+- Batching: `Users.batchInsert(rows) { row -> this[Users.email] = row.email }`.
+- For any of the three libraries, JDBC batches only become multi-row inserts if the driver rewrites them: add `rewriteBatchedStatements=true` to a MySQL Connector/J URL, `reWriteBatchedInserts=true` to a PostgreSQL (pgjdbc) URL.
+- Spring: use the Exposed Spring starter's transaction manager so `@Transactional` and `transaction {}` share a connection.
+
+## 5. HikariCP
+
+- Start small: `maximumPoolSize` about 10 per instance (the default) and raise it only with evidence. Total connections across all instances must stay under the database's limit minus admin headroom.
+- Set `maxLifetime` (default 30 min) a little shorter than any database, proxy or firewall connection cutoff. `keepaliveTime` (default 2 min in current releases, minimum 30 s) must be shorter than any idle cutoff; lower it only if a firewall drops idle connections sooner.
+- `connectionTimeout` (default 30 s) is how long a caller waits for a connection. Timeouts under load usually mean long transactions or leaked connections, not a small pool: set `leakDetectionThreshold` (off by default, minimum 2000 ms; for example 60000 ms) in staging to find the leak.
+- Defaults above are from the current HikariCP README; earlier releases had `keepaliveTime` off (0) by default, so check the version in use.
+
+## 6. Verify
+
+1. Integration tests run against the same database engine (Testcontainers), not H2 standing in for PostgreSQL or MySQL.
+2. For each changed query, log the generated SQL and run `EXPLAIN` on it with realistic data; confirm it uses the intended index.
+3. For N+1 fixes, assert the statement count in a test (a counting `DataSource` proxy or the library's listener), not just the result.
+4. For batching, time a load of 10,000 rows before and after.
+5. Run the full test suite.
+
+## Stop and ask the user
+
+- A dynamic identifier cannot be allow-listed because callers pass arbitrary column names.
+- A fix needs a schema change or a new index on a large production table.
+- Switching libraries (for example MyBatis to jOOQ) or major versions.
+
+## Never
+
+- Never use `${}` or string concatenation with request data.
+- Never hold a transaction or connection open across an HTTP call or message wait.
+- Never raise the pool size to hide a connection leak.
+
+## Report back
+
+```
+Library / DB: <MyBatis|jOOQ|Exposed version>, <database>
+Changed queries: <mapper or method> | <problem> | <fix> | <statements before/after>
+Injection audit: <each ${} or plain-SQL use and its status>
+Pool: <settings changed and why>
+Tests: <command> -> <result>; EXPLAIN checked for: <queries>
+```

package/skills/jvm-sql-mappers/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Our MyBatis mapper uses ${orderBy} from the request, make it injection-safe",
+    "The MyBatis nested collection select runs one query per order, fix the N+1",
+    "Load orders with their line items in one jOOQ query using multiset",
+    "Bulk inserting 50k rows with Kotlin Exposed takes minutes, speed it up with batchInsert",
+    "HikariCP 'Connection is not available, request timed out after 30000ms' under load in our jOOQ service"
+  ],
+  "should_not_trigger": [
+    "Fix LazyInitializationException on a Hibernate @OneToMany association",
+    "Our Postgres query is slow, read this EXPLAIN ANALYZE output",
+    "Add a Flyway migration for a new column in our Spring Data JPA entity",
+    "Write a Ktor route that returns JSON with kotlinx.serialization",
+    "Fix N+1 queries in our EF Core DbContext with Include"
+  ]
+}

package/skills/jvm-sql-mappers/references/examples.md

@@ -0,0 +1,129 @@
+# Examples: MyBatis, jOOQ, Exposed
+
+Each snippet shows one pattern from SKILL.md. Adapt names to the project; check the API against the docs for the library version in use.
+
+## MyBatis: dynamic search with a safe sort column
+
+```xml
+<mapper namespace="com.example.order.OrderMapper">
+  <resultMap id="orderWithLines" type="com.example.order.Order">
+    <id property="id" column="o_id"/>
+    <result property="status" column="o_status"/>
+    <collection property="lines" ofType="com.example.order.OrderLine">
+      <id property="id" column="l_id"/>
+      <result property="sku" column="l_sku"/>
+      <result property="quantity" column="l_qty"/>
+    </collection>
+  </resultMap>
+
+  <select id="search" resultMap="orderWithLines">
+    SELECT o.id o_id, o.status o_status, l.id l_id, l.sku l_sku, l.quantity l_qty
+    FROM orders o LEFT JOIN order_lines l ON l.order_id = o.id
+    <where>
+      <if test="status != null">AND o.status = #{status}</if>
+      <if test="customerIds != null and !customerIds.isEmpty()">
+        AND o.customer_id IN
+        <foreach item="cid" collection="customerIds" open="(" separator="," close=")">#{cid}</foreach>
+      </if>
+    </where>
+    ORDER BY ${sortColumn}, o.id
+  </select>
+</mapper>
+```
+
+```java
+// The only ${} input: chosen from a fixed map, never from the raw request.
+private static final Map<String, String> SORTS = Map.of("created", "o.created_at", "total", "o.total");
+String sortColumn = SORTS.getOrDefault(request.sort(), "o.created_at");
+```
+
+Joins with collections multiply rows; paginate parents first (select the page of order ids, then join lines for those ids).
+
+## MyBatis: batch insert
+
+```java
+try (SqlSession session = sqlSessionFactory.openSession(ExecutorType.BATCH)) {
+    OrderLineMapper mapper = session.getMapper(OrderLineMapper.class);
+    int n = 0;
+    for (OrderLine line : lines) {
+        mapper.insert(line);
+        if (++n % 500 == 0) session.flushStatements();
+    }
+    session.commit();
+}
+```
+
+In Spring, define a second `SqlSessionTemplate` with `ExecutorType.BATCH` and use it inside the service's `@Transactional` method.
+
+## jOOQ: parent with children in one query
+
+```java
+List<OrderDto> orders = dsl
+    .select(
+        ORDERS.ID, ORDERS.STATUS,
+        multiset(
+            select(ORDER_LINES.SKU, ORDER_LINES.QUANTITY)
+                .from(ORDER_LINES)
+                .where(ORDER_LINES.ORDER_ID.eq(ORDERS.ID))
+        ).convertFrom(r -> r.map(Records.mapping(LineDto::new))))
+    .from(ORDERS)
+    .where(ORDERS.CUSTOMER_ID.eq(customerId))
+    .orderBy(ORDERS.ID)
+    .limit(50)
+    .fetch(Records.mapping(OrderDto::new));
+```
+
+## jOOQ: transaction and batch
+
+```java
+dsl.transaction(cfg -> {
+    DSLContext tx = DSL.using(cfg);
+    tx.batchInsert(lineRecords).execute();
+    tx.update(ORDERS).set(ORDERS.STATUS, "READY").where(ORDERS.ID.eq(orderId)).execute();
+});
+```
+
+## Exposed: DSL query, eager DAO load, batch insert (1.x packages)
+
+```kotlin
+import org.jetbrains.exposed.v1.core.and
+import org.jetbrains.exposed.v1.core.dao.id.LongIdTable
+import org.jetbrains.exposed.v1.core.eq
+import org.jetbrains.exposed.v1.jdbc.transactions.transaction
+import org.jetbrains.exposed.v1.jdbc.batchInsert
+import org.jetbrains.exposed.v1.jdbc.selectAll
+
+object Orders : LongIdTable("orders") {
+    val customerId = long("customer_id").index()
+    val status = varchar("status", 20)
+}
+
+fun openOrders(customer: Long) = transaction {
+    Orders.selectAll()
+        .where { (Orders.customerId eq customer) and (Orders.status eq "OPEN") }
+        .map { it[Orders.id].value to it[Orders.status] }
+}
+
+fun saveLines(lines: List<LineInput>) = transaction {
+    OrderLines.batchInsert(lines) { line ->
+        this[OrderLines.orderId] = line.orderId
+        this[OrderLines.sku] = line.sku
+    }
+}
+```
+
+DAO eager loading: `Order.find { Orders.customerId eq id }.with(Order::lines)`.
+
+Import paths above follow the Exposed 1.0 migration guide (core table types under `v1.core`, JDBC operations under `v1.jdbc`); confirm each import in the docs for the exact version, and use the 0.x `org.jetbrains.exposed.sql.*` packages if the project has not migrated.
+
+## HikariCP (Spring Boot properties)
+
+```properties
+spring.datasource.hikari.maximum-pool-size=10
+spring.datasource.hikari.connection-timeout=30000
+spring.datasource.hikari.max-lifetime=1500000
+spring.datasource.hikari.keepalive-time=300000
+spring.datasource.hikari.leak-detection-threshold=60000
+```
+
+`max-lifetime` here assumes an infrastructure idle cutoff above 25 minutes; set it below whatever your database or proxy enforces. Leak detection is for staging and diagnosis; it logs a stack trace for connections held longer than the threshold.

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

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