@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/swiftui-patterns/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: swiftui-patterns
+description: SwiftUI view design built on structural identity, with property-wrapper choices (@State, @Binding, @Observable models with @Bindable, @Environment), NavigationStack and value-based navigation paths, one-way data flow, keeping body cheap to avoid excess view updates, #Preview setups with sample data, and UIKit interop through UIViewRepresentable and UIHostingController. Use when building or restructuring SwiftUI screens, deciding which property wrapper owns a piece of state, migrating from ObservableObject to @Observable, fixing views that reset or redraw too often, or embedding UIKit in SwiftUI or the reverse.
+license: MIT
+compatibility: Any Agent Skills host. Needs Xcode on macOS for building, previews and tests (xcodebuild). @Observable and @Bindable need iOS 17 / macOS 14 or newer.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "xcodebuild"
+  kete-loom/owner: "Kete-org"
+---
+
+# SwiftUI patterns
+
+Write SwiftUI where each piece of state has one owner, view identity is stable, and `body` is cheap. Swift language features, actors and Swift 6 concurrency belong to `swift-patterns`; XCTest and Swift Testing belong to `swift-testing`.
+
+## 0. Before you write
+
+1. Find the deployment target (project settings or `Package.swift` `platforms:`). It decides the APIs you may use:
+   - iOS 16+: `NavigationStack`, `NavigationSplitView`, `navigationDestination`.
+   - iOS 17+: `@Observable`, `@Bindable`, `@Environment(Model.self)`.
+   - Below that: `ObservableObject`, `@StateObject`, `NavigationView`. Use `if #available` only for small additions.
+2. See whether the project uses `ObservableObject` or `@Observable` today. Don't mix both styles in one feature.
+3. Build once (`xcodebuild ... build` or the project's script) and record the result.
+
+## 1. Which property wrapper
+
+| The view... | Use |
+|---|---|
+| Owns a simple value (toggle, text, selection) | `@State private var` |
+| Owns a reference-type model it creates | `@State private var model = Model()` with an `@Observable` class (iOS 17+), or `@StateObject` for `ObservableObject` |
+| Edits a value owned by a parent | `@Binding` |
+| Receives an `@Observable` model and needs bindings to its properties | `@Bindable var model` |
+| Receives an `@Observable` model and only reads it | a plain `let` / `var` property |
+| Reads app-wide values or injected models | `@Environment(\.key)` or `@Environment(Model.self)` |
+| Receives an `ObservableObject` it doesn't own | `@ObservedObject` |
+
+Rules:
+
+- `@State` and `@StateObject` are always `private` and initialised in the view that owns them. Never pass an owned value into a child's `@State`; the child keeps its first copy and ignores later changes.
+- Never create an `ObservableObject` with `@ObservedObject var model = Model()`; it is recreated on every parent update.
+- Keep models `@MainActor` when they drive UI.
+- Migrating to `@Observable`: drop `@Published`, replace `@StateObject` with `@State`, `@EnvironmentObject` with `@Environment(Model.self)` (and `.environmentObject(model)` with `.environment(model)` at the injection site), and use `@Bindable` where you need `$model.property`.
+
+## 2. View identity
+
+SwiftUI tracks views by their position in the hierarchy (structural identity) or by explicit `.id` / `ForEach` IDs. When identity changes, state is destroyed and transitions run.
+
+- Prefer modifiers over branches: `.opacity(isHidden ? 0 : 1)` keeps identity; `if isHidden { } else { }` swaps two different views and resets their state.
+- `ForEach` needs stable, unique IDs from the data (`Identifiable` with a real ID). Never use `\.self` on non-unique values or array indices on mutable arrays.
+- Use `.id(value)` deliberately to reset a view (for example a form when the edited record changes), never as a "force refresh" hack.
+- Avoid `AnyView` in hot paths; it hides identity and costs diffing. Use `@ViewBuilder` and `some View`.
+
+## 3. Navigation
+
+- Use `NavigationStack(path:)` with a `@State` path (`NavigationPath` or `[Route]` of a `Hashable` enum) when the app navigates programmatically or restores state.
+- Register destinations with `.navigationDestination(for: Route.self)` once, near the stack root, not inside lazy containers.
+- Push by appending a value; pop by removing from the path. Pass IDs or small values, and load the model at the destination.
+- Use `NavigationSplitView` for sidebar layouts on iPad and Mac.
+- Present sheets with `.sheet(item:)` bound to optional state so the content gets the right value; avoid `.sheet(isPresented:)` plus a separate selected-item variable.
+- Deep links: handle `.onOpenURL` once and translate the URL into a path.
+
+## 4. Data flow
+
+- Data flows down as values or models; events flow up through bindings or closures.
+- Side effects belong in `.task { }` (cancelled automatically when the view disappears) or `.task(id:)` for work tied to a changing value. Don't start work in `init` or in `body`.
+- Long work and networking go in the model or a service, not the view. Update observable state on the main actor.
+- Keep one source of truth. Never copy a model's value into local `@State` "for editing" without a clear commit/cancel step.
+
+## 5. Performance
+
+- `body` runs often; keep it pure and cheap. No formatting objects created per call, sorting, filtering big arrays or I/O in `body`. Compute in the model or cache.
+- Split big views into small subviews so a change only re-evaluates the part that reads it. With `@Observable`, a view updates only when properties it reads change.
+- Use `LazyVStack`, `LazyHStack`, `LazyVGrid` or `List` for long content, not `VStack` in a `ScrollView`.
+- Profile with Instruments (the SwiftUI and Time Profiler instruments) on a device in Release. `Self._printChanges()` inside `body` (debug only, remove before committing) shows why a view updated.
+- Load images at display size; use `AsyncImage` only for simple cases and cache elsewhere when lists are long.
+
+## 6. Previews
+
+- Give every screen a `#Preview` (Xcode 15+; `PreviewProvider` on older Xcode) with in-memory sample data: no network, no real database.
+- Inject dependencies through initialisers or the environment so previews can pass fakes.
+- Add previews for empty, loading, error and long-text states, plus dark mode and a large Dynamic Type size.
+
+## 7. UIKit interop
+
+- UIKit view inside SwiftUI: `UIViewRepresentable` (or `UIViewControllerRepresentable`). Create the view in `makeUIView`, apply state in `updateUIView` (it runs often: compare before mutating), and use a `Coordinator` for delegates and target-action.
+- SwiftUI inside UIKit: `UIHostingController(rootView:)`, added as a child view controller with `addChild` and `didMove(toParent:)`. Pass a model, not a snapshot, so updates flow.
+- Don't keep strong references from the coordinator back to the representable's parent; use the values passed in `updateUIView`.
+
+**Stop and ask the user** before raising the deployment target, or before migrating a whole feature from `ObservableObject` to `@Observable` when only a small change was requested.
+
+## Never
+
+- Never initialise `@State` from a parent's value expecting it to stay in sync.
+- Never do work in `body` or a view's `init`.
+- Never use array indices as `ForEach` IDs for data that changes.
+- Never leave `Self._printChanges()` in committed code.
+
+## Report back
+
+End with: views and models changed, which wrapper owns each new piece of state, the build and test commands with results, and the OS versions or simulators you ran on.

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

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Should this SwiftUI child view use @State, @Binding or @Bindable for the user model?",
+    "Migrate our view models from ObservableObject and @Published to the @Observable macro",
+    "Set up a NavigationStack with a path so I can pop to root after checkout",
+    "My SwiftUI form resets its text fields whenever the parent list refreshes",
+    "Wrap an MKMapView in UIViewRepresentable with a coordinator for the delegate"
+  ],
+  "should_not_trigger": [
+    "Make this Swift networking layer Sendable for Swift 6 strict concurrency",
+    "Write XCTest unit tests for the payment view model",
+    "My Jetpack Compose screen recomposes on every keystroke",
+    "Fix the swift build error about ambiguous use of init in the package",
+    "Share the login logic between Android and iOS with Kotlin Multiplatform"
+  ]
+}

