Sync: Complete project state with all MEGA SPRINT V1-V3 features and Codex stubs
This commit is contained in:
renato97
424
docs/SPRINT_v0.1.33_NEXT_OPENCODE.md
Normal file
424
docs/SPRINT_v0.1.33_NEXT_OPENCODE.md
Normal file
@@ -0,0 +1,424 @@
|
||||
# SPRINT v0.1.33 - NEXT FOR OPENCODE
|
||||
## Use The Ableton MCP Correctly, Stop Stalling, Generate Songs With Tools Or Python Fallback
|
||||
|
||||
**Owner:** OpenCode
|
||||
**Reviewer:** Codex
|
||||
**Fecha:** 2026-04-03
|
||||
**Reason:** OpenCode is behaving as if the MCP were unavailable or unreliable, and is overthinking instead of using the tools to make songs.
|
||||
|
||||
---
|
||||
|
||||
## 1. Verified MCP Truth
|
||||
|
||||
Codex already verified the MCP state from this workspace.
|
||||
|
||||
Current truth:
|
||||
|
||||
- OpenCode MCP server is connected
|
||||
- `toolCount = 77`
|
||||
- canonical wrapper is:
|
||||
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py`
|
||||
- current OpenCode config is valid in:
|
||||
- `C:\Users\ren\.config\opencode\opencode.json`
|
||||
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\opencode.json`
|
||||
- MCP timeout is already:
|
||||
- `600000 ms`
|
||||
|
||||
Therefore:
|
||||
|
||||
- this is **not** a connection sprint
|
||||
- this is **not** a config sprint
|
||||
- this is a **tool-usage discipline sprint**
|
||||
|
||||
If OpenCode says:
|
||||
|
||||
- "MCP unavailable"
|
||||
- "tools missing"
|
||||
- "timeout means failure"
|
||||
|
||||
without rechecking runtime state, that is a workflow error.
|
||||
|
||||
---
|
||||
|
||||
## 2. Core Problem
|
||||
|
||||
OpenCode is wasting turns in reasoning and often does one of these bad patterns:
|
||||
|
||||
1. thinks too much before calling any MCP tool
|
||||
2. treats a timeout as final failure
|
||||
3. retries generation blindly
|
||||
4. mixes code-debugging behavior into a normal "make me a song" request
|
||||
5. claims a song was generated without validating the runtime result
|
||||
|
||||
This sprint exists to stop that behavior.
|
||||
|
||||
---
|
||||
|
||||
## 3. Hard Rules For OpenCode
|
||||
|
||||
These are not suggestions.
|
||||
|
||||
### 3.1 When the user asks for a song, use MCP immediately
|
||||
|
||||
If the user asks to:
|
||||
|
||||
- create a song
|
||||
- generate a track
|
||||
- remake a reference
|
||||
- refine an existing generated song
|
||||
|
||||
then OpenCode must call Ableton MCP tools early.
|
||||
|
||||
Do not spend the turn in analysis-only mode.
|
||||
|
||||
Within the first tool phase, OpenCode must do at least:
|
||||
|
||||
1. `ableton-mcp-ai_get_session_info`
|
||||
2. `ableton-mcp-ai_get_tracks`
|
||||
3. one generation or edit tool appropriate to the request
|
||||
|
||||
### 3.1.b If MCP tools are temporarily unavailable in the client UI, use Python or shell immediately
|
||||
|
||||
If OpenCode cannot see MCP tools in the chat client but the project is local and the wrapper exists, it must not stop there.
|
||||
|
||||
Approved fallback:
|
||||
|
||||
1. verify MCP config files
|
||||
2. verify wrapper path
|
||||
3. run `opencode mcp list --print-logs`
|
||||
4. inspect Live log if needed
|
||||
5. only after that declare a true MCP problem
|
||||
|
||||
Allowed shell or Python checks:
|
||||
|
||||
- `opencode mcp list --print-logs`
|
||||
- `python C:\\ProgramData\\Ableton\\Live 12 Suite\\Resources\\MIDI Remote Scripts\\mcp_wrapper.py`
|
||||
- `Get-Content C:\\Users\\ren\\AppData\\Roaming\\Ableton\\Live 12.0.15\\Preferences\\Log.txt -Tail 200`
|
||||
|
||||
This fallback path is for diagnosis and recovery, not for replacing song generation logic permanently.
|
||||
|
||||
### 3.2 For full-song creation, prefer async by default
|
||||
|
||||
For a complete song request, the default tool must be:
|
||||
|
||||
- `ableton-mcp-ai_generate_song_async`
|
||||
|
||||
Do **not** start with `generate_song` unless there is a strong reason to keep the call synchronous.
|
||||
|
||||
Reason:
|
||||
|
||||
- full-song generation can legitimately take time
|
||||
- async is the correct contract for long-running jobs
|
||||
- retrying sync generation creates duplicate or misleading states
|
||||
|
||||
### 3.3 Timeout does not equal failure
|
||||
|
||||
If `generate_song_async` or `generate_song` times out:
|
||||
|
||||
- do **not** immediately retry generation
|
||||
- do **not** claim the run failed
|
||||
- do **not** spawn a second generation blindly
|
||||
|
||||
Instead, OpenCode must verify state first.
|
||||
|
||||
### 3.4 Never close a generation turn without validation
|
||||
|
||||
After generation, OpenCode must always run:
|
||||
|
||||
1. `ableton-mcp-ai_validate_set`
|
||||
2. `ableton-mcp-ai_diagnose_generated_set`
|
||||
3. `ableton-mcp-ai_get_generation_manifest`
|
||||
|
||||
If these are missing, the report is incomplete.
|
||||
|
||||
---
|
||||
|
||||
## 4. Approved Workflow
|
||||
|
||||
This is the exact workflow OpenCode must follow.
|
||||
|
||||
There are two approved modes:
|
||||
|
||||
1. `MCP-first`
|
||||
2. `Python/shell recovery`
|
||||
|
||||
### 4.1 Preflight
|
||||
|
||||
Before generating:
|
||||
|
||||
1. call `ableton-mcp-ai_get_session_info`
|
||||
2. call `ableton-mcp-ai_get_tracks`
|
||||
3. confirm Live is reachable
|
||||
4. confirm there is no confusion about the active set state
|
||||
|
||||
Minimum output OpenCode should understand from preflight:
|
||||
|
||||
- tempo
|
||||
- track count
|
||||
- whether the session is empty or already populated
|
||||
|
||||
### 4.1.b Python or shell recovery preflight
|
||||
|
||||
If the client UI cannot access the MCP tools directly, OpenCode must verify local truth with shell or Python before giving up.
|
||||
|
||||
Minimum recovery checks:
|
||||
|
||||
1. `opencode mcp list --print-logs`
|
||||
2. inspect:
|
||||
- `C:\\Users\\ren\\.config\\opencode\\opencode.json`
|
||||
- `C:\\ProgramData\\Ableton\\Live 12 Suite\\Resources\\MIDI Remote Scripts\\opencode.json`
|
||||
3. verify wrapper path:
|
||||
- `C:\\ProgramData\\Ableton\\Live 12 Suite\\Resources\\MIDI Remote Scripts\\mcp_wrapper.py`
|
||||
4. inspect Ableton log:
|
||||
- `C:\\Users\\ren\\AppData\\Roaming\\Ableton\\Live 12.0.15\\Preferences\\Log.txt`
|
||||
|
||||
If those checks show the MCP is healthy, OpenCode must return to MCP generation, not drift into passive analysis.
|
||||
|
||||
### 4.2 Full-song generation
|
||||
|
||||
For "make me a song", use:
|
||||
|
||||
- `ableton-mcp-ai_generate_song_async`
|
||||
|
||||
Typical parameters:
|
||||
|
||||
- `genre`
|
||||
- `style`
|
||||
- `reference_path`
|
||||
- `bpm`
|
||||
- `key`
|
||||
- `structure`
|
||||
|
||||
Example shape:
|
||||
|
||||
- genre: `reggaeton`
|
||||
- style: `perreo duro vieja escuela tipo safaera`
|
||||
- reference_path: `libreria\\reggaeton\\ejemplo.mp3`
|
||||
- bpm: `95`
|
||||
- key: `Am`
|
||||
|
||||
### 4.3 Job follow-up
|
||||
|
||||
If async returns a `job_id`, OpenCode must poll with:
|
||||
|
||||
- `ableton-mcp-ai_get_generation_job_status`
|
||||
|
||||
Poll sparingly and read the state:
|
||||
|
||||
- `queued`
|
||||
- `running`
|
||||
- `completed`
|
||||
- `failed`
|
||||
- `cancelled`
|
||||
|
||||
Do not interpret `running` as failure.
|
||||
|
||||
### 4.4 If the async call itself times out
|
||||
|
||||
This is the recovery order:
|
||||
|
||||
1. re-check `ableton-mcp-ai_get_session_info`
|
||||
2. re-check `ableton-mcp-ai_get_tracks`
|
||||
3. call `ableton-mcp-ai_get_generation_history`
|
||||
4. inspect whether a new run appeared or the set changed
|
||||
5. only retry generation if there is clear evidence that nothing started
|
||||
|
||||
OpenCode must not create duplicate jobs because it panicked on timeout.
|
||||
|
||||
### 4.5 Validation
|
||||
|
||||
After a generation completes, OpenCode must run:
|
||||
|
||||
1. `ableton-mcp-ai_validate_set`
|
||||
2. `ableton-mcp-ai_diagnose_generated_set`
|
||||
3. `ableton-mcp-ai_get_generation_manifest`
|
||||
|
||||
OpenCode must report:
|
||||
|
||||
- the new `session_id`
|
||||
- `generation_mode`
|
||||
- whether the arrangement contains real material
|
||||
- whether the result is usable or still weak
|
||||
|
||||
### 4.6 Python or shell diagnosis is allowed after generation, but it is not the source of truth
|
||||
|
||||
Allowed post-run shell checks:
|
||||
|
||||
- inspect `generation_manifests.json`
|
||||
- inspect `generation_jobs.json`
|
||||
- inspect Ableton `Log.txt`
|
||||
|
||||
But final truth still comes from:
|
||||
|
||||
- MCP validation tools
|
||||
- persisted manifest truth
|
||||
- the actual Arrangement state
|
||||
|
||||
---
|
||||
|
||||
## 5. Approved Edit Workflow
|
||||
|
||||
If the user wants to edit what already exists, OpenCode must not regenerate immediately.
|
||||
|
||||
Start with inspection:
|
||||
|
||||
1. `ableton-mcp-ai_get_session_info`
|
||||
2. `ableton-mcp-ai_get_tracks`
|
||||
3. `ableton-mcp-ai_get_track_info` on the important tracks
|
||||
|
||||
Then use the edit tools that already exist instead of rewriting the whole set:
|
||||
|
||||
- `ableton-mcp-ai_set_track_name`
|
||||
- `ableton-mcp-ai_set_track_volume`
|
||||
- `ableton-mcp-ai_apply_clip_fades`
|
||||
- `ableton-mcp-ai_write_volume_automation`
|
||||
- `ableton-mcp-ai_apply_sidechain_pump`
|
||||
- `ableton-mcp-ai_arrange_song_structure`
|
||||
- `ableton-mcp-ai_set_loop_markers`
|
||||
|
||||
OpenCode must understand this distinction:
|
||||
|
||||
- if the user asks for refinement, edit first
|
||||
- if the user asks for a new song, generate first
|
||||
|
||||
If MCP is temporarily unavailable at the client layer, OpenCode may use Python or shell to inspect manifests, jobs and logs before resuming the edit workflow.
|
||||
|
||||
---
|
||||
|
||||
## 6. Anti-Patterns That Are No Longer Allowed
|
||||
|
||||
### 6.1 Bad pattern: think forever, call nothing
|
||||
|
||||
Wrong:
|
||||
|
||||
- long reasoning
|
||||
- no MCP tools
|
||||
- no song
|
||||
|
||||
Correct:
|
||||
|
||||
- preflight
|
||||
- generation
|
||||
- validation
|
||||
|
||||
### 6.2 Bad pattern: sync timeout then async timeout then surrender
|
||||
|
||||
Wrong:
|
||||
|
||||
1. call `generate_song`
|
||||
2. get timeout
|
||||
3. call `generate_song_async`
|
||||
4. get timeout
|
||||
5. declare MCP broken
|
||||
|
||||
Correct:
|
||||
|
||||
1. use `generate_song_async` first
|
||||
2. if timeout happens, inspect state
|
||||
3. then decide whether a retry is actually necessary
|
||||
|
||||
### 6.3 Bad pattern: report success from logs alone
|
||||
|
||||
Wrong:
|
||||
|
||||
- "generation completed"
|
||||
|
||||
without:
|
||||
|
||||
- `validate_set`
|
||||
- `diagnose_generated_set`
|
||||
- `get_generation_manifest`
|
||||
|
||||
Correct:
|
||||
|
||||
- only claim success when runtime validation agrees
|
||||
|
||||
### 6.4 Bad pattern: use code-review mode for a song request
|
||||
|
||||
If the user asked for a song, OpenCode must not spend the turn mainly reading Python files.
|
||||
|
||||
Only debug code when:
|
||||
|
||||
- generation tools genuinely fail
|
||||
- or the user explicitly asks for debugging/review
|
||||
|
||||
### 6.5 Bad pattern: use Python or Bash as an excuse to avoid MCP
|
||||
|
||||
Wrong:
|
||||
|
||||
- inspect logs
|
||||
- inspect config
|
||||
- inspect python files
|
||||
- never generate
|
||||
|
||||
Correct:
|
||||
|
||||
- use Python or Bash only to restore or verify MCP
|
||||
- return to MCP tools as soon as they are available
|
||||
|
||||
---
|
||||
|
||||
## 7. Product Rules Still Active
|
||||
|
||||
OpenCode must preserve these project requirements while generating:
|
||||
|
||||
- final result must live in Arrangement View
|
||||
- no automatic vocal tracks
|
||||
- user library must remain part of the musical identity
|
||||
- harmonic support must stay present across the song
|
||||
- do not solve variation with silence and holes
|
||||
- do not claim success if the song still feels like one good 4-second loop plus empty space
|
||||
- no pianos
|
||||
- no piano audio loops
|
||||
- no `HARMONY_PIANO_MIDI`
|
||||
- no piano-roll strategy based on piano timbre
|
||||
|
||||
OpenCode must also remember:
|
||||
|
||||
- harmonic support is still required
|
||||
- but it must be implemented with non-piano timbres
|
||||
- use pluck, synth, keys-like non-piano textures, pads or other coherent harmonic roles from the library
|
||||
- do not reinterpret "harmony" as permission to add piano
|
||||
|
||||
This rule is absolute for this sprint:
|
||||
|
||||
- if OpenCode adds piano, it failed the requirement
|
||||
|
||||
---
|
||||
|
||||
## 8. Minimum Report Format For OpenCode
|
||||
|
||||
Every song-generation answer must include:
|
||||
|
||||
1. which MCP tools were used
|
||||
2. whether generation was sync or async
|
||||
3. session id
|
||||
4. validation result
|
||||
5. diagnosis result
|
||||
6. short honest statement of whether the song is actually usable
|
||||
|
||||
If any of those are missing, the result is below standard.
|
||||
|
||||
The report must also state explicitly:
|
||||
|
||||
- whether MCP-first was used
|
||||
- whether Python or shell recovery was needed
|
||||
- whether any piano asset or piano MIDI role was used
|
||||
|
||||
If piano appears, the report must mark that as a failure.
|
||||
|
||||
---
|
||||
|
||||
## 9. What OpenCode Must Do Next
|
||||
|
||||
On the next real song request, OpenCode must:
|
||||
|
||||
1. use MCP immediately
|
||||
2. use `generate_song_async` as the default full-song path
|
||||
3. handle timeout by inspecting state, not panicking
|
||||
4. validate the result every time
|
||||
5. report the actual session truth, not assumptions
|
||||
6. avoid all piano material
|
||||
7. use Python or Bash only as a recovery or verification path, not as a substitute for MCP song generation
|
||||
|
||||
This sprint is complete only when OpenCode behaves like an operator of the system, not a spectator of the system.
|
||||
Reference in New Issue
Block a user