mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-03 04:38:33 +00:00
WaterrrForever
17b852784b
* feat(skills): add brief contract — interaction modes + shared intake fields across workflows New hyperframes-core/references/brief-contract.md, the shared intake contract every creation workflow now runs its brief against: - §1 interaction mode: collaborative (default) vs autonomous, ongoing vs one-time signals, mode set once and carried forward, and a gate taxonomy (preference / checkpoint / quality / routing) — autonomous skips waiting, never verification - §2 field registry: destination→aspect derivation (feed → 1:1, Shorts/TikTok → 9:16, else 16:9), message, angle, length, audience, language, narration — each workflow binds fields as ask or state - §3 question rules: one round with one question per asked field (native question UI mandatory when available, recommended option first with a receipt), never drop a question as inferable, and a mode legend advertised in the intro text instead of asked Wired into the surfaces: - hyperframes router: detect mode at entry, derive aspect from destination instead of stating 16:9 - product-launch-video / pr-to-video / faceless-explainer: ask/state binding tables at Step 0; Step 3/6 checkpoint-gate branches (autonomous posts a heads-up with a preview hint before render) - website-to-video: local mode definition now defers to the contract - music-to-video, general-video, embedded-captions, talking-head-recut, slideshow, motion-graphics: mode semantics wired per gate type - storyboard-format: new optional 'mode' frontmatter key - pr-to-video: length tier is a ceiling, not a floor — a one-headline PR recommends inside the 30–90s sweet spot regardless of diff size * feat(skills): story spine + mode-first brief across creation workflows Story — the reverse-iceberg feedback: - New hyperframes-creative/references/story-spine.md, three rules for the narrated workflows: the hook speaks the viewer's outcome language, the value claim lands by beat 2 (implementation is the footnote of the story, not the spine), and the storyboard is presented as a proposal — 'This video tells [audience] that [message]' plus a per-frame why: drawn from narrativeRole - pr-to-video: feature-reveal reordered promise-first (impact leads, diff/mechanism follow as evidence); hooks ban file/function names; fix-explainer, refactor-walkthrough, changelog unchanged - product-launch-video / faceless-explainer hook rules aligned to the spine; website-to-video's beat summary gains the echo line + why:; general-video points at the spine from its plan step Brief — hardened after live-test drift: - Mode is now the first question (Collaborative recommended vs Autonomous), its own round, skipped when the request carries a signal; autonomous asks nothing further until one final preview-or-render question before render - Step 0 rewritten as a literal two-round question script in each shot-sequence workflow (website-to-video's editorial register, channel-agnostic); brief-contract.md §3 reduced to invariants so the procedure lives in exactly one place * feat(skills): split type minimums by viewing context typography.md: full-screen viewing keeps body 20px / headline 60px; in-feed destinations (X / LinkedIn / Instagram — brief-contract's destination field) scale to body >=32px, headline >=90px, data labels >=24px. First-pass values, to be calibrated against real renders. * feat(skills): storyboard proposal as a table + credits close by default - story-spine § 3: the proposal presents frames as a markdown table (frame · beat · on screen · why) instead of dense paragraphs; the three shot-sequence workflows and website-to-video's beat summary reference the same shape - pr-to-video: the credits close is now the default ending — every PR video ends on a contributors frame (committers by commit count, 1-6 avatars), with no taste judgment; the only skip is when no avatar was fetched, and the user can cut the frame in the proposal * fix(skills): address review nits on the brief/story contracts - embedded-captions: the identity procedure now states both sides of the preference gate inline (user picks; autonomous picks with a stated why) - website-to-video step-2-brief: note that its mode section is the workflow's application of brief-contract.md, not a second definition - brief-contract: resuming a project reads mode from STORYBOARD.md frontmatter — a recorded mode counts as set, closing the write-only gap * docs(skills): add a non-code receipts example to the brief contract Review nit (jrusso1020, #2058): the receipts example in § 3 was PR-video-shaped only. A destination-shaped example joins it so the rule reads as workflow-neutral.
72 lines
5.8 KiB
Markdown
72 lines
5.8 KiB
Markdown
---
|
|
name: hyperframes-creative
|
|
description: Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.
|
|
---
|
|
|
|
# HyperFrames Creative
|
|
|
|
Brand, pacing, style, narration, and composition direction. Use after the technical contract from `hyperframes-core` is in place.
|
|
|
|
For motion patterns, scene blueprints, transitions, and CSS marker effects, use `hyperframes-animation` — this skill is intentionally non-animation.
|
|
|
|
> **Read these two FIRST for any non-trivial composition — they override web instincts:**
|
|
>
|
|
> - `references/house-style.md` — "interpret the prompt, generate real content," the lazy-default list, and the background/foreground layer recipe. This is what turns a literal restyle into a _concept_.
|
|
> - `references/video-composition.md` — video-medium density, scale, foreground metadata (the "produced, not generated" detailing: data bars, registration marks, monospace readouts, 8-10 elements/scene).
|
|
>
|
|
> Skipping these is the single biggest cause of generic, web-page-looking output. They are not optional rows in the routing table below — for anything beyond a one-line edit, open both before you choose colors or write HTML.
|
|
|
|
## Workflow
|
|
|
|
1. If a project has a design spec, **read it first** and treat its frontmatter tokens as brand truth (colors, fonts, spacing, tone, constraints). Which file to read (precedence `frame.md` → `design.md` → `DESIGN.md`) and how to parse it (frontmatter = normative, prose = context) are defined once in [`references/design-spec.md`](references/design-spec.md) — resolve and load per that doc.
|
|
2. If no design spec exists and the user asks for visual direction, choose a route:
|
|
- Ready-made frame-preset (optional) → `frame-presets/` (adopt a `FRAME.md` as `frame.md`; see `references/design-spec.md`)
|
|
- Named style or mood → `references/visual-styles.md`
|
|
- Fast defaults → `references/house-style.md`
|
|
- Interactive selection → `references/design-picker.md`
|
|
3. For multi-scene work, plan beats and rhythm before writing HTML → `references/beat-direction.md`. For scene transitions, jump to `hyperframes-animation/transitions/`.
|
|
4. For motion-heavy work, read `references/motion-principles.md` (high-level guardrails), then go to `hyperframes-animation` for atomic rules.
|
|
|
|
## Routing
|
|
|
|
| Topic | Read |
|
|
| ----------------------------------------------------------------------------- | ---------------------------------------------- |
|
|
| Adopt a ready-made frame-preset as `frame.md` (optional) | `frame-presets/` · `references/design-spec.md` |
|
|
| Default palettes, motion, typography, lazy defaults to question | `references/house-style.md` |
|
|
| Named style presets, mood-to-style routing | `references/visual-styles.md` |
|
|
| Palette-specific color tokens | `palettes/*.md` |
|
|
| Composition patterns — PiP, text-behind-subject, title card, slide show | `references/composition-patterns.md` |
|
|
| Stats / infographic presentation | `references/data-in-motion.md` |
|
|
| Structured expansion for open-ended prompts | `references/prompt-expansion.md` |
|
|
| Video-medium density, scale, color, frame composition | `references/video-composition.md` |
|
|
| Per-beat direction, rhythm planning, transition timing | `references/beat-direction.md` |
|
|
| Post-authoring spec verification (colors, type, corners, spacing, depth) | `references/design-adherence.md` |
|
|
| High-level motion guardrails and GSAP-quality rules | `references/motion-principles.md` |
|
|
| Font selection, pairings, rendered-video type guardrails | `references/typography.md` |
|
|
| Story doctrine — hook language, value-before-evidence, storyboard-as-proposal | `references/story-spine.md` |
|
|
| Script pacing, tone, openings, number pronunciation | `references/narration.md` |
|
|
| Precomputed audio bands mapped to motion | `references/audio-reactive.md` |
|
|
|
|
## Scripts
|
|
|
|
- `scripts/contrast-report.mjs` — inspect contrast warnings from rendered frames.
|
|
- `scripts/extract-audio-data.py` — pre-extract audio bands for audio-reactive compositions.
|
|
- `scripts/package-loader.mjs` — support script for bundled creative tooling.
|
|
|
|
`contrast-report.mjs` resolves helper packages from the current project first, then can bootstrap the bundled HyperFrames package version. Set `HYPERFRAMES_SKILL_PKG_VERSION=<version>` only when running the skill outside the bundled CLI/skill install and you need to pin that bootstrap version explicitly.
|
|
|
|
Run from the repo root with explicit paths, for example:
|
|
|
|
```bash
|
|
python skills/hyperframes-creative/scripts/extract-audio-data.py <audio-file>
|
|
```
|
|
|
|
Animation analysis (`animation-map.mjs`) lives in `hyperframes-animation/scripts/`.
|
|
|
|
## Boundaries
|
|
|
|
- Do not override `hyperframes-core` technical rules.
|
|
- Do not require a design system for a minimal technical composition.
|
|
- Do not add extra scenes, narration, music, captions, or transitions unless the request calls for them or you first propose the expansion.
|
|
- Keep recipe references task-specific; do not read every reference for simple edits.
|