feat(skills): mode-first briefs, value-first storyboards, and destination defaults across creation workflows

[WaterrrForever]

Esper Labs power users (MVH & Trevin) gave us direct feedback: HyperFrames is "a hammer, not a factory" — the creation workflows hand users raw tools and expect them to drive. Three complaints land squarely on the skills: no way to choose "just build it" vs "walk me through it"; PR videos lead with the diff instead of why it matters; defaults assume desktop full-screen viewing while users post to X/LinkedIn. This PR turns that feedback into two shared contracts plus opinionated defaults across the creation workflows.

What

• Mode-first intake: every creation workflow opens with one question — Collaborative (recommended) or Autonomous. Autonomous asks nothing else until a single "preview first, or render?" before the final render; a "surprise me" in the prompt skips even the first question.
• Value-first storyboards: the hook speaks the viewer's language, the message lands by beat 2, and diffs/mechanisms become supporting evidence — "implementation is the footnote of the story, not the spine."
• Recommendations carry receipts: every recommended default states its basis, and the storyboard comes back as a proposal — "This video tells [audience] that [message]" plus a frame table where every frame states its why.
• Opinionated defaults: destination drives aspect (X/LinkedIn feed → 1:1, Shorts/TikTok → 9:16, YouTube/embed → 16:9), in-feed type minimums scale up, and PR videos end on a "Shipped by" credits frame by default.

Changes

