video/skills/pipelines/animation/proposal-director.md

Proposal Director — Animation Pipeline

When to Use

You are the Proposal Director for a generated animation video. You sit between the Research Director and the Script Director. You receive a research_brief full of raw findings — both topic data and animation technique research — and transform it into a concrete, reviewable proposal that the user approves before any money is spent.

This is the approval gate. Nothing downstream runs until the user says "go."

Animation proposals have a unique dimension: animation mode selection. Unlike explainer videos where the visual approach is secondary to the narrative, animation videos ARE their visual approach. The mode choice (Manim vs Remotion vs AI video vs motion graphics) fundamentally shapes the entire production.

Runtime Selection (required field — render_runtime)

Animation proposals must lock both a renderer_family (creative grammar) and a render_runtime (technical engine). These are separate concepts now that HyperFrames is a first-class runtime. Read skills/meta/animation-runtime-selector.md and skills/core/hyperframes.md for the decision matrix, and AGENT_GUIDE.md → "Present Both Composition Runtimes (HARD RULE)" for the governance contract.

MANDATORY workflow — present both runtimes, don't silently default:

1. Query video_compose.get_info()["render_engines"]. If both remotion and hyperframes are True, proceed to step 2. If only one is available, go to step 4 with just that one.
2. Present both runtimes to the user with brief-specific analysis:
   • Remotion — one line on fit (e.g. "your brief uses data-chart and stat_card heavily, both already exist as React components"), one line on tradeoff (e.g. "React component authoring is more rigid than HTML/CSS for custom typographic motion").
   • HyperFrames — one line on fit (e.g. "the kinetic-typography opener fits HTML + GSAP better than Remotion interpolation"), one line on tradeoff (e.g. "no word-level caption burn parity yet; no access to existing Remotion chart library").
3. Recommend one with rationale tied to the brief's delivery_promise, the selected animation mode, and the reuse strategy from research.
4. Wait for explicit user approval. Do NOT write render_runtime into proposal_packet.production_plan before approval.
5. Log a render_runtime_selection decision in decision_log with BOTH runtimes in options_considered, the user's pick as selected, and the rationale as reason. If a runtime was unavailable, record it as rejected with rejected_because: "runtime not available on this machine".

Fit cheat-sheet for the recommendation (NOT an auto-decision):

Brief characteristic	Lean toward
Data-chart-heavy, text_card/stat_card/kpi_grid dominant	Remotion
MathAnimate / Manim scene in the animatic	Remotion (Manim renders to a video, composed in Remotion)
Kinetic typography, product promo, launch reel, HTML/GSAP-native motion	HyperFrames
Website-to-video or UI-driven composition	HyperFrames
Registry blocks needed (data-chart, grain-overlay, shader transitions)	HyperFrames
Word-level/karaoke caption burn required	Remotion (HyperFrames caption parity deferred)
Simple source-footage concat, no composition	ffmpeg

A render_runtime_selection decision with only one option considered when both were available is a CRITICAL reviewer finding. That's how the moat collapses into "everything looks like our chart stack."

Prerequisites

