@thedecipherist/claude-packs 0.0.0-stage → 1.1.0

package/packs/shell/rules/shell-strict-and-quoted.md

@@ -0,0 +1,27 @@
+---
+# concepts: shell
+paths:
+  - "placeholder"
+---
+
+# Shell fails loudly and quotes everything
+
+<constraints>
+Always do:
+- Start a script with `set -euo pipefail`. A file that is only sourced leaves that to its caller.
+- Quote every expansion: `"$file"`, `"${list[@]}"`.
+- Use `$(...)`, never backticks.
+- Guard a variable in a delete: `rm -rf "${dir:?}/build"`.
+- Make a temp file with `mktemp`, and remove it with `trap`.
+- Stop what you start: after `child &`, `trap 'kill "$pid" 2>/dev/null' EXIT INT TERM`.
+- Keep a program in its own file: a script that needs Python or Node calls a file, which can be linted and tested.
+- Run `shellcheck` where the project has it.
+
+Never do:
+- Use `eval`, or pipe a download into a shell.
+- Parse `ls`: use a glob.
+- Write to a fixed path in `/tmp`.
+</constraints>
+
+## Check
+`sh-strict-mode`, `sh-no-backticks`, `sh-no-eval`, `sh-no-parse-ls`, `sh-rm-guarded`, `sh-quote-arguments`, `sh-no-pipe-to-shell`, `sh-mktemp`, `sh-no-program-in-heredoc`.

package/packs/shell/skills/shell-extract-template/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: shell-extract-template
+description: Use when template-law refuses shell code, when scan lists repeated shell, or when copying a script to start another.
+---
+
+# Extract a shell repeat into one template (one job: pick the shell form, and move every copy to it)
+
+Follow `make-it-a-template`. This skill is its shell forms.
+
+<constraints>
+Always do:
+1. A repeated block: one function in the shared file, what differs as its arguments, read into named locals.
+   ```bash
+   wait_for_file() {
+     local file="$1" what="$2"
+     wingate_wait "$pid" "[ -s '$file' ]" || exit 1
+     [ -s "$file" ] || { echo "FAIL no $what" >&2; exit 1; }
+   }
+   ```
+2. One command with other arguments: a table and one loop.
+   ```bash
+   rows=("a silent slot|PLANT_SILENT" "a dead key|PLANT_DEAD")
+   for row in "${rows[@]}"; do expect_fail "${row%%|*}" env "${row##*|}=1" "$gate"; done
+   ```
+3. Source the shared file by its own location, so it works from any folder: `. "$(dirname "$0")/lib.sh"`.
+4. A program pasted into a heredoc: move it to its own file and call it.
+5. Run the scripts the change reaches. Then search for the old block: none is left.
+
+Never do:
+- Pass values through globals when an argument will do.
+- Use `eval` to make a function general.
+</constraints>

package/packs/shell-hooks/checks/gnu-only-in-shell.json

@@ -0,0 +1,18 @@
+{
+  "id": "gnu-only-in-shell",
+  "why": "GNU-only: on macOS `date +%N` prints the literal N, sha1sum/stat -c/readlink -f do not exist, and the hook exits non-zero, which blocks every tool call. Use node -e for time, hashes and file stats.",
+  "rule": ".claude/rules/hooks-portable-anchored-quoted.md",
+  "concepts": [
+    "shell-hooks"
+  ],
+  "globs": [
+    "**/*.sh"
+  ],
+  "exclude": [
+    "**/node_modules/**"
+  ],
+  "code": false,
+  "pattern": "\\bdate\\s+\\+\\S*%\\d*N|\\b(?:sha1|sha256|md5)sum\\b|\\bstat\\s+-c\\b|\\breadlink\\s+-f\\b|\\bsed\\s+-i\\s+(?!'')(?!\\\")[^\\s]",
+  "bad": "NOW=$(date +%s%3N)",
+  "good": "NOW=$(node -e 'console.log(Date.now())')\nH=$(node -e 'const c=require(\"node:crypto\");console.log(c.createHash(\"sha1\").update(process.argv[1]).digest(\"hex\").slice(0,12))' \"$DIR\")"
+}

package/packs/shell-hooks/checks/hook-command-anchored.json

