oscine: Instructions file for Codex

AGENTS.md

Guidance for AI agents and humans working in the Oscine codebase. Oscine is itself agent-controllable at runtime (MCP + OSC); this file is about editing its source. Read README.md for what the app is, docs/north-star.md for what it's for, ROADMAP.md for what's next, and CHANGELOG.md for what shipped when.

The one rule that matters

The command catalog is the contract. Features land as catalog commands first, UI second.

src/api/commands.js is the single source of truth for every programmatic capability. The MCP tools and the OSC address space are derived from it, and the UI calls the same store actions the catalog handlers do. If you add a feature to the UI without a corresponding command, you have broken the project's core promise (UI/console/MCP/OSC parity). Add the command, then wire the UI to it.

To add a command: define it in src/api/commands.js (name, description, JSON Schema), implement cmd_<name> in src/api/api.js. It then surfaces automatically as an oscine_<name> MCP tool and, if you add a route, in plugin/server/osc-gateway.js. The smoke tests fail if a catalog command has no handler.

The arrangement side is in the catalog as of 2.2: arrangement, clip, lane, marker, cycle, range, insert, automation and words, with the edits themselves in src/core/arrangement.js behind store actions. The remaining debt is the other direction: the timeline, mixer and inspectors still mutate the project directly instead of calling those store actions. New arrangement UI must go through a store action; rewiring the existing UI is on ROADMAP.md.

Architecture invariants

Data flow is one-directional and event-driven. Do not shortcut it.

UI gesture / console / MCP / OSC
        -> store action (the ONLY place project state mutates)
        -> bus event
        -> engine mirrors audio, UI re-renders

Layer boundaries, enforced by discipline (and partly by tests):

• src/core/ has no DOM and no audio. It must stay importable from node (the tests import it). Bus, store, schema, persistence, utils.
• src/engine/ is audio only and never mutates the project. It reacts to bus events and mirrors state into Web Audio nodes.
• src/ui/ is DOM only and never touches audio nodes directly; it calls store actions and reads state.
• src/api/ is the programmatic surface (catalog + handlers + bridge).