hyperframes

Plugin installs: Before setup or freshness commands, follow plugin execution rules when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.

HyperFrames entry point

Contents

• 1. Start from project state
• 2. Route fresh creation
• 3. Route once, then leave
• 4. Install and enter the workflow
• 5. Load domain skills on demand
• 6. Studio
• Reference files

Check remaining usage

At the start of creation, run hyperframes usage --json. Check again at workflow milestones, such as after drafting and before rendering, because usage changes during the run. Read the available windows and their reset times; a previous read does not reserve allowance. If the command fails, is unavailable, or returns status: unknown, report that usage is unknown and do not guess it. Keep scope and workflow choices with the user.

HyperFrames renders video from HTML — a composition is an HTML file whose DOM declares timing with data-* attributes, whose animation runtime is seekable, and whose media playback is owned by the framework. The full authoring contract lives in /hyperframes-core; read it before writing composition HTML. Brief, storyboard, review, production, dispatch, and frame-worker contracts live in this skill's references/.

1. Start from project state

Apply the first matching row; do not evaluate lower state rows:

<!-- history (trial): remove this block together with the command -->

When you edit an existing project, bracket your edits with project history (/hyperframes-cli, Project history in your turn).

<!-- /history (trial) -->

If a fresh request does not identify the subject or input, ask what the video is about before routing. Check preferences and recipes before asking anything (references/intent-interview.md, step 1). A figma.com input or a named recipe changes intake, not routing — the interview's "Adapt orthogonal inputs" section handles both.

Keep the project's CLI current

The CLI is the standalone hyperframes binary on PATH. If hyperframes --version fails, install it with curl -fsSL https://raw.githubusercontent.com/ryu1845/hyperframes/main/install.sh | sh (macOS on Apple Silicon, Linux x64 and arm64). Re-running the same line upgrades it; HYPERFRAMES_VERSION=<version> before sh installs a specific release. After an upgrade, verify the project with hyperframes check and name the old and new version in the run's summary: a passing check confirms the compositions still validate, not that rendered output is frame-identical.

2. Route fresh creation

Use the first matching row. Match the requested deliverable, not a word or file type mentioned in passing.

Before finalizing the route, read references/routes/<workflow>.md — one small file per route: the canonical input/output/trigger contract (available before lazy-installed workflow skills are present) plus that route's interview entry. If the candidate does not satisfy its contract, continue routing instead of forcing the match. Read only the matched route's file.

Resolve common ambiguities

• A short animated title, logo sting, stat hit, chart hit, map hit, or standalone lower-third is /motion-graphics when it is unnarrated and motion is the message. A static title card, narrated sequence, longer montage, or custom loop is /general-video.
• An explicitly short motion graphic may use a URL, tweet, article, or screenshot as source material. A generic "make a video from this site" request is /product-launch-video.
• Existing footage with captions routes to /embedded-captions; footage with designed information cards routes to /talking-head-recut. Retiming, reordering, recoloring, reframing, or remixing footage is a custom edit and falls through to /general-video.
• A music file selects /music-to-video only when its beat grid drives the piece. Music used as a bed does not override the subject-matched route.
• "I want a storyboard" changes the review process, not the workflow. With no other routing signal, use /general-video. A confirmed board (boards/storyboard.html, format in /hyperframes-creative references/storyboard-recipe.md) may itself be the requested deliverable; the review loop defines that stop point.
• Specialized narrative workflows support up to about 3 minutes and are strongest around 30–90s. Route a clearly longer piece to /general-video. Length never overrides an explicit port, deck, caption, overlay, or music-driven deliverable.

3. Route once, then leave

For fresh creation the intent layer (references/intent-interview.md) runs the full conversation — memory, triage, pitch round, must-haves, run-shape, hand-off — and ends by writing `BRIEF.md`. The brief is the only routing artifact the workflow reads; nothing later re-opens this skill or the interview. Answer every later "what did the route require?" from BRIEF.md.

