Instalar HyperFrames
Reproduce, en una sola pasada, la integración que añade HyperFrames como proveedor de video siguiendo el contrato de tres pasos Añadir un Nuevo Proveedor en CLAUDE.md. Lista de verificación autocontenida de cada artefacto que debe existir; verifica cada uno y crea solo lo que falta.
Ejecuta este skill en lugar de derivar la integración desde cero. Es el registro canónico de lo que significa "HyperFrames está conectado" en este repositorio.
Cuándo invocarlo
- Clon nuevo del motor de marketing que aún no tenga soporte para HyperFrames.
- Un rebase o merge eliminó alguno de los artefactos siguientes (
router:checkse queja, el enrutamiento de video vuelve ahiggsfieldpara tareas de tipografía, o faltan.skills/hyperframes*/). - Un nuevo cliente quiere cortos programáticos / tipografía en movimiento / carretes de visualización de datos y la matriz necesita los tres tipos de tarea conectados.
- Al incorporar un nuevo operador que necesita un manual ejecutable con un solo comando en lugar de tener que leer tres commits.
Entradas
repo_root: cadena. Ruta absoluta al clon del motor de marketing. Por defecto:process.cwd().branch: cadena, opcional. Rama en la que hacer commit. Por defecto:claude/install-hyperframes. Crea la rama si no existe; nunca hace commit enmain.dry_run: booleano, opcional. Cuando es verdadero, imprime los cambios planificados y sale sin escribir.
Proceso
Ejecuta cada paso en orden. Cada paso es idempotente: volver a ejecutarlo en un repositorio ya integrado no hace nada para ese paso.
Paso 1 — Verificación previa
- Confirmar que
repo_rootcontieneCLAUDE.mdcon la línea## How to Add a New Provider. Negarse a ejecutar si falta (no es un repositorio del motor de marketing). - Confirmar que existen
lib/providers/video.ts,lib/providers/matrix.ts,lib/providers/types.tsylib/providers/__mocks__/video.ts. Negarse a ejecutar si falta alguno. - Confirmar que la rama activa no es
main. Si está enmain, crear y cambiar abranchprimero.
Paso 2 — Añadir los tres skills de ejecución
Crear estos tres directorios con los archivos SKILL.md. Cada archivo ya existe en la versión canónica dentro del árbol; copiar textualmente de la sección Conjunto de artefactos de referencia más abajo. Omitir un archivo si ya existe y su name en el frontmatter coincide.
.skills/hyperframes/SKILL.md— reglas de autoría de composición (diseño antes de animación, líneas de tiempo pausadas y registradas enwindow.__timelines, sinMath.random()/lógica basada en tiempo, variables declaradas mediantedata-composition-variables)..skills/hyperframes-cli/SKILL.md— bucle de desarrollonpx hyperframeslint → inspect → render. Siempre renderiza con--strict --strict-variables..skills/hyperframes-prompt-builder/SKILL.md— especialista invocado porvideo-prompt-buildercuando la matriz resuelve ahyperframes; carga tokens de marca desdeclients/<slug>/design.md, elige una plantilla segúntask_kind, devuelve una especificación de composición + argumentos de render.
Paso 3 — Actualizar el skill del despachador
En .skills/video-prompt-builder/SKILL.md:
- Añadir
hyperframes-prompt-buildera la lista de especialistas en el párrafo inicial y en la sección Skills relacionados. - Extender el enum de entrada
task_kindconmotion_typography,data_viz_reel,programmatic_short. - En el paso Proceso que verifica las variables de entorno, añadir
HYPERFRAMES_ACTIVEa la lista. - En el mapeo proveedor→especialista, añadir la fila
Hyperframes -> hyperframes-prompt-builder. - Añadir un ejemplo: un carrete semanal de KPI enrutado a HyperFrames con
task_kind: programmatic_short.
Omitir cualquier sub-paso cuya cadena objetivo ya esté presente.
Paso 4 — Extender la capa de proveedores
En lib/providers/types.ts, añadir tres miembros a la unión VideoTask:
| "motion-typography"
| "data-viz-reel"
| "programmatic-short"
En lib/providers/matrix.ts:
- Añadir tres filas a
EMBEDDED_DEFAULTS.video:motion-typography,data-viz-reel,programmatic-short— cada una con valor por defectohyperframes. - Añadir alias de etiqueta a
TASK_LABEL_MAP:"motion typography","kinetic typography","data viz reel","data-viz reel","programmatic short","parametrized short".
En lib/providers/video.ts:
- Añadir una clase
HyperframesVideoProviderque extiendaRealVideoBase, controlada porprocess.env.HYPERFRAMES_ACTIVE === "true", que lance un error "local CLI render required in caller context; stub" desderealGenerate(siguiendo el patrón de stubs existente de higgsfield/topview). - Registrar
hyperframes: () => new HyperframesVideoProvider()enREAL_VIDEO_REGISTRY.
En lib/providers/__mocks__/video.ts:
- Añadir un
MockHyperframesVideoProviderque extiendaBaseMockVideoconname = "hyperframes". - Registrar
hyperframes: () => new MockHyperframesVideoProvider()enMOCK_VIDEO_REGISTRY.
Paso 5 — Actualizar el archivo de matriz de enrutamiento
En .specs/architecture/PROVIDERS.md, añadir tres filas a la tabla Video Routing:
| Tipografía en movimiento | hyperframes | Tipo cinético HTML/GSAP, fiel a la marca, determinista |
| Carrete de visualización de datos | hyperframes | Variables declaradas → gráficos re-renderizables (estilo NYT) |
| Corto programático | hyperframes | Composición HTML parametrizada; re-renderizados byte-idénticos |
Paso 6 — Actualizar .env.example
Añadir, después de WAVESPEED_API_KEY=:
# HyperFrames es un renderizador local HTML→MP4; no necesita clave API.
# Establecer HYPERFRAMES_ACTIVE=true una vez que `npx hyperframes doctor` pase localmente
# (Node >= 22, FFmpeg en PATH). Ver https://github.com/wesleysimplicio/hyperframes
HYPERFRAMES_ACTIVE=false
Paso 7 — Actualizar CLAUDE.md
- En la tabla Stack, cambiar la celda de proveedores de la fila
Videopara incluirhyperframes (local HTML→MP4). - En Skills Disponibles, insertar tres líneas después de
wavespeed-batch:hyperframes— Autoría de composición en movimiento con HTML como fuente de verdad.hyperframes-cli— Ejecutanpx hyperframeslint/inspect/preview/render.hyperframes-prompt-builder— Seleccionado porvideo-prompt-buildercuando la matriz resuelve ahyperframes.
Paso 8 — Verificar
- Analizar
.specs/architecture/PROVIDERS.mdmediante la prueba siguiente y afirmar quemotion-typography,data-viz-reel,programmatic-shortresuelven todos ahyperframes. - Ejecutar
npm run typecheck— aceptar cualquier fallo preexistente no relacionado con los cambios (ej. falta@types/node); fallar si algún nuevo error de TS referencia la capa de proveedores. - Ejecutar
npm run router:checksi existe un.enven el repositorio; de lo contrario omitir (el script requiere.envy no está relacionado con la forma de la integración). - Confirmar que
git statusmuestra solo los archivos esperados.
node --input-type=module -e "
import { readFileSync } from 'node:fs';
const text = readFileSync('.specs/architecture/PROVIDERS.md', 'utf8');
const expected = ['motion-typography', 'data-viz-reel', 'programmatic-short'];
for (const key of expected) {
if (!text.toLowerCase().includes(key.replace(/-/g, ' '))) {
console.error('FALTA:', key); process.exit(1);
}
}
console.log('PROVIDERS.md OK');
"
Paso 9 — Hacer commit y push
- Preparar (staging) exactamente los archivos que este skill tocó. Nunca usar
git add -A. - Hacer commit con el mensaje canónico:
más un cuerpo describiendo la ejecución del contrato de tres pasos (ver el commit de referencia fusionado para la redacción).feat(skills): wire HyperFrames as a video provider - Hacer push a
origin <branch>. Abrir un PR borrador si no existe ninguno para la rama.
Salidas
branch: cadena. La rama que contiene el commit.pr_url: cadena. La URL del PR borrador, si se creó o ya existía.files_written: array de rutas relativas realmente creadas o modificadas.files_skipped_idempotent: array de rutas relativas que ya eran correctas.verification:{ providers_md_pass: booleano, typecheck_pass: booleano, router_check: "pass" | "skipped" | "fail" }.
Reglas innegociables
- Idempotente. Volver a ejecutar en un repositorio ya integrado no toca ningún archivo.
- Nunca hacer commit en
main. Crear primero una rama de características; la política de ramas del motor se aplica upstream. - Ningún cuerpo de skill menciona
hyperframesfuera del contrato. La selección de proveedor sigue fluyendo a través dePROVIDERS.md+lib/router.ts. Este skill es el arranque; la selección en tiempo de ejecución sigue siendo agnóstica al proveedor. - No editar un MP4 renderizado ni ningún archivo bajo
outputs/. Este skill solo cambia la infraestructura del motor. - Nunca eliminar un skill
compliance-<cliente activo>existente ni ningún artefacto específico de cliente. La integración es aditiva.
Modos de fallo
- La verificación previa del Paso 1 falla (no es un repositorio del motor de marketing): mostrar el archivo faltante y detenerse. No intentar "arreglarlo".
- Un archivo ya existe con contenido conflictivo (ej.
.skills/hyperframes/SKILL.mdfue editado a mano): comparar con el contenido canónico; mostrar la diferencia; preguntar al operador antes de sobrescribir. npm run typecheckreporta un nuevo error de TS enlib/providers/: detenerse, mostrar el error, no hacer commit.git pushfalla por razones no relacionadas con la red: detenerse. Los fallos de red se reintentan según la política de git del proyecto (2s, 4s, 8s, 16s de espera, hasta 4 intentos).
Skills relacionados
hyperframes: autoría en tiempo de ejecución (instalado por este skill en el Paso 2).hyperframes-cli: lint/inspect/render en tiempo de ejecución (instalado por este skill en el Paso 2).hyperframes-prompt-builder: especialista en tiempo de ejecución (instalado por este skill en el Paso 2).video-prompt-builder: despachador actualizado por este skill en el Paso 3.llm-router: no relacionado; el enrutamiento de proveedores LLM es un despachador paralelo.
Conjunto de artefactos de referencia
Los contenidos canónicos de cada archivo que este skill escribe están en el commit fusionado en main:
- Skills:
.skills/hyperframes/SKILL.md,.skills/hyperframes-cli/SKILL.md,.skills/hyperframes-prompt-builder/SKILL.md - Capa de proveedores:
lib/providers/types.ts,lib/providers/matrix.ts,lib/providers/video.ts,lib/providers/__mocks__/video.ts - Matriz de enrutamiento:
.specs/architecture/PROVIDERS.md - Entorno:
.env.example - Acta fundacional:
CLAUDE.md
En caso de duda, comparar con origin/main en el commit de referencia fusionado y copiar la versión canónica textualmente. No teclear de memoria.
Referencia upstream
- HyperFrames: https://github.com/wesleysimplicio/hyperframes
- Catálogo de skills del proyecto: https://github.com/wesleysimplicio/hyperframes/tree/main/skills