nanxnguyen/remotion-ai-agentic-studio

Fluxo de trabalho de produção de vídeo

Este é o único fluxo de trabalho de produção para novos vídeos neste repositório. video-director é o dono do resultado final e do status. Use .claude/skills/viral-tech-video-creator/SKILL.md para técnicas de pesquisa e escrita e .claude/skills/video-shotcraft/SKILL.md para referências de cena, movimento e som. Quando esses recursos discordarem deste arquivo, siga este arquivo. Leia CLAUDE.md e as referências selecionadas antes de trabalhar. Responda em vietnamita; escreva código em inglês.

O fluxo de trabalho é totalmente automático: os agentes produzem, revisam e aprovam pelos próprios gates, e nenhuma etapa espera pela aprovação manual do usuário. Nunca termine um turno ou um relatório de agente com "gửi bạn nghe thử / duyệt giúp / OK chưa"; escolha a melhor opção, registre a decisão em docs/<vid>/ e continue. Pergunte ao usuário apenas quando uma entrada crítica estiver faltando e não puder ser inferida com segurança, ou quando o usuário solicitar explicitamente um gate de decisão. A audição humana (áudio, MP4 final) são registros opcionais, nunca perguntas ou bloqueadores. Revisores independentes usam contexto limpo. Mantenha literalmente apenas as linhas do usuário que ele marcou como obrigatórias; todo o resto pode ser dramatizado ou reescrito para servir à história (veja a lição do gate-A em Pontos comuns de falha). A publicação requer uma solicitação separada do usuário.

Modo leve. Para um vídeo curto (story), ou quando o usuário forneceu o roteiro/voz, o diretor pode mesclar etapas sem pular nenhum gate: um research-agent, sem arquivo de pesquisa quando a conta do usuário é a fonte, os três ramos da Fase 3 em uma mensagem paralela, e task-planner com um scene-agent para cada 3-4 planos. Gates A, D, E, B, C, as revisões dos ramos de conteúdo e áudio, a disciplina de correção em loop e a propriedade dos arquivos sempre permanecem.

Mapa do pipeline

Após o gate A, o trabalho se divide em três ramos paralelos (conteúdo, áudio, design), cada um com seu próprio produtor → revisor em contexto limpo. Quando todos os três passam, video-director os une e o gate E revisa o plano combinado antes da construção.

flowchart TD
  P0["0 Intake<br/>intake-agent ×2-3"] --> P1["1 Research<br/>research-agent ×N"]
  P1 --> P2["2 Script<br/>script-agent"]
  P2 --> A{"Gate A ≥ 9<br/>script-reviewer"}
  A -- "revise (≤3 rounds)" --> P2
  A -- pass --> FORK(("fork"))

  subgraph BR["3 · Três ramos paralelos"]
    direction LR
    subgraph B1["3a Conteúdo"]
      CA["content-agent<br/>content-pack.md"] --> CR{"content-reviewer ≥ 9"}
      CR -- revise --> CA
    end
    subgraph B2["3b Áudio"]
      VA["voice-agent + audio-agent<br/>sN.mp3, BGM/SFX, mix plan"] --> AR{"audio-reviewer ≥ 9"}
      AR -- revise --> VA
    end
    subgraph B3["3c Design"]
      DA["design-agent<br/>proto, style frames, cover, board"] --> DR{"Gate D ≥ 9<br/>design-reviewer"}
      DR -- revise --> DA
    end
  end

  FORK --> CA
  FORK --> VA
  FORK --> DA
  CR -- pass --> J
  AR -- pass --> J
  DR -- pass --> J
  J["4 Join<br/>video-director: voice.json, timeline.ts,<br/>reconcile timing / text / mood"] --> E{"Gate E ≥ 9<br/>integration-reviewer"}
  E -- "ticket → owning branch" --> BR
  E -- pass --> P6["6 Tasks<br/>task-planner"]
  J -.->|"early scaffold"| P7
  P6 --> B{"Gate B ≥ 8<br/>task-reviewer"}
  B -- pass --> P7["7 Build<br/>scene-agent ×N"]
  P7 --> P8["8 QA<br/>qa-agent ×N"]
  P8 --> P9["9 Render<br/>render-agent"]
  P9 --> C{"Gate C ≥ 8 · BARREIRA FINAL<br/>full re-test on the MP4<br/>final-check.md all ✓ + video-reviewer ×3"}
  C -- "fix → owner, re-render, re-test everything" --> P7
  C -- pass --> P10["10 Delivery<br/>video-director"]

