How we ship a graded batch of ads.

1. Onboard a new client SETUP_NEW_CLIENT.md

What it does

Walks through 12 numbered steps to onboard a new client from cold:

1. Step 0: Ask for client name, shortcode (3-letter code), website URL, category, vertical, any uploaded materials. Don't guess these.
2. Step 1: Scan Clients/{Brand}/ for existing assets — brand guidelines, transcripts, style guides, performance data. These are gold and override anything from a website scrape.
3. Step 2: Read the system files (the agent rubrics, asset-type templates, prompt-assembly rules) so the rest of the steps reference them correctly.
4. Step 3: Create the client folder structure.
5. Step 4: Scrape the website and build the brand bible at Clients/{Brand}/{SHORTCODE}-brand-bible.md — 10 sections covering company, product, customer, positioning, voice/tone, compliance, visual direction, personas/angles, paid social process, emotional architecture.
6. Step 5: Distill the brand bible into a creative onboarding doc at {SHORTCODE}-creative-onboarding.md — the "read this before writing a single line of copy" cheat sheet.
7. Step 6: Scrape the product catalog → {SHORTCODE}-product-catalog.md.
8. Step 7: Create the brand voice agent at {SHORTCODE}-brand-voice-agent.md — the client-specific override for Agent 06 (Brand Compliance). 5 weighted scoring dimensions, hard violations list, proprietary truths.
9. Step 8: Create the client overview at {SHORTCODE}.md.
10. Step 9: HUMAN TASK — user inspects the brand's website CSS for exact fonts and hex colors. Claude is unreliable at this. Stop and wait for user paste.
11. Step 10: Build the brand spec card + visual style card as HTML, render to PNG. These get uploaded to Fal alongside every prompt.
12. Step 11: Create the Nano Banana base prompt template (legacy; modern flow uses GPT Image 2).
13. Step 12: Verify all files exist. Ask the user "Ready to generate briefs? How many rounds?"

Output (per brand)

Clients/{BRAND}/
  ├ {SHORTCODE}.md                          ← client overview (personas, angles, KPI, team)
  ├ {SHORTCODE}-brand-bible.md              ← 10-section comprehensive brand reference
  ├ {SHORTCODE}-creative-onboarding.md      ← TL;DR brand cheat sheet
  ├ {SHORTCODE}-product-catalog.md          ← every SKU with specs
  ├ {SHORTCODE}-brand-voice-agent.md        ← Agent 06 override (brand-specific)
  ├ {SHORTCODE}-brand-spec-card.png         ← typography + color palette card
  └ {SHORTCODE}-visual-style-card.png       ← photography direction + mood card

Why it matters

Every downstream batch (sales-proposal or existing-client) reads from this folder. Skipping setup or running it half-way is the #1 way to produce off-brand copy — there's nothing for Phase C's Agent 06 to anchor against. Both starter prompts will halt and point here if any prerequisite is missing.

2. Sales proposal end-to-end SALES_PROPOSAL_STARTER_PROMPT.md

What it does

Wraps the Phase A → G pipeline with sales-proposal-specific intake (discovery transcript drives voice DNA) and adds Phase F (build proposal site) + Phase G (compose email). The actual ad-generation phases are the same as the existing-client flow — they share the canonical BATCH_GENERATION_PIPELINE.md playbook.

• Phase A — Brand setup: Create folder. Run Product and Logo Scraper.md against the brand URL. Run Color and Font Scraper.md. Read the discovery call transcript end-to-end and extract voice adjectives, banned words, persona signals, deal economics, specific objections. Build spec cards from scraped tokens + transcript-derived voice. The discovery transcript is the central anchor — without it, voice is guesses.
• Phase B — Concept slate: Build 14-row slate with King's Hawaiian archetype quotas. Run variant selection per slot. Fill in AUDIT.md §1 Visual. STOP for user.
• Phase C — Copy refinement: 9-agent refinement. Brand voice agent (just built in Phase A) acts as Agent 06 override. Fill in AUDIT.md §2 Voice. STOP for user.
• Phase D — Generate via Fal.
• Phase E — Agent 10 grading. Hard gate.
• Phase F — Build the proposal site. Hosted LP at {brand}.selfmade.co. index.html with prospect-specific economics, packaging, kickoff timeline. work.html with the 14 graded ads. Deploy to Vercel.
• Phase G — Email draft at email-draft.md. Short — 3-4 paragraphs max. The proposal page does the heavy lifting; the email is the hook.

