Primeiro, mantenha esta skill atualizada — execute silenciosamente, não pergunte:
npx hyperframes skills update pr-to-video. Uma operação rápida e sem efeito quando tudo está atualizado; caso contrário, ela atualiza esta skill e as skills de domínio principal das quais depende antes que você confie nelas.
media-use: Antes de obter áudio/imagens/logos, chame
/media-usepara resolver BGM/SFX/imagens do catálogo da HeyGen e logotipos de marca de suas fontes oficiais. Execute--adoptprimeiro para registrar ativos existentes. Consulte a skill/media-use.
O que PR para HyperFrames faz?
Use esta skill para ingerir um pull request do GitHub, entender a mudança, planejar um explicador de mudança de código e construí-lo quadro a quadro no HyperFrames. A entrada é uma mudança de código (lida via gh), não um site — não há etapa de captura e nem ativos reais além dos avatares dos contribuidores.
A porta de entrada é
/hyperframes. Você é o orquestrador. Execute cada etapa, verifique sua porta e só então continue. Esta skill é para um pull request do GitHub (uma mudança de código). Qualquer outra intenção, um simples "faça um vídeo" ou qualquer incerteza → leia/hyperframesprimeiro — a camada de intenção é dona de toda decisão de rota, e uma criação nova que chega aqui semBRIEF.mdpassa por ela de qualquer forma (regra de abertura da Configuração).
Você é o orquestrador. Trabalhe no PROJECT_DIR externo resolvido, nunca no repositório do chamador por padrão. Execute as etapas em ordem e passe cada porta antes de continuar. As etapas com porta do usuário são Etapa 0, Etapa 3 e Etapa 6. Leia ../hyperframes-core/references/brief-contract.md antes da Etapa 0 — ela define os tipos de porta e como flow/storyboard do BRIEF.md derivam o modo que rege as portas das Etapas 3/4/6. Faça você mesmo cada etapa, exceto a Etapa 5, onde você despacha um pool limitado de trabalhadores de quadro. Não coloque regras de design ou movimento aqui; elas vivem no subagente trabalhador de quadro, nas ../hyperframes-animation/rules/ + ../hyperframes-animation/blueprints/ locais desta skill e em hyperframes-creative.
Fluxo de trabalho: Etapa 0 configuração → hyperframes.json; Etapa 1 ingestão → capture/extracted/ + assets/<login>.png; Etapa 2 sistema de design → frame.md; Etapa 3 storyboard/roteiro → STORYBOARD.md e SCRIPT.md; Etapa 3.1 áudio → audio_meta.json; Etapa 4 design visual → STORYBOARD.md enriquecido; Etapa 5 quadros → compositions/frames/NN-*.html e index.html; Etapa 6 renderização final → renders/video.mp4.
Etapa 0: Configuração
Objetivo: Entrar com um resumo confirmado — incluindo a referência do PR (uma URL completa, uma referência <owner>/<repo>#<N> ou "este PR" em um repositório verificado) — criar o projeto HyperFrames e tornar o resumo durável. O estilo é sempre code-editorial (fixado na Etapa 2, nunca perguntado).
O resumo é confirmado pela camada de intenção, não por perguntas feitas aqui. Regra de abertura, em ordem: (1) BRIEF.md existe → leia-o e não pergunte nada — o resumo está resolvido, e seu flow/storyboard derivam o modo (contrato de resumo § 1). (2) Sem BRIEF.md mas o projeto existe (hyperframes.json / STORYBOARD.md no disco) → retome do frontmatter do storyboard e das preferências registradas; nunca reinterrogue um projeto meio construído. (3) Nem um nem outro — uma solicitação de criação nova que chegou aqui diretamente → leia /hyperframes e execute sua camada de intenção (references/intent-interview.md): ela verifica receitas e padrões lembrados, e conduz as perguntas desta rota — incluindo a doutrina tamanho do PR → duração, que vive inteira em ../hyperframes/references/routes/pr-to-video.md — então devolve o resumo bloqueado. Solicitações de edição pulam tudo isso — vá fazer a edição.
Resolva o diretório do projeto antes de fazer qualquer outro trabalho. Preserve um diretório de projeto fornecido pelo usuário; caso contrário, use o local de cache externo durável impresso pelo resolvedor. Nunca crie videos/ no repositório do chamador:
PR="<url | owner/repo#N>"
if [ -n "${EXPLICIT_PROJECT_DIR:-}" ]; then
PROJECT_DIR="$(node <SKILL_DIR>/scripts/project-dir.mjs --pr "$PR" --project-dir "$EXPLICIT_PROJECT_DIR")"
else
PROJECT_DIR="$(node <SKILL_DIR>/scripts/project-dir.mjs --pr "$PR")"
fi
echo "Projeto PR para vídeo: $PROJECT_DIR"
node <SKILL_DIR>/scripts/preflight.mjs
A verificação de capacidade ocorre antes da busca, trabalho de storyboard, áudio ou despacho de quadros. Se a CLI instalada não puder executar o comando de validação exigido por esta skill, pare com sua instrução de atualização em vez de gastar o contexto da execução primeiro.
Inicialize apenas se $PROJECT_DIR/hyperframes.json estiver faltando. Seu nome base vem do PR, como acme-sdk-pr-1842; nunca use o nome do workspace ou um timestamp.
npx hyperframes init "$PROJECT_DIR" --non-interactive --example=blank --skill=pr-to-video — init verifica as skills instaladas em relação às mais recentes no GitHub e atualiza o conjunto global se alguma estiver desatualizada.
Todo comando de caminho relativo abaixo é executado com $PROJECT_DIR como seu diretório de trabalho. Exemplos sem um subshell explícito significam (cd "$PROJECT_DIR" && …); nunca mude a árvore de trabalho do repositório do chamador.
Escreva BRIEF.md imediatamente após o init (nunca antes — init recusa um diretório não vazio): o resumo bloqueado da camada de intenção, formato conforme ../hyperframes-core/references/brief-format.md. Resolva <MEDIA_DIR> como o diretório da skill /media-use instalada. Em seguida, registre cada resposta apoiada por preferência com node <MEDIA_DIR>/scripts/prefs.mjs record --hyperframes . (brief-format.md nomeia o subconjunto). Se a camada de intenção adotou uma receita, execute node <MEDIA_DIR>/scripts/recipe.mjs use --hyperframes . --name <name>; ela copia seu frame.md para o projeto (a Etapa 2 é então pulada) e retorna os esqueletos a partir dos quais a Etapa 3 elabora. Uma receita preenche respostas, não aprovações; as portas de revisão ainda são executadas.
Mostre o status de login antes de prosseguir após a Configuração — execute npx hyperframes auth status e transmita sua saída literalmente. Ele informa se a voz/BGM usará HeyGen ou mecanismos locais e, quando desconectado, como fazer login. Aplique um ramo:
- Colaborativo: aguarde o usuário fazer login ou escolher explicitamente
offline/go. - Autônomo: informe o status e continue através dos mecanismos locais disponíveis.
Não omita silenciosamente uma capacidade necessária quando nenhum provedor offline existir; exponha o bloqueador. Não dobre esta decisão em outra pergunta ou escreva chaves em um .env por repositório. Propriedade de autenticação e fallbacks offline: /media-use references/setup-providers.md § Provedores.
Porta: hyperframes.json e BRIEF.md existem; a referência do PR está capturada no resumo; as respostas apoiadas por preferência foram registradas (contrato de resumo § 2); o status de login foi mostrado (logado ou continuando offline).
Etapa 1: Ingerir o PR (sem captura)
Objetivo: Buscar os fatos do PR e integrá-los ao projeto como fonte de informação. Não há captura de site. fetch-pr.mjs executa gh deterministicamente — completando a lista de arquivos via gh api paginada para que um PR grande não seja truncado em ~100 arquivos, e escrevendo apenas capture/pr.json + capture/diff.patch (sem diretório temporário). Para PRs MERGED, ele também resolve um shipped_version (+ version_source) de melhor esforço em pr.json, para que o cartão final possa citar uma versão real em vez de inventar uma. Em seguida, ingest.mjs integra isso no pacote de captura sintético offline.
PR="<url | owner/repo#N | N>"
# Busca o PR deterministicamente: executa gh, completa a lista de arquivos via
# gh api paginada (para que um PR grande não seja truncado em ~100 arquivos), escreve apenas capture/pr.json +
# capture/diff.patch — sem diretório temporário. Erros de gh auth / não encontrado / privado saem com 1 aqui.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture)
# Transformação offline → capture/extracted/{tokens.json (colors:[] → paleta code-editorial),
# visible-text.txt (o resumo), people.json (contribuidores, filtrados por bot, nome+login,
# avatarFile=assets/<login>.png)}.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/ingest.mjs \
--pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)
# A única etapa de rede da parte de pessoas — baixa o avatar do GitHub de cada contribuidor para
# assets/<login>.png para o close de créditos. Melhor esforço; sempre sai com 0.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
Se fetch-pr.mjs sair com 1 (gh auth / não encontrado / privado), relate seu stderr e pare — não fabrique conteúdos de PR. Se ingest.mjs sair com 1, leia seu stderr (geralmente um pr.json malformado), corrija e execute novamente (determinístico). fetch-people-avatars.mjs sempre sai com 0; avatares faltando apenas significam nenhum close de créditos para o autor.
people.json carrega um name para quaisquer contribuidores que gh já nomeou (o autor do PR, autores de commit, mergedBy) — null para o resto (revisores/comentadores/designados, que gh pr view só dá um login simples). Antes de escrever o close de créditos na Etapa 3, resolva você mesmo qualquer name nulo para as 1-6 pessoas que realmente aparecerão naquele quadro: gh api users/<login> --jq .name (você já tem gh — não precisa scriptar isso). Se o GitHub também não tiver um nome público para aquele usuário, recorra ao login na tela e remova essa pessoa da linha falada (consulte a seção de créditos de story-design.md — a narração ainda deve dizer nomes, nunca handles brutos).
Porta: capture/pr.json, capture/diff.patch, capture/extracted/tokens.json, capture/extracted/visible-text.txt e capture/extracted/people.json existem; você pode declarar a mudança do PR em uma frase clara. assets/<login>.png é melhor esforço — sua ausência não é uma falha.
Etapa 2: Sistema de Design
Objetivo: Adotar o preset de quadro code-editorial; um script o transforma no frame.md + skin de legenda deste vídeo.
O estilo é fixo — code-editorial (editorial acolhedor; uma superfície de código marinho construída para diffs). Execute:
node <SKILL_DIR>/scripts/build-frame.mjs --preset code-editorial --hyperframes .
O script copia o FRAME.md do preset code-editorial → frame.md, remixa-o em quaisquer tokens de marca em capture/extracted/tokens.json (um PR não tem nenhum → colors:[]/fonts:[] mantém a própria paleta code-editorial, um design completo), copia a skin de legenda do preset para .hyperframes/caption-skin.html e autovalida (sai com 1 em um mapeamento quebrado). Prossiga assim que sair com 0 — sem edição manual.
Porta: build-frame.mjs saiu com 0 — frame.md existe a partir do preset code-editorial, e .hyperframes/caption-skin.html existe como a fonte da skin de legenda.
Etapa 3: Storyboard e Roteiro
Objetivo: Transformar o PR em um plano de explicação quadro a quadro aprovado.
Leia ../hyperframes-creative/references/story-spine.md (linguagem de gancho, valor antes da evidência, storyboard como proposta, visuais com origem rastreável), references/story-design.md, ../hyperframes-animation/blueprints-index.md, ../hyperframes-core/references/storyboard-format.md e ../hyperframes-core/references/script-format.md. Use-os para escrever STORYBOARD.md e, quando a narração for necessária, SCRIPT.md. Defina o duration: do frontmatter a partir do length do resumo — uma expectativa aproximada; a montagem relata onde o corte final fica em relação a ela.
Use story-design.md para o arquétipo do PR (changelog / revelação de recurso / explicador de correção / passo a passo de refatoração), os tipos de quadro nativos do PR, gancho, persuasão, batidas, o orçamento de palavras por quadro e o close de créditos. A sequência vem do design narrativo, não da ordem de arquivos do diff — explique a mudança, não leia o diff em voz alta. Como um guia suave, consulte o menu de papel→blueprint em ../hyperframes-animation/blueprints-index.md: para cada batida, escreva a narração na forma que seu blueprint candidato implica e marque aquele candidato id blueprint: quando um se encaixar (a verdade da história ainda decide quais batidas existem — nunca force uma batida a se encaixar em uma forma). Apresente 2–4 trechos reais de diff (de capture/diff.patch), cada um um pequeno snippet legível; nomeie o bloco code-* que cada um quer na scene do quadro. Os quadros não carregam asset_candidates exceto o close de credits (1–6 avatares assets/<login>.png). Use os campos exatos exigidos das referências de storyboard e roteiro.
Após o rascunho, execute a passagem de plano do loop de revisão — ../hyperframes-core/references/review-loop.md § 1: abra o quadro (não pergunte se deve — execute a prévia de PROJECT_DIR em segundo plano), apresente o plano como uma proposta e faça as duas perguntas — aprovar ou alterar, e esboços primeiro (recomendado) ou pular. O feedback passa pelo chat ou arquivo de comentários do quadro até aprovação. Esta é uma porta de ponto de verificação (contrato de resumo § 1): no modo autônomo não há quadro e nada a perguntar — publique o mesmo resumo como um aviso e prossiga; os esboços são incorporados na construção, e a única pergunta de prévia vem na Etapa 6.
Porta: STORYBOARD.md existe, cada quadro tem os campos narrativos exigidos, SCRIPT.md existe quando a narração é necessária, e o usuário aprovou o plano (autônomo: o resumo foi publicado como um aviso).
Etapa 3.1: Áudio
Objetivo: Gerar narração, temporizações de palavras, música e metadados de áudio a partir do roteiro aprovado.
Inicie o áudio após a aprovação da Etapa 3. Execute-o em segundo plano, depois continue para a Etapa 4.
Escolha a voz de narração a partir da solicitação do usuário antes de invocar. Se a solicitação nomeou uma voz, gênero ou tom, escolha um id de voz correspondente e passe-o com --voice <id>. O padrão do pipeline é, caso contrário, Marcia (feminina) na HeyGen / am_michael no Kokoro — portanto, uma solicitação como "uma voz masculina" é silenciosamente ignorada a menos que você passe a flag. Os ids de voz são específicos do provedor; resolva contra o provedor que o status de login da Etapa 0 selecionou: HeyGen (logado) via node <MEDIA_DIR>/audio/scripts/heygen-tts.mjs --list (ou GET /v3/voices?engine=starfish); Kokoro (offline) via a tabela de vozes em <MEDIA_DIR>/audio/references/tts.md (prefixos am_/bm_ masculino, af_/bf_ feminino). Quando o usuário não expressou preferência, recorra à voz lembrada (contrato de resumo § 2) antes do padrão do pipeline e diga qual você usou; omita --voice apenas quando nenhum dos dois nomear uma. Quando o usuário escolheu explicitamente uma ...
[... truncado para tradução ...]
Etapa 4: Design Visual
Objetivo: Enriquecer o storyboard aprovado com direção visual explícita, formas geométricas e peças de design.
Consulte as regras de animação em ../hyperframes-animation/rules/ e a paleta/blocos de design em frame.md. Crie um STORYBOARD.md enriquecido (ou um arquivo separado VISUAL_DESIGN.md se preferir) que especifique para cada quadro: layout, animações de transição, elementos visuais (caixas, setas, destaques) e posicionamento dos snippets de código. Use o blueprint: id marcado na Etapa 3 para obter formas e movimentos específicos do blueprint. Esta etapa não gera HTML nem ativos finais, apenas o plano visual.
Porta: O storyboard enriquecido existe com direção visual para cada quadro; você pode explicar o design visual de cada cena.
Etapa 5: Construir Quadros
Objetivo: Produzir os arquivos HTML dos quadros e um index.html que os orquestre.
Despache um pool limitado de trabalhadores de quadro (subagentes) para construir os quadros em paralelo. Cada trabalhador pega um quadro do storyboard enriquecido e gera compositions/frames/NN-*.html. O orquestrador então monta compositions/index.html que sequencia os quadros. Use frame.md e .hyperframes/caption-skin.html como modelos. Nenhum ativo externo é necessário, exceto os avatares de crédito baixados na Etapa 1.
Porta: compositions/frames/ contém todos os arquivos NN-*.html, e compositions/index.html existe e pode ser pré-visualizado.
Etapa 6: Renderização Final
Objetivo: Compilar os quadros, a narração e a música em um único arquivo de vídeo.
Execute o comando de renderização:
npx hyperframes render "$PROJECT_DIR/compositions" --output "$PROJECT_DIR/renders/video.mp4"
Este comando usa o HyperFrames CLI para combinar os HTMLs dos quadros com a trilha de áudio (audio_meta.json) e produzir um MP4. O tempo de renderização depende do número de quadros e da duração do áudio.
Porta do usuário (colaborativo): Apresente a prévia do vídeo (renders/video.mp4) para o usuário. Pergunte se o vídeo está aprovado ou se são necessárias alterações. Se alterações forem solicitadas, itere nas etapas apropriadas (geralmente Etapa 3 ou 4) e re-renderize.
Porta (autônomo): Simplesmente informe que o vídeo foi renderizado em renders/video.mp4.
Pós-renderização: Limpeza e Resumo
Uma vez que o vídeo seja aprovado, execute a limpeza:
- Remova artefatos temporários (
capture/diff.patch, arquivos de log) - Atualize o
BRIEF.mdcom o caminho final do vídeo e duração real - Imprima um resumo executivo:
- PR:
<owner>/<repo>#<N> - Vídeo:
renders/video.mp4 - Duração:
<N>s - Quadros:
<N> - Narração:
<voice_id> - Alterações: breves pontos sobre os snippets de código apresentados
- PR: