Sync: Complete project state with all MEGA SPRINT V1-V3 features and Codex stubs
This commit is contained in:
renato97
417
docs/SPRINT_v0.1.36_NEXT_KIMI_PROJECT_EDITING.md
Normal file
417
docs/SPRINT_v0.1.36_NEXT_KIMI_PROJECT_EDITING.md
Normal file
@@ -0,0 +1,417 @@
|
||||
# SPRINT v0.1.36 - NEXT FOR KIMI
|
||||
## Expose Real Project-Editing Tools In MCP And Use `song.als` As The Benchmark
|
||||
|
||||
**Owner:** Kimi via OpenCode
|
||||
**Reviewer:** Codex
|
||||
**Fecha:** 2026-04-03
|
||||
**Context:** We are no longer only generating songs from scratch. We now need to edit already-open Ableton projects until they sound professional.
|
||||
|
||||
Primary benchmark project:
|
||||
|
||||
- `C:\Users\ren\Desktop\song Project\song.als`
|
||||
|
||||
Supporting audit:
|
||||
|
||||
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs\PROJECT_AUDIT_song_2026-04-03.md`
|
||||
|
||||
---
|
||||
|
||||
## 1. Core Product Decision
|
||||
|
||||
From this sprint forward, the system must support two workflows:
|
||||
|
||||
1. `generate new song`
|
||||
2. `edit existing opened project`
|
||||
|
||||
The second workflow is now mandatory.
|
||||
|
||||
The `song.als` project is the first real benchmark for it.
|
||||
|
||||
---
|
||||
|
||||
## 2. Current MCP Truth
|
||||
|
||||
Codex verified the current MCP situation.
|
||||
|
||||
### 2.1 What is already exposed as public MCP tools
|
||||
|
||||
The server already exposes:
|
||||
|
||||
- `get_session_info`
|
||||
- `get_tracks`
|
||||
- `get_track_info`
|
||||
- `set_track_name`
|
||||
- `set_track_color`
|
||||
- `set_track_volume`
|
||||
- `apply_clip_fades`
|
||||
- `write_volume_automation`
|
||||
- `apply_sidechain_pump`
|
||||
- `arrange_song_structure`
|
||||
- `set_loop_markers`
|
||||
- `create_drum_pattern`
|
||||
- `create_bassline`
|
||||
- `create_chord_progression`
|
||||
- `validate_set`
|
||||
- `diagnose_generated_set`
|
||||
- `get_generation_manifest`
|
||||
- generation tools
|
||||
|
||||
This means:
|
||||
|
||||
- basic editing exists
|
||||
- but not enough for serious project editing
|
||||
|
||||
### 2.2 What already exists in runtime but is NOT properly exposed as MCP tools
|
||||
|
||||
Codex verified these capabilities already exist in:
|
||||
|
||||
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\abletonmcp_init.py`
|
||||
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\abletonmcp_runtime.py`
|
||||
|
||||
Existing runtime commands include:
|
||||
|
||||
- `set_track_mute`
|
||||
- `set_track_solo`
|
||||
- `set_track_arm`
|
||||
- `set_track_pan`
|
||||
- `set_track_send`
|
||||
- `set_device_parameter`
|
||||
- `create_arrangement_clip`
|
||||
- `add_notes_to_arrangement_clip`
|
||||
- `duplicate_clip_to_arrangement`
|
||||
|
||||
These are exactly the kinds of operations we need for editing real projects.
|
||||
|
||||
### 2.3 Main gap
|
||||
|
||||
The gap is not “Ableton cannot do it”.
|
||||
|
||||
The gap is:
|
||||
|
||||
- the runtime can do it
|
||||
- but the MCP server does not expose enough of it in a clean public interface
|
||||
|
||||
Conclusion:
|
||||
|
||||
- yes, we **must give those tools to MCP**
|
||||
|
||||
---
|
||||
|
||||
## 3. Project-Audit Truth To Respect
|
||||
|
||||
From `PROJECT_AUDIT_song_2026-04-03.md`, Kimi must treat these as real product targets:
|
||||
|
||||
- the arrangement exists but is still skeletal
|
||||
- the project has useful palette and bass continuity
|
||||
- the harmonic MIDI spine is empty in Arrangement
|
||||
- there are too many arrangement islands
|
||||
- the declared structure and actual timeline are mismatched
|
||||
- this project is worth editing, not discarding
|
||||
|
||||
This sprint is therefore about:
|
||||
|
||||
- making project editing possible
|
||||
- not about generating another new song
|
||||
|
||||
---
|
||||
|
||||
## 4. Coding Goals
|
||||
|
||||
## P0. Expose project-edit primitives as public MCP tools
|
||||
|
||||
Add public MCP tools in:
|
||||
|
||||
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py`
|
||||
|
||||
using the already-existing runtime support underneath.
|
||||
|
||||
### Required new MCP tools
|
||||
|
||||
#### Inspection
|
||||
|
||||
- `get_clips(track_index)`
|
||||
- `get_devices(track_index, track_type="track")`
|
||||
- `get_clip_info(track_index, clip_index)`
|
||||
|
||||
These are required so an agent can inspect an already-open project without guessing.
|
||||
|
||||
#### Track control
|
||||
|
||||
- `set_track_mute(track_index, mute, track_type="track")`
|
||||
- `set_track_solo(track_index, solo, track_type="track")`
|
||||
- `set_track_arm(track_index, arm, track_type="track")`
|
||||
- `set_track_pan(track_index, pan, track_type="track")`
|
||||
- `set_track_send(track_index, send_index, value, track_type="track")`
|
||||
|
||||
These are required for real editing and mix decisions.
|
||||
|
||||
#### Device control
|
||||
|
||||
- `set_device_parameter(track_index, device_index, value, parameter_name="", parameter_index=-1, track_type="track")`
|
||||
|
||||
This is required to shape an already-built project instead of regenerating it.
|
||||
|
||||
#### Arrangement editing
|
||||
|
||||
- `create_arrangement_clip(track_index, start_time, length)`
|
||||
- `add_notes_to_arrangement_clip(track_index, start_time, notes)`
|
||||
- `duplicate_clip_to_arrangement(track_index, clip_index, start_time)`
|
||||
|
||||
These are the minimum serious tools needed to:
|
||||
|
||||
- fill harmonic holes
|
||||
- extend sections
|
||||
- edit MIDI support over an existing song
|
||||
|
||||
---
|
||||
|
||||
## P0. Add a first-class editing workflow for existing songs
|
||||
|
||||
Do not stop at exposing low-level tools.
|
||||
|
||||
Add one orchestration path in the server for project editing.
|
||||
|
||||
### Preferred direction
|
||||
|
||||
Add a tool like:
|
||||
|
||||
- `audit_current_project()`
|
||||
|
||||
and optionally:
|
||||
|
||||
- `refine_existing_song(...)`
|
||||
|
||||
But do **not** make `refine_existing_song` a fake magic black box.
|
||||
|
||||
It must internally use the new public MCP-edit tools and return inspectable actions.
|
||||
|
||||
### Minimum acceptable behavior for `audit_current_project()`
|
||||
|
||||
It should detect:
|
||||
|
||||
- longest drum gap
|
||||
- longest harmonic gap
|
||||
- tracks with zero arrangement clips
|
||||
- MIDI harmonic tracks with devices but no clips
|
||||
- declared section structure mismatch
|
||||
- repeated sample overuse
|
||||
|
||||
This tool should be aimed at real projects, not only generated manifests.
|
||||
|
||||
---
|
||||
|
||||
## P0. Use `song.als` as the benchmark project
|
||||
|
||||
Kimi must develop against the actual benchmark:
|
||||
|
||||
- `C:\Users\ren\Desktop\song Project\song.als`
|
||||
|
||||
The sprint is not complete if the new editing tools only work on toy examples.
|
||||
|
||||
Required benchmark checks:
|
||||
|
||||
- inspect tracks from the loaded project
|
||||
- inspect clips from the loaded project
|
||||
- inspect devices from the loaded project
|
||||
- create or extend MIDI harmony in the loaded project
|
||||
|
||||
---
|
||||
|
||||
## P1. Do not confuse shell-level project opening with MCP editing
|
||||
|
||||
Opening a `.als` file can remain outside MCP for now.
|
||||
|
||||
Shell-level opening is acceptable:
|
||||
|
||||
- `Start-Process "C:\ProgramData\Ableton\Live 12 Suite\Program\Ableton Live 12 Suite.exe" -ArgumentList '"C:\Users\ren\Desktop\song Project\song.als"'`
|
||||
|
||||
That is not the blocker.
|
||||
|
||||
The blocker is:
|
||||
|
||||
- once the project is open, MCP still lacks enough public editing tools
|
||||
|
||||
So do not waste this sprint inventing a fancy “open set” MCP feature first.
|
||||
|
||||
Prioritize editing and inspection.
|
||||
|
||||
---
|
||||
|
||||
## P1. Keep product semantics correct
|
||||
|
||||
### No piano requirement
|
||||
|
||||
The user explicitly said:
|
||||
|
||||
- no pianos
|
||||
|
||||
So for this sprint:
|
||||
|
||||
- do not add piano-specific strategy
|
||||
- do not build new features around piano timbre
|
||||
- if a track is currently called `HARMONY_PIANO_MIDI`, treat it as an editable harmonic MIDI track, not as a reason to force piano sound
|
||||
|
||||
### Harmonic role is still required
|
||||
|
||||
Even with no piano:
|
||||
|
||||
- harmonic MIDI support remains required
|
||||
- the editing workflow must be able to add MIDI notes across the arrangement
|
||||
|
||||
The point is:
|
||||
|
||||
- non-piano harmonic editing
|
||||
- not no-harmony
|
||||
|
||||
---
|
||||
|
||||
## 5. Code Review Constraints
|
||||
|
||||
Kimi must follow these review-grade rules.
|
||||
|
||||
### 5.1 Do not just expose wrappers blindly
|
||||
|
||||
Each new MCP tool must:
|
||||
|
||||
- validate parameters
|
||||
- call the correct runtime command
|
||||
- return useful JSON or readable text
|
||||
- handle `track_type` correctly where relevant
|
||||
|
||||
### 5.2 Do not break generation while adding editing
|
||||
|
||||
This sprint is about adding editing capability.
|
||||
|
||||
Do not regress:
|
||||
|
||||
- `generate_track`
|
||||
- `generate_song`
|
||||
- runtime truth
|
||||
- manifest persistence
|
||||
|
||||
### 5.3 Do not build project editing only around manifests
|
||||
|
||||
Real editing must inspect the actual open project state:
|
||||
|
||||
- tracks
|
||||
- clips
|
||||
- devices
|
||||
|
||||
Not only the stored manifest.
|
||||
|
||||
### 5.4 Do not overtrust ALS XML for mutable runtime truth
|
||||
|
||||
The `.als` file is useful for audit.
|
||||
|
||||
But live editing truth must come from:
|
||||
|
||||
- the loaded Live set via MCP tools
|
||||
|
||||
That means the new tools must become the primary source of truth after opening the project.
|
||||
|
||||
---
|
||||
|
||||
## 6. Required Implementation Order
|
||||
|
||||
Kimi must implement in this order:
|
||||
|
||||
1. public inspection tools
|
||||
2. public track/device edit tools
|
||||
3. public arrangement MIDI edit tools
|
||||
4. one project-audit tool
|
||||
5. benchmark validation against `song.als`
|
||||
|
||||
Do not start from a giant “smart edit” tool before the primitives exist.
|
||||
|
||||
---
|
||||
|
||||
## 7. Required Tests
|
||||
|
||||
Kimi must add tests for the new MCP-facing layer.
|
||||
|
||||
Minimum coverage:
|
||||
|
||||
### Tool exposure tests
|
||||
|
||||
Verify the server exports the new tools:
|
||||
|
||||
- clip inspection
|
||||
- device inspection
|
||||
- track control
|
||||
- arrangement edit
|
||||
|
||||
### Parameter validation tests
|
||||
|
||||
Verify bad indexes and bad values fail cleanly.
|
||||
|
||||
### Runtime command wiring tests
|
||||
|
||||
Verify each MCP tool sends the correct command payload to Ableton.
|
||||
|
||||
### Project-edit benchmark tests
|
||||
|
||||
At least one test must cover the logic needed for:
|
||||
|
||||
- detecting an empty harmonic MIDI track with an instrument loaded
|
||||
- identifying arrangement holes worth filling
|
||||
|
||||
---
|
||||
|
||||
## 8. Required Validation For The Report
|
||||
|
||||
The next validation report is invalid unless it includes:
|
||||
|
||||
### New tools
|
||||
|
||||
- exact list of new MCP editing tools added
|
||||
|
||||
### Evidence
|
||||
|
||||
- proof they are callable from OpenCode
|
||||
- proof they work on the open `song.als` project
|
||||
|
||||
### Benchmark actions
|
||||
|
||||
At minimum, Kimi must demonstrate:
|
||||
|
||||
1. inspect clip data on a real track from `song.als`
|
||||
2. inspect devices on `HARMONY_PIANO_MIDI`
|
||||
3. create or extend arrangement MIDI on that track or another chosen harmonic track
|
||||
|
||||
### Honesty requirement
|
||||
|
||||
If the tools are exposed but not yet pleasant to use, say so.
|
||||
|
||||
Do not call the editing workflow “done” if it is still only low-level and awkward.
|
||||
|
||||
---
|
||||
|
||||
## 9. What Success Looks Like
|
||||
|
||||
At the end of this sprint, OpenCode/Kimi should be able to do this on a loaded project:
|
||||
|
||||
1. inspect tracks
|
||||
2. inspect clips
|
||||
3. inspect devices
|
||||
4. mute/solo/arm tracks if needed
|
||||
5. change pan/sends/device parameters
|
||||
6. create an arrangement MIDI clip
|
||||
7. add notes to it
|
||||
8. duplicate or extend arrangement material
|
||||
|
||||
That is the minimum viable “edit existing song” workflow.
|
||||
|
||||
If those steps work, we can stop treating every problem as “generate again”.
|
||||
|
||||
---
|
||||
|
||||
## 10. Non-Goals
|
||||
|
||||
Do not spend this sprint on:
|
||||
|
||||
- new genre generation features
|
||||
- new piano-forward logic
|
||||
- more reference-remake tuning
|
||||
- cosmetic report polish
|
||||
|
||||
This sprint is about giving the MCP real editing hands.
|
||||
Reference in New Issue
Block a user