promo-from-brief

name

promo-from-brief

description

Use when the user gives a text brief for a branded promo short -- "promo for the <event> webinar", "componme el promo de X con la marca Y". Composes scene-spec.json from the promo-* library (promo-intro-card, promo-hero, promo-card-speaker, promo-blur-cta, promo-agenda, promo-quote, promo-details), binds a brand pack via spec.brand, then assembles, runs per-scene QA, and renders. Defer to this skill for any brand-pack-driven promo. Skip for non-promo shorts (canonical-short) and when the brand pack does not exist yet (extract-brand-pack first).

Promo from brief

CWD: all bash commands below assume cd apps/hyperframe first. Paths like src/episodes/<slug>/, brands/<slug>/ are app-relative.

A promo episode is a typed scene-spec.json composed from the promo-* scene-type library, with a top-level "brand": "<brand-slug>" binding it to brands/<brand-slug>/brand.json. The assembler stamps the brand pack's --brand-* CSS variables into the generated index.html -- never hand-edit index.html; edit the spec (or the brand pack) and re-run bun run assemble <slug>. No Figma reference is needed: everything comes from the text brief + the brand pack + photo composites.

Scope

• IN: composing a complete branded promo episode from a text brief (campaign goal, speaker, date, language, CTA) using only the existing promo-* scene-types.
• OUT: extracting a new brand (.agents/skills/extract-brand-pack/SKILL.md), building a new scene-type from a design reference (.agents/skills/figma-to-scene-type/SKILL.md), non-promo shorts (canonical-short).

Inputs

Collect before touching the spec; ask the user for anything missing:

1. Brief -- campaign goal, event name, speaker name + role, date/time, language of the copy, CTA wording.
2. Brand slug -- must exist as brands/<brand-slug>/brand.json. ls brands/ to verify; if missing, stop and run extract-brand-pack first (assemble hard-errors on a declared-but-missing brand pack).
3. Photo composites -- per-campaign inputs, NOT generated by this skill. Sources, in order of preference: existing exports under the episode's assets/ from a prior Figma session, exports produced during the extract-brand-pack flow, or AI generation via .agents/skills/generated-raster-assets/SKILL.md. Needed kinds: speaker photo card(s), blurred full-bleed background composite(s), circular avatar crop.
4. Logo files -- brand wordmark in dark-on-light and light-on-dark variants (SVG preferred), usually copied from brands/<brand-slug>/.

Scene grammar

The seven promo-* types and their required slots (full detail: read templates/scenes/<type>/v1/manifest.json). All are 1080x1920 story-ad replicas sharing the same family geometry.

Type	Purpose	Required slots
promo-intro-card	Opener on a white frame: centered rounded photo card with notch badge, name/role, logo + headline + date	badge, speakerName, speakerRole, title, date, photoImage, logoImage
promo-hero	Photo card pinned top over dimmed blur bg, light-on-dark lower block with logo + title + body + CTA	badge, title, body, cta, bgImage, photoImage, logoImage
promo-card-speaker	White frame: photo card upper half, badge + name/role on top, dark-on-light lower block with CTA	badge, speakerName, speakerRole, title, body, cta, photoImage, logoImage
promo-blur-cta	Closer: full-bleed blur bg, circular avatar + name/role mid-frame, light-on-dark lower block with CTA	badge, speakerName, speakerRole, title, body, cta, bgImage, avatarImage, logoImage
promo-agenda	White frame: badge, display title, 2-4 numbered topic rows, logo + date footer	badge, title, items (repeat 2-4, each { "text" }), date, logoImage
promo-quote	Pull quote on blur bg, circular avatar + name/role below, logo footer	badge, quote, speakerName, speakerRole, bgImage, avatarImage, logoImage
promo-details	White frame recap: badge, logo, display title, 2-4 info chips (date/time/format), solid CTA	badge, title, chips (repeat 2-4, each { "text" }), cta, logoImage

Narrative ordering (default beat sequence; cut beats for shorter promos, never reorder against the funnel):

1. Announce -- promo-intro-card (speaker-led) or promo-hero (event-led).
2. Agenda -- promo-agenda: what attendees get.
3. Quote -- promo-quote: speaker credibility beat.
4. Urgency -- promo-hero or promo-card-speaker with scarcity copy ("last seats", date proximity).
5. Recap -- promo-details: date/time/format chips.
6. CTA closer -- promo-blur-cta, always last.

Durations: 4-5s per scene (type defaults already sit in that band; closer gets 5s). A 6-beat promo lands at ~27s.

Skeleton (light vs dark logo variants follow the frame: dark-on-light scenes take the black logo, blur-bg scenes the white one):

