@ketecode/loom 0.0.0-stage → 0.2.0

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

package/skills/gcp-patterns/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: gcp-patterns
+description: Guides Google Cloud projects through service-account-based IAM without key files, choosing Cloud Run, GKE or Cloud Run functions, Cloud SQL connections through the Auth Proxy or connectors, Cloud Storage access control, Secret Manager, VPC and firewall basics, and the GCP billing gotchas such as idle GKE nodes, egress, and log ingestion. Use when deploying to or designing on Google Cloud, granting roles to a service account, picking a GCP runtime, or tracing an unexpected Google Cloud charge.
+license: MIT
+compatibility: Any Agent Skills host. Live checks need the gcloud CLI authenticated to the target project. Infrastructure code may be Terraform or gcloud scripts.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: network
+  kete-loom/requires: "gcloud"
+  kete-loom/owner: "Kete-org"
+---
+
+# Google Cloud patterns
+
+Run workloads on Google Cloud with one dedicated identity per service, no downloaded keys, private data stores and a bill you can explain. Terraform mechanics are in `terraform-patterns`, Kubernetes manifests in `kubernetes-patterns`, CI auth wiring in `github-actions-ci`.
+
+## Ground rules
+
+1. **One project per environment** (dev, staging, prod), grouped under folders in an organization. Projects are the blast-radius and billing boundary.
+2. **One user-managed service account per workload.** Never run services as the default Compute Engine service account; in older projects it may hold the broad Editor role.
+3. **No service account key files.** Workloads on Google Cloud get credentials from the metadata server automatically. CI uses Workload Identity Federation; GKE pods use Workload Identity Federation for GKE. If someone asks for a JSON key, **stop and ask** what it's for and offer federation first. Recommend the org policy `iam.disableServiceAccountKeyCreation`.
+4. **Predefined roles, granted at the narrowest resource.** Grant `roles/secretmanager.secretAccessor` on the one secret, `roles/storage.objectViewer` on the one bucket, not at project level. Never grant basic roles (Owner, Editor, Viewer) to workloads.
+5. **Secrets in Secret Manager**, mounted or exposed as env vars by Cloud Run / GKE from a pinned version or `latest` deliberately. Never in source, `app.yaml`, or build args.
+6. **Everything in IaC.** Console clicks are for exploring. Enable APIs (`gcloud services enable ...`) in code too.
+
+## Choosing compute
+
+| Need | Pick | Watch out for |
+|---|---|---|
+| Stateless HTTP service or container, scale to zero | Cloud Run (service) | Request timeout limits; CPU is throttled outside requests under the default request-based billing, so background work needs instance-based billing (`--no-cpu-throttling`); set `max-instances` to cap cost and DB connections |
+| Batch or run-to-completion container | Cloud Run jobs | Set task timeout and retries explicitly |
+| Single function on an event (Pub/Sub, Storage, Eventarc) | Cloud Run functions (formerly Cloud Functions) | Same limits as Cloud Run; 1st gen is legacy, prefer the current generation |
+| Many services, need Kubernetes APIs, daemons or GPUs on nodes | GKE (Autopilot first, Standard if you need node control) | Cluster fee plus node or pod cost; idle node pools on Standard |
+| Legacy VM software | Compute Engine with a managed instance group | Use OS Login / IAP TCP forwarding, no public SSH |
+
+Decision rule: default to Cloud Run. Move to GKE only when a concrete requirement (sidecars Cloud Run can't host, node-level access, very high steady load) is named.
+
+## Networking basics
+
+1. Use a custom-mode VPC with explicit subnets per region; don't build on the `default` network, whose firewall rules are broad.
+2. Firewall rules target service accounts or network tags, not "all instances". No `0.0.0.0/0` ingress except to a load balancer.
+3. Private Google Access on subnets so private VMs reach Google APIs without external IPs.
+4. Cloud Run reaches private resources (Cloud SQL private IP, Memorystore) through Direct VPC egress or a Serverless VPC Access connector.
+5. Outbound internet from private resources goes through Cloud NAT. Put public HTTP behind an external Application Load Balancer with Cloud Armor if the user needs WAF rules.
+
+## Data
+
+- **Cloud SQL:** private IP, automated backups and point-in-time recovery on, high availability for production, deletion protection on. Connect through the Cloud SQL Auth Proxy or the language connector libraries (IAM-authorized, TLS) rather than allowlisting IPs. Prefer IAM database authentication where the engine supports it.
+- **Cloud Storage:** uniform bucket-level access on; public access prevention enforced; object versioning or soft delete for data you can't regenerate; lifecycle rules for old objects. Give out signed URLs for temporary access, never `allUsers`.
+- **Firestore / Spanner / BigQuery:** pick by access pattern; BigQuery bills by bytes scanned on on-demand pricing, so partition and cluster large tables and never `SELECT *` on them.
+
+## Cost traps
+
+- GKE Standard node pools left at fixed size; GKE clusters for one tiny service.
+- Cloud Run with `min-instances` > 0 or instance-based billing on services that are mostly idle.
+- Internet and cross-region egress; Cloud NAT data processing.
+- Cloud Logging ingestion from chatty debug logs; set exclusion filters and retention.
+- BigQuery full-table scans; unattached persistent disks and old snapshots; static external IPs not in use.
+
+Set a budget with alert thresholds on the billing account first.
+
+## Steps for a change
+
+1. Confirm the project ID and environment (`gcloud config get-value project`). If the active project is not the one the user means, **stop and ask**.
+2. Write the change in IaC; enable the APIs it needs in the same change.
+3. Validate: `terraform plan`; for gcloud scripts, `describe` the current state first, since most gcloud commands have no dry-run mode. For IAM, list what the change grants and to whom.
+4. **Stop and ask before** applying anything that deletes or recreates a database, bucket or disk, grants a basic role, makes a resource public, or targets production.
+5. After apply, verify the service's health endpoint, check `gcloud run services describe` (or equivalent) shows the intended service account, and confirm nothing became public.
+
+## Never
+
+- Download a service account key "temporarily".
+- Grant `roles/owner` or `roles/editor` to a service account or to `allAuthenticatedUsers`.
+- Delete a project, bucket or Cloud SQL instance without the user confirming the exact name.
+
+## Review output
+
+```
+GCP review: <project/env>
+Critical: <public buckets, key files, basic roles on workloads>
+High: <default SA in use, no backups, open firewall rules>
+Cost: <each trap found>
+Suggested IaC changes: <file: change>
+Not checked: <what you had no access to>
+```

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

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Deploy this container to Cloud Run and give it a dedicated service account with minimal roles",
+    "How should our Cloud Run service connect to Cloud SQL Postgres on a private IP?",
+    "A teammate wants to download a JSON key for a GCP service account, is there a better way?",
+    "Cloud Run, GKE Autopilot or Cloud Run functions for a Pub/Sub event processor?",
+    "Our Google Cloud invoice is dominated by Cloud Logging ingestion and BigQuery scans"
+  ],
+  "should_not_trigger": [
+    "Let our GitHub Actions workflow authenticate to Google Cloud with workload identity federation",
+    "Choose between Lambda and ECS Fargate for our API on AWS",
+    "Make our Azure Functions app read secrets from Key Vault with a managed identity",
+    "Write a BigQuery SQL query that finds the top ten customers by revenue",
+    "Tune the Helm chart values for our ingress controller"
+  ]
+}