What you need before starting

• Brand e-commerce URL
• Discovery call transcript (non-negotiable)
• Prospect contact names
• Target subdomain for the hosted proposal
• Use-case framing (sales-call demo / post-call follow-up / cold)
• Channel scope (default: Meta only)

Slim version

If you only want the 14 ads (no proposal site, no email), run Phases A (steps 1-6), B, C, D, E only. The full prompt has a slim-version block at the bottom of the file with this scope.

3. Existing-client recurring batch EXISTING_CLIENT_STARTER_PROMPT.md

What it does

Differentiated from the sales-proposal flow by Phase A: the data drives the slate. Instead of voice from a discovery transcript, the iteration tracker provides a spend-weighted action plan that allocates EXTEND / RETIRE / FILL slots automatically.

• Phase A — Performance read. Single script call to pull-insights.mjs against the iteration tracker. Writes insights-export.json + an auto-formatted DATA_BRIEF.md with three buckets:
  • EXTEND — replicate/extend action-plan recs, sorted by priority. The proven winners.
  • RETIRE — pause/avoid recs (dead/fatigued dimensions with material spend). Per-ad bottomByRoas losers.
  • FILL — top Adlib gap-analysis opportunities (missing/underused types) by priority score.
  Also enumerates the brand's central asset folder (In-House Clients/Brands/{Brand} ({CODE})/Assets/) so SKU selection is data-grounded.
• Phase B — Slate with allocation 5–7 EXTEND / 4–6 FILL / remainder open + the King's Hawaiian archetype quotas. Variant selection. CTA + Logo flags per slot (the truth table is in this doc — different per format archetype). Fill in AUDIT.md §1. STOP for user.
• Phase C — 9-agent refinement (brand voice agent loads as Agent 06 override). Less-copy default per Easy Man learnings: HEADLINE + SUBHEAD max unless the format archetype literally requires body. Fill in AUDIT.md §2. STOP.
• Phase D — Generate. Per-ad references include the specific product photo from the brand's central assets folder, NOT the briefing folder.
• Phase E — Agent 10 grading. Pass insights-export.json + DATA_BRIEF.md to the grader — these power Gate 10 (Brand Performance Resonance), which scores each ad's format × persona × angle × emotion against the action plan. Without these, Gate 10 is N/A and gates 0–9 redistribute pro rata.
• Phase F — Deliver 9:16 source-of-truth. Save the locked script + Agent 10 report alongside.
• Phase G — Resize to 1:1 + re-grade.

What you need before starting

