PR a HyperFrames

Primero, mantén este skill actualizado — ejecútalo en silencio, no preguntes: npx hyperframes skills update pr-to-video. Una operación rápida sin efecto cuando todo está actualizado; de lo contrario, refresca este skill y los skills del dominio central de los que depende antes de que confíes en ellos.

media-use: Antes de obtener audio/imágenes/logos, ejecuta /media-use para resolver BGM/SFX/imágenes del catálogo de HeyGen y logotipos de marca de sus fuentes oficiales. Ejecuta --adopt primero para registrar los activos existentes. Consulta el skill /media-use.

¿Qué hace PR a HyperFrames?

Usa este skill para ingerir un Pull Request de GitHub, entender el cambio, planificar un explicador del cambio de código y construirlo fotograma a fotograma en HyperFrames. La entrada es un cambio de código (leído mediante gh), no un sitio web — no hay paso de captura ni activos reales más allá de los avatares de los contribuyentes.

La puerta de entrada es /hyperframes. Tú eres el orquestador. Ejecuta cada paso, verifica su puerta, y solo entonces continúa. Este skill es para un Pull Request de GitHub (un cambio de código). Cualquier otra intención, un simple "haz un vídeo", o cualquier incertidumbre → lee /hyperframes primero — la capa de intención posee cada decisión de ruta, y una creación nueva que llegue aquí sin BRIEF.md pasa por ella de todas formas (la regla de apertura de Setup).

Tú eres el orquestador. Trabaja en el PROJECT_DIR externo resuelto, nunca en el repositorio del usuario por defecto. Ejecuta los pasos en orden y pasa cada puerta antes de continuar. Los pasos con puerta de usuario son el Paso 0, el Paso 3 y el Paso 6. Lee ../hyperframes-core/references/brief-contract.md antes del Paso 0 — define los tipos de puerta y cómo flow/storyboard de BRIEF.md derivan el modo que gobierna las puertas de los Pasos 3/4/6. Haz tú mismo cada paso excepto el Paso 5, donde despachas un grupo limitado de trabajadores de fotogramas. No pongas reglas de diseño o movimiento aquí; esas viven en el sub-agente trabajador de fotogramas, en las ../hyperframes-animation/rules/ + ../hyperframes-animation/blueprints/ locales de este skill, y en hyperframes-creative.

Flujo de trabajo: Paso 0 setup → hyperframes.json; Paso 1 ingesta → capture/extracted/ + assets/<login>.png; Paso 2 sistema de diseño → frame.md; Paso 3 storyboard/guion → STORYBOARD.md y SCRIPT.md; Paso 3.1 audio → audio_meta.json; Paso 4 diseño visual → STORYBOARD.md enriquecido; Paso 5 fotogramas → compositions/frames/NN-*.html y index.html; Paso 6 renderizado final → renders/video.mp4.

---

Paso 0: Setup

