casting-agent

# Casting Agent Turn story context and entity extraction into accepted visual casting decisions and contact-sheet work orders. This skill is the visual-art-direction layer between story/entity extraction and `contact-sheet`. It answers: ```text What should this character, creature, prop, or scene look like in this story? Which references support that decision? What state, time period, mood, outfit, or environment variant matters? ``` It then delegates contact-sheet generation to `contact-sheet`. ## Boundary Own: - Read `story_contract.md`, screenplay, storyboard, context notes, and `visual_entities.json`. - Accept user/project-agent provided reference image paths or URLs. - Recall accepted prior visual assets from `memory` when requested. - Use `brave-search` only when provided/recalled references are missing or insufficient. - Select state/time/mood-specific reference queries, such as `pre-Heresy Horus Lupercal smiling`. - Write `casting_contract.json`, `chosen_reference_inputs.json`, and `contact_sheet_work_order.json`. - Review generated contact sheets against the casting contract and request bounded retries. Do not own: - Final image rendering mechanics. Delegate panel generation and Pillow sheet assembly to `contact-sheet`. - Kling, Seedance, lip-sync, or other paid video provider calls. - Voice training or final audio identity. Emit visual casting only unless a downstream voice skill is explicitly invoked. - Direct ArangoDB or Qdrant writes. Use `memory` / `contact-sheet`. ## Workflow ```text story + context + visual_entities -> optional provided references -> memory recall for accepted prior assets -> Brave search fallback for missing canon-sensitive references -> casting_contract.json -> chosen_reference_inputs.json -> contact_sheet_work_order.json -> contact-sheet generates panels -> casting-agent reviews panels -> accepted_casting_receipt.json or blocked_casting_receipt.json ``` ## Runtime ```bash cd skills/casting-agent ./run.sh plan-package \ --story-package /path/to/story_visual_package.json \ --out-dir /mnt/storage12tb/skills/persona-dream/outputs/<run-id>/casting ./run.sh plan \ --story /path/to/story_contract.md \ --visual-entities /path/to/visual_entities.json \ --out-dir /mnt/storage12tb/skills/persona-dream/outputs/<run-id>/casting \ --context "Use pre-Heresy warmer Horus, not corrupted Horus." \ --reference character_horus_lupercal_warmaster=/path/to/ref1.png \ --reference character_horus_lupercal_warmaster=/path/to/ref2.png ./run.sh sanity ``` The `plan-package` command is the preferred intake for real persona-dream work. It requires a keyed story visual package JSON, extracts `story_contract.md` and normalized `visual_entities.json`, imports embedded per-entity reference paths, and then writes the casting artifacts. The `plan` command remains a compatibility path for pre-split story/entity inputs. Neither command calls providers, runs Brave search, generates images, writes memory, or writes Qdrant. Live research/generation remains delegated to the named skills and must preserve their receipts. ## Inputs Required: ```text story_visual_package.json out-dir ``` Optional: ```text story_contract.md plus visual_entities.json for compatibility context text provided reference image paths or URLs memory recall policy Brave search policy max search rounds max generation rounds ``` Reference CLI format: ```text --reference <entity_id>=<path-or-url> ``` Primary `story_visual_package.json` shape: ```json { "schema": "persona_dream.story_visual_package.v1", "story_id": "stable_story_id", "story": { "text": "Accepted story text...", "context": "State, mood, time period, and visual constraints..." }, "keyed_entities": { "characters": { "horus": { "entity_id": "character_horus_lupercal_warmaster", "description": "Description of Horus in this story state.", "image_file_paths": ["/path/to/provided_reference.png"], "document_paths": [], "source_urls": [], "visual_anchors": ["bald", "pre-Heresy", "Warmaster"], "must_not_include": ["corrupted Chaos monster"], "contact_sheet_required": true, "contact_sheet_kind": "character_reference_pack" } }, "creatures": {}, "scenery": {}, "props": {}, "effects": {} } } ``` Every extracted thing should be keyed by a stable short name such as `characters.horus`, `characters.embry`, `creatures.tyranids`, `scenery.void_world_patio`, or `props.tea_service`. Each value must carry a description and may carry `image_file_paths`, `document_paths`, and `source_urls`. Embedded `image_file_paths` are treated as provided references. ## Output Artifacts ```text casting_contract.json chosen_reference_inputs.json contact_sheet_work_order.json casting_plan.md ``` `casting_contract.json` must record, per entity: ```text entity_id entity_type display_name story_role visual_state reference_strategy provided_references memory_reference_queries brave_search_queries must_include must_avoid contact_sheet_required contact_sheet_kind retry_budget ``` `chosen_reference_inputs.json` records the supplied or selected references that `contact-sheet` should use as grounding. `contact_sheet_work_order.json` is the handoff to `contact-sheet`; it names the Element set, required panels, expected output paths, and validation criteria. ## Reference Priority Use references in this order: ```text 1. Human/project-agent provided reference images. 2. Memory/Qdrant recalled accepted visual assets. 3. Project-local artifacts. 4. Brave search raw image/web receipts. 5. Provisional generated placeholders, explicitly marked provisional. ``` If provided references pass basic checks, do not force Brave search. Use Brave search to fill gaps or correct insufficient state/time/mood grounding. ## Contact-Sheet Delegation For every Kling-ready Element, apply `best-practices-kling-contact-sheet`: ```text 2-4 separate images per Element main/front or hero image first supplementary angle/detail/scale images next explicit Element description do-not-change list ignore list minimum 300 px each side 10 MB or less per uploaded image ``` The contact sheet is a human review artifact. Provider inputs are the separate panel images. ## Bounded Self-Correction The worker subagent may iterate, but only with receipts. Default limits: ```text max_search_rounds: 3 max_generation_rounds_per_entity: 2 max_review_rounds: 2 ``` Retry only for concrete failures: ```text wrong identity wrong era/state/mood low-quality or missing reference inconsistent panel identity too few/too many Kling Element images critical prop/environment omitted ``` Stop with `blocked_casting_receipt.json` if identity, references, or generated contact sheets cannot satisfy the contract within budget. ## Failure Modes - `missing_story`: story file missing or unreadable. - `missing_visual_entities`: visual entities missing or invalid. - `insufficient_references`: no provided/recalled/search references satisfy the entity contract. - `contact_sheet_blocked`: downstream `contact-sheet` could not produce panels. - `visual_review_failed`: generated sheets do not match the casting contract. ## Related Skill `create-cast` is a broader collaborative movie-casting workflow for character identity packs and voices. Use it when the task is actor/voice casting for a movie pipeline. Use `casting-agent` when `persona-dream` needs story-grounded visual references and contact sheets for characters, creatures, props, and environments.