claude-code-arcane 2.0.0 → 2.2.0

package/docs/SKILLS-CATALOG.md

@@ -1,6 +1,8 @@
 # Skills Catalog — Claude Code Arcane
 
-Catalogo completo de los 337 skills disponibles para proyectos consumidores. Organizados por division.
+Los 388 skills disponibles para proyectos consumidores, organizados por division.
+
+La tabla cubre 346: hay 42 skills instalables que todavia no estan catalogados aca. Un test de CI (`src/__tests__/doc-counts.test.ts`) verifica que estos numeros coincidan con el filesystem y que el header de cada seccion coincida con sus filas.
 
 ## Como ejecutar un skill
 
@@ -98,7 +100,27 @@ Desde cualquier proyecto que tenga Arcane configurado, escribi `/` seguido del n
 
 ---
 
-## General (55 skills)
+## Audio (13 skills)
+
+| Skill | Descripcion | Uso |
+|-------|-------------|-----|
+| `/audio-bible` | Identidad sonora: paleta, emotional targets por game state, frequency allocation, standards | `[full\|core\|standards]` |
+| `/audio-spec` | SFX spec sheets y event lists con concurrencia, cooldown y prioridad | `[system-name \| all \| events]` |
+| `/music-composition` | Armonia, melodia, forma, groove, orquestacion con salida accionable | `[harmony\|melody\|form\|groove\|orchestration\|analyze]` |
+| `/adaptive-music` | Musica interactiva: layering, re-secuenciacion, stingers, sync points, histeresis | `[design\|layers\|transitions\|stingers\|map]` |
+| `/midi-compose` | Genera `.mid` desde spec JSON con scripts Python stdlib-only | `[spec-path \| new \| validate]` |
+| `/sfx-design` | Capas attack/body/tail, variacion, round-robin, anti-repeticion | `[sound-name \| layers \| variation \| review]` |
+| `/procedural-audio` | Footsteps, viento y ambientes por sintesis; decision y presupuesto de CPU | `[decide \| footsteps \| wind \| ambience \| budget]` |
+| `/ui-sound-design` | Feedback de UI: duraciones y niveles por tipo, jerarquia, haptics, accesibilidad | `[set \| event-name \| review \| haptics]` |
+| `/spatial-audio` | HRTF vs Ambisonics vs panning, atenuacion, oclusion vs obstruccion, presupuesto | `[decide \| hrtf \| ambisonics \| occlusion \| budget]` |
+| `/audio-mix` | Jerarquia de buses, ducking, mix states, masking, loudness | `[buses \| ducking \| states \| loudness \| review]` |
+| `/middleware-integration` | Wwise/FMOD: containers, eventos, Switch/State/RTPC, banks, contrato con codigo | `[structure \| events \| rtpc \| banks \| contract]` |
+| `/voice-pipeline` | VO: naming, script con contexto, casting, barks, localizacion, batch | `[script \| casting \| naming \| loc \| barks]` |
+| `/audio-audit` | QA: voice count, CPU, memoria, leaks, loudness ASWG-R001, conformidad de assets | `[full \| perf \| loudness \| assets \| platform]` |
+
+---
+
+## General (54 skills)
 
 | Skill | Descripcion | Uso |
 |-------|-------------|-----|
@@ -455,6 +477,27 @@ Desde cualquier proyecto que tenga Arcane configurado, escribi `/` seguido del n
 
 ---
 
