@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/release-management/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: release-management
+description: Ships a software release end to end - deciding the next semantic version from what changed, updating the changelog, tagging, writing release notes for users, cutting alpha/beta/rc pre-releases, patching an old version from a hotfix branch, and wiring up release tooling such as release-please, semantic-release or Changesets. Use when preparing or publishing a release, picking a version number, turning merged work into release notes, shipping a hotfix to an already-released line, or automating versioning and changelogs.
+license: MIT
+compatibility: Any Agent Skills host. Needs git. Publishing steps need the project's package manager and, for GitHub releases, the gh CLI.
+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"
+---
+
+# Release management
+
+A release is a promise: this exact commit, with this version number, does what the notes say. Work through the steps in order and stop at each checkpoint marked **ask**.
+
+## 0. Find the existing process
+
+1. Look for release tooling and docs: `RELEASING.md`, `CONTRIBUTING.md`, `release-please-config.json`, `.release-please-manifest.json`, `.releaserc*`, `release.config.*` or a `release` key in `package.json` (semantic-release), `.changeset/` (Changesets), `cliff.toml` (git-cliff), `.goreleaser.yaml`, and release workflows in `.github/workflows/`.
+2. If a tool owns versioning, **use the tool**. Don't hand-edit versions or changelogs it generates; that causes drift or a double bump.
+3. Find every place the version lives: `package.json`, `pyproject.toml`, `Cargo.toml`, `*.csproj`, `build.gradle*`, `pubspec.yaml`, plugin manifests, a `VERSION` file, constants in code. Search the codebase for the current version string to catch the rest.
+4. Find the last release: `git describe --tags --abbrev=0` and `git tag --sort=-v:refname | head`.
+
+## 1. Check the release is ready
+
+- `git fetch --tags --prune`, and confirm you are on the release branch (usually the default branch) with a clean tree and nothing unpushed.
+- CI is green for the exact commit you will tag. Run the project's full check command locally as well.
+- If anything fails, **stop**. Never tag a red build.
+
+## 2. Decide the version (Semantic Versioning 2.0.0)
+
+List what changed since the last tag: `git log --oneline <last-tag>..HEAD`. If commits follow Conventional Commits, the type and `!`/`BREAKING CHANGE` footers tell you directly.
+
+| Since last release | Bump | Example |
+|---|---|---|
+| Any incompatible change to the public API, config, CLI, data format or supported runtimes | MAJOR | 2.4.1 → 3.0.0 |
+| New backward-compatible functionality, or a deprecation | MINOR | 2.4.1 → 2.5.0 |
+| Only backward-compatible bug fixes | PATCH | 2.4.1 → 2.4.2 |
+| Nothing user-facing (docs, tests, CI) | No release needed | |
+
+Rules:
+
+- First decide what the **public API** is (exported functions, HTTP endpoints, CLI flags, config keys, file formats). Only changes to it count.
+- Under `0.y.z`, the public API is not stable and anything may change. Most projects bump MINOR for breaking changes and PATCH for everything else; follow the project's history.
+- `1.0.0` is a deliberate decision that the API is stable. **Ask** before making it.
+- A MAJOR bump, or any case where you are unsure whether something is breaking: **ask** the user, with the specific change that makes you think so.
+- Never reuse or move a published version or tag. A bad release gets a new version.
+
+## 3. Update the changelog
+
+If no tool generates it, keep `CHANGELOG.md` in the Keep a Changelog style:
+
+```
+## [2.5.0] - 2026-03-14
+
+### Added
+- CSV export from the reports page (#512)
+
+### Fixed
+- Totals no longer go negative when a refund exceeds the line amount (#498)
+```
+
+- Sections: Added, Changed, Deprecated, Removed, Fixed, Security. Omit empty ones.
+- Write each entry for the user of the software, not the developer: what they can now do or what stopped going wrong. Link the PR or issue.
+- Move entries out of `## [Unreleased]` into the new version heading; date in ISO format.
+- Breaking changes go first under **Changed** or **Removed**, each with the migration step.
+
+## 4. Bump, commit and tag
+
+1. Update every version location from step 0. Use the ecosystem's command where one exists (for example `npm version <x.y.z> --no-git-tag-version`) so lockfiles follow.
+2. Commit: `git commit -am "chore(release): <x.y.z>"` (or the project's convention).
+3. Tag with an **annotated** tag: `git tag -a v<x.y.z> -m "v<x.y.z>"`. Use `-s` instead of `-a` if the project signs tags. Match the existing tag prefix (`v1.2.3` or `1.2.3`, or `pkg@1.2.3` in monorepos).
+4. **Ask** before pushing: pushing a tag usually triggers publishing. Then `git push origin <branch>` and `git push origin v<x.y.z>`. Don't use `git push --tags`, which can push stray local tags.
+
+## 5. Release notes
+
+Release notes are the changelog entry rewritten for a reader skimming the release page.
+
+```
+## Highlights
+<1-3 sentences on why someone should upgrade>
+
+## Breaking changes
+- <what changed> → <what to do>
+
+## What's new / Fixes
+- <user-facing change> (#PR)
+
+## Upgrade
+<command or steps, including any migration>
+```
+
+Publish with `gh release create v<x.y.z> --title "v<x.y.z>" --notes-file notes.md --verify-tag` (add `--prerelease` for pre-releases). `--verify-tag` aborts if the tag is not on the remote, instead of letting gh create a tag from the default branch's head. `--generate-notes` builds a PR list, which is a starting draft, not finished notes.
+
+## 6. Pre-releases
+
+- Format: `<x.y.z>-<label>.<n>`, for example `3.0.0-beta.2`. SemVer orders `alpha < beta < rc` and `3.0.0-rc.1 < 3.0.0`. Always put a dot before the counter: `beta.10` sorts after `beta.9` (numeric identifiers compare as numbers), but `beta10` sorts before `beta9` (compared as text).
+- Publish so default installs don't pick them up: `npm publish --tag next` (npm), a pre-release version string for PyPI (`3.0.0b2`, PEP 440), `--prerelease` on the GitHub release.
+- Bump only the counter between pre-releases of the same version; the final release drops the suffix.
+
+## 7. Hotfixes to a released line
+
+When a fix must ship without unreleased work on the default branch:
+
+1. Branch from the release tag: `git switch -c hotfix/<x.y.z+1> v<x.y.z>`.
+2. Land the fix on the default branch first when possible, then `git cherry-pick -x <sha>` onto the hotfix branch (`-x` records the source commit). If it only applies to the old line, fix it there and port forward.
+3. Run the full checks on the hotfix branch, then do steps 3-5 with a PATCH bump.
+4. Make sure the changelog entry also reaches the default branch, so the next release doesn't lose it.
+5. For long-lived support lines, keep a `release/<major>.<minor>` branch instead of recreating it each time.
+
+## 8. Automating releases
+
+Pick one tool, and only if the project has none yet. **Ask** before adding it, since it changes how everyone merges.
+
+| Tool | Fits | How it works |
+|---|---|---|
+| release-please | GitHub repos, monorepos, wanting a human gate | Opens a release PR from Conventional Commits; merging it tags and releases |
+| semantic-release | Fully automatic releases on every merge | Analyses commits in CI, then bumps, tags and publishes |
+| Changesets | JS monorepos, versioning decided per PR | Contributors add `.changeset/*.md` files; a release PR applies them |
+| git-cliff | Changelog generation only | Builds the changelog from commits via `cliff.toml` |
+
+Before wiring one in: confirm commit messages already follow the convention it needs, give the CI token only the permissions the tool's docs list, and run it in dry-run mode first (`semantic-release --dry-run`, or check release-please's PR before merging).
+
+## Never
+
+- Never tag or publish from a dirty tree or an unpushed commit.
+- Never delete or move a published tag, or republish the same version with different contents.
+- Never hand-edit files that the release tool generates.
+- Never publish (tag push, registry publish, GitHub release) without the user's go-ahead.
+
+## Report back
+
+```
+Version: <old> → <new> (<major|minor|patch|pre-release|hotfix>), reason: <change that decided it>
+Changed files: <version files, CHANGELOG.md>
+Tag: <tag> (<pushed | local only>)
+Published: <registry/release URL, or not yet>
+Notes: <path or inline>
+Follow-ups: <port hotfix forward, announce, etc.>
+```

