@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/flutter-patterns/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: flutter-patterns
+description: Flutter app architecture from the widget tree up, covering small const widgets and composition over inheritance, choosing between Riverpod, Bloc and Provider for state, declarative routing with go_router or Navigator, FutureBuilder and StreamBuilder async UI with loading and error states, rebuild and jank performance, and Dart-to-native platform channels or Pigeon. Use when building or restructuring Flutter screens and widgets, picking or applying a state management approach, wiring navigation and deep links, chasing dropped frames, or calling iOS or Android code from a Flutter app.
+license: MIT
+compatibility: Any Agent Skills host. Needs the Flutter SDK (flutter analyze, flutter test); device runs need Xcode for iOS or the Android SDK.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "flutter"
+  kete-loom/owner: "Kete-org"
+---
+
+# Flutter patterns
+
+Build Flutter screens from small widgets, keep state where one decision rule puts it, and keep frames under budget. Plain Dart language features, isolates and package layout belong to `dart-patterns`; widget and golden tests belong to `dart-testing`. To review someone else's Flutter change, use the `flutter-reviewer` agent.
+
+## 0. Before you write
+
+1. Read `pubspec.yaml`: Flutter/Dart SDK constraints, and which of `flutter_riverpod`, `flutter_bloc`, `provider`, `go_router`, `auto_route` are already used.
+2. Read `analysis_options.yaml`. Keep `flutter_lints` (or the project's stricter set) on; `use_build_context_synchronously` catches real async bugs. `prefer_const_constructors` is no longer in `flutter_lints` (removed in 5.0), so enable it explicitly if the team wants const enforced.
+3. Follow the existing folder layout (feature-first `lib/features/<name>/` or layer-first). Don't reorganise unasked.
+4. Run `flutter analyze` and `flutter test` once and record the result.
+
+## 1. Widget composition
+
+- Split a widget when a part rebuilds for different reasons, is reused, or the `build` method passes ~80 lines. Extract a **widget class**, not a helper method returning `Widget`: classes get their own element, can be `const` and rebuild independently.
+- Mark constructors and instances `const` wherever possible; const subtrees are skipped on rebuild.
+- `StatelessWidget` by default. Use `StatefulWidget` only for state owned by this widget: controllers, animation, focus, local form input.
+- Every `TextEditingController`, `AnimationController`, `ScrollController`, `FocusNode`, `StreamSubscription` and `Timer` created in a `State` is disposed or cancelled in `dispose()`. Create them in `initState`, never in `build`.
+- Pass data down through constructors; pass events up through callbacks. Don't reach into a child's state with a `GlobalKey` unless a framework API (forms, navigators) needs it.
+- Keys: use `ValueKey(item.id)` on list items that can reorder, insert or delete, so state follows the item.
+
+## 2. State management
+
+Use what the project already uses. For a new project or a new kind of state, apply this rule:
+
+| State | Put it in |
+|---|---|
+| Ephemeral UI (tab index, expanded, text field) | `State` of the widget |
+| Shared app or server state, new or small-to-mid project | Riverpod (`Notifier` / `AsyncNotifier`, optionally with `riverpod_generator`) |
+| Event-driven flows where the team wants explicit events and transitions | Bloc / Cubit (`flutter_bloc`) |
+| Existing Provider app | Keep `provider` with `ChangeNotifier`; don't mix in a second library |
+
+Rules that apply to all three:
+
+- Keep business logic out of widgets: a notifier, cubit or repository owns it, and is unit-testable without a widget.
+- State objects are immutable values (`copyWith`, or `freezed` if already used); never mutate a list in place and re-emit the same instance.
+- Watch the narrowest thing: `ref.watch(provider.select((s) => s.count))`, `context.select`, or `BlocSelector`, so unrelated changes don't rebuild the screen.
+- Use `ref.read` / `context.read` in callbacks, `watch` only in `build`.
+- Model async state explicitly: loading, data, error (`AsyncValue` in Riverpod, sealed state classes in Bloc).
+
+## 3. Navigation
+
+- Apps with deep links, web, or nested tabs: `go_router` with a single route table, path parameters for IDs, and `redirect` for auth guards.
+- Small apps with no deep links: `Navigator.push` with `MaterialPageRoute` is fine.
+- Pass IDs in routes, not whole objects, so deep links and restoration work.
+- Return results with `Navigator.pop(context, value)` / `context.pop(value)` and await the push.
+- Handle the Android back button with `PopScope` where leaving would lose data.
+
+## 4. Async UI
+
+- Never start a future inside `build`. `FutureBuilder(future: fetch())` refetches on every rebuild. Create the future in `initState` (or a provider) and pass the stored future.
+- Always render all three states: loading, error with a retry, and data (including empty).
+- After every `await` in a `State` method, check `if (!mounted) return;` before using `context` or calling `setState`. For a `BuildContext` passed in as a parameter, check `context.mounted`.
+- Capture `Navigator.of(context)` or `ScaffoldMessenger.of(context)` before the `await` when you need them after it.
+- Cancel stream subscriptions in `dispose()`; prefer `StreamBuilder` or a provider so the framework does it.
+
+## 5. Performance
+
+Measure in **profile mode** (`flutter run --profile`) on a real device, with the DevTools performance view and "track widget rebuilds". Debug mode is not representative.
+
+- Long or unbounded lists: `ListView.builder` / `SliverList` with `itemExtent` or `prototypeItem` when rows are fixed height. Never `Column` + `map` inside a `SingleChildScrollView` for long data.
+- Avoid `shrinkWrap: true` on long lists inside other scrollables; use slivers in a `CustomScrollView`.
+- Keep `build` cheap: no parsing, sorting, I/O or `DateFormat` construction in it. Move heavy CPU work to `compute()` / `Isolate.run`.
+- `Opacity`, `ClipRRect`, `ShaderMask` and `BackdropFilter` over large areas are expensive; prefer `FadeTransition`, pre-clipped images or a colour with alpha.
+- Wrap independently animating regions in `RepaintBoundary` only when the DevTools repaint view shows it helps.
+- Size images: `cacheWidth` / `cacheHeight` on `Image` for thumbnails.
+
+## 6. Platform channels
+
+1. Search pub.dev for a maintained plugin (federated, with iOS and Android support) first.
+2. For your own native calls, prefer **Pigeon** to generate type-safe Dart, Kotlin and Swift code over hand-written `MethodChannel` string maps.
+3. With `MethodChannel`: one channel name per feature (`com.example.app/battery`), handle `PlatformException` and `MissingPluginException` in Dart, and return errors from native with an error code, never a crash.
+4. Platform handlers run on the platform's main thread; move long native work to a background thread and reply when done.
+5. Native code changes need a full rebuild, not a hot reload. Test on both platforms.
+
+**Stop and ask the user** before adding a new state management or routing package, raising the SDK constraint, or changing native project settings (signing, min SDK, deployment target).
+
+## Never
+
+- Never call `setState` or use `context` after an `await` without a mounted check.
+- Never create controllers, futures or streams inside `build`.
+- Never use a helper method where a const widget class would do.
+- Never ignore an analyzer warning by adding `// ignore:` without saying why.
+
+## Report back
+
+End with: widgets and files changed, state approach used and why, `flutter analyze` and `flutter test` results, and the platforms and mode (debug, profile, release) you ran it in.

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

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Should this Flutter app use Riverpod or Bloc for the cart and auth state?",
+    "Set up go_router with a login redirect and a product/:id route",
+    "My FutureBuilder keeps refetching every time the parent rebuilds, how do I structure this screen?",
+    "Call the Android battery API from my Flutter app using Pigeon",
+    "Break this 400-line Flutter build method into smaller widgets"
+  ],
+  "should_not_trigger": [
+    "Review this Flutter pull request for setState after await and leaked controllers",
+    "Convert these Dart enums and nullable fields into a sealed class hierarchy",
+    "Write widget tests and golden tests for the checkout screen",
+    "My React Native FlashList is janky on older Android phones",
+    "Build a Jetpack Compose list screen backed by a ViewModel"
+  ]
+}

