claude-code-arcane 2.1.0 → 2.2.0

package/skills/audio-spec/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: audio-spec
+description: "SFX spec sheets y audio event lists: trigger, prioridad, concurrencia, cooldown, variaciones, propiedades espaciales. Usar para: especificar sonidos, event list por sistema, brief para sound designer."
+category: "audio"
+argument-hint: "[system-name | all | events]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+# audio-spec — SFX Specs & Event Lists
+
+Convierte dirección sonora en especificaciones que un sound designer externo puede producir sin más briefing, y en event lists que un programador puede implementar sin adivinar.
+
+Dos entregables distintos y complementarios:
+- **Spec sheet** — describe *el sonido*: cómo suena, cuánto dura, cuántas variantes
+- **Event list** — describe *el contrato*: qué lo dispara, con qué prioridad, cuántas instancias, qué parámetros recibe
+
+## Cuándo usar
+
+- Después de `/audio-bible` (la dirección tiene que existir primero)
+- Cuando vas a tercerizar producción de SFX y necesitás un brief cerrado
+- Cuando el código necesita saber qué eventos postear antes de que existan los assets
+- Antes de `/middleware-integration` — la event list es su input
+
+## Modos
+
+| Modo | Qué hace |
+|---|---|
+| `system-name` | Especifica un sistema concreto: spec sheets + event list de, por ejemplo, `combat` |
+| `all` | Barre todos los sistemas del proyecto, uno por vez |
+| `events` | Solo la event list, sin spec sheets. Para cuando el código necesita el contrato antes de que existan los assets |
+
+## Input
+
+1. Leer audio bible (paleta, frequency allocation, mix hierarchy, standards). Si no existe, avisar y ofrecer `/audio-bible` primero
+2. Identificar el sistema a especificar (combate, locomoción, UI, ambiente, props...) o `all`
+3. Leer el código/GDD del sistema para extraer los momentos que piden sonido
+4. Preguntar al usuario: nivel de detalle (spec completo vs event list sola) y si hay assets existentes que reusar
+
+---
+
+## Spec sheet — campos obligatorios
+
+Cada sonido lleva estos campos. Un campo vacío es una decisión que alguien va a tomar por vos:
+
+| Campo | Qué define | Ejemplo |
+|---|---|---|
+| **ID** | Nombre canónico, matchea naming del bible | `sfx_weapon_shotgun_fire` |
+| **Descripción** | Qué es, en una línea funcional | Disparo de escopeta de doble caño, seco, sin cola de reverb |
+| **Referencias** | 1-3 sonidos concretos con qué tomar de cada uno | — |
+| **Carácter frecuencial** | Dónde vive, contra la allocation del bible | Sub-punch 50-70 Hz + crack 3-5 kHz, vacío en mids |
+| **Duración** | Rango, no valor único | 180-260 ms |
+| **Envolvente** | Attack / body / tail explícitos | Attack <5 ms, body 60 ms, tail 120 ms |
+| **Rango de volumen** | Nivel relativo a la categoría | −6 dB a −3 dB del bus SFX |
+| **Propiedades espaciales** | 2D/3D, curva de atenuación, min/max distance | 3D, 2-40 m, log |
+| **Variaciones** | Cuántas variantes y qué randomización | 5 variantes, pitch ±3%, volumen ±1.5 dB |
+| **Prioridad** | Qué se cae primero bajo presión de voces | Alta (feedback de acción del jugador) |
+
+## Event list — campos obligatorios
+
+| Campo | Qué define |
+|---|---|
+| **Evento** | Nombre que postea el código |
+| **Trigger** | Condición exacta de gameplay que lo dispara |
+| **Sonidos** | Qué IDs de spec resuelve (uno o un container) |
+| **Concurrencia** | Máximo de instancias simultáneas + qué hacer al exceder (drop oldest / drop newest / reject) |
+| **Cooldown** | Mínimo entre disparos, para eventos que pueden spamearse |
+| **Parámetros** | RTPCs que recibe, con rango normalizado |
+| **Stop condition** | Cómo termina: one-shot, loop con stop explícito, o fade |
+
+**Concurrencia y cooldown no son opcionales.** Son la diferencia entre un sistema que sobrevive 40 enemigos en pantalla y uno que satura el voice budget. Todo evento que puede dispararse más de una vez por frame necesita ambos.
+
+---
+
+## Proceso
+
+1. **Barrer el sistema** — listar cada momento que pide sonido, incluyendo los negativos (dónde el silencio es la decisión)
+2. **Agrupar** — sonidos que comparten carácter van juntos; identificar qué puede ser variación de un mismo asset en vez de asset nuevo
+3. **Draftar** specs y event list del grupo
+4. **Presentar** al usuario para review
+5. **Escribir** — preguntar "¿Escribo el spec de `<sistema>` a `<path>`?" antes de usar Write
+
+No batchear sistemas: cerrar uno antes de abrir el siguiente.
+
+### Reducción de assets
+
+Antes de especificar N sonidos nuevos, preguntar si el caso se resuelve con variación o con síntesis. El caso canónico: 20 samples × 6 superficies × 3 intensidades = 360 archivos (~180 MB) vs footsteps procedurales (~50 KB) con variación infinita. Si el sistema es de alta frecuencia y muchas dimensiones, derivar a `/procedural-audio` antes de escribir el spec.
+
+---
+
+## Verdict
+
+Por sistema especificado:
+
+- **READY** — todo sonido tiene los 10 campos, todo evento tiene concurrencia y cooldown. Un externo puede producir y un programador puede implementar
+- **CONCERNS** — hay campos vacíos o eventos sin límites; listar cuáles
+- **BLOCKED** — falta el audio bible, o el sistema de gameplay no está definido lo suficiente para saber qué momentos existen
+
+## Anti-patterns
+
+> → Read references/anti-patterns.md
+
+## Next steps
+
+- `/middleware-integration` para implementar la event list en Wwise/FMOD
+- `/procedural-audio` para los sistemas de alta frecuencia que no conviene samplear
+- `/sfx-design` para profundizar el diseño de los sonidos hero
+- `/audio-audit` para verificar los assets entregados contra el spec