• hyperframes-core/references/brief-contract.md (new) — the shared intake contract: mode signals + propagation, four gate types (preference / checkpoint / quality / routing), the shared field registry (destination→aspect derivation, message, angle, …), and question rules (two rounds, one question per ask-marked field, receipts required). Workflows bind fields as ask/state; the contract never carries workflow-specific content.
• hyperframes-creative/references/story-spine.md (new) — three cross-workflow story rules: viewer-language hooks (no file/function names, no feature lists), reverse-iceberg ordering, and storyboard-as-proposal (echo line + per-frame why: from narrativeRole, presented as a table). Includes an exemption list (music / motion-graphics / captions / recut / slideshow) and a voice guard: value-first is an ordering decision, not a marketing tone.
• Workflow wiring — router detects mode at entry and derives aspect from destination; product-launch-video / pr-to-video / faceless-explainer get two-round question scripts at Step 0 (website-to-video's editorial register, channel-agnostic) and checkpoint-gate branches at Steps 3/6; website-to-video's local mode definition now defers to the contract; music-to-video, general-video, embedded-captions, talking-head-recut, slideshow, and motion-graphics wire in per gate type.
• pr-to-video specifics — feature-reveal reordered promise-first (impact leads; diff/mechanism follow as evidence; fix/refactor/changelog untouched — they were already value-first); the length tier is a ceiling, not a floor (a one-headline PR recommends inside the 30–90s sweet spot regardless of diff size); the credits close is the default ending (committers by commit count, 1–6 avatars; skipped only when no avatar was fetched).
• hyperframes-creative/references/typography.md — type minimums split by viewing context: full-screen keeps body 20px / headline 60px; in-feed destinations scale to body ≥32px / headline ≥90px / labels ≥24px (first-pass values, to calibrate against real renders).
• hyperframes-core/references/storyboard-format.md — optional mode frontmatter key so resumed sessions inherit the interaction mode (parser-safe: unknown keys land in globals.extra).

No skill descriptions or routing surfaces changed, so the five catalog surfaces (CLAUDE.md / AGENTS.md / README / docs / CLI templates) stay untouched.

Guardrails

• Autonomous mode changes only preference and checkpoint gates — lint / validate / inspect and routing confirmations never skip, in any mode.
• Autonomous is not silent: every absorbed question becomes "decision + one-line reason", and delivery always includes the contact sheet.
• The ask/state split is fixed per workflow binding — a question is never dropped because its answer looks inferable; confidence sharpens the recommended default instead.

Tests / verification

• Six live-test rounds on pr-to-video × a real PR (fix(cli,skills): install workflow skills on demand instead of re-pulling the full set #2012), each round converting an observed drift into a deterministic rule: mode legend not rendering → mode became the first question; question count drifting (4/3/1/2 across runs) → every question written into Step 0; the model skipping the question UI → channel rule tightened; a 1,113-line diff recommending ~130s → tier-is-a-ceiling rule; dense prose proposals → the frame table.
• End-to-end run on PR fix(cli,skills): install workflow skills on demand instead of re-pulling the full set #2012: mode question → four field questions (angle/audience/length/destination, recommended-first with receipts) → storyboard proposal with per-frame why → 1080×1080 video for the feed with the credits close. Full walkthrough with screenshots and the playable video: https://www.heygenverse.com/a/bb7c97ba-2604-450a-9840-125aa5198c16
• lint / filesize / skills-manifest / format pre-commit hooks green on every commit; manifest hashes regenerated by the hook.

[miga-heygen]

Review: LGTM with nits ✅

Well-structured skill-level documentation work. The two new contracts (brief-contract.md and story-spine.md) cleanly separate concerns: brief-contract owns intake mechanics (mode, fields, question rules), story-spine owns narrative doctrine (hook language, value ordering, proposal shape). The wiring across 14 workflow skills is consistent.

SSOT audit

• brief-contract.md — single source for mode semantics, gate taxonomy, field registry, question invariants. ✓
• story-spine.md — single source for narrative doctrine (hook language, value ordering, proposal table shape). ✓
• Per-workflow question scripts — intentionally local (Round 2 field lists differ per workflow). Contract explicitly says "invariants centralized, executable scripts local." Correct design. ✓
• No duplicated decisions across workflows for the shared contract rules. ✓

Findings (non-blocking)

1. website-to-video retains local mode definition overlapping the contract
skills/website-to-video/references/step-2-brief.md:121-130 — Suggestion

The PR correctly says "Mode semantics are canonical in brief-contract.md" in the SKILL.md, but step-2-brief.md still carries its own full mode definition (preference vs quality gates, TTS/music/captions examples). Today they agree, but the local copy could drift. Consider adding a one-line note: "These rules are this workflow's instantiation of brief-contract.md section 1 — see there for the canonical gate taxonomy."

2. embedded-captions "the user picks" contradicts autonomous mode
skills/embedded-captions/SKILL.md:101-107 — Nit

The new paragraph correctly identifies the identity pick as a preference gate and says "pick yourself." But the next existing line still reads "the user picks" — directly contradicts autonomous mode when read back-to-back. Easy fix: update the existing line to say "recommend ONE with a one-line why" without the "the user picks" suffix.

3. aspect field description is terse
skills/hyperframes-core/references/brief-contract.md — Nit

In the field registry table, aspect's Meaning column just says "canvas." Every other field has a short phrase. "canvas aspect ratio" would be more consistent.

Summary

Clean PR that extracts two genuine shared contracts from previously ad-hoc per-workflow behavior, wires them consistently across all 14 affected skills, and hardens pr-to-video with value-first ordering and credits-close-by-default from real user testing. All markdown — no runtime code, no tests affected. Ship it.

— Miga

[jrusso1020]

Review — COMMENT (external author; stamp = James's call)

Audited: the two new shared contracts (hyperframes-core/references/brief-contract.md and hyperframes-creative/references/story-spine.md) end-to-end; workflow-side wiring in product-launch-video, pr-to-video, faceless-explainer, website-to-video, general-video, music-to-video, motion-graphics, slideshow, talking-head-recut, embedded-captions; the router (skills/hyperframes/SKILL.md); PR-body claims; and the manifest regeneration.

Trusting: the six iterative live-test rounds on PR #2012 described in the PR body (I don't have a reproducible fixture to replay them from), and Miga's parallel review-in-flight for a second pass.

Strengths (file:line-cited)

• Contract scope is clean and non-overlapping. brief-contract.md owns interaction mode + shared field registry + question rules; story-spine.md owns narrative ordering rules and defers voice to the workflow. Neither leaks workflow-specific content. The mode is set once invariant + the 4-gate taxonomy (preference / checkpoint / quality / routing) at brief-contract.md § 1 is exactly the right shape for guarding against "autonomous → skip verification" misuse; the explicit "Reasoning like 'autonomous means bias toward action, so I'll skip verification' misuses the mode" is a real footgun-blocker in prose.
• Exemption lists are enforced by wiring, not just documented. story-spine.md's exemption list (music-to-video, motion-graphics, embedded-captions, talking-head-recut, slideshow) is honored: none of those SKILL.md files reference story-spine (verified with grep across all 13 touched SKILLs). Conversely, the 5 workflows the spine claims (product-launch / pr-to-video / faceless-explainer / website-to-video / general-video) each wire it in — for narrated story workflows on the main path, and conditionally ("when the piece tells a story") in general-video per the spine's own exemption note.
• Story-workflow trio has identical Step 0 preambles — product-launch-video/SKILL.md:14, pr-to-video/SKILL.md:14, faceless-explainer/SKILL.md:14 all read "Read ../hyperframes-core/references/brief-contract.md before Step 0 — it defines the two modes, the gate types, and the brief fields; the mode governs the Step 0/3/6 gates." Not accidentally-drift-prone.
• Value-first framing correctly separates ordering from voice — story-spine.md § 2 last sentence: "Structure is value-first; the voice stays whatever the workflow prescribes (a PR video keeps its plain, no-hype developer voice — leading with value is an ordering decision, not a marketing register)." This kills the natural drift-toward-marketing-tone risk of "value-first" up front.
• Manifest regeneration is byte-clean. skills-manifest.json +15/-15 = only the hashes of skills whose files actually changed were updated (embedded-captions, faceless-explainer, general-video, hyperframes, hyperframes-core, hyperframes-creative, motion-graphics, music-to-video, pr-to-video, product-launch-video, slideshow, talking-head-recut, website-to-video). figma hash unchanged (no touched files under it). Pre-commit hook regenerated it correctly + CI's Skills: manifest in sync gate is green.

Verified PR-body claims

• "the five catalog surfaces (CLAUDE.md / AGENTS.md / README / docs / CLI templates) stay untouched" — verified via gh api pulls/2058/files grep: zero hits under CLAUDE.md|AGENTS.md|README.md|docs/guides/skills.mdx|packages/cli/src/templates/. Claim holds; correct call since no skill descriptions or routing surfaces moved (per Rule "adding/repurposing skills means updating the five catalogs in lockstep" — the inverse here: content changes that DON'T touch descriptions/routing DON'T need catalog sync).
• Autonomous single-question invariant (preview vs render only) — brief-contract.md § 1 states it explicitly; router (skills/hyperframes/SKILL.md:51) echoes it; product-launch / pr-to-video / faceless-explainer Step 0 sections each carry the literal two-round script.
• Destination-defaults regression safety for unknown/desktop — router at skills/hyperframes/SKILL.md:53: "YouTube / embed / unknown → 16:9". Users who don't specify a destination still get the pre-PR default. No silent regression.

Nits (all non-blocking)

• (nit / spine self-check) story-spine.md § 2 recommends a self-check: "Delete every evidence beat — the remaining beats must still state the value on their own." That's an excellent authoring rubric but it's phrased as a suggestion to the model, not enforced anywhere. If a future storyboard reviewer wanted to catch violations at build time, the frame-table format's Why column (with the "trace back to message" contract from § 3) is the mechanical hook — currently only prose-enforced.
• (nit / typography first-pass) hyperframes-creative/references/typography.md label acknowledges the in-feed values are "first-pass values, to calibrate against real renders." That's good self-signaling. Worth a follow-up issue to actually calibrate once the first N feed videos ship, so this doesn't become the permanent baseline.
• (nit / brief-contract § 3 "receipts") The receipts requirement ("Every recommended option states its basis: '~40s — small change, +44/−13 across 12 files'") — the example is pr-to-video-shaped. Consider adding one non-diff example (e.g. product-launch: "~60s — SaaS promo, 30–90s sweet spot") so future readers of the contract in isolation don't over-anchor on the PR-video example.
• (question, not a finding) The mode: autonomous frontmatter key in storyboard-format.md — how does a resumed session actually READ that? Does the workflow SKILL.md's Step 0 script check for it and skip questions? The doc adds the field but the workflow-side "read frontmatter to inherit mode" wiring wasn't obvious in my scan of the Step 0 templates. If that's carried in a reference file I skimmed past, please point at it; if it's not wired yet, might be worth a small follow-up rather than a mode key that's set but not read.

Verdict

COMMENT — contract design is clean, exemption enforcement is real (not just documented), the "autonomous ≠ silent + never skips quality gates" invariant is well-anchored across contract + router + workflows, and CI is green on 2aacb79bb0ac. As before, stamp = @jrusso1020's call (external author WaterrrForever; requester Miao is allowlisted but not a trusted-stamper, per delegation rule).

— Rames Jusso