Texto alternativo: 0 Intake → 1 Research → 2 Script ⇒ A → fork[ 3a content-agent ⇒ content-reviewer | 3b voice+audio ⇒ audio-reviewer | 3c design-agent ⇒ D ] → 4 Join → E → 6 Tasks ⇒ B → 7 Build → 8 QA → 9 Render ⇒ C → 10 Delivery.

Contrato e nomeação

• Um vídeo tem um ID de tópico único em kebab-case minúsculo <vid>, um slug de voz <voice>, docs/<vid>/, src/<vid>/, public/audio/<vid>/, e out/qa/<vid>-*.png.
• O único vídeo final é out/<vid>-<voice>-reel.mp4, por exemplo out/cam-on-phien-ban-minh-anh-khoi-reel.mp4. O slug de voz descreve a voz realmente ouvida. Quando a voz mudar, execute python3 -I scripts/pipeline.py voice <vid> <new-voice> antes de renderizar; o arquivo anterior permanece disponível.
• Comece com python3 -m unittest scripts.test_voice_catalog para garantir que as prévias do catálogo sejam resolvidas. Escolha um candidato de vietnamese-voice-samples/previews/ (a pasta é o catálogo; os nomes de arquivo são nomes de voz abreviados) pela descrição do catálogo e pela solicitação do usuário, e registre o provedor e seu ID de voz em brief.md. Uma prévia não concede direitos comerciais ou de clonagem por si só.
• Após a verificação de tópico duplicado da Fase 0 ser concluída, inicialize uma vez: python3 -I scripts/pipeline.py init <vid> --comp <CompId> --voice <voice> --profile story|product|knowledge|news. --voice é obrigatório para novas produções: passe o melhor palpite atual, então execute pipeline.py voice <vid> <slug> assim que a rota for decidida (o slug deve nomear a voz realmente ouvida); --out é apenas para nomes de saída legados. Inicie ou reutilize o Pipeline Monitor na porta 4180 antes de despachar agentes de produção. Não edite status.json manualmente.
• Ao redor de cada etapa de trabalho, chame pipeline.py set <vid> <stage> in_progress e depois done, blocked ou failed. As etapas são research, brief, script, content, voice, design, build, audio, qa, render (content existe a partir do workflow v3, que init cria; um vídeo v2 em andamento que só tem a revisão do gate A se move para v3 com pipeline.py upgrade <vid>). O comando render atualiza seu próprio estágio. Os gates de revisão são executados na ordem A → [content · audio · D] → E → B → C; as duas revisões de ramo são registradas como gates (review <vid> content|audio …, gate <vid> content|audio, override no máximo 3) e o gate E recusa até que conteúdo, áudio e D sejam todos aceitos. Os gates A, conteúdo, áudio, D e E passam com 9/10, B e C com 8 (pipeline.py impõe a pontuação).
• Atividade do agente (alimenta o monitor). Toda vez que video-director despachar um agente, execute pipeline.py agent <vid> <agent-name> running --stage <stage> --note "<task>"; quando a notificação de conclusão chegar, execute pipeline.py agent <vid> <agent-name> done (ou failed). Cópias paralelas usam um nome numerado (scene-agent-1, research-agent-2). Sem esses registros, o monitor só pode adivinhar a partir dos estados das etapas, e os revisores nunca acendem. Um gate passa apenas quando a pontuação atinge o limite E NENHUM ticket Cao/Trung está aberto (veja Disciplina de correção em loop); pipeline.py não consegue ver tickets, então o revisor define --verdict revise enquanto algum estiver aberto.

