nanxnguyen/remotion-ai-agentic-studio

Flujo de trabajo de producción de video

Este es el único flujo de trabajo de producción para nuevos videos en este repositorio. video-director es dueño del resultado final y del estado. Usa .claude/skills/viral-tech-video-creator/SKILL.md para técnicas de investigación y redacción, y .claude/skills/video-shotcraft/SKILL.md para referencias de planos, movimiento y sonido. Cuando esos recursos no coincidan con este archivo, sigue este archivo. Lee CLAUDE.md y las referencias seleccionadas antes de trabajar. Responde en vietnamita; escribe el código en inglés.

El flujo de trabajo es totalmente automático: los agentes producen, revisan y aprueban a través de las puertas por sí mismos, y ningún paso espera la aprobación manual del usuario. Nunca termines un turno o un informe de agente con "gửi bạn nghe thử / duyệt giúp / OK chưa"; elige la mejor opción, registra la decisión en docs/<vid>/, y continúa. Pregunta al usuario solo cuando falte una entrada crítica y no se pueda inferir de forma segura, o cuando el usuario haya solicitado explícitamente una puerta de decisión. Las escuchas humanas (audio, MP4 final) son registros opcionales, nunca preguntas o bloqueadores. Los revisores independientes usan contexto limpio. Mantén textualmente solo las líneas del usuario que el usuario marcó como obligatorias; todo lo demás puede ser dramatizado o reescrito para servir a la historia (consulta la lección de la puerta A en Puntos de fallo comunes). La publicación requiere una solicitud separada del usuario.

Modo ligero. Para un video story corto, o cuando el usuario proporcionó el guión/voz, el director puede fusionar pasos sin eliminar ninguna puerta: un research-agent, sin archivo de investigación cuando la cuenta del usuario es la fuente, las tres ramas de la Fase 3 en un mensaje paralelo, y task-planner con un scene-agent por cada 3-4 tomas. Las puertas A, D, E, B, C, las revisiones de las ramas de contenido y audio, la disciplina del bucle de corrección y la propiedad de los archivos siempre se mantienen.

Mapa del pipeline

Después de la puerta A, el trabajo se bifurca en tres ramas paralelas (contenido, audio, diseño), cada una con su propio bucle de productor → revisor de contexto limpio. Cuando las tres pasan, video-director las une y la puerta E revisa el plan combinado antes de la construcción.

flowchart TD
  P0["0 Ingreso<br/>intake-agent ×2-3"] --> P1["1 Investigación<br/>research-agent ×N"]
  P1 --> P2["2 Guión<br/>script-agent"]
  P2 --> A{"Puerta A ≥ 9<br/>script-reviewer"}
  A -- "revisar (≤3 rondas)" --> P2
  A -- pasar --> FORK(("bifurcación"))

  subgraph BR["3 · Tres ramas paralelas"]
    direction LR
    subgraph B1["3a Contenido"]
      CA["content-agent<br/>content-pack.md"] --> CR{"content-reviewer ≥ 9"}
      CR -- revisar --> CA
    end
    subgraph B2["3b Audio"]
      VA["voice-agent + audio-agent<br/>sN.mp3, BGM/SFX, mix plan"] --> AR{"audio-reviewer ≥ 9"}
      AR -- revisar --> VA
    end
    subgraph B3["3c Diseño"]
      DA["design-agent<br/>proto, style frames, cover, board"] --> DR{"Puerta D ≥ 9<br/>design-reviewer"}
      DR -- revisar --> DA
    end
  end

  FORK --> CA
  FORK --> VA
  FORK --> DA
  CR -- pasar --> J
  AR -- pasar --> J
  DR -- pasar --> J
  J["4 Unión<br/>video-director: voice.json, timeline.ts,<br/>reconciliar timing / texto / mood"] --> E{"Puerta E ≥ 9<br/>integration-reviewer"}
  E -- "ticket → rama propietaria" --> BR
  E -- pasar --> P6["6 Tareas<br/>task-planner"]
  J -.->|scaffold temprano| P7
  P6 --> B{"Puerta B ≥ 8<br/>task-reviewer"}
  B -- pasar --> P7["7 Construcción<br/>scene-agent ×N"]
  P7 --> P8["8 QA<br/>qa-agent ×N"]
  P8 --> P9["9 Renderizado<br/>render-agent"]
  P9 --> C{"Puerta C ≥ 8 · BARRERA FINAL<br/>re-test completo en el MP4<br/>final-check.md todo ✓ + video-reviewer ×3"}
  C -- "corregir → propietario, re-renderizar, re-probar todo" --> P7
  C -- pasar --> P10["10 Entrega<br/>video-director"]