{
  "slug": "<episode-slug>",
  "lang": "es",
  "width": 1080,
  "height": 1920,
  "brand": "<brand-slug>",
  "palette": { "accent": "#111111", "accent2": "#8a8f98" },
  "scenes": [
    { "id": "intro", "type": "promo-intro-card", "duration": 4.5, "slots": { "badge": "Webinar gratuito", "speakerName": "...", "speakerRole": "...", "title": "Linea uno<br>linea dos", "date": "...", "photoImage": "assets/photo-card.png", "logoImage": "assets/logo-black.svg" } },
    { "id": "agenda", "type": "promo-agenda", "duration": 4.5, "slots": { "badge": "...", "title": "...", "items": [{ "text": "..." }, { "text": "..." }, { "text": "..." }], "date": "...", "logoImage": "assets/logo-black.svg" } },
    { "id": "quote", "type": "promo-quote", "duration": 4, "slots": { "badge": "...", "quote": "...", "speakerName": "...", "speakerRole": "...", "bgImage": "assets/bg-blur.png", "avatarImage": "assets/avatar.png", "logoImage": "assets/logo-white.svg" } },
    { "id": "urgency", "type": "promo-hero", "duration": 4.5, "slots": { "badge": "...", "title": "...", "body": "... <strong>...</strong>", "cta": "...", "bgImage": "assets/bg-blur.png", "photoImage": "assets/photo-hero.png", "logoImage": "assets/logo-white.svg" } },
    { "id": "details", "type": "promo-details", "duration": 4.5, "slots": { "badge": "...", "title": "...", "chips": [{ "text": "..." }, { "text": "..." }], "cta": "...", "logoImage": "assets/logo-black.svg" } },
    { "id": "closer", "type": "promo-blur-cta", "duration": 5, "slots": { "badge": "...", "speakerName": "...", "speakerRole": "...", "title": "...", "body": "...", "cta": "...", "bgImage": "assets/bg-blur.png", "avatarImage": "assets/avatar.png", "logoImage": "assets/logo-white.svg" } }
  ]
}

Reference implementation: src/episodes/vidext-webinar-ita/scene-spec.json.

Copy rules

• Copy is a draft. Present the full per-scene copy table to the user for approval BEFORE assembling. Never invent factual claims -- no made-up stats, bios, attendee numbers, or company history; everything factual must come from the brief or be asked for.
• Write in the brief's language. For Spanish: español de España, never argentinisms (no "cerrás/tenés/vos/fijate").
• Display titles (title, quote) are richText: break lines with explicit <br> where the layout needs two lines -- the scene-types do not auto-wrap display type. body accepts <strong> for the CTA-adjacent emphasis.
• Keep the badge text identical across scenes (it is the campaign label, e.g. "Webinar gratuito").

Workflow

bun run new:episode <episode-slug> --intent=social     # scaffold; starter spec gets replaced

1. Scaffold with the command above, then replace the starter scene-spec.json entirely with the composed promo spec (skeleton above). Promo episodes do not use the house outro -- promo-blur-cta is the brand sign-off.
2. Add "brand": "<brand-slug>" at the top level. Leave meta.json alone: meta.brand is a render-time override only; assemble-time stamping carries into QA and render on its own.
3. Stage assets. Copy photo composites, avatar, and logo variants into src/episodes/<episode-slug>/assets/. For a non-Inter brand, also copy the brand woff2 there AND confirm the pack declares it in its fonts array (brands/<brand-slug>/brand.json, e.g. "fonts": [{ "family": "Sora", "file": "SoraVariable.woff2" }]) -- the assembler emits the @font-face from that field; the shell itself only registers Inter and Berkeley Mono.
4. Validate + assemble:

   bun run scene:check src/episodes/<episode-slug>/scene-spec.json
   bun run assemble <episode-slug>
   

   Confirm the brand actually bound: grep -o 'data-brand="[^"]*"' src/episodes/<episode-slug>/index.html must print the brand slug (a typo'd spec key like "brnad" is silently ignored and renders unbranded).
5. Per-scene QA (HITL):

   bun run scripts/scene-qa.ts <episode-slug> [--scenes=id1,id2]
   

   Show the contact sheet; iterate only rejected scenes via --scenes=. Get explicit approval per scene before rendering.
6. Render:

   bun run render:episode <episode-slug> --format=mp4
   

   The render log should show the brand slug; a publishable: false pack warns here and only here.

Gotchas

• assemble hard-errors on a missing brand pack. "brand": "x" with no brands/x/brand.json stops the build with a named error -- run extract-brand-pack first, or remove the field.
• Editing brand.json requires re-assemble. Brand values are baked into the generated html, same rule as spec edits; QA and render read whatever index.html is on disk.
• meta.json brand stays unset. Setting it creates a double source; it exists only to override the brand at render time.
• Photo radii may be baked into the image assets. .pin-photo/.pcs-photo have no CSS border-radius -- the rounded corners live in the exported PNG. Prepare speaker composites already rounded (and avatars already circular), or they render square.
• Composites are inputs, not outputs. This skill never generates photos; missing composites means pausing to source them (Figma export, extract-brand-pack leftovers, or generated-raster-assets).
• Brand font needs file + declaration. --brand-font alone changes only the stack; the woff2 must sit in the episode assets/ and the pack's fonts array must declare it (that emits the @font-face). Missing either means the render silently uses system-ui and line wraps drift.

Final checklist

• Brand pack exists; data-brand="<brand-slug>" present in the assembled index.html.
• Per-scene copy approved by the user; no invented facts; correct language variant; <br> line breaks in display titles.
• All photoImage/bgImage/avatarImage/logoImage paths resolve under the episode assets/; logo polarity matches each frame.
• Brand font woff2 staged in assets/ and declared in the pack's fonts array (if the brand is not Inter).
• scene:check passes; every scene approved in the scene-qa HITL loop; meta.json untouched.
• Render log shows the brand; total runtime ~4-5s per scene.

Handoff

Publishing copy (YouTube/TikTok/Reels/LinkedIn) for the rendered promo: .agents/skills/generate-distribution-copy/SKILL.md.