ukimsanovandClaude Opus 4.7
5594a8286c
A second agent debrief (different session, with the prior enforcement edits
applied) revealed the most damning failure yet: the agent used 1 of 65
captured assets. They wrote their own "Asset Audit" table saying SKIP for
64 hero illustrations, brand SVGs, and signature visuals. The entire point
of capture is to USE the brand's assets — that gate was bypassed entirely.
The debrief also revealed 5 other patterns the prior enforcement missed.
This commit closes all 6.
**Pattern A — Asset Audit gate (step-3-storyboard.md)** — BIGGEST FIX
Adds a non-skippable Asset Audit section in Step 3 that requires viewing
every page of capture/assets/contact-sheet-*.jpg + svgs/contact-sheet-*.jpg,
pasting 5 distinctive assets per page (with descriptions of what's actually
pictured), and choosing USE/SKIP per asset with one-sentence justification
for each SKIP. Brand-defaults floor: at least one beat MUST use a captured
hero illustration/photograph/signature diagram — not just the logo. The
forbidden list explicitly calls out: reading asset-descriptions.md alone
without opening the contact sheets, and rebuilding signature graphics in
CSS when the brand's own SVG of that graphic is in capture/assets/.
**Pattern B — Auto mode scope (SKILL.md + step-2-brief.md)**
Clarifies that auto mode covers user-PREFERENCE gates (TTS provider,
voice, beat count, captions yes/no — where the agent decides on the
user's behalf) but NOT quality-VERIFICATION gates (Asset Audit, per-beat
HTML read, DoD checklist, honest disclosure). Adds explicit test for
distinguishing: if the answer changes the content of the video, it's a
preference; if the answer is "did the verification happen?", it's a
quality gate. The agent that skipped the captions question by reasoning
"auto mode says bias toward action" was misusing auto mode.
**Pattern C — 3-path audio/motion verification (step-6-validate.md)**
Replaces the prior "Path 1 or explicit deferred" with three explicit
paths: (1) Play preview in Playwright, (2) render low-res MP4 and read
frames at ≥5fps, or (3) explicit deferred disclosure with QUANTIFIED
coverage gap ("18/900 frames = 2% coverage"). The percentage in Path 3 is
mandatory — vague "deferred to user" was the loophole. Forbidden: claiming
"confirmed via snapshot" as audio/motion evidence; 18 PNGs from a 900-
frame video is 2% coverage, not verification.
**Pattern D — Sub-agent diagnoses are hypotheses (beat-builder-guide.md)**
When a sub-agent reports "this is a linter false positive" / "this is a
known bug", that is a HYPOTHESIS from one symptom — not a verified
finding. Before propagating the workaround to other beats, main agent
must EITHER read the source to confirm OR explicitly disclose the
unverified claim. The debrief showed the main agent applied beat-2's
"linter false positive" diagnosis to beat-4 without ever reading
packages/core/src/lint/utils.ts to confirm.
**Pattern E — Re-snapshot after parallel sub-agents (step-5-build.md)**
When sub-agents run in parallel, each snapshots a project where sibling
beats may not exist yet. Their snapshots at beat boundaries or during
shader transitions show the WRONG content (typically previous beat).
Required after all complete: a canonical project-wide snapshot via the
CLI — that's what Step 6's DoD uses. Sub-agents' intermediate snapshots
are sanity checks, not the deliverable.
**Pattern F — STORYBOARD.md must be updated when divergence accepted
(beat-builder-guide.md)**
When a sub-agent diverges from spec ("the real brand mark is lowercase
'huly' not uppercase 'HULY'") AND the main agent accepts the divergence,
the main agent MUST patch STORYBOARD.md to reflect reality. Otherwise
the spec lies and the next session reading it as ground truth gets the
wrong information. Examples covered: brand mark casing, cell size at
scale, SFX timing alignment.
6 files changed, +131/-11 (net +120 lines of enforcement).
Format checks pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
10 KiB
name, description
| name | description |
|---|---|
| website-to-hyperframes | Capture a website and create a HyperFrames video from it. Use when: (1) a user provides a URL and wants a video, (2) someone says "capture this site", "turn this into a video", "make a promo from my site", (3) the user wants a social ad, product tour, or any video based on an existing website, (4) the user shares a link and asks for any kind of video content. Even if the user just pastes a URL — this is the skill to use. |
Website to HyperFrames
Capture a website, then produce a professional video from it.
Users say things like:
- "Capture https://... and make me a 25-second product launch video"
- "Turn this website into a 15-second social ad for Instagram"
- "Create a 30-second product tour from https://..."
The workflow has 7 steps. Each produces an artifact that gates the next. By default it's collaborative — gates marked 💬 stop and ask the user. If the user signals autonomous mode ("decide for me", "surprise me"), 💬 user-preference gates are skipped; see step-2-brief.md for how that propagates.
Autonomous mode is NOT "skip all gates." Auto mode covers user-preference questions (TTS provider, voice, color emphasis, beat count, music yes/no, captions yes/no — where the agent decides on the user's behalf). It does NOT cover quality-verification gates. The following remain non-skippable in auto mode:
- Asset Audit (Step 3) — viewing contact sheets and justifying USE/SKIP for each asset
- Per-beat HTML read (Step 5) — structured evidence block per beat
- DoD checklist (Step 6) — including animation-map, per-warning WCAG verification, audio/motion playback
- Honest disclosure section (Step 6) — "What I did NOT verify" must appear in your final summary
If you find yourself reasoning "auto mode says bias toward action, so I'll skip X" — and X is a verification gate, not a preference question — that reasoning is wrong. Bias toward action applies to deciding what to build, not to deciding whether to verify.
Step 0: Capture & Understand the Brand
Read: references/step-0-capture.md
Capture the site, then read the extracted data to understand the brand and product — what it does, who it's for, what voice it speaks in, what mood it lives in. The captured assets are a brand toolkit for later, not the building blocks the video is made from.
Gate: Site summary printed — strategy-first (what the product does, who it's for, brand voice) before the asset / color / font inventory.
Step 1: Brand Identity
Read: references/step-1-design.md
Write DESIGN.md — a brand cheat sheet covering the visual identity: colors, typography, component styles, layout principles. Use design-styles.json for exact computed values.
Speed option: For fast-pacing videos (billboard-per-beat), DESIGN.md can be a 50-line summary of colors + fonts + do's/don'ts — not a 300-line document. The sub-agent prompt in Step 5 pastes brand values directly, so DESIGN.md depth only matters for complex compositions.
Gate: DESIGN.md exists (any length) with at minimum: color palette, font choices, and do's/don'ts.
Step 2: Strategy & Messaging
Read: references/step-2-brief.md, references/capabilities.md (scan the Table of Contents — deep-dive sections only as needed)
Align with the user on what the video must communicate before talking visuals or assets. Parse the user's prompt — they probably already gave you the video type and style. Ask only what's missing: the ONE thing this video must say, the narrative arc, and the audience.
Gate: Video type, duration, format, and — critically — the message and narrative arc are locked. Without those, Step 3 can't write a concept-first storyboard.
Step 3: Storyboard + Script 💬
Read: references/step-3-storyboard.md
Write the storyboard concept-first: message → narrative arc → beats that serve the arc → techniques per beat → brand accents pass at the end. Then write the narration script to match. Present both to the user with a beat-by-beat summary. Iterate until they approve.
Gate: STORYBOARD.md + SCRIPT.md exist AND the user has approved the plan.
Step 4: VO, Timing + Captions 💬
Read: references/step-4-vo.md
If Step 2 said no narration — ask about background music, then skip to Step 5. Otherwise: ask the user which TTS provider (HeyGen TTS, ElevenLabs, or Kokoro), generate audio, transcribe, map timestamps to beats. Then ask about captions.
Gate: Either (a) no narration was requested and storyboard has manual beat timings, or (b) narration.wav + transcript.json exist and beat timings updated with real durations.
Step 5: Build Compositions
Read: The hyperframes skill (load it — every rule matters)
Read: references/step-5-build.md
Build index.html and compositions following the architecture and pacing chosen in the storyboard (Step 3). Sub-agents run hyperframes lint and hyperframes snapshot on each beat before reporting back.
Gate: Every compositions/beat-N.html has been read top-to-bottom by the main agent against DESIGN.md and STORYBOARD.md. The per-beat checklist lives in step-5-build.md.
Step 6: Validate & Deliver
Read: references/step-6-validate.md
Lint, validate, take snapshots scaled to video length (formula: max(beats × 3, ceil(duration_seconds / 2))), and review each one. Fix issues before delivering. Deliver the localhost Studio project URL — only render to MP4 on explicit user request.
Deliver something you're proud of. Before handing off, ask yourself: would I post this on social media with my name on it? If not, fix what's wrong.
Gate: npx hyperframes lint and npx hyperframes validate pass with zero errors, and the final response includes the active Studio project URL.
Quick Reference
Video Types
Typical constraints by video type — use as a starting point, not a formula. Beat count should follow from the content and the narration, not from a target range.
| Type | Typical duration | Duration driver | Narration |
|---|---|---|---|
| Social ad (IG/TikTok) | 10–15s | Platform limit | Optional |
| Product demo | 30–60s | Script length | Full narration |
| Feature announcement | 15–30s | Feature complexity | Full narration |
| Brand reel | 20–45s | Music track | Optional, music focus |
| Launch teaser | 10–20s | Hook energy | Minimal |
Beat count is not in this table intentionally — it should come from the storyboard, not from "social ad = 3-4 beats." A social ad for a complex product might need 5 well-timed beats. A brand reel with one strong visual thesis might need 3.
Format
- Landscape: 1920x1080 (default)
- Portrait: 1080x1920 (Instagram Stories, TikTok)
- Square: 1080x1080 (Instagram feed)
Reference Files
| File | When to read |
|---|---|
| step-0-capture.md | Step 0 — capture, understand the brand and product, write strategy-first site summary |
| step-1-design.md | Step 1 — write DESIGN.md brand cheat sheet (5 sections, 250-350 lines; 50-line fast-path for billboard-style social ads) |
| step-2-brief.md | Step 2 — align on message, narrative arc, audience with user |
| capabilities.md | Steps 2 & 5 — full inventory of what HyperFrames can do (24 sections). Scan the TOC during the brief, deep-dive specific sections during build |
| step-3-storyboard.md | Step 3 — storyboard + script (combined) with user review gate |
| step-4-vo.md | Step 4 — TTS provider choice, generation, timing |
| step-5-build.md | Step 5 — build index.html + compositions |
| step-6-validate.md | Step 6 — lint, validate, snapshots (scaled to video length), preview |
| techniques.md | Steps 3 & 5 — 13 primitive animation techniques with code patterns (adapt, don't copy-paste) |
| html-in-canvas-patterns.md | Step 5 — complete code patterns for HTML-in-Canvas effects (lives in the hyperframes skill) |