/storyboard-architect

name: storyboard-architect
description: Turn a creative brief into a production-grade storyboard with shot specs, timing, on-screen text, and per-shot rationale. Use when the user describes a video brief, plans a video, references shots or beats, scripts a social video, or hands over a creative concept to break into scenes. Produces run.json, storyboard.md, shots.json, text-overlays.json, and brand-lock.snapshot.md. Pairs with visual-prompt-forge, visual-asset-critic, storyboard-html-preview.

Storyboard Architect

You are turning a creative brief into a deterministic storyboard. The output is a set of files an editor, agency, or developer can act on without asking follow-up questions.

This is not a creative-writing exercise. The output is a spec.

When to use

Trigger this skill when the user:

• Describes a video they want to make ("30-second explainer for...", "TikTok ad about...")
• Asks to storyboard, plan shots, break out beats, write a shot list
• Hands over a script, brief, or concept document expecting structured pre-production output
• Mentions a beat framework by name (Hero Trilogy, Pain-Proof-Promise, etc.)
• References an existing brand-lock file or pack

If the user only wants prompts for an image generator (no narrative structure), use `visual-prompt-forge` directly instead.

What you produce

For every storyboard run, create this exact set of files in the working output directory:

output/
├── run.json                   # Run identity + every input pinned by content hash
├── storyboard.md              # Human-readable, structured per shot
├── shots.json                 # Machine-readable, schema in templates/shots.schema.json
├── text-overlays.json         # On-screen text + timing
└── brand-lock.snapshot.md     # Frozen copy of the brand-lock used (audit trail)

`run.json` is what makes the rest of the tree auditable later. A filename says nothing about the bytes behind it, so the snapshot sitting next to a set of frames is not proof that it is the snapshot they were built from. The hashes in `run.json` are that proof. Write it once, at the end of the run, and never edit it.

If the user asks for image prompts or HTML preview, hand off to `visual-prompt-forge` or `storyboard-html-preview`, those skills consume `shots.json` directly. Don't try to do their job here.

Inputs

You need these. If any are missing, ask before drafting.

| Input | Required? | Default if absent | |---|---|---| | Brief (problem, audience, goal) | Yes | Ask | | Total duration | Yes | Ask | | Aspect ratio | Yes | Ask (16:9, 9:16, 1:1) | | Beat framework | No | Suggest based on brief | | Brand-lock file path | No | Use `brand-packs/_template.md` and flag the gap | | Voiceover style (VO present, on-screen only, captions) | No | Ask if unclear | | Target generator(s) for downstream prompts | No | Note as "to be specified" |

Workflow

Follow this sequence. Don't skip steps even if the brief seems simple.

Step 1. Read the brand-lock

If a brand-lock file path is provided, read it first. Extract:

• Palette (hex)
• Typography
• Mood descriptors
• "Never" list (what this brand will never do visually)
• Motion language
• Voice tone
• Aspect-ratio preferences

If no brand-lock is provided, copy `brand-packs/_template.md` into the output as `brand-lock.snapshot.md` with a note: `# UNCONFIGURED, using template defaults. Recommend providing a real brand-lock for production work.`

Step 2. Pick the beat framework

Read `references/beat-frameworks.md`. Pick the one that matches the brief. Common cases:

• Pain-reframe-promise → conversion content
• Hero Trilogy → product hero films
• Founder Explainer → personal-brand content
• Content Spiral → kinetic typography / opinion pieces

If none fit cleanly, build a custom beat structure but document why in `storyboard.md` rationale section.

Step 3. Block out timing

Read `references/timing-rules.md` for the math. Default cadence:

• Hook beat: 0–2 seconds
• Pain/setup: 2–6 seconds (for 30s) or 2–10 seconds (for 60s)
• Proof/reframe: middle third
• Promise/CTA: final 4–6 seconds

Don't fight the framework. If the brief and the duration disagree, surface the disagreement before drafting.

Step 4. Draft the shot list

Read `references/shot-grammar.md` for controlled vocabulary. The field names below are the schema's field names. `templates/shots.schema.json` sets `additionalProperties: false`, so a near-miss like `environment` instead of `environment_ref` is a validation failure, not a synonym.

• `id`, sequential, zero-padded (`shot_01`, `shot_02`...)
• `beat`, which beat this shot serves
• `start` / `end`, timestamps in seconds, decimal allowed. `end` must be after `start`
• `framing`, ECU / CU / MCU / MS / MLS / WS / EWS
• `angle`, eye-level / high / low / overhead / dutch
• `motion`, static / push / pull / pan-left / pan-right / tilt-up / tilt-down /

handheld / orbit / whip / rack. All eleven are legal; the schema enum is the authority and `references/shot-grammar.md` explains when each earns its keep

• `depth_of_field`, optional, shallow / deep / rack
• `subject`, what's in frame, structured
• `environment_ref`, references series-lock language, default `series_lock.environment`
• `lighting_ref`, references series-lock language, default `series_lock.lighting`
• `on_screen_text`, null, one text-overlay id, OR an array of ids when a shot carries

more than one overlay

• `vo`, voiceover line, or null
• `rationale`, one sentence explaining *why this shot at this moment*

Note on `rack`: as a `motion` value it means the rack focus is the shot's movement; as a `depth_of_field` value it means focus shifts mid-shot. Same word, two fields, two meanings.

Step 5. Separate the text layer

Every piece of on-screen text becomes an entry in `text-overlays.json`. Never bake text into the visual description. Each overlay has:

• `id`, `text_01`, `text_02`...
• `shot_id`, which shot this overlays on
• `content`, the actual tex