claude-code-arcane 2.1.0 → 2.3.0

package/skills/interview-prep/SKILL.md

@@ -4,7 +4,7 @@ description: "Prepare for a job interview: company research, likely question ban
 argument-hint: "[application-note | company + role + round]"
 category: "career"
 user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, WebFetch
+allowed-tools: Read, Glob, Grep, Write, Edit, WebFetch, Task
 ---
 
 # Interview Prep - Preparación de entrevista
@@ -57,13 +57,21 @@ Preparás al usuario para una entrevista concreta: research de la empresa, banco
 1. Leer aplicación + empresa + perfil. WebFetch del sitio/notas de la empresa.
 2. Crear nota en `06-Entrevistas/` con el template `Entrevista`.
 3. Llenar research, banco de preguntas (marcando las top), STAR de las 3-5 historias clave, preguntas a hacer, red flags.
-4. Ofrecer un **mock**: vos hacés de entrevistador y das feedback sobre las respuestas.
+4. Ofrecer un **mock** con el agente `mock-interviewer` (ver abajo).
 5. Post-entrevista: ayudar a registrar feedback y definir próximo paso / follow-up (con `/cold-outreach`).
 
+## El mock va en un agente, no en esta sesión
+
+El mock lo corre el agente `mock-interviewer`, no vos. La razón es dura: vos acabás de escribir las respuestas STAR del usuario, así que ibas a preguntar exactamente lo que preparó, iba a salir perfecto, y el usuario iba a entrar a la entrevista real con confianza falsa.
+
+Al lanzarlo, pasale **inline**: el JD, la ronda, y el CV que se mandó. **No** le pases el perfil maestro ni la nota de `06-Entrevistas/` con las respuestas preparadas - eso invalida el simulacro, y el agente tiene instrucción de rechazarlos.
+
+Cuando devuelve el feedback, tu trabajo es registrarlo: agregá en la nota de `06-Entrevistas/` qué respuestas hay que rehacer y por qué. Ese es el valor que queda para la próxima ronda.
+
 ## Idioma
 
 En el idioma de la entrevista. Preparar respuestas en inglés si el rol es internacional, aunque la prep se converse en español.
 
 ## Handoff
 
-Pedí aprobación (approval) antes de escribir la nota en `06-Entrevistas/`. Cuando la prep está READY, ofrecé un mock; post-entrevista, seguí con `/cold-outreach` para el follow-up.
+Pedí aprobación (approval) antes de escribir la nota en `06-Entrevistas/`. Cuando la prep está READY, ofrecé el mock con `mock-interviewer` y registrá su feedback; post-entrevista, seguí con `/cold-outreach` para el follow-up.

package/skills/job-aplicar/SKILL.md