package/skills/tdd-workflow/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: tdd-workflow
+description: Test-first development loop that writes a failing test, makes it pass with the smallest change, then refactors with the suite green. Use when adding a feature, fixing a reproducible bug, or refactoring code in a project that has (or should have) automated tests.
+license: MIT
+compatibility: Any Agent Skills host. Needs the project's test runner and git.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git"
+  kete-loom/owner: "Kete-org"
+---
+
+# TDD workflow
+
+Drive every behaviour change with a test that fails first. The loop is short on purpose: red, green, refactor, commit.
+
+## 0. Before you start
+
+1. Find how this project runs tests. Check, in order: the README, `AGENTS.md`, `package.json` scripts, `Makefile`, `pyproject.toml`, `go.mod`, `Cargo.toml`, CI config in `.github/workflows/`.
+2. Run the existing suite once. Record the result.
+   - If it already fails, **stop and tell the user** which tests fail before changing anything. Do not "fix" unrelated failures silently.
+3. Restate the behaviour you are about to build as 1–5 concrete examples (input → expected output). If you cannot, ask the user for the missing detail.
+
+## 1. Red: write one failing test
+
+- Pick the **smallest** example that is not yet supported.
+- Put the test next to existing tests for that module, following their naming, fixtures and style.
+- Test behaviour through the public interface, not private helpers.
+- Run only that test. It must fail **for the expected reason** (assertion fails, or the function doesn't exist). A test that fails because of a typo or import error doesn't count; fix the test and rerun.
+
+For a bug fix, the first test reproduces the bug exactly as reported.
+
+## 2. Green: make it pass
+
+- Write the least code that makes the test pass. Hard-coding is acceptable at this step if the next test will force generalisation.
+- Run the single test, then the whole related test file.
+- Do not add features no test asks for.
+
+## 3. Refactor: clean up with the suite green
+
+- Remove duplication, improve names, extract functions.
+- Run the full suite after each refactor. If anything goes red, undo the last refactor rather than debugging forward.
+
+## 4. Repeat or finish
+
+Go back to step 1 with the next example until every example from step 0 is covered. Then also cover:
+
+- Edge cases: empty input, boundaries, invalid input, and the error path.
+- Anything the user called out as important.
+
+Prefer a few meaningful tests over chasing a coverage number. If the project enforces a coverage threshold, meet it.
+
+## 5. Commit
+
+When the full suite is green, commit with a message that states the behaviour added or the bug fixed. One logical change per commit. Don't commit if the suite is red.
+
+## Rules
+
+- Never delete, skip or weaken an existing test to make the suite pass. If an existing test is wrong, explain why to the user and get agreement first.
+- Never mock the unit under test. Mock only slow or external boundaries (network, clock, filesystem when needed).
+- Keep tests deterministic: no real network calls, fixed seeds, fixed time.
+- If you can't get to green after three focused attempts, stop and report what you tried and what you observed.
+
+## Report back
+
+End with: tests added (names), the command you ran, the final pass/fail counts, and anything left uncovered.

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

@@ -0,0 +1,14 @@
+{
+  "should_trigger": [
+    "Add a discount-code field to the checkout service, test first please",
+    "There's a bug where negative quantities are accepted in the cart. Reproduce it with a failing test and fix it.",
+    "Refactor the invoice calculator but keep behaviour identical, write tests before you touch it",
+    "Implement the parseDuration helper using red-green-refactor"
+  ],
+  "should_not_trigger": [
+    "Explain what test-driven development is in two sentences",
+    "Run all the checks on my branch before I open a pull request",
+    "Review my last commit for security vulnerabilities",
+    "Write a README section describing how to install the project"
+  ]
+}

package/skills/technical-writing/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: technical-writing
+description: Writes and restructures developer-facing documentation people actually use, such as READMEs, how-to guides, tutorials and API reference, by naming the audience first, organising around the reader's task, shipping copy-paste examples that are run before publishing, and keeping docs beside the code they describe. Use when drafting or rewriting a README, a getting-started or how-to guide, reference docs for a library, CLI or HTTP API, or when docs are confusing, stale or nobody reads them.
+license: MIT
+compatibility: Any Agent Skills host. Running examples needs the project's own toolchain.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: docs
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# Technical writing
+
+Docs exist so a reader can finish a task. Every decision below follows from that: know who reads, know what they're trying to do, show them a working path, and keep it true.
+
+## 1. Pin down audience and job
+
+Before writing, answer these. Ask the user for any you can't infer from the repo:
+
+1. **Who reads it?** First-time user, integrating developer, operator, contributor. One primary reader per document.
+2. **What are they trying to do?** Install, try it, solve one specific problem, look up an exact detail, understand a design.
+3. **What do they already know?** Language, framework, domain terms.
+
+The answer to question 2 picks the document type. Don't mix types in one page.
+
+| Reader wants to | Write a | Shape |
+|---|---|---|
+| learn by doing, first time | tutorial | one guided path, every step succeeds, no choices |
+| solve a specific problem | how-to guide | goal in the title, prerequisites, numbered steps, result |
+| look up an exact fact | reference | complete, consistent, structured like the code |
+| understand why | explanation | prose, trade-offs, diagrams, links to the rest |
+
+This is the Diátaxis split. Use it to decide, not as jargon in the docs.
+
+## 2. Structure task-first
+
+- Title says the task or the thing: "Send a webhook test event", not "Webhooks overview".
+- Put the shortest successful path first. Options, edge cases and theory come after.
+- Number steps that must happen in order. One action per step. Put the expected result after the step that produces it.
+- State prerequisites up front (versions, accounts, permissions), never halfway down.
+- Use headings a reader would search for. Keep paragraphs short.
+
+### README order
+
+1. Name and one sentence on what it does and for whom.
+2. Install (one command where possible).
+3. Quick start: the smallest example that does something real, with its output.
+4. Common tasks or a link to guides.
+5. Configuration (table: key, default, meaning).
+6. Links: full docs, contributing, license, support.
+
+Badges, history and architecture go below this or in other files.
+
+## 3. Examples that run
+
+- Every example is complete enough to paste and run: imports, setup, and placeholder values that are obviously placeholders (`YOUR_API_KEY`, `example.com`).
+- Show the expected output or response.
+- Run every example before you publish it, using the project's toolchain. If you can't run one, mark it "not run" in your report and tell the user.
+- Use the project's real names, flags and defaults. Search the code to confirm each one; don't recall them.
+- Label code blocks with their language. Split commands from their output.
+- Never put real secrets, tokens, internal hostnames or customer data in examples.
+
+## 4. Reference docs
+
+- Generate from the source where the project already has a generator (docstrings, OpenAPI, typedoc-style tools). Fix the source comments, not the generated output.
+- For each item: signature or endpoint, parameters (name, type, required, default, meaning), return value or response, errors, one example.
+- Keep the same order and wording pattern for every entry so readers can scan.
+- Document behaviour callers depend on: units, limits, side effects, idempotency, thread safety, deprecation and what replaces it.
+
+## 5. Keep docs with the code
+
+- Put docs in the repo, next to what they describe (`README.md` at package roots, `docs/` for guides, docstrings for reference).
+- When code and docs disagree, the code is the truth. Fix the docs, or tell the user if the code looks wrong.
+- Prefer links over copies. Duplicate text goes stale in one place first.
+- If the project has docs linting, link checking or doctests, run them.
+- When a code change alters behaviour, update docs in the same change. For that job, delegate to the `doc-updater` agent if it's available.
+
+## 6. Style
+
+- Second person, active voice, present tense: "Run `make test`", not "The tests can be run".
+- Plain words. Define a term the first time, then use it the same way every time.
+- Be specific: "takes about 2 minutes", not "may take some time"; "requires Node 18 or later" only after checking the project's engines field or CI.
+- Cut filler: "simply", "just", "easy", "obviously". They insult the reader who's stuck.
+- Follow the project's existing style guide and spelling if it has one.
+
+## Stop and ask
+
+- The audience or document type is unclear and changes the outcome.
+- The docs would describe behaviour you can't confirm in the code.
+- You'd delete or restructure existing docs that other pages or external sites may link to.
+
+## Report back
+
+Return the files you wrote or changed, the reader and document type each targets, which examples you ran (with the command) and which you didn't, and any doc-versus-code mismatches you found. For a guided walkthrough of code, use `code-tour`; for getting oriented yourself, use `codebase-onboarding`.

package/skills/technical-writing/evals/triggers.json

@@ -0,0 +1,14 @@
+{
+  "should_trigger": [
+    "Rewrite our README so someone new can install the CLI and run their first command in five minutes",
+    "Write a how-to guide for rotating API keys in our service",
+    "Our API reference is a mess, restructure the docs for the REST endpoints with examples for each",
+    "Nobody reads our getting-started docs. Can you make them task-first with runnable code samples?"
+  ],
+  "should_not_trigger": [
+    "I renamed the --verbose flag to --debug in this commit, sync the docs and changelog with that change",
+    "Walk me through this unfamiliar repo so I know how to build and run it",
+    "Create a file-by-file tour of the auth flow for new contributors",
+    "Write a blog post announcing our product launch for the marketing site"
+  ]
+}

package/skills/terraform-patterns/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: terraform-patterns
+description: Terraform and OpenTofu infrastructure-as-code practice, from root and child module layout, pinned providers and remote state with locking, through per-environment variables, reading a plan before apply, detecting drift, adopting existing resources with import blocks, and renaming or moving resources safely with moved and removed blocks instead of destroy and recreate. Use when writing or restructuring .tf code, setting up a state backend, reviewing what terraform plan will replace or destroy, or bringing hand-made cloud resources under Terraform.
+license: MIT
+compatibility: Any Agent Skills host. Needs terraform or tofu on PATH and cloud credentials for plan and apply. Commands are the same for both CLIs; substitute tofu for terraform when the project uses OpenTofu.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "terraform"
+  kete-loom/owner: "Kete-org"
+---
+
+# Terraform patterns
+
+Change infrastructure through code that plans cleanly, keeps state safe, and never destroys something by accident. Cloud-specific service choices belong to `aws-patterns`, `gcp-patterns` or `azure-patterns`; this skill covers the Terraform layer itself.
+
+## 0. Orient
+
+1. Detect the CLI: `.terraform.lock.hcl`, `required_version`, a `.terraform-version` / `.opentofu-version` file, or CI steps tell you whether it is `terraform` or `tofu`, and which version. Use that one throughout.
+2. Find the root modules (directories with a `backend` block or that CI runs `plan` in), the child modules (`modules/`), and how environments are split (separate root directories per env, workspaces, or a wrapper such as Terragrunt).
+3. Read the backend block. Note where state lives and whether locking is on.
+4. **Stop and ask the user** before `apply`, `destroy`, `import` on the CLI, any `state` subcommand that writes (`mv`, `rm`, `push`), `force-unlock`, or `init -migrate-state`. `fmt`, `validate`, `init` (without migration) and `plan` are fine.
+
+## 1. Layout
+
+```
+modules/
+  network/        main.tf variables.tf outputs.tf versions.tf README.md
+  service/
+envs/
+  dev/            main.tf backend.tf terraform.tfvars versions.tf
+  prod/
+```
+
+- One root module per environment (or per environment and component) with its own state. Keep blast radius small: networking, data stores and apps in separate states when they change at different rates.
+- Child modules take inputs and return outputs; they don't configure providers or backends. Pass providers explicitly (`providers = { aws = aws.eu }`) when a module needs an aliased one.
+- Pin versions: `required_version` in every root, and `required_providers` with a `~>` constraint. Commit `.terraform.lock.hcl` for root modules.
+- Pin module sources: registry modules with `version = "~> x.y"`, git sources with `?ref=<tag>`.
+- Prefer `for_each` over `count` for anything that has identity, so removing one item doesn't shift the indexes of every other.
+
+## 2. Variables and environments
+
+- Declare a `type` and `description` for every variable; add `validation` blocks for values with rules (CIDRs, allowed names).
+- Mark secrets `sensitive = true`, and better, don't pass them as variables at all: read them from a secret manager data source or have the service fetch them at runtime. Sensitive values are still stored in state in plain text.
+- Per-environment values in `envs/<env>/terraform.tfvars` or `-var-file`. Never commit a tfvars file containing secrets.
+- Use `locals` for derived names and common tags instead of repeating expressions.
+
+## 3. Remote state and locking
+
+- Never keep state for shared infrastructure on a laptop or in git. Use a remote backend with locking and encryption: S3 (with `use_lockfile = true` for S3-native locking on current Terraform; the older `dynamodb_table` locking is deprecated), GCS, `azurerm`, HCP Terraform, or the backend the team already uses. Examples are in `references/backends.md`.
+- Turn on versioning for the state bucket so a bad write can be recovered.
+- Restrict who can read state: it contains every attribute of every resource, including secrets.
+- Read another stack's outputs with `terraform_remote_state` or, better, a data source that looks the resource up, rather than copying IDs by hand.
+- If a lock is stale (a crashed run), confirm with the user that no run is in progress before `force-unlock <LOCK_ID>`.
+
+## 4. The plan is the review
+
+Run `terraform plan -out=tfplan` and read it before anything is applied.
+
+1. Read the summary line: `Plan: X to add, Y to change, Z to destroy`.
+2. Search the plan for `must be replaced`, `forces replacement` and `will be destroyed`. For each, name the attribute that forces it.
+3. Treat replacement or destruction of a stateful resource (databases, buckets, disks, DNS zones, KMS keys, clusters, IAM roles other systems depend on) as a stop: explain it to the user and propose an alternative (a `moved` block, `ignore_changes` for an attribute managed elsewhere, or an in-place change).
+4. Check for unexpected changes to resources you didn't touch: that is drift or a provider upgrade, not your change. Report it separately.
+5. Apply only the saved plan (`terraform apply tfplan`), so what runs is exactly what was reviewed.
+
+For machine-readable checks: `terraform show -json tfplan` and look at `resource_changes[].change.actions` for `"delete"`.
+
+Protect critical resources with `lifecycle { prevent_destroy = true }`, and use `create_before_destroy = true` where a replacement must not cause downtime.
+
+## 5. Drift
+
+- `terraform plan -refresh-only` shows what changed outside Terraform without proposing to revert it.
+- Decide per item with the user: bring the code in line with reality, or let the next apply revert the manual change. Don't silently revert a hotfix someone made in the console.
+- `-detailed-exitcode` (exit 2 means changes) lets CI detect drift on a schedule.
+
+## 6. Safe refactors
+
+Renaming or moving a resource address without telling Terraform plans a destroy and a create. Use config-driven blocks, which show up in the plan and get reviewed like any other change:
+
+```hcl
+moved {
+  from = aws_s3_bucket.logs
+  to   = module.logging.aws_s3_bucket.this
+}
+
+import {
+  to = aws_s3_bucket.assets
+  id = "my-existing-assets-bucket"
+}
+
+removed {
+  from = aws_instance.legacy
+  lifecycle { destroy = false }   # forget it, keep the real resource
+}
+```
+
+- `moved` for renames, `count` → `for_each`, and moving resources into or out of modules. The plan should then show no destroy for those addresses.
+- `import` blocks to adopt existing resources; `terraform plan -generate-config-out=generated.tf` drafts the matching configuration. Edit the generated code until plan shows no changes for the imported resource.
+- `removed` with `destroy = false` to stop managing something without deleting it.
+- These blocks need a reasonably recent CLI, and Terraform and OpenTofu added them (and options such as `removed`'s `lifecycle { destroy = false }`) in different releases. Check the docs for the CLI and version in `required_version`; if not, stop and ask before falling back to `terraform state mv` / `state rm`, which change state immediately and skip review.
+- Keep `moved` blocks in shared modules for at least one release so every caller's state migrates; remove `import` and `removed` blocks after the apply.
+
+## 7. Verify
+
+Run, and report each as pass or fail:
+
+1. `terraform fmt -check -recursive`
+2. `terraform init -backend=false` then `terraform validate` in each changed root (no credentials needed).
+3. Linters the project already uses (`tflint`, `checkov`, `trivy config`).
+4. `terraform plan` in each affected environment if credentials are available; paste the summary line and every replace or destroy.
+
+## Never
+
+- Never run `apply -auto-approve` or `destroy` on the user's behalf without explicit approval for that environment.
+- Never edit a state file by hand or commit `*.tfstate`, `.terraform/` or secret-bearing tfvars.
+- Never use `-target` as a routine workflow; it is for recovery, and leaves the rest of the config unreviewed.
+- Never upgrade a provider's major version as a side effect of another change.
+
+## Report back
+
+End with: CLI and version, roots changed, the plan summary per environment (add/change/destroy) with every replacement or destroy named and justified, the verification commands with pass or fail, and anything you could not plan because of missing credentials.

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

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "I renamed a resource in our Terraform and now plan wants to destroy and recreate the database",
+    "Set up an S3 remote state backend with locking for our Terraform project",
+    "We created a bunch of buckets by hand in the console, how do I bring them under Terraform?",
+    "Restructure our tf code into reusable modules with separate dev and prod environments",
+    "terraform plan shows changes nobody made, how do I check for drift?"
+  ],
+  "should_not_trigger": [
+    "Should we use Cloud Run or GKE for this service on Google Cloud?",
+    "Write a Kubernetes Deployment with resource limits for the API",
+    "Review this terraform plan output and the k8s manifests for risky or destructive changes",
+    "Add a GitHub Actions job that builds and pushes our Docker image",
+    "Containerise the Python worker with a slim base image"
+  ]
+}

