Director Mode, Preflight & the Approval Gate

Director mode turns videoclaw into a careful film studio: before it spends a single credit on a real provider, it scans your storyboard for hazards, refuses to run on a stale plan, and waits for a human (or agent) to explicitly approve the shot list. Nothing reaches Veo, Seedance, or Runway by accident.

What it does

• Adds a hard approval gate. With --mode director (a.k.a. --production-mode director), execute/produce will block before any provider submission and write a human-readable storyboard.md for review. Real generation only proceeds once approval is set.
• Runs a preflight hazard scan over the storyboard, catching the things that quietly waste credits:
  • Content-filter hazards — wording like "spectral blade", "katana clash", combat verbs ("stab/slash/strike"), "taser", or "fires a gun" that providers reject. These are reported as errors and can be auto-rewritten to safe phrasing (e.g. "radiant staff of light").
  • Pronoun drift — a scene calls a character "she" then "he"; flagged so identity stays consistent.
  • Near-duplicate scenes — adjacent scenes that overlap >= 75% of their words and won't look visually distinct.
  • Prompt-quality and dialogue-vs-duration fit — words that won't fit the clip length.
  • Broken character references — unreachable reference image URLs, missing Go Bananas character ids, characters with no reference image, and reference-sheet role collisions.
• Refuses to run on a stale plan. If you edit the storyboard after it was approved, the review goes stale and execution is blocked until you refresh it — even if approval is still set.
• Stays plan-safe. Preflight and storyboard-review spend no credits and call no providers. They are pure checks plus on-disk artifact writes.

How to use it

Examples use the source-checkout form node dist/cli/vclaw.js video .... If you installed the CLI, just type vclaw video ... instead.

node dist/cli/vclaw.js video director-preflight --project demo

Runs the hazard scan and prints a JSON result with pass, errors, and warnings. Fix every error before you can execute.

node dist/cli/vclaw.js video director-preflight --project demo --apply-content-fixes

Same scan, but first auto-rewrites known content-filter wording in the storyboard (and regenerates the story bible), then re-checks.

node dist/cli/vclaw.js video storyboard-review --project demo --mode director

Runs preflight, writes storyboard.md for human review, and moves the project into awaiting-approval — without starting a run. Add --apply-content-fixes to clean wording first.

node dist/cli/vclaw.js video execute --project demo --mode director

Tries to produce, but blocks at the approval gate: it writes storyboard.md and exits with a "Storyboard approval required" report. Nothing is submitted.

VIDEOCLAW_APPROVE_STORYBOARD=1 node dist/cli/vclaw.js video execute --project demo --mode director

The approved run. Preflight must pass and the review must be fresh; only then does the asset stage proceed to the provider.

node dist/cli/vclaw.js video approve --project demo --mode director

Runs execute for you with VIDEOCLAW_APPROVE_STORYBOARD=1 already set — the approved run itself (add --dry-run to validate without spending). A convenience so you don't have to export the env var by hand. (The "prints the exact next command" behavior belongs to the blocked-gate report's blockers[] / next-action, not to approve.)

How it flows

Diagram source (live Mermaid)

Artifacts & outputs

• projects/<slug>/storyboard.md — the human-readable review file the gate writes before blocking. Lists scenes plus any preflight errors and suggestions.
• projects/<slug>/artifacts/execution-report.json — the blocked (or proceeding) run report; status is blocked with blockers[] until the gate is satisfied.
• projects/<slug>/artifacts/storyboard.json — rewritten in place when --apply-content-fixes / DIRECTOR_AUTO_FIX_CONTENT=1 substitutes hazard wording.
• projects/<slug>/artifacts/story-bible.json — regenerated after content auto-fixes so continuity stays consistent.
• projects/<slug>/events/events.jsonl — appends director.preflight.blocked, storyboard.review.stale.blocked, storyboard.approval.required, or director.storyboard.auto-fixed so the timeline records exactly why a run stopped.

Tips & gotchas

Use the two-step in CI/agents

Run director-preflight (or storyboard-review) first to get a clean pass, then run execute with approval. Splitting the check from the spend keeps failures cheap.

Stale review blocks even when approved

Editing the storyboard after approval flips its review-state to stale. The runtime checks freshness before honoring VIDEOCLAW_APPROVE_STORYBOARD, so a stale plan is blocked regardless. Refresh the review (re-run storyboard-review) after any storyboard edit.

Escape-hatch env vars — know what they do

• DIRECTOR_AUTO_FIX_CONTENT=1 — auto-applies content-filter rewrites at execute time (same as --apply-content-fixes).
• SKIP_DIRECTOR_PREFLIGHT=1 — skips the hazard scan entirely. The run records a director.preflight.skipped event; use only when you have already verified the storyboard.
• DIRECTOR_STRICT_PROMPT_QUALITY=1 and DIRECTOR_STRICT_DIALOGUE_FIT=1 — promote those checks from warnings to hard errors, so weak prompts or over-long dialogue block the run.

Content hazards are about provider policy, not taste

The rewrites (weapon clashes, body-shatter, firearm verbs) exist because Veo/Seedance/Runway content filters reject them — fixing the wording is what lets the shot generate at all. See providers for route-specific filtering.

Driving it from an agent

An AI agent (e.g. Claude Code) runs video director-preflight --project <slug> and parses the JSON: a non-empty errors[] (or pass: false) means stop and fix before spending credits. To proceed it sets VIDEOCLAW_APPROVE_STORYBOARD=1 on the execute call. The gate is fail-safe: every block path returns an execution-report.json with status: "blocked" and a blockers[] array naming the exact next command, so an agent can self-correct without a human in the loop — preflight errors, stale review, and missing approval each surface their own remediation string.

Related

• storyboard — the artifact preflight scans
• story bible — regenerated after content auto-fixes
• projects lifecycle — where the review-state ladder lives
• Deep reference: Production Workflow