Cubase-MCP-GAJ3T.MusicGen.R.../prompts/plan.md

47 KiB

Riff-Groove-Builder: Architecture and Phased Implementation Plan

Status: Approved. Executable fixes 7/8 implement real Riffer .griff/.briff and SD3 .sd3p codecs, original fixtures and independent saved validators. Step 9 fix wires them into actual MCP/installed-wheel generation, target defaults, operator-local template configuration and atomic multi-artifact publication. See CURRENT report_7_fix.md, report_8_fix.md, report_9_fix.md. Final native/MIDI/CC software, exact persisted wheel and read-only operator template acceptance are recorded CURRENT-first in report_10.md; the earlier MIDI-only report is preserved there as retracted historical scope. The original full native/application definition of done is NOT complete: plugin/SD3 open/play/save/reload, audible checks and Cubase import remain UNRUN. Native codec/service implementation is no longer absent-evidence BLOCKED. Earlier step descriptions below retain historical sequencing, not current readiness.

Continuation decision: functional MIDI fallback

Retraction of interim closure and native-format continuation

At the earlier MIDI-only Step 10 checkpoint, independent fallback software was verified, including installed-wheel stdio generation, 1,119 passing tests, lint, formatting, strict types, dependency checks, and wheel/sdist builds. The final targeted native investigation is recorded in report_7_fix.md; it did not establish an AGP layout or obtain a usable native fixture.

The earlier interim closure was an orchestration error, not user approval to reduce scope. The original native-output requirement remains active. The user explicitly required continued implementation; native capability checks are not accepted as native writers.

Read-only inspection of the standard local vendor folders subsequently found genuine installed evidence that should have been checked earlier:

  • Ample Metal Eclipse VST3 version 4.0.1; native Riffer guitar .griff files.
  • Ample Metal Ray5 VST3 version 4.1.0; native Riffer bass .briff files.
  • Both Riffer containers are XML with Riff root, layout Ver="2.1" and PPQBase="480", including actual note, articulation and CC fields.
  • Superior Drummer executable version 3.4.4 and genuine text .sd3p projects with PlugVersion 3.4.4, SongTrack, MidiLoop and packed MidiEvents.

The requested .agp/.sdp suffixes do not match these observed installed native examples. A focused format-choice question received an unavailable-user response delegating a pragmatic choice. The compatibility-preserving implementation decision is to generate the actual .griff/.briff/.sd3p native files and retain agp/sdp as request aliases, explicitly documenting this correction. This preserves all three native targets; it is not another MIDI-only deferral and does not authorize mislabeled file bytes. No .strumseq exporter is added.

Local native files remain read-only evidence. No factory musical sequence, licensed manual, plugin binary or private template is copied into source/tests or uploaded. Tests generate original minimal content. SD3 instrument setup may use an operator-local template with its song replaced, never a shipped private project. Native codecs, target maps, service wiring and final validation must now be implemented and reviewed before full completion is claimed.

Current native integration outcome (Step 9 fix, 2026-10-20)

The native implementation continuation above is executed in software: all three target subsets are the unambiguous part defaults; standard maps remain explicitly selectable fallbacks, never relabeled vendor maps. Default requests produce combined MIDI and actual selected native suffixes. agp/sdp remain aliases only. Native-only requests do not force MIDI unless known fallback is required. Optional operator --sd3-template is not a tool-controlled path; bad supplied templates are errors, absent optional template permits drum-only fallback while preserving Riffer outputs. Source identity/content is preserved. Palm mute is reachable for lead/bass, with native PM/PMP and MIDI switch/velocity semantics; mixed-request drums stay normal with disclosed applicability. Owned exclusive-create file identities and saved-content hashes cover the complete multi-file stage before one Windows no-replace directory rename. Partial writes, validation/model/IO/publication faults never become successful fallback. Actual stdio and installed-wheel native generation and read-only genuine local template acceptance use original generated music; private state stays ignored/local. Report 9 fix records exact checks and remaining application-only limits. No later prompt, application hosting or commit is part of this fix.

Historical fallback execution clarification (superseded by native fixes above)

The plan was approved and Steps 1-4 accepted. Step 5 mechanics passed, while real-target mappings and native layouts remained unverified. On the user's autonomous-continuation instruction, the following execution clarification supersedes earlier clauses that made every subsequent development step depend on all vendor maps:

  • Standard MIDI fallback is already in scope. Ship explicitly labeled standard pitched-note/General MIDI percussion fallback profiles, distinguished from vendor mappings in public profile metadata and generation warnings.
  • Standard fallback data must be sourced from MIDI facts and documented server policy, not relabeled synthetic fixtures or claims of plugin compatibility. Unsupported vendor techniques remain explicit errors; never simulate a keyswitch by guessing a vendor note.
  • Step 5 fix can accept standard-fallback production mechanics while retaining a separately tracked real-target mapping gate. This permits Step 6 text/MIDI composition and the Step 9 fallback/service path to become operational.
  • Implement native capability checks and explicit unavailability when layouts cannot be established. Missing native evidence is not a completed native writer, and MIDI fallback is never reported as native generation.
  • Steps 7/8 real serialization and Step 10 application acceptance remain gated. Their blockers must persist in reports and compatibility documentation; they must not prevent independent fallback functionality from being completed.
  • Worker prompts and report reviews still occur one at a time, with fix prompts for defects. Any skipped/deferred native acceptance is disclosed, not passed.

