--- name: hyperframes-video description: Use when the user wants to generate a rendered promotional video (not just a script) for a PR, feature, or product change — produces a HyperFrames HTML composition, iterates with `npx hyperframes preview`, and outputs mp4 + poster for X/LinkedIn/social. ---

# HyperFrames Video

Turn a PR into a rendered short-form promo video with a hook, code moments, and CTA, using HyperFrames. Iterate with live preview via `npx hyperframes preview`, then render `video.mp4` and `poster.jpg` for X/LinkedIn/social.

Unlike `/video-script` (which produces a textual script), this skill produces the actual video file. Counterpart to the `remotion-video` skill — same workflow shape, same storytelling rules, but built on the HyperFrames stack instead of Remotion.

## Triggers

Invoke when the user says: "make a video for this PR", "hyperframes video", "render a promo video", "video for X/LinkedIn", or when selected from `/marketing-pipeline`.

## How this skill relates to the hyperframes ecosystem

This skill carries only the promo-video-from-PR logic: input resolution, narrative planning, motif derivation, hook enforcement, scene-plan auditing, render-time gates. The mechanics of authoring HyperFrames compositions, running the CLI, animating with GSAP, and installing registry components are owned by separate skills you should invoke when their topic comes up:

- **`hyperframes`** — composition authoring rules: DESIGN.md gate, Layout Before Animation, palettes, transitions, typography, motion principles, captions, audio, TTS. - **`hyperframes-cli`** — every `npx hyperframes <command>` (init, lint, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, compositions, docs, benchmark). - **`gsap`** — GSAP timeline patterns, easing, stagger, performance, position parameter, labels, nesting, playback. - **`hyperframes-registry`** — registry blocks/components and how to wire them via `hyperframes add`.

When this skill needs to do something covered by one of those skills, defer to that skill's instructions rather than re-deriving them here.

## Process Flow

``` Resolve input → Phase 1: Discovery → Phase 2: Configuration → Phase 3: Narrative planning → Phase 4: Scaffold → Phase 5: First draft + iterate → Phase 6: Render → Phase 7: Cleanup ```

Phases 1, 3, 5, and 7 have explicit approval gates. Phase 2 is an interactive Q&A. Phase 5 is a freeform iteration loop that can run many rounds.

## "Use Sane Defaults" / "Don't Ask Questions" — What It Does and Doesn't Override

When the user invokes the skill with phrasing like *"use sane defaults"*, *"don't ask questions"*, *"non-interactive"*, *"just ship it"*, or any equivalent — interpret it precisely:

**It DOES override (skip the prompt, pick the default):**

- Q2.1 duration → derive from scope using the ladder in Q2.1 (still in the 15–60s window); pick the midpoint of the matched scope band and proceed without asking - Q2.2 aspect ratio → 16:9 landscape - Q2.3 project location → `marketing/<feature-slug>/hyperframes/` - Q2.4 brand *confirmation* (the "use these / customize / provide your own?" question) - Phase 1.4 scope confirmation - Phase 3.0 motif confirmation - Phase 3.1 story-pattern confirmation - Phase 3.3 scene-plan approval - Phase 5 freeform iteration loop (the "what would you like to change?" prompt)

**It does NOT override (must always run regardless):**

- Brand color/font/logo **scanning** (Q2.4 detection — see HARD-GATE in Q2.4). Hardcoding colors from training-data assumptions about a project is a forbidden shortcut. - Phase 5 **preview** (HARD-GATE in Phase 5). Even in fully unattended mode, `npx hyperframes preview` must start and the studio URL must be opened in the browser before the render runs. The user can interrupt; the agent must not pre-decide for them. - Phase 6 pre-render audits (storytelling, hook rules, motif presence, pacing variance, value-prop timing, contrast). These exist to prevent shipping a generic video. - Phase 7 cleanup question (the user owns project disposition).

If you're tempted to skip a HARD-GATE because the user "said no questions" — re-read this section. The user said no *questions*, not no *gates*.

## Input Resolution

Resolve the argument (if provided) in this order:

1. Path to a marketing brief (`.md` containing "Executive Summary" or "Key Messages") → **marketing brief** 2. Path to a blog post (`.md` with blog post structure) → **blog post** 3. Path to a changelog → **changelog** 4. GitHub PR URL or `#\d+` pattern → **PR** 5. Matches `<ref>..<ref>` or `<ref>...<ref>` (alphanumeric + `/`, `_`, `.`, `-` on each side) → **git ref range** 6. Resolves to an existing file/directory → **codebase feature** 7. Otherwise → **freeform text**

If no argument is provided, ask: "What should the video be about? You can provide a PR URL/number, marketing brief, blog post, changelog, git ref range, file/directory path, or just describe the feature."

When invoked from the pipeline with a PR *and* upstream marketing-brief/blog-post paths, read both: PR for technical accuracy, upstream content for positioning/tone.

(Detailed phase specs begin below — see Phase 1.)

## Phase 1: Discovery

### Step 1.1 — Check hyperframes skills availability

Attempt to invoke the `hyperframes` and `hyperframes-cli` skills via the Skill tool. If either is unavailable, present:

> "The `hyperframes` / `hyperframes-cli` skills aren't installed. Options: > a) proceed with baseline knowledge (quality may be reduced) > b) wait while you install them > c) cancel"

If the user picks (a), emit a warning in the final summary noting reduced quality.

### Step 1.2 — Analyze input

