feat(skills): remotion-to-hyperframes SKILL.md + orchestrator (7/7)

[jrusso1020]

What

The leaf PR of the 7-PR stack. Two pieces:

1. Real SKILL.md body — replaces the placeholder from PR 1 with a 5-step workflow that loads per-topic references on demand (skill-creator's progressive-disclosure pattern).
2. Top-level orchestrator at assets/test-corpus/run.sh that runs all four tiers and emits a pass/fail report.

End-to-end validation

Run on a clean checkout:

remotion-to-hyperframes corpus run
==================================
  ▶ tier-1-title-card (threshold 0.95, composition TitleCard)
    ⏳ render Remotion baseline
    ⏳ render HF translation
    ✓ pass (mean SSIM 0.9739, threshold 0.95)
  ▶ tier-2-multi-scene (threshold 0.95, composition MultiScene)
    ⏳ render Remotion baseline
    ⏳ render HF translation
    ✓ pass (mean SSIM 0.985292, threshold 0.95)
  ▶ tier-3-data-driven (threshold 0.9, composition Stargazed)
    ⏳ render Remotion baseline
    ⏳ render HF translation
    ✓ pass (mean SSIM 0.952941, threshold 0.9)
  ▶ tier-4-escape-hatch (lint-only)
    ✓ pass (8/8 cases)

==================================================
  passed 4/4, failed 0, skipped 0

SKILL.md design

Per skill-creator's progressive-disclosure pattern:

• Frontmatter (always loaded): trigger phrases + out-of-scope list. Unchanged from PR 1.
• Body (loaded when triggered): 5-step workflow under 100 lines. Lean by design.
• References (loaded as needed): the 11 per-topic files from PR 6.

The body has a "Source contains → Load reference" table that tells the agent which references to pull based on the actual Remotion APIs the source uses. The agent doesn't load all 11 references — it loads 1–4 based on what the source needs.

| Source contains | Load reference |
|---|---|
| `Composition`, `defaultProps`, `schema`, `calculateMetadata` | parameters.md |
| `Sequence`, `Series`, `Loop`, `AbsoluteFill`, `Freeze` | sequencing.md |
| `useCurrentFrame`, `interpolate`, `spring`, `Easing` | timing.md |
| `Audio`, `Video`, `Img`, `IFrame`, `staticFile` | media.md |
| `TransitionSeries`, `@remotion/transitions` | transitions.md |
| `@remotion/lottie` | lottie.md |
| `@remotion/google-fonts/<Family>`, `Font.loadFont` | fonts.md |

Orchestrator design

assets/test-corpus/run.sh:

• Iterates tier-1-* through tier-4-* directories.
• For T1–T3: setup binary assets (T2 only) → lint Remotion source → lazy npm install → render Remotion baseline → render HF translation → SSIM diff at the fixture's per-tier threshold → generate frame strip on failure.
• For T4: validate.sh (lint-only).
• Emits run-report.json with per-tier pass/fail and aggregate counts.
• Accepts a single-tier argument for fast iteration: ./run.sh tier-1-title-card.

The orchestrator is what makes this skill regression-testable: any future PR that touches the references can re-run ./run.sh to verify nothing broke.

Stack — complete

#	PR	Status	What
1	#506	draft	scaffold
2	#507	draft	eval harness
3	#508	draft	T1 + T2 fixtures (validated 0.974 / 0.985)
4	#509	draft	T3 data-driven fixture (validated 0.953)
5	#515	draft	T4 escape-hatch fixtures (8/8 cases)
6	#516	draft	references (11 files, ~1500 LOC)
7	this PR	draft	SKILL.md body + orchestrator

Test plan

• SKILL.md passes oxfmt --check
• ./run.sh runs all four tiers end-to-end on a clean checkout, all pass
• ./run.sh tier-1-title-card runs a single tier (selective execution works)
• Skill-creator's package_skill.py validates the final skill
• Lefthook pre-commit (lint + format + typecheck) passes
• run-report.json excluded from git via .gitignore (it's regenerated per run)

Reviewer notes

This is a substantive skill (~3000 LOC across the stack — scripts, fixtures, references, body) so it warrants more than a glance. Highest-leverage things to look at:

1. SKILL.md body — the workflow has to be right because everything else hangs off of it. Specifically the "Source contains → Load reference" table — if any common Remotion idiom is missing a reference link, the skill will load the wrong context.
2. references/timing.md spring → back.out table — every spring config in the wild needs a corresponding row. PR 6 has the validated 1.4 / 1.2 ratios; if you've seen springs the table doesn't cover, add them.
3. The 0.95 / 0.95 / 0.90 / n/a thresholds — these came from a single calibration run on this machine. CI on a different host with a different Chromium version could drift. Wider thresholds = fewer false alarms but higher chance of missing a real regression.

[miguel-heygen]

The final orchestration layer has two blockers: the lambda-only policy contradicts the corpus/references, and the advertised corpus runner fails before it can run the lint-only tier in a clean checkout.

[miguel-heygen]

This makes every blocker a hard stop with no HF output, but the T4 corpus expects lambda-only sources to use drop_lambda_code_translate_remainder_if_clean, and escape-hatch.md also documents that edge case. Since lint_source.py currently emits r2hf/lambda-import as a blocker with exit code 1, the final skill will never take the documented lambda-only path. Please align the policy across SKILL.md, T4, references, and the linter severity before this lands.

[miguel-heygen]

This preflight runs before tier selection, so ./assets/test-corpus/run.sh tier-4-escape-hatch fails in a clean checkout even though T4 is lint-only and does not need the HF CLI. I reproduced the failure locally: error: HF CLI not built. Run 'bun run --filter @hyperframes/core build' .... The suggested command is also wrong for this check because the script needs packages/cli/dist/cli.js; building @hyperframes/core will not produce that file. Please only require the CLI for T1-T3 and point users at the CLI/root build command.

[jrusso1020]

@miguel-heygen — addressed in the amended commit 95b89ca0:

SKILL.md Step 1 — @remotion/lambda moved from Blockers list to Warnings list. Now consistent with #507's lint severity, T4's expected.json (#515), and the references (#516):

- **Blockers** (refuse + recommend interop): `useState`, `useReducer`, `useEffect` with non-empty deps, async `calculateMetadata`, `@remotion/lambda`, third-party React UI libraries...
+ **Blockers** (refuse + recommend interop): `useState`, `useReducer`, `useEffect`/`useLayoutEffect` with non-empty deps, async `calculateMetadata`, third-party React UI libraries...

- **Warnings** (translate after dropping): `delayRender`, `useCallback`, `useMemo`, custom hooks.
+ **Warnings** (translate after dropping the construct): `@remotion/lambda` config, `delayRender`, `useCallback`, `useMemo`, custom hooks.

The "What this skill explicitly does NOT do" list lost the lambda bullet and gained a parenthetical note pointing at escape-hatch.md for the warning-level treatment.

run.sh preflight fix: the HF CLI presence check (and the ffmpeg check) moved out of top-level into a require_render_tier_tools() function called from run_render_tier(). T4 (lint-only) skips it entirely. Also fixed the build command suggestion: bun run --filter @hyperframes/cli build (was @hyperframes/core — different package, doesn't produce cli/dist/cli.js).

Verified ./run.sh tier-4-escape-hatch works on a clean checkout (no CLI build needed). Full ./run.sh still passes 4/4 end-to-end.

[miguel-heygen]

The lambda policy is now aligned and T4 can run without the CLI, but the full orchestrator still reports success when the render tiers never ran.

[miguel-heygen]

Returning success here converts missing render-tier tooling into a skipped fixture, and the aggregate exits 0 as long as there are no explicit failures. In a clean checkout without packages/cli/dist/cli.js, I ran ./assets/test-corpus/run.sh; it skipped T1/T2/T3, ran only T4, printed passed 1/4, failed 0, skipped 3, and exited 0. That makes the advertised end-to-end corpus check pass without validating any render/diff tier. Missing CLI/ffmpeg for a requested render tier should be a failure, or the aggregate should exit non-zero when required tiers are skipped. Also the header comment still points users at @hyperframes/core build, while the runtime error correctly says @hyperframes/cli build.

[jrusso1020]

@miguel-heygen — addressed in f29a0627 (after #507's regex fix rebase):

The aggregator now treats skipped fixtures as failures so a clean checkout without the HF CLI doesn't accidentally report green:

sys.exit(0 if failed == 0 and skipped == 0 else 1)

The summary block also calls out skipped fixtures explicitly with their reason and notes that they count as failures, so the user sees what didn't run rather than just a small passed N/M line.

Verified all three modes:

# Happy path (CLI built, ffmpeg present)
$ ./run.sh ; echo "exit=$?"
  passed 4/4, failed 0, skipped 0
  exit=0

# T4-only (lint, no CLI needed)
$ ./run.sh tier-4-escape-hatch ; echo "exit=$?"
  passed 1/1, failed 0, skipped 0
  exit=0

# Clean checkout, full run, CLI not built (Miguel's repro)
$ ./run.sh ; echo "exit=$?"
  passed 1/4, failed 0, skipped 3
  ⚠ 3 skipped: tier-1-title-card, tier-2-multi-scene, tier-3-data-driven
    reason: render toolchain unavailable
  Skipped fixtures count as failures for the aggregate.
  exit=1

The single-tier mode (./run.sh tier-N-...) only counts the selected tier — tiers that weren't selected don't show up as skips, so picking T4 alone still cleanly exits 0.

[jrusso1020]

Ran /simplify on the stack. Landed in #517's amend (b7769b23):

Three run.sh cleanups:

1. Per-fixture JSON tempfiles instead of bash string concat. The old aggregator built each result as RESULTS+=("{\"fixture\":\"$name\",…}") and reassembled the array as [$(IFS=,; echo "${RESULTS[*]}")], then re-parsed it as Python source via <<PY. A fixture name with " or \ would corrupt both the JSON and the Python literal. Now each fixture writes its own $RESULTS_DIR/<fixture>.json and the aggregator globs *.json. No two-stage interpolation, no injection shape, and the per-result structure is enforced by json.dump.

2. composition_id lives in expected.json instead of being sniffed from Root.tsx via regex. This drops a python3 -c "import json, re; src = open('$file').read(); m = re.search(...)" per fixture (and a fragile shell-source-into-Python interpolation). The corresponding composition_id field was added to T1 / T2 / T3 expected.json in #508/#509.

3. Unreachable branch removed. The "missing expected.json" path in run_render_tier only fires if a fixture is locally deleted — every checked-in fixture has the file. Drop the runtime check; let read_json_value fail loudly if the file's gone.

4. Narrating comments dropped (e.g., # THIS_DIR is …, # Run a single render-tier fixture (T1, T2, T3). — restating the line above or the function name). Kept only WHY commentary (the JSON-tempfile rationale, the r2hf/lambda-import warning treatment, the skipped-fixtures-count-as-failures reasoning).

All three exit-code modes still verified:

• ./run.sh → 4/4 pass, exit 0
• ./run.sh tier-4-escape-hatch → 1/1 pass, exit 0
• ./run.sh (CLI not built) → 1/4 pass + 3 skipped, exit 1

Final report.json is structurally identical to before.

[miguel-heygen]

Re-checked the latest head against my requested-change thread. The full corpus runner now exits non-zero when render tiers are skipped because the HF CLI is missing (passed 1/4, skipped 3, rc=1), while ./run.sh tier-4-escape-hatch still runs cleanly without the CLI (rc=0). The stale @hyperframes/core build instruction is also corrected to @hyperframes/cli. This resolves my blocker.