package/skills/terraform-patterns/references/backends.md

@@ -0,0 +1,67 @@
+# Remote state backends
+
+Check the backend's docs for your CLI version before copying; argument names change between releases.
+
+## AWS S3 (S3-native locking)
+
+```hcl
+terraform {
+  backend "s3" {
+    bucket       = "acme-terraform-state"
+    key          = "prod/network/terraform.tfstate"
+    region       = "eu-west-1"
+    encrypt      = true
+    use_lockfile = true   # writes a .tflock object next to the state
+  }
+}
+```
+
+- The bucket should have versioning on, public access blocked, and default encryption (SSE-S3 or SSE-KMS).
+- With `use_lockfile`, the caller needs `s3:GetObject`, `s3:PutObject` and `s3:DeleteObject` on the lock object as well as the state object.
+- Migrating from `dynamodb_table` locking: the two can be set together during the transition. Add `use_lockfile = true`, run `terraform init -reconfigure`, confirm runs create the `.tflock` object, then remove `dynamodb_table`.
+
+## Google Cloud Storage
+
+```hcl
+terraform {
+  backend "gcs" {
+    bucket = "acme-terraform-state"
+    prefix = "prod/network"
+  }
+}
+```
+
+GCS locks natively. Enable object versioning on the bucket.
+
+## Azure Storage
+
+```hcl
+terraform {
+  backend "azurerm" {
+    resource_group_name  = "rg-terraform"
+    storage_account_name = "acmetfstate"
+    container_name       = "tfstate"
+    key                  = "prod/network.tfstate"
+  }
+}
+```
+
+Azure locks via blob leases. Enable blob versioning or soft delete on the storage account.
+
+## Partial configuration
+
+Keep environment-specific backend values out of shared code:
+
+```hcl
+terraform {
+  backend "s3" {}
+}
+```
+
+```sh
+terraform init -backend-config=backend.prod.hcl
+```
+
+## Changing backends
+
+`terraform init -migrate-state` copies state to the new backend. Before running it: confirm with the user, take a copy with `terraform state pull > backup.tfstate` (store it securely, it contains secrets), and make sure no other run is in progress.

