Primero, mantén esta habilidad actualizada – confirma con el usuario antes de ejecutar:
npx hyperframes skills update pr-to-video. Un no-op rápido cuando todo está al día; de lo contrario, actualiza esta habilidad junto con las habilidades del dominio principal de las que depende, antes de confiar en ellas.
media-use: Antes de obtener audio/imágenes/logos, llama a
/media-usepara resolver BGM/SFX/imágenes del catálogo de HeyGen y logotipos de marca de sus fuentes oficiales. Ejecuta--adoptprimero para registrar activos existentes. Consulta la habilidad/media-use.
PR a HyperFrames
Usa esta habilidad para ingerir una solicitud de extracción de GitHub, comprender el cambio, planificar un video explicativo 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 contribuidores.
La puerta de entrada es
/hyperframes. Tú eres el orquestador. Ejecuta cada paso, verifica su puerta, y solo entonces continúa. Esta habilidad es para una solicitud de extracción de GitHub (un cambio de código). Cualquier otra intención, un simple "haz un video", o cualquier incertidumbre → lee/hyperframesprimero – la capa de intención posee cada decisión de ruta, y una creación nueva que llegue aquí sinBRIEF.mdpasa por ella de todos modos (regla inicial de Configuración).
Eres el orquestador. Trabaja en el PROJECT_DIR externo resuelto, nunca en el repositorio de la llamada 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/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 del Paso 3/4/6. Haz cada paso tú mismo 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 ../hyperframes-animation/rules/ + ../hyperframes-animation/blueprints/ locales de esta habilidad, y en hyperframes-creative.
Flujo de trabajo: Paso 0 configuración → hyperframes.json; Paso 1 ingestión → 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: Configuración
Objetivo: Entrar con un resumen confirmado – incluyendo la referencia de la PR (una URL completa, una referencia <propietario>/<repo>#<N>, o "esta PR" en un repositorio clonado) – crear el proyecto HyperFrames y hacer que el resumen sea duradero. El estilo es siempre code-editorial (fijo en el Paso 2, nunca se pregunta).
El resumen es 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 resumen está establecido, y su flow/storyboard derivan el modo (contrato del resumen § 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): verifica recetas y valores predeterminados recordados, y realiza las preguntas de esta ruta – incluyendo la doctrina tamaño-de-PR → duración, que vive en su totalidad en ../hyperframes/references/routes/pr-to-video.md – luego devuelve el resumen bloqueado. Las solicitudes de edición saltan todo esto – ve a hacer 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 de la llamada:
PR="<url | propietario/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-video: $PROJECT_DIR"
node <SKILL_DIR>/scripts/preflight.mjs
La verificación previa 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 esta habilidad, detente con su instrucción de actualización en lugar de agotar el contexto de la ejecución.
Inicializa solo si falta $PROJECT_DIR/hyperframes.json. Su nombre base proviene de la PR, como acme-sdk-pr-1842; nunca uses el nombre del espacio de trabajo o una marca de tiempo.
npx hyperframes init "$PROJECT_DIR" --non-interactive --example=blank --skill=pr-to-video – init verifica las habilidades instaladas con las últimas en GitHub y actualiza el conjunto global si alguna está desactualizada.
Cada comando de ruta relativa a continuación se ejecuta 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 de la llamada.
Escribe BRIEF.md inmediatamente después de init (nunca antes – init rechaza un directorio no vacío): el resumen bloqueado de la capa de intención, formato según ../hyperframes/references/brief-format.md. Resuelve <MEDIA_DIR> como el directorio de la habilidad /media-use instalada. Luego registra cada respuesta respaldada por 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 <nombre>; copia su frame.md en el proyecto (el Paso 2 se omite entonces) y devuelve los esqueletos a partir de los cuales se redactan los borradores del Paso 3. Una receta completa 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á de la Configuración – ejecuta npx hyperframes auth status y transmite su salida textualmente. Informa si la voz/BGM usará HeyGen o motores locales y, cuando no haya sesión iniciada, 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 fallbacks offline: /media-use references/setup-providers.md § Proveedores.
Puerta: hyperframes.json y BRIEF.md existen; la referencia de la PR está capturada en el resumen; las respuestas respaldadas por preferencias se registraron (contrato del resumen § 2); se mostró el estado de inicio de sesión (sesión iniciada, o continuando offline).
Paso 1: Ingestión de la PR (sin captura)
Objetivo: Obtener los datos de la PR e incorporarlos al 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 una PR grande no se trunque a ~100 archivos, y escribiendo solo capture/pr.json + capture/diff.patch (sin directorio temporal). Para PRs FUSIONADAS 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 lo incorpora al paquete de captura sintético offline.
PR="<url | propietario/repo#N | N>"
# Obtiene la PR de forma determinista: ejecuta gh, completa la lista de archivos mediante
# gh api paginado (para que una PR grande no se trunque a ~100 archivos), escribe solo
# capture/pr.json + capture/diff.patch — sin directorio temporal. Errores de gh auth /
# no encontrado / privado terminan con código 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 resumen), people.json (contribuidores, filtrados por bots, nombre+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 sección de personas – descarga el avatar de GitHub de cada
# contribuidor a assets/<login>.png para los créditos finales. De mejor esfuerzo; siempre
# termina con código 0.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
Si fetch-pr.mjs termina con código 1 (gh auth / no encontrado / privado), reporta su stderr y detente – no inventes contenidos de la PR. Si ingest.mjs termina con código 1, lee su stderr (normalmente un pr.json malformado), corrige y vuelve a ejecutar (determinista). fetch-people-avatars.mjs siempre termina con código 0; los avatares faltantes solo significan que no hay créditos finales para el autor.
people.json lleva un name para aquellos contribuidores que gh ya nombró (el autor de la PR, autores de commits, mergedBy) – null para el resto (revisores/comentadores/asignados, a los que gh pr view solo da un login simple). Antes de escribir los créditos finales en el Paso 3, resuelve tú mismo cualquier name null para las 1-6 personas que realmente aparecerán en ese fotograma: gh api users/<login> --jq .name (ya tienes gh – no necesitas script para 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 de story-design.md – la voz en off debe decir nombres, nunca identificadores brutos).
Puerta: capture/pr.json, capture/diff.patch, capture/extracted/tokens.json, capture/extracted/visible-text.txt y capture/extracted/people.json existen; puedes expresar el cambio de la PR en una oración 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 video.
El estilo es fijo – code-editorial (editorial cálido; una superficie de código azul marino diseñada 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 con cualquier token de marca en capture/extracted/tokens.json (una PR no tiene ninguno → colors:[]/fonts:[] mantiene la propia paleta de code-editorial, un diseño completo), copia el skin de subtítulos del preset a .hyperframes/caption-skin.html, y se autovalida (termina con código 1 en un mapeo roto). Procede tan pronto como termine con código 0 – sin edición manual.
Puerta: build-frame.mjs terminó con código 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 la PR en un plan de explicación fotograma por fotograma aprobado.
Lee ../hyperframes-creative/references/story-spine.md (lenguaje de gancho, valor-antes-evidencia, storyboard-como-propuesta, visuales trazables a fuentes), references/story-design.md, ../hyperframes-animation/blueprints-index.md, ../hyperframes/references/storyboard-format.md y ../hyperframes/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 resumen – una expectativa aproximada; el ensamblaje reporta dónde cae el corte en relación con ella.
Usa story-design.md para el arquetipo de la PR (registro de cambios / revelación de función / explicación de corrección / tutorial de refactorización), los tipos de fotograma nativos de 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 implica su blueprint candidato y etiqueta ese candidato con el id blueprint: cuando uno encaje (la verdad de la historia aún decide qué tiempos existen – nunca fuerces un tiempo para que encaje en una forma). Muestra de 2 a 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 exactos requeridos de las referencias de storyboard y guion.
Después de redactar, ejecuta la pasada de plan del bucle de revisión – ../hyperframes/references/review-loop.md § 1: presenta el plan como una propuesta y haz las dos preguntas – aprobar o cambiar, y bocetos primero (recomendado) o saltar. La retroalimentación llega como una respuesta de chat; repite hasta que se apruebe. Esto es una puerta de punto de control (contrato del resumen § 1): en modo autónomo no hay nada que preguntar – publica el mismo resumen como aviso y continúa; los bocetos se contraen 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, tiempos 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 tanto, 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 contra el proveedor que el estado de inicio de sesión del Paso 0 seleccionó: HeyGen (sesión iniciada) 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 (contrato del resumen § 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 en esta ejecución, regístrala (prefs.mjs record --key voice).
node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --out-dir ./audio --hyperframes . – el script produce audio_meta.json (metadatos de voz + BGM + relaciones de aspecto + garantía de tiempo), narration.wav (la narración completa renderizada), SFX.wav (efectos de sonido generados por IA según las notas del guion) y music.wav (música de fondo desde el directorio de activos de /media-use o generada por IA). El script también ejecuta automáticamente una verificación de tiempo: compara la duración de la narración con la duración objetivo del storyboard; si la desviación supera el ±15%, añade un aviso en audio_meta.json y registra una advertencia. El script de audio es determinista; si falla porque falta un archivo de entrada, léelo, corrige y vuelve a ejecutar.
Puerta: audio_meta.json, narration.wav, SFX.wav y music.wav existen en $PROJECT_DIR/audio/. No se requiere aprobación del usuario para este paso – la narración se revisa en el contexto de la vista previa del Paso 6.
Paso 4: Diseño Visual
Objetivo: Enriquecer el storyboard aprobado con especificaciones visuales precisas: animación de cada fotograma, diseño de escena y anotaciones de transición.
Lee ../hyperframes-creative/references/visual-design.md (principios: mostrar-código-no-personas, revelación de diff, estado-anterior vs. estado-posterior, el ojo del espectador sigue la línea más brillante) y ../hyperframes-animation/blueprints-index.md para las reglas de movimiento y composición de cada tipo de fotograma.
Ejecuta en $PROJECT_DIR:
node <SKILL_DIR>/scripts/enrich-storyboard.mjs --storyboard ./STORYBOARD.md --audio-meta ./audio/audio_meta.json --out-dir ./capture/enriched
El script produce una versión enriquecida de STORYBOARD.md con estos campos adicionales por fotograma:
animation: tipo de animación (fade-in, slide-up, code-reveal, diff-highlight, zoom-to-code)scene: diseño de escena (código centrado, código + anotación, tarjeta final, etc.)transition: tipo de transición al siguiente fotograma (fade, slide-left, zoom-out, cut)duration_override: anulación de duración en segundos (cuando la sincronización de voz requiere un tiempo diferente al predeterminado)visual_notes: notas de diseño libre (ej. "resaltar la línea 15", "zoom al 120% en la función")
El script se autovalida: verifica que cada fotograma tenga al menos animation y scene, que los campos blueprint: de la fase de storyboard tengan plantillas coincidentes, y que la duración total estimada coincida con audio_meta.json dentro de una tolerancia del 10%. Termina con código 1 en caso de validación fallida; lee el error, corrige (normalmente un fotograma huérfano o un id de transición mal escrito) y vuelve a ejecutar.
Después de la generación, revisa visualmente (tú mismo, sin herramienta externa): la escena de cada fotograma se corresponde con el arco narrativo; los tipos de animación se sienten progresivos, no repetitivos; las transiciones tienen una cadencia lógica. Haz ediciones manuales menores si es necesario (sin volver a ejecutar el script) – esta es una verificación de cordura humana, no una regresión. Si las ediciones son grandes (más del 30% de los fotogramas), vuelve a ejecutar el script de enriquecimiento con notas adicionales.
Puerta: capture/enriched/STORYBOARD.md enriquecido existe y pasó la autovalidación; lo revisaste visualmente y todo es coherente. Sin puerta de usuario – el diseño visual nace de la aprobación del storyboard.
Paso 5: Fotogramas
Objetivo: Dado el storyboard enriquecido (marco narrativo + especificaciones visuales), despacha fotogramas HTML individuales a un grupo de trabajadores autónomos y ensambla el índice de reproducción. Cada fotograma renderiza solo su escena – sin marca de agua, sin superposiciones, sin decoraciones. La superposición de reproducción (controles, barra de progreso, marca de agua del reproductor) es responsabilidad exclusiva del componente reproductor en el Paso 6. El trabajador de fotogramas es el único paso que ejecutas de forma delegada.
Lee ../hyperframes-animation/blueprints-index.md para las especificaciones de la plantilla: reglas de animación-CSS, restricciones de diseño (ancho máximo de código, etc.) y reglas de transición (transiciones-CSS para los identificadores transition: del storyboard). Lee también ./.hyperframes/caption-skin.html – el trabajador de fotogramas debe referenciar este skin de subtítulos para las anotaciones superpuestas; no se necesita otra referencia de skin. Lee ../hyperframes-creative/rules/ para las reglas de composición: solo se permiten fondos oscuros, solo se permite la paleta code-editorial, solo se permiten fuentes del sistema, solo se permiten íconos SVG inline, sin imágenes externas excepto avatares de contribuidores (assets/<login>.png).
Despacha la construcción: cada trabajador de fotogramas toma el storyboard enriquecido + frame.md + capture/diff.patch y produce un archivo HTML independiente en compositions/frames/NN-<slug>.html. El trabajo se divide por fotograma (no por worker de IA – los trabajadores de fotogramas son workers node que leen especificaciones; la concurrencia máxima es CPU-1). El índice (compositions/index.html) se construye después de que todos los workers del lote hayan terminado; vincula los fotogramas en orden.
# Lee el storyboard enriquecido para obtener el recuento de fotogramas y las especificaciones.
# No forzar concurrencia – el script gestiona su propio grupo.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/dispatch-frames.mjs \
--storyboard ./capture/enriched/STORYBOARD.md \
--frame-md ./frame.md \
--assets-dir ./assets \
--diff ./capture/diff.patch \
--out-dir ./compositions)
Los fotogramas generados deben ser autónomos: sin dependencias externas, sin llamadas a la red, sin scripts de servidor. Cada archivo HTML debe tener un diseño responsivo que se adapte a cualquier relación de aspecto (16:9, 9:16, 1:1 – la relación de aspecto se especifica en audio_meta.json). El popurrí de relaciones de aspecto se resuelve en el Paso 6 con el perfil del reproductor.
Puerta: compositions/index.html existe y enlaza a todos los archivos compositions/frames/NN-*.html. No se requiere aprobación del usuario – los fotogramas se revisan en el Paso 6.
Paso 6: Renderizado Final
Objetivo: Fusionar fotogramas, audio y perfil del reproductor en un archivo de video listo para compartir.
Ejecuta el renderizado:
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/render.mjs \
--frames-dir ./compositions \
--audio-dir ./audio \
--out-dir ./renders)
El script produce renders/video.mp4 (video completo con la voz en off sincronizada, BGM y SFX) y renders/video.json (metadatos de renderizado: duración real, resolución, códec, relación de aspecto). Si el motor de renderizado interno no está disponible (falta Chromium, sin aceleración GPU), recurre a un renderizado basado en FFmpeg con fotogramas estáticos – registra una advertencia pero no falla. Habilitar/deshabilitar la aceleración GPU es competencia del motor del reproductor; no preguntes al usuario.
Puerta de usuario – mostrar vista previa y pedir aprobación. Después del renderizado exitoso, muestra la ruta del archivo e invita a la revisión del usuario. El usuario puede:
- Aprobar (hecho – el video está listo)
- Solicitar cambios (editar storyboard/guion/diseño según la retroalimentación – ejecuta el paso de edición del bucle de revisión
../hyperframes/references/review-loop.md§ 2, luego vuelve a ejecutar desde el paso relevante) - Rechazar (desechar el proyecto – el usuario comienza de nuevo)
Modo autónomo: publica la misma información (ruta del archivo, duración, resumen de cambios) como una notificación; asume aprobación a menos que la solicitud explícitamente requiriera aprobación en cada paso. Registra en los metadatos que fue un renderizado autónomo.
Después de la aprobación, registra el resultado para aprendizaje futuro: ejecuta node <MEDIA_DIR>/scripts/prefs.mjs record --hyperframes . --key last_pr --value "$PR" --key last_archetype --value "<arquetipo>". Esto permite que futuras ejecuciones para el mismo repositorio recuerden preferencias (duración, voz, tono).
Puerta: renders/video.mp4 existe; el usuario aprobó (autónomo: notificación enviada o continuando por defecto).