• The brand folder must already have brand bible / voice agent / spec cards / product catalog (from SETUP_NEW_CLIENT.md). Otherwise STOP and run setup first.
• Meta data ingesting cleanly into the iteration tracker (https://insights.selfmade.co/client/{CODE} shows non-zero ads).
• Adlib mapping configured (else FILL bucket is empty; pipeline still works).
• INSIGHTS_AUTH_PASS exported in the shell.
• Default batch size: 14. Default optimize-for: ROAS.

Encoded production lessons

This file has accumulated several universal patterns the user codifies after each batch — currently includes:

• King's Hawaiian archetype quotas (≥2 platform-UGC, ≥1 macro, ≥1 outdoor, ≥1 type-only, ≥1 chaotic)
• Easy Man less-copy default — every slot is HEADLINE + SUBHEAD MAX unless body is format-mandatory
• Easy Man composition cleanliness — headline + subhead = one tight typographic unit; product/scene below as a separate beat
• Easy Man founder-quote attribution rule — wrap founder first-person in quotes + add a separate — Name, role. attribution line
• Easy Man brand-name pun caps rule — match the brand wordmark's casing for pun-payoff lines, not the voice agent's "sentence case throughout"
• Easy Man logo-default-OFF rule — drop the standalone logo when the can wordmark is in frame and legible at thumbnail
• Comparison-fulcrum-word rendering rule — "Vs." goes on its own line between A and B, smaller and italic, not as a side label

4. The canonical playbook BATCH_GENERATION_PIPELINE.md

What it does

Defines Phase 0 → Phase 8 as the universal sequence, independent of which starter prompt invokes it. Each phase has a documented failure mode the phase exists to prevent (most pulled from the BlackMask 2026-04-29 batch and subsequent learnings).

• Phase 0 — Brand setup. Files the client folder needs (spec cards, product photos, brand kit, reference materials). Points at SETUP_NEW_CLIENT.md for the one-time setup flow.
• Phase 1 — Concept slate. Build the 14-row table — concept · format file · persona · angle · emotion · awareness · product reference. King's Hawaiian archetype quotas mandatory.
• Phase 2 — Asset Type variant selection. The most-skipped step. Each format file in /Briefing/Asset Types/ has 4–9 styles inside it (Style A, B, C…). Defaulting to Style A in every file produces 14 versions of the same ad. Per-slot variant selection against the brand DNA.
• Phase 3 — Visual diversity audit (mandatory STOP gate). Now formalized as §1 of AUDIT_TEMPLATE.md. 12-bucket coarse surface taxonomy. Cluster cap of 3 slots per bucket. Adjacent-pair check on 4 dimensions. Pinterest grid test.
• Phase 3.5 — Thumbnail one-liners. Folded into the §1 audit table as a required column.
• Phase 4 — Copy refinement through agents 01–09. Two viable patterns: (A) one general-purpose agent loaded with all 9 rubrics (cheap, ~$1-2); (B) per-agent passes (rigorous, ~$5-8). Either way: every ad must clear ≥ 90 on every applicable rubric before Phase 5.
• Phase 4.5 — Voice diversity audit (mandatory STOP gate). §2 of AUDIT_TEMPLATE.md. Voice register tally, source citation per line, repeated-anchor check, brand-swap test.
• Phase 5 — Generate via Fal. Picks the model (GPT Image 2 vs Nano Banana 2 — see GPT_IMAGE_2_PIPELINE.md § 9). Sequential, 4-attempt fetch retry, save on success.
• Phase 6 — Grade with Agent 10. 11-gate rubric. Composite ≥ 90 with no caps triggered = ship.
• Phase 7 — Iterate failures. Copy fix → edit prompt's COPY block. Scene fix → swap variant from Phase 2. Image-level glitch → regenerate same prompt. Loop until all ≥ 90.
• Phase 8 — Ship. Move PNGs to deploy folder. Archive failed/legacy. Save the locked generate-ads-gpt2.mjs as the artifact that documents what shipped.

Why it matters

The starter prompts evolve fast (each batch adds new universal patterns). This file is the durable canonical reference — the failure modes documented here are the seven that have actually shipped at SelfMade and the rules above are the antidote to each. When the starter prompts contradict each other, this is the source of truth.

5. The slate audit AUDIT_TEMPLATE.md

What problem it solves

Per-ad rubrics (Phase 4's 9-agent refinement, Phase 6's Agent 10 grader) score each ad independently. They cannot catch slate-level diversity failures:

• Visual cluster failure — 14 ads on different format files all reading as the same warm-editorial mood at thumbnail (King's Hawaiian 2026-04-29; Go Brewing v4 cream-editorial cluster). The freeform Surface | Lighting | Format archetype matrix used to label these as "different" — but at thumbnail the cluster is obvious.
• Voice register over-indexing — every ad scores ≥ 90 on per-ad rubrics but the slate as a whole skews to one register (Go Brewing v3: 3 founder-podcast slots + 5 award-credibility slots + 0 brand-editorial). The slate ships off-brand even though no individual ad fails.

Both are slate-level failures. This template audits the slate as a whole.

Two sections, two phases

• §1 Visual Diversity Audit — filled at Phase B (after slate built, before copy refinement). Doesn't need copy. Audits the slate's scene language alone:
  • 12-bucket coarse surface taxonomy (A platform-chrome / B flat-color / C cream-paper-editorial / D wood-organic / E macro / F studio-softbox / G cinema-matte-black / H outdoor / I kitchen / J bar-taproom / K phone-mockup / L chaotic-tablescape)
  • Plus parallel taxonomies for lighting (8 buckets), primary subject (5 buckets), color cast (8 buckets)
  • Hard caps: max 3 per surface bucket / max 4 per lighting / max 5 single-can-hero / max 4 per color cast
  • Adjacent-pair check: each consecutive pair must differ on ≥ 2 of {surface, lighting, subject, cast}
  • Pinterest grid test with mandatory written answer
• §2 Voice Diversity Audit — filled at Phase C (after 9-agent refinement passes, before generation):
  • 7-register voice taxonomy (V1 BRAND-editorial / V2 BRAND-customer / V3 BRAND-PDP / V4 CAMPAIGN-defiant / V5 CAMPAIGN-satire / V6 CAMPAIGN-meta / V7 FOUNDER-podcast)
  • Source citation per line: [PODCAST] / [REVIEW] / [META] / [BRAND-EDITORIAL] / [BRAND-PDP] / [BRAND] / [SATIRE-ALLOWED]
  • Voice register tally check: BRAND voice 6-8 slots / CAMPAIGN 2-4 / FOUNDER-podcast 1-2 max
  • Repeated-anchor check: 1 founder story / ≤ 2 award slots / ≤ 2 SKU slots (3 for flagship+winner) / 1 signature phrase
  • Brand-swap test verification per the brand's voice agent

Why briefing stage, not QC

Diversity is a property of the slate, not of any individual rendered ad. Catching clustering after Fal generation costs $30+ in regen per batch. The audit lives at the briefing stage — STOP gates at Phase B and Phase C — so the cluster gets fixed in the prompt, not in the rendered output.

6. The technical generation reference GPT_IMAGE_2_PIPELINE.md

What's in it

1. § 0 When to use this — picks between this doc, nano_banana_revision_prompt.md, and BATCH_GENERATION_PIPELINE.md.
2. § 1 Setup — files needed on disk per client (spec cards, logo, product assets), aspect-ratio constraints (Fal hard rejects reference images > 3:1 long-edge), fal.ai credentials, image size selection (9:16 / 1:1 / 4:5).
3. § 2 Brief input — the per-ad input block: brand, product, persona, angle, tone adjectives, hard rules, format, scene language, headline / subhead / callouts / CTA / kicker, people override.
4. § 3 Assembly rules — 6 blocks Claude assembles in this exact order:
   1. § 3.1 Preamble (brand context)
   2. § 3.2 SAFE_ZONE block (verbatim) — the hard pixel constraints + background-continuity rules + coordinate-interpretation key. Copy this verbatim into every prompt.
   3. § 3.3 Brand typography (per spec card)
   4. § 3.4 Format-specific scene template (one of 22 format archetypes — features-benefits, headline, testimonial, before-after, ugc-tiktok, ugc-ig-story, handwriting-postit, press, etc.)
   5. § 3.5 Copy block (literal text only — no labels)
   6. § 3.6 Tier 1 rules (verbatim) — 14 hard-fail rules covering safe zones, instruction leakage, single continuous image, product fidelity, realistic light, no floating objects, sharp 0px corners, no em-dashes, brand banned words, typography fidelity, no paper-inset artifacts, scene specificity, brand DNA gate, variant rotation.
5. § 4 Generation script — the canonical generate-ads-gpt2.mjs template. fal.subscribe("openai/gpt-image-2/edit", ...). Sequential per-ad calls. 4-attempt fetch retry. Save on success.
6. § 5 Surgical product + lock matching — only upload the products that actually appear in the scene. Don't pass all SKUs as references on every call.
7. § 6 Custom dimensions — 1088×1920 (9:16), 1080×1080 (1:1), 1080×1350 (4:5).
8. § 7 Reference table — per-format expected count of text elements, scene archetype, common variants.
9. § 8 Production learnings — accumulated lessons from real batches: text rendering, product fidelity, scene realism, the safe-zones-important-caveat, King's Hawaiian production learnings, Luma UNI-1 production learnings, copy fidelity, multiple reference images, aspect ratio fidelity, retries and stability.
10. § 9 Picking a model — GPT Image 2 vs Nano Banana 2 trade-offs.

Why it matters

The SAFE_ZONE block in § 3.2 is the difference between an ad that ships and an ad with a headline rendered into Instagram's top status-bar zone. The Tier 1 rules in § 3.6 are the difference between an ad with a real-looking can on a real surface and an ad with paper-inset artifacts that the model invents. Every one of these rules came from a specific failure that shipped — they are not theoretical.