@ketecode/loom 0.0.0-stage → 0.1.0

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

package/skills/github-actions-ci/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: github-actions-ci
+description: Writes, hardens and debugs GitHub Actions workflows under .github/workflows, including triggers and job structure, dependency caching, build matrices, reusable workflows and composite actions, keyless OIDC login to AWS, Google Cloud and Azure, least-privilege GITHUB_TOKEN permissions, SHA-pinned third-party actions, and diagnosing red runs from their logs. Use when creating or editing a GitHub Actions workflow YAML, speeding up a slow pipeline, removing stored cloud keys from CI, or figuring out why a GitHub Actions job failed.
+license: MIT
+compatibility: Any Agent Skills host. Reading run logs and re-running jobs needs the GitHub CLI (gh) authenticated to the repository.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git, gh"
+  kete-loom/owner: "Kete-org"
+---
+
+# GitHub Actions CI
+
+Make workflows that are fast, give every job only the permissions it needs, never store long-lived cloud keys, and fail with logs you can act on. Release rollout strategy lives in `deployment-strategies`; versioning and changelogs in `release-management`; the cloud-side roles in `aws-patterns`, `gcp-patterns` and `azure-patterns`.
+
+## Ground rules
+
+1. **Set `permissions` explicitly.** At the top of every workflow put `permissions: contents: read`, then widen per job only where needed (`pull-requests: write`, `id-token: write`, `packages: write`). Don't rely on the repository default.
+2. **Pin third-party actions to a full commit SHA**, with the version in a comment: `uses: some-org/some-action@<40-char-sha> # v2.3.1`. Tags can be moved; SHAs can't. Let Dependabot or Renovate (`package-ecosystem: github-actions`) keep pins current. Actions owned by `actions/` and your own org may use tags if the team's policy allows, but SHAs are still safer.
+3. **No cloud access keys in secrets.** Use OIDC (below). Secrets that must exist (API tokens for third parties) live in environment secrets with required reviewers for production.
+4. **Never interpolate untrusted input into `run:`.** `${{ github.event.pull_request.title }}`, branch names, issue bodies and commit messages are attacker-controlled. Pass them through `env:` and quote the shell variable.
+5. **Treat `pull_request_target` and `workflow_run` as privileged.** They run with secrets and a write token. Never check out and run the PR's code in them. Use plain `pull_request` for building and testing contributions.
+6. **Bound every job:** `timeout-minutes` on each job (the default is hours), and `concurrency` so a new push cancels stale runs of the same branch.
+
+## Workflow skeleton
+
+```yaml
+name: ci
+on:
+  pull_request:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [20, 22]
+    steps:
+      - uses: actions/checkout@<sha> # vN
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@<sha> # vN
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+      - run: npm ci
+      - run: npm test
+```
+
+Adapt the setup action and commands to the project's language. Find the real test and build commands in the README, `package.json`, `Makefile` or equivalent before writing them.
+
+## Caching
+
+1. Prefer the setup action's built-in cache (`cache: npm | pip | gradle | maven`, Go and others have their own) over hand-written cache steps.
+2. With `actions/cache`, key on the OS plus a hash of the lockfile: `key: ${{ runner.os }}-deps-${{ hashFiles('**/package-lock.json') }}` and a `restore-keys` prefix for partial hits.
+3. Cache dependency downloads, not build outputs that hide stale-code bugs. Never cache anything containing secrets.
+4. For Docker builds use BuildKit cache (`cache-from` / `cache-to` with `type=gha`) in the build action.
+
+## Matrices and reuse
+
+- `strategy.matrix` for versions and OSes; `include` / `exclude` to trim combinations; `fail-fast: false` when you need every result. Keep matrices small: each cell is a billed job.
+- **Reusable workflows** (`on: workflow_call` with typed `inputs` and declared `secrets`) for whole pipelines shared across repos. Call with `uses: org/repo/.github/workflows/build.yml@<sha-or-tag>`. Pass only the secrets the callee needs; use `secrets: inherit` only within the same trust boundary.
+- **Composite actions** (`action.yml` with `runs: using: composite`) for a few repeated steps inside jobs.
+- Pass data between jobs with `outputs` (small values) or artifacts (files). Don't rebuild the same artifact in a deploy job: build once, deploy that artifact.
+
+## OIDC to clouds (no stored keys)
+
+The job needs `permissions: id-token: write` (plus `contents: read`). The cloud must trust GitHub's issuer `https://token.actions.githubusercontent.com` and restrict the token's `sub` claim to this repo and, for deploys, to a branch or environment (for example `repo:org/app:environment:production`).
+
+| Cloud | Action | Inputs | Cloud side |
+|---|---|---|---|
+| AWS | `aws-actions/configure-aws-credentials` | `role-to-assume`, `aws-region` | IAM OIDC provider + role trust policy with `aud` = `sts.amazonaws.com` and a `sub` condition |
+| Google Cloud | `google-github-actions/auth` | `workload_identity_provider`, `service_account` | Workload Identity pool + provider with an attribute condition on `assertion.repository`, then `roles/iam.workloadIdentityUser` on the service account |
+| Azure | `azure/login` | `client-id`, `tenant-id`, `subscription-id` | Federated credential on an app registration or user-assigned managed identity, subject matching the branch or environment |
+
+Never accept a trust condition that allows any repository or any branch to assume a production role. If the user asks for one, **stop and explain** why first.
+
+## Debugging a failed run
+
+1. Get the failure: `gh run list --workflow <name> --limit 5`, then `gh run view <run-id> --log-failed`. Read the first error, not the last line.
+2. Classify it:
+   - **Code or test failure:** reproduce locally with the same command and versions as the matrix cell.
+   - **Environment drift:** `ubuntu-latest` moved, a tool version changed, a cache restored stale content. Pin the version or bump the cache key.
+   - **Permissions:** `Resource not accessible by integration` or 403 means the job's `permissions` block lacks a scope. Add only that scope to that job.
+   - **OIDC:** `Not authorized to perform sts:AssumeRoleWithWebIdentity` or similar means the `sub`/`aud` condition doesn't match. Compare the condition with the run's ref or environment.
+   - **Secret empty or missing:** runs from forked-repo pull requests get no secrets (except `GITHUB_TOKEN`, read-only). Don't switch to `pull_request_target` to get them; move the secret-needing step to a post-merge workflow.
+   - **Workflow never started:** events caused by `GITHUB_TOKEN` (a push or PR opened by another workflow) don't start new runs, except `workflow_dispatch` and `repository_dispatch`. Check the `on:` filters (`branches`, `paths`) too.
+   - **Flaky:** passes on `gh run rerun <run-id> --failed` with no change. Report it as flaky; don't paper over it with retries without telling the user.
+3. For more detail, re-run with debug logging (the UI option, or set the repository secret or variable `ACTIONS_STEP_DEBUG` to `true`; `ACTIONS_RUNNER_DEBUG` adds runner diagnostics).
+4. Lint workflows with `actionlint` if available before pushing.
+
+## Never
+
+- Use `permissions: write-all`, or leave a deploy job without an `environment` protection rule.
+- Echo secrets, or write them to files that get uploaded as artifacts.
+- Add `continue-on-error: true` to hide a failing step.
+- Push workflow changes to the default branch without the user seeing the diff.
+
+## Report format (reviews and fixes)
+
+```
+Workflow: <file>
+Findings: <severity> <line> <issue> -> <fix>
+Changed: <what you edited>
+Verified: <run id or local command and result>
+Still open: <anything you could not verify>
+```

