@milenyumai/film-kit 2.2.0 → 2.3.0

package/packages/multi/content/agents/continuity-editor.md

@@ -18,10 +18,10 @@ You do not create new scenes unless requested for repair.
 ## Responsibilities
 
 1. verify planned shots exist for every batch
-2. verify SHOT01 ILK FRAME matches `team-plan.json -> batches[0].chain_entry` (first-frame entry validation)
-3. verify cross-batch continuity (`SHOT[N]_END -> SHOT[N+1]_START`)
+2. verify SHOT01 continuity entry matches `team-plan.json -> batches[0]` (first-frame entry or storyboard handoff validation)
+3. verify cross-batch continuity (start/end chain or storyboard handoff chain)
 4. verify continuity notes in `_index.md` match actual files
-5. verify chained `ILK/İLK FRAME` code blocks contain only `Use SHOT[prev]_END as exact first frame`; any competing visual prompt is a chain break blocker
+5. $SEMANTIC_AUDIT_CONTRACT
 6. patch continuity text mismatches when safe and deterministic
 7. verify actual shot count matches `team-plan.json -> shot_sizing.selected_target_shots`
 
@@ -33,9 +33,9 @@ Write `$OUTPUT_DIR/reports/CONTINUITY-REPORT.md` with this strict structure:
 # CONTINUITY REPORT
 
 - overall_status: pass/fail
-- chain_entry_status: pass/fail
-- chain_boundary_status: pass/fail
-- chained_ilk_frame_status: pass/fail
+- continuity_entry_status: pass/fail
+- continuity_boundary_status: pass/fail
+- reference_mode_contract_status: pass/fail
 - file_completeness_status: pass/fail
 - blockers:
   - none

package/packages/multi/content/agents/delivery-editor.md

@@ -21,8 +21,8 @@ You are responsible for final delivery readiness checks.
 - `team-plan.json` contains top-level `voiceCast`
 - `team-plan.json` contains top-level `visual_world`
 - each file follows one-file-per-shot contract
-- each shot has ILK/İLK, SON, VIDEO sections with valid code blocks
-- chained ILK/İLK FRAME code blocks contain only exact reuse text; competing visual prompts are marked CHAIN BREAK
+- each file follows the active reference-mode shot format
+- $REFERENCE_MODE_CONTRACT
 - every speaking shot has an `Audio Plan` block with valid `activeSpeakerKey`
 - when model is `kling-3.0`, VIDEO prompt code blocks start with `[CHARACTER / SUBJECT CONSISTENCY]` and include timing, background, final-frame, and negative prompt blocks
 - when model is `kling-3.0`, custom storyboard mode never exceeds 4 shots in one video

package/packages/multi/content/agents/lead-director.md

@@ -47,14 +47,16 @@ Create a machine-readable plan with this shape:
       "target": "$MODEL",
       "display": "$MODEL_DISPLAY",
       "kling_preset": "$KLING_PRESET",
-      "transition_mode": "start-end"
-    }
+      "transition_mode": "$REFERENCE_MODE"
+    },
+    "reference_mode": "$REFERENCE_MODE"
   },
