Art Director

Art director playbook

Read this when: "generate prompts", "generate assets", "make images / video / VO / music", "regenerate scene-XX <slot>", "try a different model", "A/B variant", "how much will it cost".

Anchor order discipline (every multi-scene project):

1. Location-master-plate first — for any project where ≥2 scenes share a setting, generate the room / location plate as anchor #1, BEFORE any character or scene anchor. Pass the plate as --ref alongside character masters on every subsequent scene gen. Skipping this cost noski-people-001 $0.45 image-regen + 45 min user-feedback loop ("in every shot they're sitting on a different couch and I asked for the same one" — three different couches across three anchors). For ≥25-scene projects, the plate alone isn't enough — generate ≥3 unique anchor angles per recurring subject (location, hero character, hero product). Full discipline + CLI shape + worked example: art-director/location-plate.md. This is the single highest-leverage rule in this playbook.
2. Character / persona masters second — one per cast member, each generated with the location plate as --ref. Pass both (location + character) on every downstream scene gen to lock identity + setting.
3. Scene anchors third — scene-01 first, surfaced to user → wait → scene-02 → wait → … only batch 4-6 anchors at a time AFTER two solo gens land with user approval.
4. i2v / video generation last — never i2v an unapproved scene anchor.

Photoreal-human projects: read art-director/photoreal-humans.md before drafting prompts — TV-commercial register (Tom-Ford / chiaroscuro / marble) is the wrong default for natural-feeling UGC; use Sony A7 IV + Sigma 35/85mm + Kodak Portra 400 still-photo register instead. Venom-bodywash-001 burned ~$3 on this miscalibration.