package/skills/github-actions-ci/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Add a GitHub Actions workflow that runs our tests on Node 20 and 22 on every pull request",
+    "Our CI keeps reinstalling dependencies every run, add caching to the workflow",
+    "Replace the AWS_ACCESS_KEY_ID secret in our deploy workflow with OIDC",
+    "Why does this Actions job fail with Resource not accessible by integration?",
+    "Harden our workflows: pin third-party actions to SHAs and restrict GITHUB_TOKEN permissions"
+  ],
+  "should_not_trigger": [
+    "Plan how to roll out the new payments service gradually with a canary and rollback",
+    "Write conventional commit messages for these staged changes",
+    "Cut a release, bump the version and generate the changelog",
+    "Write a multi-stage Dockerfile for our Go service",
+    "Set up least-privilege IAM for an S3 bucket our app reads from"
+  ]
+}

package/skills/github-api-automation/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: github-api-automation
+description: Scripts and services that drive GitHub through the gh CLI, the REST and GraphQL APIs or a GitHub App, covering the choice between fine-grained tokens and app installation tokens, JWT-to-installation-token exchange, Link-header and cursor pagination, primary and secondary rate limits, X-Hub-Signature-256 webhook verification, and the Actions REST endpoints for dispatching, re-running and reading workflow runs. Use when writing a bot, sync job or webhook receiver that calls the GitHub API, choosing between a PAT and a GitHub App, or debugging 403 rate-limit or signature failures from GitHub.
+license: MIT
+compatibility: Any Agent Skills host. Live calls need network access to api.github.com (or a GitHub Enterprise Server host). Examples use the gh CLI and plain HTTP; the rules apply to Octokit and other SDKs.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: integrations
+  kete-loom/risk: network
+  kete-loom/requires: "gh"
+  kete-loom/owner: "Kete-org"
+---
+
+# GitHub API automation
+
+Build GitHub automation that uses the least-privileged credential, pages through every result, backs off before GitHub bans it, and trusts a webhook only after its signature checks out. Writing workflow YAML under `.github/workflows` is a different job; this skill is about calling GitHub from code or the shell.
+
+## Ground rules
+
+1. **Least privilege.** Ask for the narrowest repository access and permissions that do the job. Never use a classic PAT with `repo` scope for a shared service.
+2. **Secrets from the environment** (`GH_TOKEN`, app private key, webhook secret). Never commit them, log them or pass them on a command line other processes can read.
+3. **Pin the API version** with `X-GitHub-Api-Version`. Supported values are `2022-11-28` (the default when the header is omitted) and `2026-03-10`. Also send `Accept: application/vnd.github+json` and a `User-Agent`.
+4. **Read before you write.** Dry-run bulk changes (labels, branch protection, repo settings) by printing the planned calls first.
+5. **Webhooks are verified, deduplicated and acknowledged fast.**
+
+## Choose the credential
+
+| Situation | Use |
+|---|---|
+| One-off script on your own machine | `gh auth login`, then `gh api` |
+| Personal automation on a few repos | Fine-grained PAT scoped to those repos, with an expiry |
+| Inside a GitHub Actions job | The job's `GITHUB_TOKEN`, with `permissions:` set in the workflow |
+| Bot or service acting for an org, or across many orgs | GitHub App with an installation token |
+| Acting as the signed-in user in your web app | GitHub App user access token (OAuth flow), not an OAuth App, unless you need something only OAuth Apps support |
+
+Stop and ask the user before choosing a credential that will be shared by a team or deployed to production, and before requesting any `administration`, `secrets` or org-level write permission.
+
+## GitHub App auth
+
+1. Create the app with only the permissions and events it needs. Store the private key (PEM) as a secret.
+2. Sign a JWT with RS256: `iat` about 60 seconds in the past (clock drift), `exp` no more than 10 minutes ahead, `iss` set to the app's client ID (or app ID).
+3. Find the installation: `GET /repos/{owner}/{repo}/installation` or `GET /app/installations` with the JWT.
+4. Exchange: `POST /app/installations/{installation_id}/access_tokens`, optionally with `repositories` and `permissions` to narrow it further. The token lasts one hour; cache it and refresh a few minutes before `expires_at`.
+5. Call the API with `Authorization: Bearer <installation token>`. Never send the JWT to anything other than the `/app` endpoints.
+
+## Pagination
+
+- REST: request `per_page=100` (the maximum on most endpoints) and follow the `Link` header's `rel="next"` URL until it is absent. Never build page numbers yourself on endpoints that return cursor links.
+- `gh api --paginate repos/{owner}/{repo}/issues` follows links for you; add `--slurp` to merge pages into one JSON array before piping to `jq`.
+- GraphQL: request `first: 100` (1 to 100 allowed) with `pageInfo { hasNextPage endCursor }`, then pass `endCursor` as `after`. `gh api graphql --paginate` works when the query takes a `$endCursor` variable.
+- Use the search API only for searching; it has its own lower rate limit and caps results at 1,000 per query.
+
+## Rate limits
+
+Primary limits per hour (check the docs, they change): unauthenticated 60; PAT or user token 5,000; app installation starts at 5,000 and scales to 12,500 (15,000 on Enterprise Cloud); `GITHUB_TOKEN` 1,000 per repo. GraphQL is budgeted separately in points.
+
+Secondary limits apply on top: at most 100 concurrent requests, a points-per-minute budget per endpoint (writes cost more than reads), and about 80 content-creating requests per minute.
+
+Rules:
+
+1. Read `x-ratelimit-remaining` and `x-ratelimit-reset` (epoch seconds) on every response. `GET /rate_limit` shows the buckets.
+2. On 403 or 429: if `retry-after` is present, wait that many seconds; else if `x-ratelimit-remaining` is `0`, wait until `x-ratelimit-reset`; else wait at least one minute. Then back off exponentially and give up after a fixed number of attempts.
+3. Make writes serially, not in parallel. Prefer conditional requests (`If-None-Match` with the stored `ETag`; a 304 does not count against the primary limit when authorised).
+4. Prefer webhooks to polling.
+
+## Webhooks
+
+1. Set a random secret on the webhook or app. Verify `X-Hub-Signature-256`: it is `sha256=` plus the hex HMAC-SHA256 of the **raw** body with that secret. Compute it before any JSON parsing and compare with a constant-time function. Reject with 401 on mismatch. Never fall back to the legacy SHA-1 `X-Hub-Signature`.
+2. Respond `2xx` within 10 seconds; queue the real work.
+3. Deduplicate on `X-GitHub-Delivery` (a GUID per delivery; redeliveries reuse it). Route on `X-GitHub-Event` plus the payload's `action`.
+4. GitHub does not retry failed deliveries automatically. To recover, list failed deliveries (`GET /app/hook/deliveries` for an app, or the repo/org hook deliveries endpoint) and redeliver them.
+5. Ignore events from your own bot (check `sender.type == "Bot"` and the login) to avoid loops.
+6. Local testing: `gh webhook forward --repo=OWNER/REPO --events=issues --url=http://localhost:3000/webhook` (a gh extension, `cli/gh-webhook`) or a smee.io channel.
+
+## Actions API
+
+| Task | Call |
+|---|---|
+| Start a workflow with inputs | `POST /repos/{owner}/{repo}/actions/workflows/{workflow_id or file name}/dispatches` with `ref` and `inputs`; the workflow must declare `workflow_dispatch`. `gh workflow run deploy.yml -f env=staging` |
+| List or watch runs | `GET /repos/{owner}/{repo}/actions/runs?branch=&status=`; `gh run list`, `gh run watch <id>` |
+| Re-run | `POST .../actions/runs/{run_id}/rerun` or `.../rerun-failed-jobs`; `gh run rerun <id> --failed` |
+| Cancel | `POST .../actions/runs/{run_id}/cancel` |
+| Logs | `GET .../actions/runs/{run_id}/logs` returns a redirect to a zip; `gh run view <id> --log-failed` |
+| Artifacts | `GET .../actions/runs/{run_id}/artifacts`; `gh run download <id>` |
+| Secrets | Encrypt with the repo public key (`GET .../actions/secrets/public-key`, libsodium sealed box) before `PUT`; or `gh secret set NAME` |
+
+By default a dispatch returns `204` with no body. Send `"return_run_details": true` in the body to get `200` with the new run's details (added February 2026; `gh` 2.87.0+ does this by default); check the REST reference for the field names. On GitHub Enterprise Server versions without it, list runs for that workflow and ref created after your request time, or pass a correlation ID as an input and match it in `run-name`.
+
+## Reviewing existing automation
+
+Look for: a classic PAT or admin token where an app or `GITHUB_TOKEN` would do; tokens in logs or URLs; only the first page read; parallel write loops with no backoff; retries on 403 that ignore `retry-after`; webhook handlers that parse JSON before verifying, use `==` to compare signatures, or skip verification when the header is missing; no dedupe on `X-GitHub-Delivery`; bots that react to their own events.
+
+## Stop and ask the user
+
+- Before any bulk write across many repositories (settings, branch protection, deleting branches, archiving).
+- Before creating or rotating secrets, deploy keys or app private keys.
+- Before granting an app org-wide installation instead of selected repositories.
+
+## Before you finish
+
+Test with a throwaway repository: run the job twice (idempotent), force a page boundary (more than 100 items), send a webhook with a wrong signature (rejected), redeliver a webhook (processed once), and check the rate-limit headers in a log line. GitHub's REST and GraphQL docs at docs.github.com are the final word on endpoints and limits.