package/skills/release-management/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "We removed a deprecated endpoint and added CSV export, what should the next version be? Then cut the release",
+    "Prepare release 1.4.0: update CHANGELOG.md, bump the version and tag it",
+    "Customers on 2.3.x need a security fix but main has unreleased features, how do we ship 2.3.5?",
+    "Set up release-please so merging to main produces versioned releases and a changelog",
+    "Publish a 3.0.0 release candidate to npm without making it the default install"
+  ],
+  "should_not_trigger": [
+    "Write a commit message for this fix that follows the feat/fix convention",
+    "Rebase my feature branch onto main and push it safely",
+    "Plan a blue-green deployment for the API so we can roll back quickly",
+    "Write a GitHub Actions workflow that builds and tests the project",
+    "Update the README to document the new configuration options"
+  ]
+}

package/skills/remotion-video/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: remotion-video
+description: Remotion video projects written in React, covering Composition and Sequence timing, frame-driven animation with interpolate and spring, staticFile assets, font loading held by delayRender, deterministic rendering with the remotion CLI or renderMedia, and serverless rendering on AWS Lambda with concurrency and S3 privacy settings. Use when building or fixing a Remotion composition, timing scenes in frames, animating with useCurrentFrame, rendering an MP4 from React code, or setting up Remotion Lambda.
+license: MIT
+compatibility: Any Agent Skills host. Needs Node 18+ and a Remotion 4 project; Lambda rendering needs an AWS account and network access.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "node, npx"
+  kete-loom/owner: "Kete-org"
+---
+
+# Remotion video
+
+Remotion renders a React tree once per frame in a headless browser and encodes the frames. Everything visible must be a pure function of the current frame. That one rule explains most Remotion bugs.
+
+## Ground rules
+
+1. **Time is frames, not seconds.** Read `useCurrentFrame()` and `useVideoConfig()` (`fps`, `durationInFrames`, `width`, `height`). Convert seconds with `seconds * fps`. Never use `Date.now()`, `setTimeout`, `setInterval` or CSS transitions/animations for motion: they don't follow the frame and render as jumps or flicker.
+2. **Deterministic.** No `Math.random()`; use `random(seed)` from `remotion`. Data fetched at render time must be the same on every frame and every machine.
+3. **Anything async holds the frame.** Fetching data, loading fonts, waiting for a canvas or a third-party chart: wrap it with `useDelayRender()` (or `delayRender()` / `continueRender(handle)`), and call `cancelRender(err)` on failure. The default timeout is 30 seconds; raise it per call with `timeoutInMilliseconds`, not globally by habit.
+4. **Use Remotion's media tags.** `<Img>`, `<Audio>`, and `<Video>` from `@remotion/media` (or `<OffthreadVideo>` for older code) wait for media to load before a frame is captured. A plain `<img>` or `<video>` can be captured half-loaded.
+5. **Assets come from `public/` through `staticFile('name.png')`**, or from a full URL. Don't import big videos into the bundle.
+
+## Project shape
+
+- `src/index.ts` calls `registerRoot(RemotionRoot)`.
+- `src/Root.tsx` lists `<Composition id="Intro" component={Intro} durationInFrames={300} fps={30} width={1920} height={1080} defaultProps={...} />`. The `id` is what you render.
+- Typed props: give the composition a Zod `schema` so props can be edited in the Studio and validated before render. Use `calculateMetadata` when duration or size depends on props or data (for example, length of a voice-over).
+- Preview with `npx remotion studio`. Start a new project with `npx create-video@latest`.
+
+## Timing scenes
+
+1. Put each scene in `<Sequence from={f} durationInFrames={d}>`. Inside, `useCurrentFrame()` restarts at 0, so a scene's animation code doesn't need to know where it sits.
+2. Lay out back-to-back scenes with `<Series>` and `<Series.Sequence durationInFrames={d}>` instead of adding offsets by hand.
+3. For crossfades and slides between scenes use `@remotion/transitions` (`TransitionSeries` with `fade()`, `slide()` and a timing such as `linearTiming` or `springTiming`). A transition overlaps two scenes, so the total gets shorter by the transition length.
+4. Wrap layers in `<AbsoluteFill>` to stack them full-frame.
+5. Keep timing numbers in one place (a `timings` object or computed from props) so a script change doesn't mean editing ten files.
+
+## Animation
+
+- `interpolate(frame, [0, 30], [0, 1], { extrapolateLeft: 'clamp', extrapolateRight: 'clamp' })`. Without `clamp` the value keeps going past the range: opacity above 1, elements flying off-screen. Input ranges must be strictly increasing.
+- Easing: pass `easing: Easing.bezier(...)` or `Easing.out(Easing.cubic)` to `interpolate`.
+- `spring({ frame, fps, config: { damping: 200 }, delay: 10, durationInFrames: 30 })` returns 0 to about 1 with physics; defaults are `mass: 1`, `damping: 10`, `stiffness: 100`. Higher `damping` means less bounce. Feed the result into `interpolate` to map it to pixels or degrees.
+- Colours: `interpolateColors(frame, [0, 60], ['#000', '#fff'])`.
+- Animate `transform` and `opacity`. Animating `width`, `top` or heavy `filter: blur()` per frame is slow to render.
+
+## Text, fonts and audio
+
+- Load fonts before frames are captured: `loadFont()` from `@remotion/google-fonts/<Family>`, or `@remotion/fonts` `loadFont({ family, url: staticFile('x.woff2') })`. Both hold the render until the font is ready. A system font that isn't installed on the render machine or Lambda will silently fall back.
+- Measure text with `@remotion/layout-utils` (`measureText`, `fitText`) when it must fit a box.
+- Audio: `<Audio src={staticFile('music.mp3')} volume={(f) => interpolate(f, [0, 30], [0, 1], {extrapolateRight: 'clamp'})} />`. Skip the start with `trimBefore` (in frames; code before 4.0.319 uses `startFrom`) and cap the length by wrapping it in a `<Sequence durationInFrames>`.
+- Captions: `@remotion/captions` for the caption data type and TikTok-style pages.
+
+## Rendering locally
+
+1. `npx remotion render <entry> <composition-id> out/video.mp4` (the entry defaults to the configured entry point). Common flags: `--props=./props.json`, `--codec=h264|h265|vp8|vp9|prores`, `--crf`, `--concurrency`, `--frames=0-59` for a quick check, and `npx remotion still <id> out/frame.png --frame=120` for one frame.
+2. From Node: `bundle()` from `@remotion/bundler`, then `selectComposition()` and `renderMedia()` from `@remotion/renderer`. Bundle once and reuse it for many renders.
+3. Check the output with a quick look in a player and `ffprobe out/video.mp4` (duration, fps, resolution, audio stream present).
+
+## Rendering on Lambda
+
+Follow `references/lambda.md`. In short: create the IAM role and user from `npx remotion lambda policies role|user`, `npx remotion lambda functions deploy`, `npx remotion lambda sites create src/index.ts --site-name=<name>`, then `npx remotion lambda render <serve-url> <composition-id>` or `renderMediaOnLambda()` with `getRenderProgress()`.
+
+## Performance checklist
+
+When renders are slow or time out, check in order:
+
+1. Run `npx remotion benchmark` or render with `--log=verbose` to see slow frames.
+2. Heavy work per frame (parsing JSON, building big arrays): move it into `useMemo` or `calculateMetadata`.
+3. Big images: resize to the output size; prefer JPEG/WebP over huge PNGs.
+4. Too many simultaneous videos, or `<Video>` sources with sparse keyframes: re-encode sources with FFmpeg (see the ffmpeg-media-processing skill).
+5. GPU-only CSS (`backdrop-filter`, large blurs, WebGL) on a machine without a GPU: check what's available with `npx remotion gpu`, try `--gl=angle` or `--gl=swangle` (the Lambda default), or simplify the effect.
+6. Tune `--concurrency`; more is not always faster on a small machine.
+
+## Never
+
+- Never drive motion with timers, CSS animations, or state updated in `useEffect` per frame.
+- Never leave a `delayRender()` without a matching `continueRender()` or `cancelRender()` on every code path.
+- Never commit AWS keys; `REMOTION_AWS_ACCESS_KEY_ID` and `REMOTION_AWS_SECRET_ACCESS_KEY` live in `.env` that is gitignored.
+
+## Stop and ask the user
+
+- Before the first Lambda deploy or a large Lambda render: it creates AWS resources and costs money.
+- Whether rendered files should be public or private in S3 (`--privacy`); the default is public.
+- Licensing: Remotion is free for individuals and companies of up to 3 people; bigger for-profit companies need a company license. Point it out once when the project is for a company; don't decide for them.
+
+## Report back
+
+Composition IDs touched, the render command you ran, output path with duration/fps/resolution from `ffprobe`, and any frame you checked by eye.

