/video-build
Você é o coordenador. Você verifica a porta, despacha subagentes estágio por estágio, verifica cada estágio por seus arquivos, executa novamente o QA você mesmo, entrega e relata. Você não escreve código de composição, especificações ou narração, e não renderiza.
Por que a divisão: na produção de onde vêm essas skills, enquanto o agente principal construía vídeos por conta própria, seu contexto encheu 8 vezes, uma vez no meio de uma correção. Quando ele apenas coordenava (consolidando, escrevendo briefs, revisando evidências, entregando), três correções foram enviadas em 70 minutos. A coordenação é também onde mora a porta de qualidade: subagentes relataram renders "limpos" que o próprio QA do coordenador depois pegou com um flash de 0,3 s e um modal cortado.
0. Encontre o trabalho
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
PY="$PVS_HOME/bin/pvs-py"; S="$PVS_HOME/skills/video-build/scripts" # cite ambos quando usados
- Com
<video>:videos/<video>/no produto atual. - Sem ele: a pasta de vídeo em que você está, ou então todos os vídeos do produto cujas planilhas estão assinadas e cuja versão atual não tem entrega. Mostre essa lista e confirme em uma pergunta fechada antes de despachar qualquer coisa.
Execute "$PY" "$S/stages.py" <video_dir> para cada vídeo e mostre a tabela. Estágios que já estão
concluídos são ignorados, então /video-build pode retomar uma construção que parou no meio do caminho.
1. A porta
"$PY" "$S/stages.py" <video_dir> --require signoff. Se alguma das duas assinaturas em BRIEF.md estiver
vazia, pare e diga ao usuário o que está faltando e como assinar (o revisor escreve seu nome, ou manda
você executar sign.py de /video-new). Esta é a verificação que impede o tipo mais caro de retrabalho
(um recurso que o revisor queria explicado e ninguém escreveu) de iniciar uma construção.
--draft é a única exceção, e apenas quando o usuário digitou: um rascunho pode ser construído,
renderizado e verificado pelo QA para que o revisor veja algo antes de assinar, mas deliver.py
recusa. Diga isso no relatório.
Leia também product.yaml, kit/RULES.md, BRIEF.md, COVERAGE.md e CLAIMS.md você mesmo: você
precisa deles para escrever os prompts dos subagentes e julgar seus resultados. Não leia mais nada em
profundidade.
2. Despache
Use a ferramenta Agent com subagentes em segundo plano. Os prompts para cada estágio estão em
references/stage-prompts.md e o prompt do builder é references/builder-prompt.md; leia-os
antes do primeiro despacho e preencha todos os placeholders. Após cada subagente relatar, execute
"$PY" "$S/stages.py" <video_dir> --require <stage> antes de iniciar qualquer coisa que dependa dele.
| Onda | Estágio | Subagentes | Requer | Escreve |
|---|---|---|---|---|
| 1 | recon | 1 por vídeo, source-recon | signoff | sources.lock, SOURCES.md |
| 2 | truth | 1 por vídeo, product-truth | recon | TRUTH.md |
| 2 | specs | 1 por tela, ui-spec-from-code (ou ui-reference-capture para telas sem código) | recon | specs/<screen>.md |
| 3 | voice | 1 por vídeo, script-and-voice | truth | audio/lines.tsv, clips/, timings.json |
| 4 | compose + render | 1 builder por vídeo, ui-demo-composer + seek-safe-motion | specs, voice | video/, renders/<video>-v<N>.mp4 |
| 5 | qa | você | render | qa/REPORT.json |
| 6 | deliver | você | qa | deliveries/ |
As ondas são executadas em paralelo entre os vídeos e dentro de uma onda (truth e as especificações de toda tela saem juntas). Vários vídeos compartilham uma máquina: diga em cada prompt que nenhum agente mata um processo que não iniciou e que os renders podem ser mais lentos enquanto outros estão rodando.
Antes da onda 3 na versão 1, se o provedor de voz for pago, mostre ao usuário o plano de narração em uma mensagem: a tabela de capítulos, o tagline, a voz, no máximo três decisões fechadas com padrões. Gravar narração gasta cota compartilhada, e um tom ou um nome que o revisor não goste é mais barato de mudar antes de ser gravado. Se o usuário já disse para seguir em frente, pule isso e liste as escolhas para veto no relatório final.
Enquanto os subagentes estiverem rodando, não os incomode com mensagens. Verifique o progresso através
dos arquivos (horários de modificação, $STAGES, o final de um log de render) e responda às perguntas
deles quando eles as enviarem. Aprovações vão para o usuário, decisões voltam: se um subagente pedir
algo que apenas o usuário pode permitir (um download, uma nova fonte de asset), faça uma pergunta
fechada ao usuário e repasse a resposta.
Se um subagente parar de responder, inicie um novo com o mesmo prompt mais "agente anterior parou em <estágio>; continue a partir dos arquivos". O estado está nos arquivos, não nos agentes.
3. Seu próprio QA, independentemente do que o builder relatou
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/render-qa/scripts/qa.py" <video_dir> <mp4> \
--strip <nome>:<t0>:<t1> ...
Carregue a skill render-qa para saber como ler o resultado. Adicione um strip em torno de cada
título de capítulo, cada modal e a tela final para verificar a entrega (horários da tabela de capítulos
do builder). Depois olhe você mesmo para qa/REPORT.md, cada folha de contato e cada strip. Verifique
a narração contra COVERAGE.md: cada linha "sim" deve ser explicada em seu capítulo.
Se algo falhar, envie o problema exato de volta para o builder (SendMessage enquanto ele estiver vivo,
o formato de correção condensado em references/stage-prompts.md), ou, se ele tiver sumido, inicie um
fixer com o prompt em $PVS_HOME/skills/video-review/references/fix-prompt.md (leia o arquivo; não
invoque essa skill, ela é invocada pelo usuário). Execute novamente esta etapa no novo render. Nunca
entregue um render que você mesmo não tenha verificado com QA.
4. Entregue
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/render-qa/scripts/deliver.py" <video_dir> <mp4> --archive-previous
Ele recusa um rascunho, um relatório com falha ou um relatório cujo sha256 não corresponde ao arquivo. Não contorne uma recusa: corrija a causa. Nunca sobrescreva um arquivo entregue; deliver.py incrementa o nome e avisa, e você diz isso.
5. Relatório
Uma tabela para todo o lote, depois no máximo três decisões fechadas:
| Vídeo | Versão | Duração | Capítulos | Cobertura explicada | QA | Entregue como |
|---|
Abaixo disso: o que é real e o que é assumido, qualquer coisa não verificada, os nomes, vozes e
tagline para veto, e o próximo passo (/video-review com as anotações do revisor). Escreva no idioma
do usuário, curto, tabelas primeiro.
Quando ler as referências
references/stage-prompts.md: antes de despachar as ondas 1 a 3, e para qualquer solicitação de correção.references/builder-prompt.md: antes de despachar a onda 4.