package/skills/github-api-automation/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Write a script that uses gh api to add a label to every open issue across our org's repos",
+    "Should our PR bot use a fine-grained personal access token or a GitHub App installation token?",
+    "Our GitHub webhook receiver needs to verify X-Hub-Signature-256 before processing push events",
+    "The sync job hits 403 secondary rate limit errors from api.github.com, how do I back off properly?",
+    "Trigger a workflow_dispatch run from our deploy service through the REST API and wait for it to finish",
+    "Fetch every pull request with its review comments via the GraphQL API using cursor pagination"
+  ],
+  "should_not_trigger": [
+    "Add a GitHub Actions workflow that lints and tests on every pull request",
+    "Speed up the dependency cache step in our .github/workflows/test.yml",
+    "Create a Jira issue automatically when a build fails",
+    "Post a message to a Slack channel when a deploy finishes",
+    "Sync our Linear issues into a weekly report"
+  ]
+}

package/skills/go-patterns/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: go-patterns
+description: Idiomatic Go for writing and restructuring code, covering package layout, error wrapping with %w and errors.Is/As, small consumer-side interfaces, context.Context propagation, goroutine and channel patterns that do not leak or race, Go modules hygiene, and golangci-lint setup. Use when writing new Go code, designing a Go package or service, choosing between channels and mutexes, or asking how a Go project should be structured.
+license: MIT
+compatibility: Any Agent Skills host. Needs the go toolchain; golangci-lint is optional.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "go"
+  kete-loom/owner: "Kete-org"
+---
+
+# Go patterns
+
+Write Go that reads like the standard library: plain, explicit, and boring on purpose. Follow the project's existing conventions first; these rules fill the gaps.
+
+## 0. Before you write
+
+1. Read `go.mod` for the module path and the `go` directive. Do not use language or library features newer than that version.
+2. Check for `.golangci.yml` / `.golangci.yaml`, a `Makefile` or CI workflow, and use the lint and test commands they define.
+3. Search the codebase for an existing helper, error type or interface before adding a new one.
+
+## 1. Package layout
+
+- One package per directory, named for what it provides (`invoice`, not `utils`, `common` or `helpers`). Package names are short, lower case, no underscores.
+- `cmd/<binary>/main.go` for each executable; keep `main` thin (parse config, wire dependencies, call `run(ctx) error`).
+- `internal/` for code other modules must not import. Prefer it by default for application code.
+- Do not create `pkg/`, `models/` or layer-per-folder trees unless the project already uses them. Start flat; split a package when it has two clearly separate jobs.
+- Avoid stutter: `invoice.New`, not `invoice.NewInvoice`; `http.Client`, not `http.HTTPClient`.
+- No package-level mutable state except where unavoidable (registered metrics, `flag`). Pass dependencies in.
+
+## 2. Errors
+
+- Return `error` as the last result. Check it immediately; never assign it to `_` without a comment saying why it is safe.
+- Add context when you return: `fmt.Errorf("load invoice %s: %w", id, err)`. Lower case, no trailing punctuation, no "failed to" prefix chains.
+- Use `%w` only when callers may need to inspect the cause. Use `%v` when the cause is an implementation detail you do not want in your API.
+- Inspect with `errors.Is(err, ErrNotFound)` and `errors.As(err, &target)`. Never compare `err.Error()` strings, and never use `==` on a possibly wrapped error.
+- Sentinel errors: `var ErrNotFound = errors.New("invoice: not found")`. Custom types when callers need fields (`*ValidationError{Field string}`).
+- Combine independent failures (for example several `Close` calls) with `errors.Join`.
+- Handle an error once: either log it or return it, not both.
+- `panic` only for programmer errors that cannot happen in correct code. Never panic across a package boundary for expected failures.
+
+## 3. Interfaces
+
+- Define interfaces where they are **used**, not where they are implemented. Keep them to the one or two methods the consumer needs.
+- Functions accept interfaces and return concrete types (`func NewStore(db *sql.DB) *Store`).
+- Do not create an interface for a single implementation "for mocking later". Add it when a second implementation or a test fake needs it.
+- Assert compliance at compile time when it matters: `var _ io.Reader = (*Decoder)(nil)`.
+- A nil pointer stored in an interface is not a nil interface. Return a literal `nil` for "no error", never a typed nil `*MyError`.
+
+## 4. Context
+
+- `ctx context.Context` is the first parameter of anything that does I/O, blocks, or calls something that does. Name it `ctx`.
+- Pass the caller's context down. Never store a context in a struct, and never pass `nil` (use `context.TODO()` while wiring).
+- `context.Background()` belongs in `main`, tests and top-level goroutines that outlive a request, nowhere else.
+- Every `WithCancel`, `WithTimeout`, `WithDeadline` is followed by `defer cancel()`.
+- Context values carry request-scoped data only (trace IDs, auth principal) under an unexported key type. Never pass optional parameters through them.
+- Long loops and blocking selects check `ctx.Done()` and return `ctx.Err()`.
+
+## 5. Goroutines and channels
+
+Rule: **every goroutine you start has a clear owner, a way to stop, and someone who waits for it.**
+
+- Use `sync.WaitGroup` or `golang.org/x/sync/errgroup` to wait. Call `wg.Add` before the `go` statement, never inside the goroutine; on Go 1.25+ `wg.Go(func() { ... })` does both. With errgroup, use `errgroup.WithContext` so the first error cancels the rest, and `g.SetLimit(n)` to bound concurrency.
+- A goroutine that sends on a channel must be able to exit if nobody receives: select on `ctx.Done()` too, or use a buffered channel sized to the number of sends.
+- The sender closes a channel, never the receiver. Close once. Ranging over a channel ends only when it is closed.
+- Prefer a `sync.Mutex` guarding a field over a channel when you only protect shared state. Use channels to hand off ownership or signal events.
+- Keep the mutex next to the fields it guards and document which ones. Do not copy a struct containing a mutex (pass a pointer).
+- `time.After` in a hot loop allocates a timer per iteration; use a `time.Ticker` or a reused `time.NewTimer`. Before Go 1.23 an unstopped timer or ticker was not collected until it fired, so always `Stop` them on older modules.
+- Never start goroutines in `init` or in a library constructor without a `Close`/`Stop` method.
+
+Worked patterns (worker pool, fan-out with errgroup, pipeline with cancellation, graceful HTTP shutdown) are in `references/concurrency.md`. Read it before writing any of those shapes.
+
+## 6. Modules and dependencies
+
+- Add a dependency with `go get example.com/mod@vX.Y.Z`, then `go mod tidy`. Commit `go.mod` and `go.sum` together.
+- Prefer the standard library. Check whether `net/http`, `log/slog`, `encoding/json`, `slices`, `maps` already do the job before adding a package.
+- `replace` directives are for local development or a temporary fork. Do not commit a `replace` pointing at a local path unless the repo already does.
+- Use `go.work` for multi-module local work; do not commit it unless the repo already does.
+
+## 7. Style details that matter
+
+- `gofmt` (or `goimports`) every file. Unformatted Go is a defect.
+- Zero values should be useful: `var buf bytes.Buffer` works without a constructor; design your types the same way where you can.
+- Slices: `append` may reuse the backing array. When you return or store a subslice the caller might append to, copy it (`slices.Clone`) or use a full slice expression `s[lo:hi:hi]`.
+- Maps are not safe for concurrent writes. Guard them or use `sync.Map` only for its documented cases.
+- `defer f.Close()` on a file you wrote to loses the write error; check the `Close` error for writers.
+- Use `log/slog` for structured logging if the project has no logger yet.
+- Exported identifiers get a doc comment that starts with the identifier's name.
+
+## 8. Lint and verify
+
+Run, in order, and fix what they report in code you touched:
+
+1. `gofmt -l .` (must print nothing) or the project's format command.
+2. `go vet ./...`
+3. `golangci-lint run ./...` if the project has a config or the user wants it. For a new config, keep `linters.default: standard` (errcheck, govet, ineffassign, staticcheck, unused) and enable extras such as `errorlint`, `bodyclose` and `contextcheck` only as needed. golangci-lint v2 configs begin with `version: "2"`; run `golangci-lint migrate` to convert a v1 file.
+4. `go test -race ./...`
+
+Do not silence a linter with `//nolint` unless you name the linter and give the reason: `//nolint:errcheck // best-effort cleanup`.
+
+## Stop and ask the user
+
+- Before restructuring packages or moving files across `internal/` boundaries.
+- Before adding a third-party dependency for something the standard library covers.
+- Before changing an exported API (signature, error values) that other modules may import.
+
+## Never
+
+- Ignore an error silently, or `log.Fatal` outside `main`.
+- Start a goroutine with no way to stop it.
+- Use `interface{}`/`any` where a concrete type or a generic type parameter would do.
+- Add generics for code that only has one type today.
+
+## Report back
+
+End with: files changed, the format/vet/lint/test commands you ran and their results, and anything you chose not to change.

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

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "How should I lay out the packages for a new Go HTTP service with a CLI and a worker?",
+    "Write a Go function that fetches 200 URLs concurrently, at most 10 at a time, and stops on the first error",
+    "Should I wrap this error with %w or %v, and how do callers check for ErrNotFound in Go?",
+    "Design a small interface in my Go code so the billing package doesn't depend on the postgres store",
+    "Set up golangci-lint for our Go repo and fix the idiomatic issues it finds in the new package",
+    "Where should context.Context go in these Go function signatures, and should I keep it on the struct?"
+  ],
+  "should_not_trigger": [
+    "Write table-driven tests with subtests for my Go parser and run them with -race",
+    "Review this Go pull request for goroutine leaks and ignored errors",
+    "go build fails with 'missing go.sum entry for module providing package', fix it",
+    "Refactor this TypeScript service to use dependency injection",
+    "Explain Rust ownership and borrowing for a Go developer"
+  ]
+}