@@ -0,0 +1,12 @@
+{
+  "id": "hook-command-anchored",
+  "why": "A relative hook command resolves only when Claude Code starts in one directory; from a subfolder or /cd it silently never runs. Anchor on $CLAUDE_PROJECT_DIR or an absolute path.",
+  "rule": ".claude/rules/hooks-portable-anchored-quoted.md",
+  "concepts": [
+    "hook-settings"
+  ],
+  "code": false,
+  "pattern": "\\\"command\\\"\\s*:\\s*\\\"(?!(?:node|bash|sh|python3?|npx)\\s+\\\\?\\\"?(?:\\$CLAUDE_PROJECT_DIR|\\$HOME|~|/))(?!\\$CLAUDE_PROJECT_DIR|/|~)",
+  "bad": "\"command\": \"bash packages/channel/hooks/check-signal.sh\"",
+  "good": "\"command\": \"node \\\"$CLAUDE_PROJECT_DIR/.claude/hooks/check-signal.mjs\\\"\""
+}

package/packs/shell-hooks/checks/hook-json-by-tool.json

@@ -0,0 +1,18 @@
+{
+  "id": "hook-json-by-tool",
+  "why": "printf-built JSON breaks on the first quote or backslash in a value and the consumer drops the line silently. Produce JSON with node -e or jq.",
+  "rule": ".claude/rules/hooks-portable-anchored-quoted.md",
+  "concepts": [
+    "shell-hooks"
+  ],
+  "globs": [
+    "**/*.sh"
+  ],
+  "exclude": [
+    "**/node_modules/**"
+  ],
+  "code": false,
+  "pattern": "\\b(?:printf|echo)\\s+(?:-e\\s+)?['\\\"]\\s*\\{[^'\\\"]*\\\\?\\\"\\w+\\\\?\\\"\\s*:",
+  "bad": "printf '{\"decision\":\"block\",\"reason\":\"%s\"}' \"$1\"",
+  "good": "node -e 'console.log(JSON.stringify({ decision: \"block\", reason: process.argv[1] }))' \"$1\""
+}

package/packs/shell-hooks/checks/no-bash-c-with-variable.json

@@ -0,0 +1,20 @@
+{
+  "id": "no-bash-c-with-variable",
+  "why": "bash -c with a string the project can edit runs whatever that file says; a gate command rewritten to `true` turns red green. Hash-pin the config or pass an argv array.",
+  "rule": ".claude/rules/hooks-portable-anchored-quoted.md",
+  "globs": [
+    "**/*.ts",
+    "**/*.js",
+    "**/*.mjs"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/*.test.*",
+    "**/test/**"
+  ],
+  "code": false,
+  "pattern": "\\bspawn(?:Sync)?\\s*\\(\\s*['\\\"](?:bash|sh|zsh)['\\\"]\\s*,\\s*\\[\\s*['\\\"]-c['\\\"]\\s*,\\s*(?!['\\\"`])[\\w.]+",
+  "bad": "const child = spawn('bash', ['-c', command], { cwd });",
+  "good": "const child = spawn(argv[0], argv.slice(1), { cwd });"
+}

package/packs/shell-hooks/pack.json

@@ -0,0 +1,36 @@
+{
+  "name": "shell-hooks",
+  "version": "1.0.0",
+  "description": "Shell and Node hooks for Claude Code: portable, anchored, quoted, one prelude, JSON by a tool.",
+  "type": "stock",
+  "author": "claude-packs",
+  "license": "MIT",
+  "homepage": "https://github.com/TheDecipherist/claude-packs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TheDecipherist/claude-packs.git",
+    "directory": "packs/shell-hooks"
+  },
+  "keywords": [
+    "hooks",
+    "shell"
+  ],
+  "engines": {
+    "claude-packs": ">=0.19.0"
+  },
+  "folders": {},
+  "concepts": {
+    "shell-hooks": [
+      "**/hooks/**/*.sh",
+      "**/hooks/**/*.mjs",
+      "**/hooks/**/*.js",
+      "**/hooks/**/*.cjs"
+    ],
+    "hook-settings": [
+      "**/.claude/settings.json",
+      "**/.claude/settings.local.json"
+    ]
+  },
+  "skillsIn": null,
+  "hooks": {}
+}

package/packs/shell-hooks/rules/hooks-portable-anchored-quoted.md

