---
name: visual-design
description: SUPERSEDED by Starsend Casting + Location Refs pipeline. Legacy visual bible creator — color palettes, character designs, props, locations.
allowed-tools: Read, Write, Bash, Glob
argument-hint: "[project] [--audit | --validate | --section characters|locations|props|vfx|lens|lighting]"
---

# /visual-design — Visual Bible Creation

Establish the project's visual language before frame generation. Creates the **visual_bible.md** — the production-ready design document consumed by the storyboard agent and generation pipeline.

## Usage

```
/visual-design leviathan                      # Full guided creation from template
/visual-design leviathan --audit              # Check existing visual_bible.md completeness
/visual-design leviathan --validate           # Validate against breakdown.json
/visual-design leviathan --section characters # Focus on character designs only
/visual-design leviathan --section locations  # Focus on location designs only
/visual-design leviathan --section lens       # Focus on lens package only
```

## What It Produces

A single file at `/[project]/visual_bible.md` built from `/templates/visual_bible_template.md`.

The visual bible defines:
- **Color Palette** — Global and per-location HEX codes
- **Characters** — Visual summaries, wardrobe per arc phase, signature props, reference image paths
- **Props** — Materials, colors (HEX), light behavior, state changes across episodes
- **Locations** — Architecture, materials, lighting, atmosphere, color palettes (HEX)
- **VFX Elements** — Type, colors, behavior, production notes
- **Lens Package** — Primary, close-up, wide, specialty lenses + film stock reference
- **Lighting Guides** — Per-mood/scenario setups with exact prompt language
- **Flux 2 Reference Slot Assignments** — Character identity (1-4), props (5), environment (6-7), lighting (8), pose/layout (9-10)

## Parameters

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `project` | Yes | — | Project folder name |
| `--audit` | No | — | Check completeness of existing visual_bible.md |
| `--validate` | No | — | Cross-reference against breakdown.json |
| `--section` | No | all | Focus on one section (characters, locations, props, vfx, lens, lighting) |

## Prerequisites (HARD GATE)

Before running this command, the project MUST have:

1. **Completed episode scripts** — Visual design needs the scripts to know what exists
2. **Script breakdown** — `visual/breakdown.json` provides the asset inventory

```bash
# Check prerequisites
ls ./[project]/scripting/episodes/ep_001.md          # Episodes must exist
ls ./[project]/visual/breakdown.json       # Breakdown must exist
```

**If prerequisites are not met:**
```
ERROR: Visual design prerequisites not met.

  Missing: visual/breakdown.json
  → Run /breakdown [project] first to extract visual assets.

  Missing: episodes/
  → Generate episodes first with /generate-script-orchestrated [project].
```

## Execution

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

### Quick Summary

1. **Load Context** — Read breakdown.json, characters.md, series_bible.md, appendix_e
2. **Copy Template** — Start from `/templates/visual_bible_template.md`
3. **Fill Sections** — Guided creation with the user:
   - Extract character visuals from breakdown.json + characters.md
   - Map wardrobe phases to arc phases
   - Define HEX palettes per location tier
   - Establish lens package based on project tone
   - Define lighting guides per mood
   - Assign Flux 2 reference slots
4. **Validate (MANDATORY)** — Run `validate_visual_bible.py` against the output
5. **Fix & Report** — If validation fails, fix and re-validate (max 3 attempts)

### Audit Mode (--audit)

1. Read existing `/[project]/visual_bible.md`
2. Check each section for completeness:
   - Characters: all from breakdown.json present? Visual descriptions? Wardrobe phases? Reference images?
   - Locations: all from breakdown.json present? HEX palettes? Lighting notes?
   - Props: signature props present? Materials and colors defined?
   - Lens Package: all three lenses defined? Film stock set?
   - Lighting: at least 3 mood setups defined?
3. Report completeness with specific gaps

### Validate Mode (--validate)

Run the validation gate:

```bash
python3 /tools/validate_visual_bible.py \
  /[project]/visual_bible.md \
  /[project]/ --prompt
```

This mechanically checks all required sections, character coverage, HEX codes, lens package, film stock, and lighting guides. Exit codes follow CONSTANTS.md convention (0=clean, 1=fail, 2=warnings).

### Section Mode (--section)

Focus the guided creation on one section only. Useful for iterative design:
- `characters` — Character designs, wardrobe, reference images
- `locations` — Location architecture, lighting, atmosphere
- `props` — Prop descriptions, materials, colors
- `vfx` — VFX elements, production notes
- `lens` — Lens package, film stock
- `lighting` — Lighting guides, mood setups

## Output Path

```
/[project]/visual_bible.md
```

## Downstream Consumers

| Consumer | What It Reads |
|----------|---------------|
| **Production Console — Visual Bible tab** | All sections — interactive editor for camera, lens, palette, characters, locations, lighting. Saves directly to `visual_bible.md` and `project_config.json`. |
| **Storyboard Agent** | Lens package, HEX palettes, lighting guides, character visual summaries |
| **generate_from_storyboard.py** | Film stock, cinematic modifiers (appended to all prompts) |
| **Breakdown Editor** | Reference image paths, color palettes |
| **Human review** | All sections — visual bible is reviewed before production |

## Workflow Position

```
/generate-script-orchestrated [project]   ← 60 episodes generated
    ↓
/breakdown [project]               ← Extract visual assets
    ↓
/visual-design [project]           ← THIS COMMAND
    ↓
/storyboard [project] ep [N]      ← Storyboard with visual context
```

## Related

- **Template:** `/templates/visual_bible_template.md`
- **Agent protocol:** `/agents/visual_design_agent.md`
- **Validator:** `/tools/validate_visual_bible.py`
- **Flux 2 protocols:** `/appendix_e_flux2_protocols.md`
- **Breakdown output:** `/[project]/visual/breakdown.json`
- **Constants:** `/CONSTANTS.md` → Visual Production section