---
name: storyboard
description: SUPERSEDED by Starsend Plan Pass (Stage 2) + Previz. Legacy AI Cinematographer — creative visual direction from episode scripts.
allowed-tools: Read, Write, Bash, Glob
argument-hint: "[project] ep [N] [--revise | --sketch]"
---

# /storyboard — AI Cinematographer

Analyze an episode script as a director of photography and produce creative visual direction — shot-by-shot storyboard with visual vocabulary, directorial reasoning, and optional rough sketches via ComfyUI.

## Usage

```
/storyboard [project] ep [N]              # Full storyboard from script
/storyboard [project] ep [N] --revise     # Incorporate annotations from review
/storyboard [project] ep [N] --sketch     # Generate rough viz via ComfyUI alongside storyboard
```

**Examples:**
```
/storyboard leviathan ep 1                  # Full storyboard of Episode 1
/storyboard leviathan ep 1 --revise         # Revise from annotation feedback
/storyboard leviathan ep 1 --sketch         # Storyboard + rough ComfyUI sketches
```

## What It Produces

A single JSON file at `/[project]/_pipeline/shot_plans/storyboard_ep_NNN.json` with creative visual direction.

The JSON contains:
- **Visual Vocabulary** — Episode-level palette, lighting strategy, lens philosophy, rhythm, visual rhyme
- **Characters** — Visual descriptions with reference image paths from visual_bible.md
- **Shots** — Ordered shot list with creative direction per shot:
  - Shot type, angle, movement — with **why** each choice serves the narrative
  - Framing, blocking, lighting motivation
  - Atmospheric inference, emotional coloring
  - Sketch prompts (for rough ComfyUI visualization)
  - Director notes, transition reasoning
  - Extended take flags with justification

## Parameters

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `project` | Yes | — | Project folder name |
| `ep [N]` | Yes | — | Episode number |
| `--revise` | No | — | Incorporate annotations from review session |
| `--sketch` | No | — | Generate rough ComfyUI viz alongside storyboard |

## Execution

When this skill is invoked, follow the agent protocol in `/agents/storyboard_agent.md`.

### Quick Summary

1. **Read Script as Director** — Two passes: story comprehension, then visual planning
2. **Establish Visual Vocabulary** — Dominant palette, lighting strategy, lens philosophy, rhythm, visual rhyme
3. **Break Into Shots** — Directed shots with "why" reasoning (2-7 per beat, 13-24 total)
4. **Assign Generation Approach** — Each shot gets `generation_approach`: `triptych_split_flf`, `standard_flf`, `held_frame_push`, or `held_frame_static`
5. **Write Direction Per Shot** — Framing, blocking, lighting motivation, atmosphere, emotion, transitions
6. **Write Triptych Prompts** — For every `triptych_split_flf` shot, compose the `triptych_prompt` field using the 3-panel template from `INNOVATIONS.md`. Also write `hero_frame` for the center panel.
7. **Attach Character Refs** — Pull reference images from visual_bible.md for each shot
8. **Visual Arc Check** — Does the visual language evolve? Do shots rhyme? Is rhythm intentional?
9. **Write Output** — Save `storyboard_ep_NNN.json` to `/[project]/_pipeline/shot_plans/`
10. **Report** — Summary with visual arc description

### Mandatory Validation

After writing the JSON, the agent MUST run:

```bash
python3 /tools/validate_storyboard.py \
  /[project]/_pipeline/shot_plans/storyboard_ep_NNN.json \
  /[project]/scripting/episodes/ep_NNN.md --json
```

This mechanically checks:
- All 5 beats present with assigned shots
- Every script line covered by at least one shot
- No hallucinated content in shot excerpts
- Required fields populated, valid enums, correct dimensions
- Reasonable shot distribution across beats

**Do NOT proceed until `is_valid: true`.** If invalid, run with `--prompt` for fix instructions.

### --revise Mode

1. Read existing storyboard JSON + annotations from review
2. Apply per-shot decisions: ACCEPT / REJECT / MODIFY
3. Re-run visual arc check
4. If `--sketch` also specified, re-sketch modified shots only
5. Write updated JSON

### --sketch Mode

Generate rough ComfyUI visualizations per shot alongside storyboard creation. Uses Flux 2 at low resolution (512px, 4-8 steps) for composition checks.

## Output Path

```
/[project]/_pipeline/shot_plans/storyboard_ep_NNN.json
```

The `_pipeline/shot_plans/` directory is created if it doesn't exist.

## Downstream Consumers

| Consumer | What It Reads |
|----------|---------------|
| **Shotlist Editor** (Production Console → Shotlist tab) | Full JSON — visual editing |
| **Storyboard Editor** (Production Console → Storyboard tab) | Storyboard review — annotation interface |
| **generate_storyboard_keyframes.py** | `generation_approach`, `triptych_prompt`, `hero_frame`, `first_frame`, `last_frame`, `action`, `motion_prompt` |
| **Human review** | All fields — the JSON is the source of truth for visual production |

## Shot Analysis Guidelines

| Script Element | Shot Strategy |
|----------------|---------------|
| Scene heading | New shot (WIDE or establishing) |
| Detail action (object focus) | ECU or CU |
| Character introduction | MCU or MS portrait |
| Dialogue exchange | MS two-shot or CU alternating |
| Physical action | WIDE or MS with movement |
| Emotional beat | CU or ECU on face/hands |
| Discovery/reveal | Dolly or crane movement |
| Cliffhanger image | Match treatment's visual precisely |

## Related

- **Schema:** `/templates/storyboard_schema.json`
- **Agent protocol:** `/agents/storyboard_agent.md` (creative direction — AI Cinematographer)
- **Shotlist agent:** `/agents/shotlist_agent.md` (downstream — mechanical production specs)
- **Storyboard review editor:** Production Console → Storyboard tab (`/editors/_standalone/storyboard_editor.html`)
- **Shotlist editor:** Production Console → Shotlist tab (`/editors/_standalone/shotlist_editor.html`)
- **Generation script:** `~/ComfyUI/output/generate_from_storyboard.py`