@@ -0,0 +1,26 @@
+---
+# concepts: shell-hooks, hook-settings
+paths:
+  - "placeholder"
+---
+
+# A hook is portable, anchored, quoted, and fails open on its own bugs only
+
+A PreToolUse hook that errors blocks **every** tool call. `date +%s%3N` prints the literal `3N` on macOS and the arithmetic that follows exits non-zero: one GNU-ism blocks the whole session on a Mac.
+
+<constraints>
+Always do:
+- Time, hashes and JSON in a hook come from `node -e` (or the `.mjs` hook itself), never GNU-only binaries: no `date +%N`, `sha1sum`, `stat -c`, `readlink -f`, `sed -i` without a suffix (`gnu-only-in-shell`). Prefer `.mjs` hooks over `.sh` for anything beyond ten lines.
+- JSON is produced by `node -e`/`jq`, never by `printf '{"a":"%s"}'` (`hook-json-by-tool`): an unescaped quote or backslash corrupts the line and the consumer drops it silently.
+- Hook commands in `settings.json` are anchored: `node "$CLAUDE_PROJECT_DIR/.claude/hooks/x.mjs"`. A relative `bash packages/x/hooks/y.sh` resolves only from one cwd (`hook-command-anchored`).
+- Shared logic (read stdin, find the marker, freshness test) lives in **one** `lib/` file that every hook imports or sources; a change to the marker format is one edit.
+- Anything a hook spools to disk is written with mode 0600 and masked **before** it hits disk; the terminal prompt may contain a pasted token.
+- Credentials come from one documented env var; a hook never searches `~/.claude.json`, a repo `.env` and the environment in turn.
+- `--selftest` in every hook; the project test suite runs each hook's selftest and fires every hook at a sibling project path, which must never block (`never block other projects`).
+- A hook that fails open says so in one comment at the top, and names what is unenforced during an outage.
+
+Never do:
+- `bash -c "${command}"` with a string the project (the executor) can edit; gates run from a hash-pinned config or argv arrays.
+- Parse JSON with `grep -o '"key":"value"'` that depends on `JSON.stringify` key order; use `node -e` with `JSON.parse`.
+- Rewrite `settings.local.json` on server boot; installers are explicit commands with a dry run.
+</constraints>

package/packs/sound-design/checks/audio-seed-fixed.json

@@ -0,0 +1,23 @@
+{
+  "id": "audio-seed-fixed",
+  "why": "An unseeded source makes two renders differ, and every measurement then carries noise.",
+  "rule": ".claude/rules/meter-before-engine.md",
+  "globs": [
+    "**/*.cpp",
+    "**/*.cc",
+    "**/*.h",
+    "**/*.hpp",
+    "**/*.mm"
+  ],
+  "exclude": [
+    "**/build/**",
+    "**/out/**",
+    "**/_deps/**",
+    "**/JUCE/**",
+    "**/node_modules/**"
+  ],
+  "pattern": "\\bstd::random_device\\b|\\bsrand\\s*\\(\\s*(?:std::)?time\\s*\\(|\\bjuce::Random::getSystemRandom\\s*\\(|\\bjuce::Random\\s+\\w+\\s*;",
+  "bad": "std::mt19937 rng{std::random_device{}()};",
+  "good": "std::mt19937 rng{kNoiseSeed};",
+  "code": true
+}

package/packs/sound-design/checks/mix-is-a-crossfade.json

@@ -0,0 +1,30 @@
+{
+  "id": "mix-is-a-crossfade",
+  "why": "A mix that scales only the wet path is silent at 0%. It is a crossfade.",
+  "rule": ".claude/rules/neutral-is-exact.md",
+  "globs": [
+    "**/*.cpp",
+    "**/*.cc",
+    "**/*.h",
+    "**/*.hpp",
+    "**/*.mm"
+  ],
+  "exclude": [
+    "**/build/**",
+    "**/out/**",
+    "**/_deps/**",
+    "**/JUCE/**",
+    "**/node_modules/**",
+    "**/tests/**",
+    "**/test/**",
+    "**/probes/**",
+    "**/gates/**",
+    "**/*_test.*",
+    "**/*.test.*"
+  ],
+  "pattern": "=\\s*\\w*wet\\w*\\s*\\*\\s*\\w*mix\\w*\\s*;",
+  "bad": "out = wet * mix;",
+  "good": "out = dry * c + wet * s;",
+  "flags": "i",
+  "code": true
+}

