directing-story-scenes

name	directing-story-scenes
description	Directs each story scene into 3–5 comic panels with prose, dialogue, narration beats, and pacing, and is used when the Scene Director converts anchors into playable scenes.

Turns each anchor into a cinematic motion-comic scene with clear emotional progression and clean panel pacing. Uses Gemini's interleaved output to generate narration text and panel illustrations together in a single API call.

Use this skill when

• A story anchor is approved and ready to become a playable scene.
• The Scene Director must write prose, dialogue, narration beats, and panel breakdowns.
• The frontend needs renderable 3–5 panel scene content.
• The system needs story-first scene design before visuals and audio are added.
• The hackathon's interleaved output requirement must be satisfied (Creative Storyteller category).

Interleaved Output (Mandatory)

The Scene Director is the primary agent that satisfies the hackathon's interleaved output requirement. It calls a Gemini image-capable model (gemini-3.1-flash-image-preview) with responseModalities: ['TEXT', 'IMAGE']. In a single API call, Gemini returns narration text and AI-generated panel illustrations alternating in the response parts:

# The Scene Director makes ONE Gemini call per scene that returns:
response.parts = [
    Part(text="Panel 1 narration..."),
    Part(inline_data=<panel 1 illustration>),
    Part(text="Panel 2 narration..."),
    Part(inline_data=<panel 2 illustration>),
    # ... up to 5 panels
]

The backend parses these parts, separates text from images, and packages them into the typed scene JSON. The Visual Motion Director provides style/composition guidance as INPUT to this call (style bible, character descriptions), but the actual image generation happens here inside the Scene Director's Gemini call.

Capabilities

• Writes scenes as 3–5 sequential comic panels.
• Generates panel illustrations inline via Gemini interleaved output (text + image in one call).
• Balances narration, dialogue, silence, and visual storytelling.
• Keeps the emotional focus clear in each panel.
• Builds scenes that work with or without voiceover.
• Writes motion direction per panel — what should move in the 2-3 second GIF (character actions, environmental motion, camera movement).
• Ends scenes on a strong beat, especially before choices.
• Produces typed JSON the visual and audio agents can consume directly.
• Receives style bible and character reference descriptions from the Visual Motion Director as input context.

Workflow

1. Read the story bible and current state. Understand the scene purpose before writing.
2. Decide the scene beat. Each scene should do one main job:
   • invite
   • test
   • reveal
   • confront
   • resolve
3. Plan 3–5 panels.
   • Panel 1: orient mood and setting
   • Panels 2–4: escalate conflict or deepen reflection
   • Final panel: land the beat or present the choice
4. Write concise prose and dialogue. Keep lines speakable for TTS and readable on screen.
5. Add narration beats. These should support, not repeat, what the panel already shows.
6. Write motion direction per panel. Describe what should move in the 2-3 second GIF — character actions (turning, reaching, reacting), environmental motion (wind, flickering light), and camera movement (zoom, pan) when it serves the story. Think like a cinematographer.
7. Control pacing. Alternate motion-heavy beats with spoken or silent beats.
8. Prepare for multimodal use. Each panel should include enough meaning to survive GIF or audio failure.
9. Return typed JSON.

Recommended panel fields

• panel_id
• purpose
• visual_beat
• motion_direction (what moves in the GIF — character action, environment, camera)
• dialogue
• narration
• emotion
• estimated_duration_sec

Example

{
  "scene_id": "scene_A3",
  "anchor": "A3",
  "panels": [
    {
      "panel_id": "p1",
      "purpose": "arrival",
      "visual_beat": "The courier stands in a hall of sealed letters that whisper his own thoughts.",
      "motion_direction": "Letters on shelves subtly flutter and glow. Faint wisps of light drift between the shelves. Camera holds steady on the courier's silhouette.",
      "dialogue": [],
      "narration": "Some rooms do not echo. They answer.",
      "emotion": "unease",
      "estimated_duration_sec": 4
    },
    {
      "panel_id": "p2",
      "purpose": "revelation",
      "visual_beat": "One letter opens by itself, showing the promise he once made to silence himself.",
      "motion_direction": "The letter slowly unfolds, casting warm golden light across the courier's face. His eyes widen. Slow push-in on the letter.",
      "dialogue": ["'You wrote the law you now obey.'"],
      "narration": "The trap had not been built around him. It had been built from him.",
      "emotion": "shock",
      "estimated_duration_sec": 5
    }
  ]
}

Scene guardrails

• Do not exceed 5 panels unless there is a very strong reason.
• Do not write overwritten prose.
• Do not explain what the image already communicates.
• Do not lose the emotional mirror to the user's original issue.

Project references

• AGENTS.md — 3–5 comic panels, dark immersive tone, graceful degradation rules.
• docs/PRD.md — per-scene multimodal requirements, panel pacing, voiceover and timing expectations.
• docs/roadmap.md — MVP scene delivery uses AI-generated GIFs with real motion, falling back to static images.