+## Second Brain (14 skills)
+
+| Skill | Descripcion | Uso |
+|-------|-------------|-----|
+| `/second-brain` | Entry point: crea o adopta el vault (PARA + Zettelkasten + hub files), escribe su CLAUDE.md y su cache hot.md, detecta plugins, conecta otros proyectos al mismo vault y rutea | `[setup\|adopt\|status\|next\|link]` |
+| `/brain-dump` | Captura sin friccion al dump del dia: sin tags, sin clasificar, sin decidir donde va | `[texto a capturar]` |
+| `/review-dump` | Procesa el dump: clasifica item por item con confirmacion, actualiza hubs, rutea tareas y crea el daily | `[today\|YYYY-MM-DD]` |
+| `/review-weekly` | Retrospectiva semanal: temas recurrentes, hilos abiertos y tareas hechas vs no hechas | `[current\|YYYY-Www\|YYYY-MM-DD]` |
+| `/review-monthly` | Retrospectiva mensual: patrones, logros con evidencia, semillas y salud del vault | `[current\|YYYY-MM]` |
+| `/zettel` | Nota atomica con el criterio de cuando una idea pasa de nota de proyecto a permanente | `[idea\|ruta#seccion\|dump YYYY-MM-DD]` |
+| `/hub-note` | Hub file (MOC) por entidad que importa: el tejido entre PARA y Zettelkasten | `[entidad] [--update]` |
+| `/vault-recall` | Busqueda con ranking (BM25, acentos plegados, expansion por alias) y notas relacionadas por vocabulario compartido, via indice cacheado | `<consulta> \| related <nota> [-n N]` |
+| `/vault-clip` | URL a nota limpia: contenido sin menus ni banners, con resumen propio y fuente | `<url> [--full\|--summary]` |
+| `/vault-audit` | Reporte de salud via script Python: huerfanas, links roto, stale, semillas que no crecieron, contradicciones, tag sprawl, nombres duplicados. Read-only | `[--vault <path>] [--stale-days N]` |
+| `/vault-tidy` | Aplica los arreglos del audit con approval item por item. Nunca borra, archiva | `[orphans\|broken\|duplicates\|tasks\|frontmatter\|archive\|all]` |
+| `/obsidian-markdown` | Sintaxis Obsidian: wikilinks, embeds, callouts, block IDs, propiedades. Valida o corrige una nota | `[reference\|check <archivo>\|fix <archivo>]` |
+| `/obsidian-bases` | Archivos .base: vistas, filtros, formulas y summaries. Incluye migracion desde Dataview | `[create <desc>\|explain <archivo>\|migrate <query>]` |
+| `/obsidian-canvas` | Archivos .canvas (JSON Canvas): nodos, grupos y edges con direccion y color | `[create <desc>\|explain <archivo>\|edit <archivo>]` |
+
+---
+
 ## E-Commerce (12 skills)
 
 | Skill | Descripcion | Uso |

package/docs/USER-GUIDE.md

@@ -2,7 +2,7 @@
 
 ## What is Arcane?
 
-Arcane is a configuration harness for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It provides a curated library of **337 skills**, **87 agents**, **15 hooks**, and **20 rules** that you selectively deploy into any project. Instead of shipping everything to every project (wasting tokens and degrading performance), you pick a **profile** that matches your stack and only the relevant tools get installed.
+Arcane is a configuration harness for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It provides a curated library of **388 skills**, **98 agents**, **16 hooks**, and **26 rules** that you selectively deploy into any project. Instead of shipping everything to every project (wasting tokens and degrading performance), you pick a **profile** that matches your stack and only the relevant tools get installed.
 
 ## Table of Contents
 
@@ -536,7 +536,7 @@ Yes, and it's recommended. This way everyone on the team gets the same Claude Co
 
 ### How many tokens does a profile consume?
 