Raw official Ample manual-page HTML, unlike the initial simplified extraction, exposes the public Eclipse/Ray5 main-panel manuals and Riffer/Strummer manuals. The initial "no usable mapping documentation" finding was incomplete. Their technical facts may be used with precise source/limitations; no licensed manual or factory song content is copied into the repository. Access to the manuals alone does not verify native layouts or the user's installed configuration.

1. Purpose and scope

Build a Python MCP server that converts text descriptions into coordinated lead, bass, and drum parts, then generates:

  • .agp content for the user's Ample Guitars Eclips lead instrument.
  • .agp content for the user's Ample Ray bass instrument.
  • .sdp content for Superior Drummer 3.
  • Standard MIDI .mid files, both directly requested and as an explicit fallback.

Use the user's instrument names until exact product names, versions, and import workflows are verified. Native files are instrument-specific content loaded into the relevant plugins in Cubase; they are not Cubase .cpr project files. Compatibility must be demonstrated, not inferred from an extension.

The server uses JSON-RPC over stdio only. No HTTP server, GUI, audio analysis, audio rendering, plugin hosting, DAW automation, external language-model service, database, or unrelated musical/export formats are included.

This document is a design, not a claim that any implementation or compatibility test already exists.

2. Repository findings and evidence gates

Initial inspection found an empty Git worktree with docs, prompts, and src directories, no tracked files, and no existing Python manifest or tests.

Verified from public documentation:

  • MCP stdio messages are UTF-8 JSON-RPC messages delimited by newlines. stdout must contain only protocol messages; diagnostics belong on stderr.
  • MCP requires initialization and capability/protocol negotiation.
  • Mido can write and read Standard MIDI Files, including synchronous type 1 files, with integer delta times in ticks.
  • MIDIUtil can independently construct multi-track MIDI files.

Not verified:

  • What .agp represents in each exact Ample product/version, whether it contains the required riff/groove data, and whether guitar and bass share a layout.
  • What .sdp represents in the user's Superior Drummer 3 workflow and whether it can contain generated song-track MIDI rather than only preset settings.
  • Native file layouts, supported versions, templates, checksums, or serialization.
  • Exact playable ranges, keyswitch numbers, CC semantics, velocity layers, and drum maps for the user's instrument versions and presets.

The Ample manual URL fetched during planning did not yield usable format documentation. The Toontrack manual page required login. Neither is evidence that the requested native formats can be generated by writing MIDI with a new extension.

Native-format and profile evidence gate

Before implementing a native writer, obtain lawfully usable vendor documentation or user-provided minimal files produced by the installed application:

  1. Exact product/version and the application's export/import operation.
  2. Empty, one-note/hit, and multi-note/hit examples.
  3. Controlled examples changing tempo, timing, velocity, and articulation.
  4. A documented native load/save round trip in the target plugin.
  5. Permission to store and redistribute fixtures, or a documented local-only fixture procedure when redistribution is not permitted.

Record source, version, observed structure, and unresolved fields. Do not upload user files, credentials, licensed content, or repository code to third parties. Do not bypass vendor authentication or copy licensed manuals into the repository.

Use a documented serializer when possible. A template-based serializer is acceptable only after its fields, lengths/checksums, version constraints, and content ownership are understood and round-trip tests prove the output works. Do not patch arbitrary offsets or silently preserve unexplained musical data.

If evidence shows the requested extension cannot carry the required content, report the contradiction and request a decision. Do not substitute another proprietary format or expand scope without approval.

Native evidence and MIDI mapping evidence are separate gates: a usable MIDI articulation map does not establish a native file layout. MIDI-only development can continue without native layouts, but plugin-specific MIDI compatibility and articulation claims still require verified instrument mappings.

3. Technology and dependency decisions

  • Python with a proposed minimum of 3.11; verify compatibility with the selected dependencies during Step 1 before committing the supported-version policy.
  • Official Python MCP SDK for stdio transport, lifecycle, protocol validation, tool registration, and JSON-RPC behavior. Do not write a competing transport.
  • Pydantic models and JSON Schema for tool inputs, outputs, musical structures, and profile validation, aligned with the selected SDK.
  • mido as the single production MIDI event writer and read-back validator. It provides explicit control over ticks and event ordering.
  • MIDIUtil / python-midiutil as an independent test-fixture generator for cross-library MIDI interoperability checks, not a second production writer.
  • pytest, the MCP SDK's supported asynchronous test approach, Ruff, and one type checker, configured in pyproject.toml. Avoid redundant test/lint tools.
  • Standard-library JSON, fractions.Fraction, pathlib, temporary directories, and deterministic random.Random instances where useful.

