# Visual Design Agent Protocol

> Establish the project's visual language. Creates visual_bible.md from template, guided by breakdown.json and characters.md.

---

## Context Loading

Read these files before beginning:

| File | Purpose |
|------|---------|
| `/[project]/visual/breakdown.json` | **Primary input** — all characters, locations, props, VFX, wardrobe phases |
| `/[project]/bible/characters.md` | Character visual descriptions, behavioral DNA |
| `/[project]/bible/series_bible.md` | World, tone, atmosphere |
| `/templates/visual_bible_template.md` | Template to fill |
| `/appendix_e_flux2_protocols.md` | Flux 2 prompt engineering (HEX, lens, reference slots) |
| `/CONSTANTS.md` | Visual production constants (dimensions, lens defaults, reference slots) |

---

## Workflow

### Step 1: Verify Prerequisites

```bash
ls ./[project]/visual/breakdown.json
ls ./[project]/episodes/ep_001.md
```

Both must exist. If breakdown.json is missing, output:
```
ERROR: visual/breakdown.json not found.
→ Run /breakdown [project] first.
```

### Step 2: Load Breakdown Data

Read `visual/breakdown.json` and extract:
- **Characters**: names, visual descriptions, wardrobe phases, hair/makeup states, signature props
- **Locations**: names, types (INT/EXT), description samples, lighting notes
- **Props**: names, owners, descriptions, confidence levels
- **VFX Elements**: names, types, colors, production methods
- **SFX Elements**: names, types

These form the inventory that the visual bible must cover.

### Step 3: Copy Template

Read `/templates/visual_bible_template.md` and begin filling sections.

### Step 4: Fill Sections (Guided)

Work through each section with the user. For each section, present what was extracted from breakdown.json and ask the user to confirm or refine.

#### 4a. Color Palette

**From breakdown.json:** Extract any HEX codes already present in character/location descriptions.

**From hero reference images (if available):**
```bash
python3 /tools/extract_palette.py ./[project]
```
This extracts 5-8 dominant HEX colors per character from hero images in `visual/refs/characters/heroes/`, excluding white backgrounds. Colors are auto-classified (skin, hair, wardrobe_primary, etc.) and can update `breakdown.json` directly. Use `--dry-run` to preview, `--no-update` for console output only.

**Ask user:**
- Global palette (3-5 dominant HEX colors for the series)
- Per-location tier palettes (warm/cold/neutral tiers)
- Character-associated colors (e.g., protagonist = amber, antagonist = chrome)

**Output format:**
```markdown
### Global Palette
| Color | HEX | Use |
|-------|-----|-----|
| [name] | #XXXXXX | [where used] |
```

#### 4b. Character Designs

**From breakdown.json:** Visual descriptions, wardrobe phases, hair/makeup states per episode range.

**For each main character, add `### [Name]` under `## Characters`:**
- **Header must match characters.md exactly** — `### Jinx`, not `### Jinx — The Gambler`. The validator cross-checks names against characters.md.
- Visual summary (face, build, distinguishing features)
- Wardrobe per arc phase (with episode ranges from breakdown)
- Signature props (from breakdown props with owner mapping)
- Reference image slots (front, profile, three-quarter, full body, back)
- HEX accent color

**For minor/recurring characters**, use the separate `## Supporting Characters` section (h2, not under `## Characters`). Brief visual notes only — no full reference sheets.

**Use breakdown wardrobe phases directly** — they are the source of truth for what the character wears in each episode range.

#### 4c. Props

**From breakdown.json:** All props with confidence levels, owners, descriptions.

**For each significant prop, define:**
- Dimensions and materials
- Colors (HEX)
- Light behavior (glow, reflection, matte)
- State changes across episodes (from breakdown state_changes)

#### 4d. Locations

**From breakdown.json:** All locations with types, description samples, lighting notes.

**For each location, define:**
- Architecture and materials
- Lighting (natural/artificial, color temperature)
- Atmosphere (fog, dust, humidity, temperature)
- Color palette (HEX, subset of global palette)

#### 4e. VFX Elements

**From breakdown.json:** VFX elements with types, colors, production methods.

**For each VFX element, define:**
- Visual description
- Colors (HEX)
- Production method (post_composite, prompt_directly, practical)
- Production notes (compositing requirements)

#### 4f. Lens Package

**From CONSTANTS.md defaults:**

| Lens | Default | Use |
|------|---------|-----|
| Primary | 50mm f/2.0 (per CONSTANTS.md) | MS, MCU, dialogue, general coverage |
| Close-Up | 85mm f/1.4 (per CONSTANTS.md) | ECU, CU, emotional beats, detail shots |
| Wide | 24mm f/8 (per CONSTANTS.md) | Establishing shots, environmental, action |
| Specialty | (project-specific) | Special shots |