Layer	Resource	Purpose
Schema	schemas/artifacts/proposal_packet.schema.json	Artifact validation
Prior artifact	research_brief from Research Director	Raw findings + technique research
Pipeline manifest	pipeline_defs/animation.yaml	Stage and tool definitions
Tool registry	support_envelope() output	What's actually available right now
Cost tracker	tools/cost_tracker.py	Cost estimation data
Style playbooks	styles/*.yaml	Available visual styles
User input	Topic, any preferences expressed	Creative direction

Process

Step 0: Check for Reference Video Context

Before starting proposal work, check if a VideoAnalysisBrief exists for this project.

When a VideoAnalysisBrief is present — Reference-Aware Animation Concept Design:

HARD RULE: No carbon copies. Each concept option MUST:

1. Name at least ONE animation element it keeps from the reference (pacing, motion style, narrative structure)
2. Name at least ONE element it changes (animation mode, visual identity, topic angle)
3. Explain WHY the change makes the output more engaging or clearer

Animation differentiation patterns:

Pattern	Example
Same topic, different animation mode	Reference: stock footage → Ours: Manim mathematical visualization
Same style, different complexity	Reference: simple diagrams → Ours: progressive build with layers
Same pacing, different visual identity	Reference: corporate blue → Ours: vibrant neon-on-black
Same narrative, different interactivity	Reference: linear → Ours: data-driven with animated charts

Mandatory Sample Protocol: After concept approval, produce a 10-15 second sample to validate the animation style before full production.

When no VideoAnalysisBrief is present: Skip this step and proceed normally.

Step 1: Absorb the Research (or Direct Brief)

If a research_brief artifact exists: Read it thoroughly. Extract:

If no research_brief exists (direct user brief): The user has given you a creative brief directly. This is common for short videos (30-60s) where formal research is overkill. Use the user's brief as your input and proceed to Step 2. Note the missing research as a limitation — you won't have data_points, technique references, or audience_insights to draw from, so concept design relies on your knowledge and the user's direction.

When a research_brief IS available, extract:

• research_summary — read first. Contains both the key insight and the most promising animation approach.
• angles_discovered — raw concept candidates, each with an animation_fit field.
• data_points — especially those with high visual_potential ratings.
• Animation technique references — from the animation-specific research step. These directly inform mode selection.
• audience_insights.misconceptions — animation excels at showing "wrong way → right way" transitions.
• Mathematical/technical accuracy notes — critical constraints on what we can and cannot simplify.

Step 2: Run Preflight

Before designing concepts, know what tools are available:

python -c "from tools.tool_registry import registry; import json; registry.discover(); print(json.dumps(registry.support_envelope(), indent=2))"

Also check the capability catalog:

python -c "from tools.tool_registry import registry; import json; registry.discover(); print(json.dumps(registry.capability_catalog(), indent=2))"

Animation-specific preflight checks:

Capability	What to Check	Impact if Missing
math_animate	Is ManimCE installed and working?	Cannot do programmatic math animation — fall back to diagram_gen + image_selector
diagram_gen	Is Mermaid rendering available?	Cannot do diagram-led animation — fall back to image_selector
video_selector	Which video gen providers are available?	Limits AI video clip options
image_selector	Which image gen providers are available?	Limits still frame options
tts_selector	Which TTS providers are available?	Affects narration quality
video_compose	Is FFmpeg/Remotion available?	Critical — cannot render without this

Record all findings. Do not propose an animation mode that requires tools you don't have.

Step 3: Animation Approach Selection

This is the key differentiator from the explainer proposal. Present the user with concrete animation approaches, explain what each looks like, what tools/keys they need, and what's already available.

Step 3a: Tool Availability Scan

Before designing concepts, scan what's available and present it honestly. Do NOT hardcode provider names, costs, or key names in this output — they drift. Read them live from the registry:

from tools.tool_registry import registry
registry.discover()
summary = registry.provider_menu_summary()  # see AGENT_GUIDE.md > Mandatory Preflight

Then render the scan from summary, grouping by capability. Example shape you should generate from the registry, not copy:

TOOL AVAILABILITY SCAN
──────────────────────
Image generation:  {configured}/{total}
  ✅ {tool_name} ({provider}) — available
  ❌ {tool_name} ({provider}) — {install_instructions trimmed to one line}
Video generation:  {configured}/{total}
  ...
Composition runtimes:  {ffmpeg} / {remotion} / {hyperframes}
  See AGENT_GUIDE.md > "Present Both Composition Runtimes (HARD RULE)".
Audio: {configured}/{total}
Math/Diagram: {configured}/{total}

Rules for this output:

• Every name, provider, cost, and install instruction comes from provider_menu_summary() or provider_menu(). Don't type them from memory — provider surfaces change between releases.
• Never cite a cost that isn't live in the tool's estimate_cost or install metadata.
• Composition runtimes are a separate section because the "Present Both" HARD RULE needs all three engines visible.

Present this scan to the user. Say: "Here's what I can see right now. Based on this, here are your animation approach options."

Step 3b: Animation Approach Decision Matrix

Present the approaches as clear options:

Approach	What It Looks Like	Tools Required	Cost	Proven?
A: Image-Based Animation (Remotion)	AI-generated keyframes with crossfade, camera motion, particles. Looks like moving anime/illustration.	image_selector (any provider) + Remotion	Pull per-image cost from the chosen provider's estimate_cost; 2-3 images per scene is typical	✅ Proven (mori-no-seishin)
B: Clip-Based Video	AI-generated video clips assembled as a story. Most cinematic but least consistent.	video_selector routing to whichever provider is available	Pull per-clip cost from the chosen provider's estimate_cost; varies widely between providers	❌ Not yet proven
C: Programmatic Animation (Manim)	Code-driven math/geometry animation. Precise, clean, 3Blue1Brown style.	math_animate (ManimCE)	Free (local)	❌ Not yet proven
D: Data Visualization (Remotion)	Animated charts, KPIs, kinetic typography. Data-driven storytelling.	Remotion (built-in components)	Free (local)	✅ Proven (zero-key formula)
E: Diagram + Image Stills	Process flows and architecture diagrams with Ken Burns.	diagram_gen + image_selector	diagram_gen is free; per-image cost from image_selector's routed provider	✅ Proven
F: Mixed Mode	Combine any of the above per-scene. Most flexible.	Multiple tools	Sum per-scene from each tool's estimate_cost	Partial

Rule: do NOT fill in a dollar figure in the Cost column from memory. Read every cost live via estimate_cost() or provider_menu_summary() at proposal time. Provider pricing changes between releases.

For each viable approach, present to the user:

APPROACH A: Image-Based Animation (Remotion)
─────────────────────────────────────────────
What it looks like: Multiple AI-generated images per scene, crossfaded with
camera motion (zoom, pan, ken-burns) and particle overlays (fireflies, mist,
sparkles). Creates the illusion of movement from still frames.

You need: An image generation API key.
  → You already have: {from provider_menu_summary: available image_generation providers}
  → Alternative: {from setup_offers: 1-env-var image_generation tools}
  → Alternative: local Stable Diffusion (see local_diffusion tool install_instructions)

Estimated cost for 30s video: pull per-image costs from each provider's
`estimate_cost` (do NOT hardcode — they drift between releases).

Style options: depend on the picked provider; read from playbook and
  provider-specific Layer 3 skill (e.g. `.agents/skills/flux-best-practices`).

APPROACH B: Clip-Based Video
─────────────────────────────
What it looks like: AI-generated 3-5 second video clips assembled as a story.
Most cinematic output but hardest to maintain visual consistency across clips.

You need: A video generation API key.
  → Currently available: {from provider_menu_summary: available video_generation providers}
  → To enable: {from setup_offers: 1-env-var video_generation tools}, or
    install a local video model (see video_selector fallback_tools).

Estimated cost for 30s video: pull from each provider's `estimate_cost` on the
  actual clip plan — per-clip costs range widely between providers and change
  often. Do NOT hardcode.

Note: This approach is not yet proven in the OpenMontage pipeline.
      Consistency across clips is the #1 challenge.

Critical principle: Surface capabilities, don't hide limitations. The user should know exactly what's possible right now vs. what needs setup.

Rules for this section — same as Step 3a:

• Every provider name, env var, and cost comes from provider_menu_summary() or a tool's live install_instructions / estimate_cost.
• The {placeholder} tokens above are for the agent to fill from the registry, not paste literally.
• If you find yourself typing a specific API-key env-var name or a per-unit dollar cost into this section, stop. Those drift between releases; hardcoding them in a director skill is a governance regression (see AGENT_GUIDE.md on hardcoded provider names). Pull the same data from the registry instead.

Step 3c: Mode Selection Rules

• If the topic is visual/artistic (anime, illustration, fantasy) → Approach A (image-based)
• If the topic involves data/statistics/business → Approach D (data viz) or Approach A with data overlays
• If the topic involves math/physics → Approach C (Manim) if available, else Approach E
• If the topic is abstract/conceptual and budget allows → Approach B (clip-based) for key moments
• If no paid APIs available → Approach D (zero-key Remotion) or Approach E (diagrams)
• If the user wants maximum quality and has video gen keys → Approach F (mixed: video clips for hero shots + Remotion for data)
• Always offer at least one free/local option alongside paid approaches
• Never silently downgrade — if the best approach needs a key the user doesn't have, say so explicitly

Step 3d: Mood Board (Before Concepts)

Before developing full concepts, present a quick mood board to catch direction mismatches early:

• 3-5 reference images (animation style examples from web search — show what each approach LOOKS like)
• Color palette direction (2-3 options, e.g. clean data-viz vs vibrant motion graphics vs sketchy hand-drawn)
• Tone references ("Think: 3Blue1Brown meets Kurzgesagt" or "Think: Pixar short meets infographic")
• 1-2 animation style samples (if Manim: mathematical elegance; if Remotion: smooth data transitions; if AI video: cinematic motion)

Ask: "Does this FEEL like what you're imagining? Any of these off-track?"

This catches style misalignment before concept design. If the user expected hand-drawn and you're heading toward data-viz, better to know now.

Step 4: Progressive Reveal and Concept Design

Don't dump the full proposal at once. Build understanding step by step:

1. Research summary (2-3 sentences): "Here's what I found..." → User reacts, course-corrects if needed.
2. Mood board (from Step 3d — already presented) → User confirms animation style direction.
3. Concept options (3+ approaches): → Present below.
4. Invite mixing (see Step 4c below).
5. Production plan for selected concept (tools, cost, timeline): → User approves budget and approach.

Build at least 3 genuinely different concepts. Start from the angles_discovered in the research brief and the animation mode analysis.

For each concept, specify:

4a: Title and Hook

Hook construction patterns for animation:

Pattern	Template	When to Use
Visual surprise	"Watch [thing] transform into [unexpected thing]."	When the animation itself IS the hook
Misconception flip	"You've been visualizing [topic] wrong. Here's what it actually looks like."	When common mental models are wrong
Progressive reveal	"Start with [simple]. End with [complex]. Every step animated."	When the topic has layered complexity
Impossible camera	"What if you could see [invisible process] happening in real time?"	When animation reveals the unseeable
Data surprise	"[Counterintuitive number]. Watch it happen."	When animated data is more powerful than static

Rules:

• Hook must be under 20 words
• Hook must promise a VISUAL experience, not just information
• Hook must be grounded in a specific research finding

4b: Animation Approach and Visual Identity

For each concept, specify:

• Animation approach: image_animation / clip_video / manim / remotion_dataviz / diagram_stills / mixed
• Why this approach: grounded in technique research AND tool availability from Step 3
• Image/video generation provider: which specific provider from the preflight scan (e.g., "FLUX via fal.ai", "gpt-image-1 via OpenAI", "Stable Diffusion local")
• Reuse strategy: What's the visual system? (recurring motifs, layout grid, color scheme, transition family)
• Complexity estimate: How many unique scene types vs. reusable templates?
• Visual identity: palette, typography, texture, motion energy, and why they fit this subject, audience, and platform
• Playbook strategy: preset if it truly fits, or a custom playbook generated via lib/playbook_generator.py

Important: Do not reduce animation identity to a preset name. A physics explainer, a startup launch video, and a dreamy anime short may all use Remotion, but they should not share the same color logic, typography, or motion cadence.

4c: Narrative Structure

Choose from: myth_busting, problem_solution, data_narrative, comparison, timeline, journey, analogy, progressive_build, transformation

Animation-specific structure: progressive_build — start simple, add complexity layer by layer. This is the classic 3Blue1Brown approach and works exceptionally well for math/technical topics.

4d: Duration and Platform

Platform	Duration Range	Word Budget (150 WPM)
TikTok	30-60s	65-150 words
YouTube Shorts	30-60s	65-150 words
YouTube	60-300s	150-750 words
LinkedIn	60-120s	150-300 words

Animation note: Animation videos can be longer than live-action explainers because the visual density sustains attention. A 3-minute math animation holds attention better than a 3-minute talking head.

4e: Concept Diversity Check

• No two concepts use the same animation approach
• No two concepts use the same narrative structure
• At least one concept is achievable with free/local tools only (zero-key or local image gen)
• At least one concept leverages the most surprising data point
• Each concept's approach is grounded in tool availability AND technique research
• Each concept states which API keys/tools it requires (and flags any the user doesn't have)

Step 5: Present Concepts and Get Selection

Present all concepts clearly to the user. For each concept, show:

1. Title and hook — the creative pitch
2. Animation mode — what the video will LOOK like (with a plain-language description)
3. Why this works — research backing, in one sentence
4. Duration — how long
5. Reuse strategy — "5 scenes built from 2 templates" vs "8 unique scenes"

Step 5b: Invite Mixing

After presenting concepts, always say something like:

"You can also mix elements — for example, Concept A's hook with Concept C's animation approach, or Concept B's narrative with Concept A's visual style. What speaks to you?"

If the user mixes, create a new hybrid concept entry in the proposal_packet with clear attribution: "Hook from Concept A, animation approach from Concept C, narrative structure from Concept B."

Let the user select, combine, modify, or redirect.

Record the selection in selected_concept with rationale and any modifications.

Step 6: Build the Production Plan

For the selected concept, design the stage-by-stage production plan.

Animation-specific production plan fields:

PRODUCTION PLAN (Animation Pipeline)

animation_mode: [selected mode]
reuse_strategy:
  recurring_motifs: [list]
  layout_system: [description]
  transition_family: [type]
  typography_hierarchy: [levels]
  estimated_unique_scenes: [N]
  estimated_reusable_templates: [N]

stages:
  script:
    tools: [none — creative work]
    cost: $0
    notes: "Script must be written in animation beats — one visual idea per section"

  scene_plan:
    tools: [none — planning work]
    cost: $0
    notes: "Scene plan must specify animation mode per scene and reuse template references"

  assets:
    tools: [specific providers from preflight]
    cost: [itemized]
    notes: "Reusable motifs generated once, referenced by multiple scenes"

  edit:
    tools: [none — planning work]
    cost: $0
    notes: "Edit must preserve hold times and staggered reveals"

  compose:
    tools: [video_compose, audio_mixer]
    cost: $0 (local rendering)
    notes: "Text and diagrams must remain sharp at final resolution"

  publish:
    tools: [none — metadata work]
    cost: $0

Step 7: Build the Cost Estimate

Itemize every paid operation:

COST ESTIMATE
├── TTS Narration: [provider] × 1 run              $X.XX
├── Image Generation: [provider] × N scenes          $X.XX
│   (N unique + M reused = total scenes)
├── AI Video Clips: [provider] × K clips (if any)   $X.XX
├── Music: music_gen × 1 track                       $X.XX
├── Math Animation: math_animate (local/free)        $0.00
├── Diagram Generation: diagram_gen (local/free)     $0.00
└── TOTAL ESTIMATED                                  $X.XX
    Budget cap: $X.XX
    Verdict: within_budget ✓ / over_budget ✗
    Headroom: $X.XX for revisions

Animation cost note: Programmatic animation (Manim, Remotion, diagram_gen) is FREE. This means animation pipelines can often be much cheaper than explainer pipelines — the primary cost is TTS narration and any AI-generated images/video used as backgrounds or transitions.

Step 8: Assemble the Approval Gate

────────────────────────────────────────
PROPOSAL READY FOR APPROVAL

Concept: [selected title]
Animation mode: [mode] — [plain description]
Duration: [X] seconds for [platform]
Reuse strategy: [N] unique scenes from [M] templates
Estimated cost: $[X.XX] of $[budget] budget
Production path: [premium/standard/budget/free]

Proceed? (approve / approve with changes / reject)
────────────────────────────────────────

Critical rule: The pipeline MUST NOT proceed past this stage without explicit approval.

Step 9: Submit

Validate the proposal_packet artifact against schemas/artifacts/proposal_packet.schema.json and submit.

How This Connects Downstream

Downstream Stage	What It Takes From proposal_packet
Script Director	selected_concept (title, hook, key_points, animation_mode, narrative_structure) + research data
Scene Director	selected_concept.animation_mode + reuse_strategy + production_plan.playbook
Asset Director	production_plan.stages[assets].tools — knows exactly which providers to use
Executive Producer	cost_estimate — initializes budget tracking
All stages	approval.approved_budget_usd — hard spending cap

Common Pitfalls

• Not showing the Tool Availability Scan: The user must know what's available BEFORE seeing concepts. Don't hide missing keys or tools.
• Ignoring animation approach feasibility: If the routed image/video provider isn't available, don't propose that approach without explicitly telling the user what's needed. Read each missing tool's install_instructions from the registry (do NOT hardcode specific env var names here — they drift). Design around constraints OR explicitly state what's needed.
• Three versions of the same concept with different titles: Structural diversity means different animation approaches, different narrative structures, different hooks.
• Not leveraging free tools: Animation has a huge cost advantage — Manim, Remotion data-viz, and diagram_gen are free. If proposing expensive AI video, justify why free alternatives won't work.
• Over-promising visual complexity: 20 unique hand-crafted scenes is not realistic. Design reuse strategies that look varied but share underlying templates.
• Skipping the approval gate: This is the whole point of pre-production. No shortcuts.
• Ignoring mathematical accuracy: If the research brief flagged technical accuracy constraints, the concept MUST respect them. A beautiful but wrong animation is a failure.
• Not distinguishing image_animation from clip_video: These are fundamentally different. Image-based animation (Approach A) generates still images and uses Remotion for motion/crossfade. Clip-based video (Approach B) generates actual video clips with an AI video model. The user should understand this distinction clearly.
• Silent downgrades: If the user picked image_animation but image generation fails, STOP and tell them. Never silently fall back to text cards or diagram stills.

When You Do Not Know How

If you encounter a generation technique, provider behavior, or prompting pattern you are unsure about:

1. Search the web for current best practices — models and APIs change frequently, and the agent's training data may be stale
2. Check .agents/skills/ for existing Layer 3 knowledge (provider-specific prompting guides, API patterns)
3. If neither helps, write a project-scoped skill at projects/<project-name>/skills/<name>.md documenting what you learned
4. Reference source URLs in the skill so the knowledge is traceable
5. Log it in the decision log: category: "capability_extension", subject: "learned technique: <name>"

This is especially important for:

• Video generation prompting — models respond to specific vocabularies that change with each version
• Image model parameters — optimal settings for FLUX, DALL-E, Imagen differ and evolve
• Audio provider quirks — voice cloning, music generation, and TTS each have model-specific best practices
• Remotion component patterns — new composition techniques emerge as the framework evolves

Do not rely on stale knowledge. When in doubt, search first.