video-spec-builder

Video Spec Builder collects video requirements through Socratic questioning and produces a standardized video-spec.md containing a storyboard (shot list) for downstream rendering. It is used when a user wants to make a video, promotional piece, product demo, animated short, or social platform content (such as Douyin or YouTube), and also when they want to revise an existing spec — changing shots, adjusting pacing, swapping music, editing subtitles, adding voiceover, or changing transitions. It operates in two modes. The 0-1 mode gathers requirements through deep dialogue and proactively surfaces the rendering layer's full capabilities, since users often do not know what is possible. The iteration mode handles changes to an existing video-spec.md, detecting conflicts with the current spec before updating it.

On startup it scans the project directory for a video-spec document using exact and fuzzy matches (video-spec.md, patterns containing video-spec, storyboard, or the Chinese term for storyboard); finding one enters iteration mode, multiple prompts the user to choose, and none enters 0-1 mode. It also checks for an optional design.md theme file used during the visual-style stage. The skill is built on first principles: capability-first (always asking whether the rendering layer can do it better and describing capabilities in terms of how the picture will look rather than technical names), information density (no empty frames, each shot must carry a clear payload, with guidance on minimum and maximum shot durations), and a preference for live web lookups over stale memory when references, industry conventions, or specific tools are involved.

It enforces strict questioning discipline against four failure modes — guessing questions from memory, amiably accepting vague answers, prematurely stopping when it feels done, and fabricating content the user never said — using a question bank as a calibration constraint rather than a rigid questionnaire. A capability table maps user triggers to renderer features including local TTS voiceover, Whisper word-level subtitle timing, keying/segmentation to transparent WebM, GSAP/anime.js/WAAPI/CSS animation, Lottie, Three.js 3D scenes and shaders, Canvas 2D particles, audio-reactive visualization, text-mark animations, shader transitions, variable and kinetic typography, motion paths, typewriter effects, video compositing/PiP, aspect ratios, frame rates, and output formats. Visual themes are not pre-baked; the renderer (HyperFrames) reads a single design.md at the project root, and the user either picks one of eight HyperFrames presets or supplies/generates a custom design.md in HyperFrames YAML format. Output is written per a template into video-spec.md, and the skill's voice is that of a director — plain, direct, refusing adjectives and avoiding technical jargon with the user.