pr-to-video - ponto de entrada de despacho
A entrada é uma Pull Request do GitHub (uma mudança de código), fornecida como uma URL de PR, uma referência <owner>/<repo>#<N>, ou "esta PR" enquanto um repositório com uma PR aberta está em checkout. A saída é um vídeo explicativo da mudança de código: o que foi enviado, por que, e como funciona — renderizado a partir do diff/commits como cenas de antes-depois, destaque de diff, árvore de arquivos e impacto. Duração padrão de até ~3 min (ponto ideal ~30-90s); uma apresentação genuinamente mais longa ou exaustiva de cada arquivo (5 min+) é um registro diferente → /general-video. Não há scraping de site e nem Chrome headless para ingestão — a ingestão é feita pela CLI gh. O preset de estilo enviado é sempre claude (editorial acolhedor; janela de código azul-marinho característica).
Confirme a rota antes do Passo 0. Esta skill explica uma Pull Request do GitHub (uma mudança de código lida via
gh). Se a entrada for um site de marketing / produto →/product-launch-video; um site genérico →/website-to-video; um tópico / artigo sem PR →/faceless-explainer; um tour de repositório inteiro ou release multi-PR →/general-video. Fora do escopo: dados ativos / em tempo de renderização — os fatos da PR são lidos uma vez no momento de autoria e incorporados. Se receber uma entrada que não seja PR, ou não tiver certeza? Leia/hyperframesprimeiro.
Este fluxo de trabalho é dono apenas da parte específica da PR (ingestão + design da história); toda fase marcada como compartilhada reutiliza o mecanismo copiado do faceless-explainer inalterado (ele reside sob os próprios scripts/ + agents/ + phases/ desta skill, então <SKILL_DIR> resolve para pr-to-video).
Todos os artefatos vão para PROJECT_DIR = videos/<project-name>/ (criado no Passo 0); todos os caminhos abaixo são relativos a ele. O despacho é portável entre harnesses: antes do primeiro despacho de subagente, leia <SKILL_DIR>/../hyperframes-core/references/subagent-dispatch.md uma vez — ele mapeia os verbos de despacho (fan-out paralelo / background / wait) para os primitivos do seu harness; um limite de concorrência abaixo de N significa ondas do tamanho do limite, nunca menos workers. Este arquivo é um runbook vinculante, não leitura de fundo: execute os passos em ordem e produza cada artefato de fase com seu script designado ou papel de agente — não substitua por um pipeline livre, e não pule um passo de pausa porque o pedido parece claro. Um passo que você não pode executar → pare e relate.
| Fase | Execução | Artefato principal | Fluxo detalhado |
|---|---|---|---|
| init | Bash | hyperframes.json | Passo 0 |
| ingest (própria) | Bash (CLI gh + ingest.mjs + fetch-people-avatars.mjs, SEM agente, SEM scraping) | capture/pr.json + diff.patch + extracted/{tokens.json,visible-text.txt,people.json} + public/avatars/ | Passo 1 |
| design-system (compartilhada) | Bash (sem agente, claude determinístico) | design-system/design.html + chunks/ | Passo 1b |
| story-design (própria) | subagente | narrator_scripts.json | agents/story-design.md |
| áudio (compartilhada) | audio.mjs no Bash | audio_meta.json | phases/audio/guide.md |
| visual-design (compartilhada) | subagente | section_plan.md | agents/visual-design.md |
| prep (compartilhada) | prep.mjs no Bash | group_spec.json | scripts/prep.mjs |
| legendas (compartilhada, detalhada) | captions.mjs group -> captions.mjs html no Bash (sem subagente) | caption_groups.json + compositions/captions.html | scripts/captions.mjs |
| cenas (compartilhada) | N x subagente (paralelo) | compositions/scene_*.html ou compositions/group_w*.html | agents/hyperframes-scene.md |
| finalizar (compartilhada) | Prelúdio Bash (wait-bgm + montar + injetar/verificar transições + hoist-videos + sfx-verify + preflight) -> subagente finalizar (corrigir achados breves no local + uma olhada enxuta de contato + renderizar) | renders/video.mp4 | Passo 7 / agents/hyperframes-finalize.md |
Pré-requisitos
macOS Apple Silicon ou Linux x64. Ferramentas do sistema: brew install [email protected] node ffmpeg (use Homebrew Python, não /usr/bin/python3, ou pip install será bloqueado pelo PEP 668); depois npx hyperframes doctor uma vez (baixa o Chrome — necessário para snapshot/render, não para ingestão). O gate de sobreposição renderizado (scripts/check-overlap.mjs, executado em auto-verificações de worker e preflight) reutiliza o mesmo Chrome em cache — ele nunca baixa um navegador; sua única dependência é o módulo npm puppeteer-core, garantido uma vez antes do fan-out de cenas (Passo 5.5, --ensure-deps, ~5s, sem instalação completa de puppeteer). CLIs: gh (GitHub CLI, autenticado — gh auth status deve passar) e hyperframes. Chaves de nuvem opcionais (senão fallbacks locais) — injete no Passo 0.5:
| Chave / requisito | Usado para | Padrão / fallback |
|---|---|---|
gh auth status OK | Ler a PR (pública ou privada) | obrigatório — falhe rápido com a dica de autenticação |
HEYGEN_API_KEY (ou hyperframes auth login) | TTS (nuvem, timestamps em nível de palavra) | voz: auto (primeira voz starfish em inglês; sobrescreva com --voice) |
ELEVENLABS_API_KEY | TTS (nuvem; precisa de pip install elevenlabs) | voz 21m00Tcm4TlvDq8ikWAM (Rachel) |
| nenhuma, e não logado | TTS | Kokoro local, voz am_michael (não inglês: passe --voice) |
GEMINI_API_KEY / GOOGLE_API_KEY (alias) | Música de fundo Lyria | não definido -> MusicGen local (primeira execução baixa ~300 MB) |
Fluxo
Passo 0.0 - Confirme o briefing (SEMPRE pergunte uma rodada, depois construa)
Antes do Passo 0, sempre pause e pergunte o briefing em uma mensagem, depois aguarde o usuário — nunca pule isso, mesmo para um pedido que pareça completo. Lidere com um padrão recomendado para cada campo e pré-preencha qualquer coisa que o usuário já deu (confirme em vez de perguntar cegamente): o ângulo (changelog / revelação de funcionalidade / correção / refatoração — padrão: inferir da PR), o público (desenvolvedores vs usuários gerais — padrão: desenvolvedores), duração (padrão ~60-90s), e — se /hyperframes não os definiu — aspecto (padrão 16:9) e idioma. O estilo é sempre claude. Prossiga para o Passo 0 somente após o usuário responder; uma resposta "vai" / "use os padrões" é uma resposta válida que aceita todos os padrões.
Passo 0 - Inicialize o projeto de vídeo
cwd é a raiz do workspace do agente (ex.: /tmp/pr-video-...). Escreva todos os artefatos de vídeo sob PROJECT_DIR = videos/<project-name>/.
<project-name>: use o diretório que o usuário deu (ex.: Use ./videos/retry-pr), senão um nome curto em kebab-case derivado da PR (<repo>-pr-<N>, ex.: widgets-pr-1187). Não o nome base do workspace ou um timestamp.
Apenas quando $PROJECT_DIR/hyperframes.json estiver ausente:
PROJECT_DIR="${PR_VIDEO_DIR:-videos/<project-name>}"
mkdir -p "$(dirname "$PROJECT_DIR")"
npx hyperframes init "$PROJECT_DIR" --non-interactive --skip-skills --example=blank
hyperframes initcoloca umAGENTS.md/CLAUDE.mdgenérico em$PROJECT_DIR; deixe-os no lugar — são andaimes de agente para quem abrir o projeto finalizado depois.
Restrições: nunca execute hyperframes init / gere AGENTS.md / CLAUDE.md na raiz do workspace; nunca aninhe outro hyperframes/ dentro de PROJECT_DIR; todo comando Bash (master + subagentes) é um subshell (cd "$PROJECT_DIR" && ...) — nunca cd puro.
Passo 0.5 - Orientação de chaves de API
Pule se $PROJECT_DIR/.env existir ou context.log não estiver vazio (= não é a primeira execução). Caso contrário, primeiro detecte o que está disponível (HeyGen TTS ligado se $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY definido ou ~/.heygen/credentials existir de hyperframes auth login; ElevenLabs / Gemini apenas se suas chaves de ambiente estiverem definidas), depois sempre pause e ofereça o menu — aguarde o usuário; não prossiga por conta própria mesmo quando uma configuração funcional for detectada (o usuário pode querer adicionar uma chave como Gemini). Informe o que foi detectado, depois: cole chaves (→ Escreva $PROJECT_DIR/.env, uma CHAVE=valor por linha, sobrescreva mesmo nome) / "vai" (prossiga com o que está configurado — env, .env, ou hyperframes auth login) / "pular" (prossiga com fallbacks locais para qualquer coisa não configurada). Depois prossiga para o Passo 1.
Passo 1 - Ingestão (Bash, SEM agente, SEM scraping)
Resolva a referência da PR e extraia fatos estruturados com gh, depois dobre-os no pacote de captura sintético que o backend compartilhado espera (espelha o scaffold sem scraping do faceless-explainer). gh é executado aqui, no orquestrador, então erros de autenticação / não encontrado / repositório privado aparecem com o stderr do próprio gh; ingest.mjs é uma transformação puramente offline.
# Referência da PR: uma URL completa, "<owner>/<repo>#<N>", ou "<N>" dentro de um repositório com checkout.
PR="<url | owner/repo#N | N>"
# Falhe rápido se gh não estiver autenticado.
gh auth status || { echo "gh não autenticado — execute: gh auth login"; exit 1; }
(cd "$PROJECT_DIR" && mkdir -p capture/extracted capture/assets)
(cd "$PROJECT_DIR" && gh pr view "$PR" \
--json number,title,body,author,url,baseRefName,headRefName,commits,files,additions,deletions,changedFiles,labels,reviews,latestReviews,comments,assignees,reviewDecision,mergedBy \
> capture/pr.json)
(cd "$PROJECT_DIR" && gh pr diff "$PR" > capture/diff.patch)
# Dobre pr.json + diff.patch em tokens.json (colors:[] → paleta nativa claude) +
# visible-text.txt (o resumo narrativo) + people.json (autor da PR + autores de commits com contagens +
# revisores / comentadores / designados, filtrados por bot + deduplicados, cada um com URL de avatar do GitHub).
# (O `author` da PR é apenas o abridor; autores de commits de commits[].authors[] também são rastreados.)
# ingest é OFFLINE.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/ingest.mjs \
--pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)
# Etapa de rede (a única da frente de pessoas — ingestão permanece offline): baixe
# o avatar do GitHub de cada contribuidor para public/avatars/<login>.png para um encerramento opcional
# de créditos / enviado por. Melhor esforço — um avatar ausente ou execução offline nunca bloqueia (exit 0).
# Avatares + esse encerramento são o ÚNICO lugar onde pr-to-video relaxa o padrão faceless.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
Validação:
[ -s "$PROJECT_DIR/capture/pr.json" ] && \
[ -s "$PROJECT_DIR/capture/diff.patch" ] && \
[ -s "$PROJECT_DIR/capture/extracted/tokens.json" ] && \
[ -s "$PROJECT_DIR/capture/extracted/visible-text.txt" ] && \
[ -s "$PROJECT_DIR/capture/extracted/people.json" ] && \
[ -d "$PROJECT_DIR/capture/assets" ] && echo ok || echo faltando
# public/avatars/ é melhor esforço — sua ausência NÃO é uma falha (nenhum avatar resolvido / offline).
Se gh errar (autenticação / não encontrado / privado), relate o stderr exato e pare — não invente conteúdos da PR. Se ingest.mjs sair
…
[truncado para tradução]