Implementation spec: governance, decision intelligence, theme system, and E2E bug fixes
Implements the 2026-04-02 transformation spec (Phases 1-8) and fixes all critical bugs found during 5-pipeline E2E testing. Governance & Decision Intelligence: - Pipeline-specific stage order in checkpoint (replaces global STAGES list) - Provider scoring engine (lib/scoring.py) with 7-dimension weighted ranking - Decision log artifact enforced at proposal/idea stage across all 10 pipelines - Delivery promise classifier prevents silent motion-to-still downgrades - Structured shot language in scene_plan schema (camera, lens, lighting, DOF) - Variation checker and slideshow risk scorer block samey output before render - Creative intake, capability extension, and creative-intake meta skills - Final self-review artifact with 5 mandatory checks before presenting output - Source media review contract for user-supplied footage Render & Theme System: - Remotion AnimatedBackground now derives colors from playbook (no more hardcoded dark blue fintech gradient on every video) - video_compose builds custom ThemeConfig from playbook YAML colors/fonts — custom playbooks flow through to Remotion automatically - Explainer component wires theme to all child components (charts, cards, etc.) - resolveAsset() handles absolute paths on Windows/Unix via file:// URIs - RENDERER_FAMILY_MAP synced with actual Remotion compositions Critical Bug Fixes: - Windows npx subprocess: run_command() resolves .cmd wrappers via shutil.which() - Silent renderer downgrade: Remotion failure now returns explicit error with options instead of silently falling back to FFmpeg - .env inline comment parsing strips trailing # comments from API keys - concat_path UnboundLocalError in video_compose finally block - audio_mixer and showcase_card capture=True kwarg bug - Selector estimate_cost() calls fixed (_select_tool -> _select_best_tool) - asset_manifest schema expanded with provider, license, subtype fields - screen-demo subtitle_gen moved from required to optional tools - Duration drift detection in post-render final review (>25% warns)
This commit is contained in:
calesthio
@@ -11,7 +11,7 @@ This is where plans become real files. A missing or low-quality asset will torpe
|
||||
| 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"]` | What to produce |
|
||||
| Prior artifacts | `state.artifacts["scene_plan"]["scene_plan"]`, `state.artifacts["script"]["script"]`, `state.artifacts["proposal"]["proposal_packet"]` | What to produce |
|
||||
| Playbook | Active style playbook | Image prompts, diagram style, audio preferences |
|
||||
| Tools | `tts_selector`, `image_selector`, `video_selector`, `diagram_gen`, `code_snippet`, `music_gen` — selectors auto-discover all available providers from the registry | Generation capabilities |
|
||||
| Cost tracker | `tools/cost_tracker.py` | Budget governance |
|
||||
@@ -188,6 +188,17 @@ If any dimension scores below 3, fix before proceeding.
|
||||
|
||||
Validate the asset_manifest against the schema and persist via checkpoint.
|
||||
|
||||
### Mid-Production Fact Verification
|
||||
|
||||
If you encounter uncertainty during asset generation:
|
||||
- Use `web_search` to verify visual accuracy of subjects (e.g. what does this building actually look like?)
|
||||
- Use `web_search` to find reference images before generating illustrations
|
||||
- Log verification in the decision log: `category="visual_accuracy_check"`
|
||||
|
||||
Visual accuracy matters. If the script mentions a specific place, person, or object,
|
||||
verify what it actually looks like before generating images. Don't rely on
|
||||
the AI model's training data — it may be wrong or outdated.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Generating before checking budget**: Always estimate total cost first. A 60-second video with 15 images can burn $3+ quickly.
|
||||
@@ -195,3 +206,22 @@ Validate the asset_manifest against the schema and persist via checkpoint.
|
||||
- **Ignoring narration timing**: If TTS produces 12s of audio for a 10s section, the edit phase will struggle. Check durations.
|
||||
- **Missing pronunciation guide**: "PostgreSQL" or "Kubernetes" will be mispronounced without explicit guidance.
|
||||
- **One retry then give up**: If an image doesn't match, refine the prompt specifically — don't just retry the same prompt.
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
@@ -58,6 +58,21 @@ This directly affects what you can promise in the production plan. **Do not prop
|
||||
|
||||
**Setup offers:** If critical tools are UNAVAILABLE but fixable with a simple configuration, read each tool's `install_instructions` from the registry and offer the user setup help before designing around the limitation. See AGENT_GUIDE.md "Provider Menu" protocol for the approach. Group related tools that share the same env var dependency.
|
||||
|
||||
### Step 2c: Mood Board (Before Concepts)
|
||||
|
||||
Before developing full concepts, present a quick mood board to catch direction mismatches early:
|
||||
|
||||
- **3-5 reference images** (from web search, stock, or quick generations)
|
||||
- **Color palette direction** (2-3 options derived from playbook candidates)
|
||||
- **Tone references** ("Think: Kurzgesagt meets Vice" or "Think: Apple product video meets TED-Ed")
|
||||
- **1-2 music mood references** (genre + energy level, not specific tracks)
|
||||
|
||||
Ask: **"Does this FEEL like what you're imagining? Any of these off-track?"**
|
||||
|
||||
This is cheaper than generating 3 full concepts and catches direction mismatches before they become expensive. If the user says "too corporate" or "more playful," you've saved an entire concept round.
|
||||
|
||||
If the user confirms the direction, proceed. If they redirect, adjust your concept design to match.
|
||||
|
||||
### Step 3: Design Concept Options
|
||||
|
||||
Build **at least 3 genuinely different concepts.** Start from the `angles_discovered` in the research brief, but elevate them into full production concepts.
|
||||
@@ -137,32 +152,89 @@ Set realistic duration based on platform and content depth:
|
||||
| YouTube | 60-180s | 150-450 words |
|
||||
| LinkedIn | 60-120s | 150-300 words |
|
||||
|
||||
#### 3e: Concept Diversity Check
|
||||
#### 3e: When to Break the Patterns
|
||||
|
||||
Before finalizing, verify diversity:
|
||||
The hook patterns and narrative structures above are starting points, not templates. Here are signs you should invent something new:
|
||||
|
||||
**Signs your concepts are cosmetically diverse but conceptually identical:**
|
||||
- All three hooks create the same type of curiosity gap
|
||||
- Swapping the hooks between concepts would barely change anything
|
||||
- All three would produce roughly the same script if you wrote them blind
|
||||
- The visual approaches are "dark vs light vs colorful" but the content structure is identical
|
||||
|
||||
**Anti-formula rule:** Write the hook in your own words first. Then check if a pattern helps sharpen it. If you start FROM the pattern, you'll produce pattern-shaped content instead of research-shaped content.
|
||||
|
||||
**When to deviate from the 6 hook templates:**
|
||||
- The research reveals a unique framing that doesn't fit any template
|
||||
- The audience is sophisticated enough that template hooks feel condescending
|
||||
- The topic's best angle is emotional rather than informational
|
||||
- You found a specific quote, anecdote, or event that IS the hook
|
||||
|
||||
#### 3f: Concept Diversity Gate
|
||||
|
||||
This is two checks, not one:
|
||||
|
||||
**Structural diversity (necessary but not sufficient):**
|
||||
- [ ] No two concepts use the same narrative structure
|
||||
- [ ] No two concepts use the same hook pattern
|
||||
- [ ] At least one concept targets a different audience segment
|
||||
- [ ] At least one concept leverages the most surprising data point
|
||||
- [ ] At least one concept addresses the biggest content gap found
|
||||
- [ ] Each concept's `grounded_in` references different research findings
|
||||
|
||||
### Step 4: Present Concepts and Get Selection
|
||||
**Conceptual diversity (the actual test):**
|
||||
- [ ] Each concept offers a genuinely different INSIGHT, not just a different title for the same insight
|
||||
- [ ] At least one concept takes a creative risk (unusual structure, unexpected angle, provocative framing)
|
||||
- [ ] If you removed the titles and hooks, the concepts would still be distinguishable by their content structure
|
||||
- [ ] The concepts are NOT interchangeable — each serves a different audience need or curiosity
|
||||
|
||||
Present all concepts clearly to the user. For each concept, show:
|
||||
If your concepts fail the conceptual diversity test, go back to the research brief. The problem is usually that you're working from one angle and varying the surface, instead of working from different angles entirely.
|
||||
|
||||
#### 3g: Playbook Violation Budget
|
||||
|
||||
Up to 20% of scenes in the final video may intentionally deviate from the playbook for creative impact. When presenting concepts, note which moments might benefit from visual surprise (a color shift, a different typography treatment, an unexpected transition). These deviations must be logged as `playbook_override` decisions in the decision log.
|
||||
|
||||
#### 3h: Voice Selection
|
||||
|
||||
Surface the voice/TTS decision at proposal time:
|
||||
- What voice provider and voice ID will be used
|
||||
- Why this voice fits the concept's tone
|
||||
- Cost implications
|
||||
- Whether voice variation is appropriate for hero moments
|
||||
|
||||
### Step 4: Progressive Reveal and Concept Selection
|
||||
|
||||
Don't dump the full proposal at once. Build understanding step by step:
|
||||
|
||||
**4a. Research summary** (2-3 sentences): "Here's what I found..."
|
||||
→ User reacts, course-corrects if needed.
|
||||
|
||||
**4b. Mood board** (from Step 2c — already presented)
|
||||
→ User confirms feel.
|
||||
|
||||
**4c. Concept options** (3+ directions):
|
||||
|
||||
For each concept, show:
|
||||
1. **Title** and **hook** — the creative pitch
|
||||
2. **Why this works** — the research backing, in one sentence
|
||||
3. **What it'll look like** — visual approach in plain language
|
||||
4. **Duration** — how long the video will be
|
||||
|
||||
**4d. Invite Mixing:**
|
||||
|
||||
After presenting concepts, always say something like:
|
||||
> "You can also mix elements — for example, Concept A's hook with Concept C's visual approach. 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, visual approach from Concept C, narrative structure from Concept B."
|
||||
|
||||
Let the user:
|
||||
- Select one as-is
|
||||
- Combine elements from multiple concepts
|
||||
- Combine elements from multiple concepts (hybrid)
|
||||
- Request modifications
|
||||
- Describe a completely different direction (in which case, use the research to strengthen it)
|
||||
|
||||
**4e. Production plan for selected concept** (tools, cost, timeline):
|
||||
→ User approves budget and approach.
|
||||
|
||||
Each step is a chance for the user to course-correct before the next step builds on it. This prevents the "I approved a proposal and then the video wasn't what I expected" failure mode.
|
||||
|
||||
Record the selection in `selected_concept` with rationale and any modifications.
|
||||
|
||||
### Step 5: Build the Production Plan
|
||||
@@ -378,3 +450,22 @@ TOTAL: $0.64 of $2.00 budget
|
||||
- Premium (Remotion): Best available TTS + 4 AI images + 4 Remotion animated scenes = $0.48
|
||||
- Standard: Mid-tier TTS + images = $0.40
|
||||
- Free: Local TTS + Remotion component scenes only = $0.00 (no images, pure motion graphics)
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
@@ -11,7 +11,7 @@ This is where a great video reaches its audience. Without proper metadata and pa
|
||||
| Layer | Resource | Purpose |
|
||||
|-------|----------|---------|
|
||||
| Schema | `schemas/artifacts/publish_log.schema.json` | Artifact validation |
|
||||
| Prior artifacts | `state.artifacts["compose"]["render_report"]`, `state.artifacts["idea"]["brief"]` | Video file and original brief |
|
||||
| Prior artifacts | `state.artifacts["compose"]["render_report"]`, `state.artifacts["proposal"]["proposal_packet"]`, `state.artifacts["research"]["research_brief"]` | Video file and original proposal |
|
||||
| Playbook | Active style playbook | Visual style for thumbnail |
|
||||
|
||||
## Process
|
||||
@@ -19,14 +19,14 @@ This is where a great video reaches its audience. Without proper metadata and pa
|
||||
### Step 1: Gather Context
|
||||
|
||||
Collect everything needed for metadata:
|
||||
- **Brief**: title, hook, key points, target platform, tone
|
||||
- **Proposal packet**: title, hook, key points, target platform, tone
|
||||
- **Render report**: output path, duration, resolution
|
||||
- **Script**: section summaries for description/chapters
|
||||
|
||||
### Step 2: Generate SEO Metadata
|
||||
|
||||
**Title** (max 60 characters for YouTube):
|
||||
- Include the primary keyword from the brief
|
||||
- Include the primary keyword from the proposal packet
|
||||
- Lead with a hook or number
|
||||
- Avoid clickbait but be compelling
|
||||
- Examples: "Vector Databases Explained in 60 Seconds" > "About Vector Databases"
|
||||
@@ -39,7 +39,7 @@ Collect everything needed for metadata:
|
||||
- Links: relevant resources mentioned in the video
|
||||
|
||||
**Tags/Keywords** (platform-dependent):
|
||||
- 5-10 specific tags derived from brief's key_points
|
||||
- 5-10 specific tags derived from proposal packet's key_points
|
||||
- Mix broad and specific: "machine learning" + "vector database tutorial"
|
||||
- Include the topic, format ("explainer"), and related terms
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ This is where words become visuals. A great script with a bad scene plan produce
|
||||
| Layer | Resource | Purpose |
|
||||
|-------|----------|---------|
|
||||
| Schema | `schemas/artifacts/scene_plan.schema.json` | Artifact validation |
|
||||
| Prior artifacts | `state.artifacts["script"]["script"]`, `state.artifacts["idea"]["brief"]` | Script sections and creative brief |
|
||||
| Prior artifacts | `state.artifacts["script"]["script"]`, `state.artifacts["proposal"]["proposal_packet"]` | Script sections and proposal packet |
|
||||
| Playbook | Active style playbook | Visual language, transitions, motion rules |
|
||||
| Layer 3 | `.agents/skills/flux-best-practices/`, `.agents/skills/beautiful-mermaid/`, `.agents/skills/manim-composer/` | Image gen, diagram, animation knowledge |
|
||||
|
||||
|
||||
@@ -185,6 +185,17 @@ If any dimension scores below 3, revise before submitting.
|
||||
|
||||
Call `handle_explainer_script(state, {"script": script_json})` to validate and persist.
|
||||
|
||||
### Mid-Production Fact Verification
|
||||
|
||||
If you encounter uncertainty during script writing:
|
||||
- Use `web_search` to verify factual claims before committing them to the script
|
||||
- Use `web_search` to find reference images for visual accuracy
|
||||
- Log verification in the decision log: `category="visual_accuracy_check"`
|
||||
|
||||
Every factual claim in the script should be traceable to the `research_brief`.
|
||||
If you make a claim that isn't in the research, do additional research and
|
||||
add the source. Do not invent statistics, dates, or attributions.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Writing too many words**: The #1 failure. TTS pacing is fixed. If you write 250 words for a 60-second video, either the audio will be rushed or the video will be 100 seconds. Count your words.
|
||||
|
||||
Reference in New Issue
Block a user