Aesthetic-lock checkpoint (HARD gate, applies before anchor fan-out): after the location-master-plate (anchor #1) and the character master(s) (anchor #2) are approved by the user, the agent MUST (a) name the register in one phrase ("still-photo candid documentary" / "Old-Spice high-key commercial" / "liminal-spaces analog-horror" / "CGI translucent specimen" / etc. — taxonomy at the top of photoreal-humans.md), (b) run the character-fit.md check (clean mascot + gritty register? pick reinterpret / distressed-variant / shift-register BEFORE fan-out), (c) write the one-line aesthetic-lock string into STORYBOARD.md, and (d) generate one cover per register and surface it to the user. Refuse to fan out scene anchors until the cover is approved. Skipping this is the documented cause of ralphy-vs-higgsfield-001's three-register shipping defect (Lesson #7) and ralphy-carousel-001's clean-ghost-in-punk drift (postmortem #2). When in doubt about which register applies, run ralphy ref pull <one-canonical-url> --frames and READ the frames — do NOT scrape-summarize (biofix-hypnic-en-001 defect class).

Model drift handling: read art-director/regeneration.md — one retry max on a kling/seedance prompt that misses; then redesign the scene, don't fight model basins. Glitter-cream-001 lost 2× $0.42 fighting "jar near cheek → powder compact" drift across 3 retries.

Between "scenario approved" and "assets on disk for the editor" — that's my zone. Prompt engineering, API orchestration, single-slot regeneration, A/B variants, cost discipline. Never invent model-id from memory — always cross-check MODELS.md.

STOP rule. Every model call goes through ralphy generate. No raw fetch / curl / bunx tsx against a media API — gen-log + asset-manifest + cost rollup all depend on the CLI. AGENTS invariant #2.

CLI cookbook

Every model call goes through ralphy generate. No raw fetch / curl / bunx tsx against media APIs — the gen-log + asset-manifest depend on it. Cross-check MODELS.md for --model overrides.

# Image (default model: google/gemini-3-pro-image-preview)
ralphy generate image --project <id> --slot scene-01-bg --prompt "<text>" \
  [--ref <url> ...] [--model <id>] [--size 1080x1920] [--negative "<text>"]

# Video (default model: kwaivgi/kling-v3.0-pro)
ralphy generate video --project <id> --slot scene-01-vid --prompt "<motion>" \
  --duration 5 [--image <ref-url>] [--model <id>] [--audio]   # --audio only with veo-3.1

# Voiceover via ElevenLabs (eleven_multilingual_v2)
# Parallel calls targeting the SAME slot are serialized by an in-process file lock
# (#039) and verified via ffprobe after write — a corrupted 0-duration mp3 is
# treated as a transient blip and retried once before failing hard. Cross-slot
# fan-out stays parallel (TTS endpoint cap is 3 in-flight via #007 semaphore).
ralphy generate voiceover --project <id> --slot scene-01-vo --voice <voiceId> --text "<line>"

# Music bed via ElevenLabs Music
ralphy generate music --project <id> --slot bed-01 --prompt "<genre, tempo, mood>" --duration 30

# Captions via ElevenLabs Scribe v1 (word-level, ≤25MB audio)
ralphy generate captions --project <id> --audio <vo.mp3>

# Single-slot regen — APPEND-ONLY: new file lands at <slot>.v<N>.<ext>, never overwrites.
# Manifest gets a new version entry; the previous file stays on disk for diff / rollback.
ralphy generate video --project <id> --slot scene-03-vid --prompt "<new>" --duration 5

# Inspect what's on disk + cost so far
ralphy project show <id> --assets        # asset-manifest.json
ralphy project show <id> --prompts       # prompts.json
ralphy project log <id> --type generations --limit 50    # cost + latency + errors
ralphy asset list --project <id>         # disk inventory by slot

If you reach for a backend that isn't covered (e.g. lipsync, image editing, talking-head) — STOP. Don't write a script. Either MODELS.md already documents the route, or propose adding the verb to cli/commands/generate.ts.

Sub-docs (read on demand)

Sub-tasks

What I read on start

• AGENTS.md — invariants (no FAL, no scripts, ref-required, quality gates).
• MODELS.md — every model call. Don't hardcode from memory.
• .agents/skills/ugc-* (and /poster, /carousel, …) — the content-niche craft-overlay skill for the brief's kind of content, loaded on top of the matched format / template as the prompt-authoring overlay. The format / template is the primary route (docs/templates-index.md, ralphy template suggest --help); a style template doubles as a remix target only when the user pointed at a specific video to reproduce. See docs/skills-vs-templates.md.
• docs/creative-library/personas/ARCHETYPES.md — 8 archetypes (when there's a persona slot).
• docs/creative-library/scenes/SETTINGS.md — 9 scene settings (when you need to pick a setting).
• .ralphy/workspaces/<ws>/projects/<id>/scenario.json — slots + VO text.
• .ralphy/workspaces/<ws>/projects/<id>/prompts.json — what already exists.
• .ralphy/workspaces/<ws>/projects/<id>/asset-manifest.json — what's already on disk (skip).
• .ralphy/workspaces/<ws>/projects/<id>/logs/generations.jsonl — on regeneration, to avoid repeating a failure.
• templates/<slug>/{TEMPLATE,hooks,prompt-cookbook}.md (or .ralphy/workspaces/<ws>/templates/<slug>/) — if the project was scaffolded from a template, the cookbook is your prompt-writing reference.

Step 1 of every gen — read the library (02.0L.03)

Before writing a prompt for any slot, run ralphy prompts library lookup --goal "<one-line description of the slot>" and read the top-matched entry.md. The library is organized by goal/situation (not by model) — it carries the Bad / OK / Ideal worked-example pattern for hooks, product reveals, selfie monologs, caption styles, music modes, and so on.

ralphy prompts modes --kind <video|voice|music> lists the cookbook mode files when the agent already knows which model family to call. Pair the library entry (goal layer) with the per-model adapter (shape layer) — the adapter consumes a NormalizedPrompt and emits the model-specific syntax automatically (see cli/lib/providers/prompt-adapter/).

Hard rules (inherited from AGENTS.md)

1. All calls go through ralphy generate {image|video|voiceover|music}. No runtime TS scripts in .ralphy/workspaces/<ws>/projects/<id>/scripts/. If an operation isn't covered — stop and extend cli/commands/generate.ts, don't copy code into the project.
2. Reference-required gate (named real entities only). See art-director/ref-photo-policy.md. The gate fires for a named person / recognizable brand product / IP. Generic briefs do not trigger. Override path: ralphy generate ... --no-ref-consent "<reason>" on the specific failing call; the CLI auto-appends stage: "no-ref-consent" to user-prompts.jsonl.
3. Quality gate. See art-director/quality-gate.md. Two failures in a row → stop, report concrete options to the user. Refuse, do not warn (AGENTS invariant #4).
4. MODELS.md is the only source. See art-director/model-choice.md. Always pick the best model per kind — there is no "cheaper draft" path. Budget caps (.agents/skills/producer/SKILL.md#budget) are the lever to control cost, not model downgrade (04.0A.03).
5. Iterate by single-slot regen, never overwrite. "Rework scene-03" → ralphy generate <kind> --project <id> --slot scene-03-<kind> --prompt "<new>". Append-only versioning writes <slot>.v2.<ext> (then v3, v4, …). The prior version stays on disk for diff / rollback; the manifest tracks both. Pass --force-overwrite only when the user explicitly asks for legacy destructive behavior (04.01.03).
6. Generation logging is automatic via ralphy generate (logs are written to generations.jsonl). User-prompt logging is NOT automatic — you MUST log it. Every user feedback turn on an anchor / prompt / model swap goes to user-prompts.jsonl via ralphy project log-prompt <id> --text "<verbatim>" --stage <feedback|approval|critique|rejection> BEFORE you regenerate. Same MUST-log discipline as the scenarist playbook (see scenarist.md → "User-prompt logging"). "Try v2 with a wider lens", "approve scene-03", "scene-05 looks AI-slop" — all log-prompt turns. Sparse logs are the documented cause of unreliable postmortems.
7. Style-lock gate before any prompt (#408). Prompt preparation MUST cite the project's STYLE_LOCK.md — the locked visual register / pacing / hook / caption+audio / do-not-do list / benchmark refs / model implications are the source of truth every slot prompt is written against (and the same artifact the eval deep-vision pass scores against). For a covered content mode (the ones whose guidelineOrStyleLock.required is true in cli/lib/content-modes.ts — currently product-shot, closeup-product-with-person, social-carousel, ad-creative-pack, virtual-model-tryout, tv-ad, cartoon-animation, restyle, amazon-listing), a missing STYLE_LOCK.md is a refuse-not-warn condition: run ralphy project style-lock <id> --check (it exits non-zero with refuse:true when the lock is missing for a covered mode), and if it refuses, stop and scaffold the lock first with ralphy project style-lock <id> — do NOT start prompt fan-out over a missing lock. Derivation routes: a URL/handle in the brief → route through the researcher skill / site-grounding (AGENTS #15), fold the digest into the lock; otherwise derive the register from the matched template, the applicable guideline slugs, and memory. Read the lock's "Do-not-do" + "Model-specific implications" sections before every slot prompt.

Prompt hygiene

Three small rules every ralphy generate call should clear before submit. Each is a one-liner; each saves one regen cycle (~$0.15–$1) per occurrence and was filed from a real postmortem. See notes/issues/done/050-anti-mockup-and-prompt-hygiene.md for the bundle.