Select and record compatible dependency versions in Step 1. Do not install dependencies merely to produce this plan. No MIDI device, audio backend, Cubase installation, or proprietary SDK is required for ordinary unit tests.

4. Proposed directory structure

Only this plan is created in the architecture phase. The remaining files are created by their owning worker steps.

.
|-- pyproject.toml
|-- README.md
|-- .gitignore
|-- src/
|   `-- riff_groove_builder/
|       |-- __init__.py
|       |-- __main__.py
|       |-- server.py
|       |-- schemas.py
|       |-- errors.py
|       |-- description.py
|       |-- compose.py
|       |-- profiles.py
|       |-- articulations.py
|       |-- midi.py
|       |-- service.py
|       |-- formats/
|       |   |-- __init__.py
|       |   |-- agp.py
|       |   `-- sdp.py
|       `-- data/
|           `-- profiles/
|               |-- eclips.<verified-version>.json
|               |-- ray.<verified-version>.json
|               `-- sd3.<verified-map-version>.json
|-- tests/
|   |-- unit/
|   |-- integration/
|   `-- fixtures/
|       |-- descriptions/
|       |-- profiles/
|       |-- midi/
|       `-- native/
|-- docs/
|   |-- architecture.md
|   |-- compatibility.md
|   |-- articulation-profiles.md
|   `-- formats/
|       |-- agp.md
|       `-- sdp.md
`-- prompts/
    |-- plan.md
    |-- step_N.md
    |-- report_N.md
    |-- step_N_fix.md
    `-- report_N_fix.md

Angle-bracket version placeholders above are naming examples, not literal file names or verified version identifiers. Production profile files are created only when their data is supported by evidence. Synthetic test profiles remain under test fixtures and are never advertised as real instrument mappings.

5. Core modules and data flow

MCP client
  -> server: SDK lifecycle, tools/list, tools/call
  -> schemas: strict input validation
  -> description: text -> normalized musical intent
  -> compose: intent -> coordinated logical score
  -> profiles + articulations: score -> instrument-specific event plan
  -> service: output capability checks and requested-format policy
  -> midi / formats.agp / formats.sdp: render into staging directory
  -> independent read-back/structural validation
  -> service: publish the complete artifact directory
  -> server: typed structured result and concise text summary
Module Responsibility
__main__.py Start the stdio server; accept a required local output-root setting; send startup failures to stderr and exit nonzero.
server.py Register exactly the tools below, expose schemas, translate known domain failures to MCP tool errors, and keep stdout protocol-clean.
schemas.py Define strict request/result models, normalized intent, logical score, scheduled MIDI events, profile capabilities, and artifact metadata.
errors.py Define specific validation, unsupported-description, mapping, native-capability, serialization, and filesystem errors.
description.py Resolve supported natural-language terms and explicit overrides; report contradictions, missing capabilities, and meaningful unsupported instructions.
compose.py Generate deterministic lead/bass/drum patterns on one shared musical timeline, within verified ranges.
profiles.py Load packaged, versioned profile data; validate MIDI ranges, layers, provenance, and native capabilities.
articulations.py Compile logical techniques into note, keyswitch, velocity, and CC events with appropriate state/reset behavior.
midi.py Convert scheduled absolute events to stable type 1 SMF tracks and validate the saved files with Mido.
formats/agp.py Write and validate verified Ample native layouts, with separate target/version handling where required.
formats/sdp.py Write and validate the verified Superior Drummer 3 native layout.
service.py Coordinate the pipeline, enforce fallback policy, stage files, prevent output collisions, publish artifacts, and return actual results.

Keep these as small concrete modules; introduce no generic plugin framework, queue, database, persistent job system, or arbitrary exporter-discovery layer. The three fixed output formats need only a small internal capability dispatch.

6. Internal musical representation

Separate musical intent from MIDI mechanics and native serialization.

  • MusicalIntent: resolved description, selected parts, tempo, meter, key/mode, bar count, supported rhythm/technique terms, and deterministic seed.
  • Score: one shared tempo, meter, musical start, and end; ordered lead, bass, and/or drum tracks.
  • LogicalNote: part, pitch or drum voice, rational start/duration in quarter-note beats, intensity, and normalized articulation name.
  • EventPlan: absolute integer ticks, MIDI channel, event type, payload, event role such as musical note or keyswitch, and stable ordering information.
  • InstrumentProfile: exact instrument/map version, playable range, channel, drum voice map if applicable, articulation definitions, evidence metadata, and independently verified MIDI/native capabilities.

Use exact rational beat arithmetic until quantization. Proposed resolution is 960 ticks per quarter note. A bar lasts numerator * 4 / denominator quarter notes, not always four beats. Reject unsupported subdivisions rather than accumulating floating-point drift.

Do not model keyswitches as ordinary generated musical pitches. Preserve the logical score as well as the compiled event plan so a native adapter can use whichever representation its verified format actually requires.

7. MCP contract

Use the SDK's supported protocol negotiation; the 2025-11-25 specification is the planning reference, not a license to hard-code an unsupported SDK version. Advertise tools only, plus mandatory SDK protocol behavior. No sampling, resources, prompts, HTTP, or remote requests are needed.

Both tools publish input and output JSON Schemas. Reject unknown input fields, booleans masquerading as numeric values, non-finite numbers, duplicate list items, and invalid cross-field combinations. Tool handlers call the same service functions exercised by integration tests.

Tool 1: list_instrument_profiles

Purpose: discover real instrument mappings, supported techniques, and format availability before generation.

Parameters: an empty object; no additional properties.

Return type:

ProfileListResult {
  profiles: ProfileSummary[]
}

ProfileSummary {
  id: string,
  part: "lead" | "bass" | "drums",
  instrument: "eclips" | "ray" | "sd3",
  product_name: string,
  product_version: string,
  mapping_version: string,
  midi_available: boolean,
  native_format: "agp" | "sdp",
  native_available: boolean,
  supported_articulations: string[],
  limitations: string[]
}

An empty registry is returned honestly as an empty list. Unavailable capabilities may be listed with explicit limitations; synthetic fixtures are excluded. No absolute private fixture paths or licensed manual contents are exposed.

Tool 2: generate_music

Purpose: create coordinated musical content from a description and export the requested native files and/or MIDI.

Parameter Type Required/default Meaning
description string, 1-4000 nonblank characters Required Natural-language musical request within the documented supported vocabulary.
basename string matching [A-Za-z0-9][A-Za-z0-9_-]{0,63} Required Safe artifact-directory/file stem; Windows reserved names are also rejected.
parts unique nonempty array of lead, bass, drums Optional If absent, infer explicit part-selection language; otherwise default to all three and report that assumption.
formats unique nonempty array of mid, agp, sdp Optional If absent, request MIDI and the native format relevant to each selected part.
tempo_bpm finite number, 20-300 Optional Explicit tempo override.
bars integer, 1-256 Optional Explicit length override.
time_signature object `{numerator: integer 1-16, denominator: 1 2 4
key string from documented pitch-class plus major/minor grammar Optional Explicit tonality override.
profiles object with optional lead, bass, drums profile-ID strings Optional Select verified versions; entries must refer to selected parts.
seed integer, 0-2147483647 Default 0 Local deterministic variation; never use global random state.
allow_midi_fallback boolean Default true Permit explicitly reported MIDI substitution for unavailable requested native capabilities.

The limits are proposed bounded-generation defaults, subject to plan review. Also enforce a documented generated-event budget, initially 100,000 events, before serialization. These are resource safeguards, not extra musical features.

Rules:

  • Explicit structured overrides win over text and are disclosed in the result. Contradictory text without an override is an error with actionable details.
  • Unspecified musical defaults are 120 BPM, four bars, 4/4, and E minor; return the assumptions. Do not invent unrequested song sections or tempo changes.
  • Eclips is lead, Ray is bass, SD3 is drums. Select a default profile only when the registry declares an unambiguous verified default; otherwise return a profile-selection error identifying the available choices.
  • Explicit agp requires at least one selected lead/bass part; explicit sdp requires drums. Apply a format only to its relevant selected parts.
  • One combined .mid contains every selected part when MIDI is requested.
  • An allowed native fallback also emits one combined .mid containing all selected parts, even if mid was not explicitly listed. Explain which native targets it substitutes for. Emit it only once.
  • Unknown or unverifiable plugin mappings are not repaired by guessed MIDI events. MIDI fallback for a target requires a verified map for the requested notes/techniques; otherwise fail explicitly.

Success return type:

GenerationResult {
  status: "complete" | "midi_fallback",
  resolved: {
    parts: ("lead" | "bass" | "drums")[],
    tempo_bpm: number,
    bars: integer,
    time_signature: {numerator: integer, denominator: integer},
    key: string,
    seed: integer,
    profile_ids: object,
    assumptions: string[],
    overrides: string[],
    musical_start_tick: integer,
    musical_end_tick: integer,
    ticks_per_quarter: integer
  },
  artifacts: [{
    format: "mid" | "agp" | "sdp",
    parts: ("lead" | "bass" | "drums")[],
    path: string,
    size_bytes: integer,
    profile_ids: string[],
    fallback_for: ("lead" | "bass" | "drums")[]
  }],
  warnings: [{code: string, part: string | null, message: string}]
}

path is the resolved absolute local path to an actually published file, not encoded file bytes. No MCP resource endpoint or on-disk sidecar is introduced. Native artifacts each identify one part; the MIDI artifact identifies all its included tracks. complete means every requested applicable output was made. midi_fallback means native output was unavailable and an allowed substitution was made; it must include explicit warnings, not success-shaped silence.

Use MCP structuredContent with a concise text content summary for successful results. For domain failures, return isError: true and a structured GenerationError {code, message, details} branch declared in the tool's output schema, subject to the selected SDK's schema facilities. Protocol-level malformed requests remain SDK JSON-RPC errors; do not mislabel every error as a parse error.

Expected error codes include INVALID_REQUEST, UNSUPPORTED_DESCRIPTION, PROFILE_REQUIRED, UNSUPPORTED_ARTICULATION, NATIVE_FORMAT_UNAVAILABLE, OUTPUT_EXISTS, OUTPUT_IO_ERROR, and SERIALIZATION_ERROR.

8. Text interpretation and composition strategy

Start with a documented, deterministic local vocabulary rather than adding a model provider. Support explicit note/key names, tempo, meter, bar length, part selection, note subdivisions, rests, and verified articulation aliases. Small rhythm templates implement riff, lead, bass groove, and drum-pattern requests; each template shares the same grid and key.

Translate supported qualitative terms through documented rules, such as a specific tempo for "slow" when no numeric tempo is provided. Freeze those rules in tests. Descriptive filler may be ignored, but materially unsupported musical instructions must produce an actionable error, not an unrelated generic loop. Support more text vocabulary only when necessary for this scoped generation.

Lead and bass use the resolved key and verified playable ranges. Drums use the selected SD3 map, never an assumed General MIDI map disguised as an SD3 map. Requested lead/bass/drum parts align over exactly the resolved bar count. Any optional variation is seeded, bounded, and cannot move notes outside the range, timeline, or supported articulation semantics.

9. Articulation mapping and event scheduling

Profiles are declarative, versioned JSON data validated at load time. For each articulation store the applicable combination of:

  • Canonical name and supported text aliases.
  • Keyswitch note number, velocity, gate length, lead time, and channel.
  • Whether switching is latched or momentary, and required reset/release actions.
  • CC number/value actions, their channel and timing, and any reset value.
  • Verified velocity-layer ranges and intensity-to-layer behavior.
  • Playable note range or percussion voice mapping and overlap restrictions.
  • Source/version provenance and limitations.

For example, text "palm mute" normalizes to palm_mute. The selected verified Eclips or Ray profile supplies the actual keyswitch/CC/layer values; the compiler emits those controls before the associated musical note and releases/resets them according to the profile. This plan intentionally specifies no unverified vendor note number. Tests may use clearly labeled synthetic values.

MIDI numbers are authoritative; octave labels alone are insufficient because applications label octaves differently. Musical note-on velocity is 1-127; controller values and note-off velocities are 0-127. Layer boundaries must be valid, non-overlapping, and tested at both ends. Never silently clamp an invalid profile or intensity into a plausible output.

The scheduler must:

  1. Resolve profile state independently per part/channel; lead, bass, and drums use separate channels, with the drum channel documented by its profile.
  2. Emit selection controls only when needed, unless a momentary technique requires per-note triggers.
  3. Reject overlapping notes requiring incompatible latched articulations on the same channel unless the verified profile supplies a supported mechanism.
  4. Never emit negative ticks. For required pre-note lead time at song start, calculate one common pre-roll for all parts and all applicable native adapters. Report the musical-start tick; never independently shift one part. If a native format cannot preserve that relationship, mark that native capability unavailable rather than misaligning outputs.
  5. Apply profile lead times explicitly. At equal ticks, finish applicable releases/note-offs, then selection/reset controls as dictated by state transitions, then note-ons; use stable tie-breaking. Do not let a generic sort undo a profile's required causal ordering.
  6. Pair every musical note and keyswitch note with a release, handle repeated same-pitch notes, and restore momentary CC/keyswitch state appropriately.
  7. Preserve control events in the same part track as affected notes so a single Cubase part import does not lose its switches.

Standard MIDI fallback retains the verified target's articulation events. It does not guarantee that arbitrary General MIDI synthesizers will reproduce plugin articulations.

10. File generation and publication

Standard MIDI

  • Produce synchronous SMF type 1 with a conductor track plus selected part tracks, shared resolution, tempo, time signature, and meaningful track names.
  • Quantize exact beat positions to the documented tick grid, stable-sort absolute events, and convert to nonnegative integer delta times once.
  • Include valid end-of-track events at the shared end boundary, accounting for pre-roll and necessary control releases. Distinguish musical end from any documented release tail.
  • Mido reads each saved file back. Validate header/type, track layout, timing, channels, tempo/meter, note pairing, CC payloads, and expected duration.
  • Use MIDIUtil-generated reference files in tests to compare normalized musical events. Do not require byte equality across libraries.

Ample .agp

  • Lead and bass get separate artifacts, normally <basename>_lead.agp and <basename>_bass.agp.
  • Support only layouts/versions established by the native evidence gate.
  • Determine whether the native format stores notes, patterns, articulation identifiers, MIDI events, preset state, or references. Serialize the correct representation; do not assume it is a MIDI container.
  • Reuse shared score/event structures, but share guitar/bass serialization only if evidence proves compatibility.
  • Validate structure and supported round trips automatically. Require an actual Eclips/Ray import test before claiming each instrument/version compatible.

Superior Drummer 3 .sdp

  • Normally emit <basename>_drums.sdp.
  • Verify whether the extension supports the generated groove/song data. Preset-only support does not satisfy a drum-song writer.
  • Preserve the selected verified drum map, event timing, velocity, and supported articulation controls in the representation the real format requires.
  • Validate structure/round trips and require a real SD3 import test before a compatibility claim.

Fallback and filesystem behavior

Check known native capabilities before writing. If a requested native capability is unavailable and fallback is allowed, retain available requested native outputs and emit the combined MIDI plus explicit NATIVE_FORMAT_UNAVAILABLE warnings. If fallback is disabled, fail without publishing any files.

Fallback applies only to known capability limitations. Unexpected serialization errors, corrupt templates, invalid profiles, permission errors, and disk errors must fail visibly; do not hide them by returning a MIDI-only success.

The startup output root is local and configured by the operator. Tool requests cannot supply arbitrary output paths. Resolve and validate it, reject unsafe basenames and Windows reserved names, and prevent path traversal or escaping through links/reparse points.

Stage the complete validated artifact set in a unique directory under that root. Publish it as <output-root>/<basename> with a same-volume directory rename, rejecting any existing destination rather than overwriting. A competing request for the same basename must fail explicitly; do not overwrite or merge directories. Return paths only after publication succeeds. On failure, clean up only this request's temporary files. Keep all behavior testable with temporary directories.

No manifests, project databases, audio files, or extra output formats are needed.

11. Testing and compatibility strategy

Unit tests

  • Strict schemas: valid bounds, invalid numeric types/values, unknown fields, conflicting parts/formats/profiles, and safe basenames.
  • Text parsing: supported phrases, aliases, structured override precedence, defaults, contradictions, and materially unsupported requests.
  • Musical generation: exact bar lengths in different meters, aligned parts, key/range constraints, deterministic seeds, and event-budget rejection.
  • Profiles: provenance/capability fields, corrupt JSON, MIDI ranges, layer boundaries, drum maps, and exclusion of synthetic production mappings.
  • Articulations: keyswitch ordering/lead times, latching, momentary release, CC reset, velocity layers, channel isolation, retriggers, and incompatible overlapping articulations.
  • MIDI: integer nonnegative deltas, note pairing, conductor data, pre-roll, shared endings, and deterministic semantic output.
  • Native adapters: verified structure/version behavior, known fixtures, corrupted/truncated inputs, and explicit capability failures.
  • Service: fallback enabled/disabled, honest warnings/status, no false native artifacts, no publication after failure, and output-collision handling.

Automated integration tests

  • Description -> score -> mapped MIDI -> disk -> Mido read-back.
  • MIDIUtil reference file -> Mido normalization, compared with production output for the same controlled musical events.
  • Request native and MIDI together; verify output names, actual signatures, artifact metadata, exact musical events, and fallback policy.
  • Use real verified native fixtures/validators when available; fake adapters may test service plumbing but never establish native compatibility.
  • Launch the installed Python module as a subprocess and exercise initialize, initialized notification, tools/list, and tools/call over real stdio.
  • Check parse/invalid-parameter/unknown-method handling supported by the SDK, request-ID preservation, notification behavior, protocol-clean stdout, and clean EOF shutdown. Do not invent a JSON-RPC shutdown method.
  • Run from a different working directory and from the built distribution to prove packaged profiles and imports work outside the repository.
  • Check temporary-root confinement, unsafe paths, same-name collisions, permission/serialization failures, and cleanup without deleting other files.

Manual application acceptance

Keep a versioned matrix in docs/compatibility.md covering:

  1. Import the MIDI into Cubase; confirm tempo/meter, track alignment, duration, instrument routing, switches/CC, and usable musical content.
  2. Load lead .agp into the exact Eclips version and bass .agp into Ray; verify notes, timing, velocity, articulation, and subsequent save/reload.
  3. Load .sdp into the exact SD3 version and verify drum song/groove content, mapping, timing, dynamics, and save/reload.
  4. Confirm native and MIDI variants represent the same requested musical parts.
  5. Record application versions, fixture identifiers, expected/observed results, and limitations without publishing licensed user data.

Pure-Python CI cannot replace these application checks. A missing application or private fixture is a named blocker, not a passed test. Separate public tests from private compatibility tests and disclose any skips in every report.

Use targeted tests during development, plus the complete suite, configured lint/type checks, and package-build checks at final acceptance. No benchmarks, coverage threshold, or unrelated CI platform is required by this scope.

12. Phased worker sequence

Every row becomes exactly one detailed worker prompt only when its turn is approved. File lists identify the main owned surfaces; each prompt will specify the exact test files and documentation changes after inspecting prior work. Later workers reuse reviewed contracts rather than replacing working modules.

Step 1: Foundation and compatibility evidence inventory

  • Objective: establish packaging, test/lint/type commands, the package skeleton, and an honest product/format/profile evidence inventory.
  • Files: pyproject.toml, .gitignore, README.md, package __init__.py, initial test scaffold, docs/architecture.md, docs/compatibility.md, docs/formats/agp.md, and docs/formats/sdp.md.
  • Implementation: select supported dependencies/Python policy, establish src layout, record lawful fixture sources and exact instrument/version questions, and document native/mapping gates without inventing implementations.
  • Unit tests: package import/version smoke tests.
  • Integration tests: build/install into a test environment and import from outside the repository; run the configured checks.
  • Acceptance: reproducible foundation and explicit evidence/blocker inventory. An inventory can be complete while native evidence remains unresolved; that does not certify a writer or permit bypassing its later gate.

Step 2: Typed domain models and MCP tool contracts

  • Depends on: Step 1.
  • Files: schemas.py, errors.py, schema/domain tests, related contract docs.
  • Implementation: strict request/result models, profile summaries, musical intent/score/event models, validation rules, errors, and JSON Schemas.
  • Unit tests: parameter bounds, default resolution boundaries, unknown fields, incompatible combinations, event validity, and result/error schemas.
  • Integration tests: representative requests/results round-trip through models and published schemas, including all parts and formats.
  • Acceptance: one authoritative typed contract with no duplicated validation.

Step 3: MCP stdio server skeleton

  • Depends on: Steps 1 and 2.
  • Files: server.py, __main__.py, package entry point configuration, protocol integration tests, startup usage documentation.
  • Implementation: SDK stdio lifecycle, two tool registrations, output-root configuration, stderr logging, and explicit unfinished-service errors. Temporary unfinished errors are development-only and removed in Step 9.
  • Unit tests: handler argument/result/error translation and root validation.
  • Integration tests: real subprocess initialization, listing tools/schemas, notification behavior, malformed requests, stdout cleanliness, and EOF.
  • Acceptance: valid MCP skeleton; unfinished generation never claims success.

Step 4: MIDI timing, scheduling, and file writer

  • Depends on: Step 2.
  • Files: midi.py, event-model refinements if needed, MIDI unit/integration tests, lawful MIDI fixtures, timing documentation.
  • Implementation: exact timeline math, deterministic event ordering, SMF type 1 writing, conductor/part tracks, and post-write validation.
  • Unit tests: multiple meters, boundaries, repeated pitches, channels, event ordering, pre-roll, release tails, note pairing, and invalid event rejection.
  • Integration tests: multi-part files read back with Mido and independently generated MIDIUtil reference-event comparisons.
  • Acceptance: valid deterministic MIDI from explicit controlled event plans; no unverified instrument-specific claims.

Step 5: Instrument profiles and articulation compiler

  • Depends on: Steps 2 and 4; verified mapping evidence for production targets.
  • Files: profiles.py, articulations.py, verified profile JSON files, synthetic profile fixtures, profile/compiler tests, docs/articulation-profiles.md.
  • Implementation: versioned mappings, real playable/drum ranges, keyswitch/CC actions, layer selection, state transitions, and overlap restrictions.
  • Unit tests: layer boundaries, aliases, latched/momentary switches, resets, profile rejection, and channel/state isolation.
  • Integration tests: logical palm-muted lead/bass and articulated drums compiled to MIDI; assert exact events using documented profile values.
  • Acceptance: real mappings have evidence. Synthetic tests can prove compiler mechanics but cannot close a missing production-profile gate.

Step 6: Text interpretation and coordinated composition

  • Depends on: Steps 2, 4, and 5.
  • Files: description.py, compose.py, description fixtures, parser/composer unit tests, full text-to-MIDI integration tests, supported-text usage docs.
  • Implementation: supported vocabulary, defaults/overrides, seeded bounded patterns, aligned parts, key/range validation, and event-budget enforcement.
  • Unit tests: parsing contradictions/unknown instructions, exact meter/bar lengths, seed reproducibility, range compliance, and articulation selection.
  • Integration tests: representative descriptions covering lead-only, bass-only, drums-only, and combined parts, verified after MIDI read-back.
  • Acceptance: genuinely text-driven content; no silent unrelated default loop.

Step 7: Verified Ample .agp generation

  • Depends on: Steps 4-6 and the Ample native evidence gate.
  • Files: formats/__init__.py, formats/agp.py, lawful native fixtures, Ample unit/integration tests, docs/formats/agp.md, compatibility matrix.
  • Implementation: supported layout/version serialization for Eclips and Ray; preserve exact rhythm, dynamics, and required articulation semantics.
  • Unit tests: native fields, version checks, invalid data, fixture round trips, and distinct guitar/bass behavior where necessary.
  • Integration tests: generated native files structurally validated against evidence; actual Eclips/Ray import and save/reload recorded separately.
  • Acceptance: both targets verified. An unavailable adapter or renamed MIDI is not completion. If blocked, issue an evidence/fix prompt and seek the needed files/decision rather than pretending this step passed.

Step 8: Verified Superior Drummer 3 .sdp generation

  • Depends on: Steps 4-6 and the SD3 native evidence gate.
  • Files: formats/sdp.py, lawful SD3 fixtures, SD3 unit/integration tests, docs/formats/sdp.md, compatibility matrix.
  • Implementation: the confirmed SD3 container/content representation with generated drum events, mapping, timing, and dynamics.
  • Unit tests: supported fields/versions, corrupt/truncated data, fixture round trips, and mapping/articulation preservation.
  • Integration tests: structural validation plus real SD3 import/save/reload.
  • Acceptance: actual drum content loads correctly; a preset-only file or metadata stub does not satisfy the requested generation.

Step 9: Generation service, fallback, and complete MCP wiring

  • Depends on: Steps 3-8.
  • Files: service.py, server.py, result/error integration, service and end-to-end stdio tests, final output/fallback usage documentation.
  • Implementation: connect the full pipeline, profiles tool, capability policy, all requested artifacts, atomic publication, structured results, and explicit operational failures. Remove development-only unfinished handlers.
  • Unit tests: output planning, fallback policy, error translation, safe names, collision handling, and exact artifact/result metadata.
  • Integration tests: real stdio generation in all formats; injected unavailable capabilities with fallback on/off; serialization/IO failures; no partial publication; concurrent same-basename requests.
  • Acceptance: externally usable tools with honest results and no silent failures.

Step 10: Compatibility acceptance and release readiness

  • Depends on: Steps 1-9.
  • Files: end-to-end/regression tests, packaging metadata as needed, README.md, architecture/format/profile docs, and compatibility matrix.
  • Implementation: close task-caused defects, verify installed distribution behavior, and document MCP client configuration and Cubase/plugin imports. Do not add unrelated capabilities during final hardening.
  • Unit tests: complete suite with regressions for any fixes.
  • Integration tests: installed-package stdio workflow, representative combined exports, validated native fixtures, and final application acceptance matrix.
  • Acceptance: configured lint/type checks, build, full automated suite, and required manual compatibility evidence pass; all skips/blockers disclosed.

Although some dependencies are technically independent, execution is deliberately one worker prompt at a time in the listed order. If a blocker requires reordering independent work, the orchestrator must first record the proposed adjustment and obtain review; it must not silently skip a failed or unreviewed step.

13. Worker prompt and report protocol

After this plan is reviewed:

  1. Create only prompts/step_1.md; do not generate the later prompts in bulk.

  2. Each prompt contains the objective, prerequisites/evidence gates, exact files, implementation constraints, unit tests, integration tests, validation commands, and measurable acceptance criteria.

  3. Include this exact instruction, substituting the current step number for N:

    When complete, write your end-of-step report to ./prompts/report_N.md including: what was implemented, test results (pass/fail with details), any issues encountered, and whether you're ready for the next step

  4. Also require changed-file summaries, exact commands and outcomes, skipped tests with reasons, compatibility evidence where relevant, and unresolved blockers. Require the entire report inside one plain triple-backtick fence, with no content outside it.

  5. Hand off that prompt and wait. Do not implement the worker's task in parallel or assume that creating a prompt means its task is complete.

  6. Read prompts/report_N.md, inspect relevant implementation/evidence, and evaluate acceptance critically. A report alone is not proof: run focused checks where needed; native claims require real application evidence.

  7. If defects, failed tests, undisclosed skips, or blockers remain, create prompts/step_N_fix.md instead of the next step. Require prompts/report_N_fix.md; read and evaluate it before advancing. If further corrections are needed, revise the fix prompt and require a fresh report, preserving prior outcomes in the report's history.

  8. Ask for missing user-owned evidence or decisions when a blocker cannot be resolved locally. Do not manufacture fixtures, maps, or passing results.

  9. Create prompts/step_(N+1).md only after the current step is accepted.

Historical planning decision: no worker was launched and no first worker prompt was created during the initial architecture-only request. User approval and the continuation decision above subsequently authorized implementation; the initial awaiting-review state is no longer current. Prior step reports remain historical.

14. Final definition of done

  • A packaged Python server implements the reviewed MCP stdio contracts.
  • Supported text descriptions generate aligned lead, bass, and drum content.
  • Verified keyswitch, velocity-layer, and CC behavior survives export.
  • Standard MIDI files validate and import into Cubase.
  • Actual .griff / .briff files load into Eclipse 4.0.1 / Ray5 4.1.0; agp is retained as a request alias, not a mislabeled file suffix.
  • Actual .sd3p files load the generated drum content into SD3 3.4.4/SL-DFH; sdp remains a request alias. Software serialization is verified, while application load/play/save/reload remains UNRUN.
  • Native fallback is explicit, test-covered, and never masks data/IO failures.
  • No false file extensions, fabricated mappings, partial published requests, protocol-noisy stdout, or unreported compatibility gaps remain.
  • Tests, packaging checks, documentation, and required application evidence are complete. MIDI-only support is useful interim progress, not completion of the full requested scope.

15. Planning references

Public documentation consulted during architecture planning:

Vendor references above identify evidence still needed; they do not establish that .agp or .sdp serialization has been verified.