Initial release — OpenMontage: the first open-source agentic video production system
11 production pipelines, 47 tools, 124 agent skills. Supports cloud APIs (fal.ai, OpenAI, ElevenLabs, Suno, HeyGen, Runway) and free local providers (diffusers, Piper TTS, WAN 2.1, Hunyuan, CogVideo). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
calesthio
@@ -0,0 +1,70 @@
|
||||
# Asset Director - Animation Pipeline
|
||||
|
||||
## When To Use
|
||||
|
||||
This stage prepares the actual animated ingredients: narration, diagrams, math renders, motion backgrounds, code visuals, and reusable type or layout systems.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Layer | Resource | Purpose |
|
||||
|-------|----------|---------|
|
||||
| Schema | `schemas/artifacts/asset_manifest.schema.json` | Artifact validation |
|
||||
| Prior artifacts | `state.artifacts["scene_plan"]["scene_plan"]`, `state.artifacts["script"]["script"]`, `state.artifacts["idea"]["brief"]` | Tool path and beat map |
|
||||
| Tools | `tts_selector`, `image_selector`, `video_selector`, `math_animate`, `diagram_gen`, `code_snippet`, `music_gen` — selectors auto-discover all available providers from the registry | Asset production options |
|
||||
| Playbook | Active style playbook | Visual consistency |
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Start With Deterministic Assets
|
||||
|
||||
Prefer the lowest-variance useful path:
|
||||
|
||||
- `diagram_gen` before generic image generation for structured diagrams,
|
||||
- `code_snippet` for code scenes,
|
||||
- `math_animate` for real math motion,
|
||||
- provided artwork before new generation.
|
||||
|
||||
### 1b. Sample Preview (Prevents Wasted Spend)
|
||||
|
||||
Before batch-generating assets, produce one sample of each expensive type and show the user:
|
||||
|
||||
1. **TTS sample** (if narration-led): Generate one section. Confirm voice and tone before batching.
|
||||
2. **Visual sample**: Generate one representative scene visual (diagram, illustration, or motion background). Confirm style and quality before batching the rest.
|
||||
|
||||
If rejected, adjust parameters and retry (max 3 iterations). Do not batch until approved.
|
||||
|
||||
### 2. Build Reusable Systems
|
||||
|
||||
Create once:
|
||||
|
||||
- typography treatments,
|
||||
- lower-third or label styles,
|
||||
- repeated motif assets,
|
||||
- background containers.
|
||||
|
||||
### 3. Narration Is Optional, But The Plan Must Be Explicit
|
||||
|
||||
If the project is narration-led, produce or source narration. If it is text-led or music-led, say so clearly in metadata.
|
||||
|
||||
### 4. Use Metadata For Feasibility Truth
|
||||
|
||||
Recommended metadata keys:
|
||||
|
||||
- `tool_path_map`
|
||||
- `reusable_assets`
|
||||
- `narration_assets`
|
||||
- `scene_asset_index`
|
||||
- `blocked_assets`
|
||||
|
||||
### 5. Quality Gate
|
||||
|
||||
- the asset path is explicit per scene,
|
||||
- reusable assets are actually reused,
|
||||
- missing capabilities are surfaced honestly,
|
||||
- every referenced file exists.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- Using high-variance generation when a deterministic asset would work better.
|
||||
- Rebuilding the same title or label system repeatedly.
|
||||
- Hiding failed asset paths instead of reporting them.
|
||||
@@ -0,0 +1,47 @@
|
||||
# Compose Director - Animation Pipeline
|
||||
|
||||
## When To Use
|
||||
|
||||
Render the animation with an emphasis on text sharpness, timing integrity, and consistent output cadence.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Layer | Resource | Purpose |
|
||||
|-------|----------|---------|
|
||||
| Schema | `schemas/artifacts/render_report.schema.json` | Artifact validation |
|
||||
| Prior artifacts | `state.artifacts["edit"]["edit_decisions"]`, `state.artifacts["assets"]["asset_manifest"]` | Timing plan and asset files |
|
||||
| Tools | `video_compose`, `audio_mixer`, `video_stitch` | Final assembly |
|
||||
| Playbook | Active style playbook | Render consistency |
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Preserve Motion Timing
|
||||
|
||||
Do not let export settings or careless composition change the perceived timing of holds, stagger, or scene transitions.
|
||||
|
||||
### 2. Protect Text And Diagram Sharpness
|
||||
|
||||
Animation often fails on export through soft text, muddy thin lines, or cramped mobile framing.
|
||||
|
||||
### 3. Verify The First And Last Frames
|
||||
|
||||
Ensure:
|
||||
|
||||
- the opening frame reads immediately,
|
||||
- the final frame lands cleanly,
|
||||
- nothing important is clipped by safe zones.
|
||||
|
||||
### 4. Use Render Metadata
|
||||
|
||||
Recommended metadata keys:
|
||||
|
||||
- `render_fps`
|
||||
- `sharpness_checks`
|
||||
- `safe_zone_checks`
|
||||
- `variant_outputs`
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- Soft or aliased text after rendering.
|
||||
- Compression choices that damage diagrams.
|
||||
- Scene cadence changing between preview and final.
|
||||
@@ -0,0 +1,54 @@
|
||||
# Edit Director - Animation Pipeline
|
||||
|
||||
## When To Use
|
||||
|
||||
This stage turns the scene plan into an animatic-grade edit plan. Timing is the product.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Layer | Resource | Purpose |
|
||||
|-------|----------|---------|
|
||||
| Schema | `schemas/artifacts/edit_decisions.schema.json` | Artifact validation |
|
||||
| Prior artifacts | `state.artifacts["assets"]["asset_manifest"]`, `state.artifacts["scene_plan"]["scene_plan"]`, `state.artifacts["script"]["script"]` | Assets, timing plan, and beats |
|
||||
| Playbook | Active style playbook | Motion and typography rules |
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Protect Hold Time
|
||||
|
||||
After key reveals, plan enough time for the viewer to process the frame. Do not stack every scene edge to edge with motion.
|
||||
|
||||
### 2. Stagger Secondary Elements
|
||||
|
||||
Primary element first, supporting elements second. The edit decisions should reinforce hierarchy.
|
||||
|
||||
### 3. Keep Motion Meaningful
|
||||
|
||||
Motion should signal:
|
||||
|
||||
- emphasis,
|
||||
- transition,
|
||||
- transformation,
|
||||
- contrast.
|
||||
|
||||
### 4. Use Metadata For Timing Detail
|
||||
|
||||
Recommended metadata keys:
|
||||
|
||||
- `hold_windows`
|
||||
- `stagger_rules`
|
||||
- `transition_map`
|
||||
- `scene_timing_notes`
|
||||
|
||||
### 5. Quality Gate
|
||||
|
||||
- key information has enough dwell time,
|
||||
- movement clarifies hierarchy,
|
||||
- transitions stay consistent,
|
||||
- the edit remains readable on the target platform.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- Overcrowding the timeline with continuous motion.
|
||||
- Revealing all elements at once.
|
||||
- Letting stylistic motion reduce readability.
|
||||
@@ -0,0 +1,420 @@
|
||||
# Executive Producer — Animation Pipeline
|
||||
|
||||
## When to Use
|
||||
|
||||
You are the **Executive Producer (EP)** for a generated animation video. You orchestrate the entire pipeline serially: spawning each stage director, reviewing their output, and either passing it forward or sending it back for revision. You are the stateful brain; the directors are stateless workers.
|
||||
|
||||
**You replace the default parallel/sequential execution model.** Instead of running all stages blindly, you exercise judgment at every gate.
|
||||
|
||||
## Why This Exists
|
||||
|
||||
Animation pipelines have unique failure modes that parallel execution cannot catch:
|
||||
|
||||
- Motion consistency breaks when scenes are generated independently
|
||||
- Mathematical accuracy errors compound if not caught after script
|
||||
- Animation timing requires hold times and reveals that get squeezed out without cross-stage awareness
|
||||
- Reuse strategy degrades when each stage plans independently
|
||||
- Budget allocation between AI-generated assets and free programmatic animation needs active management
|
||||
- Text readability and diagram sharpness must be verified at compose time, not assumed
|
||||
|
||||
The EP solves all of these by maintaining cumulative state and applying animation-specific judgment at each gate.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Layer | Resource | Purpose |
|
||||
|-------|----------|---------|
|
||||
| Pipeline | `pipeline_defs/animation.yaml` | Stage definitions, review focus, success criteria |
|
||||
| Skills | All 9 director skills + `meta/reviewer` | Stage execution knowledge |
|
||||
| Schemas | All artifact schemas | Validation |
|
||||
| Playbook | Active style playbook | Quality constraints |
|
||||
| Tools | Full tool registry | Available capabilities |
|
||||
|
||||
## Cumulative State
|
||||
|
||||
The EP maintains a running state object that flows through the entire pipeline:
|
||||
|
||||
```
|
||||
EP_STATE:
|
||||
pipeline: animation
|
||||
playbook: <selected playbook name>
|
||||
target_duration_seconds: <from proposal_packet.selected_concept>
|
||||
budget_total_usd: <from proposal_packet.approval.approved_budget_usd or configured limit>
|
||||
budget_spent_usd: 0.0
|
||||
budget_remaining_usd: <budget_total>
|
||||
|
||||
# Animation-specific state
|
||||
animation_mode: <manim | remotion | ai_video | diagram_stills | mixed>
|
||||
reuse_strategy:
|
||||
recurring_motifs: []
|
||||
layout_system: null
|
||||
transition_family: null
|
||||
typography_hierarchy: null
|
||||
unique_scene_count: 0
|
||||
reused_template_count: 0
|
||||
math_accuracy_notes: [] # constraints from research on what NOT to oversimplify
|
||||
|
||||
# Accumulated from each stage (8 stages)
|
||||
artifacts:
|
||||
research: null # → research_brief
|
||||
proposal: null # → proposal_packet (includes approval gate)
|
||||
script: null # → script
|
||||
scene_plan: null # → scene_plan
|
||||
assets: null # → asset_manifest
|
||||
edit: null # → edit_decisions
|
||||
compose: null # → render_report
|
||||
publish: null # → publish_log
|
||||
|
||||
# Pre-production context (carried forward from research + proposal)
|
||||
research_brief: null # full research_brief artifact
|
||||
selected_concept: null # the approved concept from proposal_packet
|
||||
production_plan: null # the approved tool/provider plan
|
||||
approved_budget_usd: null # explicit user-approved spend cap
|
||||
|
||||
# Cross-stage tracking
|
||||
narration_durations: {} # section_id → actual_seconds
|
||||
total_narration_seconds: 0
|
||||
total_visual_seconds: 0
|
||||
style_anchors: {} # consistency tokens carried forward
|
||||
revision_counts: {} # stage_name → number of revisions
|
||||
issues_log: [] # all issues found, with resolution status
|
||||
```
|
||||
|
||||
## Execution Protocol
|
||||
|
||||
### Phase 0: Initialize
|
||||
|
||||
1. Load the pipeline manifest (`animation.yaml`)
|
||||
2. Load the playbook (from user selection or default)
|
||||
3. Set budget from configuration or user input (default: $2.00)
|
||||
4. Initialize EP_STATE
|
||||
|
||||
### Phase 1: Execute Stages Serially
|
||||
|
||||
For each stage in order: `research → proposal → script → scene_plan → assets → edit → compose → publish`
|
||||
|
||||
**Pre-production stages (research, proposal)** run before any money is spent:
|
||||
- **research** gathers topic data AND animation technique references via web search — zero cost
|
||||
- **proposal** presents concepts with animation mode selection and costs to the user — zero cost, but contains the **approval gate**
|
||||
- The pipeline MUST NOT proceed past proposal without `approval.status == "approved"` or `"approved_with_changes"`
|
||||
|
||||
After proposal approval, extract and store in EP_STATE:
|
||||
- `selected_concept` from `proposal_packet.selected_concept`
|
||||
- `animation_mode` from `selected_concept.animation_mode`
|
||||
- `reuse_strategy` from `selected_concept.reuse_strategy`
|
||||
- `production_plan` from `proposal_packet.production_plan`
|
||||
- `approved_budget_usd` from `proposal_packet.approval.approved_budget_usd`
|
||||
- `playbook` from `proposal_packet.selected_concept → suggested_playbook`
|
||||
- `math_accuracy_notes` from research_brief (if applicable)
|
||||
|
||||
```
|
||||
EXECUTE_STAGE(stage_name):
|
||||
|
||||
1. PREPARE
|
||||
- Load the director skill for this stage
|
||||
- Inject EP_STATE as context (prior artifacts, budget remaining, style anchors, animation mode, reuse strategy)
|
||||
- Inject any EP feedback from previous revision attempts
|
||||
|
||||
2. SPAWN DIRECTOR
|
||||
- The director executes its full process (as defined in its skill MD)
|
||||
- Director produces an artifact
|
||||
|
||||
3. REVIEW (EP performs this, not a separate reviewer)
|
||||
- Schema validation against artifact schema
|
||||
- Check review_focus items from pipeline manifest
|
||||
- Check success_criteria from pipeline manifest
|
||||
- Cross-check against playbook constraints
|
||||
- Run EP-SPECIFIC CROSS-STAGE CHECKS (see below)
|
||||
|
||||
4. GATE DECISION
|
||||
If PASS:
|
||||
- Store artifact in EP_STATE
|
||||
- Update cumulative tracking (budget, durations, etc.)
|
||||
- Log: "[stage] PASSED — moving to next stage"
|
||||
- Continue to next stage
|
||||
|
||||
If REVISE:
|
||||
- Increment revision_counts[stage_name]
|
||||
- If revision_counts[stage_name] >= 3:
|
||||
- PASS WITH WARNINGS (never block forever)
|
||||
- Log unresolved issues
|
||||
- Else:
|
||||
- Compose specific feedback for the director
|
||||
- Re-run SPAWN DIRECTOR with feedback injected
|
||||
- Re-run REVIEW
|
||||
|
||||
If SEND_BACK(target_stage):
|
||||
- Only used when a downstream discovery invalidates upstream work
|
||||
- Re-execute from target_stage forward (artifacts after target are invalidated)
|
||||
- Max 1 send-back per stage pair (prevent infinite loops)
|
||||
```
|
||||
|
||||
### Phase 2: Final Quality Assurance
|
||||
|
||||
After all stages complete, the EP performs a holistic review:
|
||||
|
||||
```
|
||||
FINAL_QA:
|
||||
1. PROBE the output video:
|
||||
- Duration: within ±5% of target?
|
||||
- Resolution: matches media profile?
|
||||
- Audio: narration audible throughout? Music balanced?
|
||||
- File: valid container, reasonable size?
|
||||
|
||||
2. TEXT AND DIAGRAM SHARPNESS (ANIMATION-SPECIFIC):
|
||||
- Are text elements readable at target resolution?
|
||||
- Are diagram lines crisp, not blurry from scaling?
|
||||
- Are mathematical symbols rendered correctly?
|
||||
- Is typography hierarchy maintained across scenes?
|
||||
|
||||
3. MOTION CONSISTENCY:
|
||||
- Do transitions follow the declared transition family?
|
||||
- Are hold times preserved (not squeezed by timing)?
|
||||
- Do staggered reveals play correctly?
|
||||
- Is the pacing animation-friendly (not rushed)?
|
||||
|
||||
4. STYLE CONSISTENCY:
|
||||
- Do all scenes follow the reuse strategy?
|
||||
- Is the color palette consistent?
|
||||
- Do recurring motifs appear correctly across scenes?
|
||||
|
||||
5. MATHEMATICAL ACCURACY (if applicable):
|
||||
- Do animated formulas/diagrams match the research brief's accuracy notes?
|
||||
- Are any simplifications flagged in the research still correct?
|
||||
|
||||
6. BUDGET RECONCILIATION:
|
||||
- Total actual spend vs. budget
|
||||
- Log per-stage cost breakdown
|
||||
|
||||
7. DECISION:
|
||||
If all checks pass → APPROVE for publish stage
|
||||
If issues found → Send back to the specific stage(s) that can fix them
|
||||
- Text/diagram issues → compose director (re-render) or asset director (regenerate)
|
||||
- Motion issues → edit director (re-time) or scene director (replan)
|
||||
- Audio issues → compose director
|
||||
- Duration issues → script director (rewrite)
|
||||
- Math errors → script director (fix content) then cascade forward
|
||||
```
|
||||
|
||||
## EP-Specific Cross-Stage Checks
|
||||
|
||||
These checks use information accumulated across stages — something no individual director can do.
|
||||
|
||||
### After RESEARCH stage:
|
||||
```
|
||||
CHECK: Research depth
|
||||
- At least 3 data_points with source URLs?
|
||||
- At least 3 angles_discovered with grounded_in references?
|
||||
- At least 2 animation technique references?
|
||||
- At least 5 sources cited?
|
||||
- If any minimum not met: REVISE research
|
||||
- Note: Do NOT checkpoint with user — research is informational, not a decision point
|
||||
```
|
||||
|
||||
### After PROPOSAL stage:
|
||||
```
|
||||
CHECK: Approval gate (CRITICAL)
|
||||
- Is approval.status == "approved" or "approved_with_changes"?
|
||||
- If "pending" or "rejected": STOP. Present to user and wait.
|
||||
- If "approved_with_changes": apply modifications before proceeding
|
||||
- Extract: animation_mode, reuse_strategy, target_duration, playbook, budget, tool selections
|
||||
|
||||
CHECK: Animation mode feasibility
|
||||
- Does the selected animation mode's required tools exist in the registry?
|
||||
- If Manim mode selected: is math_animate available?
|
||||
- If Remotion mode selected: is video_compose (Remotion) available?
|
||||
- If AI video mode selected: are video generation providers available?
|
||||
- If any required tool is unavailable: alert user, offer alternatives
|
||||
|
||||
CHECK: Reuse strategy validity
|
||||
- Does the reuse strategy define recurring motifs?
|
||||
- Is the unique-to-template ratio reasonable (aim for ≤ 3:1)?
|
||||
```
|
||||
|
||||
### After SCRIPT stage:
|
||||
```
|
||||
CHECK: Word count vs. duration target
|
||||
- Calculate: total_words / 150 = estimated_minutes
|
||||
- If estimated_minutes > target_duration * 1.15:
|
||||
REVISE script: "Script is {X} words → {Y}min. Target: {Z}min. Cut {N} words."
|
||||
- If estimated_minutes < target_duration * 0.7:
|
||||
REVISE script: "Script is too short. Add {N} words."
|
||||
|
||||
CHECK: Animation beat structure
|
||||
- Does each section express ONE clear visual idea?
|
||||
- Are hold times budgeted (not every second filled with new information)?
|
||||
- Is on-screen text concise (phrases, not paragraphs)?
|
||||
|
||||
CHECK: Mathematical accuracy (if applicable)
|
||||
- Does the script's explanation match the research brief's accuracy notes?
|
||||
- Are any simplifications technically defensible?
|
||||
- If inaccurate: REVISE script with specific correction from research
|
||||
```
|
||||
|
||||
### After SCENE_PLAN stage:
|
||||
```
|
||||
CHECK: Total scene duration covers full script
|
||||
- Sum all scene durations
|
||||
- Compare to script's total duration
|
||||
- If gaps > 1 second: REVISE scene_plan
|
||||
- If overlaps: REVISE scene_plan
|
||||
|
||||
CHECK: Animation mode adherence
|
||||
- Does every scene specify which animation mode/tool it uses?
|
||||
- Are mode choices consistent with the proposal's selected mode?
|
||||
- If mixed mode: are transitions between modes planned?
|
||||
|
||||
CHECK: Reuse strategy enforcement
|
||||
- Does the scene plan reference the recurring motifs from the proposal?
|
||||
- Are templates reused where specified?
|
||||
- If every scene is unique: flag as potential over-complexity
|
||||
|
||||
CHECK: Visual variety within constraints
|
||||
- Count consecutive same-type scenes
|
||||
- If > 3 consecutive: REVISE scene_plan
|
||||
```
|
||||
|
||||
### After ASSETS stage:
|
||||
```
|
||||
CHECK: Narration duration feedback loop (CRITICAL)
|
||||
- For each TTS audio file, probe actual duration
|
||||
- Store in EP_STATE.narration_durations
|
||||
- For each section:
|
||||
If actual_duration > planned_duration * 1.15:
|
||||
Option A: SEND_BACK to script director
|
||||
Option B (within 25% over): Adjust scene_plan durations
|
||||
- Update EP_STATE.total_narration_seconds
|
||||
|
||||
CHECK: Budget gate
|
||||
- If budget_spent > budget_total * 0.9 and stages remain:
|
||||
Alert: "90% budget consumed with {N} stages remaining"
|
||||
Adjust remaining stages to free/cheap alternatives
|
||||
|
||||
CHECK: Style consistency
|
||||
- Compare visual styles across all generated assets
|
||||
- Are recurring motifs visually consistent?
|
||||
- Store style_anchors for downstream use
|
||||
|
||||
CHECK: Programmatic asset integrity (if Manim/Remotion)
|
||||
- Did math_animate or video_compose succeed without errors?
|
||||
- Are output files valid and correctly sized?
|
||||
```
|
||||
|
||||
### After EDIT stage:
|
||||
```
|
||||
CHECK: Timeline completeness
|
||||
- Verify edit decisions cover 0 to total_duration with no gaps
|
||||
- Verify all asset references point to existing files
|
||||
- Verify audio ducking is configured for all narration segments
|
||||
|
||||
CHECK: Hold time preservation (ANIMATION-SPECIFIC)
|
||||
- Verify hold times from scene_plan are preserved in edit decisions
|
||||
- Verify staggered reveals are not compressed
|
||||
- Verify motion serves hierarchy, not decoration
|
||||
|
||||
CHECK: A/V sync pre-validation
|
||||
- For each cut: narration_start aligns with visual_start (±0.5s)
|
||||
- For each scene: narration_duration ≤ visual_duration
|
||||
```
|
||||
|
||||
### After COMPOSE stage:
|
||||
```
|
||||
CHECK: Output validation
|
||||
- ffprobe the output: duration, resolution, codec, audio channels
|
||||
- If duration drift > 5%: investigate which stage caused it
|
||||
- If audio missing: check audio_mixer configuration
|
||||
- If resolution wrong: check media profile selection
|
||||
|
||||
CHECK: Text and diagram sharpness (ANIMATION-CRITICAL)
|
||||
- Text must be readable at target resolution
|
||||
- Diagram lines must be crisp (no scaling artifacts)
|
||||
- Mathematical symbols must render correctly
|
||||
- If any text/diagram is blurry: REVISE compose with resolution/scaling adjustments
|
||||
```
|
||||
|
||||
## Feedback Message Templates
|
||||
|
||||
### To Script Director:
|
||||
```
|
||||
EP FEEDBACK — Script Revision Required
|
||||
Reason: {reason}
|
||||
Specific issue: {detail}
|
||||
Constraint: {word_count_limit / duration_target / math_accuracy}
|
||||
Animation mode: {current mode — affects how text and beats should be structured}
|
||||
Keep: {what was good}
|
||||
Change: {what specifically needs to change}
|
||||
```
|
||||
|
||||
### To Scene Director:
|
||||
```
|
||||
EP FEEDBACK — Scene Plan Revision Required
|
||||
Reason: {reason}
|
||||
Affected scenes: {scene_ids}
|
||||
Animation mode: {current mode}
|
||||
Reuse strategy: {what motifs/templates should be reused}
|
||||
Available tools: {current tool registry status}
|
||||
```
|
||||
|
||||
### To Asset Director:
|
||||
```
|
||||
EP FEEDBACK — Asset Regeneration Required
|
||||
Reason: {reason}
|
||||
Affected assets: {asset_ids}
|
||||
Style anchors: {consistency requirements}
|
||||
Animation mode: {current mode — affects which tools to use}
|
||||
Budget remaining: ${remaining}
|
||||
```
|
||||
|
||||
### To Compose Director:
|
||||
```
|
||||
EP FEEDBACK — Re-render Required
|
||||
Reason: {reason}
|
||||
Specific issue: {text_sharpness / motion_timing / audio_sync / etc.}
|
||||
Expected: {what the output should be}
|
||||
Actual: {what was produced}
|
||||
```
|
||||
|
||||
## Quality Gates Summary
|
||||
|
||||
| Gate | After Stage | What's Checked | Fail Action |
|
||||
|------|-------------|---------------|-------------|
|
||||
| G1 | research | Data depth, technique references, angle diversity | Revise research |
|
||||
| G2 | proposal | Concept quality, mode feasibility, user approval | Revise proposal OR wait for user |
|
||||
| G3 | script | Word count, beat structure, math accuracy | Revise script |
|
||||
| G4 | scene_plan | Coverage, mode adherence, reuse strategy, variety | Revise scene_plan |
|
||||
| G5 | assets | Narration duration, budget, style, asset integrity | Revise assets OR send-back to script |
|
||||
| G6 | edit | Timeline completeness, hold times, A/V pre-sync | Revise edit |
|
||||
| G7 | compose | Output probe, text sharpness, motion timing | Revise compose OR send-back |
|
||||
| G8 | publish | Metadata, packaging, animation-mode tags | Revise publish |
|
||||
| FINAL | all | Holistic review: sharpness, motion, accuracy, style | Send-back to specific stage |
|
||||
|
||||
## Execution Limits (Anti-Loop Protection)
|
||||
|
||||
| Limit | Value | Rationale |
|
||||
|-------|-------|-----------|
|
||||
| Max revisions per stage | 3 | Prevent perfectionism loops |
|
||||
| Max send-backs per stage pair | 1 | Prevent ping-pong |
|
||||
| Max total send-backs | 3 | Cap total re-work |
|
||||
| Max total budget | Configurable (default $2) | Hard stop on spending |
|
||||
| Max total wall-time | 15 minutes | Timeout for entire pipeline |
|
||||
|
||||
After any limit is hit: **proceed with warnings**, never block indefinitely.
|
||||
|
||||
## Integration with Existing Skills
|
||||
|
||||
The EP doesn't replace any director skill — it wraps them. Each director skill continues to work exactly as documented. The EP adds:
|
||||
|
||||
1. **Context injection**: Directors receive EP_STATE with cross-stage information
|
||||
2. **Feedback injection**: Directors receive specific revision instructions when sent back
|
||||
3. **Budget awareness**: Directors receive remaining budget and adjust tool choices
|
||||
4. **Animation mode context**: Directors know the selected mode and reuse strategy
|
||||
5. **Style anchors**: Directors receive consistency tokens from prior stages
|
||||
6. **Math accuracy notes**: Directors receive constraints on technical accuracy
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Over-revising**: A "good enough" animation in the right mode is better than a "perfect" one after 5 rounds.
|
||||
- **Ignoring text sharpness**: The #1 animation quality issue. Always verify text readability at final resolution.
|
||||
- **Letting reuse strategy erode**: If the proposal specified 3 templates, the scene plan should use 3 templates, not 8 unique designs.
|
||||
- **Not probing outputs**: Always ffprobe the final video. Never trust metadata alone.
|
||||
- **Losing animation mode context**: If the proposal selected Manim, every downstream stage should know it's a Manim project. Don't let stages default to generic image_selector when programmatic animation was approved.
|
||||
- **Skipping math accuracy checks**: For technical topics, this is non-negotiable. A wrong animation is worse than no animation.
|
||||
@@ -0,0 +1,72 @@
|
||||
# Idea Director - Animation Pipeline
|
||||
|
||||
## When To Use
|
||||
|
||||
Use this pipeline when the video should be built primarily through designed motion: motion graphics, kinetic typography, diagram-led explainers, math visuals, or illustrative animation.
|
||||
|
||||
Do not use this pipeline when the project is really footage-led with a few overlays. That belongs in `hybrid`.
|
||||
|
||||
## Reference Inputs
|
||||
|
||||
- `docs/animation-best-practices.md`
|
||||
- `skills/creative/animation-pipeline.md`
|
||||
- `skills/creative/storytelling.md`
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Classify The Animation Mode
|
||||
|
||||
Choose the primary mode:
|
||||
|
||||
- `diagrammatic`
|
||||
- `motion_graphics`
|
||||
- `kinetic_type`
|
||||
- `math_animation`
|
||||
- `illustrative`
|
||||
- `mixed_animation`
|
||||
|
||||
### 2. Decide The Visual Path Early
|
||||
|
||||
Figure out which tools are supposed to do the work:
|
||||
|
||||
- `diagram_gen`
|
||||
- `math_animate`
|
||||
- `code_snippet`
|
||||
- `image_selector`
|
||||
- `video_selector` or a concrete video provider tool
|
||||
- source-provided art
|
||||
|
||||
If the requested mode depends on unavailable tools, say so in the brief metadata immediately.
|
||||
|
||||
### 3. Choose A Reuse Strategy
|
||||
|
||||
Animation gets expensive when every scene is unique. Define:
|
||||
|
||||
- recurring motifs,
|
||||
- layout system,
|
||||
- transition family,
|
||||
- typography hierarchy.
|
||||
|
||||
### 4. Build The Brief
|
||||
|
||||
Recommended metadata keys:
|
||||
|
||||
- `animation_mode`
|
||||
- `visual_path`
|
||||
- `narration_strategy`
|
||||
- `reuse_strategy`
|
||||
- `timing_style`
|
||||
- `blocked_capabilities`
|
||||
|
||||
### 5. Quality Gate
|
||||
|
||||
- the animation mode is explicit,
|
||||
- the visual path is feasible,
|
||||
- the project is designed for reuse,
|
||||
- the brief is honest about missing tools.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- Treating all animation as one generic category.
|
||||
- Planning bespoke visuals for every scene.
|
||||
- Hiding missing tool paths until the asset stage.
|
||||
@@ -0,0 +1,263 @@
|
||||
# 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.
|
||||
|
||||
## 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 1: Absorb the Research
|
||||
|
||||
Read the `research_brief` thoroughly. 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 Mode Decision Matrix
|
||||
|
||||
This is the key differentiator from the explainer proposal. For each viable animation mode, evaluate:
|
||||
|
||||
| Mode | Best For | Tool Required | Visual Quality | Cost | Iteration Speed |
|
||||
|------|----------|---------------|----------------|------|-----------------|
|
||||
| **Manim (ManimCE)** | Math, physics, geometry, algorithms | `math_animate` | Precise, programmatic | Free (local) | Fast (code-driven) |
|
||||
| **Remotion** | Data viz, charts, React components, kinetic type | `video_compose` (Remotion mode) | Smooth, web-native | Free (local) | Fast (code-driven) |
|
||||
| **AI Video Generation** | Abstract concepts, metaphors, transitions | `video_selector` providers | Variable, cinematic | $0.05-0.50/clip | Slow (generation time) |
|
||||
| **Diagram + Image Stills** | Process flows, architecture, comparisons | `diagram_gen` + `image_selector` | Clean, reliable | $0-0.05/image | Fast |
|
||||
| **Mixed Mode** | Complex topics needing multiple techniques | Multiple tools | Varied | Varies | Moderate |
|
||||
|
||||
**Mode selection rules:**
|
||||
- If the topic involves math/formulas/geometry → prefer Manim
|
||||
- If the topic involves data/statistics/charts → prefer Remotion or diagram_gen
|
||||
- If the topic is abstract/conceptual → consider AI video for key moments
|
||||
- If the topic is process/workflow → prefer diagram builds
|
||||
- Always check tool availability before committing to a mode
|
||||
- Mixed mode is valid when different sections need different approaches
|
||||
|
||||
### Step 4: Design Concept Options
|
||||
|
||||
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 Mode and Approach
|
||||
|
||||
For each concept, specify:
|
||||
- **Primary animation mode**: manim / remotion / ai_video / diagram_stills / mixed
|
||||
- **Why this mode**: grounded in technique research from the brief
|
||||
- **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?
|
||||
|
||||
#### 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 mode
|
||||
- [ ] No two concepts use the same narrative structure
|
||||
- [ ] At least one concept is achievable with free/local tools only
|
||||
- [ ] At least one concept leverages the most surprising data point
|
||||
- [ ] Each concept's animation mode is grounded in technique research
|
||||
|
||||
### 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"
|
||||
|
||||
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
|
||||
|
||||
- **Ignoring animation mode feasibility**: If Manim isn't installed, don't propose a Manim-based concept. Design around constraints.
|
||||
- **Three versions of the same concept with different titles**: Structural diversity means different animation modes, different narrative structures, different hooks.
|
||||
- **Not leveraging free tools**: Animation has a huge cost advantage — Manim, Remotion, 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.
|
||||
@@ -0,0 +1,45 @@
|
||||
# Publish Director - Animation Pipeline
|
||||
|
||||
## When To Use
|
||||
|
||||
Package the animation so the metadata, thumbnail concept, and platform framing reflect the actual visual system of the project.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Layer | Resource | Purpose |
|
||||
|-------|----------|---------|
|
||||
| Schema | `schemas/artifacts/publish_log.schema.json` | Artifact validation |
|
||||
| Prior artifacts | `state.artifacts["compose"]["render_report"]`, `state.artifacts["idea"]["brief"]`, `state.artifacts["script"]["script"]` | Final outputs and topic framing |
|
||||
| Playbook | Active style playbook | Visual naming consistency |
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Match Packaging To The Animation Mode
|
||||
|
||||
Examples:
|
||||
|
||||
- diagram-heavy videos should look structured and legible,
|
||||
- kinetic-type pieces should package around strong copy,
|
||||
- illustrative animation should package around hero imagery.
|
||||
|
||||
### 2. Preserve Visual-System Truth
|
||||
|
||||
Store in `publish_log.metadata`:
|
||||
|
||||
- `animation_mode`
|
||||
- `hero_frame_notes`
|
||||
- `thumbnail_concept`
|
||||
- `platform_notes`
|
||||
|
||||
### 3. Quality Gate
|
||||
|
||||
- metadata fits the actual animation mode,
|
||||
- thumbnail concept matches the final visual system,
|
||||
- exports are labeled by purpose and platform,
|
||||
- the package is usable without extra manual work.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- Writing generic metadata that ignores the animation style.
|
||||
- Creating a thumbnail concept unrelated to the final frames.
|
||||
- Mixing platform variants without clear labels.
|
||||
@@ -0,0 +1,256 @@
|
||||
# Research Director — Animation Pipeline
|
||||
|
||||
## When to Use
|
||||
|
||||
You are the **Research Director** for a generated animation video. You are the first stage in the pipeline — before any creative decisions, before any script, before any money is spent. Your job is to **deeply research the topic AND the animation approach** using web search and produce a `research_brief` artifact that grounds the entire video in real data, real pedagogy, and proven visual techniques.
|
||||
|
||||
Animation videos differ from general explainers: the research must cover both **what to explain** (topic) and **how to animate it** (technique). A math-animation video about eigenvalues needs different visual research than a kinetic-typography brand video.
|
||||
|
||||
**You do NOT make creative decisions.** You gather raw material. The Proposal Director downstream will use your findings to craft concept options with animation-mode recommendations.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Layer | Resource | Purpose |
|
||||
|-------|----------|---------|
|
||||
| Schema | `schemas/artifacts/research_brief.schema.json` | Artifact validation |
|
||||
| User input | Topic, audience hint, animation hint | Research scope |
|
||||
| Tools | Web search, web fetch | Research execution |
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Scope the Research
|
||||
|
||||
Before searching anything, establish boundaries:
|
||||
|
||||
- **Topic**: What is the core subject? Extract from user input.
|
||||
- **Audience hint**: Did the user mention who this is for? (developers, students, general public, professionals)
|
||||
- **Animation hint**: Did the user mention an animation style? (math animation, motion graphics, kinetic typography, diagram-led, illustrative)
|
||||
- **Platform hint**: Did the user mention where this will go? (YouTube, TikTok, LinkedIn, classroom)
|
||||
- **Depth**: Is this a well-known topic or niche?
|
||||
|
||||
If the user's request is a single phrase like "make a math animation about eigenvalues," that's fine — you have enough to research. Do NOT ask clarifying questions at this stage.
|
||||
|
||||
### Step 2: Content Landscape Scan
|
||||
|
||||
**Goal:** Understand what already exists so we can find gaps.
|
||||
|
||||
```
|
||||
SEARCH BATCH 1 — Landscape (run all in parallel)
|
||||
|
||||
Q1: "[topic] animation" site:youtube.com
|
||||
→ Find: Existing animated explainers. Note animation styles used, view counts, quality.
|
||||
|
||||
Q2: "[topic]" (animation OR "motion graphics" OR "animated explainer") -site:youtube.com
|
||||
→ Find: Articles, tutorials, and write-ups about animating this topic.
|
||||
|
||||
Q3: "[topic] [current month] [current year]"
|
||||
→ Find: The freshest content. What's being published RIGHT NOW?
|
||||
|
||||
Q4: "[topic]" (manim OR "3blue1brown" OR "motion design" OR "animated diagram")
|
||||
→ Find: Programmatic or technical animation approaches to this topic.
|
||||
```
|
||||
|
||||
**Parse results for:**
|
||||
- Which animation styles have been used for this topic (and which haven't)
|
||||
- Quality benchmarks — what do the best animations of this topic look like?
|
||||
- Gaps — which visual approaches haven't been tried?
|
||||
- Whether programmatic animation (Manim) has been used for this topic before
|
||||
|
||||
Record at least 3 entries in `landscape.existing_content` with specific titles, sources, and gap analysis.
|
||||
|
||||
### Step 3: Trending Pulse
|
||||
|
||||
**Goal:** Find what's happening RIGHT NOW — news, debates, discoveries.
|
||||
|
||||
```
|
||||
SEARCH BATCH 2 — Trending (run all in parallel)
|
||||
|
||||
Q5: "[topic]" (announcement OR discovery OR update OR breakthrough) after:[current year]-01-01
|
||||
→ Find: Recent events that make this topic timely.
|
||||
|
||||
Q6: "[topic]" site:reddit.com after:[6 months ago]
|
||||
→ Find: Active community discussions, pain points.
|
||||
|
||||
Q7: "[topic]" site:news.ycombinator.com
|
||||
→ Find: Technical audience opinions and analysis.
|
||||
|
||||
Q8: "why is [topic]" (trending OR important OR everywhere) [current year]
|
||||
→ Find: Meta-commentary on why people care right now.
|
||||
```
|
||||
|
||||
If no trending signal exists, note `timeliness_window: "evergreen"` and move on.
|
||||
|
||||
### Step 4: Data and Evidence Gathering
|
||||
|
||||
**Goal:** Find specific, citable facts that will anchor the script AND drive visual moments.
|
||||
|
||||
```
|
||||
SEARCH BATCH 3 — Data (run all in parallel)
|
||||
|
||||
Q9: "[topic]" statistics [current year]
|
||||
→ Find: Hard numbers — adoption rates, performance benchmarks, measurements.
|
||||
|
||||
Q10: "[topic]" (study OR research OR survey) [current year - 1] OR [current year]
|
||||
→ Find: Academic or industry research.
|
||||
|
||||
Q11: "[topic]" "surprisingly" OR "counterintuitively" OR "most people don't know"
|
||||
→ Find: Surprising facts — these become visual hooks.
|
||||
|
||||
Q12: "[topic]" (comparison OR benchmark OR "vs") data
|
||||
→ Find: Comparative data that becomes animated stat cards or side-by-side visuals.
|
||||
```
|
||||
|
||||
**For each data point, record:**
|
||||
- The specific claim (precise, not vague)
|
||||
- Source URL and source name
|
||||
- Credibility rating: `primary_source`, `secondary_source`, `anecdotal`
|
||||
- Surprise factor: expected or counterintuitive?
|
||||
- **Visual potential**: Can this be animated? (e.g., "73% → 23%" is a great shrinking bar chart moment; "it's important" is not animatable)
|
||||
|
||||
**Minimum: 3 data points. Target: 5-8.**
|
||||
|
||||
### Step 5: Audience Mining
|
||||
|
||||
**Goal:** Understand what real people ask, believe, and get wrong.
|
||||
|
||||
```
|
||||
SEARCH BATCH 4 — Audience (run all in parallel)
|
||||
|
||||
Q13: "[topic]" site:reddit.com "help" OR "confused" OR "why does" OR "ELI5"
|
||||
→ Find: Real questions from real people.
|
||||
|
||||
Q14: "[topic]" site:quora.com OR site:stackoverflow.com
|
||||
→ Find: Structured Q&A — what do beginners ask?
|
||||
|
||||
Q15: "[topic]" "common mistakes" OR "myths" OR "misconceptions"
|
||||
→ Find: What people get wrong — animation can powerfully show myth vs reality.
|
||||
|
||||
Q16: "[topic]" "wish I knew" OR "before you start" OR "nobody tells you"
|
||||
→ Find: Insider knowledge.
|
||||
```
|
||||
|
||||
**Parse results for:**
|
||||
- Top 5+ real questions
|
||||
- Common misconceptions (great for "wrong way → right way" animation transitions)
|
||||
- Knowledge level of the target audience
|
||||
|
||||
### Step 6: Animation Technique Research (ANIMATION-SPECIFIC)
|
||||
|
||||
**Goal:** Research how to best ANIMATE this topic — what visual techniques work.
|
||||
|
||||
This step is what makes the animation research-director different from the explainer version.
|
||||
|
||||
```
|
||||
SEARCH BATCH 5 — Animation Techniques (run all in parallel)
|
||||
|
||||
Q17: "[topic]" (visualization OR "visual explanation" OR infographic OR diagram)
|
||||
→ Find: How others have visualized this concept.
|
||||
|
||||
Q18: "[topic category]" animation technique (motion graphics OR manim OR "after effects")
|
||||
→ Find: Specific animation techniques used for this kind of content.
|
||||
|
||||
Q19: "[topic]" "step by step" OR "how it works" visual
|
||||
→ Find: Sequential visual breakdowns — inform scene progression.
|
||||
|
||||
Q20: "animate [topic-related-process]" OR "[topic] animation tutorial"
|
||||
→ Find: Technical approaches to animating this concept.
|
||||
```
|
||||
|
||||
**For each technique found, record:**
|
||||
- What the technique is (e.g., "progressive diagram build", "morph between states", "particle simulation")
|
||||
- Where it was used (source URL)
|
||||
- Which animation mode it maps to: `manim`, `remotion`, `motion_graphics`, `ai_video`, `illustrative`
|
||||
- Complexity: `simple` (reusable components), `moderate` (custom but repeatable), `complex` (bespoke per scene)
|
||||
- Whether it's been done before for this topic (novelty signal)
|
||||
|
||||
**Minimum: 2 technique references. Target: 4-6.**
|
||||
|
||||
### Step 7: Mathematical/Technical Accuracy Check (If Applicable)
|
||||
|
||||
**For math-animation, science, or technical topics:**
|
||||
|
||||
```
|
||||
Q21: "[topic]" (formal definition OR mathematical OR "technically")
|
||||
→ Find: The precise technical definition — animation must not oversimplify to the point of being wrong.
|
||||
|
||||
Q22: "[topic]" "common error" OR "often confused with" OR "technically incorrect"
|
||||
→ Find: Technical pitfalls that the animation must avoid.
|
||||
```
|
||||
|
||||
**Record:**
|
||||
- The precise definition or formula
|
||||
- Common simplification errors
|
||||
- What level of simplification is acceptable for the target audience
|
||||
- Any visual metaphors that are technically misleading (e.g., "electrons orbiting like planets" is wrong)
|
||||
|
||||
If the topic is not math/science, skip this step.
|
||||
|
||||
### Step 8: Angle Synthesis
|
||||
|
||||
Using everything from Steps 2-7, identify at least 3 genuinely different angle candidates.
|
||||
|
||||
For each angle, specify:
|
||||
|
||||
| Field | What | Quality Bar |
|
||||
|-------|------|-------------|
|
||||
| `name` | Short title (5-8 words) | Specific, not generic |
|
||||
| `hook` | One-sentence grabber | Must create an information gap or surprise |
|
||||
| `type` | `trending`, `evergreen`, `contrarian`, `narrative`, `data_driven` | Categorize honestly |
|
||||
| `why_now` | Why this angle is compelling right now | Must cite specific research findings |
|
||||
| `grounded_in` | Which data points or audience insights support it | Cross-reference your findings |
|
||||
| `animation_fit` | Which animation mode(s) best serve this angle | Must reference technique research from Step 6 |
|
||||
|
||||
**Angle diversity checklist:**
|
||||
- [ ] At least one angle leverages a surprising data point or visual
|
||||
- [ ] At least one angle is evergreen
|
||||
- [ ] At least one angle maps to a different animation mode than the others
|
||||
- [ ] No two angles use the same hook structure
|
||||
- [ ] Each angle's `animation_fit` references specific technique research
|
||||
|
||||
### Step 9: Source Bibliography
|
||||
|
||||
Compile all URLs used, organized by section. Minimum 5 sources.
|
||||
|
||||
**Source quality rules:**
|
||||
- Primary sources > secondary > anecdotal
|
||||
- At least 2 primary sources
|
||||
- Every data_point must have a source_url
|
||||
- Flag sources older than 2 years
|
||||
|
||||
### Step 10: Assemble and Submit
|
||||
|
||||
Build the `research_brief` artifact per the schema. Include:
|
||||
|
||||
1. `research_summary` — one paragraph: the most important insight AND the most promising animation approach.
|
||||
2. All sections from Steps 2-9
|
||||
|
||||
Validate against `schemas/artifacts/research_brief.schema.json` before submitting.
|
||||
|
||||
## Quality Bar
|
||||
|
||||
| Criterion | Minimum | Target |
|
||||
|-----------|---------|--------|
|
||||
| Existing content surveyed | 3 pieces | 5-8 pieces |
|
||||
| Data points with sources | 3 | 5-8 |
|
||||
| Audience questions sourced | 3 | 5-10 |
|
||||
| Animation techniques researched | 2 | 4-6 |
|
||||
| Angle candidates | 3 | 4-5 |
|
||||
| Total sources cited | 5 | 10-15 |
|
||||
| Searches executed | 12 | 18-22 |
|
||||
|
||||
## Execution Constraints
|
||||
|
||||
| Constraint | Value | Why |
|
||||
|------------|-------|-----|
|
||||
| Max time on research | 3-5 minutes | Diminishing returns |
|
||||
| Max searches | 25 | Prevent rabbit holes |
|
||||
| Min searches | 12 | Ensure coverage |
|
||||
| No paid tools | — | Research uses web search only — zero cost |
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Skipping animation technique research**: The explainer research-director doesn't need this, but animation does. The `animation_fit` field in angles is mandatory.
|
||||
- **Ignoring mathematical accuracy**: For math topics, the research MUST include the precise definition. An animation that looks cool but teaches wrong math is worse than no animation.
|
||||
- **Only searching topic, not visualization**: If the topic is "Fourier transforms," you must search both "Fourier transforms" AND "Fourier transform visualization/animation." The technique research is half the value.
|
||||
- **Treating all animation as one category**: Manim, Remotion, AI video, and motion graphics are fundamentally different tools with different strengths. Research should inform which mode fits the topic.
|
||||
- **Recording vague visual references**: "A nice animation" is not useful. "Progressive circle-to-wave morph showing sine decomposition (3Blue1Brown style, Manim)" is useful.
|
||||
@@ -0,0 +1,65 @@
|
||||
# Scene Director - Animation Pipeline
|
||||
|
||||
## When To Use
|
||||
|
||||
You are converting the script into a feasible animation plan. This is the stage that decides whether the project feels designed or chaotic.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Layer | Resource | Purpose |
|
||||
|-------|----------|---------|
|
||||
| Schema | `schemas/artifacts/scene_plan.schema.json` | Artifact validation |
|
||||
| Prior artifacts | `state.artifacts["script"]["script"]`, `state.artifacts["idea"]["brief"]` | Beat map and tool path |
|
||||
| Playbook | Active style playbook | Palette, typography, motion consistency |
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Make An Animatic-Minded Plan
|
||||
|
||||
For each scene, define:
|
||||
|
||||
- what appears first,
|
||||
- what changes,
|
||||
- what is held,
|
||||
- how the scene exits.
|
||||
|
||||
### 2. Limit Transition Families
|
||||
|
||||
Choose a small set of transition meanings:
|
||||
|
||||
- cut,
|
||||
- fade,
|
||||
- slide,
|
||||
- transform.
|
||||
|
||||
### 3. Match Scene Type To Tool Path
|
||||
|
||||
Use:
|
||||
|
||||
- `diagram` scenes for structured explanation,
|
||||
- `animation` scenes for motion-first sequences,
|
||||
- `text_card` for clean high-impact copy moments,
|
||||
- `generated` only where needed.
|
||||
|
||||
### 4. Use Metadata For Timing Rules
|
||||
|
||||
Recommended metadata keys:
|
||||
|
||||
- `animatic_rules`
|
||||
- `transition_rules`
|
||||
- `hold_rules`
|
||||
- `tool_path_map`
|
||||
- `reusable_motifs`
|
||||
|
||||
### 5. Quality Gate
|
||||
|
||||
- every scene has a clear timing intent,
|
||||
- the transition system is limited and meaningful,
|
||||
- the tool path is explicit,
|
||||
- the sequence feels like one designed system.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- Adding a new transition idea in every scene.
|
||||
- Planning scenes that have no realistic production path.
|
||||
- Overanimating text-heavy scenes.
|
||||
@@ -0,0 +1,117 @@
|
||||
# Script Director — Animation Pipeline
|
||||
|
||||
## When to Use
|
||||
|
||||
This stage turns the approved proposal into animation-ready beats. The script must leave room for motion, staging, and hold time — and must integrate the research findings and respect the selected animation mode.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Layer | Resource | Purpose |
|
||||
|-------|----------|---------|
|
||||
| Schema | `schemas/artifacts/script.schema.json` | Artifact validation |
|
||||
| Prior artifact | `proposal_packet` from Proposal Director | Selected concept, animation mode, target duration, reuse strategy |
|
||||
| Optional artifact | `research_brief` from Research Director | Data points, audience insights, accuracy constraints |
|
||||
| Tools | `transcriber` | Optional source transcript support |
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Absorb the Proposal
|
||||
|
||||
Read the `proposal_packet.selected_concept` thoroughly. Extract:
|
||||
|
||||
- **Title and hook** — the opening must deliver on this promise
|
||||
- **Animation mode** — `manim`, `remotion`, `ai_video`, `diagram_stills`, or `mixed`. This constrains how you write.
|
||||
- **Narrative structure** — `progressive_build`, `myth_busting`, `journey`, etc. Follow it.
|
||||
- **Target duration** — word budget = target_seconds × 2.5 words/sec (at 150 WPM)
|
||||
- **Key points** — from `selected_concept.key_points`
|
||||
- **Reuse strategy** — recurring motifs mean recurring script structures
|
||||
|
||||
If `research_brief` is available, also extract:
|
||||
- **Data points** — weave specific, sourced facts into the narration (not vague claims)
|
||||
- **Audience misconceptions** — address them directly in the script
|
||||
- **Mathematical accuracy notes** — constraints on what can and cannot be simplified
|
||||
|
||||
### 2. Write in Animation Beats
|
||||
|
||||
Each section should express ONE clear visual idea:
|
||||
|
||||
- **Statement** — introduce a concept (entrance animation)
|
||||
- **Demonstration** — show it working (the main animation)
|
||||
- **Transformation** — morph from one state to another (transition)
|
||||
- **Comparison** — show two things side by side (split screen or sequential)
|
||||
- **Conclusion** — land the insight (hold + emphasis)
|
||||
|
||||
**Animation mode affects writing style:**
|
||||
|
||||
| Mode | Writing Style |
|
||||
|------|---------------|
|
||||
| Manim | Precise, mathematical. Each beat maps to a specific geometric transformation. Write narration that describes what's being shown. |
|
||||
| Remotion | Data-driven, punchy. Each beat maps to a chart/component animation. Narration complements the visual data. |
|
||||
| AI Video | Descriptive, evocative. Each beat describes a scene the AI should generate. Narration adds context the visual can't convey. |
|
||||
| Diagram Stills | Explanatory, progressive. Each beat adds a layer to a building diagram. Narration walks through the build. |
|
||||
| Mixed | Varies per section — tag each section's mode in metadata. |
|
||||
|
||||
### 3. Keep On-Screen Text Tight
|
||||
|
||||
Animation-heavy pieces fail when the viewer has to read too much while motion is happening:
|
||||
|
||||
- **Max 8 words** for on-screen titles
|
||||
- **Max 15 words** for on-screen descriptions
|
||||
- Prefer phrases over sentences
|
||||
- Prefer numbers and labels over paragraphs
|
||||
- Mathematical notation is fine — it IS the content in math-animation mode
|
||||
|
||||
### 4. Leave Room for Visual Holds
|
||||
|
||||
Do NOT fill every second with new information. The scene plan will need time for:
|
||||
|
||||
- **Entrances** (0.5-1s): objects appearing on screen
|
||||
- **Reveals** (1-2s): progressive disclosure of complexity
|
||||
- **Holds** (1-3s): letting the viewer absorb what they see
|
||||
- **Exits** (0.5s): clearing the stage for the next beat
|
||||
|
||||
**Rule of thumb:** For every 10 seconds of narration, budget 3-4 seconds of visual breathing room. A 90-second video should have ~60-65 seconds of narration and ~25-30 seconds of visual holds.
|
||||
|
||||
### 5. Use Metadata for Motion Intent
|
||||
|
||||
Recommended metadata keys per section:
|
||||
|
||||
- `beat_type`: statement / demonstration / transformation / comparison / conclusion
|
||||
- `animation_mode`: which mode this section uses (important for mixed mode)
|
||||
- `text_constraints`: max words for on-screen text in this section
|
||||
- `narration_plan`: how narration relates to visual (describes / complements / silent)
|
||||
- `visual_priority`: what the viewer should focus on (the animation, the text, the data)
|
||||
- `hold_time_seconds`: minimum visual hold time after this section's content
|
||||
- `data_source`: if this section uses a research data point, reference it
|
||||
|
||||
### 6. Research Integration
|
||||
|
||||
If a `research_brief` is available:
|
||||
|
||||
- Use at least 2 data points from the research in the narration
|
||||
- Ground the hook in the research's most surprising finding
|
||||
- Address at least 1 audience misconception if the narrative structure supports it
|
||||
- Cite sources naturally ("According to [source]..." or "A [year] study found...")
|
||||
- Do NOT invent statistics — only use what the research found
|
||||
|
||||
### 7. Quality Gate
|
||||
|
||||
Before submitting the script, verify:
|
||||
|
||||
- [ ] Every section supports ONE strong visual idea
|
||||
- [ ] On-screen text is concise (phrases, not paragraphs)
|
||||
- [ ] Timing is animation-friendly (holds budgeted)
|
||||
- [ ] Word count is within ±10% of target duration
|
||||
- [ ] Animation mode is respected in writing style
|
||||
- [ ] Research data points are integrated (if research_brief available)
|
||||
- [ ] Mathematical accuracy is maintained (if applicable)
|
||||
- [ ] Later stages can map scenes cleanly from this script
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Writing too many ideas into one section.** One beat = one visual idea.
|
||||
- **Treating captions and on-screen text as the same thing.** Subtitles are narration transcribed. On-screen text is designed content that's part of the animation.
|
||||
- **Forgetting that motion needs pause and emphasis.** Budget hold times.
|
||||
- **Ignoring the animation mode.** A Manim script reads differently than an AI video script.
|
||||
- **Writing research-less scripts when a research_brief exists.** If the research found surprising data, use it. Generic scripts waste the research investment.
|
||||
- **Oversimplifying math to the point of being wrong.** Check the research brief's accuracy notes.
|
||||
Reference in New Issue
Block a user