**Film stock:** Default "Kodak Vision3 500T" — ask user to confirm or change.

**Ask user:** Does the project tone warrant different defaults? (e.g., a brighter/warmer project might use Fuji rather than Kodak, or wider primary lens for environmental stories)

#### 4g. Lighting Guides

**Define at least 3 lighting setups for common moods:**

| Mood | Setup | Prompt Language |
|------|-------|----------------|
| Tension/Conflict | Chiaroscuro | "Rembrandt lighting, hard directional shadows" |
| Neutral/Dialogue | Three-point | "Key, fill, and rim light" |
| Atmosphere/Mystery | Volumetric | "Light beams filtering through dust" |

Add project-specific setups based on series bible tone and locations.

#### 4h. Flux 2 Reference Slot Assignments

**Per CONSTANTS.md:**

| Slots | Purpose | Status |
|-------|---------|--------|
| 1-5 | Character identity (front, profile, three-quarter, full body, back) | Populated after ref sheet generation |
| 6 | Wardrobe/props (signature items) | Populated after prop concepting |
| 7-8 | Environment (location refs) | Populated after location concepting |
| 9 | Lighting reference (mood) | Populated after look-dev |
| 10 | Pose/layout (depth maps, blocking) | Per-shot (from storyboard) |

Track which slots are populated for each character.

### Step 5: Write Visual Bible

Write the completed visual bible to `/[project]/visual_bible.md`.

### Step 6: Validate (MANDATORY GATE)

**After writing visual_bible.md, run the validation gate:**

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

This mechanically checks:
- Required sections present (Color Palette, Characters, Lens Package, Lighting Guides)
- Every character has a filled Visual Summary (not a placeholder)
- Lens package has Primary, Close-Up, and Wide lenses
- Film stock is specified (not a placeholder)
- At least one lighting guide exists
- HEX colors are real values (not #______ placeholders)
- Characters from characters.md are covered
- Locations from breakdown.json are covered

**Do NOT proceed to Step 7 until the validator exits with code 0 or 2.**
Exit code 1 = hard errors that block storyboarding.
Exit code 2 = warnings that should be reviewed but don't block.

If invalid, run with `--prompt` for specific fix instructions, apply them, and re-validate (max 3 attempts).

### Step 7: Report

```
═══════════════════════════════════════════════════════════════
VISUAL DESIGN: [project]
═══════════════════════════════════════════════════════════════

SECTIONS:
  ✓ Color Palette: [N] colors defined
  ✓ Characters: [N]/[total] designed
  ✓ Props: [N]/[total] designed
  ✓ Locations: [N]/[total] designed
  ✓ VFX Elements: [N]/[total] designed
  ✓ Lens Package: [primary] / [close-up] / [wide]
  ✓ Film Stock: [name]
  ✓ Lighting Guides: [N] setups

VALIDATION:
  ✓ All breakdown characters covered
  ✓ All breakdown locations covered
  ✓ HEX codes valid
  ✓ Lens package complete

REFERENCE SLOT STATUS:
  Characters: [N] need reference sheets
  Locations: [N] need reference images
  Props: [N] need concepting

NEXT STEPS:
  1. Generate character reference sheets (Flux 2 Klein or Max)
  2. Generate location reference images
  3. Train character LoRAs: python3 tools/train_lora.py [project] submit [CHAR] --type t2i
  4. Run /storyboard [project] ep 1 — first storyboard with visual context
═══════════════════════════════════════════════════════════════
```

---

## Audit Mode (--audit)

Skip steps 3-5. Instead:
1. Read existing `visual_bible.md`
2. Check each section for completeness
3. Report percentage and specific gaps
4. Do NOT modify the file

---

## Validate Mode (--validate)

Skip steps 3-5. Instead:
1. Read existing `visual_bible.md`
2. Read `visual/breakdown.json`
3. Cross-reference every asset
4. Report mismatches
5. Do NOT modify the file

---

## Section Mode (--section [name])

Only execute step 4 for the specified section. Write the result to the appropriate section of `visual_bible.md`, preserving other sections.

---

## Key Principles

1. **breakdown.json is the source of truth** for what assets exist. Visual bible defines how they look.
2. **HEX codes everywhere.** Every color must have a HEX value. Flux 2 follows hex accurately.
3. **Lens package is a creative constraint.** Don't add lenses unless the project demands it.
4. **Film stock sets the overall look.** It's appended to every generation prompt.
5. **Reference slots are finite (10).** Allocate strategically per CONSTANTS.md.
6. **Human approval required.** Visual design is reviewed before storyboarding begins.