package/skills/remotion-video/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Build a 15-second Remotion intro where the logo springs in and the title fades up",
+    "My Remotion render flickers because the text animates with a CSS transition, how do I fix it?",
+    "Deploy our Remotion composition to Lambda and render personalised videos from an API",
+    "Google font isn't showing in the Remotion MP4 even though it works in the Studio",
+    "Use Series and TransitionSeries to stitch five slides into one Remotion video with fades"
+  ],
+  "should_not_trigger": [
+    "Trim the first ten seconds off this MP4 and convert it to WebM",
+    "Animate a proof of the Pythagorean theorem with Manim",
+    "Add a Framer Motion hover animation to the pricing cards",
+    "Generate a short product clip from a text prompt with a video generation API",
+    "Speed up our React dashboard that re-renders on every keystroke"
+  ]
+}

package/skills/remotion-video/references/lambda.md

@@ -0,0 +1,66 @@
+# Remotion Lambda setup and rendering
+
+Check www.remotion.dev/docs/lambda for the current version before changing anything; the function and the site must be on the same Remotion version as the project.
+
+## One-time setup
+
+1. `npx remotion add @remotion/lambda` (keeps every `remotion` and `@remotion/*` package on the same version).
+2. In AWS IAM create a role named `remotion-lambda-role` with the policy printed by `npx remotion lambda policies role`.
+3. Create a user with the policy from `npx remotion lambda policies user` and an access key. Put the key in a gitignored `.env`:
+
+   ```txt
+   REMOTION_AWS_ACCESS_KEY_ID=...
+   REMOTION_AWS_SECRET_ACCESS_KEY=...
+   ```
+
+4. Check it: `npx remotion lambda policies validate`.
+5. See your concurrency limit: `npx remotion lambda quotas`. New AWS accounts often have a low limit; request an increase before big renders.
+
+## Deploy
+
+```bash
+npx remotion lambda functions deploy                       # once per Remotion version / memory / timeout / region
+npx remotion lambda sites create src/index.ts --site-name=my-video   # every time the video code changes
+```
+
+`sites create` prints a serve URL. Redeploying with the same `--site-name` overwrites it, so a stable name keeps the URL.
+
+## Render from the CLI
+
+```bash
+npx remotion lambda render <serve-url-or-site-name> <composition-id> [out.mp4] \
+  --privacy=private --props=./props.json
+```
+
+- `--concurrency=<n>` or `--frames-per-lambda=<n>` controls how the video is split (one or the other, at most 200 functions).
+- `--privacy`: `public` (default), `private` (use `presignUrl()` to hand out a link) or `no-acl`.
+- Without an output path the file stays in the S3 bucket.
+
+## Render from Node
+
+```ts
+import { renderMediaOnLambda, getRenderProgress } from '@remotion/lambda/client';
+
+const { renderId, bucketName } = await renderMediaOnLambda({
+  region: 'us-east-1',
+  functionName,            // from getFunctions({ region, compatibleOnly: true })
+  serveUrl,
+  composition: 'Intro',
+  inputProps: { title },
+  codec: 'h264',
+  privacy: 'private',
+});
+
+// Poll from a job, not from an HTTP request handler
+const progress = await getRenderProgress({ renderId, bucketName, functionName, region: 'us-east-1' });
+// progress.done, progress.overallProgress, progress.outputFile, progress.fatalErrorEncountered, progress.errors
+```
+
+Store `renderId` and `bucketName` with your job row so a restart can resume polling. A `webhook` option on `renderMediaOnLambda` can notify you instead of polling; verify every delivery against the secret you set, using `validateWebhookSignature({ secret, body, signatureHeader })` from `@remotion/lambda/client` with the `X-Remotion-Signature` request header, before you trust it.
+
+## Common failures
+
+- Version mismatch between project, function and site: redeploy both after upgrading.
+- Fonts missing on Lambda: load them with `@remotion/google-fonts` or `@remotion/fonts`; Lambda has few system fonts.
+- `delayRender` timeouts on Lambda but not locally: remote assets are slower to fetch; raise `timeoutInMilliseconds` for that call or host assets in the same region.
+- Rate limit / concurrency errors: lower `--concurrency` or raise the AWS quota.