package/skills/audio-spec/references/anti-patterns.md

@@ -0,0 +1,45 @@
+# Audio Spec — Anti-patterns
+
+## Spec sin números
+
+"Impacto potente y satisfactorio" no es producible. Duración, envolvente, bandas de frecuencia y nivel relativo sí. Si el campo no tiene número o rango, no está especificado.
+
+## Duración como valor único
+
+"200 ms" fuerza al sound designer a mentir o a pedir aprobación. Un rango (180-260 ms) le da lugar a que el sonido termine donde tiene que terminar.
+
+## Eventos sin concurrencia
+
+El spec dice "sonido de casquillo al caer". Llegan 40 enemigos, 300 casquillos, el voice budget explota y el mix desaparece. Todo evento que puede dispararse más de una vez por frame necesita máximo de instancias y política de descarte.
+
+## Cooldown ausente en eventos de UI
+
+Navegación rápida en un menú dispara el mismo tick 15 veces en 200 ms. Suena como un glitch. Cooldown mínimo, siempre.
+
+## Una variante
+
+Un sonido sin variantes se vuelve audible como *sonido* en vez de como evento en unos 20 minutos de juego. Si el evento es frecuente, mínimo 4-5 variantes o randomización de pitch, y preferentemente ambas.
+
+## Pitch randomization exagerada
+
+±3% es variación. ±20% cambia el objeto: el arma parece otra arma. Rango chico y round-robin le gana a rango grande.
+
+## Specs 3D sin curva
+
+Marcar "3D" y no definir min/max distance ni forma de la curva deja la atenuación en el default del middleware, que casi nunca es el correcto. El sonido se oye a 200 m o desaparece a 3 m.
+
+## Especificar antes de decidir procedural
+
+Escribir 360 spec sheets de footsteps es trabajo perdido si la respuesta correcta era síntesis. Evaluar el eje frecuencia × dimensiones antes de especificar.
+
+## Event list sin stop condition
+
+Los loops son la fuente número uno de audio colgado. Todo sonido que loopea necesita decir explícitamente quién lo para y qué pasa si el objeto dueño se destruye primero.
+
+## Prioridades todas iguales
+
+Si todo es prioridad alta, el voice limiter descarta al azar y se cae el feedback de la acción del jugador antes que un ambiente lejano. Las prioridades solo sirven si están diferenciadas.
+
+## IDs que no siguen el naming del bible
+
+`shotgun2_FINAL_v3` rompe búsqueda, batch processing y automatización de banks. El ID sale del pattern del bible, sin excepciones.