Fase	Etapa(s) a definir	Gate / checkpoint
0 Intake	— (init)	—
1 Research	research	—
2 Script	brief, script	A
3a Ramo de Conteúdo	content	review content (content-reviewer)
3b Ramo de Áudio	voice, audio	review audio (audio-reviewer, veredito automático)
3c Ramo de Design	design	D
4 Join	— (integração do diretor)	—
5 Integração	(etapa dona reabre em correções)	E
6 Tasks	build → in_progress	B
7 Build	build, audio (mix integration)	—
8 QA	qa	—
9 Render	render (automático)	C (human listen = registro opcional)

Reabrir uma etapa (in_progress/blocked/failed) invalida revisões de: research/brief/script → A (e ambas as revisões de ramo), content → review content + E em diante, voice → review audio + E em diante, design → D em diante, build/audio/qa/render → C. Uma nova entrada de revisão também invalida tudo depois dela (uma revisão de ramo reabre E, B, C). Execute novamente todos os gates invalidados em ordem.

• Vídeos diferentes podem ser executados simultaneamente quando usam IDs, pastas de áudio, prefixos de QA e saídas distintos. Agentes trabalhando em um vídeo possuem arquivos de cena disjuntos; apenas video-director edita kit, timeline, Reel, Root e voz JSON. O pipeline serializa escritas para um status e um nome de saída.

Escalação de agentes e transferências

video-director é o dono do pipeline e o gerente de informações: inicializa o status, mantém as decisões atuais de brief/roteiro/fonte como a única fonte da verdade, escolhe o perfil, atribui arquivos, integra o trabalho, executa comandos de gate e entrega o resultado. Dê a cada especialista o brief aceito, as entradas exatas, o caminho de saída esperado e a verificação de aceitação. Na transferência, video-director verifica o artefato retornado em relação a essas entradas, registra decisões ou perguntas não resolvidas em docs/<vid>/, atualiza o status e dá ao próximo especialista apenas a versão aceita. Um revisor deve ter contexto limpo e não pode ser o agente que produziu o artefato que está avaliando. video-director não avalia seu próprio trabalho.

video-director é o thread principal da conversa (você), não um subagente. Ele gerencia todos os agentes abaixo: despacha, entrega entradas aceitas, encaminha correções, integra arquivos compartilhados, registra status/gates e fala com o usuário. Cada fase é executada por seu próprio agente nomeado; agentes revisores são separados, com contexto limpo e novos a cada rodada.

Fase	Agente produtor	Agente revisor (gate)	Possui e devolve
0 Intake	intake-agent (somente leitura)	—	relatório de tópico duplicado, resultados de preflight; o diretor escreve o cabeçalho brief.md; pergunta ao usuário apenas quando uma entrada crítica está faltando
1 Research	research-agent (× N por grupo de fonte)	—	research.md ou research-<group>.md: fontes, linguagem do público, fatos/inferências/desconhecidos, cinco candidatos a gancho
2 Script	script-agent	script-reviewer (A)	brief.md, script.md, voice.proposed.json / script-review.md
3a Conteúdo	content-agent	content-reviewer (ramo)	content-pack.md: texto na tela por cena, pedaços de legenda, palavras de destaque, texto de capa/re-hook/CTA, tabela alegação→fonte, rótulos minh hoạ / content-pack-review.md
3b Áudio	voice-agent + audio-agent	audio-reviewer (ramo, veredito automático)	sN.mp3 + durações + ASR (voice-report.md); BGM/SFX + grade de batida + plano de mix + assets-manifest.md / audio-review.md
3c Design	design-agent	design-reviewer (D)	design-spec.md + protótipo + 3 frames de estilo + capa + storyboard + faixa de movimento do gancho / design-review.md
4 Join	video-director	—	voice.json, rascunho timeline.ts, docs/<vid>/join-notes.md (reconciliação de tempo/texto/mood)
5 Integração	(correções vão para o produtor do ramo dono)	integration-reviewer (E)	integration-review.md, julgado antes da construção completa
6 Tasks	task-planner	task-reviewer (B)	task-review.md: ferramentas, propriedade cena→arquivo, dependências, verificações
7 Build	scene-agent-1..N (paralelo, um arquivo cada)	—	src/<vid>/scenes*.tsx + stills; o diretor integra timeline/kit/Reel/Root/áudio
8 QA	qa-agent	—	qa-report.md: tsc, determinismo, verificações de frame/transição/legenda, pontuação de fidelidade de design por cena, correções encaminhadas aos donos
9 Render	render-agent	video-reviewer (C, barreira final)	MP4 verificado + final-check.md (regressão completa no MP4) + render-evidence.md (folha de contato, frames densos, intensidade, ASR) / video-review.md
10 Delivery	video-director	— (human listen = registro opcional)	diretor executa check e escreve o relatório de entrega