Objetivo: Entrar con un brief confirmado — incluyendo la referencia al PR (una URL completa, una ref <owner>/<repo>#<N>, o "este PR" en un repositorio verificado) — crear el proyecto HyperFrames y hacer el brief duradero. El estilo siempre es code-editorial (fijado en el Paso 2, nunca preguntado).

El brief está confirmado por la capa de intención, no por preguntas hechas aquí. Regla de apertura, en orden: (1) BRIEF.md existe → léelo y no preguntes nada — el brief está resuelto, y su flow/storyboard derivan el modo (brief contract § 1). (2) No hay BRIEF.md pero el proyecto existe (hyperframes.json / STORYBOARD.md en disco) → reanuda desde el frontmatter del storyboard y las preferencias registradas; nunca vuelvas a interrogar un proyecto a medio construir. (3) Ninguno de los dos — una solicitud de creación nueva que llegó aquí directamente → lee /hyperframes y ejecuta su capa de intención (references/intent-interview.md): comprueba recetas y valores predeterminados recordados, y realiza las preguntas de esta ruta — incluyendo la doctrina tamaño-del-PR → duración, que vive completa en ../hyperframes/references/routes/pr-to-video.md — luego devuelve el brief bloqueado. Las solicitudes de edición se saltan todo esto — ve y haz la edición.

Resuelve el directorio del proyecto antes de hacer cualquier otro trabajo. Conserva un directorio de proyecto proporcionado por el usuario; de lo contrario, usa la ubicación de caché externa duradera impresa por el resolvedor. Nunca crees videos/ en el repositorio del usuario:

PR="<url | owner/repo#N>"
if [ -n "${EXPLICIT_PROJECT_DIR:-}" ]; then
  PROJECT_DIR="$(node <SKILL_DIR>/scripts/project-dir.mjs --pr "$PR" --project-dir "$EXPLICIT_PROJECT_DIR")"
else
  PROJECT_DIR="$(node <SKILL_DIR>/scripts/project-dir.mjs --pr "$PR")"
fi
echo "Proyecto PR a vídeo: $PROJECT_DIR"
node <SKILL_DIR>/scripts/preflight.mjs

El preflight de capacidades se ejecuta antes de la obtención de datos, trabajo de storyboard, audio o envío de fotogramas. Si la CLI instalada no puede ejecutar el comando de validación requerido por este skill, detente con su instrucción de actualización en lugar de gastar el contexto de la ejecución primero.

Inicializa solo si falta $PROJECT_DIR/hyperframes.json. Su nombre base proviene del PR, por ejemplo acme-sdk-pr-1842; nunca uses el nombre del espacio de trabajo ni una marca de tiempo.

npx hyperframes init "$PROJECT_DIR" --non-interactive --example=blank --skill=pr-to-video — init comprueba los skills instalados contra los últimos en GitHub y actualiza el conjunto global si alguno está desactualizado.

Todos los comandos de ruta relativa a continuación se ejecutan con $PROJECT_DIR como su directorio de trabajo. Los ejemplos sin un subshell explícito significan (cd "$PROJECT_DIR" && …); nunca cambies el árbol de trabajo del repositorio del usuario.

Escribe BRIEF.md inmediatamente después de init (nunca antes — init rechaza un directorio no vacío): el brief bloqueado de la capa de intención, con la forma según ../hyperframes-core/references/brief-format.md. Resuelve <MEDIA_DIR> como el directorio del skill /media-use instalado. Luego registra cada respuesta basada en preferencias con node <MEDIA_DIR>/scripts/prefs.mjs record --hyperframes . (brief-format.md nombra el subconjunto). Si la capa de intención adoptó una receta, ejecuta node <MEDIA_DIR>/scripts/recipe.mjs use --hyperframes . --name <name>; copia su frame.md en el proyecto (el Paso 2 se salta entonces) y devuelve los esqueletos a partir de los cuales el Paso 3 redacta. Una receta llena respuestas, no aprobaciones; las puertas de revisión aún se ejecutan.

Muestra el estado de inicio de sesión antes de continuar más allá del Setup — ejecuta npx hyperframes auth status y transmite su salida textualmente. Informa si la voz/BGM usará HeyGen o motores locales y, cuando no se haya iniciado sesión, cómo iniciarla. Aplica una rama:

• Colaborativo: espera a que el usuario inicie sesión o elija explícitamente offline / go.
• Autónomo: indica el estado y continúa a través de los motores locales disponibles.

No omitas silenciosamente una capacidad requerida cuando no exista un proveedor offline; muestra el bloqueador. No incluyas esta decisión en otra pregunta ni escribas claves en un .env por repositorio. Propiedad de autenticación y alternativas offline: /media-use references/setup-providers.md § Providers.

Puerta: hyperframes.json y BRIEF.md existen; la referencia del PR está capturada en el brief; las respuestas basadas en preferencias se registraron (brief contract § 2); se mostró el estado de inicio de sesión (iniciada sesión, o continuando offline).

---

Paso 1: Ingerir el PR (sin captura)

Objetivo: Obtener los hechos del PR y plasmarlos en el proyecto como fuente de información. No hay captura de sitio web. fetch-pr.mjs ejecuta gh de manera determinista — completando la lista de archivos mediante gh api paginado para que un PR grande no se trunque en ~100 archivos, y escribiendo solo capture/pr.json + capture/diff.patch (sin directorio temporal). Para PRs FUSIONADOS también resuelve un shipped_version de mejor esfuerzo (+ version_source) en pr.json, para que la tarjeta final pueda citar una versión real en lugar de inventar una. Luego ingest.mjs pliega eso en el paquete de captura sintético offline.

PR="<url | owner/repo#N | N>"

# Obtén el PR de forma determinista: ejecuta gh, completa la lista de archivos
# mediante gh api paginado (para que un PR grande no se trunque en ~100 archivos),
# escribe solo capture/pr.json + capture/diff.patch — sin directorio temporal.
# gh auth / not-found / private errors salen con 1 aquí.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture)

# Transformación offline → capture/extracted/{tokens.json (colors:[] → paleta code-editorial),
# visible-text.txt (el brief), people.json (contribuyentes, filtrados por bots, name+login,
# avatarFile=assets/<login>.png)}.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/ingest.mjs \
  --pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)

