# 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:

```bash
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:

```bash
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:

```python
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.
