| name | generate-video |
| description | Generate short-form video via a 5-stage human-in-the-loop pipeline — concept, first frame, last frame, motion, final render — with approval at every stage before credits are spent. Triggers on "/generate-video", "make a video", "video for P12", "animate this image", "reel from this", "image to video", "video post", or any calendar post whose content_type is video, reel, or story. Models and prices are resolved live, never hardcoded; sound costs extra — quote it first. |
| argument-hint | [--post <id>] [--script-only] [--thumbnail] |
| effort | high |
| user-invocable | true |
/socialforge:generate-video — Video Production Kit
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 (Nano Banana Pro / Gemini 3 Pro Image, resolved via
latest-image-google) — used for first-frame and last-frame keyframe generation
- WaveSpeed API — used for image-to-video generation via Kling v3.0 Pro
- Brand profile must be active (
/socialforge:switch-brand if needed)
- Calendar must be parsed (
/socialforge:parse-calendar) with video posts identified
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:
- 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.
- 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.
- 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.
- 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 generation chain. Claims in narration follow the same rules as claims
in copy: sourced or absent.
The user approves the filled script before any generation spend.
Stage 2: First Frame Generation (Vertex AI / Nano Banana Pro)
Generate 2 first-frame options based on the chosen concept. These set the opening visual and establish the look and feel.
- Images are shown inline in the terminal for immediate review
- User selects one or requests a regeneration with adjusted direction
Stage 3: Last Frame Generation (Vertex AI / Nano Banana Pro)
Generate 2 last-frame options that complete the visual narrative arc, matching the approved first frame.
- Images are shown inline in the terminal for immediate review
- User selects one or requests a regeneration with adjusted direction
Stage 4: Video Generation (WaveSpeed / Kling v3.0 Pro)
Using the approved first and last frames, generate 2 video versions via WaveSpeed's Kling v3.0 Pro image-to-video endpoint (3-15 seconds).
- A video gallery is opened in the browser for side-by-side comparison
- User selects the final version or requests a regeneration
Stage 5: Post-Process, Save & Deliver
After the user picks the final video, post-processing runs before saving:
- Logo watermark is automatically added to the video via video_postprocess.py
- Subtitles: User is asked whether to burn subtitles into the video (optional). SRT was already generated from the script and is saved separately regardless.
- Background music: If the video has no audio (sound=False in Kling config), user is asked whether to add background music (optional).
- Platform resize: Video is automatically resized for each target platform (letterbox/pillarbox with black padding, no stretching)
Save all final assets to {post_folder}/ -- keyframes in keyframes/, video versions in versions/, platform-resized final videos in final/:
- Video files (.mp4) — post-processed and resized per platform
- Script — timestamped narration/dialogue
- Storyboard — shot-by-shot visual breakdown with keyframe references
- SRT subtitle file (.srt) — for captioned playback
Output Per Video Post
| Asset | Format | Always Generated |
|---|
| Script | Markdown | Yes |
| Storyboard | Markdown + keyframe images | Yes |
| Thumbnail | PNG/WebP (via compose-creative) | Yes |
| First frame | PNG | Yes (Stage 2) |
| Last frame | PNG | Yes (Stage 3) |
| AI Video Clip | MP4 via WaveSpeed / Kling v3.0 Pro (image-to-video, 3-15 seconds) | If pipeline completed |
| SRT subtitles | .srt | If video generated |
Video Types
| Type | Duration | AI Generation | Production Notes |
|---|
| hero_video | 30-90s | Partial — AI generates 3-15s hero clip; full version needs filming | Script + storyboard + AI teaser clip |
| mini_case_study | 30-60s | Yes — AI animation from keyframes | Full pipeline supported |
| short_reel | 15-30s recommended (Instagram Reels and YouTube Shorts accept up to 3 min) | Yes — ideal for AI generation | Full pipeline supported |
| story | up to 60s per frame (Instagram Stories) | Yes — image-to-video animation | Full pipeline supported |
| talking_head | 30-120s | No — needs filming | Script + storyboard only (use --script-only) |
Rules
- Every stage requires explicit user approval before advancing
--script-only skips Stages 2-4 and generates script + storyboard only--thumbnail generates a video thumbnail via compose-creative (independent of the pipeline)- AI video clips are never auto-saved; user must confirm the final selection
- Thumbnails use the same creative mode system as static images
- All assets save to
{post_folder}/ -- keyframes in keyframes/, video versions in versions/, final video in final/
Timeout & Fallback
- AI video generation (Stage 4): 300-second timeout (Kling v3.0 Pro can take several minutes for high-quality output)
- Keyframe generation (Stages 2-3): 60-second timeout per image
- If video generation fails or times out, deliver script + storyboard + keyframes as fallback