package/skills/middleware-integration/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: middleware-integration
+description: "Integracion de middleware de audio (Wwise/FMOD): containers, eventos, Switches/States/RTPCs, atenuaciones, soundbanks, streaming vs memoria, y el contrato con el codigo de gameplay. Usar para: Wwise, FMOD, event authoring, RTPC, soundbanks, arquitectura de audio."
+category: "audio"
+argument-hint: "[structure | events | rtpc | banks | contract]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+# middleware-integration — Wwise / FMOD
+
+Diseña la estructura del proyecto de middleware y el contrato entre el audio y el código de gameplay.
+
+Conceptos agnósticos donde se puede; nomenclatura de Wwise como referencia principal, con el equivalente FMOD anotado, porque los dos modelan lo mismo con nombres distintos.
+
+## Cuándo usar
+
+- Estructurar un proyecto de Wwise/FMOD desde cero
+- Definir el contrato de eventos que va a postear el código
+- Diseñar la organización de soundbanks
+- El proyecto de middleware creció desordenado y hay que reorganizarlo
+- Decidir qué va en memoria y qué va en streaming
+
+## Input
+
+1. Leer `/audio-spec` (event lists), `/audio-mix` (buses) y `/adaptive-music` (matriz de transiciones) si existen
+2. Determinar el middleware y su versión
+3. Preguntar al usuario: plataformas target, budget de memoria de audio, y si el proyecto ya existe o se arranca limpio
+
+---
+
+## Equivalencias Wwise ↔ FMOD
+
+| Concepto | Wwise | FMOD Studio |
+|---|---|---|
+| Unidad que dispara el código | Event | Event |
+| Contenedor de variación | Random / Sequence Container | Multi-instrument, Scatterer |
+| Selección por estado discreto | Switch Container | Parameter (labeled) |
+| Mezcla continua entre variantes | Blend Container | Parameter con automatización |
+| Parámetro continuo | RTPC (Game Parameter) | Parameter (continuous) |
+| Estado global | State | Global parameter / Snapshot |
+| Agrupación de mezcla | Actor-Mixer / Bus | Group bus |
+| Snapshot de mezcla | State con propiedades de bus | Snapshot |
+| Curva de distancia | Attenuation ShareSet | 3D panner + curvas |
+| Empaquetado | SoundBank | Bank |
+| Música interactiva | Music Switch / Playlist Container | Event con transition regions |
+
+## Estructura del proyecto
+
+Organizar por **sistema de gameplay**, no por tipo de sonido. `Weapons/Shotgun/` es navegable; `Impacts/` con todo mezclado no.
+
+```
+Actor-Mixer Hierarchy
+├── Player          (locomoción, armas, voz del jugador)
+├── Enemies         (por arquetipo)
+├── World           (props, entorno, destructibles)
+├── Ambience        (por zona)
+└── UI
+
+Interactive Music
+└── (por estado: Explore, Combat, Victory...)
+
+Events
+└── (espeja la jerarquía de Actor-Mixer)
+```
+
+**Reglas que evitan el desorden:**
+- Un evento por acción de gameplay, no por sonido. `Play_Weapon_Fire` con un Switch de tipo de arma le gana a un evento por arma
+- Los ShareSets (atenuación, conversión, efectos) se definen una vez y se reusan. Un ShareSet por objeto es la causa número uno de proyectos inmanejables
+- Work units separados por sistema: es lo que permite que dos personas trabajen sin conflictos de merge
+
+## Containers
+
+| Container | Cuándo | Cuidado |
+|---|---|---|
+| **Random** | Variación de un mismo sonido | Usar *shuffle* (round-robin), no random puro: random repite |
+| **Sequence** | Sonidos que tienen orden (carga → disparo) | Definir qué pasa al interrumpir |
+| **Switch** | Selección por estado discreto (superficie, tipo de arma) | Definir el default: si el Switch no está seteado, el evento no suena |
+| **Blend** | Mezcla continua por parámetro (RPM de motor) | Cuidar el solapamiento de las curvas o hay huecos |
+
+## Switches, States y RTPCs
+
+Tres cosas distintas, y confundirlas es un error de arquitectura frecuente:
+
+| | Alcance | Tipo | Ejemplo |
+|---|---|---|---|
+| **Switch** | Por objeto de juego | Discreto | Superficie bajo *este* personaje |
+| **State** | Global | Discreto | El juego está en pausa |
+| **RTPC** | Global o por objeto | Continuo | Salud del jugador, intensidad de combate |
+
+**Regla:** si es una propiedad de un objeto específico, es Switch. Si es una condición del juego entero, es State. Si es un número que varía suave, es RTPC.
+
+Usar un State para algo que es por objeto es el bug que produce "todos los personajes caminan sobre la superficie del jugador".
+
+**Contrato de RTPCs:** todo RTPC necesita rango declarado, curva, y valor por default. El código **normaliza y clampea antes de enviarlo** — el middleware no debería recibir nunca un valor fuera de rango.
+
+## Soundbanks
+
+Estrategia por defecto que funciona en la mayoría de los proyectos:
+
+| Bank | Contenido | Cuándo carga |
+|---|---|---|
+| `Init` | Estructura del proyecto, buses | Al arrancar, siempre |
+| `Global` | UI, voz del jugador, música persistente | Al arrancar, siempre |
+| `Level_XX` | Ambiente y props del nivel | Al cargar el nivel |
+| `Character_XX` | Por personaje/enemigo | Con el spawn del personaje |
+
+**Streaming vs memoria:**
+
+| Va en memoria | Va en streaming |
+|---|---|
+| Todo lo corto y frecuente (SFX, UI, footsteps) | Música |
+| Cualquier cosa que necesite latencia cero | Diálogo largo |
+| | Ambientes largos |
+
+El streaming ahorra memoria y cuesta latencia y accesos a disco. Un SFX en streaming llega tarde; la música en memoria se come el budget.
+
+**Prefetch** para lo streameado que necesita arrancar rápido: los primeros ms van en memoria y el resto se stremea.
+
+## Contrato con el código
+
+Lo que el código tiene que poder hacer, y nada más:
+
+```
+PostEvent(eventName, gameObject)      → dispara
+StopEvent(playingId, fadeMs)          → detiene lo que loopea
+SetSwitch(group, value, gameObject)   → propiedad de objeto
+SetState(group, value)                → condición global
+SetRTPC(param, value01, gameObject?)  → parámetro, normalizado
+RegisterGameObject / Unregister       → ciclo de vida
+```
+
+**Reglas del contrato** (las mismas que enforcea `rules/gamedev/audio-code.md`):
+
+- Gameplay **nunca** referencia assets, solo nombres de evento
+- Todo loop tiene un stop explícito, y se detiene al destruirse el objeto dueño
+- Los RTPCs llegan normalizados y clampeados
+- Un evento que falla (bank no cargado) **no rompe el frame**: degrada en silencio
+- Registrar y des-registrar game objects es obligatorio — objetos filtrados son un leak clásico
+
+## Profiling
+
+El middleware trae el profiler, y es la única fuente de verdad sobre lo que pasa en runtime:
+
+- **Voces activas** vs el límite configurado, y qué se está descartando
+- **CPU de audio** contra el 5-10% del frame
+- **Memoria** por bank y total
+- **Valores de RTPC en vivo** — sirve para descubrir que el código manda un rango equivocado
+- **Árbol de contribución de voz** — por qué un sonido se oye más o menos de lo esperado
+- Capturas exportables para análisis offline
+
+Para profilear objetos de juego hay que tener la captura activa en la vista de Game Object antes de disparar los eventos, o no se registra nada.
+
+---
+
+## Proceso
+
+1. **Definir la jerarquía** por sistema de gameplay, con work units separados
+2. **Crear los ShareSets** de atenuación y conversión antes de los objetos, para que se reusen
+3. **Autorear los eventos** desde la event list de `/audio-spec`, uno por acción
+4. **Definir Switch/State/RTPC** con su alcance correcto, rango y default
+5. **Diseñar los buses** desde `/audio-mix`
+6. **Definir los banks** y qué va en streaming
+7. **Documentar el contrato** para el equipo de código
+8. **Escribir** — preguntar "¿Escribo la arquitectura a `<path>`?" antes de usar Write
+
+### Nota sobre automatización
+
+Wwise expone WAAPI y FMOD tiene su API de scripting, así que la autoría en batch es automatizable. Hay servidores MCP de terceros que exponen WAAPI a un agente, pero al momento de escribir esto el más completo se declara **EXPERIMENTAL y explícitamente no recomendado para proyectos de producción**. Si querés explorarlo, hacelo en un proyecto de prueba, nunca sobre el proyecto real.
+
+---
+
+## Verdict
+
+- **READY** — jerarquía por sistema, ShareSets reusados, cada parámetro con el alcance correcto, banks definidos, contrato documentado
+- **CONCERNS** — la estructura existe pero hay ShareSets duplicados, parámetros con alcance equivocado (State donde va Switch), o banks sin estrategia de carga
+- **BLOCKED** — falta la event list de `/audio-spec` o la estructura de buses de `/audio-mix`
+
+## Anti-patterns
+
+> → Read references/anti-patterns.md
+
+## Next steps
+
+- `/audio-audit` para profilear voces, CPU y memoria en runtime
+- `/adaptive-music` si falta la matriz de transiciones de música
+- `/audio-spec` si la event list no existe todavía

