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 quando tudo está atualizado; caso contrário, atualiza esta skill e as skills de domínio principais das quais ela depende antes que você confie nelas.
media-use: Antes de obter áudio/imagens/logos, chame
/media-usepara resolver BGM/SFX/images do catálogo HeyGen e logotipos de marca de suas fontes oficiais. Execute--adoptprimeiro para registrar assets existentes. Veja 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 vídeo explicativo da 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 assets reais além dos avatares dos contribuidores.
A porta de entrada é
/hyperframes. Você é o orquestrador. Execute cada etapa, verifique sua porta (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 é dona de toda decisão de rota, e uma criação nova que chega aqui semBRIEF.mdpassa por ela de qualquer forma (regra inicial 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 verificação 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 porta e como o flow/storyboard do BRIEF.md derivam o modo que governa as portas das Etapas 3/4/6. Faça cada etapa você mesmo, exceto a Etapa 5, onde você despacha um pool limitado de trabalhadores de quadro. Não coloque regras de design ou movimento aqui; elas estão no sub-agente trabalhador de quadro, no ../hyperframes-animation/rules/ + ../hyperframes-animation/blueprints/ locais desta skill e no 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 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 código-editorial (fixado na Etapa 2, nunca perguntado).
O brief é confirmado pela camada de intenção, não por perguntas feitas aqui. Regra inicial, em ordem: (1) BRIEF.md existe → leia-o 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 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 de tamanho do PR → duração do vídeo, que vive inteira em ../hyperframes/references/routes/pr-to-video.md — então devolve 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-para-vídeo: $PROJECT_DIR"
node <SKILL_DIR>/scripts/preflight.mjs
A verificação de capacidade pré-voo (preflight) é executada antes da busca, do trabalho de story, do áudio ou do 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 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 com suporte de 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 <nome>; 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 rascunha. 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 repita sua saída literalmente. Ele informa se a voz/BGM usará os mecanismos HeyGen ou 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 pelos mecanismos locais disponíveis.
Não omita silenciosamente uma capacidade necessária quando não existir provedor offline; mostre o bloqueador. Não coloque esta decisão em outra pergunta nem escreva chaves em um .env por repositório. Propriedade de autenticação e fallbacks offline: /media-use references/setup-providers.md § Providers.
Porta: hyperframes.json e BRIEF.md existem; a ref do PR está capturada no brief; as respostas com suporte de preferência foram registradas (contrato do brief § 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 incorporá-los ao projeto como a 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. gh auth / not-found /
# private erros 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 código-editorial),
# visible-text.txt (o brief), 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 GitHub de cada contribuidor para
# assets/<login>.png para os créditos finais. Melhor esforço; sempre sai com código 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 / not found / private), relate seu stderr e pare — não fabrique conteúdos do 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 código 0; avatares ausentes apenas significam que não haverá créditos finais para o autor.
people.json carrega um name para quaisquer contribuidores que o gh já nomeou (o autor do PR, autores de commit, mergedBy) — null para o restante (revisores/comentadores/designados, que gh pr view sempre dá apenas um login simples). Antes de escrever os créditos finais na Etapa 3, resolva qualquer name nulo você mesmo 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 não tiver um nome público para aquele usuário, fall back para 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).
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 é de melhor esforço — sua ausência não é uma falha.
Etapa 2: Sistema de Design
Objetivo: Adotar o preset de quadro código-editorial; um script o transforma no frame.md deste vídeo + skin de legenda.
O estilo é fixo — código-editorial (editorial acolhedor; uma superfície de código azul-marinho projetada para diffs). Execute:
node <SKILL_DIR>/scripts/build-frame.mjs --preset code-editorial --hyperframes .
O script copia o FRAME.md do preset código-editorial para frame.md, remixa-o com quaisquer tokens de marca em capture/extracted/tokens.json (um PR não tem nenhum → colors:[]/fonts:[] mantém a própria paleta do código-editorial, um design completo), copia a skin de legenda do preset para .hyperframes/caption-skin.html e se autovalida (sai com código 1 em um mapeamento quebrado). Prossiga assim que ele sair com código 0 — sem edição manual.
Porta: build-frame.mjs saiu com código 0 — frame.md existe a partir do preset código-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 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 duration: no frontmatter a partir do length do brief — uma expectativa aproximada; a montagem relata onde o corte final cai em relação a ela.
Use story-design.md para o arquétipo do PR (changelog / feature-reveal / fix-explainer / refactor-walkthrough), 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 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 esse candidato com o blueprint: id quando um se encaixar (a verdade da história ainda decide quais batidas existem — nunca force uma batida a se encaixar em uma forma). Destaque 2–4 hunks 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 credits close (1–6 avatares assets/<login>.png). Use os campos exatos exigidos das referências de storyboard e roteiro.
Após rascunhar, 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é aprovar. Esta é uma porta de verificação (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 colapsam na construção, e a única pergunta de pré-visualização 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, timings 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 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 é Marcia (feminino) no HeyGen / am_michael no Kokoro — portanto, uma solicitação como "uma voz masculina" é ignorada silenciosamente 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, fall back para a voz lembrada (contrato do brief § 2) antes do padrão do pipeline, e diga qual você usou; omita --voice apenas quando nenhum nomear uma. Quando o usuário escolheu explicitamente uma voz nesta execução, registre-a (prefs.mjs record --key voice).
node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STOR...
[continua...]