Respaldo de texto: 0 Ingreso → 1 Investigación → 2 Guión ⇒ A → bifurcación[ 3a content-agent ⇒ content-reviewer | 3b voice+audio ⇒ audio-reviewer | 3c design-agent ⇒ D ] → 4 Unión → E → 6 Tareas ⇒ B → 7 Construcción → 8 QA → 9 Renderizado ⇒ C → 10 Entrega.

Contrato y nomenclatura

• Un video tiene un ID de tema único en kebab-case minúscula <vid>, un slug de voz <voice>, docs/<vid>/, src/<vid>/, public/audio/<vid>/, y out/qa/<vid>-*.png.
• El único video final es out/<vid>-<voice>-reel.mp4, por ejemplo out/cam-on-phien-ban-minh-anh-khoi-reel.mp4. El slug de voz describe la voz realmente escuchada. Cuando la voz cambia, ejecuta python3 -I scripts/pipeline.py voice <vid> <new-voice> antes de renderizar; el archivo anterior permanece disponible.
• Comienza con python3 -m unittest scripts.test_voice_catalog para asegurar que las vistas previas del catálogo se resuelvan. Elige un candidato de vietnamese-voice-samples/previews/ (la carpeta es el catálogo; los nombres de archivo son nombres de voz abreviados) según la descripción del catálogo y la solicitud del usuario, y registra el proveedor y su ID de voz en brief.md. Una vista previa no otorga derechos comerciales o de clonación por sí misma.
• Después de que la verificación de tema duplicado de la Fase 0 se complete, inicializa una vez: python3 -I scripts/pipeline.py init <vid> --comp <CompId> --voice <voice> --profile story|product|knowledge|news. --voice es obligatorio para nueva producción: pasa la mejor estimación actual, luego ejecuta pipeline.py voice <vid> <slug> tan pronto como se decida la ruta (el slug debe nombrar la voz realmente escuchada); --out es solo para nombres de salida heredados. Inicia o reutiliza el Monitor de Pipeline en el puerto 4180 antes de despachar agentes de producción. No edites status.json manualmente.
• Alrededor de cada etapa de trabajo, llama a pipeline.py set <vid> <stage> in_progress y luego done, blocked, o failed. Las etapas son research, brief, script, content, voice, design, build, audio, qa, render (content existe desde el flujo de trabajo v3, que init crea; un video v2 en curso que solo tiene la puerta A revisada se mueve a v3 con pipeline.py upgrade <vid>). El comando render actualiza su propia etapa. Las puertas de revisión se ejecutan en orden A → [content · audio · D] → E → B → C; las dos revisiones de rama se registran como puertas (review <vid> content|audio …, gate <vid> content|audio, override en cap 3) y la puerta E se niega hasta que content, audio y D estén todas aceptadas. Las puertas A, content, audio, D y E pasan con 9/10, B y C con 8 (pipeline.py aplica la puntuación).
• Actividad del agente (impulsa el monitor). Cada vez que video-director despacha un agente, ejecuta pipeline.py agent <vid> <agent-name> running --stage <stage> --note "<task>"; cuando llegue su notificación de finalización, ejecuta pipeline.py agent <vid> <agent-name> done (o failed). Las copias paralelas usan un nombre numerado (scene-agent-1, research-agent-2). Sin estos registros, el monitor solo puede adivinar a partir de los estados de la etapa, y los revisores nunca se iluminan. Una puerta pasa solo cuando la puntuación alcanza el umbral Y no hay ningún ticket Cao/Trung abierto (consulta Disciplina del bucle de corrección); pipeline.py no puede ver los tickets, por lo que el revisor establece --verdict revise mientras alguno esté abierto.

