# 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

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

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

Si seguimos ahora, el sprint correcto es:

1. `clear_all_tracks` y limpieza de sesion
2. backoff/cache de Z.ai
3. same-pack strict para `atmos_fx` y `vocal_shot`
4. groove extraction desde drum loops dembow
5. un smoke test automatizado de generacion async

## Regla de trabajo

No agregar nuevas tools grandes hasta cerrar estas cuatro bases:

- estabilidad
- coherencia
- critica
- automatizacion