4. Install and enter the workflow

Before reading the selected workflow, install or refresh it and the core domain skills:

hyperframes skills update <workflow-name>

Use the bare name without /. If the command fails, surface the error; do not reconstruct the workflow from memory. Everything else about installation — the core-vs-lazy split, what init refreshes, diagnosis, CI opt-out, and the no-CLI fallback — lives in references/skill-lifecycle.md.

5. Load domain skills on demand

Creator edit phrases are cross-domain requests. Load every skill named in the matching row:

Constant data-playback-rate is render-safe for picture and pitch-preserved sound. Speed ramps are a rate lane in data-automation. For copyable edit contracts, load /hyperframes-core → references/creator-editing-recipes.md.

Broad feedback about how photographic media looks or behaves also routes to /media-use, even when the user never says “color grading” or “effect”: fix dark/flat/boring footage, stylize a clip, hide a face, or improve a media reveal. Read ../media-use/references/media-treatments.md before editing a treatment; it governs how footage is treated, never whether media may be used. Do not substitute a generic LUT, CSS filter/overlay, or opacity tween for an existing canonical treatment primitive. Keep text/layout/motion-only edits in their owning domain. During a build with important photographic media, include one grounded media-polish scan in the final quality pass; leaving suitable media unchanged is a valid result.

Domain skills never take ownership of the end-to-end deliverable. Load only what the active workflow needs.

6. Studio

The Studio preview is a full editor: the user can click anything on the canvas to change it, edit text, drag and trim clips on the timeline, and export, and every edit saves to the project. Its "Ask agent" copies a prompt back to this conversation.

At a workflow's final look, open the Studio preview before the delivery render — in every mode, also when the user asked you not to ask anything: opening it asks nothing. Say they can edit the video right there. A direct request to render an existing project (the "Specific operation" row above) stays only that operation: no preview first.

Reference files

Read the matching file directly when its topic applies; the indexes remain available for choosing among recipes.

References

• Brief contract — Read when interpreting confirmed brief fields and render approval.
• Brief format — BRIEF.md — Read when writing or resuming BRIEF.md.
• Capability menu — what HyperFrames can bring to a video — Read when offering optional capabilities for a brief.
• Frame worker — core contract (shared by the narrative video workflows) — Read when dispatching a narrative frame worker.
• The intent layer — one conversation, before any workflow runs — Read when confirming intent before routing a new request.
• Pitch round — the intent layer's divergent step — Read when developing alternative concepts before choosing one.
• Running from an installed plugin — Read when running setup or freshness commands from a plugin.
• Production loop — from an approved plan to a delivered video — Read when moving from an approved plan to delivery.
• The review loop — plan, sketch, build — Read when reviewing a storyboard, sketches, or a build.
• Route briefs (moved) — Read when following legacy brief references to the current route files.
• Route: embedded-captions — Read when routing a embedded captions request.
• Route: faceless-explainer — Read when routing a faceless explainer request.
• Route: general-video — Read when routing a general video request.
• Route: motion-graphics — Read when routing a motion graphics request.
• Route: music-to-video — Read when routing a music to video request.
• Route: pr-to-video — Read when routing a pr to video request.
• Route: product-launch-video — Read when routing a product launch video request.
• Route: remotion-to-hyperframes — Read when routing a remotion to hyperframes request.
• Route: slideshow — Read when routing a slideshow request.
• Route: talking-head-recut — Read when routing a talking head recut request.
• SCRIPT.md — locked narration (optional) — Read when writing or reading locked narration in SCRIPT.md.
• Skill installation and freshness — Read when installing or refreshing a workflow skill.
• Storyboard format — STORYBOARD.md + parsed manifest — Read when writing STORYBOARD.md or its parsed manifest.
• Subagent dispatch — harness adapter — Read when adapting worker dispatch to the available harness.
• Workflow catalog (moved) — Read when following legacy catalog references to the current routes.