package/skills/flutterwave-integration/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: flutterwave-integration
+description: Builds and reviews Flutterwave v3 payment integrations across African markets, covering Flutterwave Standard hosted checkout, direct charges for mobile money (Ghana, Kenya M-Pesa, Uganda, Francophone) and cards, server-side verification by transaction id, verif-hash webhook checks and fulfilment that runs once per tx_ref. Use when adding Flutterwave payments to an app, handling a Flutterwave webhook or redirect, charging a mobile money wallet through Flutterwave, or debugging why a Flutterwave order was marked paid wrongly or twice.
+license: MIT
+compatibility: Any Agent Skills host. Live calls need network access to api.flutterwave.com. Examples are TypeScript (Node 18+); the rules apply to any backend language.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: integrations
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# Flutterwave integration
+
+Build a Flutterwave flow where the browser can't fake a payment, every `tx_ref` gives value at most once, and pending mobile money charges still settle. This skill targets the v3 API (`https://api.flutterwave.com/v3`). If the account uses a newer API version, stop and confirm the endpoints and webhook signing scheme in the dashboard and docs before writing code.
+
+## Ground rules
+
+1. **The secret key stays on the server.** `FLW_SECRET_KEY` (`FLWSECK-...`) and the encryption key are read from the environment. Only the public key (`FLWPUBK-...`) may reach a browser or app.
+2. **The server sets the price.** Compute `amount` and `currency` from your own order record. Never accept them from the client.
+3. **One `tx_ref` per attempt, stored before you call Flutterwave**, with a unique constraint. Flutterwave requires `tx_ref` to be unique per transaction. A customer retry gets a new `tx_ref` on the same order.
+4. **Only a verify call gives value.** The redirect query string and the webhook body are hints. Call `GET /v3/transactions/{id}/verify` and require: `status === "successful"`, `tx_ref` equals yours, `currency` equals yours, and `amount >= expected` (if higher, give value and refund the difference, as Flutterwave's docs advise).
+5. **Fulfilment is idempotent.** Mark paid with a guarded update (`UPDATE payments SET status='paid' WHERE tx_ref = $1 AND status = 'pending'`) and fulfil only if a row changed. Webhooks retry, users refresh, and both paths may run at once.
+6. **Amounts are decimals in major units** in v3 (GHS 25.50 is `25.5`). Store integer minor units in your database and convert at the API boundary; never do float arithmetic on money.
+7. **Test keys first** (`FLWSECK_TEST-...`) until success, failure, cancel and duplicate-webhook paths all work.
+
+## Choose the flow
+
+| Need | Use |
+|---|---|
+| Fastest safe integration, cards + mobile money + bank, no PCI scope | Flutterwave Standard: `POST /v3/payments` returns `data.link`, redirect there |
+| Your own UI for mobile money | Direct charge: `POST /v3/charges?type=<method>` (see `references/api.md`) |
+| Your own card form | Direct card charge needs payload encryption with the account encryption key and puts you in PCI DSS scope. Stop and ask the user before building it; prefer Standard or the inline modal |
+
+## Flow (Standard)
+
+```
+client ──(order id)──▶ server: create payment row (tx_ref, expected amount/currency, pending)
+server ──POST /v3/payments──▶ Flutterwave: data.link
+client ──redirect──▶ hosted page; customer pays
+Flutterwave ──redirect_url?status=..&tx_ref=..&transaction_id=..──▶ server: verify by id, show result
+Flutterwave ──webhook charge.completed (verif-hash header)──▶ server: check hash, 200, queue verify + fulfil once
+```
+
+## Implementation steps
+
+1. **Create the payment** with `POST /v3/payments`, `Authorization: Bearer <secret key>`, body `tx_ref`, `amount`, `currency`, `redirect_url`, `customer.email` (required), optional `customer.name`, `customer.phonenumber`, `payment_options`, `meta` (put your order id here). Shapes in `references/api.md`.
+2. **Redirect handler**: read `transaction_id` from the query, call verify by id, apply ground rule 4, then show the stored status. A `status=cancelled` or `failed` redirect has nothing to verify; show the failure and offer a retry with a new `tx_ref`.
+3. **Webhook endpoint**: follow `references/webhooks.md`. Compare the `verif-hash` header to your stored secret hash in constant time, return `200` fast, then verify by `data.id` before fulfilling.
+4. **Mobile money direct charges**: follow the per-country notes in `references/api.md`. A `"success"` response with "Charge initiated" means the prompt was sent, not that money moved. Ghana returns `meta.authorization.mode: "redirect"`; send the customer to `meta.authorization.redirect`.
+5. **Reconcile pending payments**: a background job verifies payments still `pending` after a few minutes (verify by id if you have it; otherwise look up by `tx_ref` using the endpoint the current docs give) and times out stale ones.
+6. **Persist** per payment: `tx_ref`, order id, expected amount (minor units) and currency, Flutterwave transaction `id`, `flw_ref`, status, payment type, failure reason, timestamps.
+
+## Reviewing an existing integration
+
+Check every ground rule, then look for:
+
+- Fulfilment in the redirect handler based on `status=successful` in the query string, without a verify call.
+- Verify result trusted without comparing `amount`, `currency` and `tx_ref` to the stored order.
+- Webhook with no `verif-hash` check, or a check with `==` against a hard-coded value in source.
+- Webhook doing the verify and fulfilment inline before responding, so slow calls cause retries.
+- `tx_ref` reused across attempts, or generated on the client.
+- Amounts multiplied by 100 (Paystack habit) or computed with floats.
+- Secret key in a `NEXT_PUBLIC_`/`VITE_` variable or committed to the repo.
+- No handling for `failed`, `cancelled` or a charge that stays `pending`.
+
+## Stop and ask the user
+
+- Before building a raw card form (encryption plus PCI scope).
+- Which countries and currencies they sell in; payment methods differ per country.
+- Whether refunds or payouts (transfers) are in scope; they are separate APIs with their own approvals.
+
+## Before you finish
+
+Flutterwave's docs at developer.flutterwave.com are the final word on field names and versions; confirm them when writing new code. Then test in test mode: a successful payment, a declined card, a cancelled checkout, a mobile money charge that times out, the same webhook delivered twice (fulfils once), a webhook with a wrong `verif-hash` (rejected), and a tampered redirect URL (`status=successful` with a failed transaction id must not fulfil).

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

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Add Flutterwave checkout to our Nigerian e-commerce site",
+    "How do I check the verif-hash header on my Flutterwave webhook endpoint?",
+    "Charge a Kenyan customer's M-Pesa wallet through Flutterwave from our backend",
+    "Our Flutterwave redirect marks orders paid even when the transaction failed, can you fix it?",
+    "Accept Ghana mobile money with Flutterwave direct charge instead of the hosted page"
+  ],
+  "should_not_trigger": [
+    "Add Paystack checkout to our Next.js shop so Ghanaian customers can pay",
+    "Send an STK push with the Safaricom Daraja API directly",
+    "Set up Stripe subscriptions with a customer portal",
+    "Review our payment code for float money arithmetic and unverified webhooks",
+    "Integrate Hubtel online checkout for a Ghanaian school fees portal"
+  ]
+}

