Director Blueprint (AI Animation Director)

The Project Blueprint is VideoClaw's director layer — a project-level visual bible that locks the film language above the existing execution layer (cinematography.ts, filmmaking-prompts.ts). It is distinct from the Story Bible: the story bible tracks continuity (cast, settings, props, scene timeline); the blueprint tracks visual direction (color system, lighting grammar, per-character camera language, environment atmosphere, the project camera bible).

Design principle (from the source "AI Animation Director" system): the blueprint is "a director layer ABOVE your existing camera reference, not a replacement for it." It does not change how prompts are composed — it locks the decisions they express.

Generate it (the ai-director skill)

Authoring a blueprint is a creative task, so it lives in the ai-director skill (skills/ai-director/SKILL.md), which runs the staged director master-prompt (intake → 8 sections) and emits a project-blueprint.json. The CLI is the deterministic half: it validates, normalizes, and persists that JSON, then the prompt composer consumes it.

The eight locked sections:

1. Visual identity — aesthetic, influences (what's borrowed), texture, scale, time-of-day, one-line thesis.
2. Master color system — 4–6 named colors (where + emotional function), Kelvin range, warm/cool shift meaning, contrast, saturation, optional gradeId.
3. Lighting grammar — key direction, quality, shadow strategy, practicals, and three signature setups (intimate / tension / hero).
4. Character blueprint — per character: silhouette identity, signature detail, 3-color palette, costume, what the design communicates, a voice profile, and power / vulnerability / signature camera framing.
5. Environment blueprint — per location: emotional function, visual anchors, scale, light/color, and the 5 sensory words (1 smell + 1 texture + 1 sound + 2 feelings).
6. Project camera bible — camera relationship, when it moves vs. locks, 3 dominant shots, rare shots, primary angles/movements, forbidden movements, focal feel, depth strategy, and the one rule the camera must never break.
7. Performance rules — acting style, dialogue energy, silence usage, intensity scale, casting pattern, what to avoid.
8. Output notes — runtime, aspect ratio, motion style, editing rhythm, 8–12 vibe keywords.

CLI

# Validate + persist a skill-authored blueprint JSON (writes artifacts/project-blueprint.json):
vclaw video director-blueprint --project <slug> --from-json <path> --write

# Print the persisted blueprint:
vclaw video director-blueprint --project <slug> --show

director-blueprint only validates and stores — generation is the skill's job. Validation is lenient on sub-fields (missing strings → empty) but strict on the eight required sections, throwing a single invalid_flag_value error listing all missing sections. The artifact is managed + history-tracked (artifacts/project-blueprint.json, schema schemas/video/artifacts/project-blueprint.schema.json).

How it's consumed

vclaw video filmmaking-prompts auto-reads artifacts/project-blueprint.json (graceful — absent → byte-identical legacy output) and enriches every scene packet:

• A compact, prose-only addendum is appended after the canonical 13-block Seedance body (so the block-order contract is preserved) and uses no Kelvin/hue numerals (so the prompt-lint prose-register check passes):

  DIRECTOR — Palette: <master colors>. Look: <contrast/saturation + vibe keywords>.
  Lighting: <scene's signature setup>. Subject: <present character — silhouette,
  signature detail; signature framing>. Atmosphere: <5 sensory words>.
  Rule: <the one rule>.

• The scene's signature lighting setup is selected from its text (tension words → tension, reveal/hero words → hero, else intimate).

• The camera bible's forbidden movements are validated against each scene's prompt; a forbidden-camera-movement issue is raised per hit.

• When the bible forbids handheld, the storyboard-grid-reference packet also drops its default "Handheld camera moments may be used to boost realism" boilerplate — so the prompt never instructs a forbidden move (and the checker never flags its own boilerplate). No blueprint / handheld allowed → the clause stays, byte-identical to legacy.

The underlying camera/lighting vocabulary lives in src/video/shot-grammar.ts (shot-size emotional taxonomy, movement grammar with Seedance syntax, the sensory-words rule, the two-temperature technique helper in lighting-grade-register.ts, re-exported by cinematography.ts). See references/video/camera-bible.md and references/video/ai-director-blueprint.md.

Modules

File	Role
skills/ai-director/SKILL.md	The staged director master-prompt (generation)
src/video/project-blueprint.ts	Artifact type + validate/write/read
src/video/blueprint-prompt.ts	Render the DIRECTOR addendum + forbidden-move detection
src/video/shot-grammar.ts	Camera-bible shot/angle/movement taxonomy + sensory-words rule
src/video/filmmaking-prompts.ts	Consumes the blueprint into every scene packet
schemas/video/artifacts/project-blueprint.schema.json	Canonical artifact schema