Instalação do Plugin: Antes dos comandos de configuração ou atualização, siga as regras de execução do plugin quando esta skill estiver dentro de um plugin HyperFrames. Instalações independentes mantêm as instruções de atualização abaixo.
Primeiro, mantenha esta skill atualizada — confirme com o usuário antes de executar:
npx hyperframes skills update pr-to-video. Uma operação rápida e sem efeitos colaterais quando tudo está atualizado; caso contrário, atualiza esta skill e as skills de domínio core das quais ela depende, antes de você confiar nelas.
media-use: Antes de obter áudio/imagens/logos, chame
/media-usepara resolver BGM/SFX/imagens do catálogo HeyGen e logotipos de marcas de suas fontes oficiais. Execute--adoptprimeiro para registrar ativos existentes. Consulte a skill/media-use.
PR para HyperFrames
Use esta skill para ingerir um pull request do GitHub, entender a mudança, planejar um vídeo explicativo 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 nenhum ativo real além dos avatares dos contribuidores.
A porta de entrada é
/hyperframes. Você é o orquestrador. Execute cada etapa, verifique seu gate, 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 possui todas as decisões 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 gate antes de continuar. As etapas com gate do usuário são Etapa 0, Etapa 3 e Etapa 6. Leia ../hyperframes/references/brief-contract.md antes da Etapa 0 — ele define os tipos de gate e como flow/storyboard do BRIEF.md derivam o modo que rege os gates das Etapas 3/4/6. Execute cada etapa você mesmo, exceto a Etapa 5, onde você despacha um pool limitado de workers de frame. Não coloque regras de design ou movimento aqui; elas vivem no sub-agente worker de frame, neste diretório local ../hyperframes-animation/rules/ + ../hyperframes-animation/blueprints/ e 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 frames → compositions/frames/NN-*.html e index.html; Etapa 6 renderização final → renders/video.mp4.
Etapa 0: Configuração
Objetivo: Entrar com um brief confirmado — incluindo a referência do PR (uma URL completa, uma ref <owner>/<repo>#<N> ou "este PR" em um repositório clonado) — criar o projeto HyperFrames e tornar o brief durável. O estilo é sempre code-editorial (fixado na Etapa 2, nunca perguntado).
O brief é confirmado pela camada de intenção, não por perguntas feitas aqui. Regra de abertura, em ordem: (1) BRIEF.md existe → leia e não pergunte nada — o brief está resolvido, e seu flow/storyboard derivam o modo (contrato do brief § 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 já parcialmente construído. (3) Nenhum dos dois — 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 reside inteiramente em ../hyperframes/references/routes/pr-to-video.md — então retorna o brief 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-to-video: $PROJECT_DIR"
node <SKILL_DIR>/scripts/preflight.mjs
A verificação de capacidade (preflight) é executada antes da busca, trabalho de história, áudio ou despacho de frames. 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.
Todos os comandos com caminho relativo abaixo são executados com $PROJECT_DIR como diretório de trabalho. Exemplos sem um subshell explícito significam (cd "$PROJECT_DIR" && …); nunca altere 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 brief bloqueado da camada de intenção, formato conforme ../hyperframes/references/brief-format.md. Resolva <MEDIA_DIR> como o diretório da skill /media-use instalada. Em seguida, registre cada resposta baseada em 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 ignorada) e retorna os esqueletos a partir dos quais a Etapa 3 elabora os rascunhos. Uma receita preenche respostas, não aprovações; os gates de revisão ainda são executados.
Mostre o status de login antes de prosseguir após a Configuração — execute npx hyperframes auth status e repita 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 coloque esta decisão dentro de 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.
Gate: hyperframes.json e BRIEF.md existem; a ref do PR está capturada no brief; as respostas baseadas em preferência foram registradas (contrato do brief § 2); o status de login foi mostrado (conectado ou continuando offline).
Etapa 1: Ingerir o PR (sem captura)
Objetivo: Buscar os fatos do PR e incorporá-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 paginado 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 de melhor esforço (+ version_source) em pr.json, para que o cartão final possa citar uma versão real em vez de inventar uma. Em seguida, ingest.mjs incorpora 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
# paginado (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 código 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 brief), people.json (contribuidores, filtrados por bot, name+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 frente de pessoas — baixa o avatar do GitHub de cada
# contribuidor para assets/<login>.png para os créditos finais. 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 código 1 (gh auth / não encontrado / privado), relate seu stderr e pare — não fabrique conteúdos de PR. Se ingest.mjs sair com código 1, leia seu stderr (geralmente um pr.json malformado), corrija e execute novamente (determinístico). fetch-people-avatars.mjs sempre sai com 0; avatares ausentes apenas significam que não há créditos para o autor.
people.json carrega um name para quaisquer contribuidores que gh já nomeou (o autor do PR, autores de commits, mergedBy) — null para o resto (revisores/comentadores/designados, que gh pr view só fornece como login puro). Antes de escrever os créditos finais 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 criar script para isso). Se o GitHub não tiver um nome público para aquele usuário, use o login na tela e remova essa pessoa da fala (veja a seção de créditos do story-design.md — a narração ainda deve dizer nomes, nunca handles brutos).
Gate: 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 é de melhor esforço — sua ausência não é uma falha.
Etapa 2: Sistema de Design
Objetivo: Adotar o preset de frame 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 azul 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 sobre quaisquer tokens de marca em capture/extracted/tokens.json (um PR não tem nenhum → colors:[]/fonts:[] mantém a paleta própria do code-editorial, um design completo), copia a skin de legenda do preset para .hyperframes/caption-skin.html e se autovalida (sai com 1 em um mapeamento quebrado). Prossiga assim que ele sair com 0 — sem edição manual.
Gate: build-frame.mjs saiu com 0 — frame.md existe a partir do preset code-editorial, e .hyperframes/caption-skin.html existe como 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 de evidência, storyboard como proposta, visuais com rastreabilidade de fonte), references/story-design.md, ../hyperframes-animation/blueprints-index.md, ../hyperframes/references/storyboard-format.md e ../hyperframes/references/script-format.md. Use-os para escrever STORYBOARD.md e, quando a narração for necessária, SCRIPT.md. Defina a duration: do frontmatter a partir do length do brief — uma expectativa aproximada; o relatório de montagem informa onde o corte final se alinha em relação a ele.
Use story-design.md para o arquétipo do PR (changelog / revelação de funcionalidade / 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 os créditos finais. 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 função→blueprint em ../hyperframes-animation/blueprints-index.md: para cada batida, escreva a narração no formato que seu blueprint candidato implica e marque esse candidato com o id blueprint: quando um se encaixar (a verdade da história ainda decide quais batidas existem — nunca force uma batida a se encaixar em um formato). Destaque 2–4 trechos reais de diff (de capture/diff.patch), cada um um snippet pequeno e legível; nomeie o bloco code-* que cada um deseja na cena do quadro. Os quadros não carregam asset_candidates, exceto o fechamento 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/references/review-loop.md § 1: apresente o plano como uma proposta e faça as duas perguntas — aprovar ou alterar, e esboços primeiro (recomendado) ou pular. O feedback chega como uma resposta de chat; repita até a aprovação. Este é um gate de checkpoint (contrato do brief § 1): no modo autônomo não há nada a perguntar — publique o mesmo resumo como um aviso e prossiga; os esboços se consolidam na construção, e a pré-visualização final com sua única pergunta vem na Etapa 6.
Gate: 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, tempos de palavra, 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 e 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) no 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 qual provedor o status de login da Etapa 0 selecionou: HeyGen (conectado) via node <MEDIA_DIR>/audio/scripts/heygen-tts.mjs --list (ou GET /v3/voices?engine=starfish); Kokoro (offline) via a tabela de voz 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 do brief § 2) antes do padrão do pipeline.
[... truncado para tradução]