package/skills/flutterwave-integration/references/api.md

@@ -0,0 +1,73 @@
+# Flutterwave v3 API shapes used by this skill
+
+Base URL: `https://api.flutterwave.com/v3`. Server calls send `Authorization: Bearer <FLW_SECRET_KEY>` and `Content-Type: application/json`. A top-level `"status": "success"` means the API call worked, not that money moved.
+
+Confirm fields against developer.flutterwave.com before shipping; this is a working summary.
+
+## Create a Standard payment link
+
+`POST /payments`
+
+```json
+{
+  "tx_ref": "ord_8f2c1a_a1",
+  "amount": "25.50",
+  "currency": "GHS",
+  "redirect_url": "https://app.example.com/pay/flutterwave/return",
+  "customer": { "email": "customer@example.com", "name": "Ama Mensah", "phonenumber": "233241234567" },
+  "payment_options": "card, mobilemoneyghana",
+  "meta": { "order_id": "8f2c1a" },
+  "customizations": { "title": "Example Store" }
+}
+```
+
+Response: `data.link`. Redirect the customer there. `currency` defaults to NGN when omitted, so always send it. `payment_options` only applies when "Disable preferred payment methods" is off in the dashboard.
+
+Redirect back to `redirect_url`:
+- success: `?status=successful&tx_ref=...&transaction_id=...`
+- cancelled or failed: `?status=cancelled&tx_ref=...` (no transaction to verify)
+
+## Verify a transaction
+
+`GET /transactions/{id}/verify`, where `id` is `transaction_id` from the redirect or `data.id` from the webhook.
+
+| Field in `data` | Expect |
+|---|---|
+| `status` | `"successful"` (others include `failed`, `pending`) |
+| `tx_ref` | the reference you stored |
+| `currency` | the currency you stored |
+| `amount` | `>=` the expected amount; refund any excess |
+| `id`, `flw_ref` | store both |
+
+## Direct charges (mobile money)
+
+`POST /charges?type=<type>` with `tx_ref`, `amount`, `currency`, `email`, `phone_number`, and any country-specific fields.
+
+| Market | `type` | Currency | Notes |
+|---|---|---|---|
+| Ghana | `mobile_money_ghana` | GHS | Also send `network`. The docs list both `MTN`/`VODAFONE`/`TIGO` and `MTN`/`Telecel`/`AIRTEL`; confirm accepted values in the current reference. Response has `meta.authorization.mode: "redirect"`; send the customer to `meta.authorization.redirect` |
+| Kenya | `mpesa` | KES | Customer approves an STK prompt |
+| Uganda | `mobile_money_uganda` | UGX | Confirm in the reference |
+| Francophone West/Central Africa | `mobile_money_franco` | XOF / XAF | Confirm in the reference, including `country` |
+
+Every direct charge ends the same way: wait for the `charge.completed` webhook (or poll), then verify by id before giving value.
+
+## Minimal server client (TypeScript)
+
+```ts
+const FLW = 'https://api.flutterwave.com/v3';
+const headers = { Authorization: `Bearer ${process.env.FLW_SECRET_KEY}`, 'Content-Type': 'application/json' };
+
+export async function verifyFlutterwave(id: string, expected: { txRef: string; currency: string; amountMinor: number }) {
+  const res = await fetch(`${FLW}/transactions/${encodeURIComponent(id)}/verify`, { headers });
+  if (!res.ok) throw new Error(`verify failed: ${res.status}`);
+  const { data } = await res.json();
+  const paidMinor = Math.round(Number(data.amount) * 100); // shortcut: assumes 2-decimal currencies; UGX/XOF/XAF have 0
+  return (
+    data.status === 'successful' &&
+    data.tx_ref === expected.txRef &&
+    data.currency === expected.currency &&
+    paidMinor >= expected.amountMinor
+  );
+}
+```

