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

887 lines
47 KiB
Markdown

# 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.
```text
.
|-- 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
```text
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:
```text
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|8|16}` | Optional | Explicit meter override. |
| `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:
```text
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:
- [MCP stdio transport](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports)
- [MCP lifecycle](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle)
- [MCP tools and schemas](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)
- [Mido Standard MIDI Files](https://mido.readthedocs.io/en/stable/files/midi.html)
- [MIDIUtil documentation](https://midiutil.readthedocs.io/en/1.2.1/)
- [Ample manual entry point](https://www.amplesound.net/en/manual.asp):
attempted; no usable format specification obtained.
- [Superior Drummer 3 manual entry point](https://www.toontrack.com/manual/superior-drummer-3/):
login required; no native layout verified.
Vendor references above identify evidence still needed; they do not establish
that `.agp` or `.sdp` serialization has been verified.