@mthines/reaper-mcp 0.19.0 → 0.70.2

package/claude/skills/mix-memory/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: mix-memory
+description: Recall and maintain the mixing skills' memory in LoreKit (scope project::reaper-mcp) — plugin knowledge records and self-healing process lessons, as a read-only built-in layer plus the user's own layer on top. Modes — recall (load what's relevant before work), consolidate (merge duplicate user lessons, fold proven plugin notes into recommended settings), promote (turn a recurring lesson into a hard rule), publish (maintainer only — move a user record into the built-in layer), status (what's stored, per layer). Triggers on "what have you learned", "recall mixing memory", "consolidate memory", "promote that lesson", "publish to built-in", "/mix-memory".
+disable-model-invocation: false
+argument-hint: '[recall|consolidate|promote|publish|status] [plugin-slug|lesson-slug]'
+---
+
+# /mix-memory
+
+Maintain and recall the two kinds of memory the mixing skills keep in
+**LoreKit** (scope `project::reaper-mcp`, via the `memory.*` MCP tools):
+
+- **Process lessons** — tag `loop::mixing-lessons`
+- **Plugin knowledge** — tag `plugin-knowledge`
+
+Each comes in two layers: the built-in one, read through the `reaper` tools
+`list_builtin_knowledge` / `get_builtin_knowledge` (public read-only token, no
+LoreKit account needed), and the user's own, through `memory.*`:
+
+| Layer | Keys | Tag | Writable here |
+|-------|------|-----|---------------|
+| Built-in (`reaper-mcp` org, curated) | `plugins::<vendor>/<plugin>`, `mixing-lessons::<slug>` | `layer::built-in` | only via `publish` |
+| User (personal) | `user::plugins::<vendor>/<plugin>`, `user::mixing-lessons::<slug>` | `layer::user` | yes |
+
+**Never write or `memory.delete` a built-in key outside `publish`** — a delete
+without `org` archives the org row too.
+
+The full contract — buckets, body shapes,
+entrenchment guards — is `knowledge/reference/memory-protocol.md`; read it before
+any write. If the `memory.*` tools are not connected, read `~/.claude/knowledge/reference/lorekit-setup.md` (in a clone: `knowledge/reference/lorekit-setup.md`), walk the user through connecting LoreKit, and carry on once it is (stop only if they decline).
+
+## Mode detection
+
+Parse the first argument:
+
+| Mode | Default | Trigger phrases |
+|------|---------|-----------------|
+| `recall` | **yes** | "what have you learned", "recall", "what do you know about {plugin}" |
+| `consolidate` | | "consolidate memory", "compress memory", "tidy memory" |
+| `promote` | | "promote that lesson", "make it a rule" |
+| `publish` | | "publish to built-in", "make it a default", "share this plugin record" |
+| `status` | | "memory status", "what's stored", "list memory" |
+
+State the detected mode in one line before acting.
+
+---
+
+## recall
+
+1. Lessons: `memory.list { scope: "project::reaper-mcp", tags: ["loop::mixing-lessons"], order: "rank", limit: 5 }`
+   — plus a `memory.search` on the current task's keywords. Surface those whose
+   **Applies when** matches.
+2. For a named plugin: `get_builtin_knowledge { key: "plugins::<vendor>/<plugin>" }`
+   and `memory.read` of `user::plugins::<vendor>/<plugin>` (find the slug via the `fx::` tags if you
+   only have an FX name) and report the combined record, marking what comes from
+   the user's layer.
+3. No argument: summarise — lesson count per layer, which plugins are known (built-in,
+   user, or both; which have learned notes), anything
+   promotion-eligible (`seen_count >= 3` or tag `status::structural`, not yet
+   `status::promoted`).
+
+This is what the mixer/mastering/critique skills do automatically at the start of
+work — use this mode to inspect memory manually.
+
+---
+
+## consolidate
+
+Show a preview of every change and get confirmation before writing.
+
+Only `user::` records are touched — the built-in layer is read-only.
+
+- **Lessons** — `memory.list` the bucket (`view: "summary"`), find near-duplicate
+  `user::` lessons, merge each pair into the older key (rewrite its body with the
+  sharper "Do this instead"), then `memory.delete` the duplicate. A `user::` lesson
+  that just repeats a built-in one adds nothing beyond its recurrence count — keep
+  it. Expiry is automatic — never archive by hand.
+- **Plugin overlays** — when `## Learned notes` sprawl, or kept settings have
+  proven themselves across contexts: fold them into the same `user::` record's
+  `## Recommended settings` tables and trim them from the notes (read-merge-write,
+  full tag list, no `ttl_days`). Param maps and gotchas stay in the notes.
+
+---
+
+## promote
+
+The self-heal step. For a lesson at `seen_count >= 3` or tagged `status::structural`:
+1. Show the lesson and the one-line hard rule it would become.
+2. On approval, append that rule to the **`## Hard Rules` (or `## Rules`) of the
+   skill that owns the behavior** — `mixer` for mix moves, `mastering` for
+   master-bus moves, `critique` for analysis/flagging lessons
+   (`.claude/skills/{skill}/SKILL.md`).
+3. Re-write the lesson with the same key, value and `ttl_days`, adding the tag
+   `status::promoted` (audit trail; it stops re-suggesting). For a built-in lesson,
+   write that tag on a `user::` copy instead — or, as the maintainer, `publish` it.
+
+Respect the entrenchment guards in `memory-protocol.md` — never promote a lesson
+that would relax an existing hard rule.
+
+---
+
+## publish
+
+Maintainer only: turn a proven `user::` record into a built-in default every user
+of the `reaper-mcp` org sees.
+
+1. `org.list` — continue only if the `reaper-mcp` org is listed with a writing
+   role (member, admin or owner). A viewer, or no membership: say so and stop
+   (the write would land in the personal store as a second copy).
+2. Read the `user::` record and, if present, the built-in record of the same slug.
+   Merge them (plugin: the overlay's sections over the built-in ones, learned
+   notes folded together; lesson: the sharper body). Strip anything personal per
+   the privacy guard. Show the merged record and get approval.
+3. `memory.write` with `org: "reaper-mcp"`, the key **without** `user::`, the
+   tags with `layer::built-in` in place of `layer::user`, and **no** `ttl_days`
+   (curated records are permanent).
+4. `memory.read` the built-in key to confirm, then `memory.delete` the `user::`
+   key (never the built-in key).
+5. **Plugin records only: update the built-in plugin list** (`docs/PLUGINS.md` in
+   the reaper-mcp clone). Find the clone: the current directory when it has
+   `scripts/plugin-list.mjs`, else the directory this skill is symlinked from
+   (`readlink ~/.claude/skills/mix-memory` → `<clone>/.claude/skills/mix-memory`).
+   Run `node <clone>/scripts/plugin-list.mjs`; it rebuilds the table from the
+   built-in layer, so it also picks up anything published earlier. Show the
+   changed rows and tell the maintainer to commit `docs/PLUGINS.md` (the
+   bridge's one-click Update refuses while the clone has local changes). No
+   clone found, or the script fails: say so; the daily **Plugin list** workflow
+   updates the list on `main` anyway.
+
+---
+
+## status
+
+Print a compact summary from `list_builtin_knowledge { limit: 100 }` (built-in) and
+`memory.list { scope: "project::reaper-mcp", tags: ["loop::mixing-lessons", "plugin-knowledge"], view: "summary", limit: 100 }` (yours):
+lesson count per layer (`layer::` tag) and how many are promotion-eligible,
+nearest lesson expiries, and known plugins grouped by `category::` (with
+preference, marked built-in / user / both). If the built-in tools error, say the
+built-in layer is unreachable (offline) and the user's own layer works alone. Suggest `consolidate`
+when duplicate lessons show up or a plugin record's notes sprawl.

package/claude/skills/mixer/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: mixer
+description: >
+  Mixes a live REAPER session — gain staging, FX chains, EQ, compression, and
+  problem-solving — executing changes in real time via the reaper MCP tools and
+  verifying with meters. Reads and writes personal plugin + process memory so it
+  improves each session. Use when the user asks to mix, balance, gain stage, build
+  a vocal or drum chain, fix the low end, or make something cut through. Triggers
+  on "mix this", "gain stage", "fix the low end", "build a vocal chain", "/mixer".
+argument-hint: '[what to mix or fix]'
+license: MIT
+metadata:
+  author: mthines
+  version: '1.0.0'
+  workflow_type: applied
+  tags:
+    - mixing
+    - reaper
+    - gain-staging
+    - fx
+    - eq
+    - compression
+    - audio
+---
+
+# Mixer
+
+Act as a professional mix engineer operating a **live** REAPER session through
+the `reaper` MCP tools — analyze, reason in audio-engineering terms, **execute
+changes in real time**, then verify with meters. You run in the current session
+(which already holds the REAPER connection); call the tools directly.
+
+The `reaper` server exposes the full tool set (tracks, FX, transport, metering,
+MIDI, media, envelopes, snapshots) — their schemas are already available, so call
+them rather than expecting a catalog here. When unsure of a plugin's exact name,
+use `search_fx`; FX parameters are normalized 0.0–1.0, so read `get_fx_parameters`
+before setting one.
+
+## Core principles
+
+1. **Snapshot before changes** — `snapshot_save`, so the user can A/B and revert.
+2. **Recall memory, then measure, then act** (see Memory + Workflow below).
+3. **Explain the reasoning** in audio terms, then execute.
+4. **Use the best available plugin** — `list_available_fx`, then prefer the
+   highest `preference::` among LoreKit plugin records that match; fall back to stock.
+5. **Iterate** — change, verify with meters, adjust.
+6. **Decide on perceived loudness, never raw values** — the ear is far more
+   sensitive at 2–5 kHz than at 100 Hz, and peak/RMS dBFS or raw band `db` ignore
+   that. Balance in **LU** (short-term LUFS of each element against the mix bus,
+   same section, post-fader), tone and masking in **`kDb`** (K-weighted bands).
+   Load `reference/perceived-loudness.md` for any balance or EQ decision: it
+   has the rules, the per-band K gains and the stem reference points.
+
+## Memory — get better every session
+
+Plugin knowledge and process lessons live in **LoreKit**, scope
+`project::reaper-mcp`, via the `memory.*` tools, in two layers: the read-only
+**built-in** layer (`plugins::…`, `mixing-lessons::…`, tag `layer::built-in`) and
+the user's own layer on top (`user::plugins::…`, `user::mixing-lessons::…`, tag
+`layer::user`). Read the built-in layer with the `reaper` tools
+`list_builtin_knowledge` / `get_builtin_knowledge` (no LoreKit account needed) and
+the user layer with `memory.*`; the user's record wins. **Every write goes to a
+`user::` key — never write or delete a built-in key.** Governed by
+`reference/memory-protocol.md` (read it before any write — it has the exact calls,
+record shapes, layer merge and plugin lookup):
+
+- **Start of task:** read the `loop::mixing-lessons` bucket (capped at 5, plus one
+  search on the task's keywords) and treat matching lessons as soft constraints.
+  For each plugin you'll touch, read both `get_builtin_knowledge
+  { key: "plugins::{vendor}/{plugin}" }` and `memory.read` of
+  `user::plugins::{vendor}/{plugin}` (find the slug via the `fx::` tags when
+  you only have the FX name) and combine them.
+- **Plugin gate — no plugin is touched before its memory is read.** Before the
+  first call that adds, sets, loads a preset for, writes MIDI to, or reads parameters
+  of a plugin (`add_fx`, `setup_fx_chain`, `set_fx_parameter`,
+  `set_multiple_fx_parameters`, `set_fx_preset`, `load_fx_chain`, MIDI for an
+  instrument track, take FX), look it up — every plugin, every time it is new to this
+  session, including ones the user named, ones already in the project and ones you
+  only meet while listing a chain. Never skip it because the plugin looks familiar.
+  Look up both layers: `list_builtin_knowledge { query: "<plugin name>" }` (or `tags:
+  ["fx::<FX name>"]`) / `get_builtin_knowledge { key: "plugins::{vendor}/{plugin}" }`,
+  and `memory.search` / `memory.read` of `user::plugins::{vendor}/{plugin}` (the user's
+  record wins). Then **follow the record**: its MIDI map and note ranges, parameter
+  scaling, recommended settings and gotchas decide what you do, and a setting you were
+  about to use that the record warns against is not used. Say it in one chat line
+  ("Recalled Odin x Ari Lite: notes <36 are keyswitches → transposing"). Keep a running
+  list of recalled plugins and don't re-read those. No record in either layer: say so
+  and carry on (or bootstrap it when the user asked for the plugin by name). LoreKit
+  not connected: say so once and use the built-in read only.
+- **A record with an `extension::<name>` tag** means an opt-in extension drives that
+  plugin's internals (for a synth: wavetables, mod matrix, LFO shapes). When
+  `list_tool_categories` shows that extension's category, use its tools for anything
+  structural and keep `set_fx_parameter` for quick nudges; read the extension's
+  `read_*` tool before changing a patch. Not installed: say the structural part is out
+  of reach and offer `reaper-mcp extension add <name>`.
+- **Asked to use a plugin you don't know?** Bootstrap it *before* mixing with it
+  (see the protocol): dispatch the `plugin-researcher` agent, which researches
+  the web, probes the plugin on a scratch track and writes its
+  `user::plugins::` record. If the agent isn't available, do those steps
+  yourself. Then read the record and use it. Refine it as you go.
+- **On a durable plugin learning** (a verified param-index map, a setting the user
+  kept, a gotcha): read-merge-write that plugin's `user::` record (an overlay
+  when only a built-in record exists), adding a
+  **contextualized** note under `## Learned notes` — never an absolute rule.
+- **At a correction point — write the lesson immediately, before your next action.**
+  A correction point is: the user reverted/rejected a change or said "no, that's
+  wrong"; a re-measure (meters/LUFS/correlation/crest) showed your change made it
+  worse; or you fell into a recurring trap. This is non-negotiable (see Hard
+  Rules) — do not defer it to the end, and **state in chat that you captured it**
+  (key + one-line takeaway). The dominant failure of this loop is *no capture at
+  all* — treat a silent skip as a bug.
+- **End-of-session retrospective (always, even on a clean run).** Before your
+  final report, stop and ask: did the user correct or override me, did a
+  measurement surprise me, did I guess at something that paid off or nearly
+  didn't, should a lesson I already had have fired earlier? If anything surfaced,
+  write or UPDATE a lesson (dedup-search first; rewriting the same key bumps the
+  store's `seen_count`, never duplicates). Write nothing only when the
+  retrospective is genuinely empty — and say which.
+- **When a lesson recurs (`seen_count >= 3`):** offer to promote it into the
+  Hard Rules below — the self-heal. Follow the protocol's entrenchment guards;
+  never let a lesson relax a hard rule.
+- After any write, name the LoreKit key you wrote.
+- **LoreKit not connected?** Say so once and carry on with the knowledge base and
+  general mixing knowledge.
+
+## Knowledge base (load on demand — don't preload)
+
+Shipped baseline at the project `.claude/knowledge/` or `~/.claude/knowledge/`
+(Glob to locate). Load only what the task needs (plugin knowledge is in LoreKit — see Memory):
+
+- `genres/{genre}.md` — genre EQ/compression/LUFS conventions (if a genre is named)
+- `workflows/{task}.md` — step-by-step procedures; map the request to one:
+  gain-staging · session-prep · vocal-chain · drum-bus · low-end · stereo-image ·
+  master-bus · stem-prep · delivery · section-levels · transient-lighting
+- `reference/*.md` — frequencies, compression, metering, perceived-loudness, aesthetics-scoring,
+  common-mistakes (read these instead of guessing).
+
+For analysis-only ("roast my mix"), defer to `/critique`. For final
+loudness/limiting, defer to `/mastering`.
+
+## Workflow for any task
+
+1. **Recall** — read mixing lessons + relevant plugin memory (Memory above).
+2. **Understand** the request; load the matching `workflows/` + `genres/` docs.
+3. **Snapshot** — `snapshot_save { name: "before-{task}" }`.
+4. **Analyze** — `list_tracks` (in a big session filter it: `parent` = a folder
+   index or name, `nameContains`, `compact: true`, `offset`/`limit`).
+   - **Whole song / master** — `analyze_track_offline` on the master (-1) or the
+     bus in question: it renders once, needs no playback, works on folder
+     tracks, and returns integrated LUFS, LRA, true peak, crest, per-section
+     loudness (`sectionSeconds`), band balance, resonance and sibilance hints.
+     Pass `referencePath` (or `analyze_audio_file` on a reference song) for the
+     tonal and loudness delta against a reference. Resonance hints are most
+     meaningful on a single track; on a full mix they also catch sustained notes.
+   - **Balance between elements** — `list_regions` to find a section where every
+     compared element plays; then one `measure_tracks` call over it with the mix
+     bus and the elements (`lufs`, plus `spectrum` for tone). Add each track's
+     fader to its reading (the meters are pre-fader), express it as LU below the
+     mix bus, and compare against the stem reference points. Read spectra 3+
+     times (each is a ~0.5 s snapshot). A track that gave no data is under
+     `errors`, not zeros. `read_track_meters` is for headroom and clipping only,
+     never for balance.
+   - **Multi-mic sources** (snare top/bottom, kick in/out, overheads vs close
+     mics) — `measure_track_alignment`, then `set_track_property` `playOffsetMs`
+     = `suggestedPlayOffsetMs` and `phase` = `suggestedPhase` (both absolute:
+     they already include the track's current offset and polarity). With a
+     `warning` (correlation under 0.3) there is no suggestion: pick a range where
+     both tracks play the same hits and measure again.
+5. **Discover plugins** — `list_available_fx`; match against LoreKit plugin
+   records by `category::` + `fx::` tags and pick the highest `preference::`
+   (a `user::` record's preference overrides the built-in one).
+6. **Execute** — make changes, explaining each in audio terms.
+7. **Verify** — re-measure the same section the same way (LU, `kDb`); compare
+   against the reference points; revert if worse. For a judgement call (did this
+   change make the mix better?), A/B level-matched: `analyze_track_aesthetics`
+   on the same 30 s range before and after (it normalizes to -18 LUFS by
+   default — `normalizeLufs` — so a louder version does not score better just
+   for being louder). Only Production Quality (PQ) and Content Usefulness (CU)
+   judge a mix change; Content Enjoyment and Production Complexity follow the
+   arrangement and level. Treat PQ differences under ~0.1 as no change
+   (`reference/aesthetics-scoring.md`). Then ask the user to listen: their ear
+   has the final say.
+   - **Measure during playback, not by rendering**, while the user is in the
+     session: a render's progress window (and `open -a REAPER script.lua`)
+     takes focus from them. `measure_tracks`, the meters and the gain-trace
+     pair below need only playback; render the final deliverable when the user
+     says so.
+   - **Offer 2–3 variants for a judgement call** (e.g. drive/clipping/drum
+     level): save each as a snapshot, then switch between them *live* with one
+     `run_plan` that sets only the parameters that differ. A full-chunk
+     `snapshot_restore` reloads the plugins and can drop out mid-playback.
+     State each variant's LUFS, since the louder one wins a quick A/B by level
+     alone.
+   - **MIDI, notes or arrangement variants** (a drum groove, a bass line, a
+     different chorus) cannot go in snapshots, which store faders and FX
+     parameters, not items. Hand them to `/editing`, which compares whole
+     versions in fixed lanes; keep the mix side in snapshots here.
+   - **"It ducks with the full mix but not soloed"** is pumping. Measure it
+     with two `JS: reaper-mcp/mcp_gain_trace` instances: mode pre at the
+     start of the chain, mode post at the end, and the same slot on both. Read
+     the post instance's p5/p1/std after playback (std ≈1.0–1.3 dB is clean
+     on a loud metal bus, 1.5+ pumps). Check every external-sidechain
+     dynamic EQ/comp band and follow its key with `get_track_routing`
+     (receives). Kick→bass ducking deeper than about −3 dB pumps. A key from
+     the vocal can't cause ducking on drum hits.
+     `measure_tracks` removes these instances when it cleans up its own meters,
+     so read the trace before calling it.
+8. **Capture** — write any durable plugin learnings / process lessons (Memory).
+   Correction points are written *when they happen* (step 7), not saved for here.
+9. **Report** — first run the **end-of-session retrospective** (Memory) and write
+   any lesson it surfaces; then `snapshot_save { name: "after-{task}" }` and
+   summarize before/after measurements, **what you captured to memory (or that
+   nothing was)**, and suggested next steps.
+
+## Hard Rules
+
+<!-- Promotion target: recurring process lessons graduate here via /mix-memory promote. -->
+
+- **No plugin without its memory.** Before the first add/set/preset/MIDI call on any plugin this session, look up its built-in and `user::` records and follow them (plugin gate under Memory). Skipping the lookup because the plugin looks familiar is a bug.
+
+- **Never skip the before-snapshot** — even for small changes. (Invariant.)
+- **Capture the lesson at the correction point.** If the user reverts/rejects a
+  change or a re-measure is worse, write the process lesson *before your next
+  action* and say you did. Never end a session that had a correction without a
+  written lesson. (Invariant — the loop's whole value depends on it.)
+- **Don't guess plugin names** — `search_fx` for the exact name.
+- **Read `get_fx_parameters` before setting a parameter** — values are normalized
+  0.0–1.0 and the mapping varies per plugin.
+- **Meters are instantaneous** — play audio a few seconds before reading.
+- **Keep bass mono below ~100 Hz** — check `read_track_correlation` on the bus
+  before any widening.
+- **If a change sounds or measures worse, revert** to the before-snapshot.
+- **A "flat" analyzer is not perceptually flat** — a balanced mix slopes gently
+  down from lows to highs.
+- **Perceived values only, never raw.** Every balance or EQ claim cites LU
+  (post-fader, against the mix bus, same section) or `kDb` (same band across
+  tracks or a reference). Never judge or report balance from peak/RMS dBFS,
+  raw band `db`, raw FFT bins or fader positions alone, and never compare one
+  band with a different band of the same spectrum.
+- **The user's ear is the finding.** When the user hears an imbalance, a
+  measurement that disagrees is suspect first: diff plugin parameters against
+  the before-snapshot, check for pre-fader readings, a bypassed meter or a
+  different section.
+- **Section level changes are pooled automation items, never item gain.** When a
+  track is too loud or quiet in one part of the song, put automation items on its
+  Volume envelope with one pool per section type (`Vox Chorus` on every chorus),
+  so one edit moves every repeat (`workflows/section-levels.md`). Item gain and
+  take volume change what the FX chain receives; loose envelope points drift
+  apart between repeats.
+- **Never prefix track names with their parent or role** ("A INST", "STEM DRUMS",
+  "LIVE OUT"). The folder already gives the context: a copy under `MIX A` is
+  `INST`, not `A INST`. Keep the user's names and duplicate names across folders;
+  target tracks by GUID or index instead of renaming them to make names unique.