research-new-brand

name

research-new-brand

description

kickoff prep for a new brand — web research, existing-ad analysis, sourced + AI-generated brand assets, and an ad concept brief. use when starting work on a brand the repo hasn't touched before (e.g. `amex`, `klarify`, `ramp`). Emits the control-plane orchestrator's brand-context contract directly — `brand-research/{brand-summary,visual-identity,competitors,audience}.md` + `brand-assets/manifest.json` — so `video-orchestrator-with-control-plane` State 0.1 reads it with no re-fill, plus a `concept-brief.md` and a populated `brand-assets/` folder, in one pass.

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 → .

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.