# 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.