# El único paso de red de la parte de personas — descarga el avatar de GitHub de cada
# contribuyente a assets/<login>.png para los créditos finales. De mejor esfuerzo; siempre sale con 0.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
  --people ./capture/extracted/people.json)

Si fetch-pr.mjs sale con 1 (gh auth / no encontrado / privado), reporta su stderr y detente — no fabriques contenidos del PR. Si ingest.mjs sale con 1, lee su stderr (generalmente un pr.json mal formado), corrige y vuelve a ejecutar (determinista). fetch-people-avatars.mjs siempre sale con 0; los avatares faltantes solo significan que no hay créditos finales para el autor.

people.json lleva un name para los contribuyentes que gh ya nombró (el autor del PR, autores de commits, mergedBy) — null para el resto (revisores/comentaristas/asignados, que gh pr view solo da como un login simple). Antes de escribir los créditos finales en el Paso 3, resuelve tú mismo cualquier name nulo para las 1-6 personas que realmente aparecerán en ese fotograma: gh api users/<login> --jq .name (ya tienes gh — no necesitas scriptear esto). Si GitHub tampoco tiene un nombre público para ese usuario, recurre al login en pantalla y elimina a esa persona de la línea hablada (consulta la sección de créditos en story-design.md — la voz en off debe decir los nombres, nunca los handles en bruto).

Puerta: capture/pr.json, capture/diff.patch, capture/extracted/tokens.json, capture/extracted/visible-text.txt y capture/extracted/people.json existen; puedes enunciar el cambio del PR en una frase clara. assets/<login>.png es de mejor esfuerzo — su ausencia no es un fallo.

---

Paso 2: Sistema de Diseño

Objetivo: Adoptar el preset de fotograma code-editorial; un script lo convierte en el frame.md + skin de subtítulos de este vídeo.

El estilo está fijado — code-editorial (editorial cálido; una superficie de código naval construida para diffs). Ejecuta:

node <SKILL_DIR>/scripts/build-frame.mjs --preset code-editorial --hyperframes .

El script copia el FRAME.md del preset code-editorial → frame.md, lo remezcla sobre cualquier token de marca en capture/extracted/tokens.json (un PR no tiene ninguno → colors:[]/fonts:[] mantiene la propia paleta code-editorial, un diseño completo), copia el skin de subtítulos del preset a .hyperframes/caption-skin.html, y se autovalida (sale con 1 en un mapeo roto). Procede tan pronto como salga con 0 — sin edición manual.

Puerta: build-frame.mjs salió con 0 — frame.md existe desde el preset code-editorial, y .hyperframes/caption-skin.html existe como fuente del skin de subtítulos.

