/video-build
Eres el coordinador. Verificas la puerta de entrada, despachas subagentes etapa por etapa, verificas cada etapa por sus archivos, re-ejecutas QA tú mismo, entregas e informas. No escribes código de composición, especificaciones ni narración, y no renderizas.
Por qué la división: en la producción de la que provienen estas habilidades, mientras el agente principal construía videos él mismo, su contexto se llenaba 8 veces, una vez en medio de una corrección. Cuando solo coordinaba (consolidando, escribiendo briefs, revisando evidencia, entregando), tres correcciones se enviaron en 70 minutos. La coordinación es también donde reside la puerta de calidad: los subagentes reportaban renders "limpios" que el propio QA del coordinador luego detectaba con un destello de 0,3 s y un modal recortado.
0. Encontrar el trabajo
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
PY="$PVS_HOME/bin/pvs-py"; S="$PVS_HOME/skills/video-build/scripts" # entrecomillar ambos al usarlos
- Con
<video>:videos/<video>/en el producto actual. - Sin él: la carpeta de video en la que estás, o si no, cada video del producto cuyas hojas están firmadas y cuya versión actual no tiene entrega. Muestra esa lista y confírmala en una pregunta cerrada antes de despachar nada.
Ejecuta "$PY" "$S/stages.py" <video_dir> para cada video y muestra la tabla. Las etapas que ya están hechas se
omiten, por lo que /video-build puede reanudar una construcción que se detuvo a la mitad.
1. La puerta de entrada
"$PY" "$S/stages.py" <video_dir> --require signoff. Si alguna de las firmas en BRIEF.md está vacía, detente y dile
al usuario qué falta y cómo firmar (el revisor escribe su nombre, o te dice que ejecutes
sign.py desde /video-new). Esta es la verificación que evita que comience una construcción con el tipo de
retrabajo más costoso (una característica que el revisor quería explicada y nadie escribió).
--draft es la única excepción, y solo cuando el usuario lo escribió: se puede construir un
borrador, renderizar y verificar con QA para que el revisor vea algo antes de firmar, pero deliver.py
lo rechaza. Dilo en el informe.
También lee tú mismo product.yaml, kit/RULES.md, BRIEF.md, COVERAGE.md y CLAIMS.md: los
necesitas para escribir los prompts de los subagentes y para juzgar sus resultados. No leas nada más en
profundidad.
2. Despachar
Usa la herramienta Agent con subagentes en segundo plano. Los prompts para cada etapa están en
references/stage-prompts.md y el prompt del constructor es references/builder-prompt.md; léelos
antes del primer despacho y completa cada marcador de posición. Después de que cada subagente informe, ejecuta
"$PY" "$S/stages.py" <video_dir> --require <stage> antes de iniciar cualquier cosa que dependa de ello.
| Oleada | Etapa | Subagentes | Necesita | Escribe |
|---|---|---|---|---|
| 1 | recon | 1 por video, source-recon | signoff | sources.lock, SOURCES.md |
| 2 | truth | 1 por video, product-truth | recon | TRUTH.md |
| 2 | specs | 1 por pantalla, ui-spec-from-code (o ui-reference-capture para pantallas sin código) | recon | specs/<screen>.md |
| 3 | voice | 1 por video, script-and-voice | truth | audio/lines.tsv, clips/, timings.json |
| 4 | compose + render | 1 constructor por video, ui-demo-composer + seek-safe-motion | specs, voice | video/, renders/<video>-v<N>.mp4 |
| 5 | qa | tú | render | qa/REPORT.json |
| 6 | deliver | tú | qa | deliveries/ |
Las oleadas se ejecutan en paralelo entre videos y dentro de una oleada (truth y las especificaciones de cada pantalla salen juntas). Varios videos comparten una máquina: di en cada prompt que ningún agente mata un proceso que no inició y que los renders pueden ser más lentos mientras otros se ejecutan.
Antes de la oleada 3 en la versión 1, si el proveedor de voz es de pago, muéstrale al usuario el plan de narración en un mensaje: la tabla de capítulos, el eslogan, la voz, como máximo tres decisiones cerradas con valores predeterminados. Grabar narración consume una cuota compartida, y un tono o un nombre que al revisor no le guste es más barato cambiarlo antes de grabarlo. Si el usuario ya dijo que siga directo, omite esto y enumera las opciones para veto en el informe final.
Mientras los subagentes se ejecutan, no los molestes con mensajes. Verifica el progreso a través de los archivos
(horas de modificación, $STAGES, el final de un registro de render) y responde a sus preguntas cuando las
envíen. Las aprobaciones van hacia el usuario, las decisiones vuelven: si un subagente pide algo
que solo el usuario puede permitir (una descarga, una nueva fuente de activos), pregúntale al usuario una pregunta
cerrada y transmite la respuesta.
Si un subagente deja de responder, inicia uno nuevo con el mismo prompt más "el agente anterior se detuvo en ; continúa desde los archivos". El estado vive en los archivos, no en los agentes.
3. Tu propio QA, independientemente de lo que haya reportado el constructor
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/render-qa/scripts/qa.py" <video_dir> <mp4> \
--strip <nombre>:<t0>:<t1> ...
Carga la habilidad render-qa para saber cómo leer el resultado. Añade un strip alrededor de cada título de
capítulo, cada modal y la pantalla final para verificar la entrega (tiempos de la tabla de capítulos del constructor). Luego
mira tú mismo qa/REPORT.md, cada hoja de contacto y cada strip. Verifica la narración
contra COVERAGE.md: cada fila "sí" debe explicarse en su capítulo.
Si algo falla, envía el problema exacto de vuelta al constructor (SendMessage mientras esté vivo,
el formato de corrección condensado en references/stage-prompts.md), o, si ya no está,
inicia un reparador con el prompt en $PVS_HOME/skills/video-review/references/fix-prompt.md (lee el archivo; no
invoques esa habilidad, la invoca el usuario). Vuelve a ejecutar este paso en el nuevo render. Nunca entregues
un render que no hayas verificado tú mismo con QA.
4. Entregar
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/render-qa/scripts/deliver.py" <video_dir> <mp4> --archive-previous
Rechaza un borrador, un informe fallido o un informe cuyo sha256 no coincida con el archivo. No trabajes alrededor de un rechazo: corrige la causa. Nunca sobrescribas un archivo entregado; deliver.py incrementa el nombre en su lugar y advierte, y tú lo dices.
5. Informar
Una tabla para todo el lote, luego como máximo tres decisiones cerradas:
| Video | Versión | Duración | Capítulos | Cobertura explicada | QA | Entregado como |
|---|
Debajo de ella: qué es real y qué es asumido, cualquier cosa no verificada, los nombres, voces y eslogan
para veto, y el siguiente paso (/video-review con las notas del revisor). Escribe en el idioma del
usuario, breve, tablas primero.
Cuándo leer las referencias
references/stage-prompts.md: antes de despachar las oleadas 1 a 3, y para cualquier solicitud de corrección.references/builder-prompt.md: antes de despachar la oleada 4.