package/skills/git-workflow/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: git-workflow
+description: Everyday team git without an interactive editor - feature branches, choosing rebase or merge, resolving conflicts, tidying commits with fixup and autosquash, recovering lost commits through the reflog, and force-pushing with --force-with-lease so nobody's work is overwritten. Use when a branch has diverged, a rebase or merge hit conflicts, commits need squashing or rewording before review, work seems lost after a reset or bad rebase, or a rewritten branch must be pushed.
+license: MIT
+compatibility: Any Agent Skills host. Needs git 2.23+ (switch/restore); --force-if-includes needs 2.30+ and --update-refs needs 2.38+.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git"
+  kete-loom/owner: "Kete-org"
+---
+
+# Git workflow
+
+Keep history readable and never lose anyone's work. Every command here runs without opening an editor, so an agent can drive it.
+
+## 0. Look before you act
+
+1. Run `git status`, `git branch --show-current` and `git log --oneline --graph -15 --all`.
+2. Run `git fetch --prune` so you compare against the real remote.
+3. Find the base branch: `git symbolic-ref refs/remotes/origin/HEAD` (usually `origin/main`). If the project documents a different flow (release branches, `develop`), follow it.
+4. If the working tree has uncommitted changes, **stop and ask** whether to commit them, stash them (`git stash push -u -m "<why>"`) or leave the task.
+5. Before any history rewrite, create a safety ref: `git branch backup/<branch>-$(date +%Y%m%d%H%M%S)`. Delete it only after the user confirms the result.
+
+## 1. Branching
+
+- One branch per change, cut from an up-to-date base: `git switch -c <type>/<short-topic> --no-track origin/main`. Without `--no-track` the new branch tracks `origin/main`, so a bare `git push` or `git pull` targets main. Publish it with `git push -u origin <branch>`.
+- Name branches by intent (`fix/login-timeout`, `feat/export-csv`), not by person.
+- Keep branches short-lived. If a branch is more than a few days behind, integrate the base (section 2) before adding more work.
+- Never commit straight to the default branch unless the project explicitly works that way.
+
+## 2. Rebase or merge?
+
+| Situation | Do |
+|---|---|
+| Your own unshared feature branch is behind main | `git rebase origin/main` |
+| Branch is shared and others have pushed to it | `git merge origin/main` (never rewrite shared history) |
+| Integrating a finished branch into main | Follow the repo's PR setting (squash, rebase or merge commit). Don't override it locally. |
+| Long-running release branch | Merge, so the history of what shipped stays intact |
+| Stacked branches (B built on A) | `git rebase --update-refs origin/main` from the top branch moves the whole stack |
+
+To check whether a branch is shared: `git log --format='%an' origin/main..origin/<branch> | sort -u`. More than one author means merge, or ask first.
+
+Set `git config pull.rebase true` only if the team agrees; otherwise use explicit `git fetch` plus rebase or merge.
+
+## 3. Resolving conflicts
+
+1. List conflicted files: `git diff --name-only --diff-filter=U`.
+2. For each file, read both sides and the intent of each change (`git log --oneline -3 -- <file>` on each side). Resolve by meaning, not by picking a side wholesale.
+3. During a **rebase**, "ours" is the branch you are rebasing onto and "theirs" is your commit being replayed. That is the opposite of a merge. Use `git checkout --ours|--theirs <file>` only when one side should win entirely.
+4. Lockfiles and generated files: take the base version, then regenerate with the project's tool (for example reinstall dependencies) instead of hand-merging.
+5. Remove every conflict marker. Check: `git diff --check` and search for `^<<<<<<<|^>>>>>>>`.
+6. Build and run the tests before continuing.
+7. `git add <file>` then `git rebase --continue` (or `git commit --no-edit` for a merge). Use `GIT_EDITOR=true git rebase --continue` to accept the existing message without an editor.
+8. If the conflict is in code you don't understand, or both sides changed behaviour, **stop and ask** the user. To back out cleanly: `git rebase --abort` or `git merge --abort`.
+
+Turn on `git config rerere.enabled true` for repeated conflicts while rebasing long branches.
+
+## 4. Cleaning up history without an editor
+
+Only on commits that are not yet on a shared branch.
+
+- **Fix an earlier commit:** stage the fix, `git commit --fixup=<sha>`, then
+  `GIT_SEQUENCE_EDITOR=true git rebase -i --autosquash origin/main`.
+  Setting the sequence editor to `true` accepts the generated todo list, so nothing interactive opens.
+- **Reword the last commit:** `git commit --amend -m "<new message>"`.
+- **Reword an older commit:** `git commit --allow-empty -m "amend! <exact original subject>" -m "<new full message>"`, then the autosquash command above. (`--fixup=reword:` does the same but opens an editor.)
+- **Squash the whole branch into one commit:** `git reset --soft $(git merge-base HEAD origin/main)` then `git commit -m "<message>"`.
+- **Split the last commit:** `git reset HEAD~1`, then stage and commit each piece by path (`git add <path>`; `git add -p` is interactive).
+- **Drop a commit from the branch:** `git rebase --onto <sha>^ <sha>` (removes `<sha>`, keeps the rest).
+- **Undo a commit already on a shared branch:** `git revert <sha>`. Never rewrite it.
+
+After any rewrite, compare the result: `git diff backup/<branch>-<stamp> HEAD` should be empty when you only reshaped commits on the same base. If you also rebased onto a newer base, compare `git range-diff <old-base>..backup/<branch>-<stamp> <new-base>..HEAD` instead.
+
+## 5. Recovering lost work
+
+Nothing committed is gone until garbage collection. By default the reflog keeps entries for commits no longer on any branch for 30 days (`gc.reflogExpireUnreachable`), and 90 days for the rest.
+
+1. `git reflog -30` (or `git reflog show <branch>`) to find the commit before the mistake, such as the entry before `rebase (start)` or `reset: moving to`.
+2. Inspect it: `git show --stat <sha>`.
+3. Restore without destroying anything: `git branch rescue/<topic> <sha>`. Only after the user agrees, move the branch: `git reset --hard <sha>`.
+4. Lost stash: `git fsck --no-reflogs --unreachable | grep commit`, then `git show <sha>` to find it, and `git stash apply <sha>`.
+5. Unstaged changes discarded with `git checkout -- .`, `git restore .` or `git reset --hard` are **not** recoverable by git. Say so plainly; check the editor's local history instead. Changes that had been staged survive as dangling blobs: `git fsck --lost-found` writes them to `.git/lost-found/other/` for inspection.
+
+## 6. Pushing rewritten branches safely
+
+1. Push: `git push --force-with-lease --force-if-includes origin <branch>`.
+   - `--force-with-lease` refuses if the remote moved since your last fetch.
+   - `--force-if-includes` also refuses if a background fetch updated the remote ref but you never integrated those commits.
+2. If the push is rejected, **do not** retry with `--force`. Fetch, inspect `git log HEAD..origin/<branch>`, integrate the new commits, and push again.
+3. Never force-push `main`, `master`, release branches or any protected branch. If one seems to need it, stop and ask.
+4. Tell collaborators on the branch that it was rewritten; they should `git fetch` and `git rebase origin/<branch>` or reset onto it.
+
+## Never
+
+- Never run `git reset --hard`, `git clean -fd`, `git checkout -- .` or `git stash drop` on work the user hasn't confirmed is disposable.
+- Never use plain `git push --force`.
+- Never rewrite commits that exist on a shared or protected branch.
+- Never resolve a conflict by deleting the other side's change without understanding it.
+- Never bypass hooks with `--no-verify` unless the user asks.
+
+## Report back
+
+End with:
+
+```
+Branch: <name> (base <base>, ahead N / behind M)
+Did: <rebase | merge | cleanup | recovery | push>
+Conflicts: <files and how each was resolved, or none>
+Safety ref: <backup branch name, or none>
+Checks: <build/test command and result>
+Next: <what the user or collaborators must do>
+```

package/skills/git-workflow/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "My feature branch is 40 commits behind main and the rebase stopped with conflicts in three files, help me get through it",
+    "I did git reset --hard by mistake and my last two commits are gone, can we get them back?",
+    "Squash the fixup commits on this branch into the commits they belong to before I ask for review",
+    "Should I rebase or merge main into my branch? Two of us have been pushing to it",
+    "I rewrote my branch history locally, how do I push it without clobbering my teammate's commits?"
+  ],
+  "should_not_trigger": [
+    "Write a commit message for these staged changes using feat/fix prefixes",
+    "Cut version 2.4.0, update the changelog and tag the release",
+    "Set up a GitHub Actions job that runs the tests on every pull request",
+    "Write a description for my pull request summarising the changes",
+    "Review the diff on this branch for bugs before I merge"
+  ]
+}