---
name: storyboard-pass
description: Sub-agent skill for Stage 2 Storyboard Pass. Produces shot plans with 5 consumer groups (routing, prompt, spatial, asset, audio) from camera-tested episodes + Global Bible.
allowed-tools: Read, Bash, Glob, Grep
argument-hint: "--episode 1 [--project leviathan] [--dry-run]"
---

# /storyboard-pass — Storyboard Pass Sub-Agent

Reads 1 camera-tested episode + the Global Bible and produces a shot plan with per-shot records containing all 5 consumer groups. This is Stage 2 of the 3-stage render extraction pipeline.

## What This Agent Does

1. Loads camera-tested episode from `state/visual/camera_tested/ep_{NNN}.json`
2. Loads Global Bible from `state/visual/global_bible.json`
3. Creates focused bible summary for the specific episode
4. Calls extraction model (Opus 4.6 by default) with `STORYBOARD_SYSTEM_PROMPT`
5. Validates output against `EpisodePlan` schema from `lib/render_schema.py`
6. Cross-validates against Global Bible (characters, locations, props, phases)
7. Saves to `state/visual/plans/ep_{NNN}_plan.json`

## 5 Consumer Groups Per Shot

Each `ShotRecord` contains:

1. **RoutingData** — `target_editorial_duration_s`, `has_dialogue`, `camera_complexity`, `num_characters`, `is_env_only`, `narrative_requires_match_cut`
2. **PromptData** — `shot_type`, `camera_movement`, `focal_length`, `kinetic_action`, `lighting`, `prompt_skeleton`
3. **SpatialData** — `camera_side`, `screen_direction`, `character_relationships`
4. **AssetData** — `location_id`, `time_of_day`, `visual_mode`, `characters[]`, `props[]`
5. **AudioData** — `dialogue[]`, `ambient_sfx`, `foley_action`

## Validation Rules

- 1:1 mapping: output shot count must match camera-tested shot count exactly
- All `location_id` values must exist in Global Bible
- All `char_id` values must exist in Global Bible
- Wardrobe `phase_id` must match the correct phase for this episode number
- `is_env_only` must be consistent with character count
- `has_dialogue` must match presence of dialogue lines
- Every shot must have at least one light source with a practical motivator
- `kinetic_action` must use camera-artifact language (not semantic emotions)

## Parallelism

The orchestrator dispatches multiple storyboard-pass agents in parallel (one per episode), since each episode is independent once the Global Bible is complete.

## Failure Handling

- Pydantic validation error → retry with error feedback (up to 2 retries)
- Bible validation errors → retry with specific ID corrections
- After max retries → save with warnings (non-blocking) + log to review queue

## Implementation

Primary code: `orchestrator/ingest_pipeline.py` → `IngestPipeline.run_storyboard_pass()`
Schema: `lib/render_schema.py` → `EpisodePlan`, `ShotRecord`, all consumer group models