chore: using mise to manage node versions and tasks (#44)

* add mise for Node.js version management

Replace ad-hoc Node version pinning with mise (mise.toml + mise.lock).
This ensures all contributors and CI use the same Node LTS version.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* expand mise with env loading, PATH management, and task runner

- [env] _.file loads .env files for local API keys (replaces dotenv)
- [env] _.path adds node_modules/.bin to PATH for direct tool access
- [tasks] mirrors npm scripts with sources/outputs for file-based caching
- eval tasks for running LLM evaluations via mise run
- update AGENTS.md and CONTRIBUTING.md to use mise run commands

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

.gitignore

@@ -2,6 +2,7 @@ node_modules/
 dist/
 *.log
 .DS_Store
+.env
 
 # IDE/Editor directories
 .vscode/

AGENTS.md

@@ -4,6 +4,12 @@ Guidance for AI coding agents working with this repository.
 
 > **Note:** `CLAUDE.md` is a symlink to this file.
 
+## Prerequisites
+
+This project uses [mise](https://mise.jdx.dev/) to manage tool versions,
+environment variables, and project tasks. Run `mise install` to set up the
+correct tool versions from `mise.toml`.
+
 ## Repository Structure
 
 ```
@@ -18,19 +24,30 @@ skills/
 
 packages/
   skills-build/           # Generic build system for all skills
+  evals/                  # LLM evaluation system for skills
 ```
 
 ## Commands
 
+All tasks are defined in `mise.toml` and can be run with `mise run` (or via
+`npm run` which delegates to the same commands).
+
 ```bash
-npm run build                    # Build all skills
+mise install                     # Install tool versions (Node.js)
-npm run build -- {skill-name}    # Build specific skill
+mise run install                 # Install all npm dependencies
-npm run validate                 # Validate all skills
+mise run build                   # Build all skills
-npm run validate -- {skill-name} # Validate specific skill
+mise run validate                # Validate all skills
-npm run check                    # Format and lint (auto-fix)
+mise run check                   # Format and lint (auto-fix)
+mise run test                    # Run tests
+mise run eval                    # Run all LLM evals
+mise run eval:code-fix           # Run code-fix evals only
+mise run eval:workflow            # Run workflow evals only
 ```
 
-**Before completing any task**, run `npm run check` and `npm run build` to
+Tasks with `sources`/`outputs` defined in `mise.toml` skip automatically when
+nothing has changed.
+
+**Before completing any task**, run `mise run check` and `mise run build` to
 ensure CI passes.
 
 ## Creating a New Skill
@@ -41,7 +58,7 @@ Skills follow the [Agent Skills Open Standard](https://agentskills.io/).
 2. Create `SKILL.md` following the format below
 3. Add `references/_sections.md` defining sections
 4. Add reference files: `{prefix}-{reference-name}.md`
-5. Run `npm run build`
+5. Run `mise run build`
 
 ---
 

CONTRIBUTING.md

@@ -12,6 +12,26 @@ To ensure a positive and inclusive environment, please read our
 [code of conduct](https://github.com/supabase/.github/blob/main/CODE_OF_CONDUCT.md)
 before contributing.
 
+### Setup
+
+This project uses [mise](https://mise.jdx.dev/) to manage tool versions,
+environment variables, and project tasks. Install mise, then run from the
+repository root:
+
+```bash
+mise install        # Install Node.js (version defined in mise.toml)
+mise run install    # Install all npm dependencies
+```
+
+For LLM evals, copy the env example and add your API keys:
+
+```bash
+cp packages/evals/.env.example packages/evals/.env
+# Edit packages/evals/.env with your ANTHROPIC_API_KEY and OPENAI_API_KEY
+```
+
+mise automatically loads `.env` files defined in `mise.toml`.
+
 ## Issues
 
 If you find a typo, have a suggestion for a new skill/reference, or want to improve
@@ -39,14 +59,17 @@ We actively welcome your Pull Requests! Here's what to keep in mind:
 
 ### Pre-Flight Checks
 
-Before submitting your PR, please run these checks:
+Before submitting your PR, make sure you have the right tooling and run these
+checks:
 
 ```bash
-npm run validate  # Check reference format and structure
+mise install       # Ensure correct Node.js version
-npm run build     # Generate AGENTS.md from references
+mise run check     # Format and lint (auto-fix)
+mise run validate  # Check reference format and structure
+mise run build     # Generate AGENTS.md from references
 ```
 
-Both commands must complete successfully.
+All commands must complete successfully.
 
 ## Contributing New References
 
@@ -59,8 +82,8 @@ To add a reference to an existing skill:
 5. Run validation and build:
 
 ```bash
-npm run validate
+mise run validate
-npm run build
+mise run build
 ```
 
 ## Creating a New Skill
@@ -118,7 +141,7 @@ Example: `first-example-reference.md` for section "First Category"
 ### 5. Build
 
 ```bash
-npm run build
+mise run build
 ```
 
 The build system auto-discovers skills by looking for `SKILL.md` files.

mise.lock

@@ -0,0 +1,8 @@
+[[tools.node]]
+version = "24.13.0"
+backend = "core:node"
+"platforms.linux-arm64" = { checksum = "sha256:0f6d40b94c6a2eb6b4c240ffc8b9fd3ada7ab044c177dd413c06e1ef9a63f081", url = "https://nodejs.org/dist/v24.13.0/node-v24.13.0-linux-arm64.tar.gz"}
+"platforms.linux-x64" = { checksum = "sha256:6223aad1a81f9d1e7b682c59d12e2de233f7b4c37475cd40d1c89c42b737ffa8", url = "https://nodejs.org/dist/v24.13.0/node-v24.13.0-linux-x64.tar.gz"}
+"platforms.macos-arm64" = { checksum = "sha256:d595961e563fcae057d4a0fb992f175a54d97fcc4a14dc2d474d92ddeea3b9f8", url = "https://nodejs.org/dist/v24.13.0/node-v24.13.0-darwin-arm64.tar.gz"}
+"platforms.macos-x64" = { checksum = "sha256:6f03c1b48ddbe1b129a6f8038be08e0899f05f17185b4d3e4350180ab669a7f3", url = "https://nodejs.org/dist/v24.13.0/node-v24.13.0-darwin-x64.tar.gz"}
+"platforms.windows-x64" = { checksum = "sha256:ca2742695be8de44027d71b3f53a4bdb36009b95575fe1ae6f7f0b5ce091cb88", url = "https://nodejs.org/dist/v24.13.0/node-v24.13.0-win-x64.zip"}

mise.toml

@@ -0,0 +1,61 @@
+[settings]
+experimental = true
+lockfile = true
+
+[tools]
+node = "lts"
+
+[env]
+_.path = ["{{config_root}}/node_modules/.bin"]
+_.file = [".env", "packages/evals/.env"]
+
+# ── Root tasks ────────────────────────────────────────────────────────
+
+[tasks.install]
+description = "Install all dependencies"
+run = "npm install && npm --prefix packages/skills-build install && npm --prefix packages/evals install"
+sources = ["package.json", "packages/skills-build/package.json", "packages/evals/package.json"]
+outputs = ["node_modules/.package-lock.json"]
+
+[tasks.validate]
+description = "Validate all skills"
+run = "npm --prefix packages/skills-build run validate"
+sources = ["skills/**/SKILL.md", "skills/**/references/**"]
+
+[tasks.build]
+description = "Build all skills"
+run = "npm --prefix packages/skills-build run build"
+sources = ["skills/**/SKILL.md", "skills/**/references/**", "packages/skills-build/src/**"]
+outputs = ["skills/**/AGENTS.md"]
+
+[tasks.check]
+description = "Format and lint (auto-fix)"
+run = "biome check --write ."
+sources = ["**/*.ts", "**/*.js", "**/*.json", "biome.json"]
+
+[tasks."ci:check"]
+description = "CI format and lint check"
+run = "biome ci ."
+sources = ["**/*.ts", "**/*.js", "**/*.json", "biome.json"]
+
+[tasks.test]
+description = "Run tests"
+run = "vitest run"
+sources = ["test/**", "skills/**"]
+
+# ── Eval tasks ────────────────────────────────────────────────────────
+
+[tasks.eval]
+description = "Run all evals"
+run = "tsx packages/evals/src/cli.ts"
+sources = ["packages/evals/src/**", "skills/**/references/**"]
+
+[tasks."eval:code-fix"]
+description = "Run code-fix evals"
+run = "tsx packages/evals/src/cli.ts --type code-fix"
+sources = ["packages/evals/src/**", "skills/**/references/**"]
+
+[tasks."eval:workflow"]
+description = "Run workflow evals"
+run = "tsx packages/evals/src/cli.ts --type workflow"
+sources = ["packages/evals/src/**", "skills/**/references/**"]