Imported from kasselvania/Linux-VST-bridge (
AGENTS.md). Install upstream withnpx skills add kasselvania/Linux-VST-bridge. Copyright stays with the author.
Working on Linux VST Bridge
Goal
Build a usable Windows plug-in bridge for native Linux music applications as the primary release-driving product. Extend the same canonical management platform with separately scoped Windows DAW workspaces and the existing ARM appliance work. The user should not have to administer Wine prefixes, proxies, runtime versions or recovery machinery to make music. Steam Deck, Bitwig and AGain are fixtures, not the limits of the product.
Work to an outcome
Read this file and CURRENT_SLICE.md, then the architecture/code relevant to the requested change. Do not reread the entire historical corpus or repeat slice selection when the user has selected the goal.
An approved implementation task includes ordinary code changes, necessary builds, focused tests, debugging and verification within that task. The engineer chooses private types, file layout and algorithms. A routine repair does not need a new design, exact-source approval document, maintenance campaign or separate PR. Record what actually ran; do not confuse source identification with permission to iterate.
The operator's current instruction takes precedence over repository process documents. These rules replace the older mandatory selection/receipt/diagnostic/acceptance sequence. docs/campaigns/, docs/maintenance/, docs/process/ and previous slice instructions retain historical context, not standing requirements for new work. Platform/tool approvals and security restrictions are separate and remain in force; never route around a denial.
Shared failure-class check
Before a plug-in-specific repair, inspect docs/FAILURE_CLASSES.md and docs/SUPPORT_MATRIX.md alongside CURRENT_SLICE.md. Product-specific code needs evidence that the shared boundary was selected or ruled out.
Update the relevant card and matrix row in the same PR whenever understanding, fix stage, deployment, physical coverage, workaround, or support posture changes. Keep source correction, built artifact, profile/candidate, installed generation, and physical result distinct. Do not generalize a product result to another product or assign a shared cause to an older report without evidence.
Execution lanes and parallel work
Use docs/WORKSTREAMS.md for work allocation and docs/WINDOWS_DAW_WORKSPACES.md for the Windows DAW architecture extension. The native bridge remains primary; WD0 is the selected parallel FL Studio implementation. Do not wait for every native-bridge limitation to close before WD0, or delay native product completion behind FL/Ableton/ARM scope.
One canonical management implementation serves different execution lanes. A Windows DAW hosts Windows plug-ins directly in its own coherent workspace; do not insert the Linux proxy or inherit its DSP-count/added-delay claims. Reuse ownership and installer primitives without weakening closed vendor-app selectors into arbitrary execution.
Each branch owns its own task pointer and each lane its mutable workspace state. Coordinate shared-machine GUI/audio activity and service replacement with the current custodian. Do not consume unmerged code silently or replace a working installed generation merely because main is newer. Before any shared package replacement, reconcile every installed runner policy and required host/source pair. Workspace-only development must leave the existing native-bridge service and publications alone.
Keep the engineering safeguards
- Use the actual Windows plug-in, not substitute DSP or fabricated state. Respect SDK interfaces, object lifetime, thread affinity and explicit protocol boundaries. Keep Rust primary and C++ limited to the SDK edges.
- Keep blocking I/O, allocation, logging and process work out of real-time audio callbacks. Preserve truthful latency and explicit failure behavior.
- Protect existing projects, installations and credentials. Use disposable test projects/environments where practical. Restore settings changed for a test. Clean up only processes and files the task owns; investigate uncertain ownership before starting another instance.
- Retain useful failure details before cleanup. Private local diagnostics may contain the paths/process identifiers needed for debugging; do not publish them or credentials, license data, proprietary binaries or presets.
- Never fabricate a pass, silently change the tested fixture, erase failed attempts or relabel old evidence. A green build, a fake-peer test and an actual DAW test establish different things.
Verification and review
Test the behavior changed and the failures that matter. Reuse working binaries, fixtures, supervision and observations. Do not replay an entire historical matrix because a report, timeout or document changed. Preserve valid sub-results and rerun only affected parts unless a genuine end-to-end uncertainty requires more.
A meaningful successful development test on the delivered implementation may support review without being repeated under a different label. Keep its original provenance and limitations. Acceptance is the reviewer's decision about the code and evidence, not a requirement to reserve a special class of run in advance. Recorded results from the older system remain exactly as recorded.
Use normal build/test commands and the existing supervised helpers. tools/proof-run.py is an optional legacy transaction interface, not a mandatory gateway to every local test, Deck interaction, GUI action or merge. Do not weaken its historical checks, reset its ledgers or disguise a new launch as recovery. Existing explicit resource limits still apply until the operator changes them; there is no universal two-tries rule for new tasks.
Ask before changing the goal, making destructive changes to unrelated/user-owned data, installing paid software, exceeding an explicit spending limit or changing a security boundary. Ordinary compile errors, GUI pacing and in-scope harness repairs belong to the engineer. If a test repeatedly teaches nothing new, diagnose it rather than blindly rerunning it.
Publish one PR with what works, how it was checked, relevant versions, remaining limitations and cleanup. Review before merge; include the current-status update in the same PR. No separate audit/closure artifact is required by default. Write additional design only for a consequential unresolved decision, not to memorialize every implementation choice.
GUI test custody and delegated control
The implementation agent remains the test custodian. It owns the exact candidate and project, setup, permissions, target identities, allowed actions, stop conditions, evidence, cleanup, retry decision and final interpretation. A delegated GUI worker executes a bounded interaction plan; it does not choose the test, declare pass or failure, improvise a retry or change the system.
Where model-routed GUI control is available, use Luna as the default executor for routine exact-window work, normally at high reasoning and at max for owned popups or mildly ambiguous layouts. Escalate to Astra only after Luna stops on a genuinely novel or consequential visual ambiguity. Give either worker a closed action capsule containing the exact target, permitted actions, forbidden actions and immediate stop conditions. Do not replay an otherwise useful session merely to change executors.
Machine evidence from UIO, CA1 and bridge/process records outranks the worker's narration. The worker returns actions attempted, visible observations and the blocked step, not an engineering verdict. It stops on identity drift, an unexpected dialog, popup ambiguity, terminal failure, focus or capture ownership change, or any action outside the capsule. Only the test custodian may authorize another launch or attempt.
Concurrent work and access
Do not change another agent's branch, checkout or running experiment. Reconcile current instructions when integrating branches; preserve product code and original observations instead of restoring retired process requirements.
Reuse established Moonlight/Sunshine and SSH under their existing permissions. Launch Bitwig normally from Applications for desktop use. Respect Computer Use restrictions and do not substitute unapproved interaction methods. Remote access is development tooling, not a plug-in runtime dependency.
