This file is for coding agents (and the people driving them). Humans start with README.md › Development, PROGRESS.md and docs/architecture.md; everything below points back at those.
Device is a cross-platform DAW: a Rust app (crates/dstudio-app, Slint + wgpu) over a Rust
application core (crates/dstudio-core: model, commands, undo, persistence, snapshots) that drives a
C++23 real-time engine (engine/) through a hand-written C ABI (engine/include/dstudio_engine.h,
wrapped by crates/dstudio-engine).
specs/principles.md lists them with their sources. The short version:
- The audio thread never allocates, locks, blocks, does I/O, logs or calls Rust.
- Every edit to a project is a
dstudio_core::Command: validated, invertible, serialisable. - Old projects keep loading. Built-in device parameters are append-only.
- Original work only: no code, art, presets or text copied from other products.
- Internal names use
dstudio, never baredevice(it already names effects and instruments). - The engine builds with warnings as errors on clang, MSVC and GCC.
A feature, a behaviour change, anything that crosses layers (core, engine, app), performance work
or a hard bug starts with a spec, not with code. Specs live in specs/<NNN>-<slug>/ and ship in the
same pull request as the change. The workflow, and when to skip it, is in
specs/README.md. The phases have skills:
spec-write:spec.md, what and why, with acceptance checks. Stop for agreement.spec-plan:plan.mdandtasks.md, how, layer by layer. Stop for agreement.spec-build: work throughtasks.mdin order, ticking tasks off.spec-verify: check every requirement and acceptance check against the code, collect the PR evidence, mark the spec Done.
Bugs go through bug-fix (reproduce, failing test, fix, verify). Typos, doc edits and small,
obvious fixes skip the spec and go straight to the change.
The skills in .agents/skills/ encode how this codebase is changed. Prefer them to improvising.
| Skill | Use it when |
|---|---|
dstudio-command |
adding or changing an edit: a Command, its undo, coalescing, persistence, snapshot |
dstudio-engine-abi |
anything crossing the C ABI, or touching the audio thread |
dstudio-builtin-device |
adding or reworking a built-in effect or instrument |
dstudio-ui |
Slint panels, wgpu surfaces, review states, screenshots, the app self-test |
dstudio-bench |
measuring performance before and after a change |
dstudio-pr |
opening a pull request: evidence, docs, CI, review findings |
Skills are plain Markdown with a short front matter (name, description). After editing one,
run python3 tools/agents/check_skills.py: it checks the front matter and that every repository
path a skill names still exists, so skills don't silently rot as the code moves.
cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cd engine && cmake --preset default && cmake --build --preset default && ctest --preset default
cargo run --release -p dstudio-app -- --self-test --no-audioThen follow dstudio-pr. Keep README.md and docs/ accurate in the same pull request
(README › Development › Keeping this README up to date).