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. The storyboard input is --film-plan <json-path> with this wrapper:

{
  "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 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 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:

{
  "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:

vclaw video review --project <slug> --film-edit <source-json-path>
vclaw video review --project <slug> --film-edit <source-json-path> --film-review <review-json-path> --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 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.