@@ -54,7 +54,11 @@ Usar el skill **cover-letter** según el canal de aplicación (formulario ATS
 
 ## Paso 7 - Reviewer (regla drafter-reviewer, obligatorio)
 
-Seguir `.claude/rules/drafter-reviewer.md`: lanzar UN agente general-purpose de contexto fresco con el JD + borradores inline; lectura acotada al perfil; research web breve de la empresa. Aplicar la Parte A (reemplazos exactos) e incorporar lo relevante de la Parte B. Una sola ronda. Never stuff keywords: los gaps se reconocen en el cover, no se rellenan en el CV. Normalizar guiones largos del texto sugerido.
+Seguir `.claude/rules/drafter-reviewer.md`: lanzar el agente **`cv-reviewer`** de contexto fresco con el JD + borradores inline y el perfil usado. Aplicar la Parte A (reemplazos exactos) e incorporar lo relevante de la Parte B. Una sola ronda. Never stuff keywords: los gaps se reconocen en el cover, no se rellenan en el CV. Normalizar guiones largos del texto sugerido.
+
+**Segunda lente si el rol es senior o la postulación importa:** lanzar `hiring-manager` **en paralelo** con `cv-reviewer` (no en cadena). Contesta si el CV convence a quien contrata, que es una pregunta distinta a si pasa el filtro. Sus 3 preguntas van a `## Notas` de la nota: son material directo de `/interview-prep`.
+
+Si el directorio de agentes no está instalado, el fallback con `general-purpose` está en la regla.
 
 ## Paso 8 - CONFIRMACIÓN 2: aprobar CV final
 

package/skills/job-hunt/SKILL.md

@@ -67,6 +67,7 @@ Según el estado del workspace, recomendar el skill siguiente (ver routing).
 | Corrida de búsqueda con CLIs y dedup entre corridas | `/job-scrape` |
 | Postulación completa (nota + CV + cover + review + PDF) | `/job-aplicar` |
 | Registrar resultado/avance de una postulación | `/job-outcome` |
+| ¿Ya me postulé acá? / exportar el registro a CSV | `/career-registry` |
 | Gaps de skills agregados + plan de estudio | `/job-upskill` |
 | Adaptar CV a una oferta | `/cv-tailor` |
 | Exportar CV a PDF ATS | `/cv-ats-export` |
@@ -75,6 +76,22 @@ Según el estado del workspace, recomendar el skill siguiente (ver routing).
 | Optimizar perfil de LinkedIn | `/linkedin-optimize` |
 | Crear/actualizar portfolio web | `/portfolio-site` |
 | Preparar una entrevista | `/interview-prep` |
+| Diagnosticar por qué se frena la búsqueda | agente `career-strategist` (vía `/job-upskill`) |
+
+## Los 4 agentes del perfil
+
+El perfil instala `agents/career/`. Los agentes existen por una sola razón: **hay lecturas que solo sirven con contexto fresco**. Vos no podés revisar un CV que acabás de escribir, ni entrevistar a alguien cuyas respuestas preparadas leíste. Son read-only: devuelven análisis, los archivos los escribe la sesión principal.
+
+| Agente | Contesta | Lo lanza |
+|---|---|---|
+| `cv-reviewer` | ¿Pasa el filtro del ATS y del recruiter? | `/job-aplicar`, `/cv-tailor`, `/cover-letter` |
+| `hiring-manager` | ¿Convence a quien contrata? (evidencia de impacto, no keywords) | `/job-aplicar`, `/cv-tailor` (opcional) |
+| `mock-interviewer` | ¿Aguanta la entrevista real? | `/interview-prep` |
+| `career-strategist` | ¿Por qué me frenan siempre en la misma etapa? | `/job-upskill` (10+ aplicaciones resueltas) |
+
+`cv-reviewer` y `hiring-manager` se lanzan **en paralelo** cuando van los dos: son lentes independientes, encadenarlos solo suma latencia.
+
+Si el usuario instaló el perfil sin el directorio de agentes, la regla `drafter-reviewer` documenta el fallback con `general-purpose`.
 
 ## Workflow estándar para una nueva oportunidad
 

package/skills/job-outcome/SKILL.md

@@ -35,14 +35,28 @@ Empresa/oferta indicada: `$ARGUMENTS`
    - `rechazado` con feedback → anotar la lección en la nota; si se acumulan 3+ resoluciones, ofrecer `/job-upskill` y revisar los criterios de búsqueda contra los resultados reales.
    - `sin_respuesta` a los 10-14 días → ofrecer follow-up con `/cold-outreach`.
    - `contratado` → 🎉 y actualizar el resto de las aplicaciones abiertas (¿retirarse de procesos?).
+   - **Freelance** - `en_conversacion` → ofrecer ensayar con el agente `discovery-call`; `contrato_activo` → crear la nota en `08-Contratos/`; `sin_respuesta` o `rechazado` acumulados (10+ propuestas resueltas) → ofrecer `/freelance-pipeline`, que es donde se ve si el problema es la propuesta o el targeting.
 
 6. **Confirmar** al usuario qué se registró (nota, campos tocados, fila del dashboard).
 
 ## Vocabulario de `estado` (frontmatter)
 
+Depende del `tipo:` de la nota. Leelo primero: son dos pipelines distintos y confundirlos rompe el dashboard y los reportes.
+
+**`tipo: aplicacion` (empleo, perfil `+job-hunt`):**
+
 `interesado → aplicado → entrevista → oferta` y cierra en: `contratado | rechazado | sin_respuesta | declinada | descartado`
 
-Emojis del dashboard: ⬜ interesado · ✅ aplicado · 📅 entrevista/oferta · ❌ rechazado/sin_respuesta/declinada · 🚫 descartado/cerrada
+**`tipo: freelance` (propuestas, perfil `+freelance`):**
+
+`interesado → screeneado → propuesta_enviada → en_conversacion → contrato_activo → entregado` y cierra en: `ganado_cerrado | sin_respuesta | rechazado | descartado | disputa`
+
+En freelance hay dos registros extra que no existen en empleo, y sin ellos `/freelance-pipeline` no puede calcular nada:
+
+- Al marcar `propuesta_enviada`, preguntar y registrar **cuántos Connects costó** (frontmatter `connects_gastados`) y agregar la fila al ledger de `07-Recursos/Connects - <año>.md`.
+- Si la oferta se cerró sin que el cliente contratara a nadie, el resultado en el ledger es `oferta_nunca_contrato`, no `sin_respuesta`. Son cosas distintas: la primera es Connects perdidos por mal screening, la segunda es tu propuesta que no convenció.
+
+Emojis del dashboard: ⬜ interesado/screeneado · ✅ aplicado/propuesta_enviada · 📅 entrevista/oferta/en_conversacion · 🔨 contrato_activo/entregado · ❌ rechazado/sin_respuesta/declinada · 🚫 descartado/cerrada · ⚠️ disputa
 
 ## Reglas
 

package/skills/job-upskill/SKILL.md

@@ -4,7 +4,7 @@ description: "Aggregate skill gaps across all scored job applications, weigh the
 argument-hint: "[url | nota de aplicación]"
 category: "career"
 user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Bash, WebFetch, WebSearch
+allowed-tools: Read, Glob, Grep, Write, Bash, WebFetch, WebSearch, Task
 ---
 
 # /job-upskill - Análisis de gaps y plan de estudio
@@ -13,6 +13,14 @@ Detecta qué skills te están costando puntos de match en las ofertas reales y a
 
 Argumento: `$ARGUMENTS` (vacío = modo agregado; URL o nota = modo targeted)
 
+## Antes del plan: ¿el gap es real o de presentación?
+
+Este skill asume que la respuesta es estudiar. A veces no lo es: si la experiencia está en el perfil maestro pero no llega al CV, el plan de estudio manda al usuario a aprender meses lo que ya sabe.
+
+En **modo agregado con 10+ aplicaciones resueltas**, lanzar primero el agente `career-strategist` (contexto fresco, read-only). Diagnostica el embudo completo y separa gap real de gap de presentación. Si el punto de fuga no es la etapa técnica, decílo antes del heatmap: el plan de estudio no es la palanca y conviene ir a `/cv-tailor` o `/interview-prep`.
+
+Con menos de 10 resueltas, saltear: no hay volumen para un embudo y el propio agente lo va a rechazar. Seguí directo al modo agregado.
+
 ## Modo agregado (sin argumento)
 
 1. **Recolectar evidencia.** Grep de `match_score:` en `03-Aplicaciones/*.md` (excluir `_index`; aceptar también el campo legacy `score:` de notas viejas). De cada nota leer: `match_score`, `estado`, `perfil`, y los gaps mencionados en las secciones "Match con mi perfil" / "Gaps reales" y los gaps reconocidos en `## Notas`.
@@ -55,4 +63,4 @@ Argumento: `$ARGUMENTS` (vacío = modo agregado; URL o nota = modo targeted)
 
 ## Handoff
 
-Reporte COMPLETE en `07-Recursos/`. Retomar el pipeline con `/job-aplicar` en las ofertas abiertas, o `/job-scrape` para una corrida nueva apuntando a los gaps que ya se están cerrando.
+Reporte COMPLETE en `07-Recursos/`. Retomar el pipeline con `/job-aplicar` en las ofertas abiertas, o `/job-scrape` para una corrida nueva apuntando a los gaps que ya se están cerrando. Si el `career-strategist` ubicó la fuga fuera de la etapa técnica, el siguiente paso es ese (`/cv-tailor`, `/interview-prep` o `/job-search`), no el plan de estudio.

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
+```