@jesdi/skills 0.0.13 → 0.0.15

package/README.md

@@ -20,6 +20,24 @@ directory.
 npx @jesdi/skills-cli sync
 ```
 
+It looks like this:
+
+```json
+{
+  "schemaVersion": 1,
+  "agents": ["claude", "opencode"],
+  "skills": {
+    "crap-gate": { "version": "1.2.0", "package": "1.4.0" },
+    "backlog":   { "version": "0.3.0", "package": "1.4.0", "agents": ["claude"] }
+  }
+}
+```
+
+The top-level `agents` is the default for every skill; a skill's own `agents`
+overrides it. `install <skill>` inherits the default (the first interactive
+install asks once and stores it), while `install --agent ...` writes a
+per-skill override. In scripts, pass `--agent` or commit the top-level default.
+
 ## Commands
 
 ```
@@ -35,11 +53,12 @@ npx @jesdi/skills-cli uninstall <skill> [--global]
 
 Skills authored by other people are **not** copied into this repo — they keep
 their own authors, upstreams, and licenses. `external-skills.json` records
-which ones are part of the standard setup and where they come from. Install
-them from upstream with the [skills.sh](https://skills.sh/) CLI:
+which ones are part of the standard setup, where they come from, and (under
+`pins`) the upstream commit the box set is taken from. Install them from
+upstream with the [skills.sh](https://skills.sh/) CLI:
 
 ```bash
-npx skills add mattpocock/skills          # grill-me, grill-with-docs, improve-codebase-architecture
+npx skills add mattpocock/skills          # grill-me, grill-with-docs, grilling, improve-codebase-architecture, to-questionnaire, tdd, code-review, codebase-design, diagnosing-bugs, resolving-merge-conflicts
 npx skills add JuliusBrussee/caveman      # caveman suite
 npx skills add vercel-labs/skills         # find-skills
 npx skills add vercel-labs/agent-skills   # vercel-react-best-practices
@@ -49,6 +68,23 @@ npx skills add anthropics/skills          # frontend-design (skip if using the C
 The skills.sh lockfile (`~/.agents/.skill-lock.json`) tracks installed
 versions; `npx skills update` refreshes them.
 
+### Forks (the one exception)
+
+`to-spec`, `to-tickets`, `prototype` and `wizard` are modified copies of the
+mattpocock/skills originals, vendored under `skills/<name>/` with the upstream
+MIT `LICENSE` and a header naming the upstream commit. They keep their upstream
+names on purpose, so **never install the upstream copies of those four names
+alongside them** (`npx skills add mattpocock/skills` installs the whole set —
+deselect those four, or uninstall them afterwards). `external-skills.json`
+lists them under `forks`.
+
+### The box set
+
+`external-skills.json` → `sets.box` names the skills the agent-ops box
+receives: `own` from this package, `external` from the pinned upstream.
+agent-ops vendors that set into its claude-home seed with its own refresh
+command; this repo's job is to publish the set and keep the pins resolvable.
+
 ## Authoring skills
 
 Add `skills/<name>/SKILL.md` (frontmatter `name` must match the directory,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jesdi/skills",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "jesdi's agent skills (content package consumed by @jesdi/skills-cli)",
   "license": "MIT",
   "repository": {

package/skills/backlog/SKILL.md

@@ -71,16 +71,19 @@ these labels (`setup` provisions them all) — never invent new ones.
 | `testing` | Test coverage, test infrastructure, flaky tests |
 | `dependencies` | Upgrading or managing third-party dependencies |
 
-**Pipeline — at most one, orthogonal to Type and Area:**
+**Pipeline — orthogonal to Type and Area:**
 
-Whether an issue is ready for an unattended agent to pick up. Leave both off
+Whether an issue is ready for an unattended agent to pick up, and what it
+carries. `auto` and `human-required` are mutually exclusive; leave both off
 when it is genuinely unclear — an unlabelled issue is simply not routed, which
-is the safe default. Dispatchers filter on `auto`; nothing else reads these.
+is the safe default. `spec-ready` may sit alongside `auto`. Dispatchers filter
+on `auto` and read `spec-ready`; nothing else reads these.
 
 | Label | Apply when |
 |-------|-----------|
 | `auto` | Trivial, or close enough to previously automated work — suitable for the unattended agents pipeline |
 | `human-required` | Substantial fog of war remains; needs heavy human interaction before an agent can take it |
+| `spec-ready` | The issue body already carries a settled design (Problem, Solution, Implementation and Testing Decisions), typically written by `to-spec` after a grilling session — the pipeline skips its own interview and reconciles the design against current code |
 
 ## `setup` — create the board once (idempotent)
 
@@ -92,7 +95,7 @@ dir.
 1. Ensure the `project` scope: `gh auth status`; if Projects calls 403, run
    `gh auth refresh -s project`.
 2. Follow `references/graphql.md` → **Setup**: create the Project, link the repo,
-   add the six fields, create the `inbox` label plus the 14 taxonomy labels
+   add the six fields, create the `inbox` label plus the 15 taxonomy labels
    (idempotent — `--force` reconciles color/description on re-runs). On a
    brand-new board the `Area`
    single-select is created with the generic default options
@@ -171,7 +174,9 @@ Reuse the **dedup discipline** from the `file-bug-issue` skill, but take the
 3. Otherwise infer labels from the idea text per the **Label taxonomy** above,
    then create it (see `references/graphql.md` → Capture): `--label inbox` plus
    one `--label` per inferred label, body = the idea as-is (one loose sentence
-   is fine; no required structure).
+   is fine; no required structure). Add `spec-ready` only when the body being
+   filed is a settled design (the `to-spec` skill does this itself); a one-line
+   idea is never spec-ready.
 4. Report the new issue URL and the labels applied. If mid-task, treat as a
    side-quest and return.
 
@@ -182,7 +187,8 @@ Reuse the **dedup discipline** from the `file-bug-issue` skill, but take the
    (skip = leave in inbox). Offer label corrections per the **Label taxonomy**
    above; apply via `gh issue edit N --add-label … --remove-label …`
    (graphql.md → Triage). Labels stay independent of the board `Area` gathered
-   next.
+   next. If the issue carries `spec-ready`, confirm the body really is a
+   settled design with its sections intact; remove the label when it is not.
 3. For a promoted issue, gather `Impact` (1–5), `Effort` (1–5), `Area` (**pick one
    from the options present in `.backlog/project-meta.json`** → `fields.Area.options`),
    and optional blockers.

package/skills/backlog/references/graphql.md

@@ -47,9 +47,10 @@ gh label create security --repo <repo> --description "Vulnerabilities, auth, per
 gh label create performance --repo <repo> --description "Speed, memory, efficiency, scalability" --color f9d0c4 --force
 gh label create testing --repo <repo> --description "Test coverage, test infrastructure, flaky tests" --color 0e8a16 --force
 gh label create dependencies --repo <repo> --description "Upgrading or managing third-party dependencies" --color 0366d6 --force
-# Pipeline labels (at most one per issue; read by dispatchers)
+# Pipeline labels (auto/human-required mutually exclusive; spec-ready may co-exist; read by dispatchers)
 gh label create auto --repo <repo> --description "Suitable for the unattended agents pipeline" --color 5319E7 --force
 gh label create human-required --repo <repo> --description "Needs heavy human interaction before automation" --color B60205 --force
+gh label create spec-ready --repo <repo> --description "Issue body carries a settled design; the pipeline skips its interview" --color 006B75 --force
 
 # 5. Discover IDs to build .backlog/project-meta.json
 gh project view <projectNumber> --owner <owner> --format json   # -> id (projectId)

package/skills/crap-gate/SKILL.md

@@ -2,7 +2,7 @@
 name: crap-gate
 description: >-
   Score every function a branch changed with CRAP (cyclomatic complexity ×
-  untested fraction), fail on existing functions > 15 and new functions > 9,
+  untested fraction), fail on existing functions above 15 and new functions above 9,
   and drive a fixer + independent reviewer loop until the gate passes. Use
   when implementation is done and before pushing, when the user says "run the
   crap gate", "check CRAP", "is this change tested enough", or when a push
@@ -21,16 +21,19 @@ is the human approval gate at push time.
 
 ## Running the engine
 
-The engine ships with this skill and is stdlib-only Python (plus `node` and
-the project's own `typescript` package for TS/TSX targets). Run it from
-anywhere inside the repo — it walks up to `.crap-gate.json`:
+Use the bundled launcher on macOS or Linux (x86_64/ARM64; Windows via WSL).
+It downloads checksum-verified uv 0.12.13 and provisions private Python 3.13.7
+on first use, then reuses them across repositories. No global Python, uv,
+virtualenv activation, or pip installation is needed. The engine uses only
+Python's standard library and supports Python source syntax through 3.13.
+Run from anywhere inside the repo — it walks up to `.crap-gate.json`:
 
 ```bash
-python3 <skill-dir>/crap.py            # human table, exit 1 on violations
-python3 <skill-dir>/crap.py --json     # same data for a subagent prompt
-python3 <skill-dir>/crap.py --no-run   # reuse the last coverage reports
-python3 <skill-dir>/crap.py --all      # whole-repo baseline (exploration only)
-python3 <skill-dir>/crap.py --base main --threshold-new 7   # local what-ifs
+sh "<skill-dir>/run.sh"            # human table, exit 1 on violations
+sh "<skill-dir>/run.sh" --json     # same data for a subagent prompt
+sh "<skill-dir>/run.sh" --no-run   # reuse the last coverage reports
+sh "<skill-dir>/run.sh" --all      # whole-repo baseline (exploration only)
+sh "<skill-dir>/run.sh" --base main --threshold-new 7   # local what-ifs
 ```
 
 `<skill-dir>` is wherever this skill is installed (`.agents/skills/crap-gate`,
@@ -40,13 +43,37 @@ wrap it (`make crap`); prefer the wrapper when one exists.
 When you point a wrapper at an agent symlink, that symlink only exists after
 `skills-cli sync` if the matching agent is declared for the skill in
 `.my-skills.json` — `claude` → `.claude/skills/crap-gate`, `opencode` →
-`.agents/skills/crap-gate`. A wrapper that runs `.agents/skills/crap-gate/crap.py`
+`.agents/skills/crap-gate`. A wrapper that runs `.agents/skills/crap-gate/run.sh`
 therefore needs `"agents": ["opencode"]` (or `["claude", "opencode"]`) on the
 `crap-gate` entry, or a fresh checkout/worktree will lack that path after `sync`.
-The store copy `.my-skills/crap-gate/crap.py` is always materialized regardless
+The store copy `.my-skills/crap-gate/run.sh` is always materialized regardless
 of declared agents, so wrapping against it avoids the agent/path coupling
 entirely.
 
+Existing `make crap` / `make crap-gate` wrappers must replace `python3 .../crap.py`
+with `sh .../run.sh` (quote the path). Prefer the store path, for example:
+
+```makefile
+crap crap-gate:
+	sh "$(CURDIR)/.my-skills/crap-gate/run.sh"
+```
+
+The launcher needs standard shell utilities, `curl`, `tar`, and `sha256sum`
+or `shasum`. Its cache defaults to `${XDG_CACHE_HOME:-$HOME/.cache}/crap-gate`;
+set `CRAP_GATE_CACHE_DIR` to an absolute path to relocate it. To pre-provision,
+run the launcher with `--help` while online. `CRAP_GATE_OFFLINE=1` then requires
+that populated cache and prevents runtime downloads. Runtime setup messages go
+to stderr; `--json` returns a structured error on setup failure, with exit 2.
+Do not bypass the gate or repair global Python when setup fails; resolve the
+reported download/cache problem and rerun the launcher.
+
+TypeScript targets still need `node` and the project's own `typescript` package.
+Coverage commands still need the project's test dependencies; configure them
+with its normal runner (for example, `cd backend && pipenv run pytest ...`).
+The launcher preserves PATH and the caller's environment for these commands;
+its private Python is only for the gate engine. It does not install project
+dependencies or edit project environments.
+
 By default the engine runs each target's coverage command only when that
 target has changed files, so a backend-only change never runs the frontend
 suite. Coverage command output goes to `.crap/<target>.log`.

package/skills/crap-gate/crap.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """crap-gate engine: CRAP score for every function a branch changed.
 
-    python3 crap.py [--config PATH] [--base REF] [--threshold-existing N]
+    sh run.sh [--config PATH] [--base REF] [--threshold-existing N]
                     [--threshold-new N] [--run | --no-run] [--all] [--json]
 
 Exit 0 = no violations, 1 = violations, 2 = configuration/tool error.
@@ -11,12 +11,22 @@ project's own `typescript` package.
 from __future__ import annotations
 
 import argparse
+import json
 import subprocess
 import sys
 import tempfile
 import time
 from pathlib import Path
 
+# Direct invocation remains useful for development, but should fail clearly
+# before importing an analyzer that requires newer AST nodes.
+if sys.version_info < (3, 10):
+    message = "Use the bundled run.sh launcher; direct execution requires Python >= 3.10"
+    print(f"crap: {message}", file=sys.stderr)
+    if "--json" in sys.argv:
+        print(json.dumps({"error": {"kind": "tooling", "message": message}}))
+    sys.exit(2)
+
 import crap_git
 import crap_python
 import crap_typescript
@@ -201,6 +211,8 @@ def main(argv: list[str] | None = None) -> int:
         result = run(cfg, run_mode=args.run_mode, all_functions=args.all)
     except ToolError as exc:
         print(f"crap: {exc}", file=sys.stderr)
+        if args.json:
+            print(json.dumps({"error": {"kind": "tooling", "message": str(exc)}}))
         return 2
     sys.stdout.write(render_json(result) if args.json else render_text(result))
     return 1 if result.summary["fail"] else 0

package/skills/crap-gate/run.sh

@@ -0,0 +1,87 @@
+#!/bin/sh
+# Keep bootstrap dependencies to POSIX tools, curl, tar, and SHA-256.
+set -eu
+
+json=false
+for arg in "$@"; do
+    [ "$arg" != --json ] || json=true
+done
+fail() {
+    printf 'crap: %s\n' "$1" >&2
+    if "$json"; then
+        printf '%s\n' '{"error":{"kind":"tooling","message":"Runtime setup failed; see stderr. Run the launcher again after resolving the setup error."}}'
+    fi
+    exit 2
+}
+
+# Resolve file symlinks as well as symlinked skill directories.
+entry=$0
+while [ -L "$entry" ]; do
+    parent=$(CDPATH= cd -- "$(dirname -- "$entry")" && pwd)
+    entry=$(readlink "$entry")
+    case "$entry" in /*) ;; *) entry=$parent/$entry ;; esac
+done
+skill_dir=$(CDPATH= cd -- "$(dirname -- "$entry")" && pwd)
+cache=${CRAP_GATE_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/crap-gate}
+case "$cache" in /*) ;; *) fail 'CRAP_GATE_CACHE_DIR must be an absolute path' ;; esac
+uv_version=0.12.13
+python_version=3.13.7
+case "$(uname -s):$(uname -m)" in
+    Darwin:arm64|Darwin:aarch64)
+        target=aarch64-apple-darwin
+        digest=7e6ddb9316acc00f2296c82ff4d99977870ee34b2f0ddcae9444d714db9364ed ;;
+    Darwin:x86_64)
+        target=x86_64-apple-darwin
+        digest=5e287ef61cb6a9b61b3a83fef124fd143e400468a7dac794230147a810e17119 ;;
+    Linux:aarch64|Linux:arm64)
+        target=aarch64-unknown-linux-musl
+        digest=f44bc1037a17889fe562fffd2002d4ed108e499fbe68b4f022af244dc7b8244f ;;
+    Linux:x86_64)
+        target=x86_64-unknown-linux-musl
+        digest=4e2bfd0c9007b1032a50e539e965fd0a6037d87ad93ae1580d220a92d4c94098 ;;
+    *) fail 'Unsupported platform: use macOS or Linux on x86_64 or ARM64 (Windows: WSL)' ;;
+esac
+uv_dir=$cache/uv/$uv_version/$target
+uv=$uv_dir/uv
+if [ ! -x "$uv" ]; then
+    [ "${CRAP_GATE_OFFLINE:-0}" != 1 ] || fail 'uv is not cached; provision this cache online first'
+    mkdir -p "$uv_dir" || fail 'Cannot create runtime cache'
+    stage=$(mktemp -d "$uv_dir/.download.XXXXXX") || fail 'Cannot create download directory'
+    trap 'rm -rf "$stage"' EXIT
+    trap 'exit 2' HUP INT TERM
+    printf 'crap: downloading uv %s\n' "$uv_version" >&2
+    curl --fail --location --silent --show-error --connect-timeout 15 --max-time 300 \
+        "https://github.com/astral-sh/uv/releases/download/$uv_version/uv-$target.tar.gz" \
+        -o "$stage/uv.tar.gz" || fail 'Cannot download uv; check network access and retry'
+    if command -v sha256sum >/dev/null 2>&1; then
+        actual=$(sha256sum "$stage/uv.tar.gz")
+    elif command -v shasum >/dev/null 2>&1; then
+        actual=$(shasum -a 256 "$stage/uv.tar.gz")
+    else
+        fail 'SHA-256 verification requires sha256sum or shasum'
+    fi
+    [ "${actual%% *}" = "$digest" ] || fail 'uv archive checksum mismatch'
+    tar -xzf "$stage/uv.tar.gz" -C "$stage" || fail 'Cannot extract uv'
+    # Atomic publication: concurrent first runs never see a partial executable.
+    mv -f "$stage/uv-$target/uv" "$uv" || fail 'Cannot install cached uv'
+    rm -rf "$stage"
+    trap - EXIT HUP INT TERM
+fi
+
+# Limit uv settings to this subprocess. Do not activate a venv or change PATH:
+# coverage commands must inherit the caller's project environment unchanged.
+managed_uv() (
+    unset UV_NO_MANAGED_PYTHON UV_PYTHON UV_PYTHON_DOWNLOADS UV_PYTHON_BIN_DIR
+    export UV_PYTHON_INSTALL_DIR="$cache/python"
+    export UV_CACHE_DIR="$cache/uv-cache"
+    export UV_MANAGED_PYTHON=true
+    "$uv" --no-config "$@"
+)
+python=$(managed_uv python find --no-project --system --managed-python --no-python-downloads "$python_version" 2>/dev/null) || {
+    [ "${CRAP_GATE_OFFLINE:-0}" != 1 ] || fail 'Python is not cached; provision this cache online first'
+    managed_uv python install --no-bin "$python_version" >&2 || fail 'Cannot provision Python; check network access and retry'
+    python=$(managed_uv python find --no-project --system --managed-python --no-python-downloads "$python_version") || fail 'Cannot locate managed Python'
+}
+# Ignore Python-specific ambient settings for the engine, but preserve them for
+# child coverage processes. -I would also remove the sibling module directory.
+exec "$python" -E -s "$skill_dir/crap.py" "$@"

package/skills/crap-gate/test_launcher.py

@@ -0,0 +1,116 @@
+"""Launcher regressions. Real-runtime cases use a pre-provisioned cache in CI."""
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+
+import pytest
+
+from test_cli import BASE_SRC, repo  # noqa: F401 — shared git repository fixture
+
+LAUNCHER = Path(__file__).with_name("run.sh").resolve()
+
+
+def launch(env, *args, cwd=None, script=LAUNCHER):
+    return subprocess.run(
+        ["/bin/sh", str(script), *args], env=env, cwd=cwd,
+        text=True, capture_output=True, timeout=60,
+    )
+
+
+def test_empty_offline_cache_is_json_tool_error(tmp_path):
+    env = dict(os.environ, CRAP_GATE_CACHE_DIR=str(tmp_path / "cache"), CRAP_GATE_OFFLINE="1")
+    proc = launch(env, "--json")
+    assert proc.returncode == 2
+    assert json.loads(proc.stdout)["error"]["kind"] == "tooling"
+    assert "not cached" in proc.stderr
+    assert not (tmp_path / "cache").exists()
+
+
+def test_bad_download_is_rejected_before_execution(tmp_path):
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir()
+    curl = bin_dir / "curl"
+    curl.write_text('#!/bin/sh\nwhile [ "$1" != -o ]; do shift; done\nprintf corrupt > "$2"\n')
+    curl.chmod(0o755)
+    env = dict(os.environ, PATH=f"{bin_dir}:{os.environ['PATH']}",
+               CRAP_GATE_CACHE_DIR=str(tmp_path / "cache"), CRAP_GATE_OFFLINE="0")
+    proc = launch(env, "--json")
+    assert proc.returncode == 2
+    assert "checksum mismatch" in proc.stderr
+    assert json.loads(proc.stdout)["error"]["kind"] == "tooling"
+    assert not list((tmp_path / "cache").rglob("uv.tar.gz"))
+    assert not list((tmp_path / "cache").rglob(".download.*"))
+
+
+@pytest.fixture
+def runtime_env():
+    cache = os.environ.get("CRAP_GATE_TEST_CACHE")
+    if not cache:
+        pytest.skip("Set CRAP_GATE_TEST_CACHE to a cache provisioned by run.sh --help")
+    return dict(os.environ, CRAP_GATE_CACHE_DIR=cache, CRAP_GATE_OFFLINE="1")
+
+
+@pytest.mark.parametrize("python_on_path", ["absent", "incompatible"])
+def test_runtime_ignores_host_python_and_preserves_coverage_environment(
+    repo, tmp_path, runtime_env, python_on_path,
+):
+    bin_dir = tmp_path / "host bin"
+    bin_dir.mkdir()
+    for name in ("uname", "dirname", "git", "sh", "env"):
+        (bin_dir / name).symlink_to(shutil.which(name))
+    if python_on_path == "incompatible":
+        for name in ("python", "python3"):
+            executable = bin_dir / name
+            executable.write_text("#!/bin/sh\necho wrong-python >&2\nexit 99\n")
+            executable.chmod(0o755)
+    runtime_env.update(PATH=str(bin_dir), VIRTUAL_ENV=str(tmp_path / "wrong venv"),
+                       PYTHONHOME="/nonexistent-python", PYTHONPATH="/nonexistent-modules")
+    # Both files must be ignored by runtime discovery.
+    (repo / ".python-version").write_text("3.9.6\n")
+    (repo / "uv.toml").write_text("deliberately invalid configuration\n")
+    (repo / "pkg/m.py").write_text(BASE_SRC + "\ndef added():\n    return 1\n")
+    (repo / ".crap").mkdir()
+    cfg = json.loads((repo / ".crap-gate.json").read_text())
+    cfg["targets"][0]["coverage"]["command"] = (
+        "env > coverage-env.txt; printf '%s' '{\"files\":{}}' > .crap/coverage.json"
+    )
+    (repo / ".crap-gate.json").write_text(json.dumps(cfg))
+    proc = launch(runtime_env, "--json", cwd=repo)
+    assert proc.returncode == 0, proc.stderr
+    assert json.loads(proc.stdout)["functions"][0]["name"] == "added"
+    inherited = dict(line.split("=", 1) for line in (repo / "coverage-env.txt").read_text().splitlines())
+    for name in ("PATH", "VIRTUAL_ENV", "PYTHONHOME", "PYTHONPATH"):
+        assert inherited[name] == runtime_env[name]
+    assert "UV_PYTHON_INSTALL_DIR" not in inherited or inherited["UV_PYTHON_INSTALL_DIR"] == os.environ.get("UV_PYTHON_INSTALL_DIR")
+    assert not (repo / ".venv").exists()
+
+
+def test_symlink_spaces_and_exit_codes(repo, tmp_path, runtime_env):
+    link = tmp_path / "launcher link"
+    link.symlink_to(LAUNCHER)
+    (repo / "pkg/m.py").write_text(BASE_SRC + "\ndef unnew(a, b):\n    return a if b else (b if a else 0)\n")
+    (repo / ".crap").mkdir()
+    (repo / ".crap/coverage.json").write_text('{"files":{}}')
+    proc = launch(runtime_env, "--json", "--no-run", cwd=repo, script=link)
+    assert proc.returncode == 1, proc.stderr
+    assert json.loads(proc.stdout)["summary"]["fail"] == 1
+    proc = launch(runtime_env, "--json", "--base", "missing-ref", cwd=repo, script=link)
+    assert proc.returncode == 2
+    assert json.loads(proc.stdout)["error"]["kind"] == "tooling"
+
+
+def test_offline_cache_missing_python_is_tool_error(tmp_path, runtime_env):
+    original = Path(runtime_env["CRAP_GATE_CACHE_DIR"])
+    cache = tmp_path / "uv only cache"
+    for executable in (original / "uv").rglob("uv"):
+        if executable.is_file():
+            target = cache / executable.relative_to(original)
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.symlink_to(executable)
+    runtime_env["CRAP_GATE_CACHE_DIR"] = str(cache)
+    proc = launch(runtime_env, "--json")
+    assert proc.returncode == 2
+    assert "Python is not cached" in proc.stderr
+    assert json.loads(proc.stdout)["error"]["kind"] == "tooling"

package/skills/prototype/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/prototype/LOGIC.md

@@ -0,0 +1,67 @@
+# Logic Prototype
+
+A single, self-contained HTML file (a **shareable demo**) that lets anyone drive a state model by clicking buttons. Use this when the question is about **business logic, state transitions, or data shape**: the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases.
+
+Because it's one file with nothing to install, you can hand it to a non-developer (a designer, a PM, a domain expert) and let them feel the model for themselves. So it speaks their language, not the code's.
+
+## When this is the right shape
+
+- "I'm not sure if this state machine handles the edge case where X then Y."
+- "Does this data model actually let me represent the case where..."
+- "I want to feel out what the API should look like before writing it."
+- Anything where someone wants to **press buttons and watch state change**.
+
+If the question is "what should this look like," this is the wrong branch. Use [UI.md](UI.md).
+
+## Process
+
+### 1. State the question
+
+Before writing code, write down what state model and what question you're prototyping. One paragraph, at the top of the demo (in a visible intro, not just a comment). A logic prototype that answers the wrong question is pure waste, so make the question explicit so it can be checked later, whether the user is watching now or returning to it AFK.
+
+### 2. Isolate the logic in a portable module
+
+Put the actual logic (the bit that's answering the question) in a single `<script>` block written as a small, pure module that could be lifted out and dropped into the real codebase later. The page around it is throwaway; this module isn't.
+
+The right shape depends on the question:
+
+- **A pure reducer**: `(state, action) => state`. Good when actions are discrete events and state is a single value.
+- **A state machine**: explicit states and transitions. Good when "which actions are even legal right now" is part of the question.
+- **A small set of pure functions** over a plain data type. Good when there's no implicit current state, just transformations.
+- **A class or module with a clear method surface** when the logic genuinely owns ongoing internal state.
+
+Pick whichever shape best fits the question being asked, *not* whichever is easiest to wire to a page. Keep it pure: no DOM, no `document`, no button handlers reaching inside it. The page calls into it; nothing flows the other direction. This is what makes the prototype useful past its own lifetime: once the question's answered, the validated reducer / machine / function set lifts into the real module on its own.
+
+### 3. Build the shareable HTML file
+
+One file, plain HTML/CSS/JS: no framework, no bundler, no server, everything inline so it opens by double-click and survives being emailed around. Anyone should be able to run it by opening it. Write it to the path the invoking prompt names (see [SKILL.md](SKILL.md) rule 1).
+
+Write it for a non-developer. Every label is in **domain language**, not code: buttons and state read like the business, not the reducer. Explain in plain words what's happening.
+
+Lay it out with a clean hierarchy, top to bottom:
+
+1. **Title and one-line explanation** of what this demo lets you explore (the question from step 1).
+2. **Current state**: the full relevant state, rendered as a readable panel (labelled fields, not a raw JSON dump), re-rendered after every click so the change is visible. Where it helps a non-developer follow, call out what just changed.
+3. **Free-play buttons**: one button per action, always available, so anyone can poke at the model in any order. Each click dispatches its action and re-renders the state.
+4. **Guided walkthroughs**: a set of **scenarios**, one per tab. Each tab holds a short plain-language description of the scenario (the situation it sets up and what to watch for) and underneath it, the ordered **buttons to press** for that scenario. Each step is a real button: clicking it performs that action and moves to the next step. Starting a walkthrough resets to a known initial state so the scenario runs the same way every time.
+
+Choose scenarios that demonstrate the awkward cases, the ones hard to reason about on paper: the happy path, a tricky edge case, an attempt at something that should be illegal.
+
+Keep it beautiful but restrained: clean typography, generous spacing, one accent colour. No animations, no gimmicks: nothing that competes with the state and the buttons. It must read well on a phone: a single column, buttons at least 44px tall.
+
+### 4. Hand it over
+
+Send them the file, or open it for them. They'll click through the walkthroughs and free-play whenever they get to it; the interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different"; those are the bugs in the _idea_, which is the whole point. If they want new actions or a new scenario, add them. Prototypes evolve.
+
+### 5. Capture the answer
+
+Once the prototype has answered its question, capture the verdict the way [SKILL.md](SKILL.md) rule 6 describes (an issue comment when there is an issue). The validated reducer / machine / function set lifts into the real module; the HTML shell is thrown away.
+
+## Anti-patterns
+
+- **Don't add tests.** A prototype that needs tests is no longer a prototype.
+- **Don't wire it to the real database.** Use in-memory state unless the question is specifically about persistence.
+- **Don't generalise.** No "what if we wanted to support X later." The prototype answers one question.
+- **Don't blur the logic and the page together.** If the pure module references the DOM, `document`, or button handlers, it's no longer liftable. Keep the page as a thin shell over a pure module.
+- **Don't reach for a framework, bundler, or server.** One file the recipient double-clicks; a React app or a dev server defeats "shareable".
+- **Don't ship the HTML shell into production.** The page is optimised for being clicked through by hand. The logic module behind it is the bit worth keeping.

package/skills/prototype/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: prototype
+description: Build a throwaway prototype to answer a design question, delivered as one self-contained HTML file. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
+---
+
+<!--
+Modified copy of https://github.com/mattpocock/skills/tree/3cca18b368ae95cdbdebbff572ccafa662551015/skills/engineering/prototype
+(mattpocock-skills v1.2.3). Copyright (c) 2026 Matt Pocock, MIT — see LICENSE.
+Changes: the UI branch produces one self-contained HTML file holding every
+variation (no routes, no dev server) instead of routes in the running app; the
+file is written to the path the invoking prompt names; the verdict is captured as
+an issue comment instead of a throwaway branch.
+-->
+
+# Prototype
+
+A prototype is **throwaway code that answers a question**. The question decides the shape, but the delivery is always the same: **one self-contained HTML file** that opens by double-click, with no build step and no server. That is what lets a machine with no browser serve it as a file and a person open it on a phone.
+
+## Pick a branch
+
+Identify which question is being answered, using the user's prompt, the surrounding code, or by asking if the user is around:
+
+- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Free-play buttons plus tabbed guided walkthroughs that push the state machine through cases that are hard to reason about on paper, and that a non-developer can drive.
+- **"What should this look like?"** → [UI.md](UI.md). Several radically different UI variations in one page, switchable inside the page from a floating bottom bar.
+
+The two branches produce very different pages, so getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.
+
+## Rules that apply to both
+
+1. **One file, clearly a prototype.** Everything inline: HTML, CSS, JS, sample data. No framework, no bundler, no server, no network requests. Write it to the path the invoking prompt names; with no path given, put it next to the module or page it prototypes for, named `<name>.prototype.html`, so a casual reader sees it is a prototype and not production.
+2. **Trivial to run.** Opening the file is the whole procedure. No thinking required to start it.
+3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is _checking_, not something it should depend on.
+4. **Skip the polish.** No tests, no error handling beyond what makes the prototype _runnable_, no abstractions. The point is to learn something fast.
+5. **Surface the state.** After every action (logic) or on every variant switch (UI), render the full relevant state so the user can see what changed.
+6. **Capture the verdict where the next reader looks.** When the work has a GitHub issue, post the verdict as a comment on it: the question, the answer (which variant, which model, or "none of these"), and the reason. The next stage is often a fresh session that reads the issue thread and has never seen the file. With no issue, tell the user the verdict and where the file is. Fold any validated decision into the real code (a validated reducer lifts into the real module; a winning layout is rebuilt properly, not copied). The prototype file itself never lands on `main`: leave it uncommitted, or delete it once the verdict is recorded.
+
+```bash
+gh issue comment <number> --repo <owner/repo> --body-file /tmp/verdict.md
+```