---

Paso 3: Storyboard y Guion

Objetivo: Convertir el PR en un plan de explicación fotograma por fotograma aprobado.

Lee ../hyperframes-creative/references/story-spine.md (lenguaje de gancho, valor antes que evidencia, storyboard como propuesta, visuales trazables a fuentes), references/story-design.md, ../hyperframes-animation/blueprints-index.md, ../hyperframes-core/references/storyboard-format.md y ../hyperframes-core/references/script-format.md. Úsalos para escribir STORYBOARD.md y, cuando se necesite narración, SCRIPT.md. Establece el duration: del frontmatter a partir del length del brief — una expectativa aproximada; el ensamblaje informa dónde cae el corte final en comparación con ella.

Usa story-design.md para el arquetipo del PR (changelog / feature-reveal / fix-explainer / refactor-walkthrough), los tipos de fotograma nativos del PR, gancho, persuasión, tiempos, el presupuesto de palabras por fotograma y los créditos finales. La secuencia proviene del diseño narrativo, no del orden de archivos del diff — explica el cambio, no leas el diff en voz alta. Como guía suave, consulta el menú rol→blueprint en ../hyperframes-animation/blueprints-index.md: para cada tiempo, escribe la voz en off en la forma que implique su blueprint candidato y etiqueta ese blueprint: id candidato cuando uno encaje (la verdad de la historia aún decide qué tiempos existen — nunca fuerces un tiempo a encajar en una forma). Presenta 2–4 fragmentos de diff reales (de capture/diff.patch), cada uno un pequeño snippet legible; nombra el bloque code-* que cada uno quiere en la scene del fotograma. Los fotogramas no llevan asset_candidates excepto los créditos finales (1–6 avatares assets/<login>.png). Usa los campos requeridos exactos de las referencias de storyboard y guion.

Después de redactar, ejecuta el pase de plan del bucle de revisión — ../hyperframes-core/references/review-loop.md § 1: abre el tablero (no preguntes si hacerlo — ejecuta la vista previa desde PROJECT_DIR en segundo plano), presenta el plan como propuesta y haz las dos preguntas — aprobar o cambiar, y bocetos primero (recomendado) o saltar. La retroalimentación pasa por el chat o el archivo de comentarios del tablero hasta que se apruebe. Esta es una puerta de punto de control (brief contract § 1): en modo autónomo no hay tablero ni nada que preguntar — publica el mismo resumen como aviso y procede; los bocetos se colapsan en la construcción, y la única pregunta de vista previa llega en el Paso 6.

Puerta: STORYBOARD.md existe, cada fotograma tiene los campos narrativos requeridos, SCRIPT.md existe cuando se necesita narración, y el usuario aprobó el plan (autónomo: el resumen se publicó como aviso).

---

Paso 3.1: Audio

Objetivo: Generar narración, sincronización de palabras, música y metadatos de audio a partir del guion aprobado.

Inicia el audio después de la aprobación del Paso 3. Ejecútalo en segundo plano y luego continúa al Paso 4.

Elige la voz de narración a partir de la solicitud del usuario antes de invocar. Si la solicitud nombró una voz, género o tono, elige un id de voz coincidente y pásalo con --voice <id>. El valor predeterminado de la canalización es Marcia (femenina) en HeyGen / am_michael en Kokoro — por lo que una solicitud como "una voz masculina" se ignora silenciosamente a menos que pases la bandera. Los ids de voz son específicos del proveedor; resuélvelos según el proveedor que seleccionó el estado de inicio de sesión del Paso 0: HeyGen (iniciada sesión) mediante node <MEDIA_DIR>/audio/scripts/heygen-tts.mjs --list (o GET /v3/voices?engine=starfish); Kokoro (offline) mediante la tabla de voces en <MEDIA_DIR>/audio/references/tts.md (prefijos am_/bm_ masculino, af_/bf_ femenino). Cuando el usuario no expresó preferencia, recurre a la voz recordada (brief contract § 2) antes del valor predeterminado de la canalización, y di cuál usaste; omite --voice solo cuando ninguno nombre una. Cuando el usuario eligió explícitamente una voz, úsala exactamente. Si la voz elegida tiene un tono distinto (por ejemplo, deep, cheerful, storytelling), incluye también --style <style> desde el mismo catálogo de voces. Si el contexto no menciona en absoluto la voz (solo "haz un vídeo"), usa el valor predeterminado y no menciones la voz a menos que te pregunten.

