AlexandrAI AGENTS.md
agents-md

make-video2 Video Agent Team Agent Guide

Project-specific AGENTS.md guidance for the make-video2 multi-agent video production pipeline, scene fan-out, Remotion template, TTS, validation, and render contracts.

AGENTS.md

Guidance for coding agents working on make-video2, the video-agent team pipeline under .claude/.

Project Overview

make-video2 is a broadcast-style, multi-agent video production workflow. It separates research, editorial writing, scene planning, TTS/timing, and Remotion rendering. The pipeline is intentionally visual-first: narration carries explanation while visual beats drive the screen state.

Key paths:

  • .claude/skills/make-video2/skill.md: main skill contract and pipeline rules.
  • .claude/skills/make-video2/references/orchestrate.md: end-to-end execution procedure.
  • .claude/skills/make-video2/references/storyboard-rules.md: Visual PD rules.
  • .claude/skills/make-video2/references/design-system.md: visual system rules.
  • .claude/agents/make-video2-*.md: supervisor, research, editorial, scene pipeline, and video agents.
  • .claude/scripts/*.mjs: job setup, script composition, scene split/merge, TTS, timing, validation, QA, and rendering.
  • .claude/template/remotion-project/: Remotion rendering template.

Setup Commands

bashcd <project-root>
node .claude/scripts/create-job-dir.mjs
node .claude/scripts/init-project-brief.mjs
node .claude/scripts/split-scenes.mjs
node .claude/scripts/merge-scene-results.mjs
node .claude/scripts/validate-script.mjs
node .claude/scripts/validate-fonts.mjs
node .claude/scripts/render-qa.mjs
node .claude/scripts/run-video-build.mjs
node --test .claude/scripts/*.test.mjs

Run only the commands for the pipeline stage you are changing. Do not fabricate outputs for missing upstream stages.

Pipeline Rules

  • Supervisor pass 1 handles input, research, editorial script, and scene splitting.
  • Top-level orchestration fans out scene-pipeline work by scene.
  • Supervisor pass 2 merges results, composes final artifacts, validates, and renders.
  • visual_beats are the source of truth for screen state.
  • Every scene must have captions.
  • Use graphs, icons, comparisons, flows, nodes, and progress UI over text-heavy slides.
  • Keep screen text minimal; narration and subtitles carry detail.
  • A scene should not be static when multiple visual beats can communicate progression.

Remotion Rules

  • All animation should be frame-based with useCurrentFrame().
  • Do not use CSS transitions, CSS animations, or Tailwind animation classes.
  • Use the shared template transition system for cuts.
  • Use lucide-react for icons and Remotion shape primitives where available.
  • Missing asset keys should degrade to fallback cards rather than crashing render.
  • CJK languages require bundled font support plus validation.

Testing

  • Run focused script tests after changing any *-core.mjs helper.
  • Run validation scripts before rendering.
  • Run render QA before calling a video complete.
  • When modifying motif behavior, add or update motif, layout, or render-contract tests.

Security And Privacy

  • Do not commit or publish generated job outputs that contain user-private briefs, audio, transcripts, or rendered videos unless explicitly intended.
  • Keep TTS binaries, voices, API keys, and timeout overrides in runtime configuration.
  • Do not encode local absolute paths in generated manifests or public docs.