WaterrrForeverandClaude Opus 4.8
bf961d1268
* feat(cli): add skills version check, update, and freshness manifest
Give the HyperFrames skill bundle a content fingerprint so agents and
users can tell whether installed skills are the latest version, on any
platform that can run the CLI.
- skills-manifest.json (repo root): per-skill sha256 over the whole skill
directory; minimal {source, skills}, no version/timestamp so it is fully
deterministic. Generated by scripts/gen-skills-manifest.ts.
- `hyperframes skills check` [--json]: compares installed skills to the
manifest; exits non-zero when something is outdated (agent/CI gate).
- `hyperframes skills update`: thin wrapper over `npx skills update`.
- Passive nudge on render/lint/validate when skills are stale (24h cache,
same opt-out as the CLI self-update notice).
- "latest" resolved via `git ls-remote` + SHA-pinned raw URL to dodge
GitHub raw-CDN lag, falling back to the main branch URL.
- CI job + lefthook hook keep skills-manifest.json in sync with skills/.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(cli): add execFile to child_process mock in skills test
skills.test.ts mocks node:child_process but only declared execFileSync
and spawn. Loading skills.js transitively loads skillsManifest.ts, which
runs promisify(execFile) at module load, so vitest threw on the missing
execFile named export. Add a bare stub — these tests never invoke it.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(cli): init installs all skills; skills update pulls the full set
Make `hyperframes init` the single place skills are pulled in full, and
make "update" mean "get everything" rather than "refresh what's there".
- init now always installs/refreshes ALL skills (incl. ones not yet
present) instead of prompting "Install AI coding skills?" — opt out
with `init --skip-skills`. Both the interactive and non-interactive
paths pass `--all --yes` so the complete set is fetched.
- `hyperframes skills update` switches from `npx skills update` (which
only refreshes already-installed skills) to `skills add --all`, so it
installs missing skills too — the same install step init runs.
- SKILL.md documents init-installs-all and the new update semantics.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(cli): skills check treats missing skills as needing an update
The full skill set is now the goal (init and `skills update` both pull
all, including ones not installed), so a partial install is no longer
"a choice" — it's something to fix.
- diffSkills: updateAvailable is now true when anything is outdated OR
missing (local-only still doesn't count). So `skills check` exits
non-zero — and renders "Update:" instead of "up to date" — whenever a
skill is missing, not just when one is stale.
- The passive render/lint/validate nudge follows suit: it now counts
missing alongside outdated ("N skills out of date or missing"),
tracked via a new skillsMissingCount cache field.
- SKILL.md documents the stricter check.
Note: platforms that intentionally vendor only a subset of skills (e.g.
a Codex snapshot) will now see check report non-zero.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(cli): install/update skills straight from the GitHub repo
`skills add owner/repo` can resolve through the skills.sh registry, which
lags behind the repo — so `update` could install a stale version while
`check` (which resolves latest directly from GitHub) keeps reporting
"outdated", an endless loop.
Switch the install source to the full GitHub URL
(https://github.com/heygen-com/hyperframes), which makes `skills add`
git-clone the repo directly at latest main, bypassing the registry. This
covers `hyperframes skills`, `hyperframes skills update`, and `init`'s
skill install — all of which go through SOURCES. Now install/update and
check agree on what "latest" means.
The init "install skills" hint now points at `npx hyperframes skills
update` so the manual path uses the same GitHub-direct fetch.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(cli): init checks skills against GitHub, installs only when stale
`hyperframes init` now runs the skills version check first and only
(re)installs when something is outdated or missing — instead of
unconditionally re-pulling every time. Re-running init on an
already-current project is now a no-op ("skills are already up to date").
- New ensureSkillsCurrent() helper, shared by both the interactive and
non-interactive init paths (no duplicated install logic).
- The check resolves "latest" straight from GitHub (same source the
install uses); best-effort — if it can't reach GitHub it installs anyway.
- SKILL.md updated to describe the check-then-install behavior.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* refactor(cli): address skills manifest review feedback
From the PR review (points 1, 2, 4, 5):
1. Remove the `local-only` skill status. checkSkills only ever hashes
manifest-listed skills, so a local-only status could never appear in
the end-to-end output — and making it appear would wrongly flag
unrelated skills (the `.../skills` dir is shared across sources).
diffSkills now reports only on manifest skills; skills on disk that
aren't in the manifest are ignored.
2. Drop the redundant per-directory sort in listFilesSorted — the single
final out.sort() is what guarantees a deterministic hash (verified:
manifest unchanged).
4. resolveLatestManifest local-path detection now uses path.isAbsolute,
so Windows absolute paths (C:\...) are treated as local instead of
falling through to a remote fetch.
5. fetchManifest validates the response shape (asSkillsManifest) instead
of a blind `as` cast, so a CDN error page served as 200 fails with a
clear error rather than a cryptic crash later in diffSkills.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(cli): strict skills update + auto-discover any agent host
Address PR review (Magi blocker + James/Rames robustness):
- Blocker (Magi): `skills update` is the documented recovery path for
`skills check || skills update`, but it delegated to installAllSkills()
which swallowed missing-npx and failed `skills add` as "skipped",
exiting 0 even when nothing changed. Add a strict mode that throws on
failure; update sets a non-zero exit (init stays best-effort). New tests
simulate a non-zero `skills add` (exit 1) and the success path.
- Robustness (James/Rames #2): the upstream `skills` CLI installs into
~72 agent conventions; a hard-coded list (4, or even 11) can't track
that. Replace defaultSkillRoots with discoverSkillRoots — it scans cwd +
$HOME for any `<host>/skills/<manifest-skill>/SKILL.md` (plus the XDG
`.config/<host>/skills`), so detection is structural and future-proof,
no closed list. agentFromDir infers the host from the path.
- Tests (Rames #3): temp-fixture detection tests for every convention ×
{project, global}, scope priority, claude-code preference, the
no-install case, the --dir override, and an unknown/new host (proving
the no-closed-list property).
- Docs (Rames #4/#5): SKILL.md notes init's best-effort GitHub round-trip;
findRepoManifest climbs 16 levels (was 8) for deep monorepos.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(cli): resolve CodeQL file-system race + de-flake Windows npx test
Two CI fixes:
- CodeQL (high, js/file-system-race) at gen-skills-manifest.ts: the
existsSync(outPath) precheck followed by writeFileSync(outPath) is a
check-then-write race. Read the committed manifest directly in a
try/catch instead (missing/unreadable ⇒ "no committed manifest"), so
there's no precheck to race against. Behavior is unchanged.
- Windows Tests: npxCommand.test.ts's real `npx --version` smoke test
cold-starts slower than vitest's 5s default on Windows runners and
timed out. Give the test 60s headroom (and a 30s exec timeout). Kept
as a real execution check — mocking would reduce it to a tautology.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(cli): repair garbled npx smoke-test timeout comment
The explanatory comment for the 60s timeout was scrambled across the
callback/timeout arguments, failing oxfmt --check (and thus preflight,
which in turn skipped preview-parity and failed the regression gate).
Move it above the it() call so it no longer sits between call arguments.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(cli): install skills once globally + symlink-mirror to every agent
The previous install path sprayed a full ~6.7MB skill copy into each of the
~70 agent conventions `skills add --all` knows (a fresh init produced 40+
dirs / 341MB, incl. a stray dotless `agent/` from the Eve convention).
Install ONCE, globally, as one faithful copy, then symlink it everywhere:
- `skills add <url> --skill '*' --global --agent claude-code universal
--copy` lands real files in ~/.claude/skills (Claude Code reads this at
global priority) and ~/.agents/skills (the shared universal store).
- mirrorGlobalSkills() fans that store out to every OTHER installed agent's
GLOBAL dir (~/.cursor/skills, goose -> ~/.config/goose/skills, ...) — but
only for agents present on the machine (marker dir exists), so nothing is
sprayed. Unix: per-skill relative symlink into the store (one source of
truth, auto-fresh on update); Windows: copy (symlinks need admin /
Developer Mode there — the same fallback upstream and gstack make).
Why global: skills are framework-general knowledge, not project content;
Claude Code (and most agents) prioritize the personal/global scope, so the
global copy is the one actually loaded — and it installs once instead of
multiplying per project.
The per-agent dir list is GENERATED from upstream's src/agents.ts at a pinned
tag (the `skills` package exports nothing importable), committed as
agentDirs.generated.ts and resolved env-faithfully at runtime
(XDG_CONFIG_HOME / CODEX_HOME / CLAUDE_CONFIG_DIR honored). Regenerate with
`bun run --cwd packages/cli gen:agent-dirs` when the pin moves. Covers all 70
agents that define a global dir (eve/promptscript define none); the bare
project-dir agents (openclaw, astrbot) are namespaced globally, so the
stray-`agent/` footgun is gone.
`skills check` now scans global ($HOME) before project (cwd) to match the
runtime load order — so it reports on the copy the agent will really use, not
a stale project copy a newer global install silently overrides.
Test plan:
- skills.test.ts: install spawns the global --copy args, never --all; update
stays strict + exits non-zero on failure.
- skillsMirror.test.ts: Unix relative symlinks, Windows copy, XDG_CONFIG_HOME
honored, install-owned stores skipped, marker-gating, idempotent refresh,
generated-table shape.
- skillsManifest.test.ts: check is global-first.
- Full CLI suite green (981); oxlint / oxfmt / tsc clean; gen:agent-dirs
--check clean (offline + network produce byte-identical output).
- Benchmark (isolated HOME, local CLI): claude+hermes and all 70 agents —
~/.claude + ~/.agents real (19 each), every installed agent's global dir =
19 symlinks into the store, zero spray into unseeded agents, check
global-first. (The 9 "outdated" check reports are the separate skills.sh
registry lag, not this change.)
- .fallowrc.jsonc: exempt the codegen script's inherent parser complexity and
the parallel-case duplication in skillsManifest.test.ts (same rationale the
config already uses for SlideshowPanel.test.ts / hyperframes-player.test.ts).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(cli): install skills with --full-depth so a fresh install reads as current
`skills add <url>` without --full-depth fetches from the skills.sh registry
blob ("Fetching skills"), which lags GitHub main by hours — so a freshly
installed/updated set read as ~9 skills "outdated" right after install, and
`skills update` couldn't fix it (it re-fetched the same stale blob → death
loop). --full-depth switches it to a real `git clone` of HEAD ("Cloning
repository"), the only path that yields the genuine latest.
- Add --full-depth to the global install args. Verified (isolated HOME): blob
path → 10 current / 9 outdated; --full-depth → 19 current / 0 outdated.
- The clone is heavier than the blob fetch, so set GIT_LFS_SKIP_SMUDGE=1 (skills
are text; the repo's LFS objects are unrelated binaries the install doesn't
need) and raise the spawn timeout 120s → 300s.
- Correct the stale comment that claimed a full URL already bypasses skills.sh —
it doesn't; only --full-depth does.
Benchmark (skills-bench, local CLI): B.death-loop and J1.init-detect-and-refresh
flip FAIL → PASS (install/update/init now 19/0); mirror smoke reports 19 current
/ 0 outdated. (spine still reflects the raw documented `skills add <slug>`
command — the upstream skills.sh path, not this CLI.)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(skills): drop --skip-skills from workflow init so new projects refresh skills
The creation workflows scaffolded with `hyperframes init … --skip-skills`, which
skipped the skills currency check. Now that init installs globally, is a no-op
when already current, and pulls the genuine latest (via --full-depth), there's
no reason to skip it: removing --skip-skills means every new project runs the
check and refreshes the global skill set from GitHub when it's stale. Add a
one-line note to each workflow (embedded-captions, faceless-explainer,
motion-graphics, music-to-video, pr-to-video, product-launch-video) and the
hyperframes-cli + /hyperframes router explaining what init does.
skills-manifest.json regenerated by the pre-commit hook to match the edited
skill bundles.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(cli): scope agent mirror to HyperFrames' own skills, not the whole store
mirrorGlobalSkills listed every */SKILL.md in ~/.claude/skills and fanned them
out — but that store is shared, so a user's gstack / personal / company Claude
skills would get symlinked (and, since linkOrCopy removes the target first,
could overwrite a same-named skill) into Cursor / Codex / Goose / etc.
Scope the mirror to HyperFrames' own skills via the upstream lock's source
attribution — the same definition the prune already uses
(skillsAttributedToSource) — never a directory listing. New
hyperframesSkillNames() reads the global lock and returns only skills attributed
to heygen-com/hyperframes; the mirror intersects that allow-list with what's in
the store. Empty (no lock / nothing attributed) → mirror nothing, never
everything.
Also fixes the cosmetic "director(ies)" log typo (now singular/plural-aware) and
extracts the fan-out into mirrorToInstalledAgents() to keep installAllSkills
under the complexity gate.
Regression: skillsMirror.test.ts asserts a foreign gstack skill in the store is
neither mirrored out nor allowed to replace another agent's same-named skill;
the skills-bench harness seeds ~/.claude/skills/gstack and asserts it never
leaks to any agent. 1045 CLI tests + lint/types/fallow green.
Addresses Magi's request-changes on #1753.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
21 KiB
name, description
| name | description |
|---|---|
| pr-to-video | turn a GitHub pull request (a PR URL like github.com/<owner>/<repo>/pull/<N>, an <owner>/<repo>#<N> ref, or 'this PR' in a checked-out repo) into a code-change explainer video, up to ~3 min (sweet spot 30-90s) — changelog, feature reveal, fix, or refactor walkthrough, rendered from the diff / commits / files. The input is a CODE CHANGE read via the gh CLI; there is no website capture. Use this skill for a GitHub PR. Do not use it for a product launch/promo (use /product-launch-video), a tour of a real website (use /website-to-video), a topic explainer with no PR (use /faceless-explainer), captions on existing footage (use /embedded-captions), or a short unnarrated motion graphic (use /motion-graphics). If the intent is unclear, route through /hyperframes first. |
media-use: Before sourcing audio/images, call
/media-useto resolve BGM/SFX/images from the HeyGen catalog. Run--adoptfirst to register existing assets. See/media-useskill.
PR to HyperFrames
Use this skill to ingest a GitHub pull request, understand the change, plan a code-change explainer, and build it frame by frame in HyperFrames. The input is a code change (read via gh), not a website — there is no capture step and no real assets beyond the contributors' avatars.
Confirm the route before Step 0. You are the orchestrator. Run each step, verify its gate, and only then continue. This skill is for a GitHub pull request (a code change). Route other intents elsewhere: a product launch/promo →
/product-launch-video; a general website tour →/website-to-video; a topic explainer with no PR →/faceless-explainer; captions on existing footage →/embedded-captions; a short unnarrated motion graphic →/motion-graphics; a whole-repo or multi-PR release walkthrough →/general-video. Out of scope: live / at-render-time data — PR facts are read once at author time and baked in. If the user says only "make a video" or the route is uncertain, read/hyperframesfirst.
You are the orchestrator. Work in videos/<project>/. Run steps in order and pass each gate before continuing. User-gated steps are Step 0, Step 3, and Step 6. Do every step yourself except Step 5, where you dispatch one sub-agent per frame. Do not put design or motion rules here; those live in the frame-worker sub-agent, hyperframes-creative, and hyperframes-animation.
Workflow: Step 0 setup → hyperframes.json; Step 1 ingest → capture/extracted/ + assets/<login>.png; Step 2 design system → frame.md; Step 3 storyboard/script → STORYBOARD.md and SCRIPT.md; Step 3.1 audio → audio_meta.json; Step 4 visual design → enriched STORYBOARD.md; Step 5 frames → compositions/frames/NN-*.html and index.html; Step 6 final render → renders/video.mp4.
Step 0: Setup and Brief
Goal: Lock the PR reference and the core video brief, and create the HyperFrames project if needed.
Get the PR reference (a full URL, an <owner>/<repo>#<N> ref, or "this PR" in a checked-out repo) and, in one message, confirm the brief — lead with a recommended default for each and pre-fill anything /hyperframes already set: angle (changelog / feature-reveal / fix-explainer / refactor-walkthrough — default: infer from the PR), audience (default: developers), length (default: scale to the PR's change size — see below), aspect (default 16:9), language. The style is always claude. Proceed only after the user replies; a "go" accepts the defaults.
Recommend the length from the PR's change size, not a fixed guess. Before confirming the brief, peek at the PR once — a read-only call that also grounds the angle (Step 1 still does the full deterministic fetch):
gh pr view <PR_REF> --json title,additions,deletions,changedFiles
Pick the tier from additions + deletions (nudged up by changedFiles) and lead with it as the default (the user can override; hard cap ~3 min):
| PR change size | Recommended length |
|---|---|
| trivial (≲ 50 lines changed) | ~20–40s |
| focused (~50–200 lines) | ~40–70s |
| substantial (~200–600 lines) | ~70–110s |
| large (≳ 600 lines, or 25+ files) | ~110–180s |
State the basis in one phrase when you propose it (e.g. "~40s — small change, +44/−13 across 12 files"). A huge PR doesn't mean a long video — if the story is one headline change, keep it tight and say so.
Initialize only if hyperframes.json is missing. Name <project> from the PR in kebab-case, such as acme-sdk-pr-1842; never use the workspace name or a timestamp.
npx hyperframes init "videos/<project>" --non-interactive --example=blank — init checks the installed skills against the latest on GitHub and updates the global set if any are out of date.
Show sign-in status before the brief — run npx hyperframes auth status and relay its output verbatim (don't paraphrase or rewrite it). It reports whether voice/BGM will use HeyGen or local engines and, when not signed in, how to sign in. If not signed in, STOP and wait for the user to choose — sign in, or say "go"/"offline" to continue with local engines — before asking the brief or anything else. Treat it as a real decision point, not a passing note; don't fold the choice into the brief question, and don't write keys into a per-repo .env. (In autonomous mode, note the status and continue offline.) See ../hyperframes-media → Preflight for the canonical guidance.
Gate: hyperframes.json exists; the PR ref is captured; angle, length, aspect ratio, and language are locked; sign-in status was shown (signed in, or continuing offline).
Step 1: Ingest the PR (no capture)
Goal: Fetch the PR's facts and fold them into the project as the source of information. There is no website capture. fetch-pr.mjs runs gh deterministically — completing the files list via paginated gh api so a large PR doesn't truncate at ~100 files, and writing only capture/pr.json + capture/diff.patch (no scratch dir). Then ingest.mjs folds that into the synthetic capture package offline.
PR="<url | owner/repo#N | N>"
# Fetch the PR deterministically: runs gh, completes the files list via paginated
# gh api (so a big PR doesn't truncate at ~100 files), writes only capture/pr.json +
# capture/diff.patch — no scratch dir. gh auth / not-found / private errors exit 1 here.
(cd "videos/<project>" && node <SKILL_DIR>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture)
# Offline transform → capture/extracted/{tokens.json (colors:[] → claude palette),
# visible-text.txt (the brief), people.json (contributors, bot-filtered, avatarFile=assets/<login>.png)}.
(cd "videos/<project>" && node <SKILL_DIR>/scripts/ingest.mjs \
--pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)
# The people front's one network step — download each contributor's GitHub avatar to
# assets/<login>.png for an optional credits close. Best-effort; always exits 0.
(cd "videos/<project>" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
If fetch-pr.mjs exits 1 (gh auth / not found / private), report its stderr and stop — do not fabricate PR contents. If ingest.mjs exits 1, read its stderr (usually a malformed pr.json), fix, and rerun (deterministic). fetch-people-avatars.mjs always exits 0; missing avatars just mean no credits close to author.
Gate: capture/pr.json, capture/diff.patch, capture/extracted/tokens.json, capture/extracted/visible-text.txt, and capture/extracted/people.json exist; you can state the PR's change in one clear sentence. assets/<login>.png is best-effort — its absence is not a failure.
Step 2: Design System
Goal: Adopt the claude frame preset; a script turns it into this video's frame.md + caption skin.
The style is fixed — claude (warm editorial; a navy code surface built for diffs). Run:
node <SKILL_DIR>/scripts/build-frame.mjs --preset claude --hyperframes .
The script copies the claude preset's FRAME.md → frame.md, remixes it onto any brand tokens in capture/extracted/tokens.json (a PR has none → colors:[]/fonts:[] keeps claude's own palette, a complete design), copies the preset's caption skin to .hyperframes/caption-skin.html, and self-validates (exits 1 on a broken mapping). Proceed as soon as it exits 0 — no hand-editing.
Gate: build-frame.mjs exited 0 — frame.md exists from the claude preset, and .hyperframes/caption-skin.html exists as the caption skin source.
Step 3: Storyboard and Script
Goal: Turn the PR into an approved frame-by-frame explanation plan.
Read references/story-design.md, ../hyperframes-core/references/storyboard-format.md, and ../hyperframes-core/references/script-format.md. Use them to write STORYBOARD.md and, when narration is needed, SCRIPT.md.
Use story-design.md for the PR archetype (changelog / feature-reveal / fix-explainer / refactor-walkthrough), the PR-native frame types, hook, persuasion, beats, the per-frame word budget, and the optional credits close. The sequence comes from narrative design, not the diff's file order — explain the change, don't read the diff aloud. Feature 2–4 real diff hunks (from capture/diff.patch), each a small legible snippet; name the code-* block each wants in the frame's scene. Frames carry no asset_candidates except an optional credits close (2–6 assets/<login>.png avatars). Use the exact required fields from the storyboard and script references.
After drafting, show a frame-by-frame summary. In that same message ask the user (a) to approve or request changes, and (b) whether they want a live preview of the storyboard scaffold (npx hyperframes preview) — open it only on a yes. Iterate until approved; carry the preview choice to Step 6.
Gate: STORYBOARD.md exists, every frame has the required narrative fields, SCRIPT.md exists when narration is needed, and the user approved the plan.
Step 3.1: Audio
Goal: Generate narration, word timings, music, and audio metadata from the approved script.
Start audio after Step 3 approval. Run it in the background, then continue to Step 4.
node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json &
The audio script handles narration, word timings, BGM lookup from HeyGen's music library, and timing metadata. BGM mood comes from the storyboard's music: field. This uses the HeyGen Audio API for retrieval, not generation, and the same ~/.heygen credential as TTS. For provider details, read ../hyperframes-media/references/tts.md.
If there is no narration and no SCRIPT.md, skip voice generation. BGM may still run if the storyboard has a music mood.
Gate: audio job has started, or the project is marked silent.
Step 4: Frame Visual Design
Goal: Add the visual direction, layout intent, and motion choices to each storyboard frame.
Edit STORYBOARD.md in place. Do not create another storyboard. Use frame.md as the source of truth for color, type, layout feel, and style.
Read references/visual-design.md, references/composition.md, references/motion-language.md, references/code-vocabulary.md, and ../hyperframes-animation/. Use visual-design.md for required frame fields and the required ## Video direction block, and for how a code beat names a code-* block as its focal. Use code-vocabulary.md to pick the right block per beat (diff = code-diff, refactor = code-morph, new code = code-typing, …). Use composition.md for layout/hierarchy/focal points and motion-language.md + ../hyperframes-animation/ for valid effect and blueprint IDs. Do not invent effect names or block/blueprint IDs.
For every frame, add required visual and motion fields, including effects and focal and/or roles. For a code beat, name the code-* block as the focal and let effects choreograph the surrounding claude Code Surface (not the code animation, which the block owns). Add one video-wide ## Video direction block.
Do not change story, script, transition_in, asset_candidates, or the PR source. Do not write HTML in this step. There is no asset-staging step — the only real assets are the credits avatars, already in assets/.
Gate: every frame has effects plus focal and/or roles; code frames name a code-* block; ## Video direction exists.
Step 5: Build Frames
Goal: Build every storyboard frame as an HTML composition and assemble the playable video.
Wait for Step 3.1 audio to finish if audio was started. Then sync durations and fetch SFX; skip both if silent.
node <SKILL_DIR>/scripts/audio.mjs sync-durations --audio-meta ./audio_meta.json --storyboard ./STORYBOARD.md
node <SKILL_DIR>/scripts/audio.mjs fetch-sfx --storyboard ./STORYBOARD.md --hyperframes .
Duration sync is mechanical: real voice duration wins; silent frames keep estimates; never hand-edit synced durations.
Pre-install the registry blocks named across STORYBOARD.md once, before dispatch, so parallel workers don't race on the registry:
for b in <each registry block named in the storyboard>; do npx hyperframes add "$b"; done
Before dispatch, read sub-agents/frame-worker.md and ../hyperframes-core/references/subagent-dispatch.md. Dispatch one sub-agent per frame, in parallel if possible; otherwise run workers in waves. Each worker gets exactly one frame. Each worker's context must include PROJECT_DIR, frame_id, canvas size, caption status and keep-out band if captions are enabled, ANIM_DIR (absolute path to ../hyperframes-animation/), and the absolute path to references/code-vocabulary.md. Each worker reads frame.md, its own ## Frame N block, the recipe body for each cited effect/blueprint ID, and — for a code beat — code-vocabulary.md for the named block's inputs. Each worker writes only compositions/frames/NN-*.html; workers never edit STORYBOARD.md.
As each worker returns, mark that frame animated in STORYBOARD.md.
After audio timings exist, build captions in the background and assemble the index:
node <SKILL_DIR>/scripts/captions.mjs build --storyboard ./STORYBOARD.md --audio-meta ./audio_meta.json --hyperframes . --out ./caption_groups.json &
node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard ./STORYBOARD.md --hyperframes .
captions.mjs uses the project's .hyperframes/caption-skin.html (claude's, copied in Step 2), injecting brand tokens from frame.md; captions: skipped (<reason>) is valid. assemble-index.mjs stages the credits avatars from assets/ as an idempotent backstop.
Gate: every frame is marked animated, index.html exists, and captions are built or explicitly skipped.
Step 6: Finalize
Goal: Verify the assembled video, get user approval, and render the final MP4.
Inject transitions, run checks, pause for review, then render.
node <SKILL_DIR>/scripts/transitions.mjs inject --storyboard ./STORYBOARD.md --hyperframes .
node <SKILL_DIR>/scripts/transitions.mjs verify --storyboard ./STORYBOARD.md --index ./index.html
npx hyperframes lint
npx hyperframes validate
npx hyperframes inspect
npx hyperframes snapshot --at <frame-midpoints>
snapshot stitches the captured frames into one contact sheet (snapshots/contact-sheet.jpg). Glance at it; if nothing is obviously broken, move on — don't linger here.
If a command fails, surface stderr and stop — don't pile on recovery commands. Fix it yourself: the cheapest safe edit to compositions/frames/NN-*.html, then rerun the failed check.
Known false-positive — do not chase it. inspect may report a handful of text_box_overflow errors of ~1–4px on the caption highlight words (selector #caption-word-* / .caption-line). The caption pill uses a deliberately snug line-height (set once in scripts/captions.mjs) and has no overflow:hidden, so a heavy display glyph's ink spills a few px into the pill's own padding — nothing is actually clipped. Treat these as expected and proceed. Do not inflate the caption line-height (it balloons the pill, which is worse). Only act on a text_box_overflow when it names a frame element (#el-NN-*), not a caption word.
After checks pass, pause for user review. The video is assembled, viewable, and editable in Studio. Manage preview only once across Step 3 and Step 6: open it if the user asked earlier, offer it if they declined earlier, do not ask again if they are already reviewing in Studio.
Preview: npx hyperframes preview
Render only after user approval:
npx hyperframes render --skill=pr-to-video --quality high --output renders/video.mp4
Do not rerun lint, validate, inspect, or snapshot after rendering unless the user asks.
Gate: lint, validate, and inspect passed before render; user approved at the review pause; renders/video.mp4 exists. Final reply states the MP4 path and final duration.
Quick Reference
Formats: landscape 1920x1080 by default; portrait 1080x1920; square 1080x1080. Set the format once in the storyboard frontmatter.
PR deltas vs a captured-asset workflow: no Step 1 capture (the gh CLI ingests the PR into a synthetic capture/extracted/ package — tokens.json + visible-text.txt + people.json); the only real assets are the contributors' assets/<login>.png avatars (an optional credits close); no asset-descriptions.md, no asset-staging step. Code beats are rendered by the code-* registry blocks on claude's navy Code Surface; the style is always claude.
Background scripts: the workflow ships these under scripts/: fetch-pr (PR → capture/pr.json + diff.patch via gh; large-PR-safe, no scratch), ingest (→ synthetic capture package; offline), and fetch-people-avatars (contributor avatars → assets/); plus the shared engine — build-frame (adopt + brand-remix a preset into frame.md + caption skin), audio (TTS, BGM, SFX, duration sync), captions, transitions (inject + verify), and assemble-index. Everything else is the hyperframes CLI. Code blocks install via npx hyperframes add <name>.
| Read | When |
|---|---|
[references/story-design.md](references/story-design.md) |
Step 3: plan the PR explanation. |
[../hyperframes-core/references/storyboard-format.md](../hyperframes-core/references/storyboard-format.md) |
Step 3: write STORYBOARD.md. |
[../hyperframes-core/references/script-format.md](../hyperframes-core/references/script-format.md) |
Step 3: write SCRIPT.md. |
[../hyperframes-media/references/tts.md](../hyperframes-media/references/tts.md) |
Step 3.1: choose or understand TTS providers. |
[references/visual-design.md](references/visual-design.md) |
Step 4: enrich the storyboard visually. |
[references/code-vocabulary.md](references/code-vocabulary.md) |
Step 4 + 5: pick + fill the code-* block for a code beat. |
[references/composition.md](references/composition.md) |
Step 4: judge composition. |
[references/motion-language.md](references/motion-language.md) |
Step 4: judge motion language. |
[../hyperframes-animation/](../hyperframes-animation/) |
Step 4: cite effect and blueprint IDs. |
[sub-agents/frame-worker.md](sub-agents/frame-worker.md) |
Step 5: dispatch per-frame workers. |
[../hyperframes-core/references/subagent-dispatch.md](../hyperframes-core/references/subagent-dispatch.md) |
Step 5: dispatch sub-agents safely. |
[../hyperframes-creative/frame-presets/claude/FRAME.md](../hyperframes-creative/frame-presets/claude/FRAME.md) |
Step 2: the claude preset (fixed style). |