Construtor de Prompt HyperFrames
Especialista que faz a ponte entre o modelo de peça do motor de marketing (brief, task_kind, provider_override) e o contrato de composição do HyperFrames. Espelha higgsfield-prompt-builder e topview-prompt-builder na forma — mesmo despachante, alvo diferente — para que video-prompt-builder possa trocar de provedores sem alterar sua própria lógica.
Quando invocar
video-prompt-builderresolve o provedor de vídeo parahyperframespara uma peça.task_kindé um demotion-typography,data-viz-reel,programmatic-short(as tarefas nativas do hyperframes emPROVIDERS.md).- Uma peça declara
provider_override.video: hyperframesem seu frontmatter. - Um still aprovado (cartão de citação do
gpt-image, carrossel dotopview) está sendo promovido para movimento e o sistema de tipos deve permanecer fiel ao byte original. - O orquestrador precisa que a mesma composição seja re-renderizada com novos valores de variáveis (reel semanal de KPI, atualização diária de preço, variante de copy A/B) sem re-promptar um gerador de IA.
Entradas
brief: objeto. O briefing da peça com pelo menosheadline,body?,cta?,aspect,duration_seconds.task_kind:"motion-typography" | "data-viz-reel" | "programmatic-short".piece_path: string, opcional. Caminho para.specs/pieces/<piece-id>.md. O frontmatter pode conterprovider_override,compliance_flags,variables.client_slug: string. Usado para carregar.marketing-engine/clients/<slug>/design.md(ouclients/<slug>/design.mdno repositório do motor).output_dir: string. Onde o projeto e o MP4 final serão salvos (padrão:outputs/<client>/<date>/<piece-id>/).dry_run: boolean, opcional. Quando verdadeiro, retorna a especificação de composição e os argumentos de renderização sem invocarhyperframes-cli.
Processo
- Carregar contexto da marca. Ler
clients/<client_slug>/design.mde resolver{ colors, type_pairing, spacing_scale, brand_voice }. Se ausente, recusar prosseguir — exibir o caminho ausente. Violações de marca não podem ser corrigidas downstream. - Resolver substituições. Se
piece_pathestiver definido e o frontmatter tiverprovider_override.video, confirmar que éhyperframes; caso contrário, esta skill não deveria estar em execução. - Mapear task_kind para um modelo de composição.
motion-typography→ modelokinetic-type, cena única, orientada por tipo.data-viz-reel→ modelonyt-graph, cena de corpo com variáveis numéricas declaradas.programmatic-short→ modeloplay-mode, gancho/corpo/CTA, toda a copy do cliente declarada como variáveis.
- Declarar variáveis. Tudo no briefing que poderia mudar por re-renderização (headline, corpo, números de KPI, CTA, carimbo de data) vai para
variablescom tipo + rótulo + padrão explícitos. Cópia codificada é proibida quando uma variável funcionaria. - Construir a especificação de composição no formato que o
hyperframesespera:{ composition_id, aspect, duration_seconds, scenes, design_tokens, variables, assets, output_dir }. Calcularcomposition_ida partir de<piece-id>(seguro para slug). - Construir os argumentos de renderização no formato que o
hyperframes-cliespera:{ project_path, mode: "render", render_opts: { fps, quality, format, variables, strict: true, strict_variables: true, output } }. Escolherquality: "high"para peças promovidas,"draft"para revisão de primeira passagem. - Estimativa de custo. Renderização local — estimar a partir de
duration_seconds × workers × $0.00(zero custo direto; reportar minutos de tempo real comolatency_estimate_minem vez disso). - Registrar a resolução em
data/video-usage.jsonlcom{ ts, provider: "hyperframes", piece_id, task_kind, composition_id, dry_run }. - Se
dry_run, retornar sem chamarhyperframes-cli. Caso contrário, invocarhyperframes(para criar o projeto) e depoishyperframes-cli(modolint→inspect→render) em ordem.
Saídas
provider_used:"hyperframes".composition_spec: objeto. A entrada passada para a skillhyperframes.render_args: objeto. A entrada passada para a skillhyperframes-cli(modorender).expected_artifact: string. O caminho do MP4 que existirá após a renderização.latency_estimate_min: número. Estimativa de tempo real para a renderização.cost_estimate_usd: 0 (renderização local; apenas despesas operacionais).
Exemplos
Exemplo 1: reel semanal de KPI (programmatic-short)
Entrada: { brief: { headline: "Semana 21 em números", aspect: "9:16", duration_seconds: 12 }, task_kind: "programmatic-short", client_slug: "saas-consultoria-imagem", piece_path: ".specs/pieces/2026-05-22-kpi.md" }
Saída: especificação de composição com composition_id: "kpi-weekly-2026-05-22", três cenas (gancho/corpo/CTA), variáveis numéricas (leads, delta_pct); argumentos de renderização com --strict --strict-variables --quality high --variables '{"leads":42,"delta_pct":12}'.
Exemplo 2: cartão de citação animado (motion-typography)
Entrada: { brief: { headline: "Coloque a sua marca onde os olhos já estão.", aspect: "1:1", duration_seconds: 6 }, task_kind: "motion-typography", client_slug: "saas-consultoria-imagem" }
Saída: especificação de composição com uma única cena de tipo cinético, entrada de texto mascarada, tokens de design extraídos do design.md do cliente ativo; argumentos de renderização visando outputs/saas-consultoria-imagem/<date>/<piece-id>/final.mp4.
Exemplo 3: substituição de provedor
Entrada: uma peça com provider_override.video: hyperframes cujo task_kind não está na matriz.
Saída: ainda roteada para cá, padrão task_kind para programmatic-short, registrar o fallback.
Regras inegociáveis
- Nunca inventar tokens de design. Recusar prosseguir se
design.mdestiver ausente. - Sempre declarar a copy específica da peça como uma
variable, mesmo que pareça estática — a composição deve poder ser re-renderizada sem edições de código. - Sempre passar
--strict-variablesnos argumentos de renderização. Um erro de digitação em um id de variável é uma falha grave. - Nunca chamar
hyperframes-clidiretamente ignorando a sequêncialint → inspect → render.
Modos de falha
task_kinddesconhecido: padrão paraprogrammatic-short, registrar um aviso e continuar.design.mdausente: parar. Não escolher uma paleta; pedir ao operador para adicionar o arquivo.- Briefing inclui uma alegação proibida pela marca (conforme
compliance-<cliente ativo>): bloquear antes de criar; a conformidade é executada upstream da renderização. - HyperFrames CLI não instalado: exibir o comando de instalação (
npm i -g hyperframesounpx hyperframes@latest) e parar.
Skills relacionadas
hyperframes: regras de criação de composição (consumidas por esta skill).hyperframes-cli: execução de lint/inspect/render (consumidas por esta skill).video-prompt-builder: despachante que seleciona esta skill.qa-tech-specs: executa contra o MP4 final.compliance-<cliente ativo>/compliance-generic: executa contra as variáveis resolvidas e o artefato renderizado.llm-router: não usado diretamente aqui, mas pode escolher o LLM que redige a headline/corpo antes desta skill montar a especificação de composição.