Files

renato97 7bcd8052a9 docs: LLM-ready documentation suite — LLM_CONTEXT.md, module deep-dives, JSON schemas, CLI reference

Complete documentation system for LLM consumption: primary LLM_CONTEXT.md
(27KB system overview), 4 module deep-dives (composer, reaper-builder,
reaper-scripting, calibrator), 2 JSON Schema draft-07 contracts, CLI
reference, and README correction (FL Studio -> REAPER identity).

2026-05-04 10:30:24 -03:00

3.7 KiB

Raw Blame History

llm-docs Specification

Purpose

Documentation-only capability. Defines 9 LLM-ready files that ground any LLM in the REAPER .rpp generation system. Zero code changes — all artifacts are additive under docs/ plus a README rewrite.

Requirements

Requirement: LLM_CONTEXT.md Aggregates System Knowledge

docs/LLM_CONTEXT.md MUST be a single entry-point file under 40KB that an LLM can read to understand the entire system. Content MUST include: system description, ASCII architecture diagram, all dataclass definitions from src/core/schema.py, module index mapping each src/ directory to its role, pipeline steps (compose → build → calibrate → validate), plugin system (PLUGIN_REGISTRY, ALIAS_MAP, presets), ReaScript protocol, CLI reference for scripts/compose.py, scripts/generate.py, scripts/run_in_reaper.py, naming conventions, and extension guide. File MUST be valid markdown.

Scenario: LLM grounds from LLM_CONTEXT.md alone

GIVEN an LLM with no prior knowledge of fl_control
WHEN it reads docs/LLM_CONTEXT.md
THEN it identifies REAPER .rpp as the target format, understands SongDefinition → TrackDef → ClipDef as the core data model, knows module layout under src/, and locates CLI entry points
AND the file is under 40KB valid markdown with all required sections present

Requirement: Module Deep-Dives Enable Targeted Modification

Each module doc under docs/modules/ MUST document: public API signatures with types, data flow in/out, dependencies, and known gotchas. Each MUST reference LLM_CONTEXT.md as parent.

Scenario: LLM modifies a module after reading its deep-dive

GIVEN docs/modules/reaper-builder.md exists
WHEN an LLM reads it
THEN it identifies RPPBuilder, PLUGIN_REGISTRY format (key → display_name, filename, uid_guid), write() signature, and dependency on src/core/schema.py

Requirement: JSON Schemas Match Dataclass Definitions

docs/schemas/song-definition.json MUST be JSON Schema draft-07 matching every field in SongDefinition, SongMeta, TrackDef, ClipDef, MidiNote, SectionDef, PluginDef, PatternDef, ArrangementItemDef, CCEvent as defined in src/core/schema.py. docs/schemas/reascript-protocol.json MUST match ReaScriptCommand and ReaScriptResult in src/reaper_scripting/commands.py. Field names, types, and required/optional flags MUST match the dataclass source exactly.

Scenario: Schema validates SongDefinition instance

GIVEN a SongDefinition serialized via to_json()
WHEN validated against song-definition.json
THEN zero schema violations; every field name, type, and required constraint matches the dataclass

Requirement: README.md Reflects True System Identity

README.md MUST NOT reference FL Studio, .flp files, or MCP server. MUST reference REAPER .rpp generation, list real CLI entry points (compose.py, generate.py, run_in_reaper.py), and point to docs/LLM_CONTEXT.md.

Scenario: New developer reads README

GIVEN a developer reading README.md
THEN they see "REAPER", ".rpp", and docs/LLM_CONTEXT.md
AND they see NO mention of "FL Studio", ".flp", or "MCP"

Requirement: Cross-Reference Integrity

All internal markdown links in docs MUST resolve to existing files or headings. Module names in docs MUST match actual Python module names under src/. Dataclass field names in docs MUST match src/core/schema.py exactly.

Scenario: Links resolve and names match code

GIVEN all doc files under docs/
WHEN an LLM or human follows every [link](./path) reference
THEN every link resolves; no broken cross-references exist
AND all module and field names match their definitions in code

3.7 KiB Raw Blame History