Communitygithub.com

simpletibr/simplicio-loop-marketing

Executa o loop de desenvolvimento CLI do HyperFrames — init, lint, inspect, preview, render — para composições criadas sob a habilidade `hyperframes`. É invocado após o HTML da composição estar no disco e antes da peça ser marcada como concluída.

O que é simplicio-loop-marketing?

Esta habilidade automatiza o pipeline de desenvolvimento e renderização de composições HyperFrames (animações, vídeos ou gráficos baseados em HTML) diretamente pela CLI. Ela é útil para engenheiros de marketing e desenvolvedores que precisam de um fluxo de trabalho robusto: lint para validar marcação, inspect para auditar layout/overflow, preview para iteração local e render para produzir o MP4 final. Suporta Node.js >= 22 e FFmpeg, com execução segura em modo DRY_RUN. O processo segue regras não negociáveis, como nunca renderizar sem lint/inspect aprovados e sempre usar variáveis estritas para evitar erros silenciosos. A habilidade se integra com outras do ecossistema, como `hyperframes-prompt-builder` (que gera a composição) e `qa-tech-specs` (que valida o MP4 renderizado).

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/simpletibr/simplicio-loop-marketing/tree/HEAD/.skills/hyperframes-cli

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

CLI do HyperFrames

Empacota o npx hyperframes para o pipeline do motor de marketing. Requer Node.js >= 22 e FFmpeg no PATH (npx hyperframes doctor verifica). Todos os comandos são executados em modo seguro DRY_RUN por padrão — as passagens de lint/inspect não fazem chamadas externas; apenas o render escreve um MP4.

Quando invocar

  • Imediatamente após o hyperframes-prompt-builder produzir um projeto em outputs/<cliente>/<data>/<id-da-peça>/.
  • Sempre que uma composição precisar de validação antes da publicação (lint + inspect).
  • Para pré-visualização local durante a iteração de uma peça (preview).
  • Para a renderização final que produz o artefato coletado pela etapa de publicação (render).
  • Para solucionar problemas de ambiente quando a renderização falha (doctor, browser, info).

Entradas

  • project_path: string. Caminho para o projeto HyperFrames (deve conter index.html e composition.json).
  • mode: "lint" | "inspect" | "preview" | "render" | "doctor".
  • render_opts: objeto, opcional, apenas para mode = "render". Chaves reconhecidas:
    • fps: 24 | 30 | 60 (padrão 30).
    • quality: "draft" | "standard" | "high" (padrão "standard"; use "draft" durante iteração).
    • format: "mp4" | "webm" (padrão "mp4").
    • variables: objeto. Objeto JSON chaveado por ID de variável, substitui os padrões de data-composition-variables.
    • strict: booleano. Mapeia para --strict. Padrão true no pipeline — falha na renderização com erros de lint.
    • strict_variables: booleano. Mapeia para --strict-variables. Padrão true para execuções de peça.
    • workers: inteiro 1-8 ou "auto". Padrão "auto".
    • output: string. Caminho do arquivo de saída dentro de outputs/<cliente>/<data>/<id-da-peça>/.

Processo

  1. Verificar ambiente na primeira execução de uma sessão: npx hyperframes doctor. Reporte FFmpeg ou Chrome ausentes como bloqueio grave — não tente renderizar.
  2. Lint. npx hyperframes lint <project_path> --json. Trate todas as descobertas de nível error como bloqueadoras. Avisos são reportados ao orquestrador; deixe o operador decidir.
  3. Inspect. npx hyperframes inspect <project_path> --json. Resolva qualquer relato de overflow de texto ou escape de canvas antes de renderizar. Se o overflow for intencional para uma entrada/saída, marque o elemento com data-layout-allow-overflow (ou o ancestral com data-layout-ignore para elementos decorativos) — não silencie a regra globalmente.
  4. Preview (apenas operador). npx hyperframes preview <project_path> --port <port>. Devolva a URL do projeto Studio (http://localhost:<port>/#project/<nome-do-projeto>), não o caminho do index.html fonte.
  5. Renderizar. npx hyperframes render <project_path> com as flags resolvidas de render_opts. Construa o argumento --variables a partir de render_opts.variables usando uma string JSON de linha única. Sempre passe --strict e --strict-variables para execuções de peça.
  6. Verificar saída. Após a renderização, verifique se o MP4 existe e não está com zero bytes. Registre em data/video-usage.jsonl com { ts, provider: "hyperframes", composition_id, render_args, duration_seconds, file_bytes, latency_ms }.

Saídas

  • lint: { pass: boolean, errors: [...], warnings: [...] }.
  • inspect: { pass: boolean, findings: [...] }.
  • render: { artifact_path: string, duration_s: number, file_bytes: number, render_ms: number }.
  • preview: { url: string }.

Folha de dicas de comandos

npx hyperframes init <nome>                            # scaffold (usado uma vez por peça pelo prompt builder)
npx hyperframes lint <caminho>                         # validar marcação
npx hyperframes inspect <caminho>                      # auditoria de layout/overflow
npx hyperframes preview <caminho> --port 3017          # dev local
npx hyperframes render <caminho> \
  --fps 30 --quality standard --strict --strict-variables \
  --variables '{"leads":42,"delta_pct":12}' \
  --output outputs/<cliente>/<data>/<id-da-peça>/final.mp4
npx hyperframes doctor                                 # verificação de ambiente
npx hyperframes info                                   # versão/detalhes do ambiente

Regras não negociáveis

  • Nunca renderize sem uma passagem de lint e inspect aprovada. O pipeline não tem caminho de recuperação para uma composição malformada.
  • Nunca silencie uma descoberta de lint ou inspect globalmente — corrija a marcação ou coloque na lista de permissões o elemento específico com data-layout-allow-overflow / data-layout-ignore.
  • Para peças com variáveis declaradas, sempre passe --strict-variables. Um erro de digitação no ID da variável deve falhar ruidosamente, não cair silenciosamente no padrão.
  • Para renderizações de entrega final, --quality high. Para loops de iteração, --quality draft para economizar computação.
  • O pré-processamento de assets (tts, transcribe, remove-background) está fora do escopo desta habilidade — invoque-os através de uma futura habilidade hyperframes-media em vez de inserir aqui.

Modos de falha

  • doctor reporta FFmpeg ou Chrome ausentes: instale através das instruções de configuração do projeto; não contorne.
  • render falha com unknown variable: uma chave passada via --variables não está declarada em data-composition-variables. Corrija a marcação ou remova a substituição.
  • render excede o orçamento de tempo de execução: reduza --quality para standard, ou divida a composição em sub-composições e paralelize usando --workers.
  • MP4 de saída com zero bytes: execute doctor novamente; quase sempre é uma falha do Chrome durante a captura.

Habilidades relacionadas

  • hyperframes: regras de criação de composição; produz o projeto que esta habilidade valida e renderiza.
  • hyperframes-prompt-builder: briefing → especificação da composição; é executada antes desta habilidade.
  • qa-tech-specs: é executada após esta habilidade contra o MP4 renderizado para validar especificações da plataforma.

Referência upstream

Habilidade upstream completa (todas as flags, matriz de solução de problemas, renderizações parametrizadas): https://github.com/wesleysimplicio/hyperframes/tree/main/skills/hyperframes-cli

Individual skills in this repo

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

Habilidades Relacionadas