research-new-brand

research-new-brand

Purpose

Bootstrap the full creative-prep package for a new brand: research the product, analyze any existing ads, source logos and reference photos, generate brand-anchored product + lifestyle imagery, and write the brand-context docs the pipeline consumes.

This molecule emits the exact brand-context contract that video-orchestrator-with-control-plane reads at State 0.1 — the four brand-research/*.md files and brand-assets/manifest.json at the brand root. Filling these is the whole point: a brand researched by this skill needs no manual fill in the desktop Brand view, and the orchestrator's State 0.1 finds populated context and advances instead of gating. It also writes a supplementary concept-brief.md (brand-level concept seeds) and the populated brand-assets/ folders.

Layout note: write everything under the brand root — the directory that holds ad-runs/, brand-research/, and brand-assets/ (by convention <your-project>/<brand>/, but never hardcode that; use the brand_dir input or the path the caller is in). The orchestrator locates this root by walking up from a run folder until it finds brand-assets/manifest.json or brand-research/, so the only requirement is that these three siblings live together.

Inputs

• brand (required) — short slug used as the brand folder name, e.g. amex, liquid-death.
• brand_dir (optional) — absolute path to the brand root to write into. Defaults to the conventional <your-project>/<brand>/ under the workspace root, or the caller's cwd if it's already a brand root. Never hardcode the location — resolve it from this input.
• product (required) — specific product/SKU/offer to research, e.g. "Platinum Card", "Sparkling Water". Disambiguates brands with many SKUs.
• brand_url (optional) — canonical homepage. Strongly recommended to avoid wrong-entity confusion (e.g. Apple band vs. Apple Inc.).
• existing_ads_dir (optional) — path to a folder of .mp4 ads. If present, each is analyzed via watch:watch. If absent, ad-analysis is skipped and voice/tone is inferred from web research only.
• brand_video_urls (optional) — list of the brand's own video URLs (launch films, product demos, explainers). If provided, run the sibling molecule build-brand-clip-library after this skill to cut them into an indexed, reusable clip library under brand-assets/clips/.
• concept_count (optional, default 6–10) — number of social-ad concepts to draft.
• skip_generation (optional, default false) — skip Higgsfield image generation and ship research + brief only.

Composed Atoms

• source-brand-assets — scrape logos + reference hero photos into brand-assets/
• understand-brand-assets — distill web research + reference photos into the visual-identity.md content (colors, typography, photography style)
• analyze-ad-hooks — extract recurring hooks/motifs from existing ads (when provided)
• generate-ad-concepts — produce the concept list for concept-brief.md
• create-product-images-higgsfield-product-photoshoot — 4–6 hero/end-card product stills
• create-product-images-nanobanana — 8–12 vertical 9:16 lifestyle stills
• External skills: watch:watch (ad analysis), WebSearch / WebFetch (research)

Workflow

1. Disambiguate. Confirm brand + product resolves to one entity. If brand_url is missing and the name is ambiguous, stop and ask.
2. Scaffold the brand root in the orchestrator-native layout (at <brand_dir>):

   <brand_dir>/
     brand-research/                   # ← orchestrator State 0.1 reads *.md here
       brand-summary.md                # written in step 7
       visual-identity.md              # written in step 7
       competitors.md                  # written in step 7
       audience.md                     # written in step 7
       asset-urls.md                   # written in step 7 (sourced URLs + access dates)
       ui-references.md                # written in step 7 ONLY if the product has notable UI
     brand-assets/                     # ← orchestrator reads manifest.json here
       manifest.json                   # written in step 6 (File 0 contract)
       logos/
       reference-photos/
       generated-product-shots/
       generated-lifestyle/
       songs/
     concept-brief.md                  # supplementary brand-level concept seeds (step 8)
     ad-runs/                          # empty; runs created later by the app / orchestrator
     existing-ads/                     # left as-is if the user populated it
   

   Only create asset subfolders that will be populated. Do NOT create background_research.md — its content now lives split across the four brand-research/*.md files. If a brand already has a legacy flat background_research.md, fold it into the four files and delete it.
3. Web research via WebSearch + WebFetch. Priority order: brand site → trade press (Adweek/AdAge/Campaign) → reputable category reviewers. Capture: product overview, mechanics/pricing, benefits, target audience, current named campaigns with dates, core positioning, voice/tone. Record every URL with access date.
4. Existing-ads analysis (conditional). If existing_ads_dir provided, run watch:watch on each video. Capture VO transcript, visual style, recurring motifs, implicit promise. Skip cleanly if absent.
5. Source brand assets via source-brand-assets:
   • Logos: brand press kit or Wikipedia SVG → brand-assets/logos/.
   • Reference photos: 2–4 high-quality third-party shots of the product/hero → brand-assets/reference-photos/. Mark "not licensed for redistribution" in each manifest entry's description.
   • Songs: if existing ads exist, extract the audio bed of one ad as tone reference → brand-assets/songs/.
6. Generate brand-anchored imagery (skip entirely if skip_generation=true):
   • 4–6 product-photoshoot stills via create-product-images-higgsfield-product-photoshoot, grounded on the strongest reference photo so the SKU stays consistent → brand-assets/generated-product-shots/.
   • 8–12 lifestyle stills via create-product-images-nanobanana (Nano Banana Pro), 2k vertical 9:16, same reference grounding → brand-assets/generated-lifestyle/.
   • Write brand-assets/manifest.json — the File 0 contract the orchestrator reads. One entry per binary asset (every logo, reference photo, generated still, song). Schema (exact):

     {
       "schemaVersion": "1.0.0",
       "updatedAt": "<iso-8601>",
       "projectId": "<Brand>",
       "assets": [
         {
           "id": "brand-asset-<uuid>",
           "path": "brand-assets/logos/wordmark-black.svg",
           "kind": "wordmark",
           "name": "Wordmark (black on transparent)",
           "description": "Composite in end cards via PIL/ffmpeg, never AI-render. Min height 36px.",
           "addedAt": "<iso-8601>"
         }
       ]
     }
     

     • kind ∈ logo | wordmark | product_photo | lifestyle | video_ref | style_ref | ui_ref | asset.
     • path is relative to the brand root (e.g. brand-assets/...), never absolute.
     • name is the short label Claude searches by; description is how/when to use it + any usage constraint (incl. "not licensed for redistribution" on scraped photos). A vague description defeats the file's purpose.
     • Use a fresh UUID per id. Do NOT also write a README.md — manifest.json is the contract; the README was the old lossy format.
7. Write the four brand-research/*.md files — the brand-context contract State 0.1 reads. Use these exact section headers (they match the desktop app's create_project scaffold, so a researched file is a drop-in replacement for the empty stub), filled from research — never leave a placeholder marker behind:
   • brand-research/brand-summary.md — headers: What the company sells, Who they sell to, Why people buy (jobs-to-be-done), Brand voice in three words, What to never say.
   • brand-research/visual-identity.md — headers: Primary colors (hex), Typography, Logo usage rules, Photography style, Off-limits styles.
   • brand-research/competitors.md — ## Direct (each competitor: one-line positioning, pricing tier, and how <brand> wins / loses vs them) and ## Reference creative (links / vibes to emulate or avoid).
   • brand-research/audience.md — headers: Primary persona, Where they spend time online, Objections they raise, Proof points that land. Include 3–4 distinct ICP segments and verbatim audience phrasing (Reddit/forums) — these become VO seeds downstream.
   • brand-research/asset-urls.md — every sourced URL with its access date (the provenance trail for manifest.json + research claims).
   • brand-research/ui-references.md — ONLY if the product has notable in-app/product UI worth recreating; catalog the key screens. Omit the file entirely otherwise.
8. Write <brand_dir>/concept-brief.md with sections: Observed patterns from existing ads (only if step 4 ran), Strategic foundation, Concept ideas (concept_count, each with hook + format + 15s/30s beat-by-beat + why-it-works + KPI it serves), Production notes, Open questions. This is supplementary brand-level seeding — the orchestrator still runs its own per-run brainstorm; do not write production/concepts.json here.

Decision Rules

• Refuse to proceed without a disambiguated brand+product. Don't guess between two entities sharing a name.
• If a generated product image trips a provider safety flag, fall back to the alternate model (gpt_image_2 → nano_banana_2). This mirrors the Amex confetti-hero workaround.
• All generated imagery must use the same reference photo so the SKU is consistent across the asset library.
• Never claim licensed rights to scraped reference photos. Always note "not licensed for redistribution" in that asset's description in brand-assets/manifest.json.
• If Higgsfield credit balance is too low, emit a warning, skip generation, and still ship the research doc + concept brief.
• If existing_ads_dir is absent, the concept brief must not fabricate "Observed patterns" — omit the section.
• This skill produces research, sourced assets, generated imagery, and a concept brief. It does NOT clip the brand's own videos. When the brand has its own footage worth reusing (or brand_video_urls is provided), run the sibling molecule build-brand-clip-library to download those videos and cut them into an indexed clip library — the footage counterpart to this skill's generated assets.

Output

Brand-context contract (read by video-orchestrator-with-control-plane State 0.1):

• <brand_dir>/brand-research/brand-summary.md
• <brand_dir>/brand-research/visual-identity.md
• <brand_dir>/brand-research/competitors.md
• <brand_dir>/brand-research/audience.md
• <brand_dir>/brand-research/asset-urls.md
• <brand_dir>/brand-research/ui-references.md (only when the product has notable UI)
• <brand_dir>/brand-assets/manifest.json (File 0 contract) + populated logos/, reference-photos/, and (unless skipped) generated-product-shots/, generated-lifestyle/, songs/

Supplementary:

• <brand_dir>/concept-brief.md
• <brand_dir>/ad-runs/ (empty, for the app/orchestrator to fill)

Not written (deprecated): background_research.md, brand-assets/README.md, a top-level manifest.json. Their content now lives in the four brand-research/*.md files and brand-assets/manifest.json.

Quality Checks

• All four brand-research/*.md files exist with no remaining placeholder markers and use the exact section headers above (drop-in for the app scaffold).
• brand-research/asset-urls.md cites real, dated sources for every research claim and sourced asset.
• brand-assets/manifest.json parses, follows the File 0 schema, and has one entry per binary asset on disk — every path is relative to the brand root and resolves to a real file; every kind is in the allowed enum; no entry is missing name/description.
• Concept brief references specific moments from each analyzed existing ad (when step 4 ran).
• Generated imagery is visibly the same SKU end-to-end (same colorway, finish, branding).
• Folder shape is the orchestrator-native brand root: brand-research/ + brand-assets/ + ad-runs/ as siblings. No background_research.md or brand-assets/README.md left behind.
• Sanity-check against the orchestrator: from a (hypothetical) ad-runs/run-01/ folder, walking up reaches this brand root via brand-assets/manifest.json — i.e. State 0.1 would see populated context and skip its gate.

Failure Modes

• Brand name collides with another entity and brand_url was not provided.
• Brand press kit is unavailable and no acceptable third-party reference photos exist — flag and stop before image generation.
• Higgsfield credit balance too low — warn, skip step 6 cleanly, still ship steps 7–9.
• existing_ads_dir provided but contains unreadable files — log each failure, skip that file, continue.