/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:

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 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