Constructeur de Prompts HyperFrames
Spécialiste qui fait le pont entre le modèle de contenu du moteur marketing (brief, task_kind, provider_override) et le contrat de composition HyperFrames. Miroir de higgsfield-prompt-builder et topview-prompt-builder dans la forme — même répartiteur, cible différente — afin que video-prompt-builder puisse changer de fournisseur sans modifier sa propre logique.
Quand l'invoquer
video-prompt-builderrésout le fournisseur vidéo enhyperframespour une pièce.task_kindest l'un des suivants :motion-typography,data-viz-reel,programmatic-short(les tâches natives d'hyperframes dansPROVIDERS.md).- Une pièce déclare
provider_override.video: hyperframesdans son frontmatter. - Un visuel approuvé (carte de citation de
gpt-image, carrousel detopview) est promu en animation et le système de types doit rester fidèle à l'original. - L'orchestrateur a besoin que la même composition soit rendue à nouveau avec de nouvelles valeurs de variables (reel KPI hebdomadaire, mise à jour de prix quotidienne, variante A/B de copie) sans solliciter à nouveau un générateur IA.
Entrées
brief: objet. Le brief de la pièce avec au moinsheadline,body?,cta?,aspect,duration_seconds.task_kind:"motion-typography" | "data-viz-reel" | "programmatic-short".piece_path: chaîne, optionnelle. Chemin vers.specs/pieces/<piece-id>.md. Le frontmatter peut contenirprovider_override,compliance_flags,variables.client_slug: chaîne. Utilisé pour charger.marketing-engine/clients/<slug>/design.md(ouclients/<slug>/design.mddans le dépôt du moteur).output_dir: chaîne. Où se trouvent le projet et le MP4 final (par défautoutputs/<client>/<date>/<piece-id>/).dry_run: booléen, optionnel. Quand il est vrai, retourne la spécification de composition et les arguments de rendu sans invoquerhyperframes-cli.
Processus
- Charger le contexte de marque. Lire
clients/<client_slug>/design.mdet résoudre{ colors, type_pairing, spacing_scale, brand_voice }. Si manquant, refuser de continuer — afficher le chemin manquant. Les violations de marque ne peuvent pas être corrigées en aval. - Résoudre les surcharges. Si
piece_pathest défini et que le frontmatter contientprovider_override.video, confirmer qu'il s'agit dehyperframes; sinon, cette compétence ne devrait pas être exécutée. - Mapper task_kind à un modèle de composition.
motion-typography→ modèlekinetic-type, scène unique, piloté par le texte.data-viz-reel→ modèlenyt-graph, scène de corps avec variables numériques déclarées.programmatic-short→ modèleplay-mode, accroche/corps/appel à l'action, toute la copie client déclarée comme variables.
- Déclarer les variables. Tout élément du brief qui pourrait changer à chaque rendu (titre, corps, chiffres KPI, CTA, date) va dans
variablesavec un type, un libellé et une valeur par défaut explicites. La copie codée en dur est interdite lorsqu'une variable fonctionnerait. - Construire la spécification de composition dans la forme attendue par
hyperframes:{ composition_id, aspect, duration_seconds, scenes, design_tokens, variables, assets, output_dir }. Calculercomposition_idà partir de<piece-id>(sûr pour les slugs). - Construire les arguments de rendu dans la forme attendue par
hyperframes-cli:{ project_path, mode: "render", render_opts: { fps, quality, format, variables, strict: true, strict_variables: true, output } }. Choisirquality: "high"pour les pièces promues,"draft"pour la révision de première passe. - Estimation des coûts. Rendu local — estimer à partir de
duration_seconds × workers × $0.00(zéro frais directs ; rapporter le temps mural en minutes souslatency_estimate_minà la place). - Journaliser la résolution dans
data/video-usage.jsonlavec{ ts, provider: "hyperframes", piece_id, task_kind, composition_id, dry_run }. - Si
dry_run, retourner sans appelerhyperframes-cli. Sinon, invoquerhyperframes(pour créer le projet) puishyperframes-cli(modelint→inspect→render) dans l'ordre.
Sorties
provider_used:"hyperframes".composition_spec: objet. L'entrée passée à la compétencehyperframes.render_args: objet. L'entrée passée à la compétencehyperframes-cli(moderender).expected_artifact: chaîne. Le chemin du MP4 qui existera après lerender.latency_estimate_min: nombre. Estimation du temps mural pour le rendu.cost_estimate_usd: 0 (rendu local ; uniquement des dépenses d'exploitation).
Exemples
Exemple 1 : reel KPI hebdomadaire (programmatic-short)
Entrée : { brief: { headline: "Semana 21 em números", aspect: "9:16", duration_seconds: 12 }, task_kind: "programmatic-short", client_slug: "saas-consultoria-imagem", piece_path: ".specs/pieces/2026-05-22-kpi.md" }
Sortie : spécification de composition avec composition_id: "kpi-weekly-2026-05-22", trois scènes (accroche/corps/appel à l'action), variables numériques (leads, delta_pct) ; arguments de rendu avec --strict --strict-variables --quality high --variables '{"leads":42,"delta_pct":12}'.
Exemple 2 : carte de citation animée (motion-typography)
Entrée : { brief: { headline: "Coloque a sua marca onde os olhos já estão.", aspect: "1:1", duration_seconds: 6 }, task_kind: "motion-typography", client_slug: "saas-consultoria-imagem" }
Sortie : spécification de composition avec une scène unique de type cinétique, entrée de texte masquée, jetons de design extraits du design.md du client actif ; arguments de rendu ciblant outputs/saas-consultoria-imagem/<date>/<piece-id>/final.mp4.
Exemple 3 : surcharge de fournisseur
Entrée : une pièce avec provider_override.video: hyperframes dont le task_kind n'est pas dans la matrice.
Sortie : toujours routée ici, par défaut task_kind à programmatic-short, journaliser le repli.
Règles non négociables
- Ne jamais inventer de jetons de design. Refuser de continuer si
design.mdest manquant. - Toujours déclarer la copie par pièce comme une
variable, même lorsqu'elle semble statique — la composition doit pouvoir être rendue à nouveau sans modifications de code. - Toujours passer
--strict-variablesdans les arguments de rendu. Une faute de frappe dans un identifiant de variable est un échec définitif. - Ne jamais appeler
hyperframes-clidirectement en contournant la séquencelint → inspect → render.
Modes de défaillance
task_kindinconnu : utiliser par défautprogrammatic-short, journaliser un avertissement et continuer.design.mdmanquant : s'arrêter. Ne pas choisir une palette ; demander à l'opérateur d'ajouter le fichier.- Le brief contient une réclamation interdite par la marque (selon
compliance-<client actif>) : bloquer avant la création ; la conformité s'exécute en amont du rendu. - CLI HyperFrames non installée : afficher la commande d'installation (
npm i -g hyperframesounpx hyperframes@latest) et s'arrêter.
Compétences associées
hyperframes: règles de création de composition (utilisées par cette compétence).hyperframes-cli: exécution de lint/inspect/render (utilisées par cette compétence).video-prompt-builder: répartiteur qui sélectionne cette compétence.qa-tech-specs: s'exécute contre le MP4 final.compliance-<client actif>/compliance-generic: s'exécute contre les variables résolues et l'artefact rendu.llm-router: non utilisé directement ici, mais peut sélectionner le LLM qui rédige le titre/le corps avant que cette compétence n'assemble la spécification de composition.