package/packs/sound-design/checks/no-hash-in-the-signal.json

@@ -0,0 +1,30 @@
+{
+  "id": "no-hash-in-the-signal",
+  "why": "A hash in the signal path invents a difference the machine does not have, and hides a missing law.",
+  "rule": ".claude/rules/neutral-is-exact.md",
+  "globs": [
+    "**/*.cpp",
+    "**/*.cc",
+    "**/*.h",
+    "**/*.hpp",
+    "**/*.mm"
+  ],
+  "exclude": [
+    "**/build/**",
+    "**/out/**",
+    "**/_deps/**",
+    "**/JUCE/**",
+    "**/node_modules/**",
+    "**/tests/**",
+    "**/test/**",
+    "**/probes/**",
+    "**/gates/**",
+    "**/*_test.*",
+    "**/*.test.*"
+  ],
+  "pattern": "(?:cut|res|gain|level|filter)\\w*\\s*[*+]?=[^;\\n]*\\bhash\\w*\\s*\\(",
+  "bad": "cutoff *= 0.7f + 0.6f * hash01 (id);",
+  "good": "cutoff *= zone.trim;",
+  "flags": "i",
+  "code": true
+}

package/packs/sound-design/checks/no-literal-key-anchor.json

@@ -0,0 +1,30 @@
+{
+  "id": "no-literal-key-anchor",
+  "why": "A hard-coded key anchor is zero exactly where everyone auditions, so a wrong law passes by ear. Name it, with its source.",
+  "rule": ".claude/rules/test-off-the-easy-point.md",
+  "globs": [
+    "**/*.cpp",
+    "**/*.cc",
+    "**/*.h",
+    "**/*.hpp",
+    "**/*.mm"
+  ],
+  "exclude": [
+    "**/build/**",
+    "**/out/**",
+    "**/_deps/**",
+    "**/JUCE/**",
+    "**/node_modules/**",
+    "**/tests/**",
+    "**/test/**",
+    "**/probes/**",
+    "**/gates/**",
+    "**/*_test.*",
+    "**/*.test.*"
+  ],
+  "pattern": "(?:cut|filter|key)\\w*[^;\\n]*\\(\\s*\\w*note\\w*\\s*-\\s*60(?:\\.0*f?)?\\s*\\)",
+  "bad": "cut += kt * (note - 60) / 12.0;",
+  "good": "cut += kt * (note - kKeyAnchor) / 12.0;",
+  "flags": "i",
+  "code": true
+}

package/packs/sound-design/checks/test-compares-a-function-with-itself.json

@@ -0,0 +1,22 @@
+{
+  "id": "test-compares-a-function-with-itself",
+  "why": "A test that compares a function with itself passes by construction. Assert the printed value.",
+  "rule": ".claude/rules/test-off-the-easy-point.md",
+  "globs": [
+    "**/*.cpp",
+    "**/*.cc",
+    "**/*.h",
+    "**/*.hpp",
+    "**/*.mm"
+  ],
+  "exclude": [
+    "**/build/**",
+    "**/out/**",
+    "**/_deps/**",
+    "**/JUCE/**",
+    "**/node_modules/**"
+  ],
+  "pattern": "\\b(?:EXPECT_(?:EQ|NEAR|DOUBLE_EQ|FLOAT_EQ)|ASSERT_(?:EQ|NEAR)|expectWithinAbsoluteError|expectEquals)\\s*\\(\\s*([\\w:.]+)\\s*\\([^()]*\\)\\s*,\\s*\\1\\s*\\(",
+  "bad": "EXPECT_NEAR(cutoffHz(v), cutoffHz(v), 0.01);",
+  "good": "EXPECT_NEAR(cutoffHz(74), 987.8, 0.1);"
+}

package/packs/sound-design/pack.json

@@ -0,0 +1,22 @@
+{
+  "name": "sound-design",
+  "version": "1.0.0",
+  "description": "Sound that is proved by measuring audio: algorithms are data, neutral is exact, the meter is suspected before the engine, and tests sit off the easy point.",
+  "type": "stock",
+  "author": "claude-packs",
+  "license": "MIT",
+  "homepage": "https://github.com/TheDecipherist/claude-packs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TheDecipherist/claude-packs.git",
+    "directory": "packs/sound-design"
+  },
+  "keywords": [
+    "audio",
+    "dsp",
+    "sound-design"
+  ],
+  "engines": {
+    "claude-packs": ">=0.28.0"
+  }
+}