| Input type | What to read | |---|---| | Marketing brief | positioning, key messages, audience | | Blog post | headline, narrative, examples | | Changelog | highest-impact entry | | PR | `gh pr view <n> --json title,body,files,labels`, diff (`gh pr diff`), commit messages, linked issues | | Git refs | `git diff <range>` + `git log <range> --oneline` | | Codebase path | read the specified files/directories | | Freeform | parse the user's description |

For PRs with 20+ files, filter to user-facing changes only — skip `tests/`, `ci/`, `.github/`, lockfile changes, dep bumps.

**Error handling:** - `gh` not available → tell the user, ask for an alternative (diff file, freeform description) - Invalid PR/ref → ask user to verify - File not found → ask for the correct path

### Step 1.2a — PR deep analysis (when input is a PR)

When the input is a PR, the brief table in Step 1.2 is not enough. PR bodies are routinely vague, outdated, or focused on implementation rather than user value, and a video built off the body alone tends to overclaim or miss the headline angle entirely. Before continuing to Step 1.3, run this structured analysis and produce a written **PR analysis block** that becomes the source of truth for Steps 1.4 (scope confirmation), Q2.1 (duration ladder), and Phase 3 (narrative planning).

**Mandatory steps — do all of them:**

1. **Pull metadata and identify the base branch.** ``` gh pr view <n> --json number,title,body,baseRefName,headRefName,files,labels,commits,additions,deletions ``` Record `baseRefName` (usually `main` / `master` / `develop`) — that is the diff reference. `gh pr diff <n>` automatically compares the PR head against this base.

2. **Pull the full diff against the base.** ``` gh pr diff <n> ``` For very large PRs (>500 lines or >20 files), also list changed files via `gh pr view <n> --json files`.

3. **Filter to user-facing surfaces.** Ignore (do not let these shape the headline angle): `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `__mocks__/`, `ci/`, `.github/`, lockfiles, dep bumps without behavior change, generated/build artifacts (`dist/`, `build/`, `.next/`), and formatting-only diffs. What remains is the user-facing surface of the PR.

4. **Enumerate the public-API delta.** From the filtered diff, list every change a user could observe or write code against: - New, renamed, or removed `export`s (functions, types, components, hooks, classes, constants) - New CLI commands, flags, or environment variables - New routes, endpoints, or event names - New config keys or schema fields - Changed default values for existing public surfaces - Changed error messages, log shapes, or response shapes the user could rely on

Grep the diff for added lines beginning with `export `, new top-level `function`/`class`/`const` in `src/` / `lib/` / `packages/*/src/`, new files in those trees, and changes to public type signatures. **If you cannot point at a line in the diff for a claimed API, the claim is wrong — drop it.**

5. **Enumerate the behavior delta.** Beyond API surfaces, list user-visible behavior changes: UI elements added/changed (with file references), CLI / network output that looks different, side effects firing under new conditions, removed limitations, performance characteristics that changed.

6. **Write the before / after value statement.** Exactly two sentences, both grounded in concrete diff evidence: - **Before:** *"Before this PR, a user who wanted to ___ had to ___."* - **After:** *"After this PR, the same user can ___."*

The "had to" half must be a real prior workflow you can describe — copy-pasting an adapter from the docs, installing a second package, writing boilerplate, hitting an error, switching to a different tool. If the honest "Before" sentence is *"they could already do this"*, the PR has no user-visible value delta — see step 8.

7. **Cross-check the PR body against the diff.** Walk the body's claims and the diff side-by-side: - **Body claims a feature → does the diff confirm?** If the body says "added X" and the diff has no public surface for X (only tests, only docs, only internal helpers), flag it: *"PR body claims X but the diff doesn't expose X to users — should I shift the angle to <what the diff actually shows>?"* - **Diff shows multiple distinct features → body emphasizes one?** Flag the others as candidate angles: *"The body emphasizes A, but the diff also adds B and C. Which is the headline angle?"* - **Body is empty / boilerplate / `[BLANK]`?** Infer from the diff; make the inferred angle explicit and confirm with the user at Step 1.4. - **List "surprises"** — anything in the diff *not* mentioned in the body that affects user-visible behavior. Surprises are often the real story.

8. **Bail-out check: is this PR actually user-visible?** If after steps 4–6 you cannot name a single new thing the user can do or observe, the PR is not video-worthy as a feature launch. **Stop and ask the user:** > "This PR looks like an internal refactor / test-only / dep-bump PR — I can't find a user-visible value delta. Options: > a) shift to a performance / DX / cleanup angle if numbers support it > b) pick a different PR or input > c) cancel"

Do not invent a feature angle to fill the gap. A confabulated angle wastes a full iteration round and destroys user trust on the very first draft.

9. **Produce the PR analysis block.** Write the result as a short structured block before continuing to Step 1.3. This block — not the PR body — is the source of truth for everything downstream:

``` PR analysis — #1234 "Add fromZodSchema support" Base: main · Head: feature/zod-schema · Author: <login> User-facing files: 3 (packages/core/src/index.ts, packages/core/src/zod.ts, packages/core/src/types.ts) Filtered out: 5 test files, 2 doc files, lockfile

Public-API delta: + export function fromZodSchema(schema: ZodSchema): StandardSchema + export type ZodCompatibleSchema ~ default error code for ZodError changed: 'invalid_type' → 'STANDARD/type'

Behavior delta: - Users importing zod schemas no longer need a manual adapter. - Error messages from zod paths now use the StandardError shape.

Before / after: Before: copy a 15-line