+  "storyboard_reference": $STORYBOARD_REFERENCE_POLICY_JSON,
   "policy": {
     "dialogue_name_policy": "preserve-original-dialogue",
     "semantic_contract": {
       "visual_world_required": true,
-      "chained_ilk_frame_exact_reuse_only": true,
+      "chained_ilk_frame_exact_reuse_only": $CHAINED_ILK_FRAME_EXACT_REUSE_REQUIRED,
       "scene_specific_avoid_terms_required": true
     },
     "spatial_contract": {
@@ -149,7 +151,10 @@ Create a machine-readable plan with this shape:
       "shot_number": "SHOT01",
       "audio_type": "dialogue",
       "active_speaker_key": "kemal",
-      "voice_cast_binding_required": true
+      "voice_cast_binding_required": true,
+      "storyboard_continuity_note": "opening action handoff / closing action handoff when storyboard-reference is active",
+      "storyboard_phase_budget": "4-6s=1-2, 7-10s=2-3, 11-15s=3-4",
+      "continuity_mode": "continuous-shot / multi-shot-storyboard"
     }
   ],
   "support_agents": [
@@ -197,6 +202,10 @@ Create a machine-readable plan with this shape:
 Keep top-level `voiceCast` stable and require every speaking shot to bind back to it.
 `team-plan.json` is also the authoritative scene-level visual package. Keep top-level `visual_world` stable unless a shot declares `CHAIN BREAK - [reason]` and documents the new world.
 
+## Reference Mode Contract
+
+$REFERENCE_MODE_CONTRACT
+
 ## Shot Count Direction (Before Team Sizing)
 
 Use `.agent/skills/director-shot-sizing/SKILL.md` before you choose teammate count or batch map.
@@ -236,7 +245,7 @@ BATCH ID: B[NN]
 YOUR BATCH: SHOT[X] through SHOT[Y]
 OUTPUT DIR: $OUTPUT_DIR/shots/
 REPORT FILE: $OUTPUT_DIR/reports/BATCH-REPORT-B[NN].md
-CHAIN ENTRY FRAME: [exact description]
+CHAIN ENTRY FRAME / STORYBOARD ENTRY HANDOFF: [exact chain entry or storyboard handoff description]
 SPATIAL PRIORITY: [who looks at what, which plane dominates, shared light source]
 SEMANTIC WORLD: [visual_world camera height, lens family, horizon/vanishing logic, camera movement strategy, light source, shadow direction, scale map, reflection risk, physics constraints]
 
@@ -249,14 +258,13 @@ RULES:
 - One active speaker per shot
 - ONE FILE PER SHOT (SHOTNN.md includes coverage)
 - Do not add or remove shot files beyond the planned range
-- ILK/İLK FRAME section must include a fenced code block even when chained
-- Chained ILK/İLK FRAME code block must contain only `Use SHOT[prev]_END as exact first frame`; a new visual prompt requires `CHAIN BREAK`
 - Follow `team-plan.json -> visual_world` for perspective/geometry, shadow vector, scale, reflection, physics, anatomy risk, foreground/background coherence, and targeted semantic avoid terms
+- $REFERENCE_MODE_CONTRACT
 - If model is kling-3.0: enforce route metadata + `AUDIO PLAN` outside the prompt code block and professional Kling blocks from `[CHARACTER / SUBJECT CONSISTENCY]` through `[NEGATIVE PROMPT]`
 - If model is kling-3.0: require shot time ranges, `[TIMING RULES]`, `[BACKGROUND RULES]`, `[FINAL FRAME PRIORITY]`, stable background, and no warping
 - If model is kling-3.0: default to `single-transition`; use custom storyboard only for 2-4 meaningful phases, max 4 custom shots
-- If model is seedance-2.0: require explicit multimodal role assignment when references exist (`@image1`, `@video1`, `@audio1`)
-- If model is seedance-2.0: default to `No scene cuts throughout, one continuous shot.` unless the beat truly needs phased timing
+- If model is seedance-2.0: require explicit multimodal role assignment when references exist (`@Image1`/`@image1`, `@video1`, `@audio1`)
+- If model is seedance-2.0: follow the active Seedance storyboard/continuity contract in `.agent/model-profile.md`
 - If model is seedance-2.0: separate identity reference from action/camera reference whenever different materials are used
 - If model is seedance-2.0: use extension syntax when continuing a source clip (`Extend @video1 by [N]s`)
 - Never convert one glance, one micro gesture, or one tiny prop action into separate Kling storyboard beats
@@ -275,7 +283,7 @@ After all shot teammates finish, run specialist checks:
 4. `dialogue-auditor`: verify dialogue tone consistency, `voiceCast` binding, audioPlan completeness, SFX accuracy, audio direction completeness, and music policy
 5. `character-consistency-auditor`: verify character description consistency and anonymous identity stability across shots
 6. `color-continuity-auditor`: verify lighting direction and color temperature consistency across shots within the same scene
-7. `semantic-auditor`: verify `visual_world`, perspective/geometry, shadow vector, scale map, reflections, physics/anatomy, foreground/background coherence, contextual contradictions, targeted avoid terms, and chained ILK reuse
+7. `semantic-auditor`: verify `visual_world`, perspective/geometry, shadow vector, scale map, reflections, physics/anatomy, foreground/background coherence, contextual contradictions, targeted avoid terms, and the active continuity contract
 8. `pacing-auditor`: verify shot sequence rhythm, tempo variety, and dramatic arc alignment
 9. `delivery-editor`: verify packaging completeness and final summary readiness
 

package/packages/multi/content/agents/semantic-auditor.md

@@ -26,15 +26,14 @@ Reject the package if any item fails:
 - Foreground and background share perspective, lighting, color temperature, and style.
 - Contextual contradictions are absent or explicitly justified.
 - Reference-visible face, hair, skin, body proportions, wardrobe, accessories, and prop design do not drift when a reference exists.
-- Start/end pairs keep the declared invariants and change only one major semantic beat unless `CHAIN BREAK` is declared.
 - Avoid lines include scene-specific semantic failure modes.
-- Chained `ILK/İLK FRAME` code blocks contain only `Use SHOT[prev]_END as exact first frame`; any competing visual prompt is a fail and must become `CHAIN BREAK`.
+$SEMANTIC_AUDIT_CONTRACT
 - When model is `kling-3.0`, `AUDIO PLAN` and route metadata remain outside the prompt code block.
 - When model is `kling-3.0`, the VIDEO prompt code block starts with `[CHARACTER / SUBJECT CONSISTENCY]` and includes `[CORE INTENT]`, `[TOTAL DURATION]`, `[VISUAL STYLE]`, `[CAMERA]`, `[SHOT N | time range]`, `[AUDIO]`, `[TIMING RULES]`, `[BACKGROUND RULES]`, `[FINAL FRAME PRIORITY]`, and `[NEGATIVE PROMPT]`.
 - When model is `kling-3.0` and custom storyboard is used, there are no more than 4 custom shots; 5+ phases are split into chained videos.
 - Kling custom storyboard shots include time ranges, one main job, subject action, camera behavior, background behavior, and handoff/final-frame trigger.
 - When model is `seedance-2.0`, material roles are explicit when references are used and identity references are separated from camera/action references when needed.
-- When model is `seedance-2.0`, uninterrupted beats explicitly declare `No scene cuts throughout, one continuous shot.` unless phased timing is justified.
+- When model is `seedance-2.0`, uninterrupted beats explicitly declare `No scene cuts throughout, one continuous shot.`; multi-phase storyboard beats declare planned phase transitions instead.
 - When model is `seedance-2.0`, clip continuations use `Extend @video1 by [N]s` syntax instead of silently reframing the same beat as a new cut.
 
 ## Allowed Fixes
@@ -52,7 +51,7 @@ Write `$OUTPUT_DIR/reports/SEMANTIC-REPORT.md` with this strict structure:
 - overall_status: pass/fail
 - visual_world_status: pass/fail
 - reference_drift_status: pass/fail
-- start_end_contract_status: pass/fail
+- $SEMANTIC_REFERENCE_MODE_STATUS_FIELD: pass/fail
 - perspective_geometry_status: pass/fail
 - shadow_vector_status: pass/fail
 - scale_depth_status: pass/fail
@@ -60,7 +59,7 @@ Write `$OUTPUT_DIR/reports/SEMANTIC-REPORT.md` with this strict structure:
 - anatomy_physics_status: pass/fail
 - foreground_background_status: pass/fail
 - contextual_contradiction_status: pass/fail
-- chained_ilk_frame_status: pass/fail
+- $SEMANTIC_CONTINUITY_STATUS_FIELD: pass/fail
 - avoid_terms_status: pass/fail
 - kling_prompt_structure_status: pass/fail/not_applicable
 - blockers: [none or list]

package/packages/multi/content/agents/shot-generator.md

@@ -24,7 +24,7 @@ Your assignment must include:
 
 - `BATCH ID` (example: `B03`)
 - shot range (`SHOT09` through `SHOT12`)
-- chain entry frame description
+- chain entry frame or storyboard entry handoff description
 - semantic world summary from `team-plan.json -> visual_world`
 - report file path (`$OUTPUT_DIR/reports/BATCH-REPORT-B03.md`)
 
@@ -38,16 +38,7 @@ For each shot in your batch, write exactly one file:
 
 Each shot file must include:
 
-1. main shot blocks: `ILK FRAME` (or `İLK FRAME`), `SON FRAME`, `AUDIO PLAN`, `VIDEO` (or `VİDEO`)
-2. `ILK/İLK FRAME` section must always include a fenced code block
-3. if chained, first-frame code block must contain only: `Use SHOT[prev]_END as exact first frame`; any new start-frame prompt requires `CHAIN BREAK`
-4. 2-3 coverage sub-shots in the same file
-5. image prompt contract (hard requirement):
-   - if references exist, `ILK FRAME` and `SON FRAME` must use `REFERENCE LOCK`, `Keep same`, and `Change only`
-   - face/hair/skin/body/wardrobe/accessories/prop design visible in reference are immutable
-   - `SON FRAME` must preserve the same visual universe and declare only one major semantic delta
-   - `VIDEO`: minimum 120 words
-   - each coverage video prompt: minimum 70 words
+$SHOT_FILE_OUTPUT_CONTRACT
 6. specificity floor (hard requirement in every prompt):
    - concrete lens/framing/camera movement
    - camera movement named from the 24-move cinematic lexicon in `prompt-structure` when movement is present
@@ -75,12 +66,9 @@ Each shot file must include:
 
 ## Continuity Rules
 
-- First shot `ILK FRAME` / `İLK FRAME` must match assigned chain entry.
-- Chained `ILK FRAME` / `İLK FRAME` code blocks cannot contain a new camera, lens, lighting, action, or composition prompt.
-- Within your batch: `SHOT[N]_END` must match `SHOT[N+1]_START`.
-- Coverage shots are standalone and not chained.
+$CONTINUITY_CONTRACT
 - For `kling-3.0`: keep route metadata and `AUDIO PLAN` outside the prompt code block; the prompt code block starts with `[CHARACTER / SUBJECT CONSISTENCY]` and includes timing, background, final-frame, and negative prompt blocks.
-- For `seedance-2.0`: declare material roles explicitly when references exist, keep identity references separate from camera/action references, and use continuous-shot wording unless phased timing is required.
+- For `seedance-2.0`: declare material roles explicitly when references exist, keep identity references separate from camera/action references, and use continuous-shot wording only when the shot is truly uninterrupted.
 
 ## Kling Multi-Shot Decision
 
@@ -98,12 +86,7 @@ When model is `kling-3.0`, choose the simplest mode that preserves quality:
 
 When model is `seedance-2.0`, keep the shot prompt readable but explicit:
 
-- use `Use @image1 as the first frame of the scene.` when first-frame identity lock matters
-- if `@video1` is action reference and `@video2` is camera reference, say so directly
-- default to `No scene cuts throughout, one continuous shot.`
-- use timeline segments only for meaningful internal beats, not decorative micro-actions
-- when continuing a clip, use `Extend @video1 by [N]s` rather than rewriting it as a new cut
-- when `@image1` locks identity, keep face/body/wardrobe/prop design exact and change only one meaningful beat
+$SEEDANCE_STORYBOARD_CONTRACT
 
 ## Safety Rules
 
@@ -120,8 +103,7 @@ When model is `seedance-2.0`, keep the shot prompt readable but explicit:
 
 - all assigned shot files exist
 - each file has main + coverage content
-- each `ILK/İLK FRAME` section contains a code block
-- image prompt contract passes for all main prompts; video floor passes for VIDEO and coverage video prompts
+$SHOT_SELF_CHECK_CONTRACT
 - specificity floor passes (lens + light + spatial action present)
 - continuity inside batch passes
 - avoid lines exist everywhere
@@ -131,7 +113,7 @@ When model is `seedance-2.0`, keep the shot prompt readable but explicit:
 - one active speaker per shot
 - Kling gate passes (if active): professional blocks from `[CHARACTER / SUBJECT CONSISTENCY]` through `[NEGATIVE PROMPT]`, shot time ranges, timing rules, background rules, final-frame priority, no warping/stable background
 - Kling multi-shot passes (if active): single-transition by default, custom storyboard only when justified, max 4, never decorative micro-beats
-- Seedance gate passes (if active): multimodal roles explicit, continuous-shot or timeline mode intentionally chosen, extension syntax used for clip continuation
+- Seedance gate passes (if active): multimodal roles explicit, continuous-shot or multi-shot-storyboard mode intentionally chosen, extension syntax used for clip continuation
 - spatial realism passes: plane map + eyeline target + shared light + contact/depth cues
 - semantic consistency passes: `visual_world` + perspective/geometry + shadow vector + scale map + reflection/physics/anatomy/context checks
 
@@ -153,8 +135,8 @@ After generation, write the report file provided by Lead Director using this tem
 - files_written:
   - SHOTXX.md
   - SHOTYY.md
-- chain_entry_used: [text]
-- chain_exit_frame: [text]
+- continuity_entry_used: [chain entry or storyboard handoff text]
+- continuity_exit_handoff: [end frame or storyboard handoff text]
 - continuity_status: pass/fail
 - safety_status: pass/fail
 - voice_design_status: pass/fail

package/packages/multi/content/skills/storyboard-reference/SKILL.md

@@ -1,28 +1,120 @@
 ---
 name: storyboard-reference
-description: Character reference + storyboard image + brief to model-aware video prompt bundles without requiring start/end frames.
+description: Character reference sheet prep + per-shot GPT Image 2 storyboard prompts + model-aware video prompt bundles for Veo 3.1, Seedance 2.0, and Kling 3.0 without requiring start/end frame generation.
 ---
 
 # Storyboard Reference Skill
 
-Use when the user provides a character reference, storyboard reference, and video brief.
+## Purpose
+
+Use this skill when the user provides:
+
+- one or more character reference images
+- a video brief or scenario text
+- optional external storyboard guide images
+
+The output is a production workflow, not only a video prompt. First create one reusable GPT Image 2 character sheet prompt per reference character. Then create one GPT Image 2 storyboard prompt per `SHOTNN.md`. The generated shot storyboard is the staging reference for the final video model prompt.
+
+## Reference Prep
+
+### Character Sheet Prompt
+
+For each character reference, generate this prompt once:
+
+- provider: `gpt-image-2`
+- aspect ratio: `16:9`
+- layout: one widescreen production storyboard sheet
+- required views: front full body, back full body, left profile, right profile, three-quarter full body, close-up face
+- identity lock: exact face, skull shape, hair, skin texture, body proportions, wardrobe, accessories, and visible props
+- forbidden: text, labels, arrows, panel numbers, logos, watermarks, alternate outfits, alternate character designs
+
+This sheet becomes the identity reference for every later shot storyboard.
+
+### Shot Storyboard Prompt
+
+For each shot, generate a professional GPT Image 2 storyboard prompt:
+
+- provider: `gpt-image-2`
+- aspect ratio: `16:9`
+- panel budget: 4-6s = 1-2 panels, 7-10s = 2-3 panels, 11-15s = 3-4 panels
+- hard cap: max 4 panels/phases per shot unless the configured project cap is lower
+- split policy: 5+ distinct phases must become separate chained `SHOTNN.md` files
+- target detail: 160-240 words, concrete blocking and camera language, no decorative prose
+- continuity: include previous shot handoff, next shot handoff, shared `visual_world`, screen direction, lighting, and action rhythm
+
+The shot storyboard prompt must use the character sheet reference as the only identity source. Optional external storyboard guide images may inform composition and timing only.
 
 ## Role Separation
 
-- `@character1`: exact identity lock for face, hair, body proportions, wardrobe, accessories, and visible props.
-- `@storyboard1`: composition, blocking, camera angle, action progression, visual rhythm, and phase order only.
+Character references and generated character sheets are identity locks.
+
+Use them for face, hair, skin texture, body proportions, wardrobe, accessories, and visible props. Do not use them for camera path, storyboard timing, or background layout.
+
+The generated shot storyboard is the editorial and camera plan.
+
+Use it for composition, blocking, camera angle, action progression, visual rhythm, phase order, and handoff continuity. Do not use it to redesign the character, replace wardrobe, copy panel borders, copy text, copy logos, or import watermark details.
 
 ## Hard Rules
 
 - Character identity always wins over storyboard character design.
-- Do not copy storyboard text, logos, watermarks, labels, or panel borders.
-- One prompt may contain at most 4 storyboard phases.
-- 5+ distinct phases must split into multiple `SHOTNN.md` files.
-- Do not require ILK FRAME / SON FRAME assets in `storyboard-reference` mode.
-- Every model prompt needs `Avoid` or negative prompt coverage.
-- Dialogue stays in the user's original language.
-- Music is `NONE` unless explicitly requested.
+- Storyboard text, labels, watermarks, logos, and panel borders are never copied into the video.
+- One prompt may contain at most 4 storyboard phases by default.
+- 5+ distinct storyboard phases must be split into multiple `SHOTNN.md` files.
+- Do not assume start/end frame assets exist in `storyboard-reference` mode.
+- Every model output must include an `Avoid` or negative prompt section.
+- Dialogue remains in the user's original language.
+- Music is `NONE` unless the user explicitly asks for music.
+- Fail closed on public figure, real-person likeness, trademark/logo, or unsafe visual requests.
+
+## Model Grammar
+
+Seedance 2.0:
+
+- Map character sheet images to `@Image1`, `@Image2`, ... with legacy aliases `@image1`, `@image2`, ...
+- Map the generated shot storyboard to the next image token, for example one character means `@Image2`, two characters means `@Image3`.
+- Character image tokens control identity, face, body proportions, wardrobe, accessories, and visible props.
+- The storyboard token controls composition, blocking, camera direction, timing, action rhythm, and phase order only.
+- Use explicit timeline phases when the storyboard has multiple beats.
+- Use `No scene cuts throughout, one continuous shot` only for a true single uninterrupted camera move.
+- For multi-phase storyboard prompts, use only the planned phase transitions and do not add unplanned cuts.
+- Duration policy: 4-6s = 1-2 phases, 7-10s = 2-3 phases, 11-15s = 3-4 phases.
+- Seedance provider limits: max 9 image references, 3 video references, 3 audio references, 12 total files, 4-15 seconds.
+- Storyboard text, panel borders, watermark, logo, and alternate character design are never identity sources.
+
+Veo 3.1:
+
+- Describe the generated storyboard as a visual planning reference, not a literal frame.
+- Include camera, lens/framing, lighting, foreground/midground/background, continuity, and full `Audio direction`.
+- Do not request storyboard panel borders or on-screen text.
+
+Kling 3.0:
+
+- Prompt code block starts with `[CHARACTER / SUBJECT CONSISTENCY]`.
+- Include `[CORE INTENT]`, `[TOTAL DURATION]`, `[VISUAL STYLE]`, `[CAMERA]`, `[SHOT N | time range]`, `[AUDIO]`, `[TIMING RULES]`, `[BACKGROUND RULES]`, `[FINAL FRAME PRIORITY]`, and `[NEGATIVE PROMPT]`.
+- Use `resolved storyboard composition`, not `final frame exactly`, when no end frame exists.
 
 ## Output Contract
 
-Write `$OUTPUT_DIR/storyboard-reference-plan.json`, `$OUTPUT_DIR/prompt-bundles/SHOTNN.bundle.json`, `$OUTPUT_DIR/shots/SHOTNN.md`, and `$OUTPUT_DIR/reports/STORYBOARD-REFERENCE-QA.md`.
+Each shot file contains:
+
+- Turkish summary
+- model control
+- input asset roles
+- reference asset requirements
+- provider reference tokens
+- GPT Image 2 storyboard prompt
+- storyboard interpretation
+- audio plan
+- prompt bundle for requested models
+- QA verdict
+
+Generated files:
+
+```text
+$OUTPUT_DIR/storyboard-reference-plan.json
+$OUTPUT_DIR/reference-prep/CHARACTER-SHEET-*.md
+$OUTPUT_DIR/storyboard-prompts/SHOTNN-GPT-IMAGE-2-STORYBOARD.md
+$OUTPUT_DIR/prompt-bundles/SHOTNN.bundle.json
+$OUTPUT_DIR/shots/SHOTNN.md
+$OUTPUT_DIR/reports/STORYBOARD-REFERENCE-QA.md
+```

package/packages/multi/content/workflows/chain-multi.md

@@ -10,9 +10,9 @@ Use this when extending an existing project with additional shots.
 
 1. Read `.agent/model-profile.md` first.
 2. Read `$OUTPUT_DIR/_index.md` and detect highest completed shot.
-3. Read last completed shot file and extract `SON FRAME`.
-4. Extend `$OUTPUT_DIR/team-plan.json` with new batches, chain bridges, report expectations, model target, preserved `voiceCast`, and preserved or intentionally reset `visual_world`.
-5. Spawn new shot-generator teammates with explicit chain entry from the last `SON FRAME`.
+3. Read last completed shot file and extract either the `SON FRAME` (start-end mode) or final `STORYBOARD PLAN` handoff (storyboard-reference mode).
+4. Extend `$OUTPUT_DIR/team-plan.json` with new batches, chain bridges or storyboard handoffs, report expectations, model target, preserved `voiceCast`, and preserved or intentionally reset `visual_world`.
+5. Spawn new shot-generator teammates with explicit continuity entry from the last completed shot.
 6. Collect batch reports and run specialist validation on the new range.
 7. Ensure `CONTINUITY-REPORT.md`, `SAFETY-REPORT.md`, `STABILITY-REPORT.md`, `DIALOGUE-REPORT.md`, `CHARACTER-REPORT.md`, `COLOR-REPORT.md`, `SEMANTIC-REPORT.md`, `PACING-REPORT.md`, and `DELIVERY-REPORT.md` are refreshed.
 8. Update `$OUTPUT_DIR/_index.md` and mark new range status.
@@ -23,7 +23,7 @@ Use this when extending an existing project with additional shots.
 - Preserve continuity from old range into new range.
 - Preserve existing `speakerKey` bindings and reuse the same `voiceCast`.
 - Preserve `team-plan.json -> visual_world`; if camera/lens/camera-movement/light/shadow/scale world changes, declare `CHAIN BREAK`.
-- Chained `ILK/İLK FRAME` code blocks must contain only `Use SHOT[prev]_END as exact first frame`.
+- $REFERENCE_MODE_CONTRACT
 - If model is `kling-3.0`, keep Start+End transition mode and first/then/finally transition language.
 - If model is `seedance-2.0`, preserve multimodal role assignments and prefer `Extend @video1 by [N]s` when continuing from a source clip.
 - If continuity/safety/stability/dialogue/character-consistency/color-continuity/semantic/pacing/delivery fails, run `.agent/workflows/recover-multi.md` before finishing.

package/packages/multi/content/workflows/generate-multi.md

@@ -43,6 +43,7 @@ Create:
 - teammate assignment map
 - chain bridge descriptions
 - model target and preset (`project.model.target`, `project.model.preset`)
+- reference mode (`project.reference_mode`) and storyboard-reference policy (`storyboard_reference.enabled`, `storyboard_reference.character_reference_sheets`, `storyboard_reference.storyboard_prompt_policy`, `storyboard_reference.max_storyboard_phases`, `recommended_phase_budget`, `provider_reference_tokens`, `continuity_mode`, `provider_file_limits`) when active
 - Kling multi-shot policy (`policy.kling_multi_shot_policy`) with `single-transition` default and `max_custom_shots_per_video: 4`
 - dialogue naming policy (`policy.dialogue_name_policy`)
 - top-level `voiceCast`
@@ -58,12 +59,11 @@ For each batch, spawn a `shot-generator` teammate with:
 
 - `BATCH ID`
 - shot range (`SHOT[X]-SHOT[Y]`)
-- `CHAIN ENTRY FRAME`
+- `CHAIN ENTRY FRAME` or `STORYBOARD ENTRY HANDOFF`
 - output path (`$OUTPUT_DIR/shots/`)
 - report path (`$OUTPUT_DIR/reports/BATCH-REPORT-B[NN].md`)
 - rule: `Respect planned shot count; do not invent extra shots outside your assigned range`
-- rule: `ILK/İLK FRAME must include a code block even when chained`
-- rule: `Chained ILK/İLK FRAME code block must contain only: Use SHOT[prev]_END as exact first frame; new start-frame prompt requires CHAIN BREAK`
+- rule: `$REFERENCE_MODE_CONTRACT`
 - rule: `Follow team-plan.json -> visual_world for perspective/geometry, shadow vector, scale, reflection, physics, anatomy risk, foreground/background coherence, and targeted avoid terms`
 - rule: `When camera movement is present, name it from the 24-move cinematic lexicon in prompt-structure`
 - rule: `Kling mode keeps route metadata and AUDIO PLAN outside the prompt code block; the prompt code block starts with [CHARACTER / SUBJECT CONSISTENCY]`
@@ -74,8 +74,8 @@ For each batch, spawn a `shot-generator` teammate with:
 - rule: `Reuse team-plan.json -> voiceCast and never invent a second speakerKey for the same character`
 - rule: `Every speaking VIDEO section must include Audio Plan and only one active speaker`
 - quality floor:
-  - `ILK FRAME` >= 80 words
-  - `SON FRAME` >= 80 words
+  - start/end image prompts >= 80 words when start-end mode is active
+  - storyboard-reference `STORYBOARD PLAN` has timeline phases capped at $MAX_STORYBOARD_PHASES when active
   - `VIDEO` >= 120 words
   - each coverage prompt >= 70 words
 
@@ -88,7 +88,7 @@ For each batch, spawn a `shot-generator` teammate with:
 5. reject any plan where target shot count feels artificially inflated or compressed relative to the scene-unit rationale
 6. reject any batch that contains speaking shots without `voiceCast` binding or `Audio Plan`
 7. reject any batch that pads pacing with decorative micro-shots or trivial Kling storyboard phases
-8. reject any batch that violates `visual_world`, shadow vector, scale/depth, reflection/physics/anatomy, contextual logic, or chained ILK exact-reuse rules
+8. reject any batch that violates `visual_world`, shadow vector, scale/depth, reflection/physics/anatomy, contextual logic, or the active continuity contract
 
 ## Step 5: Run Specialist Validation (Lead + Specialists)
 

package/packages/multi/content/workflows/generate-storyboard.md

@@ -1,19 +1,96 @@
 ---
-description: Generate storyboard-reference prompt bundles from character reference, storyboard reference, and video brief
+description: Generate character sheet prompts, per-shot GPT Image 2 storyboard prompts, and model-aware video prompt bundles from character references and a video brief
 ---
 
-# /generate-storyboard
+# /generate-storyboard - Storyboard Reference Video Prompt Mode
 
-Read `.agent/model-profile.md`, `safety-compliance`, `reference-locking`, `storyboard-reference`, `semantic-consistency`, `visual-modes`, `audio-design` when needed, and `prompt-structure`.
+## Preconditions
 
-Flow:
+- Character reference image exists.
+- User brief or scenario text exists.
+- Optional storyboard guide images may exist, but they are not required.
+- `storyboard-reference` mode is explicitly requested or configured.
 
-1. Bind `@character1` as `character_identity`, exact lock.
-2. Bind `@storyboard1` as `storyboard_plan`, staging only.
-3. Interpret storyboard panels: 1 continuous arc, 2-4 internal phases, 5+ split shots.
-4. Build `visual_world`, continuity anchors, and model-specific prompts.
-5. Generate Seedance, Veo, and Kling prompt sections for the requested model subset.
-6. Run QA for reference lock, storyboard role separation, model grammar, avoid line, audio plan, and safety.
-7. Write all outputs under `$OUTPUT_DIR`.
+## Read Order
 
-Fail closed on missing refs, empty brief, public figure likeness, trademark/logo risk, unsafe visual requests, missing avoid line, or invalid Kling block structure.
+1. `.agent/model-profile.md`
+2. `.agent/skills/safety-compliance/SKILL.md`
+3. `.agent/skills/reference-locking/SKILL.md`
+4. `.agent/skills/storyboard-reference/SKILL.md`
+5. `.agent/skills/semantic-consistency/SKILL.md`
+6. `.agent/skills/visual-modes/SKILL.md`
+7. `.agent/skills/audio-design/SKILL.md` when dialogue, SFX, ambience, or voiceover exists
+8. `.agent/skills/prompt-structure/SKILL.md`
+
+## Flow
+
+1. Confirm asset roles:
+   - `@character1`, `@character2`, ...: `character_identity`, exact lock
+   - optional `@storyboard1`, `@storyboard2`, ...: external storyboard guides, staging only
+2. Generate one GPT Image 2 character sheet prompt per character reference:
+   - 16:9 production storyboard sheet
+   - front full body, back full body, left profile, right profile, three-quarter full body, close-up face
+   - exact identity, wardrobe, accessories, and visible props
+   - no labels, text, logos, watermarks, alternate designs, or extra characters
+3. Confirm target models: `veo31`, `seedance-2.0`, `kling-3.0`, or a user-provided subset.
+4. Select shot storyboard panel budget:
+   - 4-6 seconds: 1-2 panels/phases
+   - 7-10 seconds: 2-3 panels/phases
+   - 11-15 seconds: 3-4 panels/phases
+   - 5+ distinct phases: split into multiple `SHOTNN.md` files
+5. Build `visual_world`:
+   - environment
+   - lighting
+   - foreground/midground/background
+   - screen direction
+   - continuity anchors
+6. Generate one GPT Image 2 storyboard prompt per shot:
+   - use character sheets as the only identity source
+   - use optional storyboard guide only for composition, blocking, camera, timing, and rhythm
+   - include previous shot handoff and next shot handoff
+   - preserve shared location, lighting, screen direction, action rhythm, and scene continuity
+7. Build model prompt bundle:
+   - Seedance dynamic image mapping: character sheets first, generated shot storyboard next
+   - Veo visual-planning prompt with full audio direction
+   - Kling block-structured storyboard route
+8. Run QA gates:
+   - reference lock
+   - storyboard role separation
+   - model grammar
+   - avoid/negative prompt
+   - audio plan
+   - safety
+9. Write outputs under `$OUTPUT_DIR`.
+
+## CLI Equivalent
+
+```bash
+npx @milenyumai/film-kit generate-storyboard \
+  --character-ref ./refs/character.png \
+  --brief ./scenario.md \
+  --models veo31,seedance-2.0,kling-3.0 \
+  --duration 8 \
+  --aspect 16:9 \
+  --output-dir ./outputs
+```
+
+Optional external storyboard guide:
+
+```bash
+npx @milenyumai/film-kit generate-storyboard \
+  --character-ref ./refs/character.png \
+  --storyboard-ref ./refs/storyboard-guide.png \
+  --brief ./scenario.md \
+  --models seedance-2.0
+```
+
+## Fail-Closed Rules
+
+- Missing character reference: stop and request a valid reference.
+- Empty brief: stop and request a brief.
+- Public figure / real-person likeness / trademark risk: stop or safely anonymize before prompt generation.
+- 5+ storyboard phases: do not compress into one prompt; split shots.
+- Missing GPT Image 2 character sheet prompt: output is invalid.
+- Missing GPT Image 2 per-shot storyboard prompt: output is invalid.
+- Missing `Avoid` / negative prompt: output is invalid.
+- Kling prompt missing required block structure: output is invalid.

package/packages/multi/content/workflows/generate-teammate.md

@@ -25,14 +25,15 @@ For each assigned shot:
 1. Write `$OUTPUT_DIR/shots/SHOT[N].md`
 2. Keep one-file-per-shot contract (main + coverage in same file)
 3. Keep internal continuity across your range
-4. Keep `ILK/İLK FRAME` as a fenced code block even for chained shots
-5. If chained, the `ILK/İLK FRAME` code block must contain only `Use SHOT[prev]_END as exact first frame`; new visual content requires `CHAIN BREAK`
+4. Follow the active reference-mode contract:
+   $REFERENCE_MODE_CONTRACT
 6. Apply safety, avoid line, and audio-direction rules
 7. Reuse `team-plan.json -> voiceCast` and write `Audio Plan` for each VIDEO section
 8. Keep one active speaker per shot
-6. Enforce image prompt contract:
-   - reference-anchored `ILK FRAME` and `SON FRAME` use `REFERENCE LOCK`, `Keep same`, and `Change only`
-   - image prompts stay compact and do not use filler length
+6. Enforce active reference prompt contract:
+   - start/end mode: reference-anchored start/end prompts use `REFERENCE LOCK`, `Keep same`, and `Change only`
+   - storyboard-reference mode: generated character sheet tokens control identity and the generated shot storyboard token controls staging only
+   - visual reference prompts stay compact and do not use filler length
    - `VIDEO` >= 120 words
    - each coverage video prompt >= 70 words
 7. Enforce specificity floor:
@@ -56,11 +57,7 @@ For each assigned shot:
    - maximum 4 custom storyboard shots in one video generation
    - never split one micro gesture or tiny prop move into separate storyboard beats
 10. If model is `seedance-2.0`, enforce:
-   - explicit material roles when references exist (`@image1`, `@video1`, `@audio1`)
-   - identity reference kept separate from camera/action reference when different materials are used
-   - `No scene cuts throughout, one continuous shot.` for uninterrupted beats
-   - timeline segments only when the beat has meaningful internal phases
-   - `Extend @video1 by [N]s` syntax when continuing a reference clip
+   $SEEDANCE_STORYBOARD_CONTRACT
 11. Do not create additional SHOT files beyond the planned batch range
 
 ## Step 3: Run Self-Check
@@ -69,10 +66,7 @@ Validate:
 
 - all assigned files exist
 - each file has main + coverage sections
-- each `ILK/İLK FRAME` section has a code block
-- chained `ILK/İLK FRAME` code blocks contain only exact reuse text
-- word-count floors pass for all prompts
-- image prompt contract passes for main stills
+$SHOT_SELF_CHECK_CONTRACT
 - specificity floor passes for all prompts
 - cinematic camera movement lexicon is used when movement is present
 - semantic consistency floor passes for all prompts

package/packages/multi/content/workflows/safety-check-multi.md

@@ -26,8 +26,8 @@ Check all files in `$OUTPUT_DIR/shots/` or requested range.
 - dramatic units are neither over-compressed nor padded relative to `team-plan.json -> shot_sizing.scene_units`
 
 2. Format
-- main shot contains `ILK FRAME` (or `İLK FRAME`), `SON FRAME`, `VIDEO` (or `VİDEO`)
-- each `ILK/İLK FRAME` section includes a code block (always)
+- main shot follows the active reference-mode format
+- $REFERENCE_MODE_CONTRACT
 - coverage blocks are present in same file
 - avoid line present in every prompt
 - every video prompt has full audio direction
@@ -37,9 +37,8 @@ Check all files in `$OUTPUT_DIR/shots/` or requested range.
 - no dialogue shot contains more than one active speaker
 
 3. Continuity
-- `SHOT[N]_END` aligns with `SHOT[N+1]_START`
-- batch boundaries match chain bridge definitions
-- chained `ILK/İLK FRAME` code blocks contain only `Use SHOT[prev]_END as exact first frame`
+- batch boundaries match chain bridge or storyboard handoff definitions
+- $SEMANTIC_AUDIT_CONTRACT
 
 4. Semantic consistency
 - `team-plan.json` contains top-level `visual_world`
@@ -52,7 +51,8 @@ Check all files in `$OUTPUT_DIR/shots/` or requested range.
 
 5. Quality
 - `VIDEO/VİDEO` prompt >= 120 words
-- reference-anchored `ILK/İLK FRAME` and `SON FRAME` use compact structural format instead of filler length
+- start/end image prompts use compact structural format instead of filler length when start-end mode is active
+- storyboard-reference `STORYBOARD PLAN` phases are explicit and capped at $MAX_STORYBOARD_PHASES when active
 - each coverage video prompt >= 70 words
 - lens/framing/camera movement details are explicit
 - lighting direction/intensity/atmosphere details are explicit
@@ -72,11 +72,7 @@ Check all files in `$OUTPUT_DIR/shots/` or requested range.
 - prompt constraints include `stable background` and `no warping`
 
 7. Seedance-specific gate (when model is `seedance-2.0`)
-- material roles are explicit when references are used (`@image1`, `@video1`, `@audio1`)
-- identity reference is separated from action/camera references when needed
-- uninterrupted beats explicitly say `No scene cuts throughout, one continuous shot.`
-- timeline phases, if used, are editorially meaningful and not decorative micro-beats
-- continuation prompts use `Extend @video1 by [N]s` when they extend a source clip
+$SEEDANCE_STORYBOARD_CONTRACT
 
 7. Visual stability
 - camera position is eye-level or slight low-angle (extreme tilt/dutch/drone flagged)