@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/java-patterns/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: java-patterns
+description: Idiomatic modern Java (17 and 21 LTS and later) for writing and restructuring code with records, sealed interfaces, switch pattern matching, Optional, streams, checked versus unchecked exceptions, immutable collections, virtual threads and a standard Maven or Gradle layout. Use when writing new Java classes, modernising pre-17 Java code, choosing between a record, enum or sealed hierarchy, or deciding how to run blocking work concurrently on the JVM.
+license: MIT
+compatibility: Any Agent Skills host. Needs a JDK 17 or newer and the project's Maven or Gradle build.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/requires: "java"
+  kete-loom/owner: "Kete-org"
+---
+
+# Modern Java patterns
+
+Write Java that the compiler checks for you: model data with types, make illegal states unrepresentable, and keep mutation local.
+
+## 0. Before you write
+
+1. Find the language level the build actually uses: `maven.compiler.release` or `<release>` in `pom.xml`, or `java { toolchain { languageVersion = ... } }` / `options.release` in `build.gradle(.kts)`. Use only features that level allows. Never raise it without asking the user.
+2. Match the codebase: if it already uses Lombok, Vavr, Guava or a null-annotation library (JSpecify, JetBrains, Checker Framework), follow that convention rather than mixing styles.
+3. Feature floor, by release: records (16), sealed classes (17), pattern matching for `switch` and record patterns (21), virtual threads (21), unnamed variables `_` (22), scoped values (25). Preview features need `--enable-preview`; don't introduce them unless the project already does.
+
+## 1. Model data
+
+| Need | Use |
+|---|---|
+| Immutable value with fields, equality by value | `record` |
+| Fixed set of constants | `enum` |
+| One of several shapes with different data | `sealed interface` + `record` implementations |
+| Mutable entity with identity (JPA entity, builder state) | ordinary class |
+
+- Validate in the record's compact constructor and copy mutable inputs: `this.items = List.copyOf(items);`.
+- A record's `equals`, `hashCode` and `toString` are generated. If a record holds an array, they compare by reference; prefer a `List`.
+- Don't use records for JPA entities: they need a no-arg constructor, mutability and proxying.
+- Keep sealed hierarchies in one package (or one module) and list `permits` only when the subtypes live in other files.
+
+```java
+sealed interface Payment permits Card, MobileMoney, Cash {}
+record Card(String last4, Money amount) implements Payment {}
+record MobileMoney(String msisdn, Money amount) implements Payment {}
+record Cash(Money amount) implements Payment {}
+
+String describe(Payment p) {
+    return switch (p) {                      // exhaustive: no default needed
+        case Card c -> "card ending " + c.last4();
+        case MobileMoney(var msisdn, var amt) -> "MoMo " + msisdn;
+        case Cash cash -> "cash";
+    };
+}
+```
+
+Leave `default` out of a switch over a sealed type, so adding a subtype becomes a compile error at every switch that must handle it.
+
+## 2. Null and Optional
+
+1. Return `Optional<T>` from methods where "no result" is a normal outcome (lookups). Never return `null` from a method declared to return `Optional`.
+2. Don't use `Optional` for fields, parameters or collection elements. Return an empty collection, never `null`.
+3. Consume with `map`, `filter`, `orElse`, `orElseGet` (when the default is expensive), `orElseThrow`. Avoid `isPresent()` + `get()`.
+4. Check arguments at public boundaries: `Objects.requireNonNull(x, "x")`.
+5. `Map.get` returns `null` for missing keys; use `getOrDefault`, `computeIfAbsent` or `containsKey` deliberately.
+
+## 3. Collections and streams
+
+- Prefer `List.of`, `Set.of`, `Map.of` and `List.copyOf` for immutable results. They reject `null` elements and throw on mutation.
+- `stream().toList()` (16+) returns an unmodifiable list; `Collectors.toList()` makes no such promise. Pick deliberately when callers mutate the result.
+- Use a stream when the pipeline reads clearly (filter, map, collect). Use a loop when you need early exit with side effects, checked exceptions, or index arithmetic.
+- Never mutate shared state from inside `map` or `forEach` in a stream. Collect instead.
+- `Collectors.toMap` throws on duplicate keys; pass a merge function when duplicates are possible.
+- Don't add `.parallel()` without measuring; it runs on the common ForkJoinPool and rarely helps I/O-bound work.
+
+## 4. Exceptions
+
+1. Throw unchecked exceptions for programming errors and for failures callers can't reasonably recover from. Use checked exceptions only when the caller must handle the case.
+2. Never swallow: an empty `catch`, or `catch (Exception e) { log.error(e.getMessage()); }`, hides the stack trace. Log the exception object, or rethrow wrapped with the cause: `throw new OrderException("charge failed for " + id, e);`.
+3. Catch the narrowest type. Don't catch `Throwable` or `Error`.
+4. Use try-with-resources for anything `AutoCloseable` (streams, JDBC connections, `ExecutorService` on 19+).
+5. On `InterruptedException`, restore the flag (`Thread.currentThread().interrupt()`) before rethrowing or returning.
+
+## 5. Immutability and equality
+
+- Make fields `final` by default. Expose no setters unless a framework needs them.
+- If you override `equals`, override `hashCode` with the same fields. Never use mutable fields in either for objects stored in a `HashSet` or as `HashMap` keys.
+- Compare strings and boxed numbers with `equals`, never `==`. Compare `BigDecimal` values with `compareTo`, because `equals` also compares scale.
+- Use `BigDecimal` (or integer minor units) for money, never `double`.
+
+## 6. Concurrency
+
+Choose by workload:
+
+| Workload | Use |
+|---|---|
+| Many blocking tasks (HTTP calls, JDBC, file I/O) on 21+ | virtual threads: `Executors.newVirtualThreadPerTaskExecutor()` |
+| CPU-bound work | a fixed pool sized near `Runtime.getRuntime().availableProcessors()` |
+| Composing async results | `CompletableFuture` with an explicit executor |
+| Shared counters / maps | `AtomicLong`, `LongAdder`, `ConcurrentHashMap` |
+
+```java
+try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+    List<Future<Quote>> futures = suppliers.stream()
+        .map(s -> executor.submit(() -> s.fetchQuote(order)))
+        .toList();
+    // close() waits for all tasks
+}
+```
+
+Virtual thread rules:
+
+1. Create one per task; never pool them.
+2. Limit access to scarce resources (database connections, rate-limited APIs) with a `Semaphore`, not by shrinking a pool.
+3. Avoid large `ThreadLocal` caches; with millions of threads they multiply memory.
+4. On JDK 21 to 23, blocking inside `synchronized` pins the carrier thread; use `ReentrantLock` around blocking calls. JDK 24+ removed most of that pinning (JEP 491).
+5. Virtual threads don't make CPU-bound code faster.
+
+General rules: guard every piece of shared mutable state with one lock or make it immutable; never call `Thread.stop`; never block inside a `CompletableFuture` callback on the common pool; give threads and executors names for diagnostics.
+
+## 7. Build layout
+
+- Maven and Gradle share the layout: `src/main/java`, `src/main/resources`, `src/test/java`, `src/test/resources`. Packages follow reversed domain names (`com.example.orders`).
+- Use the wrapper the repo ships (`./mvnw`, `./gradlew`), never a globally installed version.
+- Set the language level with `release` (Maven `maven.compiler.release`, Gradle toolchains) rather than `source`/`target`, so the compiler also checks the JDK API level.
+- Pin dependency versions in one place: Maven `<dependencyManagement>` or a BOM; Gradle version catalogs (`gradle/libs.versions.toml`) or platforms.
+- Common commands: `./mvnw -q verify`, `./gradlew build`, `./mvnw dependency:tree`, `./gradlew dependencies --configuration runtimeClasspath`.
+
+## Never
+
+- Return `null` for a collection or an `Optional`.
+- Use raw types (`List` instead of `List<String>`).
+- Catch an exception just to log and continue as if it succeeded.
+- Add a dependency for something the JDK already does (`java.net.http.HttpClient`, `java.time`, `HexFormat`).
+- Use `java.util.Date` or `Calendar` in new code; use `java.time` (`Instant`, `LocalDate`, `ZonedDateTime`).
+
+## Stop and ask the user
+
+- Before raising the Java release level, adding Lombok, or enabling preview features.
+- Before changing a public API's signature that other modules or services call.
+- When moving existing thread-pool code to virtual threads in a service that holds locks or `ThreadLocal` state you can't fully trace.
+
+## Finish
+
+Compile and run the tests with the project's build command. Report what changed, the Java level you targeted, and anything you left on an older pattern on purpose.

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

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Convert these Java DTO classes to records and use a sealed interface for the payment types",
+    "What's the idiomatic way to handle a lookup that may return nothing in Java 21, Optional or null?",
+    "Our Spring service makes 200 blocking HTTP calls per request, should I use virtual threads?",
+    "Modernise this Java 8 code to Java 17: switch expressions, streams, immutable collections",
+    "Should this Java hierarchy be an enum, a record or a sealed interface?"
+  ],
+  "should_not_trigger": [
+    "Write JUnit 5 tests with Mockito for the OrderService class",
+    "Maven fails with 'package javax.annotation does not exist' after upgrading to JDK 21, fix the build",
+    "Review my Java pull request for resource leaks and equals/hashCode bugs",
+    "Convert this Java data class to an idiomatic Kotlin data class",
+    "Set up Spring Boot auto-configuration and a REST controller for orders",
+    "Map this JPA entity with a lazy OneToMany and fix the N+1 queries in the order list"
+  ]
+}

