livepilot 1.9.16 → 1.9.17

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "livepilot",
       "description": "Agentic production system for Ableton Live 12 — 236 tools, 32 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
-      "version": "1.9.16",
+      "version": "1.9.17",
       "author": {
         "name": "Pilot Studio"
       },

package/AGENTS.md

@@ -1,4 +1,4 @@
-# LivePilot v1.9.16 — Ableton Live 12
+# LivePilot v1.9.17 — Ableton Live 12
 
 ## Project
 - **Repo:** This directory (LivePilot)

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 1.9.17 — Skills Architecture V2 (April 2026)
+
+### Skills (9 new, 1 slimmed)
+- **livepilot-core** — slimmed from 900 to ~150 lines. Golden rules, speed tiers, error protocol. Domain content moved to dedicated skills.
+- **livepilot-devices** — NEW: device loading, browser workflow, plugin health, rack introspection
+- **livepilot-notes** — NEW: MIDI content, theory integration, generative algorithms, harmony tools
+- **livepilot-mixing** — NEW: volume/pan/sends, routing, metering, automation patterns
+- **livepilot-arrangement** — NEW: song structure, scenes, arrangement view, navigation
+- **livepilot-mix-engine** — NEW: critic-driven mix analysis loop (masking, dynamics, stereo, headroom)
+- **livepilot-sound-design-engine** — NEW: critic-driven patch refinement loop (static timbre, modulation, filtering)
+- **livepilot-composition-engine** — NEW: section analysis, transitions, motifs, form, translation checking
+- **livepilot-performance-engine** — NEW: safety-first live performance with energy tracking and move classification
+- **livepilot-evaluation** — NEW: universal before/after evaluation loop with capability-aware scoring
+
+### Commands (3 new, 2 updated)
+- `/arrange` — NEW: guided arrangement using composition engine
+- `/perform` — NEW: safety-constrained performance mode
+- `/evaluate` — NEW: before/after evaluation loop
+- `/mix` — updated to use mix engine critics
+- `/sounddesign` — updated to use sound design engine critics
+
+### Agent
+- **livepilot-producer** — updated to reference all 10 skills instead of inline loop definitions
+
+### Plugin Stats
+- 11 skills (was 2), 8 commands (was 5), 1 agent, 10 reference files for engine skills
+- Total plugin skill metadata: ~1100 words always-in-context (lean triggers)
+- Progressive disclosure: SKILL.md bodies ≤2000 words each, detailed content in references/
+
 ## 1.9.16 — Comprehensive Bug Fix Audit (April 2026)
 
 ### Critical Fixes