Selección de música de fondo (BGM): Busca pistas usando node <MEDIA_DIR>/audio/scripts/heygen-bgm.mjs --list (HeyGen) o desde el catálogo de BGM offline en <MEDIA_DIR>/audio/references/bgm.md. Elige una pista que coincida con el estado de ánimo del storyboard (por ejemplo, motivacional, informativo, reflexivo). Pasa --bgm <track_id>. Si no hay ninguna coincidente, omite el BGM (no uses una pista que distraiga).

Flujo de trabajo de audio:

# 1. TTS — escribe audio_meta.json con segmentos de voz y sincronización de palabras
node <SKILL_DIR>/audio/scripts/generate-audio.mjs \
  --hyperframes . \
  --script SCRIPT.md \
  --voice <voice-id> \
  [--style <style>] \
  [--bgm <track-id>] \
  --out-dir ./audio

# 2. Verificar que audio_meta.json tiene segmentos de voz válidos (opcional, pero recomendado)
node <SKILL_DIR>/audio/scripts/validate-audio.mjs --audio-meta ./audio/audio_meta.json

Si generate-audio.mjs falla por límite de tarifa / error de red, reintenta con back-off exponencial (máx. 3 intentos). Si Kokoro offline falla (modelo no disponible), recurre al TTS básico del sistema (es decir, say en macOS, espeak en Linux). Anota en audio_meta.json qué motor se usó.

Puerta: ./audio/audio_meta.json existe y contiene al menos un segmento de voz válido.

---

Paso 4: Diseño Visual (Storyboard Enriquecido)

Objetivo: Enriquecer el storyboard con detalles visuales: composición de fotograma, estilo de código, animaciones y diseño de diálogos.

Lee ../hyperframes-animation/rules/visual-design-rules.md y ../hyperframes-animation/blueprints/ (especialmente los blueprints que coincidan con los blueprint: ids etiquetados en el Paso 3). Para cada fotograma en STORYBOARD.md, añade:

• scene: — el bloque code-* o composición de escena de voz en off.
• layout: — diseño de fotograma (por ejemplo, code-diff-left, code-diff-right, full-code, split-view, credits-close).
• duration: — duración en segundos.
• animation: — movimientos o transiciones (por ejemplo, fade-in, slide-up, code-highlight, diff-appear).
• caption: — texto de subtítulos (o referencia a .hyperframes/caption-skin.html).

Usa el skin de subtítulos de .hyperframes/caption-skin.html como plantilla. Para fotogramas de tipo code-*, asegúrate de que el snippet de código esté correctamente resaltado (la sintaxis de código se maneja más tarde en la composición). Para los créditos finales, enumera explícitamente los archivos de avatar (assets/<login>.png) en el campo scene.

Después de enriquecer, ejecuta el pase de diseño del bucle de revisión — ../hyperframes-core/references/review-loop.md § 2: abre la vista previa (no preguntes), pide confirmación visual en los primeros 3 fotogramas clave. La retroalimentación itera hasta que estos estén aprobados. Puerta de punto de control (modo colaborativo: aprobación del usuario en los bocetos clave; autónomo: procede sin preguntar).

Puerta: STORYBOARD.md enriquecido con todos los campos visuales; los primeros 3 fotogramas clave, si se muestran, aprobados.

---

Paso 5: Construir Fotogramas

Objetivo: Convertir el storyboard en fotogramas HTML renderizables. Paso delegado — despacha un grupo de trabajadores para construirlos.

