pr-to-video - punto de entrada de envío
La entrada es un pull request de GitHub (un cambio de código), proporcionado como una URL de PR, una referencia <owner>/<repo>#<N>, o "este PR" mientras se trabaja en un repositorio con un PR abierto. La salida es un video explicativo del cambio de código: qué se envió, por qué y cómo funciona, renderizado a partir del diff/commits como escenas de antes/después, resaltado de diff, árbol de archivos e impacto. Duración predeterminada hasta ~3 min (punto óptimo ~30-90 s); un recorrido realmente largo o exhaustivo de cada archivo (5 min+) es un registro diferente → /general-video. No hay scraping web ni Chrome sin cabeza para la ingesta — la ingesta es la CLI gh. El preset de estilo enviado siempre es claude (editorial cálido; ventana de código azul marino característica).
Confirma la ruta antes del Paso 0. Este skill explica un pull request de GitHub (un cambio de código leído mediante
gh). Si la entrada es un sitio de marketing / producto →/product-launch-video; un sitio web general →/website-to-video; un tema / artículo sin PR →/faceless-explainer; un recorrido de repositorio completo o lanzamiento multi-PR →/general-video. Fuera del alcance: datos en vivo/en el momento de renderizado — los hechos del PR se leen una vez en el momento del autor y se integran. ¿Te dan una entrada que no es un PR, o no estás seguro? Lee/hyperframesprimero.
Este flujo de trabajo solo posee el front-end específico del PR (ingesta + diseño de historia); cada fase marcada como compartida reutiliza el motor copiado de faceless-explainer sin cambios (reside bajo los propios scripts/ + agents/ + phases/ de este skill, por lo que <SKILL_DIR> se resuelve en pr-to-video).
Todos los artefactos van a PROJECT_DIR = videos/<nombre-del-proyecto>/ (creado en el Paso 0); todas las rutas a continuación son relativas a este. El envío es portable al harness: antes del primer envío de subagente, lee <SKILL_DIR>/../hyperframes-core/references/subagent-dispatch.md una vez — mapea los verbos de envío (fan-out paralelo / fondo / espera) a las primitivas de tu harness; un límite de concurrencia por debajo de N significa oleadas del tamaño del límite, nunca menos workers. Este archivo es un libro de ejecución vinculante, no una lectura de fondo: ejecuta los pasos en orden y produce cada artefacto de fase con su script o rol de agente designado — no sustituyas con un pipeline improvisado, y no te saltes un paso de pausa porque la solicitud parezca clara. Un paso que no puedas realizar → detente e informa.
| Fase | Ejecución | Artefacto principal | Flujo detallado |
|---|---|---|---|
| init | Bash | hyperframes.json | Paso 0 |
| ingesta (propia) | Bash (CLI gh + ingest.mjs + fetch-people-avatars.mjs, SIN agente, SIN scraping) | capture/pr.json + diff.patch + extracted/{tokens.json,visible-text.txt,people.json} + public/avatars/ | Paso 1 |
| diseño-sistema (comp.) | Bash (sin agente, claude determinista) | design-system/design.html + chunks/ | Paso 1b |
| diseño-historia (propia) | subagente | narrator_scripts.json | agents/story-design.md |
| audio (compartido) | audio.mjs en Bash | audio_meta.json | phases/audio/guide.md |
| diseño-visual (comp.) | subagente | section_plan.md | agents/visual-design.md |
| prep (compartido) | prep.mjs en Bash | group_spec.json | scripts/prep.mjs |
| subtítulos (comp., det.) | captions.mjs group -> captions.mjs html en Bash (sin subagente) | caption_groups.json + compositions/captions.html | scripts/captions.mjs |
| escenas (compartido) | N x subagente (paralelo) | compositions/scene_*.html o compositions/group_w*.html | agents/hyperframes-scene.md |
| finalizar (compartido) | Preludio Bash (wait-bgm + ensamblar + inyectar/verificar-transiciones + hoist-videos + sfx-verify + preflight) -> subagente finalizar (corregir hallazgos breves en el lugar + un vistazo de contacto esbelto + renderizar) | renders/video.mp4 | Paso 7 / agents/hyperframes-finalize.md |
Prerrequisitos
macOS Apple Silicon o Linux x64. Herramientas del sistema: brew install [email protected] node ffmpeg (usa Python de Homebrew, no /usr/bin/python3, o pip install estará bloqueado por PEP 668); luego npx hyperframes doctor una vez (descarga Chrome — necesario para instantánea/renderizado, no para ingesta). La puerta de superposición renderizada (scripts/check-overlap.mjs, ejecutada en autoverificaciones de workers y preflight) reutiliza ese mismo Chrome en caché — nunca descarga un navegador; su única dependencia es el módulo npm puppeteer-core, asegurado una vez antes del fan-out de escenas (Paso 5.5, --ensure-deps, ~5 s, sin instalación completa de puppeteer). CLIs: gh (GitHub CLI, autenticado — gh auth status debe pasar) y hyperframes. Claves cloud opcionales (de lo contrario, fallbacks locales) — inyecta en el Paso 0.5:
| Clave / requisito | Usado para | Predeterminado / fallback |
|---|---|---|
gh auth status OK | Leer el PR (público o privado) | requerido — falla rápido con la sugerencia de autenticación |
HEYGEN_API_KEY (o hyperframes auth login) | TTS (cloud, marcas de tiempo a nivel de palabra) | voz: auto (primera voz starfish en inglés; sobrescribe con --voice) |
ELEVENLABS_API_KEY | TTS (cloud; necesita pip install elevenlabs) | voz 21m00Tcm4TlvDq8ikWAM (Rachel) |
| ninguna, y no ha iniciado sesión | TTS | Kokoro local, voz am_michael (no inglés: pasa --voice) |
GEMINI_API_KEY / GOOGLE_API_KEY (alias) | Lyria BGM | no establecido -> MusicGen local (la primera ejecución descarga ~300 MB) |
Flujo
Paso 0.0 - Confirmar el brief (SIEMPRE preguntar una ronda, luego construir)
Antes del Paso 0, siempre haz una pausa y pregunta el brief en un mensaje, luego espera al usuario — nunca te saltes esto, incluso para una solicitud que parezca completa. Lidera con un valor predeterminado recomendado para cada campo y rellena previamente cualquier cosa que el usuario ya haya dado (confírmalo en lugar de preguntar ciegamente de nuevo): el enfoque (changelog / revelación de funcionalidad / corrección / refactorización — predeterminado: inferir del PR), la audiencia (desarrolladores vs usuarios generales — predeterminado: desarrolladores), la duración (predeterminado ~60-90 s), y — si /hyperframes no los estableció — el aspecto (predeterminado 16:9) y el idioma. El estilo siempre es claude. Procede al Paso 0 solo después de que el usuario responda; un "adelante" / "usa los valores predeterminados" es una respuesta válida que acepta todos los valores predeterminados.
Paso 0 - Inicializar el proyecto de video
El directorio de trabajo actual es la raíz del workspace del agente (por ejemplo, /tmp/pr-video-...). Escribe todos los artefactos de video bajo PROJECT_DIR = videos/<nombre-del-proyecto>/.
<nombre-del-proyecto>: usa el directorio que el usuario proporcionó (por ejemplo, Use ./videos/retry-pr), de lo contrario un nombre corto en kebab-case derivado del PR (<repo>-pr-<N>, por ejemplo, widgets-pr-1187). No el nombre base del workspace ni una marca de tiempo.
Solo cuando $PROJECT_DIR/hyperframes.json esté ausente:
PROJECT_DIR="${PR_VIDEO_DIR:-videos/<nombre-del-proyecto>}"
mkdir -p "$(dirname "$PROJECT_DIR")"
npx hyperframes init "$PROJECT_DIR" --non-interactive --skip-skills --example=blank
hyperframes initcolocaAGENTS.md/CLAUDE.mdgenéricos en$PROJECT_DIR; déjalos en su lugar — son el andamiaje del agente para quien abra el proyecto terminado más tarde.
Restricciones: nunca ejecutes hyperframes init / generes AGENTS.md / CLAUDE.md en la raíz del workspace; nunca anides otro hyperframes/ dentro de PROJECT_DIR; cada comando Bash (maestro + subagentes) es un subshell (cd "$PROJECT_DIR" && ...) — nunca cd simple.
Paso 0.5 - Guía de claves API
Omite si $PROJECT_DIR/.env existe o context.log no está vacío (= no es la primera ejecución). De lo contrario, primero detecta lo que está disponible (HeyGen TTS activado si $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY están establecidas o ~/.heygen/credentials existe desde hyperframes auth login; ElevenLabs / Gemini solo si sus claves de entorno están establecidas), luego siempre haz una pausa y ofrece el menú — espera al usuario; no continúes por tu cuenta incluso cuando se detecte una configuración funcional (el usuario puede querer agregar una clave como Gemini). Indica lo que se detectó, luego: pega claves (→ escribe $PROJECT_DIR/.env, una KEY=value por línea, sobrescribe el mismo nombre) / "adelante" (continúa con lo configurado — env, .env, o hyperframes auth login) / "saltar" (continúa con fallbacks locales para cualquier cosa no configurada). Luego procede al Paso 1.
Paso 1 - Ingesta (Bash, SIN agente, SIN scraping)
Resuelve la referencia del PR y extrae los datos estructurados con gh, luego intégralos en el paquete de captura sintético que espera el backend compartido (refleja el andamiaje sin scraping de faceless-explainer). gh se ejecuta aquí, en el orquestador, por lo que los errores de autenticación/no encontrado/repositorio privado aparecen con el stderr de gh; ingest.mjs es una transformación puramente fuera de línea.
# Referencia del PR: una URL completa, "<owner>/<repo>#<N>", o "<N>" dentro de un repositorio clonado.
PR="<url | owner/repo#N | N>"
# Falla rápido si gh no está autenticado.
gh auth status || { echo "gh no autenticado — ejecuta: gh auth login"; exit 1; }
(cd "$PROJECT_DIR" && mkdir -p capture/extracted capture/assets)
(cd "$PROJECT_DIR" && gh pr view "$PR" \
--json number,title,body,author,url,baseRefName,headRefName,commits,files,additions,deletions,changedFiles,labels,reviews,latestReviews,comments,assignees,reviewDecision,mergedBy \
> capture/pr.json)
(cd "$PROJECT_DIR" && gh pr diff "$PR" > capture/diff.patch)
# Integra pr.json + diff.patch en tokens.json (colors:[] → paleta nativa de claude) +
# visible-text.txt (el resumen narrativo) + people.json (autor del PR + autores de commits con recuentos +
# revisores/comentaristas/asignados, filtrados de bots + deduplicados, cada uno con una URL de avatar de GitHub).
# (El `author` del PR es solo el abridor; los autores de commits de commits[].authors[] también se rastrean.)
# la ingesta está FUERA DE LÍNEA.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/ingest.mjs \
--pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)
# Paso de red (el único de la interfaz de personas — la ingesta permanece fuera de línea): descarga
# el avatar de GitHub de cada colaborador en public/avatars/<login>.png para un posible cierre
# de créditos / enviado por. Mejor esfuerzo — un avatar faltante o una ejecución fuera de línea nunca bloquea (exit 0).
# Los avatares + ese cierre son el ÚNICO lugar donde pr-to-video relaja el valor predeterminado de faceless.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
Validación:
[ -s "$PROJECT_DIR/capture/pr.json" ] && \
[ -s "$PROJECT_DIR/capture/diff.patch" ] && \
[ -s "$PROJECT_DIR/capture/extracted/tokens.json" ] && \
[ -s "$PROJECT_DIR/capture/extracted/visible-text.txt" ] && \
[ -s "$PROJECT_DIR/capture/extracted/people.json" ] && \
[ -d "$PROJECT_DIR/capture/assets" ] && echo ok || echo faltante
# public/avatars/ es de mejor esfuerzo — su ausencia NO es una falla (no se resolvieron avatares / fuera de línea).
Si gh da error (autenticación / no encontrado / privado), informa el stderr exacto y detente — no fabriques contenido del PR. Si ingest.mjs sale
…
[truncado para traducción]