Communitygithub.com

simpletibr/simplicio-loop-marketing

Habilidade de bootstrapping em um único passo que conecta HyperFrames (https://github.com/wesleysimplicio/hyperframes) a um clone do marketing-engine como um provedor de vídeo de primeira classe — as três habilidades de runtime, a classe do provedor + mock, as linhas da matriz de roteamento, variáveis de ambiente e atualizações no CLAUDE.md. Idempotente. Invoque quando um clone novo precisar adicionar HyperFrames, ou ao reaplicar a integração após um rebase que removeu qualquer parte dela.

O que é simplicio-loop-marketing?

Esta habilidade automatiza a integração do HyperFrames como um provedor de vídeo completo em um repositório `marketing-engine`, seguindo o contrato de três etapas 'Adicionando um Novo Provedor' documentado em `CLAUDE.md`. Ela é idempotente, o que significa que pode ser executada repetidamente sem efeitos colaterais indesejados, criando apenas os artefatos ausentes. O processo inclui a instalação de três habilidades de runtime (composição, CLI e construção de prompts), a extensão da camada de provedores (tipos, matriz de roteamento, provedor real e mock), a atualização da matriz de roteamento em `PROVIDERS.md`, do arquivo `.env.example` e do próprio `CLAUDE.md`. É útil para desenvolvedores que precisam adicionar suporte a vídeos programáticos, tipografia em movimento e gráficos de dados em um novo clone da base, ou para recuperar a integração após um rebase problemático. A habilidade opera em branches de funcionalidades (`claude/install-hyperframes` por padrão) e nunca faz commit diretamente no `main`, garantindo que o fluxo de trabalho da equipe seja respeitado. Ela se destina a ser invocada em vez de derivar manualmente toda a integração do zero, servindo como o registro canônico do que significa 'HyperFrames estar conectado' no repositório.

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

Perguntar na sua IA favorita

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

Documentação

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:check reclama, roteamento de vídeo cai para higgsfield em 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 no main.
  • 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

  1. Confirme que repo_root contém CLAUDE.md com a linha ## How to Add a New Provider. Recuse-se a executar se estiver faltando — não é um repositório marketing-engine.
  2. Confirme que lib/providers/video.ts, lib/providers/matrix.ts, lib/providers/types.ts e lib/providers/__mocks__/video.ts existem. Recuse-se a executar se algum estiver faltando.
  3. Confirme que o branch ativo não é main. Se estiver no main, crie e mude para o branch primeiro.

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 em window.__timelines, sem Math.random()/lógica baseada em tempo, variáveis declaradas via data-composition-variables).
  • .skills/hyperframes-cli/SKILL.md — loop de desenvolvimento npx hyperframes lint → inspect → render. Sempre renderiza com --strict --strict-variables.
  • .skills/hyperframes-prompt-builder/SKILL.md — especialista invocado por video-prompt-builder quando a matriz resolve para hyperframes; carrega tokens da marca de clients/<slug>/design.md, escolhe um template por task_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:

  1. Adicione hyperframes-prompt-builder à lista de especialistas no parágrafo de abertura e na seção Habilidades relacionadas.
  2. Estenda o enum de entrada task_kind com motion_typography, data_viz_reel, programmatic_short.
  3. Na etapa Processo que verifica variáveis de ambiente, adicione HYPERFRAMES_ACTIVE à lista.
  4. No mapeamento provedor→especialista, adicione a linha Hyperframes -> hyperframes-prompt-builder.
  5. 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ão hyperframes.
  • 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 HyperframesVideoProvider estendendo RealVideoBase, protegida por process.env.HYPERFRAMES_ACTIVE === "true", que lança um erro "local CLI render required in caller context; stub" no realGenerate (seguindo o padrão de stub existente do higgsfield/topview).
  • Registre hyperframes: () => new HyperframesVideoProvider() em REAL_VIDEO_REGISTRY.

Em lib/providers/__mocks__/video.ts:

  • Adicione um MockHyperframesVideoProvider estendendo BaseMockVideo com name = "hyperframes".
  • Registre hyperframes: () => new MockHyperframesVideoProvider() em MOCK_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

  1. Na tabela Stack, na linha Video, altere a célula de provedores para incluir hyperframes (local HTML→MP4).
  2. 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 — Executa npx hyperframes lint/inspect/preview/render.
    • hyperframes-prompt-builder — Selecionado por video-prompt-builder quando a matriz resolve para hyperframes.

Etapa 8 — Verificar

  1. Analise .specs/architecture/PROVIDERS.md com o teste abaixo e afirme que motion-typography, data-viz-reel, programmatic-short todos resolvem para hyperframes.
  2. Execute npm run typecheck — aceite quaisquer falhas pré-existentes não relacionadas às mudanças (ex.: @types/node faltando); falhe se algum novo erro TS referenciar a camada de provedores.
  3. Execute npm run router:check se um .env existir no repositório; caso contrário, pule (o script exige .env e não está relacionado à forma da integração).
  4. Confirme que git status mostra 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

  1. Prepare exatamente os arquivos que esta habilidade tocou. Nunca git add -A.
  2. Faça commit com a mensagem canônica:
    feat(skills): wire HyperFrames as a video provider
    
    mais um corpo descrevendo a execução do contrato de três etapas (veja o commit de referência mesclado para a redação).
  3. 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 hyperframes fora do contrato. A seleção do provedor ainda flui através de PROVIDERS.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.md foi editado manualmente): faça diff com o conteúdo canônico; exiba o diff; pergunte ao operador antes de sobrescrever.
  • npm run typecheck relata um novo erro TS em lib/providers/: pare, exiba o erro, não faça commit.
  • git push falha 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

Individual skills in this repo

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

Habilidades Relacionadas