Sync: Complete project state with all MEGA SPRINT V1-V3 features and Codex stubs
This commit is contained in:
renato97
199
CLAUDE.md
Normal file
199
CLAUDE.md
Normal file
@@ -0,0 +1,199 @@
|
||||
# CLAUDE.md
|
||||
|
||||
Canonical project context for AI agents working in this repository.
|
||||
|
||||
Read this file after `AGENTS.md` and before doing substantial work.
|
||||
|
||||
## Mission
|
||||
|
||||
The repository exists to control Ableton Live 12 through MCP and a Remote Script so an AI agent can:
|
||||
|
||||
- inspect the current Live set
|
||||
- create and edit tracks and clips
|
||||
- generate arrangements when needed
|
||||
- edit already-open `.als` projects
|
||||
- retrieve local samples and references
|
||||
- leave the final result audible, editable, and stable
|
||||
|
||||
This project is judged by runtime truth in Ableton, not by pretty manifests or optimistic reports.
|
||||
|
||||
## Current Operating Mode
|
||||
|
||||
The preferred workflow is currently manual:
|
||||
|
||||
- Codex reviews and fixes
|
||||
- Kimi/OpenCode or GLM/OpenCode implement coding tasks
|
||||
- tasks are handed off via markdown
|
||||
- blind background autopilot is not the default working mode
|
||||
|
||||
There is automation code under `ralph\`, but do not assume it is the active workflow unless the task explicitly says so.
|
||||
|
||||
## Current Product Direction
|
||||
|
||||
The center of gravity has shifted from "generate a whole song from scratch" to:
|
||||
|
||||
- edit the currently open Live project
|
||||
- improve coherence and continuity
|
||||
- reduce silent holes and rigid visual symmetry
|
||||
- keep harmonic material alive across the arrangement
|
||||
- blend library audio with harmonic MIDI when useful
|
||||
- avoid automatic vocals
|
||||
|
||||
Important nuance:
|
||||
|
||||
- "piano roll" means harmonic MIDI is acceptable and desired
|
||||
- it does not mean the arrangement should be forced toward piano timbres
|
||||
|
||||
## Active Paths
|
||||
|
||||
User-facing project root:
|
||||
|
||||
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts`
|
||||
|
||||
Active code root:
|
||||
|
||||
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI`
|
||||
|
||||
Current open-project target:
|
||||
|
||||
- `C:\Users\ren\Desktop\song Project\song.als`
|
||||
|
||||
Active MCP and runtime entrypoints:
|
||||
|
||||
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py`
|
||||
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\.mcp.json`
|
||||
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\opencode.json`
|
||||
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\abletonmcp_init.py`
|
||||
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\abletonmcp_runtime.py`
|
||||
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py`
|
||||
|
||||
## Mandatory Questions Before Patching
|
||||
|
||||
1. Which file is the active entrypoint?
|
||||
2. Which layer owns the bug?
|
||||
3. Can the bug be reproduced with logs, MCP calls, tests, or Live inspection?
|
||||
4. How will you prove the fix after the patch?
|
||||
|
||||
If those answers are weak, the patch will likely be weak.
|
||||
|
||||
## The Three Layers
|
||||
|
||||
Keep them separate in your head:
|
||||
|
||||
1. MCP transport and public tool layer
|
||||
2. socket protocol or runtime bridge
|
||||
3. Ableton Remote Script or Live API layer
|
||||
|
||||
Many bad fixes happened because someone patched the wrong layer.
|
||||
|
||||
## Source Of Truth Rules
|
||||
|
||||
Use this order of trust:
|
||||
|
||||
1. current Live state
|
||||
2. MCP responses and exact tool calls
|
||||
3. Ableton log
|
||||
4. code
|
||||
5. old sprint reports
|
||||
|
||||
Do not trust a report that says `COMPLETED` if Live still shows an empty or repetitive arrangement.
|
||||
|
||||
## Working Rules
|
||||
|
||||
- Use PowerShell, not bash.
|
||||
- Use absolute Windows paths in scripts and docs.
|
||||
- Compile changed Python files before runtime testing.
|
||||
- Keep Live mutations short and explicit.
|
||||
- Prefer inspection first, mutation second.
|
||||
- Do not turn every issue into a new architecture.
|
||||
- Do not patch backup trees first.
|
||||
|
||||
## Runtime Validation Checklist
|
||||
|
||||
At minimum, after meaningful runtime changes check:
|
||||
|
||||
- `get_session_info`
|
||||
- `get_tracks`
|
||||
- the relevant inspection tool for the edited object
|
||||
- Ableton log if anything hangs or times out
|
||||
|
||||
If the task is about editing the open project:
|
||||
|
||||
- inspect the edited tracks, clips, and devices after mutation
|
||||
- capture before and after evidence
|
||||
- do not rely on manifest-only proof
|
||||
|
||||
## Build / Test Commands
|
||||
|
||||
Compile common active files:
|
||||
|
||||
```powershell
|
||||
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py"
|
||||
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\abletonmcp_init.py"
|
||||
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\abletonmcp_runtime.py"
|
||||
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py"
|
||||
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\song_generator.py"
|
||||
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\reference_listener.py"
|
||||
```
|
||||
|
||||
Run targeted tests:
|
||||
|
||||
```powershell
|
||||
python -m unittest discover "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests"
|
||||
python -m pytest "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_runtime_truth.py"
|
||||
python -m unittest "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_runtime_truth.py.TestRuntimeTruthHelpers.test_public_set_device_parameter_supports_parameter_name"
|
||||
```
|
||||
|
||||
Useful diagnostics:
|
||||
|
||||
```powershell
|
||||
Get-Content "C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Log.txt" -Tail 120
|
||||
netstat -an | findstr 9877
|
||||
opencode mcp list --print-logs
|
||||
```
|
||||
|
||||
## Known Current Reality
|
||||
|
||||
- MCP connection can be healthy even when an arrangement edit path is still broken.
|
||||
- The repo already contains a lot of tooling for project inspection and partial project editing.
|
||||
- Open-project editing is the next quality frontier, not just raw generation.
|
||||
- Harmonic MIDI often exists conceptually before it is truly materialized in Arrangement; validate that distinction carefully.
|
||||
- The repo has drifted before into overly symmetrical, silent, loopy arrangements; current tasks should fight that.
|
||||
|
||||
## High-Value Files
|
||||
|
||||
- `AGENTS.md`
|
||||
- `CLAUDE.md`
|
||||
- `KIMI_K2_START_HERE.md`
|
||||
- `KIMI_K2_ACTIVE_HANDOFF.md`
|
||||
- `docs\PROJECT_AUDIT_song_2026-04-03.md`
|
||||
- `mcp_wrapper.py`
|
||||
- `abletonmcp_init.py`
|
||||
- `AbletonMCP_AI\abletonmcp_runtime.py`
|
||||
- `AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py`
|
||||
- `AbletonMCP_AI\AbletonMCP_AI\MCP_Server\song_generator.py`
|
||||
- `AbletonMCP_AI\AbletonMCP_AI\MCP_Server\reference_listener.py`
|
||||
|
||||
## What Good Looks Like Now
|
||||
|
||||
A strong result in the current phase looks like this:
|
||||
|
||||
- the open project remains stable
|
||||
- MCP tools can inspect and edit meaningful parts of the set
|
||||
- harmonic backbone exists in Arrangement, not only in Session or metadata
|
||||
- fewer structural gaps
|
||||
- less rigid mirrored repetition
|
||||
- sound choices feel coherent but not trapped in 3 identical loops forever
|
||||
- the project is easier to continue editing by hand afterward
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- claiming success from reports alone
|
||||
- calling every harmonic MIDI lane "piano" and forcing piano presets
|
||||
- overvaluing manifest metrics when Live still sounds wrong
|
||||
- using old or backup files as the first patch target
|
||||
- treating a timeout as definitive proof of failure without inspecting Live
|
||||
|
||||
## Practical Reminder
|
||||
|
||||
If a user says "this doesn't look or sound like a song," that feedback outranks a self-congratulatory validation report.
|
||||
Reference in New Issue
Block a user