package/packs/sound-design/rules/algorithms-are-data.md

@@ -0,0 +1,26 @@
+---
+paths:
+  - "**/*.cpp"
+  - "**/*.cc"
+  - "**/*.h"
+  - "**/*.hpp"
+  - "**/*.mm"
+  - "**/*.py"
+  - "**/*.ts"
+  - "**/*.js"
+  - "**/*.mjs"
+---
+
+# A machine's algorithm list is real only if each one is the right kind of effect
+
+<constraints>
+Always do:
+- Make each algorithm a block graph, as data, run by one loop.
+- Prove the kind by measuring: a delay delays, a comb combs, a filtered delay is filtered.
+- Report spread per algorithm and across the bank, as medians, over 8 seconds or more, with log-spaced frames.
+- Use the machine's own numbers: its stage count, its interval, its delay memory.
+
+Never do:
+- Pass a table test as proof. One unit had 15 algorithms on 1 DSP path, and another had 13 of 23 that were a wire.
+- Build a family of effects on a single generic engine and call the list done.
+</constraints>

package/packs/sound-design/rules/meter-before-engine.md

@@ -0,0 +1,27 @@
+---
+paths:
+  - "**/*.cpp"
+  - "**/*.cc"
+  - "**/*.h"
+  - "**/*.hpp"
+  - "**/*.mm"
+  - "**/*.py"
+  - "**/*.ts"
+  - "**/*.js"
+  - "**/*.mjs"
+---
+
+# Suspect the meter before the engine, and make the render repeat
+
+<constraints>
+Always do:
+- Make a probe's first assertion that the render reproduces. Reset every phase, ramp and seed on prepare, in its own commit.
+- Read a constant ratio or an exact multiple as a meter fault first. Fix it, re-fit what was tuned against it, and grep for the same code.
+- Assert against an absolute expected value. A meter wrong by a steady percentage passes every comparison of measurements.
+- Flush between programs, and silence earlier voices.
+- Use an RMS window longer than the oscillator's period, and RMS over whole periods for a rate.
+
+Never do:
+- Believe a factor of two: filter resonance puts two level peaks in every LFO cycle.
+- Leave a meter bug in place because it flatters the score.
+</constraints>

package/packs/sound-design/rules/neutral-is-exact.md

@@ -0,0 +1,26 @@
+---
+paths:
+  - "**/*.cpp"
+  - "**/*.cc"
+  - "**/*.h"
+  - "**/*.hpp"
+  - "**/*.mm"
+  - "**/*.py"
+  - "**/*.ts"
+  - "**/*.js"
+  - "**/*.mjs"
+---
+
+# A control at its neutral computes exactly nothing
+
+<constraints>
+Always do:
+- Make a control at its documented neutral compute exactly 1.0, or exactly 0.
+- Make 0% wet come out dry, never silent: a mix is a crossfade.
+- Start blank programs at neutral. A modulation byte of 0 can mean full negative depth.
+- Fail on a blank extraction row: clamping it to zero rendered 66 presets silent.
+
+Never do:
+- Leave a default that colours every preset: this is how a bank ends up "all sounding the same".
+- Hash a value into the signal path to make voices differ.
+</constraints>

package/packs/sound-design/rules/test-off-the-easy-point.md

@@ -0,0 +1,28 @@
+---
+paths:
+  - "**/*.cpp"
+  - "**/*.cc"
+  - "**/*.h"
+  - "**/*.hpp"
+  - "**/*.mm"
+  - "**/*.py"
+  - "**/*.ts"
+  - "**/*.js"
+  - "**/*.mjs"
+---
+
+# Test where a wrong answer cannot pass
+
+<constraints>
+Always do:
+- Vary the thing the error lives in, all the way down: low, middle and high notes; the tempo, not the division; two points for "A follows B"; phase apart from rate.
+- Take expected values from the printed source, not the code.
+- Trace where a term acts: velocity on depth is not velocity on output.
+- Excite what you test. A click hid 100x of preset difference.
+- Use two anchors to fix a law: one fits any curve.
+
+Never do:
+- Use one point that is zero exactly where everyone auditions: `note - 60` passes at middle C.
+- Compare a function with itself.
+- Invent a term. It is worse than a missing one.
+</constraints>