Fase	Etapa(s) a establecer	Puerta / punto de control
0 Ingreso	— (init)	—
1 Investigación	research	—
2 Guión	brief, script	A
3a Rama de contenido	content	review content (content-reviewer)
3b Rama de audio	voice, audio	review audio (audio-reviewer, veredicto automático)
3c Rama de diseño	design	D
4 Unión	— (integración del director)	—
5 Integración	(la etapa propietaria se reabre con las correcciones)	E
6 Tareas	build → in_progress	B
7 Construcción	build, audio (integración de mezcla)	—
8 QA	qa	—
9 Renderizado	render (automático)	C (escucha humana = registro opcional)

Reabrir una etapa (in_progress/blocked/failed) invalida las revisiones de: research/brief/script → A (y ambas revisiones de rama), content → review content + E en adelante, voice → review audio + E en adelante, design → D en adelante, build/audio/qa/render → C. Una nueva entrada de revisión también invalida todo lo que le sigue (una revisión de rama reabre E, B, C). Vuelve a ejecutar cada puerta invalidada en orden.

• Diferentes videos pueden ejecutarse simultáneamente cuando usan IDs distintos, carpetas de audio, prefijos de QA y salidas. Los agentes que trabajan en un video poseen archivos de escena disjuntos; solo video-director edita kit, timeline, Reel, Root y el JSON de voz. El pipeline serializa las escrituras a un estado y un nombre de salida.

Roster de agentes y traspasos

video-director es el propietario del pipeline y el gestor de información: inicializa el estado, mantiene las decisiones actuales de brief/guion/fuente como la única fuente de verdad, elige el perfil, asigna archivos, integra el trabajo, ejecuta comandos de puerta y entrega el resultado. Dale a cada especialista el brief aceptado, las entradas exactas, la ruta de salida esperada y la verificación de aceptación. En el traspaso, video-director verifica el artefacto devuelto contra esas entradas, registra las decisiones o preguntas no resueltas en docs/<vid>/, actualiza el estado y le da al siguiente especialista solo la versión aceptada. Un revisor debe tener contexto limpio y no debe ser el agente que produjo el artefacto que califica. video-director no califica su propio trabajo.

video-director es el hilo de conversación principal (tú), no un subagente. Gestiona cada agente a continuación: despacha, entrega las entradas aceptadas, enruta las correcciones, integra los archivos compartidos, registra el estado/las puertas y habla con el usuario. Cada fase es ejecutada por su propio agente nombrado; los agentes revisores son separados, con contexto limpio y nuevos en cada ronda.

Fase	Agente productor	Agente revisor (puerta)	Posee y devuelve
0 Ingreso	intake-agent (solo lectura)	—	informe de tema duplicado, resultados de verificación previa; el director escribe el encabezado de brief.md; pregunta al usuario solo cuando falta una entrada crítica
1 Investigación	research-agent (× N por grupo de fuente)	—	research.md o research-<group>.md: fuentes, lenguaje de la audiencia, hechos/inferencias/desconocidos, cinco candidatos de gancho
2 Guión	script-agent	script-reviewer (A)	brief.md, script.md, voice.proposed.json / script-review.md
3a Contenido	content-agent	content-reviewer (rama)	content-pack.md: texto en pantalla por toma, fragmentos de subtítulos, palabras destacadas, texto de portada/re-gancho/CTA, tabla claim→fuente, etiquetas minh hoạ / content-pack-review.md
3b Audio	voice-agent + audio-agent	audio-reviewer (rama, veredicto automático)	sN.mp3 + duraciones + ASR (voice-report.md); BGM/SFX + rejilla de ritmo + plan de mezcla + assets-manifest.md / audio-review.md
3c Diseño	design-agent	design-reviewer (D)	design-spec.md + prototipo + 3 fotogramas de estilo + portada + guión gráfico + tira de movimiento de gancho / design-review.md
4 Unión	video-director	—	voice.json, borrador de timeline.ts, docs/<vid>/join-notes.md (reconciliación de timing/texto/mood)
5 Integración	(las correcciones van al productor de la rama propietaria)	integration-reviewer (E)	integration-review.md, evaluado antes de la construcción completa
6 Tareas	task-planner	task-reviewer (B)	task-review.md: herramientas, propiedad toma→archivo, dependencias, verificaciones
7 Construcción	scene-agent-1..N (paralelo, un archivo cada uno)	—	src/<vid>/scenes*.tsx + fotogramas fijos; el director integra timeline/kit/Reel/Root/audio
8 QA	qa-agent	—	qa-report.md: tsc, determinismo, verificaciones de fotograma/transición/subtítulo, puntuación de fidelidad de diseño por toma, correcciones enrutadas a los propietarios
9 Renderizado	render-agent	video-reviewer (C, barrera final)	MP4 verificado + final-check.md (regresión completa en el MP4) + render-evidence.md (hoja de contactos, fotogramas densos, sonoridad, ASR) / video-review.md
10 Entrega	video-director	— (escucha humana = registro opcional)	el director ejecuta check y escribe el informe de entrega