package/skills/reproducible-dev-environments/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: reproducible-dev-environments
+description: Pins a project's whole toolchain so a fresh laptop and the CI runner get identical versions from one setup command, choosing between Nix flakes or Flox, Dev Containers, and mise or asdf version files, pinning the JavaScript package manager through the packageManager field and corepack, committing every lockfile, and making CI install from the same pins. Use when onboarding takes a day of manual installs, "works on my machine" bugs come from tool version drift, CI uses different Node, Python or Go versions than developers, or a team is adding a devcontainer.json, flake.nix, mise.toml or .tool-versions.
+license: MIT
+compatibility: Any Agent Skills host. Uses whichever of nix, flox, mise, asdf, docker or the Dev Containers CLI the project picks; macOS, Linux and WSL2.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# Reproducible dev environments
+
+Goal: clone, run one command, get the same compilers, runtimes, CLIs and package-manager versions as everyone else and as CI. Every version lives in a committed file; nothing depends on what happens to be installed globally.
+
+Writing the production image belongs to `docker-patterns`; CI pipeline design belongs to `github-actions-ci`. This skill owns the developer toolchain and makes CI read the same pins.
+
+## 0. Inventory
+
+1. List what a developer needs: language runtimes, package managers, CLIs (terraform, kubectl, protoc), databases or services, and system libraries (openssl, libpq, imagemagick).
+2. Find existing pins: `.nvmrc`, `.node-version`, `.python-version`, `.tool-versions`, `mise.toml`, `rust-toolchain.toml`, `go.mod` `toolchain` line, `flake.nix`, `.flox/`, `.devcontainer/`, `packageManager` in `package.json`, and the versions CI installs.
+3. Note mismatches between them. Report them before changing anything.
+
+## 1. Pick one mechanism
+
+| Situation | Choose |
+|---|---|
+| Only language runtimes and CLIs need pinning, mixed OSes, low ceremony | **mise** (`mise.toml`) or **asdf** (`.tool-versions`; mise reads it too) |
+| System libraries matter too, or the same locked toolchain versions on macOS and Linux | **Nix flake** (`flake.nix` + `flake.lock`) or **Flox** (Nix underneath, simpler CLI) |
+| Editor-integrated containers, Codespaces, Windows developers, or services alongside (database, queue) | **Dev Container** (`.devcontainer/devcontainer.json`) |
+| Team already uses one | Keep it and fix its gaps; do not add a second |
+
+A devcontainer can still use mise or Nix inside. Do not make two files authoritative for the same tool. If the choice is unclear (team habits, Windows support, Nix learning curve), **stop and ask the user**.
+
+## 2. Write the pins
+
+### mise
+
+```toml
+# mise.toml
+[tools]
+node = "22.11.0"
+python = "3.12.7"
+terraform = "1.9.8"
+
+[env]
+_.python.venv = { path = ".venv", create = true }
+```
+
+`mise install` installs everything; `mise use node@22.11.0` updates the file. Pin exact versions, not `lts` or `latest`.
+
+### asdf
+
+`.tool-versions`, one tool per line (`nodejs 22.11.0`). Each tool needs `asdf plugin add <name>` first; list the plugins in the README or setup script.
+
+### Nix flake
+
+1. A `devShells.default` in `flake.nix` listing packages from a pinned `nixpkgs` input.
+2. Commit `flake.lock`. Update deliberately with `nix flake update` in its own commit.
+3. Enter with `nix develop`; add `direnv` with `use flake` in `.envrc` for automatic activation.
+
+### Flox
+
+`flox init`, `flox install nodejs python3 ...`, commit the `.flox/` directory (it holds `env/manifest.toml` and the lock). Developers run `flox activate`.
+
+### Dev Container
+
+```jsonc
+// .devcontainer/devcontainer.json
+{
+  "name": "app",
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": { "version": "22.11.0" },
+    "ghcr.io/devcontainers/features/python:1": { "version": "3.12" }
+  },
+  "postCreateCommand": "make setup",
+  "forwardPorts": [3000]
+}
+```
+
+Pin the base image by tag at least, by digest for strict reproducibility. Use `dockerComposeFile` when services (Postgres, Redis) are needed. Test it headless with the Dev Containers CLI: `devcontainer up --workspace-folder .` then `devcontainer exec --workspace-folder . <test command>`.
+
+## 3. Package managers and lockfiles
+
+1. JavaScript: set `"packageManager": "pnpm@9.12.3"` (or yarn, npm) in `package.json`. Corepack reads it and runs that exact version. Corepack ships with Node up to 24 (opt in with `corepack enable`) but is no longer bundled from Node 25; there install it with `npm install -g corepack`, or let mise pin the package manager instead.
+2. Commit the lockfile (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `uv.lock`, `poetry.lock`, `Cargo.lock` for applications, `go.sum`). In CI install in frozen mode: `npm ci`, `pnpm install --frozen-lockfile`, `yarn install --immutable`, `uv sync --locked`, `poetry install` with the lock checked by `poetry check --lock`.
+3. Python: pin the interpreter (`.python-version` or the chosen tool) and use a project-local virtual environment, never the system Python.
+
+## 4. One setup command
+
+Provide exactly one entry point, documented first in the README: `mise install && <deps>`, `nix develop`, `flox activate`, or "Reopen in Container". If more steps are needed, put them in one `make setup` or `just setup` target (or a setup script it calls) that:
+
+- is idempotent (safe to run twice),
+- checks prerequisites and prints what is missing instead of failing obscurely,
+- copies `.env.example` to `.env` only if `.env` does not exist, and never writes real secrets,
+- ends by running a quick smoke check (build or a fast test).
+
+## 5. CI uses the same pins
+
+- mise: `jdx/mise-action` in GitHub Actions, or `mise install` in any CI.
+- Nix: install Nix, then `nix develop --command <test command>`.
+- Dev Container: `devcontainers/ci` action, or the Dev Containers CLI.
+- Setup actions that read version files: `actions/setup-node` with `node-version-file: .nvmrc` or `package.json`, `actions/setup-python` with `python-version-file`.
+
+Remove hard-coded versions from CI YAML once CI reads the pin file. A version bump is then one file change that dev and CI both pick up.
+
+## 6. Verify
+
+1. In a clean environment (fresh container, new clone, or CI), run the setup command, then the test command.
+2. Print the resolved versions (`node -v`, `python -V`, `pnpm -v`, ...) locally and in CI; they must match the pins.
+3. Run the setup command a second time; it must succeed and change nothing.
+
+## Never
+
+- Never pin with ranges or `latest` for toolchains.
+- Never rely on globally installed tools that are not in the pin file.
+- Never commit secrets in setup scripts, `.envrc` or `devcontainer.json`.
+- Never update the lockfile or `flake.lock` as a side effect of setup.
+
+## Report back
+
+```
+## Dev environment: <project>
+Mechanism: <mise | asdf | Nix | Flox | Dev Container> and why
+Pinned: <tool@version list>
+Setup command: <one line>
+CI: <how it reads the same pins>
+Mismatches fixed: <before -> after>
+Verified: clean setup yes/no, versions match CI yes/no, rerun idempotent yes/no
+```