package/skills/flutterwave-integration/references/webhooks.md

@@ -0,0 +1,49 @@
+# Flutterwave webhooks (v3)
+
+## What Flutterwave sends
+
+- `POST` with JSON such as `{ "event": "charge.completed", "data": { "id": 123, "tx_ref": "...", "status": "successful", "amount": 25.5, "currency": "GHS", ... } }`.
+- Header `verif-hash`: the **secret hash** you set in the dashboard webhook settings. It is a shared secret echoed back, not an HMAC of the body, so it proves the sender knows the secret but not that the body is untouched. That is why every webhook is followed by a verify call.
+- Anything other than `200` (including `3xx`) is a failure. With retries enabled in the dashboard, Flutterwave retries 3 times, 30 minutes apart. Requests time out after 60 seconds. Response body and headers are ignored.
+
+If the dashboard or docs for your account show an HMAC signature header instead of, or as well as, `verif-hash`, verify that signature on the raw body and keep the verify call.
+
+## Handler rules
+
+1. Store the secret hash in the environment (`FLW_WEBHOOK_HASH`), not in code.
+2. Read the `verif-hash` header. Missing or not equal (constant-time compare) → respond `401` and stop.
+3. Respond `200` immediately, then enqueue `data.id` for processing.
+4. The processor calls `GET /v3/transactions/{id}/verify`, applies the checks in `api.md`, and marks the payment paid with a guarded update keyed on `tx_ref`. Unknown `tx_ref` → log and drop; never create an order from a webhook.
+5. Log event type, `id` and `tx_ref`. Never log card data, the secret key or the hash.
+
+## Express (TypeScript)
+
+```ts
+import crypto from 'node:crypto';
+import express from 'express';
+
+const app = express();
+const HASH = process.env.FLW_WEBHOOK_HASH!;
+
+function sameSecret(a: string, b: string) {
+  const x = Buffer.from(a), y = Buffer.from(b);
+  return x.length === y.length && crypto.timingSafeEqual(x, y);
+}
+
+app.post('/webhooks/flutterwave', express.json(), (req, res) => {
+  if (!sameSecret(req.header('verif-hash') ?? '', HASH)) return res.sendStatus(401);
+  res.sendStatus(200); // acknowledge first
+  if (req.body?.event === 'charge.completed' && req.body.data?.id) {
+    queue.add('flw-verify', { id: String(req.body.data.id) }); // verify + fulfil once
+  }
+});
+```
+
+## Guarded fulfilment (SQL)
+
+```sql
+UPDATE payments
+   SET status = 'paid', flw_id = $2, paid_at = now()
+ WHERE tx_ref = $1 AND status = 'pending'
+RETURNING order_id;  -- fulfil only when a row comes back
+```

