# REGLAS DEL PROYECTO AbletonMCP_AI v2.0

> **OBLIGATORIO**: Estas reglas se aplican ANTES de cada cambio en el proyecto.

## 🚫 PROHIBIDO (NUNCA HACER)

1. **NO tocar `libreria/` ni `librerias/`** - Son las samples del usuario. NUNCA borrar, mover ni modificar nada ahí.
2. **NO borrar archivos del proyecto actual** - Si hay que reemplazar algo, hacer overwrite, no delete + create.
3. **NO crear archivos .md de debugging** en la raíz del proyecto - Todo va a `AbletonMCP_AI/docs/`.
4. **NO usar `rmdir /s /q` en carpetas que no sean `__pycache__`** - Se puede borrar todo el proyecto por error.
5. **NO modificar scripts de Ableton que no sean AbletonMCP_AI** - Las carpetas `_Framework`, `_APC`, etc. son de Ableton.

## ✅ OBLIGATORIO (SIEMPRE HACER)

1. **Compilar después de cada cambio**:
   ```powershell
   python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\__init__.py"
   python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\mcp_server\server.py"
   ```

2. **Los sprints van a `docs/`** - Cada sprint se guarda en `AbletonMCP_AI/docs/sprint_N_descripcion.md`.

3. **Usar paths absolutos de Windows** en todos los comandos y scripts.

4. **Usar PowerShell**, no bash. Los comandos son `cmd.exe` compatible.

5. **Reiniciar Ableton Live** después de cambios en `__init__.py` - El Remote Script se carga al inicio y no se puede hot-reload.

## 📁 ESTRUCTURA DEL PROYECTO

```
MIDI Remote Scripts/
├── AbletonMCP_AI/
│   ├── __init__.py          # Entry point (TODO el código de Live)
│   ├── README.md            # Documentación principal
│   ├── docs/                # Sprints y docs del proyecto
│   │   └── WORKFLOW.md      # Flujo Qwen + Kimi
│   └── mcp_server/
│       ├── server.py        # MCP FastMCP server
│       └── engines/         # Lógica musical
│           ├── sample_selector.py
│           └── song_generator.py
├── mcp_wrapper.py           # Launcher del MCP server
├── libreria/reggaeton/      # 509 samples del usuario (NO TOCAR)
└── librerias/               # Samples organizados (NO TOCAR)
```

## 🔧 ARQUITECTURA

### Remote Script (`__init__.py`)
- **Todo en un solo archivo** - Ableton solo lee `__init__.py` para descubrir el script.
- **No hacer imports de módulos externos** - Pone todo el código acá adentro.
- **Socket TCP en puerto 9877** - Un thread escucha, cada comando abre conexión nueva.
- **`update_display()` drena tareas** - Las mutaciones de Live van a `_pending_tasks` y se ejecutan en `update_display()`.

### MCP Server (`mcp_server/server.py`)
- **FastMCP sobre stdio** - Se comunica con opencode via stdin/stdout.
- **Cada tool llama a `_send_to_ableton()`** - Abre socket, envía comando JSON, cierra.
- **Timeouts por tipo de comando** - Info: 5s, Mutación: 10-15s, Generación: 300s.

## 🧪 TESTING

Después de cada cambio:
1. `python -m py_compile <archivo_modificado>`
2. Si es `__init__.py` → reiniciar Ableton
3. Probar con `get_session_info` → debe responder sin timeout

## 🤝 FLUJO QWEN + KIMI

- **Kimi** codea rápido, implementa features
- **Qwen** verifica, compila, debuggea, arregla, crea siguiente sprint
- Los sprints se guardan en `docs/`
- Qwen decide la arquitectura y el próximo paso