Imported from ethanjones1132-lab/CorvusFx (
docs/AGENTS.md). Install upstream withnpx skills add ethanjones1132-lab/CorvusFx --skill docs. Copyright stays with the author.
AGENTS.md — Corvus VST (DrippyFX) Agent Working Rules
This file gives autonomous AI agents the minimal project-specific context needed to work safely in this repo.
What This Repo Is
Corvus VST (brand name for DrippyFX) — a JUCE 8.0.12 VST3 audio plugin suite with 4 cascade effect modules + Master Output:
| Module | Type | Key Features |
|---|---|---|
| Distortion | Saturation | Tape→tube blend, pre-emphasis, 2-pole post filter, warmth shelf, DC blocker, 2x oversampling |
| Chorus | 6-voice modulation | Hermite interpolation, multi-shape LFO, mix-adaptive depth, per-voice allpass, decorrelated rates |
| Delay | Tape-style | Ping-pong, Hermite interp, tape wow/flutter, filtered feedback, soft saturation, exponential feedback mapping |
| Reverb | Freeverb-inspired | 8 comb filters + 4 allpasses, modulation (reverb_mod knob active), pre-delay, damping, Hermite interpolation |
| Master Output | Multi-stage | Push-pull asymmetrical saturation (2nd/4th harmonics), multi-band processor, DC blocker, peak limiter, 2x oversampling |
36 presets (6 per category: CLEAN, WARM, CREATIVE, EXTREME, SIGNATURE, DREAM) spanning Clean Sparkle → Warm Glow → Dreamy Space → Thick Sauce → Obliterator → Solar Flare.
Source of Truth
Authoritative JUCE C++ sources are tracked in this repo:
C:\Projects\Corvus VST\source\DrippyFX\
| File | Purpose |
|---|---|
PluginProcessor.h |
DSP engine — ProfessionalDistortion, EnhancedChorus, EnhancedDelay, UpgradedReverb, MasterOutputStage |
PluginProcessor.cpp |
Audio processor — parameter layout, processBlock, preset system, state save/load |
PluginEditor.h |
UI — AnimatedKnob, CorvusLookAndFeel, AnimatedBackground, section headers |
PluginEditor.cpp |
Editor layout — all knob setup, attachments, 2x2 grid layout |
CMakeLists.txt |
CMake build config (VST3 + AU + Standalone) |
See source/DrippyFX/README.md for CMake build steps.
Local MSBuild / Projucer tree (sync target, not git SoT):
C:\Users\ethan\Downloads\DrippyFX_v1.0.0_Complete\DrippyFX\ — copy from source/DrippyFX/ before MSBuild when using the Downloads VS solution.
Repo binaries & artifacts: C:\Projects\Corvus VST
drippy/NewProject.vst3/Contents/x86_64-win/DrippyMk1.vst3— deployed VST3 binaryDrippyMk2/NewProject.vst3/Contents/x86_64-win/DrippyMk2.vst3— secondary deployed binary.obj,.pdb,.exp,.lib,.iobjunderdrippy//DrippyMk2/— VS build artifacts (DO NOT DELETE)
Absolute Rules for Agents
1. Edit in-repo source first; every quality commit must include source + binary
# Correct (git-tracked SoT):
C:\Projects\Corvus VST\source\DrippyFX\PluginProcessor.cpp
# MSBuild: sync the same files into Downloads DrippyFX/ before building, then deploy .vst3Commit rule: quality(scope): ... commits that change DrippyMk1.vst3 (or DrippyMk2.vst3) must include the matching .cpp/.h diffs under source/DrippyFX/. Binary-only quality commits are not allowed going forward.
2. One improvement per run — pick the highest-impact item and complete it
Don't scatter-gun fixes. Follow the priority order in PRIORITIES.md.
3. Follow conventional commit format
quality(scope): description
What changed, why, measured impact where possible.
4. Verify every rebuild — 3-step protocol (MANDATORY)
After ANY binary rebuild:
git diff --stat -- "drippy/.../DrippyMk1.vst3"— byte count changemd5sumof build output vs deployed copy — confirms copy succeededgit show HEAD:<path> | md5sumvsmd5sum <path>— confirms binary differs from HEAD
If binary unchanged (same MD5 as HEAD) → force rebuild:
MSBuild ... -t:Rebuild5. Always quote paths — space in "Corvus VST" breaks unquoted commands
# Correct:
"C:/Projects/Corvus VST/drippy/..."
"C:/Users/ethan/Downloads/DrippyFX_v1.0.0_Complete/DrippyFX/..."
# Wrong (fails silently):
C:/Projects/Corvus VST/drippy/...6. Preserve binary naming — DrippyMk1.vst3 / DrippyMk2.vst3
DAWs may reference these paths.
7. Do NOT delete VS build artifacts — .obj, .pdb, .exp, .lib, .iobj are expected in repo
Build & Deploy Pipeline
Preferred: MSBuild (fast, incremental, no juceaide timeout)
"C:/Program Files/Microsoft Visual Studio/18/Community/MSBuild/Current/Bin/amd64/MSBuild.exe" ^
"C:/Users/ethan/Downloads/DrippyFX_v1.0.0_Complete/NewProject/Builds/VisualStudio2026/NewProject_VST3.vcxproj" ^
-p:Configuration=Release -p:Platform=x64 -mOutput binary:
C:/Users/ethan/Downloads/DrippyFX_v1.0.0_Complete/NewProject/Builds/VisualStudio2026/x64/Release/VST3/NewProject.vst3/Contents/x86_64-win/NewProject.vst3
Deploy:
cp "C:/Users/ethan/Downloads/DrippyFX_v1.0.0_Complete/NewProject/Builds/VisualStudio2026/x64/Release/VST3/NewProject.vst3/Contents/x86_64-win/NewProject.vst3" ^
"C:/Projects/Corvus VST/drippy/NewProject.vst3/Contents/x86_64-win/DrippyMk1.vst3"Alternative: CMake (slower — juceaide bootstrap 2-5 min)
export JUCE_PATH="C:/Users/ethan/Downloads/juce-8.0.12-windows/JUCE"
cd "C:/Users/ethan/Downloads/DrippyFX_v1.0.0_Complete/DrippyFX"
"C:/Program Files/Microsoft Visual Studio/18/Community/Common7/IDE/CommonExtensions/Microsoft/CMake/CMake/bin/cmake.exe" ^
-G "Visual Studio 18 2026" -A x64 -DJUCE_PATH="$JUCE_PATH" -S . -B build
"C:/Program Files/Microsoft Visual Studio/18/Community/Common7/IDE/CommonExtensions/Microsoft/CMake/CMake/bin/cmake.exe" ^
--build build --config ReleaseQuality Improvement Workflow (Per Cron Run)
1. Source Analysis
Review C:\Projects\Corvus VST\source\DrippyFX\ for:
- DSP quality: Algorithm improvements (saturation curves, filter topologies, delay interpolation)
- Unused parameters:
/*unused*/, commented-out params, received-but-never-referenced — these are dead UI controls - Parameter mapping: Knob ranges musically useful? Log/exp scaling needed?
- Host interop:
getNumPrograms(),setCurrentProgram(),getProgramName(),getCurrentProgram()— all agree on count/index? - Performance: Hot loops (per-sample) → SIMD, pre-computation, block processing? See
references/dsp-optimization-patterns.md - Cleanup: Debug
DBG()calls, unused code paths, stale comments - Presets: 18 presets need refinement or additions?
- Naming: "NewProject" boilerplate → "CorvusFX"?
- UI polish: Layout, responsiveness, visual improvements
2. Prioritize & Implement
Pick single highest-impact improvement:
- DSP quality (smoother filters, better modulation, anti-aliasing, oversampling)
- Parameter improvements (ranges, smoothing, tooltips)
- Performance (SIMD, pre-compute, block processing)
- Code quality (rename artifacts, dead code, structure)
- Preset refinement (values, new presets)
- UI/UX improvements
3. Rebuild → Verify → Commit
Completed Improvements (Progress Log)
| Date | Commit | Module | Improvement |
|---|---|---|---|
| 2026-07-15 | c4401c2 |
Presets | Expand factory presets from 30 to 36 with DREAM category — added 6 ambient/ethereal presets (Cloud Chamber, Frozen Lake, Ash & Ember, Stargate Portal, Underwater Cathedral, Solar Flare). Updated getNumPrograms() 30→36, idToPreset 36→43, presetToId 30→36. Editor: DREAM category + 6 items. Tooltip: 36 curated sounds. Binary MD5: b05ef287 → 649e6a10 (+13 KB). |
| 2026-06-24 | b0e960a |
Presets | Fix setCurrentProgram bounds for all 18 presets |
| 2026-06-24 | cf33942 |
Reverb | Activate comb filter modulation (reverb_mod knob now works) |
| 2026-06-24 | bc8e816 |
Delay | Exponential feedback mapping for musical response |
| 2026-06-24 | 4db06cc |
Distortion | Block-level coefficient cache (4 exp/sample → 1/block) |
| 2026-06-25 | 6bf1278 |
Master + Chorus | Block-level coefficient cache (5 exp/sample → 1/block) |
| 2026-06-25 | 61c197f |
EnhancedDelay | Block-level coefficient cache for feedback LP/HP (2 exp/sample → 1/block) |
| 2026-06-25 | 60f3dc1 |
UpgradedReverb | Block-level cache: hoisted 8× setFeedback/setDamp + mod calc |
| 2026-06-26 | b3b4f21 |
processBlock | Merge master output + safety limiter into main loop (4→2 buffer passes) |
| 2026-06-26 | f7ed642 |
MasterOutputStage | Push-pull asymmetrical saturation: even-harmonic warmth, drive=1.8x |
| 2026-06-26 | 7c37e20 |
UpgradedReverb | Hermite cubic interpolation for modulated reads |
| 2026-06-27 | a66f658 |
Distortion + Master | 2x oversampling for zero aliasing (Oversampling2x, 2nd-order half-band FIR, 8 taps) |
| 2026-06-28 | 83b59a0 |
EnhancedDelay | 2x oversampling for tape saturation in feedback loop — eliminates aliasing in delay tail |
| 2026-06-29 | b99b59c |
processBlock | Parameter smoothing (LinearSmoothedValue) on all 13 audio parameters — 20ms smoothing eliminates zipper noise from knob movement and host automation. Previously, raw atomic reads jumped instantly between blocks. |
| 2026-06-29 | 1c3652e |
UpgradedReverb | Allpass feedback scales with room size (0.50→0.70) — Size knob now varies diffusion character. Also hoisted comb setFeedback/setDamp loop from per-sample to per-block in beginBlock(). |
| 2026-06-30 | 3936329 |
processBlock | ScopedNoDenormals fix — moved from outer function scope into per-sample loop, fixing redundant reconstruction on every iteration. Single RAII object per block eliminates per-sample stack object creation/destruction overhead. |
| 2026-07-01 | 37bc0c2 |
EnhancedChorus | |
| 2026-07-03 | 0e65aa6 |
Jucer/Build | |
| 2026-07-06 | e379f2d |
||
| 2026-07-10 | 5dd1e7c |
Modules | |
| 2026-07-10 | 56758bf |
MasterOutputStage | |
| 2026-07-10 | 3645f81 |
UI/Presets/DSP |
Remaining Optimization Opportunities
- All modules: Profile-guided optimization (PGO) build
- Distortion: Antiderivative antialiasing as alternative to oversampling
- Reverb: Convolution reverb IR option for "real space" mode
Quality Targets
| Area | Goal | Success Signal |
|---|---|---|
| DSP accuracy | Studio-grade, competitive | Cleaner spectrum, less aliasing, musical parameter response |
| Performance | <5% CPU at 48kHz/64 samples | No audio dropouts, efficient SIMD where needed |
| Parameter feel | Musical across full range | Smooth transitions, no zipper noise, useful extremes |
| UI polish | Professional-grade visual | Consistent with top-tier plugins, responsive resizing |
| Code quality | Production C++17 | No "NewProject" boilerplate, const-correct, clean includes |
Known Pitfalls
- MSBuild incremental misses header changes — after modifying
.hfiles, incremental build may succeed in <1s with identical binary. Always run 3-step verification. - CMake generator must be "Visual Studio 18 2026" — machine has VS2026 (v18), NOT VS2022 (v17). Wrong generator → MSB8020.
- CMake juceaide timeout — first configure builds juceaide from scratch (2-5+ min). 120s terminal timeout insufficient. Prefer MSBuild.
- MSBuild property syntax in git-bash/MSYS — use
-p:Configuration=ReleaseNOT/p:(MSYS converts/p:to filesystem path). - JUCE_PATH must be set — required by CMakeLists.txt and build scripts.
- Space in "Corvus VST" — always quote paths.
- Plugin code name mismatch —
.jucersays "NewProject" but processor class isCorvusFXAudioProcessor, DSP files inDrippyFX/. Fix by updating.jucerand regenerating.
Environment
- JUCE SDK:
C:\Users\ethan\Downloads\juce-8.0.12-windows\JUCE - VS 2026 (v18):
C:/Program Files/Microsoft Visual Studio/18/Community/ - Jucer project:
C:\Users\ethan\Downloads\DrippyFX_v1.0.0_Complete\NewProject\NewProject.jucer - VS Solution:
...NewProject\Builds\VisualStudio2026\NewProject.sln - CMake:
C:/Program Files/Microsoft Visual Studio/18/Community/Common7/IDE/CommonExtensions/Microsoft/CMake/CMake/bin/cmake.exe - Repo workdir:
C:\Projects\Corvus VST(sources undersource/DrippyFX/, binaries underdrippy//DrippyMk2/) - Branch: master
- Cron:
corvus-cronskill (3×/day 9:45am/1:45pm/5:45pm + overnight 6:30am) - Model:
opencode-go/xiaomi/mimo-v2.5-pro - Toolsets: terminal, file, coding
Support Files (in corvus-cron skill)
references/dsp-optimization-patterns.md— Block-level coefficient pre-computation patternreferences/oversampling-pattern.md— 2x oversampling implementation detailsreferences/verification-pattern.md— Ad-hoc verification script template & checklist