Storyboard Architect
Vous transformez un brief créatif en un storyboard déterministe. La sortie est un ensemble de fichiers qu'un monteur, une agence ou un développeur peut exploiter sans poser de questions.
Ce n'est pas un exercice d'écriture créative. La sortie est un cahier des charges.
Quand l'utiliser
Déclenchez cette compétence lorsque l'utilisateur :
- Demande un storyboard ou une liste de plans pour une vidéo (« storyboard d'un explainer de 30 secondes pour... », « liste de plans pour une pub TikTok sur... »)
- Demande à planifier des plans, décomposer des séquences ou rédiger une liste de plans
- Fournit un script, un brief ou un document de concept en attendant une sortie structurée de pré-production
- Mentionne un framework de rythme par son nom (Hero Trilogy, Pain-Proof-Promise, etc.)
- Fait référence à un fichier de charte graphique ou pack existant
Si l'utilisateur ne veut que des prompts pour un générateur d'images (sans structure narrative), utilisez directement visual-prompt-forge.
Ce que vous produisez
Pour chaque exécution de storyboard, créez cet ensemble exact de fichiers dans le répertoire de sortie de travail :
output/
├── run.json # Identité de l'exécution + chaque entrée figée par empreinte de contenu
├── storyboard.md # Lisible, structuré par plan
├── shots.json # Lisible par machine, schéma dans templates/shots.schema.json
├── text-overlays.json # Texte à l'écran + minutage
└── brand-lock.snapshot.md # Copie figée de la charte utilisée (piste d'audit)
run.json est ce qui rend le reste de l'arborescence vérifiable plus tard. Un nom de fichier ne dit rien sur les octets qu'il contient, donc l'instantané à côté d'un ensemble d'images n'est pas une preuve qu'il s'agit de l'instantané à partir duquel elles ont été construites. Les empreintes dans run.json sont cette preuve. Écrivez-le une fois, en dernière étape, après que les quatre autres fichiers sont finalisés. Tout dans run.json sauf rounds est écrit une fois et jamais modifié. rounds est en ajout seul : visual-prompt-forge ajoute une entrée par tour de prompt et ne modifie jamais une entrée antérieure.
Si l'utilisateur demande des prompts d'images ou un aperçu HTML, déléguez à visual-prompt-forge ou storyboard-html-preview ; ces compétences consomment shots.json directement. N'essayez pas de faire leur travail ici.
Où se trouvent les outils et packs
Après ./install.sh, les validateurs et aides sont dans ~/.claude/shotkit-tools/ et les packs de marque sont dans ~/.claude/shotkit-brand-packs/. Une installation --project place les deux sous ./.claude/ à la place. Depuis un clone du dépôt, ils sont dans tools/ et brand-packs/. Les commandes ci-dessous donnent d'abord le chemin installé puis le chemin clone. Ils ne nécessitent aucune configuration : sk exécute chaque outil et fournit les deux packages Python qu'utilisent les validateurs.
Entrées
Vous avez besoin de ces éléments. Si l'un manque, demandez avant de rédiger.
| Entrée | Obligatoire ? | Valeur par défaut si absente |
|---|---|---|
| Brief (problème, audience, objectif) | Oui | Demander |
| Durée totale | Oui | Demander |
| Format d'image | Oui | Demander (16:9, 9:16, 1:1) |
| Framework de rythme | Non | Suggérer en fonction du brief |
| Chemin du fichier de charte | Non | Utiliser ~/.claude/shotkit-brand-packs/_starter.md (clone : brand-packs/_starter.md) et signaler l'absence |
| Style de voix off (VO présente, écran seul, sous-titres) | Non | Demander si peu clair |
| Générateur(s) cible(s) pour les prompts aval | Non | Noter comme « à spécifier » |
Résultats d'audit, brand/audit-findings.json de whystrohm-audit | Non | Sauter l'étape 1b |
Budget de lecture
Ce fichier contient ce dont une exécution normale a besoin : les champs, les vocabulaires et les formes de fichiers. Ne lisez pas les références, les modèles et les exemples à l'avance. Cela coûte des minutes à l'utilisateur avant que le premier fichier ne soit écrit.
- Toujours lire : la charte.
- Lire lorsque la décision l'exige :
references/beat-frameworks.mdpour un framework que vous ne maîtrisez pas,references/timing-rules.mdlorsque le brief et la durée ne concordent pas,references/on-screen-text.mdlorsque vous n'êtes pas sûr qu'un texte doive être à l'écran. - Lire lorsque le validateur le dit : les schémas dans
templates/. Ses messages nomment le champ et la règle, donc corrigez d'abord à partir du message. - Lire en dernier, si jamais : les exemples.
Workflow
Suivez cette séquence. Ne sautez pas d'étapes même si le brief semble simple.
Étape 1. Lire la charte
Si un chemin de fichier de charte est fourni, lisez-le en premier. Extrayez :
- Palette (hex)
- Typographie
- Descripteurs d'ambiance
- Liste « Jamais » (ce que cette marque ne fera jamais visuellement)
- Langage de mouvement
- Ton de la voix
- Préférences de format d'image
Si aucune charte n'est fournie, copiez ~/.claude/shotkit-brand-packs/_starter.md (depuis un clone, brand-packs/_starter.md) dans la sortie sous brand-lock.snapshot.md. Le starter est une charte neutre et remplie, donc l'instantané réussit sa vérification et les superpositions ont de vraies couleurs à utiliser. Définissez brand_lock_configured: false dans run.json, et dites à l'utilisateur que l'exécution a utilisé la charte de démarrage et comment la remplacer : demandez une charte depuis leur site, ou remplissez _template.md.
Ne prenez pas d'instantané de _template.md. Il est vide intentionnellement, et une palette vide échoue à la vérification de l'instantané. N'inventez pas non plus de palette pour une vraie entreprise : une charte inventée ressemble à une décision que l'entreprise n'a pas prise.
Étape 1b. Lire les résultats d'audit, s'il y en a
Si l'utilisateur pointe vers brand/audit-findings.json, ou s'il se trouve dans le dossier brand/ du projet et que le brief concerne la même entreprise, lisez-le. Son format est contracts/audit-findings.v1.schema.json dans ce dépôt. Vérifiez que contract est audit-findings et version est "1" avant de l'utiliser.
- Le premier des
top_gapsest un candidat pour la séquence problème ou monde : le problème auquel le film répond. rewrite.afterest un candidat pour une ligne de superposition. Utilisez-le uniquement tel qu'écrit. Un espace réservé entre crochets signifie que la preuve manque, donc omettez cette ligne plutôt que de la remplir.- Nommez le fichier et son
audited_atdans la section Brief destoryboard.md.
Le brief décide toujours. Les résultats informent les séquences ; ils ne remplacent jamais ce que l'utilisateur a demandé.
Étape 2. Choisir le framework de rythme
Lisez references/beat-frameworks.md. Choisissez celui qui correspond au brief. Cas courants :
- Pain-reframe-promise → contenu de conversion
- Hero Trilogy → films de présentation de produit
- Founder Explainer → contenu de marque personnelle
- Content Spiral → typographie cinétique / articles d'opinion
Si aucun ne correspond parfaitement, construisez une structure de rythme personnalisée mais documentez pourquoi dans la section de justification de storyboard.md.
Étape 3. Définir le minutage
Lisez references/timing-rules.md pour les calculs. Cadence par défaut :
- Accroche : 0–2 secondes
- Problème/mise en place : 2–4 secondes (pour 15s), 2–6 secondes (pour 30s) ou 2–10 secondes (pour 60s)
- Preuve/reformulation : tiers central
- Promesse/appel à l'action : 3–4 secondes finales (pour 15s), 4–6 secondes (pour 30s), 6–10 secondes (pour 60s)
Ne luttez pas contre le framework. Si le brief et la durée ne concordent pas, signalez le désaccord avant de rédiger.
Étape 4. Rédiger la liste de plans
Lisez references/shot-grammar.md pour le vocabulaire contrôlé. Les noms de champs ci-dessous sont les noms de champs du schéma. templates/shots.schema.json définit additionalProperties: false, donc un quasi-match comme environment au lieu de environment_ref est un échec de validation, pas un synonyme.
id, séquentiel, avec zéro non significatif (shot_01,shot_02...)beat, la séquence que ce plan sertstart/end, horodatages en secondes, décimal autorisé.enddoit être aprèsstartframing, ECU / CU / MCU / MS / MLS / WS / EWSangle, eye-level / high / low / overhead / dutchmotion, static / push / pull / pan-left / pan-right / tilt-up / tilt-down / handheld / orbit / whip / rack. Les onze sont légaux ; l'énumération du schéma fait autorité etreferences/shot-grammar.mdexplique quand chacun est utiledepth_of_field, optionnel, shallow / deep / racksubject, ce qui est dans le cadre, structuréenvironment_ref, référence au langage du verrouillage de série, par défautseries_lock.environmentlighting_ref, référence au langage du verrouillage de série, par défautseries_lock.lightingon_screen_text, null, un identifiant de superposition de texte, OU un tableau d'identifiants lorsqu'un plan porte plus d'une superpositionvo, ligne de voix off, ou nullrationale, une phrase expliquant pourquoi ce plan à ce moment
Note sur rack : comme valeur de motion, cela signifie que le point de vue est le mouvement du plan ; comme valeur de depth_of_field, cela signifie que la mise au point change en cours de plan. Même mot, deux champs, deux significations.
Étape 5. Séparer le calque de texte
Chaque élément de texte à l'écran devient une entrée dans text-overlays.json. N'intégrez jamais le texte dans la description visuelle. Chaque superposition a :
id,text_01,text_02...shot_id, le plan sur lequel cette superposition apparaîtcontent, le texte réelfont, référence à la typographie de la charteposition,center,lower-third,upper-third,left-third,right-third, ou{x, y}en pourcentagessize,display,headline,body,captionweight,regular(400),medium(500),semibold(600),bold(700),black(900)color, hex (doit provenir de la palette de la charte)enter,{ at: secondes, animation: fade-in | slide-up | slide-down | type-on | hard-cut }exit,{ at: secondes, animation: fade-out | slide-up | slide-down | hard-cut }
Ensuite, définissez le traitement typographique et vérifiez les mots :
- Traitement typographique. Marquez les deux ou trois mots qui portent chaque titre avec
emphasis, nommez la marque une fois avec unkickerou unlockup, et utilisez unplatelorsque le cadre est chargé. Les champs et quand les utiliser sont dansreferences/on-screen-text.md, sous « Traitement typographique ». - Le contrôle linguistique. Avant d'écrire le fichier, passez chaque ligne dans
references/hooks-and-language.md: une première ligne qui est une accroche et non un slogan, des mots spécifiques, une idée par ligne, rien que le brief n'ait pas donné. - Une marque sans police. Choisissez un appariement dans
type-pairings.mddu dossier des packs de marque et écrivez-le dans la charte. Ne prenez pas Inter par défaut.
Enter et exit ont des vocabulaires d'animation différents, et templates/text-overlays.schema.json fait autorité pour les deux. Un plan peut porter plus d'une superposition ; listez chaque identifiant dans le tableau on_screen_text de ce plan, sinon les superpositions supplémentaires ne s'affichent nulle part.
Étape 6. Verrouiller la série
Définissez les ancrages d'environnement, d'éclairage et de personnage qui s'appliquent à tous les plans. Ceux-ci vont en haut de shots.json sous series_lock. Sans cela, la génération d'images produira des plans incohérents.
Étape 7. Écrire la justification
Chaque plan a une justification d'une phrase. Pourquoi cette séquence. Pourquoi ce cadrage. Pourquoi ce texte à l'écran. C'est la piste d'audit. Ne la sautez pas.
Étape 8. Prendre un instantané de la charte
Copiez le fichier de charte (ou modèle) dans la sortie sous brand-lock.snapshot.md. Ajoutez ces deux commentaires tout en haut, dans cet ordre :
<!-- snapshot taken: 2026-05-07T14:23:00Z -->
<!-- source: brand-packs/whystrohm.md -->
L'horodatage est un instant UTC complet, YYYY-MM-DDThh:mm:ssZ. Une date nue ne peut pas distinguer deux exécutions faites le même jour, ce qui est le cas important. La source est le chemin depuis lequel il a été copié, ou la chaîne littérale template default pour une exécution non configurée. Après une installation, un chemin de pack est ~/.claude/shotkit-brand-packs/whystrohm.md ; depuis un clone du dépôt, c'est brand-packs/whystrohm.md. Les deux passent le validateur. Des commentaires supplémentaires après ces deux sont acceptables.
validate_brand_lock.py --snapshot <path> vérifie les deux lignes. Exécutez-le :
~/.claude/shotkit-tools/sk validate_brand_lock.py --snapshot output/brand-lock.snapshot.md
# depuis un clone du dépôt :
# tools/sk validate_brand_lock.py --snapshot output/brand-lock.snapshot.md
Étape 9. Écrire run.json
Dernière étape, après que les quatre autres fichiers sont finalisés. Remplissez templates/run.schema.json. Ces champs sont obligatoires :
| Champ | Valeur |
|---|---|
version | "1.0", le format run.json |
run_id | horodatage UTC compact, un tiret, 8 caractères hexadécimaux (ci-dessous) |
created_at | le même instant que YYYY-MM-DDThh:mm:ssZ |
shotkit_version | ligne 1 de ~/.claude/shotkit-tools/VERSION ; dans un clone du dépôt, VERSION à la racine |
project | title, duration_s et aspect de shots.json, plus framework et seed si défini |
inputs.shots_ref, inputs.shots_sha256 | shots.json et son SHA-256 |
inputs.text_overlays_ref, inputs.text_overlays_sha256 | text-overlays.json et son SHA-256, ou les deux null sans texte à l'écran |
inputs.brand_lock_ref, inputs.brand_lock_sha256 | brand-lock.snapshot.md et son SHA-256 |
inputs.brand_lock_source | le pack depuis lequel il a été copié, ou template default |
Optionnel : operator, inputs.brand_lock_configured, generators, rounds, meta.
head -n 1 ~/.claude/shotkit-tools/VERSION # depuis un clone du dépôt : head -n 1 VERSION
shasum -a 256 output/shots.json output/text-overlays.json output/brand-lock.snapshot.md
run_id est l'horodatage UTC compact, un tiret, puis 8 caractères hexadécimaux, par exemple 20260730T142300Z-9f2c1ab4. Le suffixe hexadécimal empêche deux opérateurs débutant une exécution dans la même seconde d'entrer en collision. Définissez brand_lock_configured: false lorsque l'instantané est un modèle non rempli.
Laissez rounds vide. Tout dans run.json sauf rounds est écrit une fois et jamais modifié. rounds est en ajout seul : visual-prompt-forge ajoute une entrée par tour de prompt et ne modifie jamais une entrée antérieure.
Formats de sortie
storyboard.md
Un titre par section, dans cet ordre : le brief tel que donné, les hypothèses que vous avez faites, le framework et pourquoi, le verrouillage de série, puis un bloc par plan (id, séquence, temps, caméra, sujet, texte à l'écran, VO, justification), puis le script VO complet s'il y en a un. templates/storyboard.md.tpl a la mise en page exacte si vous le souhaitez.
shots.json
Doit être validé contre templates/shots.schema.json. La structure est :
{
"version": "1.2",
"project": { "title": "...", "duration_s": 30, "aspect": "9:16", "framework": "..." },
"brand_lock_ref": "brand-lock.snapshot.md",
"series_lock": {
"character": "...",
"environment": "...",
"lighting": "...",
"color_grade": "..."
},
"shots": [
{
"id": "shot_01",
"beat": "hook",
"start": 0.0,
"end": 2.0,
"framing": "MCU",
"angle": "eye-level",
"motion": "static",
"depth_of_field": "shallow",
"subject": { ... },
"environment_ref": "series_lock.environment",
"lighting_ref": "series_lock.lighting",
"on_screen_text": ["text_01"],
"vo": "Ce produit résout un problème que vous connaissez.",
"rationale": "Accroche visuelle directe pour capter l'attention."
}
]
}
text-overlays.json
{
"version": "1.0",
"overlays": [
{
"id": "text_01",
"shot_id": "shot_01",
"content": "Le problème que vous connaissez",
"font": "Brand Sans",
"position": "lower-third",
"size": "headline",
"weight": "bold",
"color": "#1A1A2E",
"enter": { "at": 0.5, "animation": "fade-in" },
"exit": { "at": 1.8, "animation": "fade-out" }
}
]
}
run.json
{
"version": "1.0",
"run_id": "20260730T142300Z-9f2c1ab4",
"created_at": "2026-07-30T14:23:00Z",
"shotkit_version": "1.0.0",
"project": {
"title": "Vidéo promotionnelle Produit X",
"duration_s": 30,
"aspect": "9:16",
"framework": "pain-reframe-promise"
},
"inputs": {
"shots_ref": "output/shots.json",
"shots_sha256": "abc123...",
"text_overlays_ref": "output/text-overlays.json",
"text_overlays_sha256": "def456...",
"brand_lock_ref": "output/brand-lock.snapshot.md",
"brand_lock_sha256": "ghi789...",
"brand_lock_source": "brand-packs/whystrohm.md",
"brand_lock_configured": true
},
"rounds": []
}