package/skills/fsharp-patterns/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: fsharp-patterns
+description: Idiomatic F# for writing and restructuring code - discriminated unions and records that make illegal states unrepresentable, Option and Result pipelines instead of exceptions and null, task/async/result computation expressions, compilation-order-aware module layout, and safe .NET interop. Use when writing new F# code, modelling a domain in F#, converting exception-heavy or C#-style F# to a functional style, or calling .NET libraries from F#.
+license: MIT
+compatibility: Any Agent Skills host. Needs the .NET SDK (dotnet CLI). Nullable reference type guidance needs F# 9 or later.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/requires: "dotnet"
+  kete-loom/owner: "Kete-org"
+---
+
+# F# patterns
+
+Write F# that the compiler can check: types carry the rules, functions are total, errors are values, and side effects live at the edges.
+
+## 0. Before you write
+
+1. Open the `.fsproj` and read the `<Compile Include=...>` list. F# compiles files **in that order**; a file can only use what is above it.
+2. Check the target framework and `LangVersion`, and whether `<Nullable>enable</Nullable>` is set (F# 9+).
+3. Check `<PackageReference>` (or `paket.references`) for FsToolkit.ErrorHandling, FSharpPlus or similar. Use what the project already has; don't add a library for a few helpers.
+4. Match the existing style: Fantomas config (`.editorconfig`), module vs namespace usage, naming. If the project is formatted with Fantomas, run `dotnet fantomas <files>` after editing.
+
+## 1. Model the domain with types
+
+- **Records** for data that always has all its fields. **Discriminated unions** for "one of these". Never a record with a `Kind: string` plus optional fields that only apply to some kinds.
+- **Single-case unions with a private constructor** for validated primitives, with a `create` that returns `Result`:
+
+```fsharp
+type EmailAddress = private EmailAddress of string
+
+module EmailAddress =
+    let create (s: string) =
+        if System.String.IsNullOrWhiteSpace s || not (s.Contains '@')
+        then Error "invalid email"
+        else Ok (EmailAddress (s.Trim()))
+    let value (EmailAddress s) = s
+```
+
+- Encode states as cases, not flags: `type Order = Draft of DraftOrder | Paid of PaidOrder | Shipped of ShippedOrder`, so a function that ships only accepts `PaidOrder`.
+- Use `[<Measure>]` units for money and quantities that must not mix (`decimal<GHS>`). Use `decimal`, never `float`, for money.
+- Use `option` for "may be absent". Use `| null` (F# 9) only at interop boundaries, never to model missing domain data.
+- Add `[<RequireQualifiedAccess>]` to unions whose case names would clash (`Status.Active`).
+
+## 2. Keep functions total
+
+- No partial functions on input you don't control: avoid `List.head`, `List.find`, `Seq.head`, `Map.find`, `Array.get`/`arr.[i]`, `Option.get`, `.Value` and `int "abc"`. Use `List.tryHead`, `List.tryFind`, `Map.tryFind`, `Array.tryItem`, `Int32.TryParse`.
+- Every `match` must be complete. Treat warning FS0025 (incomplete matches) as an error: `<WarningsAsErrors>$(WarningsAsErrors);FS0025</WarningsAsErrors>` (append, so existing entries survive).
+- Avoid a trailing `| _ ->` on your own unions: it hides new cases. List the cases so adding one breaks the build where it matters.
+- Prefer immutable values and `List`/`Map`/`Set`. Use `mutable` or `ref` only inside a function for a local loop or measured hot path, never shared across threads or captured in a closure that outlives it.
+
+## 3. Errors as values
+
+Decision rule:
+
+| Situation | Use |
+|---|---|
+| Value may be missing, no reason needed | `Option` |
+| Expected failure the caller must handle (validation, not found, conflict) | `Result<'T, DomainError>` with a union error type |
+| Bug or broken invariant (should never happen) | exception (`invalidOp`, `failwith`) |
+| .NET call that throws on expected failure (I/O, parsing, HTTP) | catch at the boundary, convert to `Result` |
+
+- Make the error type a union (`type OrderError = NotFound of OrderId | OutOfStock of Sku | PaymentDeclined of string`), not `string`, once callers branch on it.
+- Compose with `Result.bind`, `Result.map`, `Result.mapError`, `Option.bind`, `Option.map`, `Option.defaultValue`.
+- Convert at the edges: `Option.ofObj` / `Option.ofNullable` for .NET nulls, `Result.requireSome` (FsToolkit) or a small helper for Option to Result.
+- Wrap throwing calls once, at the boundary, and catch the specific exception:
+
+```fsharp
+let readConfig path =
+    try Ok (System.IO.File.ReadAllText path)
+    with
+    | :? System.IO.FileNotFoundException -> Error (ConfigMissing path)
+    | :? System.UnauthorizedAccessException -> Error (ConfigDenied path)
+```
+
+Never catch `exn` and turn it into `Ok` or a default; never use `try ... with _ -> ()`.
+
+## 4. Computation expressions
+
+- `task { }` for code that talks to .NET (ASP.NET Core, EF Core, HttpClient). It is hot (starts immediately) and has less overhead.
+- `async { }` for cold, composable workflows and F#-first libraries; pass `CancellationToken` via `Async.CancellationToken` or explicit parameters. Convert with `Async.AwaitTask` and `Async.StartAsTask` at the boundary only.
+- Don't mix: pick one per layer. Never block with `.Result`, `.Wait()` or `Async.RunSynchronously` except in `main` or a script.
+- `result { }`, `option { }`, `asyncResult { }`, `taskResult { }` and `validation { }` come from FsToolkit.ErrorHandling (not FSharp.Core; a FsToolkit.ErrorHandling.TaskResult package also exists, so check which one the project references before using `taskResult`). Use them if the project references it; otherwise use `Result.bind` pipelines, or ask before adding the package.
+- `let!` binds, `do!` awaits unit, `return!` returns a wrapped value, `and!` runs applicatively (accumulates errors in `validation { }`).
+- In `task { }`, `use` disposes when the task finishes; don't return a disposable resource out of the block.
+
+```fsharp
+// deps.FindCustomer and deps.Save return Task<Result<_, OrderError>>
+let placeOrder (deps: Deps) (req: PlaceOrderRequest) : Task<Result<OrderId, OrderError>> =
+    taskResult {
+        let! customer = deps.FindCustomer req.CustomerId
+        let! lines = validateLines req.Lines |> Result.mapError InvalidLines
+        let order = Order.create customer lines
+        do! deps.Save order
+        return order.Id
+    }
+```
+
+## 5. Modules and file order
+
+- Order files bottom-up: domain types, then pure domain logic, then infrastructure (DB, HTTP), then composition root / `Program.fs` last.
+- One concept per file: a type and its module of functions with the same name (`type Order` + `module Order`), types first.
+- Use `namespace` at the top of library files and modules inside; a top-level `module X` is fine for small apps and scripts.
+- Mutually recursive types go in one `type ... and ...` group or a `namespace rec`; use `rec` sparingly, not to dodge file order.
+- Keep side effects out of domain modules. Pass dependencies as function parameters or a small record of functions; reach for interfaces only when interop needs them.
+- Mark helpers `private` and keep public surface small. Add `.fsi` signature files only if the project already uses them.
+
+## 6. .NET interop
+
+- Treat every value from a C#/.NET API as possibly null: wrap with `Option.ofObj`, `Option.ofNullable`, or `match x with null -> ... | v -> ...`. With `<Nullable>enable</Nullable>`, annotate interop types as `string | null` and let the compiler warn.
+- `TryParse`-style out parameters return a tuple: `match Int32.TryParse s with | true, n -> Some n | _ -> None`.
+- Expose C#-friendly APIs from library code consumed by C#: classes with members, `Task<T>` not `Async<T>`, `seq`/`IReadOnlyList` not F# `list`, no curried public members, `[<CompiledName>]` where useful.
+- Records and unions get structural equality; .NET classes don't. Don't use classes as `Map` keys unless they implement equality.
+- `[<CLIMutable>]` on records only when a serializer or ORM needs a parameterless constructor. For JSON with unions, use the project's serializer setup (for example FSharp.SystemTextJson) rather than hand-written converters.
+- Implement `IDisposable` with `interface IDisposable with member _.Dispose() = ...` and bind with `use`, not `let`.
+
+## Never
+
+- Never use exceptions for control flow inside a `Result` pipeline.
+- Never `ignore` a `Result`, `Task` or `Async` (`|> ignore` on a `Task<Result<_,_>>` drops the error).
+- Never add `| _ ->` just to silence FS0025.
+- Never reorder `.fsproj` files without checking every file that depended on the old order still compiles.
+
+## Stop and ask the user
+
+- Before adding a NuGet package (FsToolkit.ErrorHandling, FSharpPlus, a JSON library).
+- Before changing a public signature that C# or other assemblies consume.
+- When the domain rule is unclear (which states are valid, which errors callers need to distinguish).
+
+## Report back
+
+List the files changed and where they sit in the compile order, any new types or error cases, and the build or test command you ran with its result.

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

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Model our order lifecycle in F# so you can't ship an order that hasn't been paid",
+    "This F# module throws exceptions everywhere, rewrite it to return Result instead",
+    "Write an F# function that loads a customer from EF Core inside a task computation expression and returns Result",
+    "How should I organise the modules and file order in my new F# web API project?",
+    "Wrap this C# library that returns nulls so my F# code only sees Option values"
+  ],
+  "should_not_trigger": [
+    "Write Expecto property tests with FsCheck for my F# parser",
+    "Review this F# pull request for incomplete pattern matches and mutable state",
+    "My F# project fails to build with FS0039 after I added a new file, fix it",
+    "Refactor this C# service to use records and pattern matching",
+    "Set up an EF Core migration for the new Orders table in our C# API"
+  ]
+}

