start-vibing-stacks 2.29.0 → 2.30.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/setup.js +15 -1
- package/package.json +1 -1
- package/stacks/_shared/ads-agents/README.md +452 -0
- package/stacks/_shared/ads-agents/RESEARCH-REPORT.md +157 -0
- package/stacks/_shared/ads-agents/SKILL.md +210 -0
- package/stacks/_shared/ads-agents/SKILLS-UPDATE-REPORT.md +255 -0
- package/stacks/_shared/ads-agents/agents/audit-budget.md +116 -0
- package/stacks/_shared/ads-agents/agents/audit-compliance.md +131 -0
- package/stacks/_shared/ads-agents/agents/audit-creative.md +127 -0
- package/stacks/_shared/ads-agents/agents/audit-google.md +113 -0
- package/stacks/_shared/ads-agents/agents/audit-meta.md +112 -0
- package/stacks/_shared/ads-agents/agents/audit-tracking.md +134 -0
- package/stacks/_shared/ads-agents/agents/copy-writer.md +188 -0
- package/stacks/_shared/ads-agents/agents/creative-strategist.md +199 -0
- package/stacks/_shared/ads-agents/agents/format-adapter.md +175 -0
- package/stacks/_shared/ads-agents/agents/visual-designer.md +245 -0
- package/stacks/_shared/ads-agents/references/additional-platforms.md +106 -0
- package/stacks/_shared/ads-agents/references/benchmarks.md +257 -0
- package/stacks/_shared/ads-agents/references/bidding-strategies.md +333 -0
- package/stacks/_shared/ads-agents/references/brand-dna-template.md +190 -0
- package/stacks/_shared/ads-agents/references/budget-allocation.md +150 -0
- package/stacks/_shared/ads-agents/references/compliance.md +280 -0
- package/stacks/_shared/ads-agents/references/conversion-tracking.md +246 -0
- package/stacks/_shared/ads-agents/references/copy-frameworks.md +187 -0
- package/stacks/_shared/ads-agents/references/funnel-content-copy-rules.md +44 -0
- package/stacks/_shared/ads-agents/references/gaql-notes.md +49 -0
- package/stacks/_shared/ads-agents/references/google-audit.md +217 -0
- package/stacks/_shared/ads-agents/references/google-creative-specs.md +119 -0
- package/stacks/_shared/ads-agents/references/image-providers.md +133 -0
- package/stacks/_shared/ads-agents/references/linkedin-audit.md +141 -0
- package/stacks/_shared/ads-agents/references/linkedin-creative-specs.md +129 -0
- package/stacks/_shared/ads-agents/references/mcp-integration.md +125 -0
- package/stacks/_shared/ads-agents/references/meta-audit.md +141 -0
- package/stacks/_shared/ads-agents/references/meta-creative-specs.md +134 -0
- package/stacks/_shared/ads-agents/references/microsoft-audit.md +158 -0
- package/stacks/_shared/ads-agents/references/microsoft-creative-specs.md +123 -0
- package/stacks/_shared/ads-agents/references/platform-specs.md +276 -0
- package/stacks/_shared/ads-agents/references/scoring-system.md +169 -0
- package/stacks/_shared/ads-agents/references/tiktok-audit.md +165 -0
- package/stacks/_shared/ads-agents/references/tiktok-creative-specs.md +139 -0
- package/stacks/_shared/ads-agents/references/voice-to-style.md +87 -0
- package/stacks/_shared/ads-agents/references/youtube-creative-specs.md +134 -0
- package/stacks/_shared/ads-agents/skills/ads-apple/SKILL.md +225 -0
- package/stacks/_shared/ads-agents/skills/ads-audit/SKILL.md +108 -0
- package/stacks/_shared/ads-agents/skills/ads-budget/SKILL.md +198 -0
- package/stacks/_shared/ads-agents/skills/ads-competitor/SKILL.md +198 -0
- package/stacks/_shared/ads-agents/skills/ads-create/SKILL.md +198 -0
- package/stacks/_shared/ads-agents/skills/ads-creative/SKILL.md +208 -0
- package/stacks/_shared/ads-agents/skills/ads-dna/SKILL.md +245 -0
- package/stacks/_shared/ads-agents/skills/ads-generate/SKILL.md +173 -0
- package/stacks/_shared/ads-agents/skills/ads-google/SKILL.md +192 -0
- package/stacks/_shared/ads-agents/skills/ads-landing/SKILL.md +186 -0
- package/stacks/_shared/ads-agents/skills/ads-linkedin/SKILL.md +200 -0
- package/stacks/_shared/ads-agents/skills/ads-math/SKILL.md +216 -0
- package/stacks/_shared/ads-agents/skills/ads-meta/SKILL.md +167 -0
- package/stacks/_shared/ads-agents/skills/ads-microsoft/SKILL.md +163 -0
- package/stacks/_shared/ads-agents/skills/ads-photoshoot/SKILL.md +220 -0
- package/stacks/_shared/ads-agents/skills/ads-plan/SKILL.md +176 -0
- package/stacks/_shared/ads-agents/skills/ads-test/SKILL.md +199 -0
- package/stacks/_shared/ads-agents/skills/ads-tiktok/SKILL.md +190 -0
- package/stacks/_shared/ads-agents/skills/ads-youtube/SKILL.md +199 -0
- package/stacks/_shared/memories/funnel-content-copy.md +81 -0
- package/templates/CLAUDE-python.md +6 -0
|
@@ -0,0 +1,333 @@
|
|
|
1
|
+
# Bidding Strategy Decision Trees
|
|
2
|
+
|
|
3
|
+
<!-- Updated: 2026-05-14 | v1.6: corrected AI Max conversion lift + DSA migration timing -->
|
|
4
|
+
<!-- Sources: Google Research PDF 2, Claude Research, Gemini Research, 2026 Verification Pass -->
|
|
5
|
+
|
|
6
|
+
## Google Ads Bidding Decision Engine
|
|
7
|
+
|
|
8
|
+
### Strategy Selection Flow
|
|
9
|
+
|
|
10
|
+
```
|
|
11
|
+
START → How many conversions in last 30 days?
|
|
12
|
+
|
|
13
|
+
┌─ < 15 conversions ──────────────────────────┐
|
|
14
|
+
│ → Maximize Clicks (cold start) │
|
|
15
|
+
│ → Set Max CPC = Target_CPA / (CVR × 1.5) │
|
|
16
|
+
│ → Learning: 3-5 days │
|
|
17
|
+
│ → Monitor until 15+ conversions achieved │
|
|
18
|
+
│ → OR use Manual CPC if full control needed │
|
|
19
|
+
│ → NOTE: eCPC fully removed March 2025 │
|
|
20
|
+
└──────────────────────────────────────────────┘
|
|
21
|
+
|
|
22
|
+
┌─ 15-29 conversions ─────────────────────────┐
|
|
23
|
+
│ → Maximize Conversions (uncapped) │
|
|
24
|
+
│ → Learning: 7-14 days │
|
|
25
|
+
│ → Transition when CPA SD < 20% over 14d │
|
|
26
|
+
│ → THEN switch to Target CPA │
|
|
27
|
+
└──────────────────────────────────────────────┘
|
|
28
|
+
|
|
29
|
+
┌─ 30+ conversions, NO dynamic values ────────┐
|
|
30
|
+
│ → Target CPA │
|
|
31
|
+
│ → Strict: 30+ (Google says 15, but 30+ │
|
|
32
|
+
│ for reliable performance, 50+ ideal) │
|
|
33
|
+
│ → Set at: 1.1x-1.2x historical CPA │
|
|
34
|
+
│ → Adjust: Max 10% change every 14 days │
|
|
35
|
+
│ → Never lower by more than 15% at once │
|
|
36
|
+
└──────────────────────────────────────────────┘
|
|
37
|
+
|
|
38
|
+
┌─ 50+ conversions WITH dynamic values ───────┐
|
|
39
|
+
│ → Target ROAS │
|
|
40
|
+
│ → Requires dynamic conversion values │
|
|
41
|
+
│ → Set at: EXACT historical ROAS │
|
|
42
|
+
│ → Formula: Bid = P(conv) × Value × 1/tROAS│
|
|
43
|
+
│ → Adjust: Same rules as tCPA │
|
|
44
|
+
└──────────────────────────────────────────────┘
|
|
45
|
+
|
|
46
|
+
### Smart Bidding Exploration (Google, 2025+)
|
|
47
|
+
|
|
48
|
+
Allows flexible ROAS targets to discover new traffic. Delivers 18% more
|
|
49
|
+
unique search query categories + 19% more conversions.
|
|
50
|
+
|
|
51
|
+
- **How it works**: Algorithm temporarily relaxes ROAS constraints to
|
|
52
|
+
enter auctions it would normally skip, testing new user segments
|
|
53
|
+
- **When to enable**: Stable tROAS campaigns with 50+ conversions/month
|
|
54
|
+
seeking incremental growth beyond current query coverage
|
|
55
|
+
- **When to avoid**: Tight-margin accounts or campaigns already spending
|
|
56
|
+
full budget (exploration adds volume, not just efficiency)
|
|
57
|
+
- **Available on**: Target ROAS bid strategies only
|
|
58
|
+
|
|
59
|
+
### AI Max for Search (Google, 2025+)
|
|
60
|
+
|
|
61
|
+
AI Max for Search layers broad match + keywordless targeting on existing
|
|
62
|
+
Search campaigns. Google reports 7% more conversions or conversion value
|
|
63
|
+
at comparable CPA/ROAS when the full feature suite is enabled (search
|
|
64
|
+
term matching + text customization + final URL expansion). DSA officially
|
|
65
|
+
being consolidated into AI Max with automatic upgrades starting September
|
|
66
|
+
2026; new DSA campaign creation ends September 2026. Requires strong
|
|
67
|
+
negative keyword lists.
|
|
68
|
+
|
|
69
|
+
- **How it works**: Automatically expands keyword coverage using AI to
|
|
70
|
+
match user intent beyond exact keyword matches
|
|
71
|
+
- **When to enable**: Established Search campaigns with healthy conversion
|
|
72
|
+
volume and comprehensive negative keyword lists
|
|
73
|
+
- **When to avoid**: Low-budget campaigns without negative keyword hygiene;
|
|
74
|
+
accounts with strict brand safety requirements
|
|
75
|
+
- **Migration note**: Migrate DSA campaigns to AI Max before September 2026 auto-upgrade
|
|
76
|
+
|
|
77
|
+
┌─ Brand Protection campaigns ────────────────┐
|
|
78
|
+
│ → Target Impression Share │
|
|
79
|
+
│ → Target: 95-100% on brand keywords │
|
|
80
|
+
│ → No conversion data requirement │
|
|
81
|
+
│ → Search only (not available elsewhere) │
|
|
82
|
+
└──────────────────────────────────────────────┘
|
|
83
|
+
|
|
84
|
+
SPECIAL CASES:
|
|
85
|
+
- PMax: Always uses Maximize Conversions or Maximize Conv Value
|
|
86
|
+
- Demand Gen: Supports Target CPC (new), tCPA, tROAS, Max Clicks
|
|
87
|
+
- Display Pay per Conversion: Eligibility required
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### Attribution Model (Google)
|
|
91
|
+
- **DDA (Data-Driven Attribution) is now MANDATORY default** (September 2025)
|
|
92
|
+
- Only two models remain: DDA and Last Click
|
|
93
|
+
- All rule-based models deprecated (first-click, linear, time decay, position-based)
|
|
94
|
+
- No minimum data threshold for DDA
|
|
95
|
+
- Impact on bidding: DDA distributes conversion credit across touchpoints, affecting Smart Bidding signals
|
|
96
|
+
|
|
97
|
+
### Portfolio Bid Strategies
|
|
98
|
+
|
|
99
|
+
When to use portfolios:
|
|
100
|
+
- Multiple campaigns each with <15 conv, but combined >30
|
|
101
|
+
- Need cross-campaign budget optimization
|
|
102
|
+
- **CPC Cap Hack**: Only way to set max CPC bid on tCPA/tROAS
|
|
103
|
+
|
|
104
|
+
Rules:
|
|
105
|
+
- Minimum 3 campaigns per portfolio for meaningful data
|
|
106
|
+
- Group campaigns with similar target CPAs/ROAS
|
|
107
|
+
- Never mix brand and non-brand in same portfolio
|
|
108
|
+
|
|
109
|
+
### Transition Triggers (Google)
|
|
110
|
+
|
|
111
|
+
| From | To | Trigger |
|
|
112
|
+
|------|----|---------|
|
|
113
|
+
| Maximize Clicks | Maximize Conversions | 15+ conversions in 30 days |
|
|
114
|
+
| Maximize Conversions | Target CPA | CPA SD <20% over 14 days + 30+ conv |
|
|
115
|
+
| Target CPA | Target ROAS | 50+ conv + dynamic values available |
|
|
116
|
+
| Manual CPC | Maximize Clicks | Ready to test automation |
|
|
117
|
+
| Any | Target Impression Share | Brand protection need identified |
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## Meta Ads Bidding Decision Engine
|
|
122
|
+
|
|
123
|
+
### Auction Formula
|
|
124
|
+
|
|
125
|
+
```
|
|
126
|
+
Total Value = Bid × Estimated Action Rate + User Value
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
### Strategy Selection
|
|
130
|
+
|
|
131
|
+
```
|
|
132
|
+
DEFAULT (90% of campaigns):
|
|
133
|
+
→ Lowest Cost (no cap)
|
|
134
|
+
→ Best for: Most campaigns, volume maximization
|
|
135
|
+
→ Risk: CPA can spike during high-competition (Q4)
|
|
136
|
+
|
|
137
|
+
IF need cost predictability:
|
|
138
|
+
→ Cost Cap
|
|
139
|
+
→ Set at: 1.2x - 1.5x target CPA
|
|
140
|
+
→ Best for: Scaling with margin protection
|
|
141
|
+
→ Risk: Under-delivery if cap too aggressive
|
|
142
|
+
|
|
143
|
+
IF need strict cost control:
|
|
144
|
+
→ Bid Cap
|
|
145
|
+
→ Set at: 2x - 3x target CPA
|
|
146
|
+
→ Best for: Experienced advertisers with clear unit economics
|
|
147
|
+
→ Risk: Significant under-delivery if too low
|
|
148
|
+
|
|
149
|
+
IF e-commerce with revenue tracking:
|
|
150
|
+
→ ROAS Goal
|
|
151
|
+
→ Best for: Advantage+ Sales Campaigns
|
|
152
|
+
→ Requires: Purchase event + dynamic values
|
|
153
|
+
|
|
154
|
+
IF high-value diverse products:
|
|
155
|
+
→ Highest Value
|
|
156
|
+
→ Prioritizes high-value conversions
|
|
157
|
+
→ Best for: Wide AOV range
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
### Andromeda Context
|
|
161
|
+
|
|
162
|
+
Under Andromeda, creative diversity matters more than bid strategy.
|
|
163
|
+
Focus budget on creative testing, not micro-optimizing bids.
|
|
164
|
+
|
|
165
|
+
### CBO vs ABO Decision
|
|
166
|
+
|
|
167
|
+
```
|
|
168
|
+
IF daily_budget < $100:
|
|
169
|
+
→ ABO (manual control for testing)
|
|
170
|
+
|
|
171
|
+
IF daily_budget $100-$500:
|
|
172
|
+
→ Test both; CBO if similar audiences, ABO if diverse
|
|
173
|
+
|
|
174
|
+
IF daily_budget > $500:
|
|
175
|
+
→ CBO (Advantage+ Campaign Budget)
|
|
176
|
+
→ Let Meta optimize distribution
|
|
177
|
+
|
|
178
|
+
NOTE: Advantage+ Sales/Leads auto-enable CBO
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
### Learning Phase Rules
|
|
182
|
+
|
|
183
|
+
**Exit criteria:** 50 conversions per week per ad set
|
|
184
|
+
|
|
185
|
+
**Reset triggers (avoid during learning):**
|
|
186
|
+
- Budget change >20%
|
|
187
|
+
- Any targeting change
|
|
188
|
+
- Creative edit (even text)
|
|
189
|
+
- Bid strategy change
|
|
190
|
+
- Pausing >7 days
|
|
191
|
+
|
|
192
|
+
**If "Learning Limited":**
|
|
193
|
+
1. Broaden audience
|
|
194
|
+
2. Increase budget
|
|
195
|
+
3. Switch to higher-funnel event (AddToCart instead of Purchase)
|
|
196
|
+
4. Consolidate ad sets
|
|
197
|
+
5. Ensure daily budget ≥5× target CPA
|
|
198
|
+
|
|
199
|
+
---
|
|
200
|
+
|
|
201
|
+
## LinkedIn Ads Bidding
|
|
202
|
+
|
|
203
|
+
### Strategy Selection
|
|
204
|
+
|
|
205
|
+
```
|
|
206
|
+
Sponsored Content:
|
|
207
|
+
→ Start with Manual CPC for cost control (recommended default)
|
|
208
|
+
→ Test automated bidding only with established data
|
|
209
|
+
→ Maximum Delivery is the most expensive option
|
|
210
|
+
→ Minimum daily budget: $10/day (recommend $50+)
|
|
211
|
+
|
|
212
|
+
Message Ads:
|
|
213
|
+
→ CPS (Cost Per Send): bid aggressively
|
|
214
|
+
→ Frequency cap: 1 per 30-45 days per user
|
|
215
|
+
→ Win the auction for limited inbox slot
|
|
216
|
+
|
|
217
|
+
Lead Gen Forms:
|
|
218
|
+
→ Lowest Cost or Manual CPC
|
|
219
|
+
→ 13% CVR benchmark (3.25× landing pages)
|
|
220
|
+
|
|
221
|
+
Conversation Ads:
|
|
222
|
+
→ CPS: similar to Message Ads
|
|
223
|
+
→ 10-12% CTR benchmark
|
|
224
|
+
|
|
225
|
+
TLA (Thought Leader Ads):
|
|
226
|
+
→ Allocate ≥30% budget
|
|
227
|
+
→ CPC $2.29-$4.14 (vs $13.23 standard)
|
|
228
|
+
|
|
229
|
+
Accelerate Campaigns:
|
|
230
|
+
→ AI-powered end-to-end
|
|
231
|
+
→ 42% lower CPA, 21% lower CPL
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
---
|
|
235
|
+
|
|
236
|
+
## TikTok Ads Bidding
|
|
237
|
+
|
|
238
|
+
### Strategy Selection
|
|
239
|
+
|
|
240
|
+
```
|
|
241
|
+
DEFAULT:
|
|
242
|
+
→ Lowest Cost (volume maximization)
|
|
243
|
+
→ Most common, good starting point
|
|
244
|
+
|
|
245
|
+
IF margin protection needed:
|
|
246
|
+
→ Cost Cap
|
|
247
|
+
→ Set target CPA, system tries to stay near
|
|
248
|
+
|
|
249
|
+
IF strict cost control needed:
|
|
250
|
+
→ Bid Cap
|
|
251
|
+
→ Controls maximum bid per auction (not average CPA)
|
|
252
|
+
→ Set at 2-3x target CPA initially
|
|
253
|
+
→ Best for: retargeting, competitive niches (Q4/BFCM)
|
|
254
|
+
→ Risk: significant under-delivery if set too aggressively
|
|
255
|
+
|
|
256
|
+
IF Smart+ campaign:
|
|
257
|
+
→ Modular automation (choose per module)
|
|
258
|
+
→ Up to 30 ad groups, 50 creatives per asset group
|
|
259
|
+
→ Smart+ now supports modular control (2025). Lock
|
|
260
|
+
targeting/creative/budget/placement independently
|
|
261
|
+
while automating others
|
|
262
|
+
|
|
263
|
+
GMV Max (TikTok Shop):
|
|
264
|
+
→ Default/only for Shop campaigns (July 2025)
|
|
265
|
+
→ Optimizes for Gross Merchandise Value
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
### Budget Rules
|
|
269
|
+
- Campaign minimum: $50/day
|
|
270
|
+
- Ad group minimum: $20/day
|
|
271
|
+
- Budget should be ≥50× target CPA per ad group (provides sufficient learning room)
|
|
272
|
+
- Learning phase: ~50 conversions in 7 days
|
|
273
|
+
|
|
274
|
+
---
|
|
275
|
+
|
|
276
|
+
## Microsoft Ads Bidding
|
|
277
|
+
|
|
278
|
+
### Strategy Selection
|
|
279
|
+
|
|
280
|
+
```
|
|
281
|
+
IF importing from Google:
|
|
282
|
+
→ Match Google bid strategy
|
|
283
|
+
→ Validate settings transferred correctly
|
|
284
|
+
→ Adjust targets (typically 20-35% lower CPC on Bing)
|
|
285
|
+
|
|
286
|
+
IF native campaign:
|
|
287
|
+
→ Same strategy framework as Google
|
|
288
|
+
→ Lower CPC targets (expect $1.20-$1.55 avg)
|
|
289
|
+
→ Enable Copilot placement for PMax
|
|
290
|
+
|
|
291
|
+
PMax on Microsoft:
|
|
292
|
+
→ Enable "Target New Customers" (Beta 2026)
|
|
293
|
+
→ Copilot chat placement: 73% higher CTR
|
|
294
|
+
→ LinkedIn profile targeting (unique)
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
---
|
|
298
|
+
|
|
299
|
+
## Apple Ads Bidding
|
|
300
|
+
|
|
301
|
+
### Maximize Conversions (GA Feb 26, 2026)
|
|
302
|
+
|
|
303
|
+
AI-powered auto-bidder using Search Match. Currently only optimizes for installs.
|
|
304
|
+
|
|
305
|
+
```
|
|
306
|
+
Strategy Selection:
|
|
307
|
+
→ Maximize Conversions (recommended for most campaigns)
|
|
308
|
+
→ Target CPA (weekly average target) replaces CPA Cap (being deprecated)
|
|
309
|
+
→ Daily budget >= 5x target CPA
|
|
310
|
+
→ Two-week learning period before evaluating performance
|
|
311
|
+
|
|
312
|
+
Key Rules:
|
|
313
|
+
→ Set realistic target CPA based on historical install cost
|
|
314
|
+
→ Avoid budget or target changes during the 2-week learning period
|
|
315
|
+
→ Currently only optimizes for installs (not post-install events)
|
|
316
|
+
→ Pair with strong Search Match negative keywords to control relevance
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
---
|
|
320
|
+
|
|
321
|
+
## Cross-Platform Bidding Red Flags
|
|
322
|
+
|
|
323
|
+
| Red Flag | Severity | Platform | Action |
|
|
324
|
+
|----------|----------|----------|--------|
|
|
325
|
+
| Broad Match + Manual CPC | Critical | Google | Switch to Smart Bidding or Exact Match |
|
|
326
|
+
| tCPA <50% of actual CPA | Critical | Google | Unrealistic target; set at 1.1-1.2× historical |
|
|
327
|
+
| Smart Bidding with <15 conv/month | High | Google | Use Manual CPC or Maximize Clicks |
|
|
328
|
+
| >50% ad sets "Learning Limited" | Critical | Meta | Consolidate, broaden audience, increase budget |
|
|
329
|
+
| Cost Cap below historical CPA | High | Meta | Set at 1.2-1.5× target, not below |
|
|
330
|
+
| Daily budget <5× CPA | High | Meta | Increase budget or switch to higher-funnel event |
|
|
331
|
+
| Budget < $50/day campaign | High | TikTok | Increase to minimum or consolidate |
|
|
332
|
+
| No negative keywords with Broad Match | Critical | Google | Add themed negative lists immediately |
|
|
333
|
+
| No Portfolio strategy for low-vol campaigns | Medium | Google | Group <15 conv campaigns into portfolio |
|
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
# Brand DNA Template
|
|
2
|
+
|
|
3
|
+
<!-- Updated: 2026-03-12 -->
|
|
4
|
+
<!-- Used by: ads-dna (extraction), ads-create (consumption), ads-generate (style injection) -->
|
|
5
|
+
|
|
6
|
+
## Purpose
|
|
7
|
+
|
|
8
|
+
Defines the canonical schema for `brand-profile.json`. All agents that produce or
|
|
9
|
+
consume brand data must use these exact field names and value types.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## JSON Schema
|
|
14
|
+
|
|
15
|
+
```json
|
|
16
|
+
{
|
|
17
|
+
"schema_version": "1.0",
|
|
18
|
+
"brand_name": "string",
|
|
19
|
+
"website_url": "string (full URL including https://)",
|
|
20
|
+
"extracted_at": "ISO-8601 timestamp (e.g. 2026-03-12T14:30:00Z)",
|
|
21
|
+
|
|
22
|
+
"voice": {
|
|
23
|
+
"formal_casual": 7,
|
|
24
|
+
"rational_emotional": 4,
|
|
25
|
+
"playful_serious": 5,
|
|
26
|
+
"bold_subtle": 8,
|
|
27
|
+
"traditional_innovative": 6,
|
|
28
|
+
"expert_accessible": 5,
|
|
29
|
+
"descriptors": ["authoritative", "warm", "direct"]
|
|
30
|
+
},
|
|
31
|
+
|
|
32
|
+
"colors": {
|
|
33
|
+
"primary": "#1A2E4A",
|
|
34
|
+
"secondary": ["#F4A623", "#FFFFFF"],
|
|
35
|
+
"forbidden": ["#FF0000"],
|
|
36
|
+
"background": "#F9F9F9",
|
|
37
|
+
"text": "#1A1A1A"
|
|
38
|
+
},
|
|
39
|
+
|
|
40
|
+
"typography": {
|
|
41
|
+
"heading_font": "Inter",
|
|
42
|
+
"body_font": "Source Sans Pro",
|
|
43
|
+
"pairing_descriptor": "modern sans-serif, clean and readable"
|
|
44
|
+
},
|
|
45
|
+
|
|
46
|
+
"imagery": {
|
|
47
|
+
"style": "professional photography",
|
|
48
|
+
"subjects": ["people using product", "clean product shots", "diverse workforce"],
|
|
49
|
+
"composition": "clean backgrounds, good negative space",
|
|
50
|
+
"forbidden": ["stock photo clichés", "corporate handshakes", "cheesy smiles"]
|
|
51
|
+
},
|
|
52
|
+
|
|
53
|
+
"aesthetic": {
|
|
54
|
+
"mood_keywords": ["trustworthy", "modern", "approachable"],
|
|
55
|
+
"texture": "minimal, flat",
|
|
56
|
+
"negative_space": "generous"
|
|
57
|
+
},
|
|
58
|
+
|
|
59
|
+
"brand_values": ["transparency", "innovation", "customer-first"],
|
|
60
|
+
|
|
61
|
+
"target_audience": {
|
|
62
|
+
"age_range": "28-45",
|
|
63
|
+
"profession": "marketing managers and small business owners",
|
|
64
|
+
"pain_points": ["time-consuming reporting", "unclear ROI"],
|
|
65
|
+
"aspirations": ["grow efficiently", "look professional"]
|
|
66
|
+
},
|
|
67
|
+
|
|
68
|
+
"screenshots": {
|
|
69
|
+
"homepage": "./brand-screenshots/example_com_desktop.png",
|
|
70
|
+
"secondary": ["./brand-screenshots/example_com_pricing_desktop.png"]
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## Field Reference
|
|
78
|
+
|
|
79
|
+
### Voice Axes (1-10 scale)
|
|
80
|
+
|
|
81
|
+
Score interpretation: 1 = extreme left pole, 10 = extreme right pole, 5 = neutral.
|
|
82
|
+
|
|
83
|
+
| Field | 1 (Left) | 10 (Right) | Ad Implication |
|
|
84
|
+
|-------|----------|------------|----------------|
|
|
85
|
+
| `formal_casual` | Very formal, corporate | Very casual, conversational | Headlines tone |
|
|
86
|
+
| `rational_emotional` | Data-driven, logical | Emotionally evocative | Story vs stats |
|
|
87
|
+
| `playful_serious` | Fun, humorous | Serious, no-nonsense | CTA phrasing |
|
|
88
|
+
| `bold_subtle` | Big claims, loud | Understated, nuanced | Visual hierarchy |
|
|
89
|
+
| `traditional_innovative` | Classic, established | Cutting-edge, disruptive | Imagery style |
|
|
90
|
+
| `expert_accessible` | Deep expertise, jargon | Everyone can understand | Copy complexity |
|
|
91
|
+
|
|
92
|
+
`descriptors` (array of 3-5 strings): Free-form adjectives capturing tone not covered by axes.
|
|
93
|
+
|
|
94
|
+
### Colors
|
|
95
|
+
|
|
96
|
+
- `primary`: Main brand color. **Always inject into image generation prompts.**
|
|
97
|
+
- `secondary`: Supporting palette. Use for accents in generation prompts.
|
|
98
|
+
- `forbidden`: Colors to explicitly exclude from prompts (e.g., competitor brand colors).
|
|
99
|
+
- `background` / `text`: Digital UI colors (less relevant for ad image generation).
|
|
100
|
+
|
|
101
|
+
**Null handling:** If extraction fails for a color, set to `null`. Agents must skip null
|
|
102
|
+
color injection rather than defaulting to arbitrary colors.
|
|
103
|
+
|
|
104
|
+
### Typography
|
|
105
|
+
|
|
106
|
+
Used by `copy-writer` agent for tone calibration. Not injected into image prompts
|
|
107
|
+
(typography is handled by ad platform copy fields, not image generation).
|
|
108
|
+
|
|
109
|
+
### Imagery
|
|
110
|
+
|
|
111
|
+
- `style`: Main descriptor passed to image generation (e.g., "professional photography",
|
|
112
|
+
"illustration", "flat design").
|
|
113
|
+
- `subjects`: Array injected as subject guidance in prompts.
|
|
114
|
+
- `composition`: Passed verbatim as a composition constraint.
|
|
115
|
+
- `forbidden`: Converted to negative prompt modifiers (e.g., "no corporate handshakes").
|
|
116
|
+
|
|
117
|
+
### Aesthetic
|
|
118
|
+
|
|
119
|
+
- `mood_keywords`: Injected directly into generation prompts as atmosphere descriptors.
|
|
120
|
+
- `texture`: Passed as texture preference.
|
|
121
|
+
- `negative_space`: "generous" → "plenty of white space, uncluttered composition".
|
|
122
|
+
|
|
123
|
+
### Screenshots (optional, populated by `/ads dna`)
|
|
124
|
+
|
|
125
|
+
- `homepage`: Desktop screenshot of homepage. **Primary visual style reference** for
|
|
126
|
+
`visual-designer` agent. When present, generation auto-uses `gemini-3.1-flash-image-preview`
|
|
127
|
+
(Nano Banana 2) for better brand style-transfer.
|
|
128
|
+
- `secondary`: Additional pages (pricing, about, product). Supplemental context.
|
|
129
|
+
- **If field absent**: `visual-designer` falls back to text-only generation (`gemini-2.5-flash-image`).
|
|
130
|
+
- **If field present but file missing on disk**: `visual-designer` logs a warning and falls back gracefully.
|
|
131
|
+
- Set by `ads-dna` Step 2b. Omitted entirely if screenshot capture failed or `--quick` was used.
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## Extraction Guide
|
|
136
|
+
|
|
137
|
+
### Pages to scan (in order)
|
|
138
|
+
|
|
139
|
+
1. **Homepage**: Primary brand impression, dominant colors, hero headline tone
|
|
140
|
+
2. **About / Our Story**: Brand values, voice descriptors, team photography style
|
|
141
|
+
3. **Product / Service page**: Imagery style, composition, subject matter
|
|
142
|
+
4. **Existing ads** (if accessible via Meta Ad Library or Google Ads Transparency): Override
|
|
143
|
+
|
|
144
|
+
### CSS extraction targets
|
|
145
|
+
|
|
146
|
+
```
|
|
147
|
+
background-color, color → colors.primary / secondary
|
|
148
|
+
font-family → typography.heading_font / body_font
|
|
149
|
+
@import url (Google Fonts) → typography (font name from URL path)
|
|
150
|
+
og:image meta tag → imagery.style (analyze dominant visual)
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### Voice scoring heuristics
|
|
154
|
+
|
|
155
|
+
| Signal | Scoring |
|
|
156
|
+
|--------|---------|
|
|
157
|
+
| Uses "you" and "your" frequently | formal_casual +2 (casual) |
|
|
158
|
+
| Industry jargon in hero text | expert_accessible -2 (expert) |
|
|
159
|
+
| Short sentences (≤10 words) | bold_subtle +1 (bold) |
|
|
160
|
+
| Testimonials lead with emotion | rational_emotional +2 (emotional) |
|
|
161
|
+
| "Trusted by 10,000+ companies" | traditional_innovative -1 (traditional) |
|
|
162
|
+
|
|
163
|
+
### Fallback heuristics
|
|
164
|
+
|
|
165
|
+
- **No Google Fonts detected**: Set `typography.heading_font` to "system-ui"
|
|
166
|
+
- **Sparse content (< 200 words)**: Mark `extracted_at` note: "low confidence extraction"
|
|
167
|
+
- **Dark mode site**: If background is dark (#333 or darker), swap `background` and `text`
|
|
168
|
+
- **Cannot extract primary color**: Use most prominent color from og:image analysis
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
## Usage in Generation Prompts
|
|
173
|
+
|
|
174
|
+
When building image generation prompts, inject brand DNA as:
|
|
175
|
+
|
|
176
|
+
```
|
|
177
|
+
"[subject], [imagery.style], [imagery.composition],
|
|
178
|
+
brand colors [colors.primary] and [colors.secondary[0]],
|
|
179
|
+
[aesthetic.mood_keywords joined by comma] atmosphere,
|
|
180
|
+
[aesthetic.texture] texture, [aesthetic.negative_space] composition,
|
|
181
|
+
no [imagery.forbidden joined by comma]"
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
Example output:
|
|
185
|
+
```
|
|
186
|
+
"person using laptop, professional photography, clean backgrounds good negative space,
|
|
187
|
+
brand colors #1A2E4A and #F4A623, trustworthy modern approachable atmosphere,
|
|
188
|
+
minimal flat texture, generous white space composition,
|
|
189
|
+
no stock photo clichés, no corporate handshakes"
|
|
190
|
+
```
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# Budget Allocation & Scaling Framework
|
|
2
|
+
|
|
3
|
+
<!-- Updated: 2026-02-10 -->
|
|
4
|
+
<!-- Sources: Google Research PDF 2, Claude Research, Gemini Research -->
|
|
5
|
+
|
|
6
|
+
## Platform Selection Matrix by Business Type
|
|
7
|
+
|
|
8
|
+
| Business Type | Platform 1 | Platform 2 | Platform 3 | Other | Min Monthly | Primary KPI | Time to Profit |
|
|
9
|
+
|--------------|------------|------------|------------|-------|-------------|-------------|---------------|
|
|
10
|
+
| SaaS B2B | Google 35-45% | LinkedIn 30-40% | Meta 15-25% | YouTube 10% | $5,000 | Pipeline ROI, LTV:CAC | 3-6 months |
|
|
11
|
+
| E-commerce DTC | Meta 50-68% | Google PMax 23-30% | TikTok 5-15% | Email 5% | $3,000 | ROAS, MER, POAS | 0-2 months |
|
|
12
|
+
| Local Service | Google LSA/Search 60% | Meta 30% | Bing 10% | N/A | $1,500 | Cost Per Lead/Booking | 1 month |
|
|
13
|
+
| B2B Enterprise | LinkedIn 39-60% | Google 20-35% | ABM Display 15-20% | Programmatic 11% | $10,000 | Pipeline, SQLs | 6-12 months |
|
|
14
|
+
| Info Products | YouTube 40% | Meta 40% | Email 20% | N/A | $2,000 | ROAS, Webinar CPL | 1-3 months |
|
|
15
|
+
| Mobile App | Apple Search 30% | Google App 30% | Meta/TikTok 40% | N/A | $5,000 | CPI, LTV, D7 Retention | 3-6 months |
|
|
16
|
+
| Real Estate | Meta Lead Forms 50% | Google Search 40% | LinkedIn 10% | N/A | $2,500 | Cost Per Lead | 2-4 months |
|
|
17
|
+
| Healthcare | Google Search 55% | Meta 20% | Microsoft 10% | YouTube/Display 15% | $4,000 | Cost Per Patient | 2-5 months |
|
|
18
|
+
| Finance/Fintech | Google Search 40-50% | LinkedIn 20-30% | Meta 15% | YouTube/Display 10% | $8,000 | CAC, LTV:CAC | 4-8 months |
|
|
19
|
+
| Agency (Own) | LinkedIn 50% | Meta 30% | Google 20% | N/A | $1,500 | Cost Per Lead | 1-3 months |
|
|
20
|
+
| B2C / DTC | Meta 50% | Google 20% | TikTok 30% | N/A | $2,000 | ROAS, CAC | 1-3 months |
|
|
21
|
+
|
|
22
|
+
## Budget Distribution Rule: 70/20/10
|
|
23
|
+
|
|
24
|
+
```
|
|
25
|
+
70% → Proven performers (campaigns with established positive ROAS/CPA)
|
|
26
|
+
20% → Promising growth (campaigns showing traction, need scale)
|
|
27
|
+
10% → Experiments (new platforms, audiences, formats)
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Scaling Decision Tree
|
|
31
|
+
|
|
32
|
+
### 20% Rule (Scale Up)
|
|
33
|
+
```
|
|
34
|
+
IF actual_CPA < target_CPA by > 10%
|
|
35
|
+
AND conversions_last_7d >= learning_threshold
|
|
36
|
+
AND campaign NOT in learning phase
|
|
37
|
+
THEN increase budget by 20%
|
|
38
|
+
→ Wait 3-5 days before next increase
|
|
39
|
+
→ Never increase more than 20% at once on Meta (triggers learning reset)
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### 3× Kill Rule (Pause)
|
|
43
|
+
```
|
|
44
|
+
IF spend > 3× target_CPA
|
|
45
|
+
AND conversions == 0
|
|
46
|
+
THEN pause ad/ad set/campaign immediately
|
|
47
|
+
→ Review: creative, targeting, landing page, tracking
|
|
48
|
+
→ Don't restart without changes
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### Decreasing Returns Detection
|
|
52
|
+
```
|
|
53
|
+
IF CPA increased > 15% after last budget increase
|
|
54
|
+
THEN roll back to previous budget level
|
|
55
|
+
→ Wait 7 days
|
|
56
|
+
→ Try horizontal scaling instead (new audiences, platforms)
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### Saturation Signals
|
|
60
|
+
| Platform | Signal | Threshold | Action |
|
|
61
|
+
|----------|--------|-----------|--------|
|
|
62
|
+
| Google | Impression Share | >80% | Diminishing returns; diversify |
|
|
63
|
+
| Meta | Frequency (7-day) | >4.0 | Audience exhausted; refresh creative or expand |
|
|
64
|
+
| TikTok | Frequency | >3.0 | Creative fatigue; replace assets |
|
|
65
|
+
| LinkedIn | Audience penetration | >50% | Audience exhausted; expand targeting |
|
|
66
|
+
|
|
67
|
+
## Marketing Efficiency Ratio (MER)
|
|
68
|
+
|
|
69
|
+
```
|
|
70
|
+
MER = Total Revenue / Total Ad Spend (all platforms combined)
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
| Business Type | Healthy MER | Excellent MER | Danger Zone |
|
|
74
|
+
|--------------|-------------|---------------|-------------|
|
|
75
|
+
| E-commerce | 3.0-5.0 | >5.0 | <2.0 |
|
|
76
|
+
| SaaS | Use LTV:CAC (3:1 target) | >4:1 | <2:1 |
|
|
77
|
+
| Lead Gen | Revenue/Lead × CVR / CPL | N/A | <1.5 |
|
|
78
|
+
|
|
79
|
+
**Why MER over ROAS:**
|
|
80
|
+
- ROAS is platform-reported (overclaims by 20-40%)
|
|
81
|
+
- MER captures true business economics
|
|
82
|
+
- Cross-platform; not inflated by attribution overlap
|
|
83
|
+
|
|
84
|
+
## Seasonality Adjustments
|
|
85
|
+
|
|
86
|
+
### Q4 (October-December)
|
|
87
|
+
- CPMs increase 30-50%
|
|
88
|
+
- Reduce ROAS targets by 20%
|
|
89
|
+
- Front-load creative testing in September
|
|
90
|
+
- Increase budgets 40-60% for Black Friday / Cyber Monday
|
|
91
|
+
- Meta: Advantage+ Sales performs best during peaks
|
|
92
|
+
|
|
93
|
+
### Q1 (January-March)
|
|
94
|
+
- CPMs decrease 20-30% post-holiday
|
|
95
|
+
- Best time for new campaign testing
|
|
96
|
+
- Aggressive customer acquisition (lower competition)
|
|
97
|
+
- Meta Jan 2026 CPC: $0.85 (24% below prior January)
|
|
98
|
+
|
|
99
|
+
### Q2 (April-June)
|
|
100
|
+
- Steady CPMs, good testing window
|
|
101
|
+
- Mother's Day / Father's Day spikes for retail
|
|
102
|
+
|
|
103
|
+
### Q3 (July-September)
|
|
104
|
+
- LinkedIn CPC peaks in Q3 ($15.72 average)
|
|
105
|
+
- Back-to-school surge for education
|
|
106
|
+
- Good time to build retargeting pools for Q4
|
|
107
|
+
|
|
108
|
+
## Incrementality Testing (Geo-Lift)
|
|
109
|
+
|
|
110
|
+
### Setup
|
|
111
|
+
- Duration: 2-4 weeks minimum
|
|
112
|
+
- Holdout: 10% of geographic regions (matched pairs)
|
|
113
|
+
- Method: Compare conversion rates exposed vs holdout
|
|
114
|
+
- Statistical significance: p < 0.05
|
|
115
|
+
|
|
116
|
+
### Tools
|
|
117
|
+
- Meta: Robyn (R-based, open source), best for ~80% of orgs
|
|
118
|
+
- Google: Meridian (Python, Bayesian, geo-level)
|
|
119
|
+
- Advanced: PyMC-Marketing (fully customizable)
|
|
120
|
+
- Budget: Significant; allocate 10% of monthly spend for testing
|
|
121
|
+
|
|
122
|
+
### Post-Purchase Surveys
|
|
123
|
+
- Fill ~30% of attribution gap that digital tracking misses
|
|
124
|
+
- Question: "How did you first hear about us?"
|
|
125
|
+
- Implement on order confirmation page
|
|
126
|
+
- Weight responses against platform-reported data
|
|
127
|
+
|
|
128
|
+
## Minimum Viable Budgets
|
|
129
|
+
|
|
130
|
+
| Platform | Minimum Monthly | Rationale |
|
|
131
|
+
|----------|----------------|-----------|
|
|
132
|
+
| Google Ads | $1,000 | 15+ conv/month minimum for Smart Bidding |
|
|
133
|
+
| Meta Ads | $600-$800 | 50 conv/week/ad set × $CPA |
|
|
134
|
+
| LinkedIn Ads | $3,000 | High CPCs; $10/day minimum × multiple campaigns |
|
|
135
|
+
| TikTok Ads | $300 | $50/day campaign min × creative testing needs |
|
|
136
|
+
| Microsoft Ads | $200-$300 | 20-30% of Google budget |
|
|
137
|
+
|
|
138
|
+
## Cross-Platform Attribution Hierarchy
|
|
139
|
+
|
|
140
|
+
```
|
|
141
|
+
Source of Truth (best → worst):
|
|
142
|
+
1. CRM Data (actual revenue, closed deals, LTV)
|
|
143
|
+
2. MER (total revenue / total ad spend)
|
|
144
|
+
3. Post-Purchase Surveys ("How did you hear about us?")
|
|
145
|
+
4. Google Analytics 4 (cross-channel, multi-touch)
|
|
146
|
+
5. Platform-Reported Data (always overclaims 20-40%)
|
|
147
|
+
|
|
148
|
+
RULE: Never trust platform-reported ROAS alone.
|
|
149
|
+
Always cross-reference with ≥2 other data sources.
|
|
150
|
+
```
|