package/packs/sound-design/rules/unreachable-is-said.md

@@ -0,0 +1,25 @@
+---
+paths:
+  - "**/*.cpp"
+  - "**/*.cc"
+  - "**/*.h"
+  - "**/*.hpp"
+  - "**/*.mm"
+  - "**/*.py"
+  - "**/*.ts"
+  - "**/*.js"
+  - "**/*.mjs"
+---
+
+# What cannot be reached is said, never clamped
+
+<constraints>
+Always do:
+- Silence and count an out-of-range target.
+- Grey what a destination cannot reach, and say why.
+- Find the real control rate, not the timer period: a scheduler serving 16 voices in turn scales every envelope by 16.
+- Read both signs of a law before linearising it, and suspect the fixed-point format when a constant lands near a real number.
+
+Never do:
+- Clamp in silence, or let an array bound thin a pattern.
+</constraints>

package/packs/sound-design/rules/waveforms-and-octaves.md

@@ -0,0 +1,24 @@
+---
+paths:
+  - "**/*.cpp"
+  - "**/*.cc"
+  - "**/*.h"
+  - "**/*.hpp"
+  - "**/*.mm"
+  - "**/*.py"
+  - "**/*.ts"
+  - "**/*.js"
+  - "**/*.mjs"
+---
+
+# A waveform can be data, an oscillator or a generator; an octave can be locked or free
+
+<constraints>
+Always do:
+- Decide what a waveform is: data read from a table, what the oscillator itself is, or a generator beside it. If two cannot coexist on the original, they are modes.
+- Derive a locked sub from its parent's increment.
+- Treat a free layer as a whole voice.
+
+Never do:
+- Dedupe pitches in the allocator: two layers on one note is the sound.
+</constraints>

package/packs/sound-design/skills/bounce-a-plugin/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: bounce-a-plugin
+description: Use when audio has to be rendered from a VST3 with no DAW, when comparing an engine with another plugin or an emulator, when fitting a law against a plugin, or when a plugin will not load in a JUCE host or plays silence.
+---
+
+# Bounce a plugin (one job: a known input through a plugin, and the audio out, repeatable)
+
+`.claude/tools/vst3host/` is an offline VST3 renderer: no DAW, no audio device, no window, faster than real time. It does not link JUCE, on purpose: a JUCE host cannot load every JUCE plugin.
+
+```
+bash .claude/tools/vst3host/build.sh            # once, after the project's first configure; macOS and Linux
+R=out/vst3host/render
+$R --vst3 <plugin> --list                       # every parameter, with its id
+$R --vst3 <plugin> --out a.wav --note 60 --vel 100 --hold 1.5 --tail 0.6
+$R --vst3 <plugin> --param 12=0.75 --sweep 38:9 --dir out/   # one note per value of 38, 12 frozen
+$R --vst3 <plugin> --program 5 --bank 0:1 --out a.wav        # the same factory patch a machine was recorded on
+$R --vst3 <plugin> --sysex patch.syx --dump-params           # send a patch, and read whether it was taken
+```
+
+The WAV is 32-bit float, so a plugin that peaks over 1.0 is measured, never clipped. For a Roland machine, `--dt1-head "41 10 00 06" --dt1-base 1004000` sends DT1: `--dt1 OFF=VAL` pins a value, `--sweep-dt1 OFF:STEPS[:MAX]` and a repeated `--axis` sweep, `--probe LO-HI[:V1,V2]` finds which offset is a control, and `--map LO-HI[:VAL]` asks the plugin which parameter an offset is.
+
+<constraints>
+Always do:
+1. Run `--list` first. `--param` and `--sweep` take the id, never the row number. A wrong id is ignored, and the sweep renders the same sound with no complaint.
+2. Prove the bounce before you trust it. Render twice: same bytes means the plugin is repeatable, and you can compare exactly. If it is not (a free-running oscillator, modelled drift), compare averages of several bounces, and say so.
+3. Prove a control reaches the audio: sweep it, and measure that the audio moves. Two renders that match byte for byte mean the control did nothing.
+4. Render one note per value. Move a control between notes, never under one.
+5. Give a firmware emulator its boot: `--boot 12`. The emulated processor needs real samples before it answers a note, and a short boot reads as a silent plugin.
+6. When parameters do nothing, try sysex. A firmware emulator may ignore host automation and answer only the machine's own messages. The renderer sets both the controller and the processor's queue, and if the audio is still byte-identical, sysex is the way in.
+7. Ask whether a dump was taken: `--dump-params` before and after. A rejected dump and an accepted one that sounds alike cannot be told apart in a WAV. Identical output means the patches never arrived, whatever the spectra look like.
+8. Fix everything else: patch, note, velocity, sample rate, effects off. To fit one control, move only that control. A factory-patch recording cannot fit a law, since a performance has its chorus on.
+9. To compare two engines, render both with the same patch and the same notes, and name in the report what the other engine is. An emulation is a reference, not the machine: tag it as what it is, and record where it disagrees with the schematic rather than choosing quietly.
+
+Never do:
+- Open an audio device, or route through a loopback, to capture a plugin. On macOS a permission denial returns silence, not an error.
+- Load a plugin in a JUCE host to measure it and trust a crash as the plugin's fault: an allocator clash across the boundary aborts inside the plugin's own loader.
+- Read one output bus as all of them. The renderer gives every bus a buffer and keeps bus 0: a plugin with several may send a part elsewhere.
+- Commit a render: it is a build output, and a plugin's sound may be someone else's. Keep the numbers.
+- Run a cracked or unlicensed plugin. Use the maker's trial.
+</constraints>