package/skills/reproducible-dev-environments/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "New hires spend a whole day installing tools. Give us one command that sets up Node, Python and terraform at the right versions.",
+    "Add a devcontainer.json so the repo opens in Codespaces with Postgres running alongside",
+    "CI runs Node 20 but half the team is on Node 22; pin it once and make CI read the same file",
+    "Write a flake.nix dev shell with a locked nixpkgs so macOS and Linux devs get the same protoc and openssl",
+    "Pin pnpm with the packageManager field and make sure everyone uses that exact version"
+  ],
+  "should_not_trigger": [
+    "Write a multi-stage Dockerfile for our production API image",
+    "Set up a GitHub Actions workflow with a matrix over three operating systems and caching",
+    "Upgrade our npm dependencies and check them for known vulnerabilities",
+    "Package our Python CLI as a standalone Windows executable for customers",
+    "Explain idiomatic Python dataclasses versus pydantic models"
+  ]
+}

package/skills/responding-to-code-review/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: responding-to-code-review
+description: Works through review comments left on your own pull request or change with technical rigour - reads every comment before touching code, restates each one, asks about unclear items first, checks each suggestion against the codebase before agreeing, pushes back with evidence when a suggestion is wrong, applies YAGNI to scope creep, fixes one item at a time with a test, and replies in the review thread itself. Use when a reviewer, teammate or bot has left feedback on your change and you must decide what to fix, what to question and how to answer.
+license: MIT
+compatibility: Any Agent Skills host. Needs git and the project's test runner; replying on GitHub needs the gh CLI, signed in.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git, gh"
+  kete-loom/owner: "Kete-org"
+---
+
+# Responding to code review
+
+Review feedback is input to evaluate, not orders to obey or praise to return. Every reply either states a fix, asks a precise question, or disagrees with evidence.
+
+This skill is for the author receiving feedback. To review someone else's change, use the `code-reviewer` agent or the `/review` command instead.
+
+## 1. Collect all the feedback first
+
+1. Gather every comment before changing anything: the summary review, inline comments, and any bot findings. On GitHub:
+   - Reviews: `gh pr view <pr> --json reviews,comments`
+   - Inline comments with their ids, paths and lines: `gh api repos/{owner}/{repo}/pulls/<pr>/comments --paginate`
+2. Number the items. One comment can hold several items; split them.
+3. Note who wrote each item. The user or the project owner sets direction; an outside reviewer or a bot may lack context.
+
+Do not start fixing item 1 while item 5 is unread. Items often depend on each other.
+
+## 2. Restate each item
+
+For each item write one line: what the reviewer wants changed, and why, in your own words. If you cannot restate it, it is unclear.
+
+**Stop and ask** before implementing anything when any item is unclear. List the items you understand and the exact question for each unclear one. Do not implement the clear ones first; a later answer can change them.
+
+## 3. Check each suggestion against reality
+
+Before agreeing, verify. For each item:
+
+| Check | How |
+|---|---|
+| Is the claim true here? | Read the code it points at, and run it or its test if the claim is about behaviour |
+| Would the change break something? | Search the codebase for callers and run their tests |
+| Is there a reason for the current code? | `git log -L <start>,<end>:<file>` or `git blame` on the lines; read the linked issue or commit message |
+| Does it hold on every supported platform and version? | Check the project's declared runtime, targets and compatibility matrix |
+| Does it conflict with a decision the user already made? | Re-read the task, plan or earlier conversation |
+
+Classify the item: **correct** (fix it), **wrong** (push back), **partly right** (fix the valid part, explain the rest), or **cannot verify** (say what you would need).
+
+If an item conflicts with the user's earlier decision or changes architecture, **stop and ask the user** rather than settling it with the reviewer.
+
+## 4. Apply YAGNI to scope requests
+
+Requests like "handle this properly", "add pagination and caching here" or "make this configurable" can grow a small change into a large one.
+
+1. Search the codebase for real use of the thing being expanded.
+2. If nothing uses it, propose removing or keeping it minimal and ask whether usage exists that you missed.
+3. If it is used and the request is a real gap, treat it as a normal fix, or propose a follow-up issue when it is out of the change's scope.
+
+## 5. Push back with evidence
+
+Disagree when the suggestion is incorrect for this stack, breaks existing behaviour, ignores a compatibility constraint, adds unused features, or contradicts the user's decisions.
+
+A good pushback names the evidence and offers a way forward:
+
+```
+Keeping the fallback: package.json declares "engines": {"node": ">=16"} and CI
+still runs Node 16 in .github/workflows/legacy.yml, but structuredClone is only
+global from Node 17. Raise the engines floor and drop that job, or keep this?
+```
+
+- Point at a file, line, test, log or doc. Opinion alone is not evidence.
+- Ask a specific question when you want a decision.
+- If you later find you were wrong, say so in one line and fix it: "Checked again: the cache is shared across tenants, so this is a real leak. Fixed in `cache.ts:42`." No long apology, no defence of the earlier reply.
+
+## 6. Implement one item at a time
+
+Order: blocking items (bugs, security, data loss) first, then simple fixes, then larger refactors.
+
+For each item:
+
+1. Write or update a test that fails without the fix, where the item is about behaviour. Follow `tdd-workflow` if it is installed.
+2. Make the smallest change that resolves the item.
+3. Run the related tests, then the full suite before moving on.
+4. Commit or stage it as its own logical change if the project works that way, so the reviewer can see each fix.
+
+Never batch ten fixes into one untested edit. Never weaken or delete a test to satisfy a comment without the user agreeing.
+
+## 7. Reply where the comment is
+
+- Answer an inline comment in its own thread, not as a new top-level PR comment:
+  `gh api repos/{owner}/{repo}/pulls/<pr>/comments/<comment_id>/replies -f body='Fixed: ...'`
+- Answer a summary review or a general comment with `gh pr comment <pr> --body '...'`.
+- Elsewhere (GitLab, Gerrit, a chat thread), reply in the same thread the comment came from.
+- Post replies only after the fixes are pushed or the user approves pushing; a reply that says "fixed" must point at code that exists on the branch.
+
+## Tone rules
+
+- State the fix or the question. That is the acknowledgement.
+- Never write performative agreement or filler: "You're absolutely right!", "Great catch!", "Thanks for the feedback!", "Excellent point". Delete them if you notice them in a draft.
+- Never promise a change before you have verified it ("I'll fix that now").
+- Never argue for the sake of it. Concede in one line when the evidence says the reviewer is right.
+
+Reply shapes:
+
+```
+Fixed: <what changed>, <file:line>. Test: <test name>.
+Not changing: <reason with evidence>. <question or alternative>?
+Question: <exact thing you need to know> before I change <thing>.
+Can't verify without <access, data, environment>. Investigate, ask <who>, or leave?
+```
+
+## Report back
+
+End with a table the user can scan:
+
+```
+## Review response: <PR or change>
+| # | Item (restated) | Verdict | Action | Reply posted |
+|---|---|---|---|---|
+| 1 | ... | correct / wrong / partly / unclear / can't verify | fixed in <file:line> / pushed back / asked | yes / draft |
+Tests: <command> -> <pass/fail counts>
+Open questions for the user: <list, or none>
+```