| name | video-essay |
| description | Shorts-first video essay pipeline. Three shorts enter, one wins at 24h, becomes a 10-min long-form. Use when the user says "video essay", "make a video about X", "start an episode", or invokes /video-essay. This is the dispatcher — it reads current episode state and routes to the right stage-specific sub-skill. |
video-essay — dispatcher (routes to stage-specific sub-skills)
You are orchestrating a pipeline that uses short-form video as a real-world A/B test before committing to long-form production. The pipeline is split across 5 stage-aligned sub-skills. Your job as dispatcher is to detect which stage the current episode is in and invoke the right sub-skill.
Stage map — when to invoke each sub-skill
| If the state is… | Invoke | What it covers |
|---|
No episode slug yet OR packages.md absent | ve-intake | Stages 0–3: preflight → topic → angles research → pick 3 → write packages.md |
packages.md exists, shorts/{A,B,C}/video.mp4 incomplete | ve-produce | Stages 4–5: per-angle hook research → 3 shorts rendered (script/audio/images/covers/video) |
All 3 shorts/*/video.mp4 exist, upload_result.json absent or incomplete | ve-publish-shorts | Stages 6–7: LLM Bible-compliance gate → publish to YT/IG/TikTok |
Published ≥24h ago, shorts_metrics.json absent | ve-analyze | Stages 8–9: pull 24h metrics → winner declaration → promotion decision |
winner set in packages.md, long-form video.mp4 absent | ve-longform | Stage 10: title/thumb lock → deep research → script → audio → images → assemble → publish long-form |
Principles (apply at every stage)
- Separation of concerns. You do all writing and judgment. Python scripts (
ve-* commands) do all deterministic work. Never wrap ffmpeg or write API glue — invoke the existing scripts.
- The algorithm is the judge. For shorts, no LLM picks the winner — real viewers do at 24h via
ve-analyze-shorts. The LLM judge only enforces Bible compliance pre-publish.
- Always promote the best-of-3. Even on weak signal. User can override at Stage 9 if the topic doesn't deserve a long-form.
- Flow version: v4.0 (shorts-first, 2026-04-15+). Episodes 001–004 shipped under v3.1 (long-form first); 005+ uses this flow.
Project context
- Plugin root:
$CLAUDE_PLUGIN_ROOT (set by session hook). Contains pipeline/, references/, bin/.
- Episodes:
$EPISODES_DIR/<NNN-slug>/ (set by user's EPISODES_DIR userConfig value).
- Pipeline CLIs on PATH:
ve-doctor, ve-audio, ve-images, ve-thumbnail, ve-assemble, ve-qa-images, ve-publish-shorts, ve-analyze-shorts, ve-publish-youtube.
- Canonical references (read as needed):
references/shorts_bible.md, references/shorts_script_judge_rubric.md, references/shorts_angles_template.md, references/style_guide.md, references/judge_rubric.md, references/script_judge_rubric.md, references/deep_research/SKILL.md, references/env_setup.md.
Deep-research dependency
The pipeline vendors a copy of the deep-research skill at references/deep_research/SKILL.md. Sub-skills invoke it inline via the Agent tool rather than depending on the standalone deep-research plugin being loaded. If the standalone skill IS loaded in-session, the Skill tool is a convenience shortcut — identical output.
Usage
- Fresh topic: user says "video essay about X" → invoke
ve-intake with the topic.
- Mid-pipeline resume: user says
/video-essay with a slug or during a conversation about an in-progress episode → read the episode directory, match against the Stage map above, invoke the corresponding sub-skill.
- Explicit stage: user says "let's publish the shorts" / "analyze the 24h data" / "start the long-form" → invoke the named sub-skill directly.
- Preflight is non-negotiable.
ve-intake runs ve-doctor --live as its first step. Never skip it.
What to avoid
- Never let an LLM pick the winning angle — that's the algorithm's job at Stage 8.
- Never skip per-angle hook research (Stage 4).
- Never post shorts at the same minute — stagger ~15 min (handled by
ve-publish-shorts).
- Never auto-advance past user checkpoints: after Stage 3 (angles), Stage 6 (shorts review), Stage 9 (promotion decision), and every 10x substage.
Migration notes (episodes 001–004)
Episodes 001–004 shipped under v3.1. Their episodes/<slug>/short/ directory (singular) and publish_short.py flow remain functional. New episodes use shorts/{A,B,C}/ (plural) and the v4.0 flow above.