package/skills/middleware-integration/references/anti-patterns.md

@@ -0,0 +1,69 @@
+# Middleware Integration — Anti-patterns
+
+## Un evento por sonido
+
+500 eventos donde alcanzaban 40 con Switches. El código termina conociendo el nombre de cada asset, que es exactamente lo que el middleware venía a evitar. Un evento por *acción de gameplay*.
+
+## ShareSet por objeto
+
+Cada sonido con su propia atenuación y su propia conversión. Cambiar el rango de audición del juego pasa de ser un cambio a ser 300. Definir los ShareSets primero y reusarlos.
+
+## State donde va Switch
+
+Usar un State global para la superficie bajo el personaje produce el bug clásico: todos los personajes caminan sobre la superficie del jugador. Propiedad de objeto = Switch.
+
+## Switch sin default
+
+Si el Switch no está seteado cuando llega el evento, el sonido no suena, y el bug es invisible hasta que alguien nota el silencio. Todo Switch group con default.
+
+## Random puro en vez de shuffle
+
+Random repite: con 4 variantes hay 25% de escuchar la misma dos veces seguidas. Shuffle/round-robin excluyendo la última.
+
+## RTPC sin clamp del lado del código
+
+Un valor de salud que llega en 150 cuando el RTPC espera 0-100 deja el parámetro pegado al extremo. Normalizar y clampear en el boundary de gameplay.
+
+## Loops sin stop explícito
+
+La fuente número uno de audio colgado. Todo sonido que loopea necesita un stop, y tiene que detenerse cuando el objeto dueño se destruye.
+
+## Game objects sin des-registrar
+
+Cada enemigo muerto deja su game object registrado. A las dos horas de juego hay miles. Leak clásico, y arruina el profiling.
+
+## Todo en un bank
+
+Un bank monolítico se carga entero aunque el nivel use el 10%. Y cualquier cambio obliga a redistribuirlo completo. Init + Global + por nivel + por personaje.
+
+## SFX en streaming
+
+Un sonido corto y frecuente en streaming llega tarde y genera accesos a disco. Streaming es para música, diálogo largo y ambientes.
+
+## Música en memoria
+
+Se come el budget de audio entero. Streaming con prefetch.
+
+## Fallo de evento que rompe el frame
+
+Un bank no cargado tira una excepción que llega a gameplay. El audio degrada en silencio, siempre.
+
+## Jerarquía por tipo de sonido
+
+`Impacts/` con todos los impactos del juego mezclados no se navega ni se mezcla. Organizar por sistema de gameplay.
+
+## Un solo work unit
+
+Dos personas trabajando producen conflictos de merge irresolubles en un archivo binario o XML gigante. Work units por sistema.
+
+## Confiar en el editor en vez del profiler
+
+Disparar eventos a mano desde el editor no dice nada sobre voces activas, CPU o memoria en gameplay real. El profiler es la única fuente de verdad.
+
+## Profilear game objects sin activar la captura
+
+Sin la captura activa en la vista de Game Object antes de disparar los eventos, no se registra nada y parece que el sistema no funciona.
+
+## Automatizar sobre el proyecto de producción
+
+Las herramientas de autoría en batch vía WAAPI son potentes y las de terceros están mayormente en estado experimental. Probar en un proyecto descartable; el proyecto real no es el lugar.