package/skills/fsharp-testing/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: fsharp-testing
+description: Writes and fixes F# tests with Expecto or xUnit, FsCheck property-based tests for invariants, Unquote quotation assertions, and correct testing of task and async code without blocking. Use when adding tests to an F# project, turning example-based F# tests into properties, choosing between Expecto and xUnit for F#, or debugging flaky or hanging F# async tests.
+license: MIT
+compatibility: Any Agent Skills host. Needs the .NET SDK (dotnet CLI) and the project's test packages.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "dotnet"
+  kete-loom/owner: "Kete-org"
+---
+
+# F# testing
+
+Test behaviour through public functions, prefer properties for invariants, and keep async tests asynchronous.
+
+## 0. Find the setup first
+
+1. Find the test project (`*.Tests.fsproj`) and read its `<PackageReference>`s (or `paket.references`): Expecto, xUnit (`xunit` or `xunit.v3`), NUnit, FsCheck, `FsCheck.Xunit` / `FsCheck.Xunit.v3`, `Expecto.FsCheck`, Unquote.
+2. **Use the framework already there.** Don't add Expecto to an xUnit project or the reverse. If there is no test project, ask the user which one; default to Expecto for F#-only code and xUnit when the solution already uses it for C#.
+3. Run the suite once: `dotnet test` (or `dotnet run --project tests/X.Tests` for Expecto projects without the test adapter). If it already fails, **stop and tell the user** before changing anything.
+4. Remember file order: a new test file must be added to `<Compile Include=...>` in the test `.fsproj`, after the helpers it uses and before `Main.fs` / `Program.fs`.
+
+## 1. Expecto
+
+```fsharp
+module OrderTests
+
+open Expecto
+
+[<Tests>]
+let tests =
+    testList "Order" [
+        testCase "total sums line amounts" <| fun () ->
+            let order = Order.create [ line 2 10m; line 1 5m ]
+            Expect.equal (Order.total order) 25m "total"
+
+        testCase "empty order is rejected" <| fun () ->
+            Expect.isError (Order.tryCreate []) "empty order"
+
+        testTask "saves and reloads" {
+            let! saved = repo.Save order
+            let! loaded = repo.Load saved.Id
+            Expect.equal loaded (Some saved) "round trip"
+        }
+
+        testCaseAsync "async workflow" <| async {
+            let! r = Workflow.run input
+            Expect.isOk r "workflow"
+        }
+    ]
+```
+
+- `Expect.*` arguments are **actual, expected, message**. Swapping them gives misleading failure output.
+- Entry point: `[<EntryPoint>] let main argv = runTestsInAssemblyWithCLIArgs [] argv`, with `[<Tests>]` on each test value.
+- For `dotnet test` and IDE discovery, reference `YoloDev.Expecto.TestSdk` and `Microsoft.NET.Test.Sdk`.
+- Never commit `ftestCase` / `ftestList` (focused) or `ptestCase` (pending) by accident; focused tests silently skip the rest of the suite.
+- Use `testSequenced` for tests that share a resource (a database, a port); Expecto runs tests in parallel by default.
+
+## 2. xUnit
+
+```fsharp
+module OrderTests
+
+open Xunit
+open Swensen.Unquote
+
+[<Fact>]
+let ``total sums line amounts`` () =
+    let order = Order.create [ line 2 10m; line 1 5m ]
+    test <@ Order.total order = 25m @>
+
+[<Theory>]
+[<InlineData("", false)>]
+[<InlineData("a@b.co", true)>]
+let ``email validation`` (input: string, ok: bool) =
+    test <@ Result.isOk (EmailAddress.create input) = ok @>
+
+[<Fact>]
+let ``saves and reloads`` () = task {
+    let! saved = repo.Save order
+    let! loaded = repo.Load saved.Id
+    loaded =! Some saved
+}
+```
+
+- Use backtick names that read as sentences. Put tests in a module, not a class, unless you need fixture constructors or `IDisposable` cleanup.
+- Async tests return `Task` via `task { }`. Never call `.Result`, `.Wait()` or `Async.RunSynchronously` in a test; it can deadlock and hides the real exception.
+- Use `Assert.ThrowsAsync<T>` (or Unquote `raises`) for expected exceptions, not `try ... with`.
+
+## 3. Unquote
+
+- `test <@ expr @>` fails with a step-by-step reduction of the expression, which beats `Assert.True`.
+- Operators: `actual =! expected`, `actual <>! other`, `x >! y`, `raises<ArgumentException> <@ f bad @>`.
+- Works inside Expecto and xUnit. Keep each quotation to one claim; split compound `&&` checks into separate tests.
+
+## 4. FsCheck property tests
+
+Write a property when a rule holds for all inputs: round trips (`parse (format x) = x`), invariants (total is never negative), equivalence to a simple model, idempotence (`normalise (normalise x) = normalise x`).
+
+```fsharp
+// xUnit
+[<Property>]
+let ``reverse twice is identity`` (xs: int list) =
+    List.rev (List.rev xs) = xs
+
+// Expecto (Expecto.FsCheck)
+testProperty "format then parse round trips" <| fun (m: Money) ->
+    Money.parse (Money.format m) = Ok m
+```
+
+- Custom data: build a `Gen` and turn it into an `Arbitrary` with `Arb.fromGen`. Use `Gen.choose (lo, hi)`, `Gen.elements`, `Gen.map`, `Gen.filter` sparingly (heavy filters make FsCheck give up).
+- Register generators as a type with static members returning `Arbitrary<'T>`, then `[<Property(Arbitrary = [| typeof<Generators> |])>]` in xUnit, or the `arbitrary` field of `FsCheckConfig` in Expecto.
+- For validated types (private single-case unions), generate raw values that pass `create`, so properties exercise the real constructor.
+- Use `==>` for preconditions only when they rarely fail; otherwise write a generator.
+- When a property fails, FsCheck prints the shrunk counterexample and a seed. Copy the counterexample into a regular example test so it stays covered, then fix the code.
+- FsCheck 2 and 3 differ (for example, 3 uses `ArbMap.defaults` where 2 used `Arb.Default`). Check the referenced version before copying examples.
+
+## 5. Testing task and async code
+
+- Test the async function itself; don't wrap it in a synchronous helper.
+- Pass a `CancellationToken` in and assert cancellation behaviour with a pre-cancelled token.
+- Replace real time and I/O with function parameters (`now: unit -> DateTimeOffset`, `send: Email -> Task<Result<unit, SendError>>`). Pass fakes as plain lambdas; you rarely need a mocking library in F#.
+- For `Result`-returning workflows, assert on the exact error case (`Error (OutOfStock sku)`), not just `isError`.
+- No real network or wall-clock sleeps. If a test needs a delay, the design needs an injected clock.
+
+## Never
+
+- Never delete, skip or weaken an existing test to make the suite pass without the user's agreement.
+- Never leave focused (`ftest*`) or `Skip =` tests in a commit.
+- Never assert on `ToString()` or `sprintf "%A"` output of records and unions; compare values, they have structural equality.
+
+## Report back
+
+List tests added (names and file), the command you ran (`dotnet test --filter ...` or the Expecto run), final pass/fail counts, any FsCheck seed that found a bug, and what is still untested.

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

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Add Expecto tests for the F# invoice module, including the task-based repository calls",
+    "Turn these F# example tests into FsCheck properties so we cover more inputs",
+    "My xUnit test in F# hangs when I call Async.RunSynchronously, how should I test this async workflow?",
+    "Write Unquote assertions for the F# parser instead of Assert.Equal",
+    "Should our new F# library use Expecto or xUnit for its test project?"
+  ],
+  "should_not_trigger": [
+    "Model the payment states in F# with discriminated unions",
+    "Review my F# changes for partial functions and incomplete matches",
+    "The F# test project won't compile because of a value restriction error",
+    "Write xUnit tests with Moq for my C# OrderService",
+    "Raise test coverage across the repo to 80 percent"
+  ]
+}