Imported from zachgodsell93/mavericai (docs/product-videos/hyperframes/audit-log/AGENTS.md). Install upstream with npx skills add zachgodsell93/mavericai --skill audit-log. Copyright stays with the author.

HyperFrames Composition Project

Orchestration workflow

You (Fable) are the orchestrator. Plan, decompose, synthesize. Reasoning-heavy phases → deep-reasoner (Opus) Mechanical work → fast-worker Codex (/codex:rescue --background) is a cracked engineer on par with deep-reasoner (Opus), from a different perspective. Treat as a peer, not a reviewer. High-stakes decisions: task Opus (deep-reasoner) + Codex on the same problem in parallel, synthesize the best of both, without showing either the other's answer. Keep your own context lean.

Skills

This project uses AI agent skills for framework-specific patterns. Install them if not already present:

npx skills add heygen-com/hyperframes

Skills encode patterns like window.__timelines registration, data-* attribute semantics, Tailwind v4 browser-runtime styling for --tailwind projects, and shader-compatible CSS rules that are not in generic web docs. Using them produces correct compositions from the start.

Commands

npm run dev          # start the preview server (long-running — keep it alive in background)
npm run check        # lint + inspect
npm run render       # render to MP4
npm run publish      # publish and get a shareable link
npx hyperframes docs <topic> # reference docs in terminal

npm run dev is a long-running server, not a one-shot command. It blocks until stopped. Always run it as a background process so it stays alive while you edit compositions. Running it in the foreground will time out and kill the server, breaking the browser preview.

Project Structure

• index.html — main composition (root timeline)
• compositions/ — sub-compositions referenced via data-composition-src
• assets/ — media files (video, audio, images)
• meta.json — project metadata (id, name)
• transcript.json — whisper word-level transcript (if generated)

Linting — Always Run After Changes

After creating or editing any .html composition, run the full check before considering the task complete:

npm run check

Fix all errors before presenting the result.

Key Rules

1. Every timed element needs data-start, data-duration, and data-track-index
2. Visible timed elements must have class="clip" — the framework uses this for visibility control
3. GSAP timelines must be paused and registered on window.__timelines:

   window.__timelines = window.__timelines || {};
   window.__timelines["composition-id"] = gsap.timeline({ paused: true });

4. Videos use muted with a separate <audio> element for the audio track
5. Sub-compositions use data-composition-src="compositions/file.html"
6. Only deterministic logic — no Date.now(), no Math.random(), no network fetches

Documentation

Full docs: https://hyperframes.heygen.com/introduction

Machine-readable index for AI tools: https://hyperframes.heygen.com/llms.txt