package/skills/midi-compose/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: midi-compose
+description: "Genera archivos MIDI (.mid) desde un spec JSON con scripts Python stdlib-only. Sin dependencias: escribe el Standard MIDI File binario directo. Usar para: exportar una composicion a MIDI, bocetar stems, generar loops o capas para middleware."
+category: "audio"
+argument-hint: "[spec-path | new | validate]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit, Bash
+---
+# midi-compose — Composición a MIDI
+
+Baja decisiones musicales a un `.mid` real. Las decisiones las toma `/music-composition`; esta skill las escribe.
+
+**Sin dependencias.** El Standard MIDI File es un formato binario documentado y `scripts/compose_midi.py` lo emite con la stdlib de Python. No hay que instalar `midiutil`, `music21` ni nada. Corre en la máquina del usuario tal como se copia.
+
+## Alcance
+
+**Sí:** escribir `.mid` multipista con tempo, compás, tonalidad, programas General MIDI, velocities y percusión.
+
+**No:** renderizar a audio (requiere FluidSynth + soundfonts, dependencias de sistema fuera de scope), tomar decisiones musicales (→ `/music-composition`), notación.
+
+## Cuándo usar
+
+- Ya hay material decidido (progresión, melodía, groove) y hace falta el archivo
+- Bocetar stems para un sistema de capas de `/adaptive-music`
+- Generar variantes de un tema por transformación (aumentación, cambio de modo)
+- Entregar MIDI a un compositor o importarlo a un DAW/middleware
+
+---
+
+## Modos
+
+| Modo | Qué hace |
+|---|---|
+| `spec-path` | Genera el `.mid` desde un spec JSON existente |
+| `new` | Arma el spec desde cero a partir de material musical, y después genera |
+| `validate` | Solo valida el spec y reporta, sin escribir nada |
+
+## Workflow
+
+### 1. Armar el spec
+
+Un objeto JSON. Todos los tiempos están en **beats** (negras), no en ticks — el script convierte.
+
+```json
+{
+  "name": "Explore Calm",
+  "tempo": 84,
+  "ppq": 480,
+  "time_signature": [4, 4],
+  "key": "D",
+  "mode": "minor",
+  "tracks": [
+    {
+      "name": "Bed (strings)",
+      "channel": 0,
+      "program": 48,
+      "notes": [
+        { "pitch": "D3", "start": 0, "duration": 4, "velocity": 62 }
+      ]
+    }
+  ]
+}
+```
+
+Hay un ejemplo completo de tres pistas en `templates/example-composition.json`.
+
+**Campos del spec**
+
+| Campo | Default | Notas |
+|---|---|---|
+| `name` | `"untitled"` | Va al meta de nombre de secuencia |
+| `tempo` | `120` | BPM, 1-600 |
+| `ppq` | `480` | Ticks por negra, 24-32767 |
+| `time_signature` | `[4, 4]` | Denominador potencia de 2 |
+| `key` / `mode` | `"C"` / `"major"` | Solo para el meta de tonalidad; no transpone |
+| `tracks[].channel` | índice del track | 0-15, único por track |
+| `tracks[].program` | `0` | Programa General MIDI 0-127 |
+| `tracks[].drums` | `false` | Declaralo en el track del canal 9 |
+| `notes[].pitch` | — | `60`, `"C4"`, `"F#3"`, `"Bb5"`. C4 = 60 |
+| `notes[].start` | `0` | En beats desde el inicio |
+| `notes[].duration` | `1` | En beats, > 0 |
+| `notes[].velocity` | `90` | 1-127 |
+
+### 2. Validar antes de escribir
+
+```bash
+python skills/midi-compose/scripts/compose_midi.py spec.json --validate
+```
+
+Salida `[PASS]` con el resumen, más `[WARN]` por cada problema no fatal. Un `[FAIL]` nombra el track y la nota exactos.
+
+### 3. Generar
+
+```bash
+python skills/midi-compose/scripts/compose_midi.py spec.json -o salida.mid
+```
+
+Antes de escribir el `.mid` o el spec a disco, preguntar al usuario "¿Escribo esto a `<path>`?" — sobre todo si el archivo ya existe.
+
+---
+
+## Límites de MIDI que importan
+
+- **16 canales.** El canal 9 (10 en base 1) está reservado a percusión por General MIDI, así que quedan **15 pistas melódicas**. Si necesitás más, son varios archivos.
+- **Un programa por canal a la vez.** Cambiar de instrumento a mitad de pista pide otro canal.
+- **Velocity no es volumen.** Es intensidad de ataque; el sampler decide qué hacer con ella.
+- **MIDI no lleva timbre.** El programa GM es una sugerencia; cómo suena depende del soundfont o del instrumento del DAW.
+- **`pitch` en el canal de percusión es el instrumento**, no una altura: 36 = bombo, 38 = redoblante, 42 = hi-hat cerrado, 46 = hi-hat abierto.
+
+## Feel y microtiming
+
+El spec acepta `start` fraccional, así que el feel se escribe directo: para atrasar un backbeat 15 ms a 84 BPM, `15 / (60000 / 84 / 1) ≈ 0.021` beats. Un desvío de 10-30 ms es feel; arriba de ~50 ms se percibe como error. Ver `references/smf-format.md` para la relación tick/ms.
+
+## Formato
+
+> → Read references/smf-format.md para la estructura binaria del SMF, el encoding VLQ y la tabla de programas GM más usados
+
+---
+
+## Verdict
+
+- **COMPLETE** — el `.mid` se escribió y la verificación de estructura pasa
+- **CONCERNS** — se escribió pero hay `[WARN]`: contenido melódico en el canal de percusión, o pistas cerca del límite de 15
+- **FAIL** — el spec no valida; el mensaje nombra el track y la nota
+
+Verificación rápida de que el archivo es un SMF:
+
+```bash
+python -c "print(open('salida.mid','rb').read(4) == b'MThd')"   # True
+```
+
+## Next steps
+
+- `/music-composition` si el material musical todavía no está decidido
+- `/adaptive-music` para armar el sistema de capas que consume estos stems
+- `/middleware-integration` para importar los segmentos a Wwise/FMOD

