# Shared filmmaking workflow Use this guide when turning a brief into a planned, generated and reviewed video. It supplies the shared creative standard for the filmmaking skills. Existing CLI routes, provider contracts and production modes still apply. For new agent-led productions, author a complete explicit film plan by default; keep a technical test's plan short. Read the installed `vclaw schema --json` before using flags because older installations may not expose this contract. ## Plan for the intended format Record the purpose, audience and intended outcome before expanding shots. Creative format is separate from `storyboard` or `director` production mode. | Format | Planning and review focus | |---|---| | Narrative | Motivation, cause and consequence, progression and an ending or intentional unresolved outcome. | | Advert | Audience need, message, demonstration and intended action or takeaway. | | Explainer | What the audience should understand, evidence or demonstration and a clear progression. | | Music video | Visual concept, performance ownership, rhythm and sequence connections. | | Montage | Visual or thematic progression and deliberate editing relationships. | | Technical test | Observable behaviour and success criteria; no invented dramatic arc. | Do not require dialogue, conflict in every scene, a fixed shot count or a three-act structure where the project does not need them. Distinguish proposed creative choices from supplied canon. Resolve routine choices within the user's scope; preserve unknown facts rather than silently inventing established history. ## Structured planning contract The source contract lives in [`src/video/film-plan.ts`](../src/video/film-plan.ts). The storyboard input is `--film-plan ` with this wrapper: ```json { "filmPlan": { "schemaVersion": 1, "format": "technical-test", "purpose": "Check a planted standing pose", "audience": "Production reviewer", "outcome": "A readable stationary full-body subject", "style": { "version": "1", "description": "Natural colour, restrained contrast" }, "sequences": [ { "id": "courtyard", "purpose": "Observe stillness", "setting": "Courtyard" } ] }, "shots": [ { "sceneIndex": 0, "direction": { "shotId": "hold-01", "sequenceId": "courtyard", "purpose": "Check feet remain planted", "startState": "Full figure visible, both feet planted", "endState": "Same pose and framing, both feet planted", "subjectAction": "Quiet breathing while standing", "camera": "Locked wide shot", "audioIntent": "Deliberate silence" } } ] } ``` Supply ordinary scene descriptions and character bindings as well. Wrapper entries associate directions with those scene indices; stable `shotId` values identify shots when planning changes. Preserve the identifiers when reordering, and update each transition to the actual next shot. The shared validator checks schema version, supported format, non-empty purpose/audience/outcome, sequence identifiers and required direction fields. With a film plan present, every scene needs a direction. Sequence and shot IDs must be unique, referenced sequences must exist, and a supplied transition must name the next shot with an intent. Optional fields are: - `performance`: entries containing `character`, `objective`, `behaviour` and optional `delivery`. Performers must appear in the scene's character bindings. - `stateBefore` and `stateAfter`: explicit string-valued facts, such as object possession, knowledge, location or injury. These are planning assertions, not automatically verified observations. - `transition`: `{ "nextShotId": "return-01", "intent": "Match the direction of her gaze" }`. - `style`: a version and description for shared visual direction. Legacy storyboards without a plan or shot directions remain valid. Partial direction data without a plan is invalid. These structural checks do not prove that a scene is meaningful, a state change is plausible or a film is finished. The format-specific creative requirements in the table are agent review duties; they are not all separate mandatory schema fields. ## Turn the plan into shot instructions Keep purpose, motivation and story-state bookkeeping in project records. Send the current shot's observable action, starting/ending states, camera direction, applicable visual style and audio intent to its prompt. Do not paste an entire bible into every request. Separate camera motion from performer motion. A quiet performer may be filmed by an energetic camera; a static camera may observe energetic action. Write gaze, body direction, prop hand and spatial relations when they matter. Distinguish location geography from the current composition. Describe only detail the chosen framing, light and motion can make readable. Stable voice and movement canon informs performance; the current objective, pose, fatigue and reaction determine its expression. A habitual gait is not a walking instruction for a seated character. Offscreen audio needs an explicit audio role; do not invent an onscreen body to satisfy the visible-performer list. Storyboard authoring validates this contract, and the execution runtime validates it before creating tasks. The execution runtime appends shot direction to the compiled prompt. The current prompt helper emits visual style, start/end, subject action, camera, performance behaviour/delivery and audio intent. Purpose, objective, state maps and transition intent remain planning/review context. This guide does not claim all alternative generation routes consume those fields or enforce the plan. Check actual compiled requests and route evidence before reporting coverage. Normal execution, pool/auto-chain payload preparation and the render-scenes runner use the shared execution compiler. `create` and clone authoring still produce legacy storyboards; author the explicit film plan with `storyboard` when using this workflow. Standalone `batch-submit` consumes its own batch manifest, not this planning contract. `cinema-deliver` uses a separate Cinema delivery contract and refuses existing film-plan projects with an actionable route error; use normal assembly, film-edit review and publish for those projects. ## References, style and precise edits Follow the [staged cinematic reference workflow](CINEMATIC_REFERENCE_WORKFLOW.md) when the project uses that profile. Keep shared identity separate from wardrobe, sequence setting, lighting and style. A reference can establish identity, construction, material, geography or a starting frame: state which role it has. Use actual attached assets and adapter citations, not copied Higgsfield tags. Keep approved earlier identity versions when a permanent appearance change is introduced. Temporary styling and expression variations should not silently replace identity canon. Record which state the shot uses. Versioned style text alone does not invalidate footage or guarantee a consistent visual result. For edits, state the requested change and what must remain: for example, keep the glove's construction but change its material. Inspect the result for unwanted changes. Prefer a direct build with existing usable references; create an extra garment or prop plate when a demonstrated defect justifies it. No wording guarantees pixel-perfect preservation. Planned prompt packets also save local reference-byte evidence per scene. If an attached file changes, disappears or becomes available after compilation, execution identifies the dependent scenes and requires prompt rebuilding. Remote reference bytes remain explicitly unverified. This covers packet attachments, not a general project dependency graph. Product-category prompt compilation and the specialised cinema-delivery route currently reject explicit film plans with an actionable error. Use the supported cinematic planning route; use `advert` or `explainer` as the creative format where appropriate. ## Review shots, joins and the actual delivery Use the existing [motion review](MOTION_REVIEW.md) for individual clips. Also inspect adjacent shots for action, gaze, screen direction, framing, geography, relevant story state and sound. Record deliberate discontinuities instead of mistaking every jump for a defect. Watch the full export with its delivery soundtrack to judge pacing, clarity, opening/ending and sound. Record the inspected media/version, result, reasons and unresolved limitations. Changed footage, order, trims or soundtrack require review of affected joins and the delivery. Do not carry an earlier approval over an unreviewed edit. ### Version-bound film review The film-edit review source is a JSON document with paths inside the project: ```json { "clips": [ { "shotId": "hold-01", "path": "outputs/scene-0.mp4", "inSeconds": 0, "outSeconds": 6 } ], "exportedMediaPath": "outputs/final.mp4" } ``` If there is a separate delivery soundtrack, also supply `"soundtrack": { "path": "audio/mix.wav", "offsetSeconds": 0 }`. Paths are resolved inside the project; copy external media into it first. The review loader hashes actual files rather than trusting caller-supplied hashes. The fingerprint includes ordered clips, trims, soundtrack/offset and the export. For a requested edit, the source can additionally carry `"editIntent": { "change": "Darken the sky", "preserve": ["Face", "Wardrobe"] }`. `change` must contain text; `preserve` must be an array of non-empty strings (an empty array explicitly declares no preservation constraints). This intent is stored and included in the fingerprint: changing the requested edit or its preservation constraints requires fresh review. It documents the edit; it does not itself run an image/video editor or prove those constraints were preserved. Inspect the current fingerprint and status without a verdict, then record observations against the same source: ```bash vclaw video review --project --film-edit vclaw video review --project --film-edit --film-review --verdict pass ``` Use the installed command schema for allowed verdict values. Do not use `pass` until the actual playback supports it. Review JSON contains `fingerprint`, `reviewer`, `method` (`full-playback` or `sampled-frames`) and `checks`, each with `criterion`, `verdict` and `reason`. The five criteria are `story`, `pacing`, `continuity`, `audio` and `technical`; each check is `pass`, `fail` or `unreviewed`. Only a full playback with all five passing can certify the edit. Incomplete observations may be saved without approving it. History is retained in `film-edit-reviews.json`; the newest observation governs. Status reads rehash current media, so an old approval becomes stale when its fingerprint changes. The film-plan review/publish integration requires current film-edit evidence for a pass. This is version binding and recorded human/agent judgement, not automatic visual analysis or proof that the supplied edit manifest accurately describes every editing decision. Check the actual export. Do not claim review enforcement across other surfaces without verifying their route. The review station displays the current film-review status and checks completion against the same saved media evidence before writing completion artifacts; drafts remain saveable. Drafts can be exported for review. Prompt promises, successful submissions, sampled stills and passing technical checks do not establish finished creative quality. Still images cannot certify audio or lip-sync. Music performances follow the [recording-led lip-sync guide](https://github.com/davendra/videoclaw-v3/blob/main/skills/rap-avatar-mv/references/recording-led-lipsync.md) and the existing audio-mode contract. ## External Manager Loop VideoClaw remains the external agent's target CLI, not an embedded agent orchestrator. For an authorised substantial project: 1. Define bounded phases, measurable completion criteria and material assumptions. 2. Delegate independent work where authorised and useful, with ownership boundaries and required evidence; otherwise implement it directly. 3. Inspect actual changes and evidence before accepting completion. Resolve defects and run verification appropriate to the change. 4. Maintain one lightweight saved progress page: phase status, criteria, evidence, blockers, decisions and next action, plus completed/total and a timestamped chart of verified completions. 5. Treat repeated attempts without new evidence as a stall. Diagnose and change approach: simplify action, alter framing, use a cutaway, reuse or edit. Do not resubmit the same failing request indefinitely. 6. Read saved state after interruptions and continue the next incomplete phase. Honour accepted creative decisions and prior authorisation; ask only when missing information or authority prevents meaningful progress. 7. Finish when the agreed outcomes and required verification are delivered. Report locations, verification and limitations; avoid optional scope expansion. A completed counter reflects verified outcomes, not generation count. Historical recipes asking for confirmation at every step do not override explicit user instructions to manage routine decisions autonomously. Actual spend and provider authorisation requirements still apply within the agreed scope. ## Source adaptation The reviewed filmmaking notes supply useful techniques, not universal provider facts. Photorealism, grey plates, closed-lip expressions, handheld movement, teal/amber grading, specific lenses and fixed block durations are context-dependent choices. Retain the user's format, style and model choices. Discover route limits and settings from the installed contract, and test claims against real output.