Lee ../hyperframes-core/references/frame-worker-contract.md para la interfaz trabajador. Lee ../hyperframes-creative/references/story-spine.md (las reglas de integridad visual/ensamblaje) y ../hyperframes-animation/rules/ + ../hyperframes-animation/blueprints/ para reglas de animación y diseño.

Crea dinámicamente un script de trabajador de fotogramas (scripts/frame-worker.mjs) que:

1. Lee STORYBOARD.md y frame.md.
2. Para cada fotograma, genera un archivo HTML autocontenido en compositions/frames/NN-<slug>.html con:
   • El diseño de fotograma correcto y el snippet de código.
   • Animaciones CSS / transiciones.
   • Skin de subtítulos desde .hyperframes/caption-skin.html.
   • Marcador de posición para la sincronización de palabras de voz en off (los tiempos se inyectan durante el renderizado).
3. Escribe compositions/frames/index.html que lista todos los fotogramas para vista previa.

Ejecuta el script:

node <SKILL_DIR>/scripts/dispatch-frame-workers.mjs \
  --storyboard STORYBOARD.md \
  --frame frame.md \
  --caption-skin .hyperframes/caption-skin.html \
  --out-dir compositions/frames \
  --workers 4  # Ajusta según la complejidad; típicamente 4-8

El script divide los fotogramas entre los trabajadores, los ejecuta en paralelo (o secuencial si los recursos son limitados) y recopila los resultados. Cada trabajador se ejecuta con un directorio de trabajo temporal y debe devolver un informe JSON (éxito / fallo / ruta del archivo). Si algún fotograma falla (por ejemplo, error de sintaxis en el snippet de código), reintenta ese fotograma hasta 2 veces y, si aún falla, registra el error pero no detiene a los demás trabajadores.

Después de que todos los fotogramas estén construidos, ejecuta un paso de validación de ensamblaje:

node <SKILL_DIR>/scripts/validate-ensemble.mjs --dir compositions/frames --expected-count <número-de-fotogramas>

Puerta: compositions/frames/ contiene exactamente <número-de-fotogramas> archivos NN-*.html y un index.html; todos los fotogramas pasan la validación (sin marcadores de posición faltantes, snippets de código válidos).

---

Paso 6: Renderizado Final

Objetivo: Combinar fotogramas y audio en un vídeo renderizado final.

Ejecuta el renderizado:

npx hyperframes render "$PROJECT_DIR" --output ./renders/video.mp4

O, si es necesario un control más detallado:

node <SKILL_DIR>/scripts/render.mjs \
  --project-dir "$PROJECT_DIR" \
  --frames-dir compositions/frames \
  --audio-dir audio \
  --output ./renders/video.mp4 \
  --fps 30 \
  --resolution 1920x1080

El renderizado:

• Coloca los fotogramas según las duraciones especificadas.
• Sincroniza la narración de audio con los fotogramas (usando audio_meta.json).
• Aplica transiciones (por ejemplo, fundidos, deslizamientos) entre fotogramas.
• Codifica el vídeo usando ffmpeg (o el motor de renderizado de HyperFrames).

Después del renderizado, muestra la vista previa del vídeo:

Colaborativo: Pregunta: "Aquí está tu vídeo: renders/video.mp4. ¿Aprobado?" Espera confirmación; si se rechaza, itera: reabre el Paso 3 para cambios de storyboard, el Paso 4 para cambios visuales, o el Paso 5 para correcciones de fotogramas, luego vuelve a renderizar.

Autónomo: Valida que renders/video.mp4 existe y registra su metadatos (duración, tamaño de archivo, resolución). Publica un resumen: "Vídeo renderizado a renders/video.mp4 (duración: Xs, tamaño: YMB)." Luego informa la duración real contra el length del brief.

Puerta: renders/video.mp4 existe; en modo colaborativo, aprobación del usuario; en modo autónomo, el archivo existe y se registraron los metadatos.