MC Patcher
The Host/Bridge path consists of two products joined by a versioned realtime
protocol. Standalone utility plug-ins, including Pigora, have their own
processor/editor path and do not require a Bridge round trip for acceptance:
DAW -> MC Bridge VST3 -> shared-memory IPC -> MC Host graph
DAW <- MC Bridge VST3 <- shared-memory IPC <- processed wet return
Read the current README.md and relevant CMakeLists.txt sections before relying on commands in this skill. The repository evolves; source files and configured targets are authoritative.
Architecture boundaries
- Keep the Bridge limited to DAW bus negotiation, transport, discovery, state, and latency reporting. Keep graph editing, plug-in hosting, routing, and most UI in the standalone Host.
- Keep audio transport local and realtime-safe: shared memory plus lock-free SPSC structures. Use network or service discovery only outside the audio path.
- Preserve discrete multichannel behavior through the core. Do not silently clamp a general graph or protocol type to stereo.
- Keep allocation, locks, filesystem/network access, UI work, logging I/O,
shm_open, and graph reconstruction off processBlock and equivalent realtime callbacks.
- Rebuild or swap graph state on a control/message thread. Hand fixed-size messages or atomically published state to the audio thread.
- Identify hosted plug-ins by stable IDs plus names and format metadata. Do not make session restore depend only on a shell bundle path that can change across versions.
- Extend the protocol in
shared/ instead of creating a parallel transport path. Version ABI or behavior changes deliberately.
Open references/architecture.md only when the task needs product precedents, VST3/JUCE API anchors, or protocol design notes.
Work by evidence
Follow the repository AGENTS.md for failure reproduction, hypothesis limits,
writer/build ownership, staged validation, deployment, and completion wording.
This skill adds only the product-specific architecture and verification matrix.
For concurrent plug-in or capture work, classify conflicts by the complete
resource set rather than by repository name. The user's audio-router lanes are
independent by standing contract: record routes for evidence, but never use
audio channels, Bridge/IPC routes, or capture activity to block, interrupt, or
contact another task. Source dependency closure, build directory, generated
artifact, production deployment, a mutating DAW/Host control plane, and global
device-setting changes remain possible conflicts. Independent lanes continue
without interruption while only a proven colliding phase waits. Use
$orchestrator for dedicated build lanes and handoff when two or more
tasks are active. Treat build-juce as a protected integration/deployment tree:
direct configure, CMake target builds, and CTest runs there are expected to fail
without the repository build-lane wrapper. A guard failure is not a reason to
contact another task; move routine work to the caller's dedicated lane.
Validation matrix
Run only the rows touched by the change, plus at least one neighboring regression.
When a build tree may be stale, discover configured tests with ctest -N
through that task's build-lane wrapper, as shown in the verification reference.
Read references/verification.md before selecting
exact CMake/CTest targets, local plug-in probes, deployment steps, or a DAW
matrix.
For Pigora response or control integration, read
references/pigora-handoff.md. Response fitting
and evidence decisions remain owned by pigora-public-fit-training; do not
repeat its source search for an unchanged, hash-bound integration handoff.
| Change |
Minimum evidence |
| Core protocol or portable logic |
Configure/build the non-JUCE tree; run the relevant CTest case and then the portable suite when practical |
| SHM, ring, IPC, or Bridge realtime path |
Relevant ipc_smoke, shm_roundtrip, shm_multich, multi-instance, wet-return, or click tests; inspect the changed callback for allocation/locks/blocking calls |
| Host engine, graph, prepare, FIFO |
Build the Host and mc_host_engine_verify when its local plug-in prerequisites exist; exercise editor open/close during playback if that was the affected path |
| VST3 Bridge lifecycle or bus layout |
Build McBridge_VST3; run PluginVal at strictness 5 or higher when installed; test at least two relevant bus/block/sample-rate combinations when possible |
| Wet return, click, delay, or PDC |
A local regression plus a DAW-to-Bridge-to-Host-to-DAW wet-return check; record whether mount and steady state were both exercised |
| Plug-in scanning/loading or WaveShell |
Load the named real plug-in/shell, open and close its editor, and verify a previously working plug-in still loads |
| High channel count or throughput |
Inspect the current tests first. If no representative high-channel benchmark exists, add or run a bounded reproducible probe rather than presenting the lower-channel smoke test as 48/64/128-channel evidence |
| Host UI, Q-Link, or mixer |
Build the Host or Theme Lab; inspect the actual surface at target size; test selection, parameter propagation, editor lifecycle, and any prior deadlock path |
| Pigora model, parameter adapter, or editor integration |
Frozen fitting receipt plus the Pigora handoff matrix: effective controls, production audio/response agreement, point/full paths, restored hidden state, and applicable rack/host checks |
Local commercial/test plug-in probes are opt-in through MC_PATCHER_ENABLE_LOCAL_PLUGIN_TESTS. If prerequisites are absent, do not convert that absence into a product failure; report the integration layer as untested.
Deployment ownership
The current repository AGENTS.md is authoritative for mandatory Host
deployment, VST3 destinations, deployment targets, version bumps, and
restart/rescan reporting. Inspect it rather than relying on copied policy here.
Realtime review
When a diff touches an audio callback, verify all of the following:
- Buffers and containers are preallocated for the negotiated maximum.
- No mutex, file lock, condition wait, filesystem/network call, UI call, or log I/O is reachable.
- No implicit container growth, string formatting, shared ownership churn, or plug-in discovery occurs.
- Producer/consumer ownership is unambiguous; no double push/pop or unsafe lifetime handoff exists.
- Oversized blocks, sample-rate changes, channel reconfiguration, and peer teardown fail safely.
- Latency reporting covers the actual round trip and any hosted processing latency.
Report results
Use the completion standard in AGENTS.md. Add the exact plug-in identity,
channel/block/sample-rate combination, or hosted path when those details are
material to the result.
1---2name: mc-patcher3description: Develop, diagnose, build, review, and verify the mc-patcher C++/JUCE repository. Use only when the current repository is identifiable as mc-patcher or the user explicitly asks to work on or apply mc-patcher; do not trigger for generic JUCE, VST3, or audio-product research. Covers MC Host, MC Bridge, multichannel routing, shared-memory IPC, Q-Link, wet return, latency, VST3/WaveShell hosting, realtime safety, targeted validation, explicit deployment, and honest reporting of untested DAW paths.4---56# MC Patcher78The Host/Bridge path consists of two products joined by a versioned realtime9protocol. Standalone utility plug-ins, including Pigora, have their own10processor/editor path and do not require a Bridge round trip for acceptance:1112```text13DAW -> MC Bridge VST3 -> shared-memory IPC -> MC Host graph14DAW <- MC Bridge VST3 <- shared-memory IPC <- processed wet return15```1617Read the current `README.md` and relevant `CMakeLists.txt` sections before relying on commands in this skill. The repository evolves; source files and configured targets are authoritative.1819## Architecture boundaries20211. Keep the Bridge limited to DAW bus negotiation, transport, discovery, state, and latency reporting. Keep graph editing, plug-in hosting, routing, and most UI in the standalone Host.222. Keep audio transport local and realtime-safe: shared memory plus lock-free SPSC structures. Use network or service discovery only outside the audio path.233. Preserve discrete multichannel behavior through the core. Do not silently clamp a general graph or protocol type to stereo.244. Keep allocation, locks, filesystem/network access, UI work, logging I/O, `shm_open`, and graph reconstruction off `processBlock` and equivalent realtime callbacks.255. Rebuild or swap graph state on a control/message thread. Hand fixed-size messages or atomically published state to the audio thread.266. Identify hosted plug-ins by stable IDs plus names and format metadata. Do not make session restore depend only on a shell bundle path that can change across versions.277. Extend the protocol in `shared/` instead of creating a parallel transport path. Version ABI or behavior changes deliberately.2829Open [references/architecture.md](references/architecture.md) only when the task needs product precedents, VST3/JUCE API anchors, or protocol design notes.3031## Work by evidence3233Follow the repository `AGENTS.md` for failure reproduction, hypothesis limits,34writer/build ownership, staged validation, deployment, and completion wording.35This skill adds only the product-specific architecture and verification matrix.3637For concurrent plug-in or capture work, classify conflicts by the complete38resource set rather than by repository name. The user's audio-router lanes are39independent by standing contract: record routes for evidence, but never use40audio channels, Bridge/IPC routes, or capture activity to block, interrupt, or41contact another task. Source dependency closure, build directory, generated42artifact, production deployment, a mutating DAW/Host control plane, and global43device-setting changes remain possible conflicts. Independent lanes continue44without interruption while only a proven colliding phase waits. Use45`$orchestrator` for dedicated build lanes and handoff when two or more46tasks are active. Treat `build-juce` as a protected integration/deployment tree:47direct configure, CMake target builds, and CTest runs there are expected to fail48without the repository build-lane wrapper. A guard failure is not a reason to49contact another task; move routine work to the caller's dedicated lane.5051## Validation matrix5253Run only the rows touched by the change, plus at least one neighboring regression.54When a build tree may be stale, discover configured tests with `ctest -N`55through that task's build-lane wrapper, as shown in the verification reference.5657Read [references/verification.md](references/verification.md) before selecting58exact CMake/CTest targets, local plug-in probes, deployment steps, or a DAW59matrix.6061For Pigora response or control integration, read62[references/pigora-handoff.md](references/pigora-handoff.md). Response fitting63and evidence decisions remain owned by `pigora-public-fit-training`; do not64repeat its source search for an unchanged, hash-bound integration handoff.6566| Change | Minimum evidence |67|---|---|68| Core protocol or portable logic | Configure/build the non-JUCE tree; run the relevant CTest case and then the portable suite when practical |69| SHM, ring, IPC, or Bridge realtime path | Relevant `ipc_smoke`, `shm_roundtrip`, `shm_multich`, multi-instance, wet-return, or click tests; inspect the changed callback for allocation/locks/blocking calls |70| Host engine, graph, prepare, FIFO | Build the Host and `mc_host_engine_verify` when its local plug-in prerequisites exist; exercise editor open/close during playback if that was the affected path |71| VST3 Bridge lifecycle or bus layout | Build `McBridge_VST3`; run PluginVal at strictness 5 or higher when installed; test at least two relevant bus/block/sample-rate combinations when possible |72| Wet return, click, delay, or PDC | A local regression plus a DAW-to-Bridge-to-Host-to-DAW wet-return check; record whether mount and steady state were both exercised |73| Plug-in scanning/loading or WaveShell | Load the named real plug-in/shell, open and close its editor, and verify a previously working plug-in still loads |74| High channel count or throughput | Inspect the current tests first. If no representative high-channel benchmark exists, add or run a bounded reproducible probe rather than presenting the lower-channel smoke test as 48/64/128-channel evidence |75| Host UI, Q-Link, or mixer | Build the Host or Theme Lab; inspect the actual surface at target size; test selection, parameter propagation, editor lifecycle, and any prior deadlock path |76| Pigora model, parameter adapter, or editor integration | Frozen fitting receipt plus the Pigora handoff matrix: effective controls, production audio/response agreement, point/full paths, restored hidden state, and applicable rack/host checks |7778Local commercial/test plug-in probes are opt-in through `MC_PATCHER_ENABLE_LOCAL_PLUGIN_TESTS`. If prerequisites are absent, do not convert that absence into a product failure; report the integration layer as untested.7980## Deployment ownership8182The current repository `AGENTS.md` is authoritative for mandatory Host83deployment, VST3 destinations, deployment targets, version bumps, and84restart/rescan reporting. Inspect it rather than relying on copied policy here.8586## Realtime review8788When a diff touches an audio callback, verify all of the following:8990- Buffers and containers are preallocated for the negotiated maximum.91- No mutex, file lock, condition wait, filesystem/network call, UI call, or log I/O is reachable.92- No implicit container growth, string formatting, shared ownership churn, or plug-in discovery occurs.93- Producer/consumer ownership is unambiguous; no double push/pop or unsafe lifetime handoff exists.94- Oversized blocks, sample-rate changes, channel reconfiguration, and peer teardown fail safely.95- Latency reporting covers the actual round trip and any hosted processing latency.9697## Report results9899Use the completion standard in `AGENTS.md`. Add the exact plug-in identity,100channel/block/sample-rate combination, or hosted path when those details are101material to the result.
shawnxxxqazwsx