/generate-video

name: generate-video
description: "Create a short video from a concept through staged first frame, last frame, motion and render. \"turn this concept into a video\""
argument-hint: "[--post <id>] [--script-only] [--thumbnail]"
effort: high
user-invocable: true

/socialforge:generate-video — Video Production Kit

> **Script location.** If your host does not set `${CLAUDE_PLUGIN_ROOT}`, the scripts are in this plugin's `scripts/` folder, next to `skills/`. Run them with Python 3.10 or newer: `python`, or `python3` where `python` is not found (macOS, many Linux systems).

Generate video production assets through a 5-stage human-in-the-loop pipeline. Each stage requires user approval before advancing.

Context efficiency

Asset-heavy skill. **Grep before Read** the asset catalog (`${CLAUDE_PLUGIN_DATA}/socialforge/brands/<brand>/asset-index.json`) — never list the asset directory. Reference generated images / videos by path, not by loading metadata. Brand profile loads once per session.

Prerequisites

• Credentials must be configured via `/socialforge:setup`:
• **Vertex AI** (registry alias `latest-image-google`) — used for first-frame and last-frame keyframe generation
• **WaveSpeed API** (registry alias `latest-video-wavespeed`) — used for image-to-video generation
• Models are never named in this skill: each alias above is resolved to a current model id when the script runs. To see what they resolve to today, run `python "${CLAUDE_PLUGIN_ROOT}/scripts/generate_video.py" --list-models` (video) or `python "${CLAUDE_PLUGIN_ROOT}/scripts/resolve_model.py" --aliases` (every alias).
• Brand profile must be active (`/socialforge:switch-brand` if needed)
• Calendar must be parsed (`/socialforge:parse-calendar`) with video posts identified

Quote, then go (before any paid call)

Generation spends provider credits, so the first paid call waits for a quote and an explicit go. This skill states no price and the model registry stores none: `price_book.py` is the only source, and it refuses rather than guesses.

1. List what is about to be generated: for each paid call, the registry alias (`resolve_model.py --alias <alias>` gives the current model id), the provider, and the units (images, or seconds of video, plus any option that changes the price, such as synchronised audio). The first paid call is Stage 2, so quote the whole chain (the keyframes of Stages 2 and 3 and the clip of Stage 4) once, before Stage 2. Quote only providers that can run here: run `generate_video.py` without `--generate-video` first and read its `routing` block. `provider` is the one to quote; `unavailable` lists the providers that cannot run on this setup and why (Veo needs Vertex AI, so a Gemini API key alone cannot make Veo clips); `fallbacks_if_quoted` lists the others that could run. A fallback you want available is quoted as its own line, and the total you show is the worst case. 2. Quote it:

python "${CLAUDE_PLUGIN_ROOT}/scripts/price_book.py" --action quote-batch --items '[{"model":"<resolved model id>","provider":"<provider>","units":<n>,"label":"<post id and stage>"}]'

A single item can use `--action quote --model <id> --provider <provider> --units <n>`. If the quote exits non-zero or lists a blocked item, stop: run `/socialforge:price-check` to look the missing price up, then quote again. 3. Show the user the total, each line, its **source URL**, and how old the price is (a price older than 24 hours is stale and is refused; it must be looked up again):

Estimated cost: <total_usd> USD for <n> generations. Prices from <source>, <age_hours> h old (valid for 24 h).
Type "go" to generate. Anything else cancels.

4. Continue only on an explicit `go` for exactly this list. Anything else, including silence, cancels and nothing is generated. If the list changes (more posts, another model, an added option), quote again and ask again. A quote is never approval (`approved_to_run` is always `false`). 5. Pass exactly the providers that were quoted: `--quoted-providers kling` (or `kling,veo`). Only those can run. If the first provider fails and the next one was not quoted, the run ends with `video.status: NEEDS_REQUOTE` and **nothing was spent** on it: show the user the new line and total, wait for a new `go`, and never widen the list yourself.

The 5-Stage Pipeline

Stage 1: Video Concept + Script (no API call)

Claude generates **2-3 video concept ideas** based on the post brief, brand voice, and platform requirements. Each concept includes:

• Working title and hook
• Visual narrative arc (opening, middle, close)
• Suggested duration and pacing
• Tone and style direction

The user picks one concept (or requests refinements). Then **fill the script scaffold** (`generate_script` in generate_video.py) from the chosen concept and the post's actual brief, in the brand's voice — every `[FILL]` replaced, no placeholder survives into Stage 2. The scaffold enforces the structure; this pass supplies the craft, under four rules the scaffold carries with it:

1. **Hook first, never the logo.** The open earns attention with the single most arresting thing the brief supports; the brand mark lives as the corner watermark and in the end card. Three seconds of logo reveal is the classic retention killer this pipeline used to scaffold by default. 2. **Payoff per scene.** Every scene's `payoff` field states what the viewer has gained by the time it ends. A beat that only sets up the next beat is where viewers leave — give it a payoff or fold it. 3. **The pairing rule.** The hook's text overlay and the post's caption (written by adapt-copy) do different jobs and never echo. Check against the adapted copy if it already exists for this post. 4. **Compliance before credits.** Run the filled script's narration and overlay text through `compliance_check.py` BEFORE Stage 2 — a banned phrase caught in a script costs nothing; caught in a rendered video it costs the whole g