package/livepilot/.Codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "livepilot",
-  "version": "1.9.16",
+  "version": "1.9.17",
   "description": "Agentic production system for Ableton Live 12 — 236 tools, 32 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
   "author": {
     "name": "Pilot Studio"

package/livepilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "livepilot",
-  "version": "1.9.16",
+  "version": "1.9.17",
   "description": "Agentic production system for Ableton Live 12 — 236 tools, 32 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
   "author": {
     "name": "Pilot Studio"

package/livepilot/agents/livepilot-producer/AGENT.md

@@ -269,9 +269,23 @@ Every move you make is tracked in the action ledger. Call `get_last_move` to rev
 
 The system tracks what the user dislikes. Call `get_anti_preferences` before planning — if the user has repeatedly undone brightness increases, don't suggest them.
 
+## Skills Reference
+
+Load the appropriate skill for domain-specific guidance:
+- **livepilot-core** — golden rules, speed tiers, error handling (always relevant)
+- **livepilot-devices** — loading/browsing/configuring devices
+- **livepilot-notes** — MIDI content, theory, generative algorithms
+- **livepilot-mixing** — volume, pan, sends, routing, automation
+- **livepilot-arrangement** — song structure, scenes, arrangement view
+- **livepilot-mix-engine** — critic-driven mix analysis loop
+- **livepilot-sound-design-engine** — critic-driven patch refinement loop
+- **livepilot-composition-engine** — section analysis, transitions, form
+- **livepilot-performance-engine** — live performance safety constraints
+- **livepilot-evaluation** — universal before/after evaluation loop
+
 ## Rules
 
-- Always use the livepilot-core skill for tool usage guidance
+- Load relevant skills before starting domain-specific work
 - Use `build_project_brain` for complex tasks instead of ad-hoc state queries
 - Check `get_capability_state` before trusting analyzer data
 - **Verify every track produces sound** — non-negotiable

package/livepilot/commands/arrange.md

@@ -0,0 +1,19 @@
+---
+name: arrange
+description: Guided arrangement — build song structure with sections, transitions, and energy flow
+---
+
+Guide the user through arranging their session into a full song structure.
+
+1. **Read the session** — `get_session_info` to see all tracks and clips
+2. **Analyze current structure** — `get_section_graph` to see inferred sections from scene names. If no sections, `get_scenes_info` for raw scene data.
+3. **Ask about the target structure** — what form? (verse-chorus, AABA, build-drop, through-composed). What energy arc? (gradual build, peaks and valleys, flat)
+4. **Plan the arrangement** — `plan_arrangement` with the target structure. Review the proposed section order and transitions.
+5. **Build sections** — for each section, create or duplicate scenes, set scene names and colors. Use `duplicate_scene` for variations.
+6. **Check transitions** — `analyze_transition(from_section, to_section)` for each adjacent pair. `score_transition` to evaluate quality.
+7. **Plan weak transitions** — `plan_transition` for any scored below 0.6. Execute the suggested gestures (filter sweeps, energy ramps, rhythmic fills).
+8. **Check emotional arc** — `get_emotional_arc` to verify the energy flow matches the target.
+9. **Translation check** — `check_translation` to verify mono compatibility and spectral consistency across sections.
+10. **Record to arrangement** — when the user is happy, guide them through `back_to_arranger` and recording the session performance to the timeline.
+
+Use the livepilot-composition-engine skill for section analysis and transition planning. Present the arrangement as a visual timeline to the user.

package/livepilot/commands/evaluate.md

@@ -0,0 +1,39 @@
+---
+name: evaluate
+description: Evaluate recent changes — run the full before/after evaluation loop and recommend keep or undo
+---
+
+Run the universal evaluation loop on recent production changes.
+
+1. **Check capability state** — `get_capability_state` to see what evaluation modes are available:
+   - `normal` — full measured evaluation with analyzer data
+   - `measured_degraded` — analyzer online but stale data
+   - `judgment_only` — no analyzer, parameter-level heuristics only
+   - `read_only` — session disconnected
+
+2. **Get the last move** — `get_last_move` to understand what was changed. If no recent move, `get_recent_actions` for history.
+
+3. **Ask what the goal was** — what were they trying to achieve? More clarity? Wider stereo? Punchier drums?
+
+4. **Compile the goal** — `compile_goal_vector(goal_description, mode="improve")`
+
+5. **Capture current state** — `get_master_spectrum` + `get_master_rms` + `get_mix_snapshot`
+
+6. **Undo the change** — `undo()` to restore the before state
+
+7. **Capture before state** — same reads as step 5
+
+8. **Redo the change** — `redo()` to restore the after state
+
+9. **Evaluate** — `evaluate_move(before_snapshot, after_snapshot, goal)` or use engine-specific:
+   - Mix changes: `evaluate_mix_move`
+   - Composition changes: `evaluate_composition_move`
+   - Multi-dimensional: `evaluate_with_fabric`
+
+10. **Report results** — show: score (0-1), keep_change recommendation, goal_progress, collateral_damage, dimension changes
+
+11. **Act on recommendation:**
+    - If `keep_change=true` — keep, suggest `memory_learn` if score > 0.7
+    - If `keep_change=false` — `undo()`, explain why (collateral damage, goal regression)
+
+Use the livepilot-evaluation skill for the full evaluation loop details.

package/livepilot/commands/mix.md

@@ -7,9 +7,14 @@ Help the user mix their session. Follow these steps:
 
 1. **Read the session** — `get_session_info` to see all tracks
 2. **Analyze each track** — `get_track_info` for clip and device details, check current volume/pan
-3. **Suggest a mix** — propose volume levels, panning positions, and send amounts based on the track types and instruments
-4. **Apply with confirmation** — only change levels after the user approves each suggestion
-5. **Check return tracks** — `get_return_tracks` to see shared effects
-6. **Master chain** — `get_master_track` to review the master
+3. **Quick mix status** — `get_mix_summary` for a fast overview (track count, dynamics, stereo, issues)
+4. **Run critics** — `get_mix_issues` to detect problems (masking, dynamics, stereo width, headroom)
+5. **Suggest a mix** — propose volume levels, panning positions, and send amounts based on the track types, instruments, and detected issues
+6. **Apply with confirmation** — only change levels after the user approves each suggestion
+7. **Check return tracks** — `get_return_tracks` to see shared effects
+8. **Master chain** — `get_master_track` to review the master
+9. **Evaluate** — after changes, `evaluate_mix_move` with before/after snapshots to verify improvement
 
 Present suggestions in a clear table format. Always explain the reasoning (e.g., "panning the hi-hats slightly right to create stereo width"). Use `undo` if the user doesn't like a change.
+
+For deeper critic-driven iterative improvement, use the livepilot-mix-engine skill.

package/livepilot/commands/perform.md

@@ -0,0 +1,30 @@
+---
+name: perform
+description: Performance mode — enter a safety-constrained live performance context with energy tracking and safe moves
+---
+
+Enter performance mode for live set support. All actions are constrained to safe and caution-level moves only.
+
+1. **Get performance state** — `get_performance_state` to see scene roles, energy levels, and current position
+2. **Show the dashboard** — present: current scene, energy level, energy direction (up/down/hold), available safe moves
+3. **Get safe moves** — `get_performance_safe_moves` for what can be done right now
+4. **Check before acting** — `check_safety(move_type)` before every action. Only execute safe or caution moves. Caution moves require user confirmation.
+
+**BLOCKED during performance** (never execute, warn if requested):
+- Creating or deleting tracks, clips, or scenes
+- Editing notes or arrangement
+- Adding or removing devices (device chain surgery)
+
+**SAFE moves** (execute freely):
+- Scene launches, mute/unmute, volume nudges, send adjustments, macro tweaks, filter sweeps
+
+**Scene transitions:**
+- `plan_scene_handoff(from_scene, to_scene)` — generates an energy path and gesture sequence
+- Follow the energy path: if going up, suggest high-energy scenes; if going down, suggest breakdowns
+
+**Always show:**
+- Current energy level and direction
+- What moves are available
+- What moves are blocked and why
+
+Use the livepilot-performance-engine skill for safety classification and move suggestions.

package/livepilot/commands/sounddesign.md

@@ -6,12 +6,17 @@ description: Sound design workflow — load instruments and effects, shape param
 Guide the user through designing a sound. Follow these steps:
 
 1. **Ask about the target sound** — what character? (warm pad, aggressive bass, shimmering lead, atmospheric texture, etc.)
-2. **Choose an instrument** — pick the right synth for the job, load it with `find_and_load_device`
+2. **Choose an instrument** — pick the right synth for the job, load it with `search_browser` → `load_browser_item`
 3. **Verify device loaded** — `get_device_info` to confirm plugin initialized (AU/VST with `parameter_count` <= 1 = dead plugin — delete and replace with native alternative)
 4. **Get parameters** — `get_device_parameters` to see what's available
 5. **Shape the sound** — `set_device_parameter` or `batch_set_parameters` to dial in the character
-6. **Add effects** — load effects (reverb, delay, chorus, distortion, etc.) and tweak their parameters
-7. **Create a test pattern** — `create_clip` + `add_notes` with a simple pattern to audition
-8. **Fire the clip** to listen, iterate based on feedback
+6. **Run critics** — `analyze_sound_design(track_index)` to check for static timbre, missing modulation, spectral imbalance
+7. **Address issues** — `plan_sound_design_move(track_index)` for suggested improvements
+8. **Add effects** — load effects (reverb, delay, chorus, distortion, etc.) and tweak their parameters
+9. **Create a test pattern** — `create_clip` + `add_notes` with a simple pattern to audition
+10. **Fire the clip** to listen, iterate based on feedback
+11. **Evaluate** — `evaluate_move(engine="sound_design")` with before/after to verify improvement
 
 Explain what each parameter does as you adjust it. Use `undo` liberally if something sounds wrong.
+
+For iterative critic-driven patch refinement, use the livepilot-sound-design-engine skill.

package/livepilot/skills/livepilot-arrangement/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: livepilot-arrangement
+description: This skill should be used when the user asks to "arrange", "structure a song", "add an intro", "build a verse", "create sections", "scene to arrangement", "cue points", "record to arrangement", or wants to organize song structure in Ableton Live.
+---
+
+# Arrangement — Song Structure and Session Organization
+
+Organize clips into scenes, build arrangements on the timeline, navigate with cue points, and record performances in Ableton Live.
+
+## Session View vs Arrangement View
+
+Ableton has two complementary views:
+
+- **Session view** — a grid of clip slots organized by track (columns) and scene (rows). Clips loop independently. Fire scenes to trigger rows of clips simultaneously. Use for jamming, live performance, and building ideas.
+- **Arrangement view** — a linear timeline where clips play in sequence from left to right. Use for final song structure, recording automation, and export.
+
+Use `back_to_arranger` to switch from session playback to arrangement playback. When session clips are playing, they override arrangement content on their tracks.
+
+## Scene Workflow
+
+Scenes are horizontal rows in session view. Each scene can trigger all its clips at once.
+
+### Creating and Managing Scenes
+
+- `create_scene(index)` — insert a new scene at the given position
+- `set_scene_name(scene_index, name)` — name scenes after song sections: "Intro", "Verse 1", "Chorus", "Bridge", "Drop", "Outro"
+- `set_scene_color(scene_index, color_index)` — color-code sections (0-69 palette). Use consistent colors: green for verses, red for choruses, blue for bridges.
+- `set_scene_tempo(scene_index, tempo)` — set a per-scene tempo change (triggers when scene fires)
+- `duplicate_scene(scene_index)` — copy a scene for variations. Duplicate, rename, then modify clips in the copy.
+- `delete_scene(scene_index)` — remove a scene
+
+### Firing and Monitoring
+
+- `fire_scene(scene_index)` — launch all clips in a scene simultaneously
+- `fire_scene_clips(scene_index)` — launch only the clips that exist in a scene (skips empty slots)
+- `stop_all_clips` — stop everything in session view
+- `get_playing_clips` — see which clips are currently playing across all tracks
+
+### Scene Inspection
+
+- `get_scenes_info` — list all scenes with names, tempos, and colors
+- `get_scene_matrix` — see which clips exist in which slots across the entire session grid. Returns a track-by-scene matrix showing clip presence, names, and states.
+
+## Arrangement View
+
+Build linear song structures on the timeline.
+
+### Creating Arrangement Clips
+
+- `create_arrangement_clip(track_index, start_time, length)` — place a new clip on the timeline at a specific beat position
+- `set_arrangement_clip_name(track_index, clip_index, name)` — name arrangement clips for clarity
+
+### Arrangement Notes
+
+- `add_arrangement_notes(track_index, clip_index, notes)` — write MIDI notes into an arrangement clip
+- `get_arrangement_notes(track_index, clip_index)` — read notes from an arrangement clip
+- `remove_arrangement_notes(track_index, clip_index, start_time, duration, pitch_start, pitch_end)` — clear notes in a region
+- `remove_arrangement_notes_by_id(track_index, clip_index, note_ids)` — surgical deletion
+- `modify_arrangement_notes(track_index, clip_index, modifications)` — update existing notes by ID
+- `duplicate_arrangement_notes(track_index, clip_index, time_offset)` — copy notes forward
+- `transpose_arrangement_notes(track_index, clip_index, semitones, start_time, duration)` — pitch shift a region
+
+### Arrangement Clips Inspection
+
+- `get_arrangement_clips(track_index)` — list all clips on a track's arrangement timeline with positions, lengths, and names
+
+### Arrangement Automation
+
+- `set_arrangement_automation(track_index, parameter_name, points)` — write automation on the arrangement timeline. Points are `[{time, value}, ...]` pairs at absolute beat positions.
+
+## Navigation
+
+### Transport Position
+
+- `jump_to_time(beat_time)` — move the playback cursor to a specific beat position on the timeline
+- `start_playback` / `stop_playback` / `continue_playback` — basic transport control
+
+### Cue Points
+
+Cue points are markers on the arrangement timeline for quick navigation.
+
+- `toggle_cue_point` — add or remove a cue point at the current playback position
+- `get_cue_points` — list all cue points with their beat positions and names
+- `jump_to_cue(cue_index)` — jump to a specific cue point by index
+
+Use cue points to mark section boundaries: place one at beat 0 (Intro), beat 16 (Verse), beat 48 (Chorus), etc. This makes navigation fast during arrangement.
+
+## Recording
+
+### Live Recording
+
+- `start_recording` — begin recording into the arrangement or session (depends on which view is active and which tracks are armed)
+- `stop_recording` — stop recording
+- `capture_midi` — retroactive MIDI capture. Grabs whatever was played on armed MIDI tracks even if recording was not active. Live 12 keeps a buffer of recent MIDI input.
+
+### Recording Workflow
+
+1. Arm tracks with `set_track_arm(track_index, arm=true)`
+2. Optionally set input monitoring with `set_track_input_monitoring(track_index, mode)`
+3. `start_recording` — records into arrangement if in arrangement view, into session slots if in session view
+4. Play or trigger clips
+5. `stop_recording` — finalize the take
+
+For retroactive capture: if the user just played something without recording, call `capture_midi` immediately to grab it.
+
+## Section Analysis
+
+- `get_section_graph` — infer song structure from scene names and clip arrangement. Returns a graph of sections with their relationships, durations, and transitions.
+- `analyze_composition` — deeper structural analysis including phrase lengths, repetition patterns, and harmonic arcs
+- `get_phrase_grid` — see how phrases align across tracks
+
+Use `get_section_graph` to understand the current form before adding new sections. It helps identify what is missing (e.g., no bridge, no outro, chorus only appears once).
+
+## Common Song Structures
+
+When building arrangements, use these as starting templates:
+
+- **Pop:** Intro - Verse - Chorus - Verse - Chorus - Bridge - Chorus - Outro
+- **EDM/Dance:** Intro (16 bars) - Build - Drop (16) - Break (8) - Build - Drop (16) - Outro (8)
+- **Hip-hop:** Intro - Verse (16 bars) - Hook (8) - Verse (16) - Hook (8) - Bridge - Hook - Outro
+- **Lo-fi:** Intro (4) - A (8) - B (8) - A (8) - B variation (8) - Outro (4)
+
+Adapt these to the user's needs. Use `plan_arrangement` from the planner domain for algorithmic structure suggestions, and `transform_section` to create variations of existing sections.
+
+## Composition Engine
+
+For deeper compositional analysis beyond basic arrangement:
+
+- `plan_gesture(type, parameters)` — plan a musical gesture (build, release, tension, resolution)
+- `apply_gesture_template(track_index, gesture)` — apply a gesture pattern to a track
+- `evaluate_composition_move(proposed_change)` — score a proposed structural change before making it
+- `get_harmony_field(section)` — see the harmonic landscape of a section
+- `get_transition_analysis(from_section, to_section)` — analyze how two sections connect
+
+## Reference
+
+Consult `references/ableton-workflow-patterns.md` in the livepilot-core skill for session/arrangement workflow patterns, song structures by genre, follow action configurations, clip launch modes, and export settings.

package/livepilot/skills/livepilot-composition-engine/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: livepilot-composition-engine
+description: This skill should be used when the user asks to "analyze song structure", "improve transitions", "check song flow", "plan an arrangement", "detect motifs", "transform a section", or wants compositional analysis, transition planning, and translation checking.
+---
+
+# Composition Engine — Structure, Transitions, and Form
+
+The composition engine operates three sub-engines: compositional analysis (structure and motifs), transition planning (section-to-section flow), and translation checking (how the mix survives different playback systems). It also provides form-level tools for emotional arc and arrangement planning.
+
+## Composition Sub-Engine
+
+Analyze and transform the structural elements of a track.
+
+### Analysis Flow
+
+1. Call `analyze_composition` — runs a full structural pass returning sections, motifs, phrase grid, and form classification
+2. Call `get_section_graph` — returns the section map: intro, verse, chorus, bridge, drop, breakdown, outro with bar ranges
+3. Call `get_phrase_grid` — returns the rhythmic and melodic phrase boundaries within each section
+4. Call `get_motif_graph` — returns detected melodic and rhythmic motifs with their occurrence locations and transformation history
+
+### Transformation
+
+Once you understand the structure:
+
+- `transform_motif(motif_id, transformation)` — apply a transformation to a detected motif. Transformations include: inversion, retrograde, augmentation, diminution, transposition, fragmentation, sequence
+- `transform_section(section_id, transformation)` — apply a structural transformation to an entire section. Transformations include: extend, compress, strip_down, build_up, reharmonize, rhythmic_variation
+
+Always capture before state with `get_notes` or `get_arrangement_notes` before transforming. Evaluate the result with `evaluate_composition_move`.
+
+### Motif Work
+
+The motif graph tracks recurring melodic and rhythmic patterns:
+
+- Each motif has an `id`, `pitches`, `rhythms`, `first_occurrence`, and `occurrences` list
+- Related motifs are linked by transformation edges (e.g., motif_2 is an inversion of motif_1)
+- Use the motif graph to ensure thematic coherence — transformations should derive from existing material
+
+## Transition Sub-Engine
+
+Plan and execute smooth transitions between sections.
+
+### Transition Flow
+
+1. `analyze_transition(from_section, to_section)` — examine the current transition between two sections. Returns energy delta, timbral shift, harmonic distance, and detected issues
+2. `plan_transition(from_section, to_section)` — generate a transition plan based on detected issues. Returns an ordered list of moves (filter sweeps, risers, drum drops, fills, automation curves)
+3. `score_transition(from_section, to_section)` — rate the current transition quality (0.0-1.0) with breakdown by energy, harmony, rhythm, and timbral continuity
+4. Execute the planned moves using appropriate tools (`set_clip_automation`, `add_notes`, `set_device_parameter`, `apply_automation_shape`)
+5. `evaluate_composition_move` — judge whether the transition improved
+
+See `references/transition-archetypes.md` for common transition patterns and when to use each.
+
+### Transition Principles
+
+- Energy changes should be gradual unless a hard cut is intentional
+- Harmonic transitions need a pivot chord or shared tone
+- Rhythmic transitions benefit from a fill or break at the boundary
+- Timbral shifts should start 1-2 bars before the section change
+- The most effective transitions prepare the listener's ear before the change lands
+
+## Translation Sub-Engine
+
+Check how the mix translates across playback systems.
+
+### Translation Flow
+
+1. `check_translation` — run translation analysis on the current mix
+2. `get_translation_issues` — return specific problems:
+   - **mono_collapse**: elements that disappear or phase-cancel in mono playback
+   - **spectral_consistency**: frequency balance shifts between monitoring contexts
+   - **low_end_translation**: bass content that may vanish on small speakers
+   - **loudness_consistency**: perceived loudness variation across systems
+
+Translation issues feed back into the mix engine — a mono collapse issue becomes a stereo_width critic issue for the mix loop.
+
+## Form Sub-Engine
+
+High-level arrangement and emotional arc tools.
+
+### Form Flow
+
+1. `get_emotional_arc` — map the energy/intensity curve across the entire track, identifying peaks, valleys, and plateaus
+2. `plan_arrangement` — generate an arrangement plan based on the current form, suggesting section order, lengths, and energy targets
+3. `apply_gesture_template` — apply a predefined arrangement gesture (build, drop, breakdown, outro_fade, intro_build) to a bar range
+
+See `references/form-patterns.md` for common song forms and energy curves by genre.
+
+### Arrangement Principles
+
+- Every section should have a clear purpose: introduce, develop, contrast, resolve, release
+- The energy arc should have at least one clear peak — flat energy across the entire track lacks emotional impact
+- Contrast drives interest: loud/quiet, dense/sparse, bright/dark
+- Repetition builds familiarity but needs variation to avoid fatigue — transform on repeat, do not copy verbatim
+- Transitions are as important as sections — budget time for them in the arrangement
+
+## Combining Sub-Engines
+
+A typical compositional improvement session:
+
+1. `analyze_composition` to understand current structure
+2. `get_emotional_arc` to see the energy shape
+3. Identify the weakest section or transition
+4. Use the transition sub-engine to fix section boundaries
+5. Use motif transformations to add thematic development
+6. `check_translation` to verify the changes survive mono/small speakers
+7. `evaluate_composition_move` after each change
+
+Always work one change at a time. Verify and evaluate before moving to the next intervention.

package/livepilot/skills/livepilot-composition-engine/references/form-patterns.md

@@ -0,0 +1,97 @@
+# Form Patterns Reference
+
+Common song forms and energy curves used by `plan_arrangement` and `get_emotional_arc`.
+
+## Standard Forms
+
+### verse_chorus (Pop / Rock / R&B)
+```
+Intro (4-8 bars) -> Verse 1 (8-16) -> Pre-Chorus (4-8) -> Chorus 1 (8-16)
+-> Verse 2 (8-16) -> Pre-Chorus (4-8) -> Chorus 2 (8-16)
+-> Bridge (8) -> Final Chorus (8-16) -> Outro (4-8)
+```
+Energy curve: low -> medium -> high -> medium -> high -> peak -> fade
+
+### drop_form (EDM / House / Techno)
+```
+Intro (16-32 bars) -> Build 1 (8-16) -> Drop 1 (16-32)
+-> Breakdown (8-16) -> Build 2 (8-16) -> Drop 2 (16-32)
+-> Outro (8-16)
+```
+Energy curve: building -> peak -> valley -> building -> peak -> fade
+
+### through_composed (Ambient / Cinematic / Experimental)
+```
+Section A (variable) -> Section B (variable) -> Section C (variable) -> ...
+```
+No repeating sections. Energy curve follows the narrative arc. Each section introduces new material.
+
+### aaba (Jazz / Classic Pop)
+```
+A (8 bars) -> A (8) -> B (8) -> A (8)
+```
+Energy curve: establish -> reinforce -> contrast -> resolve
+
+### rondo (Classical-influenced / Progressive)
+```
+A -> B -> A -> C -> A -> D -> A
+```
+Recurring theme (A) alternates with contrasting episodes. Energy varies per episode.
+
+### loop_form (Hip-Hop / Trap / Lo-Fi)
+```
+Intro (4-8) -> Loop (4-8 bars, repeated throughout)
+Verse 1 over loop -> Hook over loop -> Verse 2 over loop -> Hook -> Outro
+```
+Energy modulation through vocal density and arrangement layering, not harmonic progression.
+
+## Energy Curve Targets
+
+The emotional arc maps energy on a 0.0-1.0 scale across the track duration.
+
+### Peak-Valley Model
+Most effective for dance and pop music:
+- At least one peak reaching 0.8-1.0
+- At least one valley dropping to 0.2-0.4
+- Energy delta between adjacent sections: 0.15-0.4
+- Gradual builds (4+ bars) feel more natural than instant jumps
+
+### Plateau Model
+For ambient, drone, and minimalist music:
+- Energy stays within a narrow band (0.3-0.6)
+- Changes are subtle: timbral, textural, not dynamic
+- Slow evolution over minutes, not bars
+
+### Escalation Model
+For builds, film scoring, and progressive tracks:
+- Monotonically increasing energy from 0.1 to 1.0
+- Each section is louder, denser, or brighter than the previous
+- No significant drops until the final resolution
+
+## Section Energy Targets by Genre
+
+| Section | Pop | EDM | Hip-Hop | Ambient |
+|---------|-----|-----|---------|---------|
+| Intro | 0.2 | 0.3 | 0.3 | 0.2 |
+| Verse | 0.4 | 0.4 | 0.5 | 0.3 |
+| Pre-Chorus | 0.6 | 0.6 | — | — |
+| Chorus/Drop | 0.8 | 1.0 | 0.7 | 0.5 |
+| Bridge | 0.5 | — | 0.4 | 0.4 |
+| Breakdown | — | 0.2 | — | 0.3 |
+| Outro | 0.3 | 0.2 | 0.2 | 0.1 |
+
+## Section Length Guidelines
+
+- **4 bars**: minimum for a recognizable section (short intros, transitions)
+- **8 bars**: standard phrase length, feels complete for most sections
+- **16 bars**: full development, typical for verses and choruses in electronic music
+- **32 bars**: extended development for drops, long builds, or ambient passages
+- **Odd lengths** (6, 10, 12 bars): create subtle tension and asymmetry — use intentionally
+
+## Arrangement Planning Rules
+
+1. Start from the emotional peak and work backwards — place the climax first, then build toward it
+2. Every section serves one of five functions: introduce, develop, contrast, climax, resolve
+3. Do not repeat a section more than 3 times without significant variation
+4. The first 30 seconds determine whether the listener stays — make them count
+5. Endings matter — an abrupt end can be intentional, but a trailing reverb wash is rarely wrong