-Each skill adds ~30-100 tokens to the system prompt. A typical base profile (20-30 skills) adds ~1-2k tokens. The core profile adds ~500 tokens. Compare that to loading all 333 skills, which is why selective deploy matters.
+Each skill adds ~30-100 tokens to the system prompt. A typical base profile (20-30 skills) adds ~1-2k tokens. The core profile adds ~500 tokens. Compare that to loading all 388 skills, which is why selective deploy matters.
 
 ### Why replace instead of merge on install?
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-arcane",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Skills, agents, hooks and rules for Claude Code — installable via npx arcane",
   "type": "module",
   "bin": {

package/profiles/audio.yaml

@@ -0,0 +1,45 @@
+name: audio
+description: "Game Audio — direccion sonora, composicion, sound design, middleware, VO y QA"
+type: base
+
+skills:
+  - audio-bible
+  - audio-spec
+  - music-composition
+  - adaptive-music
+  - midi-compose
+  - sfx-design
+  - procedural-audio
+  - ui-sound-design
+  - spatial-audio
+  - audio-mix
+  - middleware-integration
+  - voice-pipeline
+  - audio-audit
+
+rules:
+  universal:
+    []
+  gamedev:
+    - audio-code
+
+agents:
+  - audio
+
+permissions:
+  allow:
+    - "Bash(python *)"
+    - "Bash(python3 *)"
+    - "Bash(git status*)"
+    - "Bash(git add*)"
+    - "Bash(git commit*)"
+    - "Bash(git diff*)"
+    - "Bash(git log*)"
+    - "Bash(ls *)"
+    - "Bash(find *)"
+    - "Read(*)"
+    - "Glob(*)"
+    - "Grep(*)"
+  deny:
+    - "Bash(rm -rf *)"
+    - "Bash(git push --force*)"

package/profiles/second-brain.yaml

@@ -0,0 +1,37 @@
+name: second-brain
+description: "Second Brain — vault de Obsidian gestionado con Claude Code: captura sin friccion, reviews diario/semanal/mensual, notas atomicas y hub files (PARA + Zettelkasten), busqueda con ranking, captura web, auditoria de salud del vault y sintaxis nativa de Obsidian (markdown, Bases, Canvas)"
+type: addon
+
+skills:
+  - second-brain
+  - brain-dump
+  - review-dump
+  - review-weekly
+  - review-monthly
+  - zettel
+  - hub-note
+  - vault-recall
+  - vault-clip
+  - vault-audit
+  - vault-tidy
+  - obsidian-markdown
+  - obsidian-bases
+  - obsidian-canvas
+
+rules:
+  universal:
+    - vault-conventions
+  gamedev:
+    []
+
+agents:
+  []
+
+permissions:
+  allow:
+    - "Bash(python *vault_audit.py*)"
+    - "Bash(python3 *vault_audit.py*)"
+    - "Bash(python *vault_index.py*)"
+    - "Bash(python3 *vault_index.py*)"
+  deny:
+    []

package/rules/gamedev/audio-code.md

@@ -0,0 +1,45 @@
+---
+paths:
+  - "src/audio/**"
+---
+
+# Audio Code Rules
+
+- NEVER hardcode asset paths or clip references in gameplay code — post middleware events by name/ID
+- Gameplay code MUST NOT call `Play()`/`PlayOneShot()` directly — raise an audio event, let the audio layer resolve it
+- Concurrency limits (max instances, priority, cooldown) MUST be declared in data, never enforced with ad-hoc counters in gameplay
+- Use delta time for ALL fades, ducking ramps and RTPC interpolation (frame-rate independence)
+- NO static singletons for audio state — inject the audio service
+- Every RTPC/parameter driven from gameplay must be normalized and clamped at the boundary before it reaches the middleware
+- Voice budget is a hard limit: define max simultaneous voices per category and drop by priority, never let it grow unbounded
+- Audio must degrade silently — a missing bank or failed event NEVER throws into the gameplay frame
+- Keep the audio update off the render-critical path; audio work budget is 5-10% of frame time
+- Reference the audio bible section each event implements in code comments
+
+## Examples
+
+**Correct** (event-driven, data-declared):
+
+```csharp
+// Gameplay raises intent; the audio layer owns resolution and limits.
+audioService.Post(AudioEvent.PlayerFootstep, transform.position);
+
+float wetness = Mathf.Clamp01(surface.Wetness);       // clamped at the boundary
+audioService.SetParameter(AudioParam.SurfaceWetness, wetness);
+
+// Fade driven by delta time, not frame count.
+currentVolume = Mathf.MoveTowards(currentVolume, targetVolume, fadeRate * Time.deltaTime);
+```
+
+**Incorrect** (hardcoded, direct, frame-dependent):
+
+```csharp
+AudioSource.PlayClipAtPoint(
+    Resources.Load<AudioClip>("SFX/footstep_concrete_01"),  // VIOLATION: hardcoded path
+    transform.position);                                     // VIOLATION: direct playback from gameplay
+
+AudioManager.Instance.Play("footstep");   // VIOLATION: static singleton
+
+currentVolume -= 0.02f;                   // VIOLATION: no delta time
+audioService.SetParameter(AudioParam.SurfaceWetness, rawSensorValue);  // VIOLATION: unclamped
+```

package/rules/vault-conventions.md

@@ -0,0 +1,144 @@
+# Vault Conventions Rule (second brain en Obsidian)
+
+Reglas que gobiernan toda escritura dentro de un vault de Obsidian. Existen porque un agente que escribe notas sin restricciones degrada el vault mas rapido de lo que lo construye: linkea todo con todo, arrastra tareas en silencio y renombra archivos rompiendo `[[wikilinks]]`.
+
+Las rutas son relativas al vault (`--vault`, env `OBSIDIAN_VAULT`, o el directorio actual si contiene `.obsidian/`).
+
+## Cuando aplica
+
+- Cualquier skill del profile `second-brain` que cree o edite notas.
+- Cualquier escritura en un directorio que contenga `.obsidian/`, incluso desde otro skill.
+- NO aplica a los archivos de configuracion del vault (`.obsidian/**`): no se tocan nunca sin pedido explicito del usuario.
+
+## Quién escribe cada archivo
+
+Antes de tocar cualquier cosa, la pregunta es de quién es ese archivo. Hay tres clases y el permiso de escritura es distinto en cada una. Adaptado de la distinción **autorado / proyectado** de la base de conocimiento de producto de Educabot, que es la que hace que un agente y una persona escriban en el mismo repositorio sin pisarse.
+
+| Clase | Quién escribe | Qué puede hacer el agente | Ejemplos |
+|---|---|---|---|
+| **Autorado** | La persona. Cambia lento | **Nada sin approval.** Ni reformatear, ni "mejorar" | Dumps, notas atómicas, hubs, clips, proyectos, el `CLAUDE.md` del vault, la sección `## Reflexión` de los reviews |
+| **Sintetizado** | El agente, con approval, y queda como nota permanente | Proponer y escribir tras el OK. Idempotente: correr dos veces no duplica | Dailies, weeklies, monthlies, el `## Historial` de un hub |
+| **Proyectado** | El agente, sin preguntar. Derivado y descartable | Reescribir completo cuando corresponda | `hot.md`, el índice `.vault-index.json`, las vistas `.base` |
+
+Tres consecuencias que resuelven las dudas que aparecen en la práctica:
+
+- **Lo proyectado no se edita a mano.** Si el usuario lo edita, el próximo review lo pisa. Por eso `hot.md` lleva la advertencia adentro.
+- **Lo proyectado no es fuente de verdad.** Si contradice a una nota, la nota gana. Se puede borrar sin perder nada.
+- **Lo autorado no se toca ni para arreglarlo.** Si una nota del usuario tiene el frontmatter roto, se propone el arreglo; no se aplica solo. La excepción son las categorías que `/vault-tidy` aplica con approval item por item.
+
+Si no sabés en qué clase cae un archivo, es autorado. El default es no escribir.
+
+## El vault apunta, no copia
+
+Cuando algo ya tiene una fuente de verdad afuera, el vault guarda **el puntero y el porqué**, nunca una copia:
+
+| Contenido | Fuente de verdad | En el vault |
+|---|---|---|
+| Código y arquitectura | El repo | `repos:` en el frontmatter, y `codebases.md` con el path local |
+| Tickets, estados, sprints | Jira, ClickUp, Linear | Link, y la decisión que salió de ahí |
+| Diseños | Figma | Link en la nota del tema |
+| Artículos, papers | La web | El clip, con `source:` y **tu** resumen |
+
+Una copia se desactualiza en silencio y después hay dos verdades y ninguna gana. Lo que sí acumula el vault es lo que ninguna de esas fuentes tiene: **qué decidiste, por qué, y qué aprendiste**. Eso no vive en Jira ni en el código.
+
+## Resolución de rutas: roles, no carpetas
+
+Ningún skill escribe en una ruta literal. Escribe en un **rol**, y el `## Rutas` del `CLAUDE.md` del vault dice qué carpeta es ese rol en este vault. Es lo que hace que un vault adoptado con otra estructura funcione sin tocar los skills.
+
+| Rol | Qué contiene | Default del `setup` |
+|---|---|---|
+| `inbox` | captura cruda del día | `_inbox` |
+| `daily` | síntesis diaria | `Reflect/Daily` |
+| `weekly` | retrospectiva semanal | `Reflect/Weekly` |
+| `monthly` | balance mensual | `Reflect/Monthly` |
+| `atomic` | notas atómicas | `03_Resources` |
+| `hubs` | hub files por entidad | `Hubs` |
+| `projects` | proyectos con deadline | `01_Projects` |
+| `areas` | responsabilidades continuas | `02_Areas` |
+| `archive` | cerrado, nunca borrado | `04_Archive` |
+| `templates` | plantillas del usuario | `Templates` |
+
+Orden de resolución, sin excepciones:
+
+1. El `## Rutas` del `CLAUDE.md` del vault.
+2. Si el vault no lo declara, el default de la tabla, **avisándole al usuario que se está asumiendo**.
+3. Si el rol no existe en este vault (no todos tienen `areas`), preguntar antes de crear la carpeta.
+
+Los scripts reciben el mapeo por flag (`--role hubs=People`), nunca lo adivinan. **Si el `CLAUDE.md` del vault declara rutas distintas del default y un skill escribe en el default igual, eso es un bug del skill, no una preferencia.**
+
+## Las tres reglas de estructura
+
+### 1. Los links van hacia arriba, nunca hacia abajo
+
+Cada nota linkea a su contexto, no a su detalle:
+
+| Desde | Linkea a | Nunca a |
+|---|---|---|
+| Nota de `_inbox/` (dump) | hub files, proyectos, areas | otros dumps |
+| Daily | el dump del dia, notas creadas ese dia | otros dailies |
+| Weekly | los dailies de la semana | notas atomicas sueltas |
+| Monthly | los weeklies del mes | dailies |
+| Hub file | notas atomicas y proyectos del tema | dumps ni dailies |
+
+Sin esta regla el agente crea links bidireccionales en todas las direcciones y el grafo se vuelve ruido: cada nota apunta a todo y ninguna relacion significa nada. Los backlinks de Obsidian ya dan la direccion inversa gratis, no hay que escribirla.
+
+### 2. Ninguna nota se cierra sin al menos un `[[wikilink]]`
+
+Es la unica regla que previene las huerfanas de raiz. Si al terminar una nota no hay a que linkearla, esa es la senal de que falta un hub file: crear el hub (ver `/hub-note`) antes de cerrar la nota, o dejarla en `_inbox/` en vez de archivarla en `03_Resources/`.
+
+Excepcion: los dumps crudos de `_inbox/` pueden nacer sin links, porque los agrega `/review-dump`.
+
+### 3. Las tareas no hechas no se arrastran en silencio
+
+Una tarea abierta en el dump del lunes que sigue abierta el martes **se queda en el lunes**, marcada como cancelada (`- [-]`), y se crea de nuevo en el martes. No se mueve.
+
+No haber hecho algo un dia determinado es informacion. Arrastrar la tarea hacia adelante produce una lista limpia y una historia falsa.
+
+## Que no puede hacer el agente
+
+- **Nunca borrar una nota.** Mover a `04_Archive/` preservando el nombre. El borrado es decision del usuario, siempre.
+- **Nunca renombrar ni mover una nota sin approval explicito.** Rompe `[[wikilinks]]` en silencio: Obsidian solo los actualiza cuando el rename ocurre dentro de la app.
+- **Nunca editar en masa.** Una corrida toca las notas de esa corrida. Los cambios que afectan a muchas notas se proponen como plan y los aplica `/vault-tidy` con approval item por item.
+- **Nunca tocar `Templates/`** salvo pedido explicito: son el contrato del usuario, no del agente.
+- **Nunca reescribir la seccion de reflexion del usuario.** Los reviews sintetizan hechos; la interpretacion la escribe el usuario.
+
+## Contrato de frontmatter
+
+Todo campo que un skill escriba tiene que estar declarado en el `CLAUDE.md` del vault. Un campo que no esta en el contrato no se inventa: se propone y se agrega al contrato primero.
+
+Minimo por tipo de nota:
+
+```yaml
+---
+created: 2026-07-27        # ISO, nunca se reescribe
+type: daily                # daily | weekly | monthly | dump | atomic | hub | project | area | clip
+tags: []
+---
+```
+
+Los tipos con campos propios (`status` en proyectos, `source` en clips) los declara el skill que los crea.
+
+## Convenciones de escritura
+
+- Nada de guiones largos: si un texto generado trae em-dash o en-dash, normalizar a `-` antes de escribir.
+- `[[wikilinks]]` para todo lo interno, `[texto](url)` solo para URLs externas. Obsidian trackea renames de wikilinks, no de markdown links.
+- Fechas ISO (`YYYY-MM-DD`) en frontmatter y en nombres de archivo de notas periodicas.
+- Una idea por nota atomica. Si una nota necesita dos titulos de nivel `##` que no se relacionan, son dos notas.
+
+## La estructura no la sostiene este archivo
+
+Una convención que solo vive en un documento se muere en tres meses. Lo que la sostiene es lo que corre:
+
+| Convención | Qué la hace cumplir |
+|---|---|
+| Frontmatter completo, notas con al menos un link | El hook `PostToolUse` de `second-brain`, al escribir |
+| Huérfanas, links roto, nombres duplicados, semillas que no crecen | `/vault-audit`, cada vez que se corre |
+| Contradicciones sin resolver | `status: contested`, que el audit lista y el monthly mira |
+| Rutas por rol | El `## Rutas` del contrato, que los skills leen antes de escribir |
+| Tareas que no se arrastran | El paso de tareas de `/review-dump`, y `stale_open_tasks` en el audit |
+
+Si una regla nueva de este archivo no tiene una columna derecha, es una intención, no una regla. Antes de agregarla, preguntá qué la va a hacer cumplir.
+
+## Git como red de seguridad
+
+El vault deberia ser un repo git. Antes de una corrida que escribe varias notas (`/review-dump`, `/vault-tidy`), verificar que el arbol este limpio y avisar al usuario si no lo esta. Es lo que permite deshacer una corrida completa sin revisar nota por nota.

package/skills/adaptive-music/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: adaptive-music
+description: "Musica interactiva para juegos: layering vertical, re-secuenciacion horizontal, stingers, reglas de transicion con sync points, y mapeo de estados de gameplay a musica. Usar para: musica adaptativa, sistema de musica dinamica, transiciones musicales, combat music."
+category: "audio"
+argument-hint: "[design|layers|transitions|stingers|map]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+# adaptive-music — Sistemas de Música Interactiva
+
+Diseña el sistema que decide **qué música suena cuándo** y **cómo pasa de un estado a otro sin que se escuche la costura**.
+
+Esta skill diseña el sistema. El material musical lo escribe `/music-composition`; la implementación en middleware la baja `/middleware-integration`.
+
+## Cuándo usar
+
+- Cuando la música tiene que responder a gameplay y no alcanza con reproducir un track
+- Cuando las transiciones entre estados (exploración → combate → victoria) suenan a corte
+- Cuando el loop fatiga y necesitás variación estructural, no otro track
+- Antes de que el compositor escriba una nota: el sistema condiciona cómo se compone
+
+## Modos
+
+| Modo | Qué hace |
+|---|---|
+| `design` | El sistema completo: eje dominante, capas/segmentos, matriz, stingers, parámetros |
+| `layers` | Solo la arquitectura vertical: qué capas, qué rol, qué restricción compositiva |
+| `transitions` | Solo la matriz de transiciones con sync points y segmentos de transición |
+| `stingers` | Solo los stingers: armonía, sincronización, cooldown |
+| `map` | Solo la tabla estado de gameplay → música, con triggers e histéresis |
+
+## Input
+
+1. Leer audio bible, sección 2 (emotional targets por game state) y 6 (music direction). Si no existe, avisar y ofrecer `/audio-bible`
+2. Listar los estados de gameplay reales — del código o del GDD, no inventados
+3. Preguntar al usuario: middleware target (Wwise / FMOD / engine nativo / sin definir), budget de memoria para música, y si hay material compuesto o se parte de cero
+
+---
+
+## Los dos ejes
+
+Todo sistema de música adaptativa es una combinación de estos dos. Elegir cuál domina es la primera decisión.
+
+### Vertical — layering
+
+Un mismo bloque temporal, capas que entran y salen. Todas suenan sincronizadas porque comparten grid y armonía.
+
+- **Fuerte en:** respuesta inmediata a parámetros continuos (proximidad de enemigo, salud, intensidad de combate)
+- **Débil en:** cambiar de material. Todo suena a la misma pieza
+- **Costo:** memoria (N stems simultáneos) y una restricción compositiva real — cada capa debe funcionar sola y en toda combinación
+
+### Horizontal — re-secuenciación
+
+Segmentos distintos que se concatenan según reglas, con transiciones en puntos musicalmente válidos.
+
+- **Fuerte en:** cambiar de material y de forma; estructura no repetitiva
+- **Débil en:** respuesta inmediata. La transición espera el sync point
+- **Costo:** latencia de respuesta (hasta un compás o más) y complejidad de reglas
+
+**Recomendación:** vertical para intensidad continua, horizontal para cambios de estado discretos. La mayoría de los juegos necesitan los dos: capas dentro de cada segmento, re-secuenciación entre segmentos.
+
+---
+
+## Sync points — dónde se puede cortar
+
+Una transición suena bien o mal según **dónde** ocurre, no según el crossfade. De más responsivo a más musical:
+
+| Sync point | Latencia | Cuándo usarlo |
+|---|---|---|
+| **Inmediato** | 0 | Emergencias (muerte del jugador). Suena a corte, y a veces eso está bien |
+| **Siguiente beat** | hasta 1 beat | Reacción rápida que igual respeta el pulso |
+| **Siguiente compás (bar)** | hasta 1 compás | El default sano para la mayoría de los casos |
+| **Siguiente grid** | variable | Cuando definís una grilla más gruesa (2 o 4 compases) |
+| **Exit cue** | hasta el fin del segmento | Máxima musicalidad, máxima latencia |
+| **Entry cue del destino** | — | Define desde dónde arranca el segmento destino |
+
+**Segmento de transición** — un fragmento corto que se inserta entre origen y destino. Resuelve los saltos que ningún sync point salva: cambio de tonalidad, de tempo o de métrica. Es la herramienta que más mejora un sistema y la que menos se usa.
+
+En Wwise esto es la Transition Matrix del Music Switch Container: origen × destino, con Exit Cue del origen, Entry Cue del destino, fade in/out, y segmento de transición opcional. En FMOD el equivalente son transition regions y transition timelines. El concepto es el mismo; la nomenclatura cambia.
+
+---
+
+## Stingers
+
+Frases cortas que se superponen sin interrumpir la música de fondo, sincronizadas al grid para que no suenen encima del tiempo equivocado.
+
+- Uso: eventos puntuales que merecen puntuación musical — descubrimiento, kill, item raro, fallo
+- **Deben compartir armonía con el material de fondo**, o sonar deliberadamente disonantes. Un stinger en la tonalidad equivocada es el error más audible del sistema
+- Sincronizar a beat o compás, nunca inmediato
+- Definir cooldown: dos stingers superpuestos suenan a error
+- Si el fondo modula, el stinger necesita versiones por tonalidad o tiene que ser tonalmente neutro (percusión, cluster, ruido)
+
+---
+
+## Diseño del mapeo
+
+El entregable central: la tabla estado → música.
+
+| Estado de gameplay | Trigger | Segmento / capas | Sync point | Notas |
+|---|---|---|---|---|
+| Explore calm | default | bed + pulse | bar | loop indefinido |
+| Explore alert | enemigo a <30 m | + harmony | beat | vuelve a calm con 5 s de histéresis |
+| Combat | combate iniciado | segmento combat, todas las capas | bar | |
+| Combat low health | HP < 25% | + intensity, filtro | beat | |
+| Victory | combate resuelto | stinger + segmento victory | exit cue | one-shot, vuelve a explore |
+| Death | HP = 0 | inmediato, corte | inmediato | |
+
+**Parámetros continuos** aparte: qué RTPC/parámetro maneja qué, con rango normalizado y curva.
+
+| Parámetro | Rango | Controla | Curva |
+|---|---|---|---|
+| `combat_intensity` | 0-1 | volumen de capa intensity | log |
+| `player_health` | 0-1 | filtro low-pass sobre el bus música | lineal |
+
+---
+
+## Histéresis — el detalle que rompe los sistemas
+
+Un estado que se calcula por umbral (`enemigo a <30 m`) va a oscilar cuando el jugador camine en el borde. El resultado es música entrando y saliendo cada segundo.
+
+Toda transición basada en umbral necesita:
+- **Umbrales distintos por dirección** — entra a 30 m, sale a 40 m
+- **Tiempo mínimo en estado** — no se puede salir antes de N segundos
+- **Debounce del trigger** — la condición tiene que sostenerse antes de contar
+
+Sin esto, el sistema funciona en el editor y falla con un jugador real.
+
+---
+
+## Enfoques generativos
+
+Cuando la variación por capas y segmentos no alcanza:
+
+- **Selección estocástica de capas/segmentos** — la variación sale de qué combinación suena. El más barato y controlable; empezar acá siempre
+- **Cadenas de Markov** — melodía estocástica entrenada sobre material propio. Preserva idioma, no genera estructura
+- **L-systems / gramáticas recursivas** — generan estructura jerárquica por reescritura de reglas. Complemento de Markov, que no tiene forma
+- **Restricciones armónicas** — capa de validación sobre lo generado: el generador propone, las reglas de función y voice leading filtran
+
+La generación de notas en tiempo real tiene un techo de calidad y un riesgo de que suene mal en producción que la selección de material pregrabado no tiene. Justificar antes de ir por ahí.
+
+---
+
+## Proceso
+
+1. **Listar estados reales** del gameplay, con sus triggers exactos
+2. **Elegir el eje dominante** (vertical / horizontal / mixto) y justificarlo contra el budget
+3. **Definir capas o segmentos** y la restricción compositiva que impone al compositor
+4. **Llenar la matriz de transiciones** con sync points, y marcar dónde hace falta segmento de transición
+5. **Definir stingers** con su armonía y cooldown
+6. **Definir parámetros continuos** con rango y curva
+7. **Agregar histéresis** a toda transición por umbral
+8. **Presentar** al usuario y preguntar "¿Escribo el diseño a `<path>`?" antes de usar Write
+
+---
+
+## Verdict
+
+- **READY** — la matriz está completa, todo umbral tiene histéresis, los stingers tienen armonía definida, y el compositor sabe qué restricción respetar
+- **CONCERNS** — el diseño existe pero hay transiciones sin sync point, umbrales sin histéresis, o el budget de memoria no se verificó contra el número de stems
+- **BLOCKED** — los estados de gameplay no están definidos, o no hay dirección musical de la cual derivar los emotional targets
+
+## Anti-patterns
+
+> → Read references/anti-patterns.md
+
+## Next steps
+
+- `/music-composition` para escribir el material respetando las restricciones de capas
+- `/middleware-integration` para implementar la matriz en Wwise/FMOD
+- `/audio-mix` para el ducking entre música y diálogo
+- `/audio-audit` para verificar memoria y voice count del sistema en runtime

package/skills/adaptive-music/references/anti-patterns.md

@@ -0,0 +1,53 @@
+# Música Adaptativa — Anti-patterns
+
+## Crossfade como única transición
+
+Fundir dos piezas en tonalidades o tempos distintos suena a error, no a transición. El crossfade solo funciona si el material comparte armonía y grid. Si no, hace falta sync point + segmento de transición.
+
+## Transiciones inmediatas por default
+
+Cortar al instante es responsivo y musicalmente destructivo. Reservarlo para muerte del jugador y cortes deliberados. El default sano es siguiente compás.
+
+## Umbrales sin histéresis
+
+El caso clásico: el jugador camina en el borde de un radio de detección y la música de combate entra y sale seis veces en diez segundos. Umbrales asimétricos + tiempo mínimo en estado + debounce. Siempre.
+
+## Capas que dependen entre sí
+
+Si la capa de melodía se escribió asumiendo que la de armonía suena, al quitar la armonía la melodía queda flotando sin contexto. Cada capa tiene que funcionar sola y con cualquier subconjunto de las de abajo.
+
+## Stingers en la tonalidad equivocada
+
+El error más audible del sistema. Si el fondo modula y el stinger es tonal y fijo, va a chocar. Versiones por tonalidad, o stingers tonalmente neutros.
+
+## Stingers sin cooldown
+
+Cinco kills en dos segundos disparan cinco stingers superpuestos. Suena a bug.
+
+## Contar los stems y no la memoria
+
+Ocho stems estéreo a 48 kHz sonando simultáneos es mucho más que "ocho archivos". Si van descomprimidos en memoria, el número crece rápido. Verificar el budget antes de comprometer la arquitectura vertical.
+
+## Diseñar el sistema después de componer
+
+Si el compositor entregó una pieza lineal de tres minutos con clímax, convertirla en capas es imposible sin rehacerla. El sistema se diseña primero y define la restricción compositiva.
+
+## Un estado por situación
+
+Veinte estados de música para veinte situaciones de gameplay produce una matriz de transiciones de 400 celdas que nadie va a autorear bien. Agrupar situaciones por emotional target: la mayoría de los juegos vive bien con 4-6 estados.
+
+## Loop que cierra con cadencia auténtica
+
+Cada vuelta suena a arranque forzado. Cerrar abierto: semicadencia, pedal, cadencia plagal.
+
+## Música ocupando el rango del diálogo
+
+Si el arreglo vive en 500 Hz-2 kHz y hay VO, uno de los dos pierde, y el ducking agresivo se escucha. Se resuelve en el arreglo, no en el mix.
+
+## Ignorar el estado inicial y el retorno
+
+Se diseña explore → combat con cuidado y se olvida combat → explore. El retorno es la transición que el jugador escucha más veces.
+
+## Probar solo en el editor
+
+El editor de middleware permite disparar estados a mano, en el orden correcto, sin ruido. El jugador real dispara transiciones en secuencias imposibles. Probar con gameplay, no con botones.