package/skills/java-testing/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: java-testing
+description: Writes and repairs JVM tests in Java with JUnit Jupiter, AssertJ assertions, Mockito mocks, parameterized cases, Testcontainers-backed integration tests and Spring Boot test slices, and tracks down flaky tests. Use when adding unit or integration tests to a Java project, choosing between a mock and a real database container, speeding up a slow Java test suite, or diagnosing a JUnit test that passes locally and fails in CI.
+license: MIT
+compatibility: Any Agent Skills host. Needs a JDK and the project's Maven or Gradle build; Testcontainers needs a running Docker-compatible engine.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "java"
+  kete-loom/owner: "Kete-org"
+---
+
+# Java testing
+
+Tests that state behaviour, fail for one reason, and run the same way on every machine.
+
+## 0. Before you start
+
+1. Find the test stack in the build file: `junit-jupiter` (JUnit 5, or JUnit 6 which needs Java 17+), `junit:junit` (JUnit 4), `assertj-core`, `mockito-core` / `mockito-junit-jupiter`, `org.testcontainers`, `spring-boot-starter-test`. Use what is there; don't add a second assertion or mocking library.
+2. Find how tests run: `./mvnw test` (Surefire, unit), `./mvnw verify` (Failsafe, `*IT` classes), `./gradlew test`. Run one class with `./mvnw test -Dtest=OrderServiceTest` or `./gradlew test --tests 'com.example.OrderServiceTest'`.
+3. Run the suite once and record the result. If it already fails, stop and tell the user which tests fail before you change anything.
+
+## 1. Pick the test level
+
+| What you're testing | Level | Tools |
+|---|---|---|
+| Pure logic, value objects, mappers | unit | JUnit + AssertJ, no mocks |
+| A class with collaborators you own | unit | Mockito for the collaborators at the boundary |
+| SQL, migrations, repository queries | integration | Testcontainers with the real database engine |
+| HTTP layer only (Spring) | slice | `@WebMvcTest` + `MockMvc` |
+| JPA repositories only (Spring) | slice | `@DataJpaTest` + Testcontainers |
+| Whole service wiring | integration | `@SpringBootTest`, used sparingly |
+
+Rules: don't mock what you don't own (wrap the third-party client and mock the wrapper, or use a fake server); don't mock value objects or records; don't test a database with H2 when production runs PostgreSQL or MySQL, because dialect differences hide bugs.
+
+## 2. Write the test
+
+```java
+class PriceCalculatorTest {
+    private final PriceCalculator calc = new PriceCalculator(new FixedTaxRate("0.15"));
+
+    @Test
+    void appliesTaxToSubtotal() {
+        Money total = calc.total(List.of(item("10.00"), item("5.00")));
+        assertThat(total).isEqualTo(Money.of("17.25"));
+    }
+
+    @ParameterizedTest
+    @CsvSource({"0, 0.00", "1, 1.15", "100, 115.00"})
+    void scalesLinearly(int qty, String expected) {
+        assertThat(calc.total(List.of(item("1.00", qty)))).isEqualTo(Money.of(expected));
+    }
+
+    @Test
+    void rejectsEmptyCart() {
+        assertThatThrownBy(() -> calc.total(List.of()))
+            .isInstanceOf(IllegalArgumentException.class)
+            .hasMessageContaining("empty");
+    }
+}
+```
+
+- One behaviour per test; name it for the behaviour (`rejectsEmptyCart`), or use `@DisplayName`.
+- Arrange, act, assert, in that order, with no logic (loops, ifs) in the test.
+- Prefer AssertJ (`assertThat(list).containsExactly(...)`, `extracting`, `satisfies`) over bare `assertTrue`, so failures print the values.
+- Parameterize instead of copy-pasting: `@ValueSource`, `@CsvSource`, `@MethodSource`, `@EnumSource`.
+- Test classes and methods can be package-private in JUnit Jupiter; don't add `public`.
+
+## 3. Mockito
+
+```java
+@ExtendWith(MockitoExtension.class)
+class CheckoutServiceTest {
+    @Mock PaymentGateway gateway;
+    @InjectMocks CheckoutService service;
+
+    @Test
+    void chargesOnceForOrderTotal() {
+        when(gateway.charge(any())).thenReturn(ChargeResult.ok("ref-1"));
+        service.checkout(order("25.50"));
+        verify(gateway).charge(argThat(c -> c.amount().equals(Money.of("25.50"))));
+        verifyNoMoreInteractions(gateway);
+    }
+}
+```
+
+- `MockitoExtension` uses strict stubs: an unused `when(...)` fails the test. Remove the stub rather than switching to lenient.
+- Stub return values for queries; `verify` only commands (calls whose side effect is the point).
+- Use `ArgumentCaptor` when you need to assert several fields of an argument.
+- Mockito 5 uses the inline mock maker by default, so final classes and records can be mocked; mock them only when there is no simpler real instance.
+- On JDK 21+, Mockito's self-attaching agent prints a dynamic agent loading warning; the fix is to pass the `mockito-core` jar as `-javaagent` in the Surefire `argLine` or Gradle `jvmArgs`. Check Mockito's current docs for the exact snippet.
+
+## 4. Integration tests with Testcontainers
+
+```java
+@Testcontainers
+class OrderRepositoryIT {
+    @Container
+    static PostgreSQLContainer db = new PostgreSQLContainer("postgres:16-alpine");
+    // connect with db.getJdbcUrl(), db.getUsername(), db.getPassword()
+}
+```
+
+- Testcontainers 2.x renamed module artifacts (`org.testcontainers:testcontainers-postgresql`) and moved classes (`org.testcontainers.postgresql.PostgreSQLContainer`, no type parameter); 1.x uses `org.testcontainers:postgresql` and `org.testcontainers.containers.PostgreSQLContainer<?>`. Match the version in the build file.
+- Pin the image tag to the version production runs; never use `latest`.
+- `static` containers start once per class; instance containers restart per test (slow).
+- In Spring Boot 3.1+, annotate the container field with `@ServiceConnection` instead of wiring `@DynamicPropertySource` by hand.
+- With `@DataJpaTest`, if the test still connects to an embedded database, add `@AutoConfigureTestDatabase(replace = Replace.NONE)`.
+- Run the real migrations (Flyway, Liquibase) against the container so schema and code are tested together.
+- Clean data between tests (truncate tables, or a transaction rolled back per test) so order doesn't matter.
+- If Docker isn't available, stop and tell the user; don't fall back to H2 silently.
+
+## 5. Flaky tests
+
+Reproduce first: rerun the single test many times (a `@RepeatedTest(50)` locally, or a loop over the single-test command), then the whole class, then with the CI's JVM flags and parallelism.
+
+| Symptom | Usual cause | Fix |
+|---|---|---|
+| Fails only with other tests | shared static state, leftover DB rows, test order | reset state in `@BeforeEach`; isolate data |
+| Fails on slow CI | `Thread.sleep` waits, fixed timeouts | poll with Awaitility (`await().atMost(...).until(...)`) |
+| Fails near midnight or in other zones | `LocalDate.now()`, default time zone | inject a `java.time.Clock`; use `Clock.fixed` in tests |
+| Fails on assertion order | `HashMap`/`HashSet` iteration | `containsExactlyInAnyOrder`, or sort |
+| Port already in use | hard-coded ports | random ports; Testcontainers mapped ports |
+
+Never fix flakiness by adding retries, raising timeouts blindly, or `@Disabled`. If you can't find the cause, report what you tried and leave the test enabled.
+
+## 6. Coverage and speed
+
+- If the project uses JaCoCo, run its report goal and look at uncovered branches in the code you changed, not the global number.
+- Keep unit tests free of Spring context and containers. Reuse one Spring context across tests by keeping configuration identical; each distinct `@MockBean`/`@MockitoBean` set forces a new context.
+
+## Never
+
+- Delete, skip or weaken an existing test to make the suite pass without the user's agreement.
+- Assert on log output or `toString()` when a real return value or state is available.
+- Use `Thread.sleep` to wait for asynchronous work.
+- Leave `System.out.println` debugging in tests.
+
+## Finish
+
+Run the test command for the classes you touched, then the full suite. Report the tests added or changed, the command and its result, and any flaky test you could not fix.

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

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Write JUnit 5 tests with Mockito for the OrderService class",
+    "Replace H2 with Testcontainers PostgreSQL in our Java repository tests",
+    "This JUnit test passes on my laptop but fails randomly in the CI pipeline, help me find out why",
+    "Turn these five copy-pasted Java test methods into a parameterized test with AssertJ assertions",
+    "Mockito says UnnecessaryStubbingException in my CheckoutServiceTest, what's wrong?"
+  ],
+  "should_not_trigger": [
+    "Convert these Java DTO classes to records and use a sealed interface for the payment types",
+    "Gradle build fails: Could not resolve org.junit.jupiter:junit-jupiter after bumping versions",
+    "Write Playwright end-to-end tests for the checkout page",
+    "Add pytest fixtures and parametrize the tests for the billing module",
+    "Write Kotest specs with MockK for the Kotlin payment service"
+  ]
+}

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.