package/skills/test-coverage-improvement/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: test-coverage-improvement
+description: Raises meaningful test coverage by measuring line and branch coverage, ranking untested code by risk and churn, adding tests that pin observable behaviour rather than executing lines, and using mutation testing (Stryker, PIT, mutmut, cargo-mutants, Infection) to prove the new tests catch faults. Use when coverage is low or below a CI threshold, when asked where tests are missing in a module, or when a team wants coverage numbers they can trust.
+license: MIT
+compatibility: Any Agent Skills host. Needs the project's test runner and its coverage tool; mutation testing tools are optional.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# Test coverage improvement
+
+Coverage tells you what code ran during tests, not what was checked. The goal is fewer escaped bugs, so spend tests where a bug would hurt and make every test assert something a user or caller would notice.
+
+## 1. Measure the baseline
+
+1. Find the existing coverage command in CI, package scripts or the Makefile. Use it if it exists.
+2. Otherwise run the language default with **branch** coverage on where the tool supports it (Go reports statement coverage only; `cargo llvm-cov --branch` needs a nightly toolchain):
+
+| Stack | Command |
+|---|---|
+| Jest | `npx jest --coverage` |
+| Vitest | `npx vitest run --coverage` (needs `@vitest/coverage-v8`) |
+| Python | `pytest --cov=<pkg> --cov-branch --cov-report=term-missing` (pytest-cov) |
+| Go | `go test -coverprofile=cover.out ./...` then `go tool cover -func=cover.out` |
+| Rust | `cargo llvm-cov` (cargo-llvm-cov) or `cargo tarpaulin` |
+| Java | JaCoCo via `mvn verify` or `gradle jacocoTestReport` |
+| .NET | `dotnet test --collect:"XPlat Code Coverage"` |
+| PHP | `vendor/bin/phpunit --coverage-text` (needs Xdebug or PCOV) |
+
+3. Record: total line %, branch %, and the per-file numbers. If the suite fails, **stop and tell the user** first; coverage from a red suite is meaningless.
+4. If adding a coverage tool would add a dependency the project doesn't have, ask before installing it.
+
+## 2. Find the risky gaps
+
+Do not sort by "lowest %". Rank untested code by risk:
+
+1. **Money, auth, permissions, data deletion, migrations** and anything security-sensitive.
+2. **Branches with no test**: `else` paths, error handlers, early returns, `catch` blocks, default cases. Branch coverage reports show these as partial lines.
+3. **High churn**: files changed often recently (`git log --since=6.months --name-only --format= | sort | uniq -c | sort -rn | head -20`). Churn plus low coverage is where regressions come from.
+4. **Recent bugs**: code touched by recent fix commits.
+5. Public API used by many callers.
+
+Skip, and say you skipped: generated code, trivial getters and setters, framework glue with no logic, and code scheduled for deletion. Prefer excluding them in coverage config (with a comment) over writing hollow tests.
+
+Write the top 5 to 10 targets as a list with the reason each one is risky, and confirm with the user if the list is long.
+
+## 3. Write behaviour tests
+
+For each target:
+
+- Name the behaviour: "rejects a refund larger than the original charge", not "test refund function".
+- Drive it through the public interface the callers use.
+- Assert the observable result: return value, raised error and its type or message, state persisted, message sent. One behaviour per test.
+- Cover the branch you found: the error path, the boundary (0, 1, max, empty, null), the permission denied case.
+- Mock only external boundaries (network, clock, randomness, third-party services). Never mock the unit under test or its own collaborators just to reach a line.
+- Follow the existing test style, folders and fixtures.
+
+A test that would pass if the code under test returned a wrong value is not a test. Avoid:
+
+- No assertion, or `expect(result).toBeDefined()` / `assert result is not None` as the only check.
+- Snapshotting large output nobody reviews.
+- Asserting that a mock was called, without checking the outcome.
+- Calling a function in a loop over inputs just to light up lines.
+
+## 4. Check with mutation testing
+
+Mutation testing changes the code (flips `>` to `>=`, removes a call, returns a constant) and reruns the tests. A surviving mutant is a fault your tests don't catch.
+
+| Stack | Tool | Run |
+|---|---|---|
+| JS/TS | StrykerJS | `npx stryker run` |
+| Java/Kotlin (JVM) | PIT | `mvn org.pitest:pitest-maven:mutationCoverage` |
+| Python | mutmut | `mutmut run`, then `mutmut results` |
+| Rust | cargo-mutants | `cargo mutants` |
+| PHP | Infection | `vendor/bin/infection` |
+| C# | Stryker.NET | `dotnet stryker` |
+
+- Scope it to the files you just tested; a full-repo run can take hours.
+- For each surviving mutant: add or sharpen an assertion that kills it, or note it as equivalent (the change cannot alter behaviour).
+- If no tool exists for the stack, do it by hand for the riskiest function: break one condition, run the tests, confirm one fails, revert.
+
+## 5. Re-measure and lock in
+
+1. Rerun the coverage command. Report before and after for the files you touched, line and branch.
+2. If CI has a threshold, meet it. If it has none, suggest a ratchet (fail only if coverage drops) rather than an arbitrary target.
+3. Run the full suite twice to check the new tests are deterministic.
+
+## Rules
+
+- Never delete, skip or weaken existing tests to change the number.
+- Never add tests that assert current buggy behaviour without flagging it. If you find a bug, **stop and tell the user**, and write the test for the correct behaviour marked as expected-to-fail only if they agree.
+- Never exclude risky code from coverage to raise the percentage.
+- Don't chase 100 %. Stop when the risky list is covered and mutants are killed.
+
+## Report back
+
+```
+Coverage: <line>% → <line>% lines, <branch>% → <branch>% branches (files touched)
+Tests added: <file>: <test names>
+Mutation: <killed>/<total> killed in <files>; survivors: <list or none>
+Bugs found: <list or none>
+Not covered, on purpose: <items and why>
+Command: <exact commands run>
+```

package/skills/test-coverage-improvement/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Our coverage is stuck at 52% and CI wants 70, add tests where they actually matter",
+    "Which parts of the billing module have no tests? Fill the important gaps",
+    "Run mutation testing on the discount rules and tighten the tests that let mutants survive",
+    "We have 90% line coverage but bugs still slip through, make the tests mean something",
+    "Find the untested error-handling branches in src/payments and cover them"
+  ],
+  "should_not_trigger": [
+    "Implement the CSV export feature test-first",
+    "Look at the tests in this PR and list the cases that are missing for the changed code",
+    "Add a Playwright test for the password reset journey",
+    "Benchmark the new JSON parser against the old one",
+    "Run the build, lint and tests and tell me if my branch is green"
+  ]
+}