# CLAUDE.md - AbletonMCP_AI v2.0

> **Canonical project context** for AI agents.
> Read this BEFORE doing any work.

## CRITICAL RULES

1. **NEVER touch `libreria/` or `librerias/`** - User's 509 reggaeton samples.
2. **NEVER delete project files** - Overwrite only.
3. **NEVER create debug .md files in project root** - All in `AbletonMCP_AI/docs/`.
4. **ALWAYS compile after changes**: `python -m py_compile "<file_path>"`
5. **ALWAYS restart Ableton** after changes to `__init__.py`.
6. **Use PowerShell, absolute Windows paths**.

## Architecture

```
AbletonMCP_AI/
├── __init__.py          # Remote Script (all-in-one, ~300 lines)
├── README.md            # Documentation
├── docs/                # Sprints
└── mcp_server/
    ├── server.py        # MCP server (~300 lines)
    └── engines/         # Music logic
```

## How It Works

1. **Ableton** loads `__init__.py` as a Control Surface
2. **Remote Script** starts TCP server on port 9877
3. **MCP Server** (FastMCP over stdio) connects to Ableton via TCP
4. **OpenCode/opencode** sends tool calls to MCP Server via stdio

## Workflow

- **Kimi** codes fast, implements features
- **Qwen** verifies, compiles, debugs, creates next sprint
- Sprints saved to `docs/`