package/packs/sound-design/skills/choose-observable/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: choose-observable
+description: Use when writing a probe, when a measurement is noisy, or when deciding what audio can prove a behaviour.
+---
+
+# Choose the observable (one job: measure the signal that can prove it)
+
+<constraints>
+Always do:
+1. Check preconditions: renders bit-identical, start state checked, stale frames drained, the program found by name.
+2. Take the best rung: a pure gain (exact), pulse width, a stereo difference with a hard zero, pitch through the phase null, a filter, a comb's energy.
+3. On pitch, keep the depth tiny: the law is exponential, and the error accumulates.
+4. On a sampler, take the median of consecutive gaps.
+5. If it cannot see phase, say so. Assert the offset does not move, and log the open item.
+
+Never do:
+- Measure phase through a comb, or trust a filter's lowest point as its vertex.
+</constraints>

package/packs/sound-design/skills/measure-a-law/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: measure-a-law
+description: Use when fitting or checking a law against a machine or a reference recording.
+---
+
+# Measure a law (one job: a fit you can defend)
+
+<constraints>
+Always do:
+1. Use a sine at the frequency you read. A filter slope read on a saw was off by 2.3 dB per octave.
+2. Write a filter's law in the units its procedure uses.
+3. Fix it with two anchors.
+4. Keep fitted constants scripted, tagged, and rerunnable.
+5. Write disproofs down.
+
+Never do:
+- Fit a single point.
+</constraints>

package/packs/sound-design/skills/measure-reverb/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: measure-reverb
+description: Use when measuring or calibrating a reverb or a decay time.
+---
+
+# Measure a reverb (one job: a decay time you can trust)
+
+<constraints>
+Always do:
+1. Mute dry and early reflections, and zero the pre-delay.
+2. Use Schroeder T30, or a least-squares fit of the tail.
+3. Measure over a long enough render for the longest setting.
+4. Read the law in the units its procedure uses.
+5. Compare with the printed figure.
+
+Never do:
+- Read a time off the peak level.
+- Inherit a sibling machine's law: reverb times were once 20 to 45% short that way.
+</constraints>

package/packs/sound-design/skills/spread-probe/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: spread-probe
+description: Use when presets sound alike, when a bank is finished, or when an algorithm list is built.
+---
+
+# Measure the spread (one job: the programs really differ)
+
+<constraints>
+Always do:
+1. Render every program with the same excitations, chosen to excite what differs.
+2. Measure the difference between programs, per algorithm and across the bank, as medians.
+3. Count the effectively distinct sounds, and report it next to the total.
+4. Check the upstream causes first: an invented global, programs loading defaults, an algorithm with min equal to max.
+5. Share one probe across units, so a number means the same on every machine.
+
+Never do:
+- Accept "they all sound the same" as an opinion. It is a testable report: 625 presets once measured as 146.
+</constraints>