Communitygithub.com

simpletibr/simplicio-loop-marketing

Habilidad de arranque en un solo paso que integra HyperFrames en un clon del motor de marketing como proveedor de video de primera clase: los tres skills de ejecución, la clase proveedora + simulacro, las filas de la matriz de enrutamiento, variables de entorno y actualizaciones de CLAUDE.md. Idempotente. Se invoca cuando un clon nuevo necesita agregar HyperFrames, o al reaplicar la integración después de un rebase que eliminó alguna pieza.

¿Qué es simplicio-loop-marketing?

Esta habilidad automatiza la integración completa de HyperFrames como un proveedor de video en un clon del motor de marketing 'marketing-engine'. Está diseñada para ser idempotente, lo que significa que se puede ejecutar múltiples veces sin efectos secundarios, creando solo los archivos faltantes o actualizando los necesarios según un contrato de tres pasos definido en CLAUDE.md. El skill es útil para desarrolladores que trabajan con el repositorio 'marketing-engine' y necesitan añadir soporte para HyperFrames, una herramienta que permite renderizar composiciones HTML/GSAP en video (como tipografía cinética, gráficos de datos y cortos programáticos). Cubre la instalación de skills de ejecución (hyperframes, hyperframes-cli, hyperframes-prompt-builder), la extensión del código fuente en TypeScript (tipos, matriz de enrutamiento, clases de proveedor y simulacros), la actualización de la documentación y las variables de entorno, y la verificación mediante pruebas de tipo y validación de la matriz. Soporta plataformas como Claude Code, Cursor, Codex y cualquier agente que ejecute habilidades SKILL.md. Funciona mediante una serie de pasos definidos que verifican la existencia de cada artefacto requerido y lo crean o actualizan solo si es necesario, siguiendo un orden lógico que asegura la coherencia del repositorio. Es la fuente canónica de cómo se integra HyperFrames en este proyecto.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/simpletibr/simplicio-loop-marketing/tree/HEAD/.skills/install-hyperframes

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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:check se queja, el enrutamiento de video vuelve a higgsfield para 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 en main.
  • 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

  1. Confirmar que repo_root contiene CLAUDE.md con la línea ## How to Add a New Provider. Negarse a ejecutar si falta (no es un repositorio del motor de marketing).
  2. Confirmar que existen lib/providers/video.ts, lib/providers/matrix.ts, lib/providers/types.ts y lib/providers/__mocks__/video.ts. Negarse a ejecutar si falta alguno.
  3. Confirmar que la rama activa no es main. Si está en main, crear y cambiar a branch primero.

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 en window.__timelines, sin Math.random()/lógica basada en tiempo, variables declaradas mediante data-composition-variables).
  • .skills/hyperframes-cli/SKILL.md — bucle de desarrollo npx hyperframes lint → inspect → render. Siempre renderiza con --strict --strict-variables.
  • .skills/hyperframes-prompt-builder/SKILL.md — especialista invocado por video-prompt-builder cuando la matriz resuelve a hyperframes; carga tokens de marca desde clients/<slug>/design.md, elige una plantilla según task_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:

  1. Añadir hyperframes-prompt-builder a la lista de especialistas en el párrafo inicial y en la sección Skills relacionados.
  2. Extender el enum de entrada task_kind con motion_typography, data_viz_reel, programmatic_short.
  3. En el paso Proceso que verifica las variables de entorno, añadir HYPERFRAMES_ACTIVE a la lista.
  4. En el mapeo proveedor→especialista, añadir la fila Hyperframes -> hyperframes-prompt-builder.
  5. 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 defecto hyperframes.
  • 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 HyperframesVideoProvider que extienda RealVideoBase, controlada por process.env.HYPERFRAMES_ACTIVE === "true", que lance un error "local CLI render required in caller context; stub" desde realGenerate (siguiendo el patrón de stubs existente de higgsfield/topview).
  • Registrar hyperframes: () => new HyperframesVideoProvider() en REAL_VIDEO_REGISTRY.

En lib/providers/__mocks__/video.ts:

  • Añadir un MockHyperframesVideoProvider que extienda BaseMockVideo con name = "hyperframes".
  • Registrar hyperframes: () => new MockHyperframesVideoProvider() en MOCK_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

  1. En la tabla Stack, cambiar la celda de proveedores de la fila Video para incluir hyperframes (local HTML→MP4).
  2. 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 — Ejecuta npx hyperframes lint/inspect/preview/render.
    • hyperframes-prompt-builder — Seleccionado por video-prompt-builder cuando la matriz resuelve a hyperframes.

Paso 8 — Verificar

  1. Analizar .specs/architecture/PROVIDERS.md mediante la prueba siguiente y afirmar que motion-typography, data-viz-reel, programmatic-short resuelven todos a hyperframes.
  2. 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.
  3. Ejecutar npm run router:check si existe un .env en el repositorio; de lo contrario omitir (el script requiere .env y no está relacionado con la forma de la integración).
  4. Confirmar que git status muestra 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

  1. Preparar (staging) exactamente los archivos que este skill tocó. Nunca usar git add -A.
  2. Hacer commit con el mensaje canónico:
    feat(skills): wire HyperFrames as a video provider
    
    más un cuerpo describiendo la ejecución del contrato de tres pasos (ver el commit de referencia fusionado para la redacción).
  3. 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 hyperframes fuera del contrato. La selección de proveedor sigue fluyendo a través de PROVIDERS.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.md fue editado a mano): comparar con el contenido canónico; mostrar la diferencia; preguntar al operador antes de sobrescribir.
  • npm run typecheck reporta un nuevo error de TS en lib/providers/: detenerse, mostrar el error, no hacer commit.
  • git push falla 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

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

Skills relacionados