package/skills/midi-compose/references/smf-format.md

@@ -0,0 +1,129 @@
+# Standard MIDI File — formato binario
+
+Referencia de lo que emite `scripts/compose_midi.py`. Útil para debuggear un `.mid` a mano o extender el script.
+
+## Estructura general
+
+Un SMF es una secuencia de chunks. Cada chunk: 4 bytes de tipo + 4 bytes de longitud (big-endian) + cuerpo.
+
+```
+MThd <len=6> <format:2> <ntrks:2> <division:2>
+MTrk <len>   <eventos...>
+MTrk <len>   <eventos...>
+```
+
+**Formatos:**
+
+| Formato | Qué es |
+|---|---|
+| 0 | Un solo track con todo mezclado |
+| 1 | Múltiples tracks simultáneos; el track 0 es el conductor (tempo/compás) |
+| 2 | Tracks independientes, secuenciales. Casi no se usa |
+
+El script emite **formato 1**: track 0 con tempo, compás y tonalidad sin notas, y un `MTrk` por pista musical. Es lo que esperan los DAWs.
+
+**División** — con el bit alto en 0, es *ticks por negra* (PPQ). 480 es el valor estándar de la industria y divide bien tresillos (160) y semicorcheas (120).
+
+## Delta-times y VLQ
+
+Cada evento arranca con un delta-time: cuántos ticks pasaron desde el evento anterior *en ese track*. Se codifica como Variable-Length Quantity: 7 bits de datos por byte, MSB = 1 en todos los bytes menos el último.
+
+| Valor | Bytes |
+|---|---|
+| 0 | `00` |
+| 127 | `7F` |
+| 128 | `81 00` |
+| 480 | `83 60` |
+| 8192 | `C0 00` |
+
+Un delta mal codificado desplaza todo lo que sigue: es la causa número uno de un `.mid` que "suena raro a partir de la mitad".
+
+## Eventos de canal
+
+`n` es el canal, 0-15.
+
+| Evento | Bytes | Notas |
+|---|---|---|
+| Note Off | `8n kk vv` | `kk` nota, `vv` velocity de release |
+| Note On | `9n kk vv` | `vv = 0` equivale a Note Off |
+| Control Change | `Bn cc vv` | cc 7 = volumen, 10 = pan, 11 = expresión |
+| Program Change | `Cn pp` | Instrumento GM |
+| Pitch Bend | `En ll mm` | 14 bits, centro en `00 40` |
+
+**Orden en el mismo tick:** el Note Off tiene que ir antes del Note On cuando se reataca la misma nota, o el sintetizador corta la nota nueva. El script ordena por `(tick, 0=off, 1=on)` justamente por esto.
+
+## Meta eventos
+
+Todos arrancan con `FF`, después tipo, después longitud en VLQ.
+
+| Meta | Bytes | Contenido |
+|---|---|---|
+| Nombre de secuencia/track | `FF 03 <len> <texto>` | |
+| Tempo | `FF 51 03 tttttt` | Microsegundos por negra = `60000000 / BPM` |
+| Compás | `FF 58 04 nn dd cc bb` | `dd` = log2(denominador); `cc` = 24; `bb` = 8 |
+| Tonalidad | `FF 59 02 sf mi` | `sf` sostenidos (+) o bemoles (−), signed; `mi` 0 mayor / 1 menor |
+| End of Track | `FF 2F 00` | **Obligatorio** al final de cada `MTrk` |
+
+Sin `End of Track` muchos lectores rechazan el archivo entero.
+
+## Conversión de tiempo
+
+```
+ticks = beats × PPQ
+ms_por_tick = 60000 / (BPM × PPQ)
+```
+
+A 120 BPM con PPQ 480: 1 tick = 1.041 ms. A 84 BPM: 1 tick = 1.488 ms.
+
+Para escribir un desvío de feel en beats: `beats = ms × BPM / 60000`.
+
+## Programas General MIDI usados seguido
+
+| # | Instrumento | # | Instrumento |
+|---|---|---|---|
+| 0 | Acoustic Grand Piano | 48 | String Ensemble 1 |
+| 4 | Electric Piano 1 | 49 | String Ensemble 2 |
+| 11 | Vibraphone | 52 | Choir Aahs |
+| 19 | Church Organ | 56 | Trumpet |
+| 24 | Nylon Guitar | 57 | Trombone |
+| 25 | Steel Guitar | 60 | French Horn |
+| 32 | Acoustic Bass | 68 | Oboe |
+| 33 | Finger Bass | 71 | Clarinet |
+| 40 | Violin | 73 | Flute |
+| 42 | Cello | 89 | Pad 2 (warm) |
+| 46 | Orchestral Harp | 94 | Pad 7 (halo) |
+
+## Percusión (canal 9)
+
+El `pitch` es el instrumento, no la altura.
+
+| # | Instrumento | # | Instrumento |
+|---|---|---|---|
+| 35 | Acoustic Bass Drum | 44 | Pedal Hi-Hat |
+| 36 | Bass Drum 1 | 46 | Open Hi-Hat |
+| 38 | Acoustic Snare | 49 | Crash Cymbal 1 |
+| 39 | Hand Clap | 51 | Ride Cymbal 1 |
+| 40 | Electric Snare | 54 | Tambourine |
+| 41 | Low Floor Tom | 56 | Cowbell |
+| 42 | Closed Hi-Hat | 76 | Hi Wood Block |
+
+## Verificar un .mid a mano
+
+```bash
+python - <<'EOF'
+import struct
+data = open("salida.mid", "rb").read()
+assert data[:4] == b"MThd"
+length, fmt, ntrks, div = struct.unpack(">IHHH", data[4:14])
+print("format", fmt, "| tracks", ntrks, "| ppq", div)
+pos, seen = 14, 0
+while pos < len(data):
+    name, size = data[pos:pos+4], struct.unpack(">I", data[pos+4:pos+8])[0]
+    body = data[pos+8:pos+8+size]
+    assert name == b"MTrk" and body[-3:] == b"\xff\x2f\x00", f"track {seen} malformado"
+    pos += 8 + size
+    seen += 1
+assert seen == ntrks and pos == len(data)
+print("SMF valido")
+EOF
+```