Solo video-director escribe kit, timeline, Reel, Root y voice.json compartidos; los especialistas proponen cambios a esos archivos en su traspaso. Los agentes de escena leen las duraciones del mapa SHOTS del video y anclan el movimiento al lapso de voz medido. Nunca asignes a dos agentes el mismo archivo escribible. Si el usuario detiene el trabajo, detén también los agentes en segundo plano. La puerta C es una revisión de IA de las hojas de contacto, fotogramas densos, datos de ffprobe/sonoridad y ASR; una escucha humana después de C (pipeline.py listen) es un registro opcional, no un bloqueador de entrega.

Regla de velocidad: despachar en paralelo por defecto

video-director debe despachar tantos subagentes en paralelo como el trabajo lo permita, para que el video se termine lo más rápido y mejor posible. Ejecutar pasos uno tras otro cuando podrían ejecutarse juntos es un defecto.

• Envía todas las llamadas de agente independientes en UN mensaje (un bloque de herramienta), nunca uno por turno.
• Paraleliza siempre que las entradas estén aceptadas y los archivos escribibles no se superpongan: research-agent × N (uno por grupo de fuente); las tres ramas de la Fase 3 (content-agent, voice-agent + audio-agent, design-agent) juntas; scene-agent × N (un archivo y una lista de IDs de toma cada uno); qa-agent dividido por clúster de toma; correcciones de flujo de trabajo/habilidad/doc junto con el trabajo de video; correcciones independientes enrutadas a diferentes propietarios en la misma ronda.
• Las etapas independientes se ejecutan en paralelo (mapa de etapas):
  • Fase 0: verificaciones de intake-agent (tema duplicado, verificación previa de herramientas, prueba de catálogo de voces) en un mensaje; Fase 1: todos los grupos de fuente de research-agent.
  • Fase 3: los tres productores de rama en UN mensaje justo después de que A pase. Cada rama luego itera productor → su propio revisor de forma independiente: una rama que pasa espera en la unión mientras las otras siguen corrigiendo; una rama nunca espera la revisión de otra rama.
  • Fase 5–6: task-planner redacta el plan y los scene-agent construyen el scaffold temprano mientras E revisa; la revisión B espera el pase de E (el plan cambia si E cambia algo).
  • Fase 7: scene-agent × N en archivos disjuntos; Fase 8: qa-agent por clúster de toma y renderizados de fotograma fijo; Fase 9: hoja de contactos, fotogramas densos, evidencia de sonoridad y ASR calculados de forma concurrente.
  • Rondas de corrección: los tickets para diferentes propietarios se envían en un mensaje. Las revisiones pueden ejecutarse de forma concurrente, pero el director registra las puntuaciones y ejecuta gate estrictamente en orden A → D → E → B → C (pipeline.py lo aplica), y el resultado de un revisor posterior es nulo si una puerta anterior se reabre.
• Mantén la secuencia solo donde exista una dependencia real: puertas A → D → E → B → C (un revisor necesita su artefacto terminado), una ronda de corrección que depende de la revisión anterior, y cualquier archivo con un solo propietario (kit, timeline, Reel