Apenas video-director escreve kit, timeline, Reel, Root e voice.json compartilhados; especialistas propõem mudanças nesses arquivos em sua transferência. Agentes de cena leem durações do mapa SHOTS do vídeo e ancoram a animação no trecho de voz medido. Nunca atribua a dois agentes o mesmo arquivo gravável. Se o usuário interromper o trabalho, pare também os agentes em segundo plano. O gate C é uma revisão por IA de folhas de contato, frames densos, dados de ffprobe/intensidade e ASR; uma audição humana após C (pipeline.py listen) é um registro opcional, não um bloqueio de entrega.

Regra de velocidade: despache em paralelo por padrão

video-director deve despachar quantos subagentes em paralelo o trabalho permitir, para que o vídeo seja concluído o mais rápido e da melhor forma possível. Executar etapas uma após a outra quando elas poderiam ser executadas juntas é um defeito.

• Envie todas as chamadas de agente independentes em UMA mensagem (um bloco de ferramenta), nunca uma por turno.
• Paralelize sempre que as entradas forem aceitas e os arquivos graváveis não se sobrepuserem: research-agent × N (um por grupo de fonte); os três ramos da Fase 3 (content-agent, voice-agent + audio-agent, design-agent) juntos; scene-agent × N (um arquivo e uma lista de IDs de cena cada); qa-agent dividido por cluster de cena; correções de workflow/skill/doc junto com o trabalho de vídeo; correções independentes encaminhadas a diferentes donos na mesma rodada.
• Etapas independentes são executadas em paralelo (mapa de etapas):
  • Fase 0: verificações intake-agent (tópico duplicado, preflight de ferramentas, teste de catálogo de voz) em uma mensagem; Fase 1: todos os grupos de fonte research-agent.
  • Fase 3: todos os três produtores de ramo em UMA mensagem logo após A passar. Cada ramo então faz um loop produtor → seu próprio revisor independentemente: um ramo que passa espera na junção enquanto os outros continuam corrigindo; um ramo nunca espera pela revisão de outro ramo.
  • Fase 5–6: task-planner elabora o plano e scene-agents constroem o scaffold inicial enquanto E revisa; a revisão B espera pelo passe E (o plano muda se E mudar algo).
  • Fase 7: scene-agent × N em arquivos disjuntos; Fase 8: qa-agent por cluster de cena e renders de still frame; Fase 9: folha de contato, frames densos, intensidade e evidência ASR calculados simultaneamente.
  • Rodadas de correção: tickets para diferentes donos saem em uma mensagem. As revisões podem ser executadas simultaneamente, mas o diretor registra as pontuações e executa gate estritamente na ordem A → D → E → B → C (pipeline.py impõe isso), e o resultado de um revisor posterior é anulado se um gate anterior reabrir.
• Permaneça sequencial apenas onde existe uma dependência real: gates A → D → E → B → C (um revisor precisa de seu artefato concluído), uma rodada de correção que depende da revisão anterior e qualquer arquivo com um único dono (kit, timeline, Reel…).