ableton-mcp-ai/docs/ROADMAP.md

# Roadmap

Documento canonico de roadmap para el repo publicado.

Ultima revision: 2026-03-30

## Vision

Llevar el proyecto desde "MCP funcional con generacion usable" a "herramienta de produccion seria para Arrangement View", con estos pilares:

- conexion Ableton <-> MCP estable
- seleccion musical coherente por pack, seccion y rol
- generacion larga sin timeouts ni cuelgues
- ciclo de critica y reroll sobre audio real
- flujo reproducible para Claude Code, Codex y opencode

## Estado actual

### Ya resuelto (Sprint Granular v0.1.40 - 2026-04-05)

- Wrapper MCP estable por `stdio`.
- Remote Script visible como `AbletonMCP_AI`.
- Runtime canonico funcional.
- Fallback de audio materializado en Arrangement.
- Jobs async basicos para generacion.
- `pack_brain` y jueces externos integrados.
- Documentacion base publicada en el repo.
- **Sprint Granular completado:**
  - T018-T043: Spectral engine y sintesis granular
  - T072-T077: FX automation (filter sweeps, reverb tails, pitch risers)
  - T079-T087: Gain staging y calibracion de buses
  - T086-T094: Arrangement intelligence (estructura reggaeton)
  - T101-T106: Bus routing y validacion de routing
  - T121-T135: Melody generator procedural
  - T185-T200: Testing y documentacion completa

### Todavia flojo

- La coherencia musical aun depende demasiado de heuristicas y de la zona fuerte de la libreria.
- `generate_song` sigue siendo costoso y en algunos clientes expira si no se usa el camino async.
- La automatizacion real dentro de Live sigue incompleta.
- El sistema no renderiza, escucha y rerrollea automaticamente.

## Prioridad real

Si el objetivo es calidad profesional, el orden correcto de trabajo no es "mas tools", sino este:

1. Estabilidad de sesion y runtime
2. Coherencia musical y groove
3. Critica cerrada con audio real
4. Automatizacion y arreglo fino
5. Mix/master y experiencia de publicacion

## Fase 1 - v0.1.1 Estabilizacion dura

Objetivo: que generar no rompa el flujo.

### Tareas

- arreglar `clear_all_tracks` para que limpie la sesion sin error blando
- unificar `abletonmcp_init.py` y `AbletonMCP_AI/abletonmcp_runtime.py`
- corregir respuestas viejas del transporte (`start_playback`, estado de reproduccion)
- poner backoff + retry + cache local a jueces Z.ai
- dejar `generate_song_async` como camino principal y documentado
- sanear errores de automatizacion para que no ensucien el resultado

### Criterio de salida

- 10 generaciones seguidas sin crash de Live
- sin timeouts falsos en el camino async
- limpieza de sesion reproducible

## Fase 2 - v0.2.0 Coherencia musical

Objetivo: que el track deje de sentirse "armado con piezas correctas" y empiece a sonar como una sola produccion.

### Tareas

- reforzar seleccion same-pack para `bass/music/fx/vocal`
- endurecer `atmos_fx`, `vocal_shot`, `fill_fx`, `snare_roll`
- hacer seleccion por seccion, no solo por rol global
- extraer groove real de dembow desde loops de referencia
- convertir la referencia en `micro stems` y luego en `phrase plan`
- enlazar audio families con `MIDI/presets` armonicos de la misma libreria
- hacer scoring de parejas y ternas:
  - `kick + clap + hats`
  - `bass + synth`
  - `vocal + fx + atmos`

### Criterio de salida

- 3 generaciones seguidas que mantengan identidad sonora clara
- menos reemplazos manuales de samples al revisar el set

## Fase 3 - v0.3.0 Critica cerrada

Objetivo: que el sistema no entregue el primer intento ciego.

### Tareas

- render corto por bloque de 8 o 16 barras
- analisis automatico del render:
  - energia
  - densidad
  - low-end
  - brillo
  - estabilidad ritmica
- reroll por seccion si el score cae debajo de threshold
- persistir score, manifest y motivos de rechazo

### Criterio de salida

- cada generacion pasa por al menos una etapa de escucha automatica
- el sistema descarta combinaciones flojas sin intervencion manual

## Fase 4 - v0.4.0 Automatizacion y arreglo fino

Objetivo: que el set tenga respiracion y dinamica real en Arrangement.

### Tareas

- implementar escritura de automatizacion real en el runtime
- volumen, filtro, reverb y transiciones por seccion
- markers y loops consistentes para navegar el track
- fills mas musicales en build y salida de drop
- variacion de secciones A/B, no solo repeticion lineal

### Criterio de salida

- intro, build, drop, break y outro con comportamiento distinto y verificable
- menos necesidad de editar a mano volumen/fx despues de generar

## Fase 5 - v0.5.0 Mix y mastering operativo

Objetivo: que el set salga mas cerca de una premezcla util.

### Tareas

- gain staging mas consistente por bus
- chequeos de headroom, LUFS y clipping
- revision de sends y routing por bus
- presets de master por objetivo:
  - club
  - demo
  - streaming

### Criterio de salida

- exportes mas previsibles
- menos correccion manual de niveles en la sesion

## Fase 6 - v1.0.0 Produccion asistida seria

Objetivo: workflow de productor, no solo demo generativa.

### Tareas

- memoria de gustos por rating real
- render + comparacion contra referencias
- historial de decisiones por generacion
- presets de estilo por artista/subescena
- release workflow con stems, manifests y reportes

## Proximo sprint recomendado (Post-Granular v0.1.40)

El Sprint Granular ha sido completado. Proximos pasos:

1. ~~`clear_all_tracks` y limpieza de sesion~~ (Completado)
2. ~~backoff/cache de Z.ai~~ (Completado)
3. ~~same-pack strict para `atmos_fx` y `vocal_shot`~~ (Mejorado con spectral engine)
4. ~~groove extraction desde drum loops dembow~~ (Completado en arrangement_intelligence)
5. ~~smoke test automatizado de generacion async~~ (Completado)

**Siguiente sprint (v0.1.41):**
1. Optimizacion de cache espectral para librerias >10K samples
2. Integracion avanzada con reference_listener
3. Generacion de melodias con ML
4. Mejoras en GUI de Ableton para feedback visual

## Regla de trabajo

No agregar nuevas tools grandes hasta cerrar estas cuatro bases:

- estabilidad
- coherencia
- critica
- automatizacion