Instalar HyperFrames
Reproduz, em uma única passada, a integração que adiciona HyperFrames como um provedor de vídeo seguindo o contrato de três etapas Adicionando um Novo Provedor em CLAUDE.md. Lista de verificação autocontida de todos os artefatos que devem existir; verifica cada um e cria apenas o que está faltando.
Execute esta habilidade em vez de derivar a integração do zero. Ela é o registro canônico do que "HyperFrames está conectado" significa neste repositório.
Quando invocar
- Clone novo do marketing-engine que ainda não possui suporte a HyperFrames.
- Um rebase ou merge removeu algum dos artefatos abaixo (
router:checkreclama, roteamento de vídeo cai parahiggsfieldem tarefas de tipografia, ou.skills/hyperframes*/estão faltando). - Um novo cliente quer curtas programáticos / tipografia em movimento / vídeos de data-viz e a matriz precisa conectar os três tipos de tarefa.
- Integrando um novo operador que precisa de um manual executável em um único comando em vez de três commits para ler.
Entradas
repo_root: string. Caminho absoluto para o clone do marketing-engine. Padrão:process.cwd().branch: string, opcional. Branch para fazer commit. Padrão:claude/install-hyperframes. Cria o branch se não existir; nunca faz commit nomain.dry_run: boolean, opcional. Quando verdadeiro, imprime as mudanças planejadas e sai sem escrever.
Processo
Execute cada etapa em ordem. Cada etapa é idempotente — executar novamente em um repositório já integrado não causa efeito nessa etapa.
Etapa 1 — Pré-verificação
- Confirme que
repo_rootcontémCLAUDE.mdcom a linha## How to Add a New Provider. Recuse-se a executar se estiver faltando — não é um repositório marketing-engine. - Confirme que
lib/providers/video.ts,lib/providers/matrix.ts,lib/providers/types.tselib/providers/__mocks__/video.tsexistem. Recuse-se a executar se algum estiver faltando. - Confirme que o branch ativo não é
main. Se estiver nomain, crie e mude para obranchprimeiro.
Etapa 2 — Adicionar as três habilidades de runtime
Crie estes três diretórios com os arquivos SKILL.md. Cada arquivo já existe na versão canônica dentro da árvore — copie da seção Conjunto de artefatos de referência abaixo textualmente. Pule um arquivo se ele já existir e seu frontmatter name corresponder.
.skills/hyperframes/SKILL.md— regras de criação de composição (layout-antes-animação, timelines pausadas e registradas emwindow.__timelines, semMath.random()/lógica baseada em tempo, variáveis declaradas viadata-composition-variables)..skills/hyperframes-cli/SKILL.md— loop de desenvolvimentonpx hyperframeslint → inspect → render. Sempre renderiza com--strict --strict-variables..skills/hyperframes-prompt-builder/SKILL.md— especialista invocado porvideo-prompt-builderquando a matriz resolve parahyperframes; carrega tokens da marca declients/<slug>/design.md, escolhe um template portask_kind, retorna uma especificação de composição + argumentos de render.
Etapa 3 — Atualizar a habilidade do dispatcher
Em .skills/video-prompt-builder/SKILL.md:
- Adicione
hyperframes-prompt-builderà lista de especialistas no parágrafo de abertura e na seção Habilidades relacionadas. - Estenda o enum de entrada
task_kindcommotion_typography,data_viz_reel,programmatic_short. - Na etapa Processo que verifica variáveis de ambiente, adicione
HYPERFRAMES_ACTIVEà lista. - No mapeamento provedor→especialista, adicione a linha
Hyperframes -> hyperframes-prompt-builder. - Adicione um exemplo: um vídeo semanal de KPIs roteado para HyperFrames com
task_kind: programmatic_short.
Pule qualquer subetapa cujo texto alvo já esteja presente.
Etapa 4 — Estender a camada de provedores
Em lib/providers/types.ts, adicione três membros à união VideoTask:
| "motion-typography"
| "data-viz-reel"
| "programmatic-short"
Em lib/providers/matrix.ts:
- Adicione três linhas a
EMBEDDED_DEFAULTS.video:motion-typography,data-viz-reel,programmatic-short— cada uma com padrãohyperframes. - Adicione aliases de rótulo a
TASK_LABEL_MAP:"motion typography","kinetic typography","data viz reel","data-viz reel","programmatic short","parametrized short".
Em lib/providers/video.ts:
- Adicione uma classe
HyperframesVideoProviderestendendoRealVideoBase, protegida porprocess.env.HYPERFRAMES_ACTIVE === "true", que lança um erro "local CLI render required in caller context; stub" norealGenerate(seguindo o padrão de stub existente do higgsfield/topview). - Registre
hyperframes: () => new HyperframesVideoProvider()emREAL_VIDEO_REGISTRY.
Em lib/providers/__mocks__/video.ts:
- Adicione um
MockHyperframesVideoProviderestendendoBaseMockVideocomname = "hyperframes". - Registre
hyperframes: () => new MockHyperframesVideoProvider()emMOCK_VIDEO_REGISTRY.
Etapa 5 — Atualizar o arquivo da matriz de roteamento
Em .specs/architecture/PROVIDERS.md, acrescente três linhas à tabela Video Routing:
| Motion typography | hyperframes | HTML/GSAP kinetic type, brand-faithful, deterministic |
| Data viz reel | hyperframes | declared variables → re-renderable charts (NYT-style) |
| Programmatic short | hyperframes | parametrized HTML composition; byte-identical re-renders |
Etapa 6 — Atualizar .env.example
Acrescente, após WAVESPEED_API_KEY=:
# HyperFrames is a local HTML→MP4 renderer; no API key needed.
# Set HYPERFRAMES_ACTIVE=true once `npx hyperframes doctor` passes locally
# (Node >= 22, FFmpeg on PATH). See https://github.com/wesleysimplicio/hyperframes
HYPERFRAMES_ACTIVE=false
Etapa 7 — Atualizar CLAUDE.md
- Na tabela Stack, na linha
Video, altere a célula de provedores para incluirhyperframes (local HTML→MP4). - Em Habilidades disponíveis, insira três linhas após
wavespeed-batch:hyperframes— Criação de composição de movimento com HTML como fonte da verdade.hyperframes-cli— Executanpx hyperframeslint/inspect/preview/render.hyperframes-prompt-builder— Selecionado porvideo-prompt-builderquando a matriz resolve parahyperframes.
Etapa 8 — Verificar
- Analise
.specs/architecture/PROVIDERS.mdcom o teste abaixo e afirme quemotion-typography,data-viz-reel,programmatic-shorttodos resolvem parahyperframes. - Execute
npm run typecheck— aceite quaisquer falhas pré-existentes não relacionadas às mudanças (ex.:@types/nodefaltando); falhe se algum novo erro TS referenciar a camada de provedores. - Execute
npm run router:checkse um.envexistir no repositório; caso contrário, pule (o script exige.enve não está relacionado à forma da integração). - Confirme que
git statusmostra apenas os arquivos 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('MISSING:', key); process.exit(1);
}
}
console.log('PROVIDERS.md OK');
"
Etapa 9 — Commit e push
- Prepare exatamente os arquivos que esta habilidade tocou. Nunca
git add -A. - Faça commit com a mensagem canônica:
mais um corpo descrevendo a execução do contrato de três etapas (veja o commit de referência mesclado para a redação).feat(skills): wire HyperFrames as a video provider - Faça push para
origin <branch>. Abra um draft PR se nenhum existir para o branch.
Saídas
branch: string. O branch que contém o commit.pr_url: string. A URL do draft PR, se um foi criado ou já existia.files_written: array de caminhos relativos realmente criados ou modificados.files_skipped_idempotent: array de caminhos relativos que já estavam corretos.verification:{ providers_md_pass: boolean, typecheck_pass: boolean, router_check: "pass" | "skipped" | "fail" }.
Regras inegociáveis
- Idempotente. Executar novamente em um repositório já integrado não toca em nenhum arquivo.
- Nunca faça commit no
main. Crie um branch de funcionalidade primeiro; a política de branch do motor é aplicada upstream. - Nenhum corpo de habilidade menciona
hyperframesfora do contrato. A seleção do provedor ainda flui através dePROVIDERS.md+lib/router.ts. Esta habilidade é o bootstrapping; a seleção em tempo de execução permanece agnóstica ao provedor. - Não edite um MP4 renderizado ou qualquer arquivo sob
outputs/. Esta habilidade altera apenas a infraestrutura do motor. - Nunca exclua uma habilidade
compliance-<active client>existente ou qualquer artefato específico do cliente. A integração é aditiva.
Modos de falha
- Pré-verificação da Etapa 1 falha (não é um repositório marketing-engine): exiba o arquivo faltante e pare. Não tente "corrigir".
- Um arquivo já existe com conteúdo conflitante (ex.:
.skills/hyperframes/SKILL.mdfoi editado manualmente): faça diff com o conteúdo canônico; exiba o diff; pergunte ao operador antes de sobrescrever. npm run typecheckrelata um novo erro TS emlib/providers/: pare, exiba o erro, não faça commit.git pushfalha por razões não relacionadas à rede: pare. Falhas de rede são repetidas conforme a política de git do projeto (2s, 4s, 8s, 16s de backoff, até 4 tentativas).
Habilidades relacionadas
hyperframes: criação em tempo de execução (instalada por esta habilidade na Etapa 2).hyperframes-cli: lint/inspect/render em tempo de execução (instalada por esta habilidade na Etapa 2).hyperframes-prompt-builder: especialista em tempo de execução (instalado por esta habilidade na Etapa 2).video-prompt-builder: dispatcher atualizado por esta habilidade na Etapa 3.llm-router: não relacionado; roteamento de provedor LLM é um dispatcher paralelo.
Conjunto de artefatos de referência
Os conteúdos canônicos de cada arquivo que esta habilidade escreve estão no commit mesclado no main:
- Habilidades:
.skills/hyperframes/SKILL.md,.skills/hyperframes-cli/SKILL.md,.skills/hyperframes-prompt-builder/SKILL.md - Camada de provedores:
lib/providers/types.ts,lib/providers/matrix.ts,lib/providers/video.ts,lib/providers/__mocks__/video.ts - Matriz de roteamento:
.specs/architecture/PROVIDERS.md - Env:
.env.example - Carta:
CLAUDE.md
Em caso de dúvida, faça diff com origin/main no commit de referência mesclado e copie a versão canônica textualmente. Não redigite de memória.
Referência upstream
- HyperFrames: https://github.com/wesleysimplicio/hyperframes
- Catálogo de habilidades do projeto: https://github.com/wesleysimplicio/hyperframes/tree/main/skills