agileflow 3.3.0 → 3.4.0

package/src/core/commands/ads/meta.md

@@ -0,0 +1,91 @@
+---
+description: Meta/Facebook Ads deep-dive audit with 46 deterministic checks across Pixel/CAPI tracking, creative strategy, account structure, and audience targeting
+argument-hint: "<account-data>"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:ads:meta - Meta Ads deep-dive"
+    - "Delegate to ads-audit-meta agent for 46 checks"
+    - "Quality gates: Pixel required, domain verified, learning phase, Special Ad Categories"
+  state_fields:
+    - meta_score
+---
+
+# /agileflow:ads:meta
+
+Run a deep-dive audit on a Meta/Facebook Ads account using the `ads-audit-meta` agent with 46 deterministic checks across 4 categories.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:ads:meta <account-data>                    # Full Meta Ads audit
+```
+
+---
+
+## Process
+
+### STEP 1: Validate Input
+
+If no account data provided, ask the user to paste or describe their Meta Ads setup including:
+- Pixel and CAPI setup
+- Campaign objectives and structure
+- Audience targeting (LAL, custom, interest)
+- Creative assets and formats
+- Budget and performance metrics
+
+### STEP 2: Deploy Meta Ads Analyzer
+
+```xml
+<invoke name="Task">
+<parameter name="description">Meta Ads deep-dive audit</parameter>
+<parameter name="prompt">TASK: Run a comprehensive Meta/Facebook Ads audit.
+
+ACCOUNT DATA:
+{account_data}
+
+Apply ALL 46 checks across 4 weighted categories:
+- Pixel & CAPI Tracking (30%) - 12 checks
+- Creative Strategy (25%) - 14 checks
+- Account Structure (25%) - 10 checks
+- Audience Targeting (20%) - 10 checks
+
+Enforce ALL quality gates:
+1. Pixel installed and firing
+2. Domain verified
+3. Learning phase healthy (50 conversions/week)
+4. Special Ad Categories declared
+
+OUTPUT: Full findings with Meta Ads Score X/100</parameter>
+<parameter name="subagent_type">ads-audit-meta</parameter>
+</invoke>
+```
+
+### STEP 3: Present Results
+
+Show the Meta Ads Score and key findings, then offer next steps.
+
+---
+
+## 46 Checks Overview
+
+| Category | Weight | Checks | Focus |
+|----------|--------|--------|-------|
+| Pixel & CAPI Tracking | 30% | 12 | Pixel, CAPI, EMQ, AEM, dedup, privacy |
+| Creative Strategy | 25% | 14 | Diversity, video, formats, refresh, DCO |
+| Account Structure | 25% | 10 | CBO, objectives, consolidation, learning phase |
+| Audience Targeting | 20% | 10 | LAL, custom, overlap, retargeting, exclusions |
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:ads:meta` - Meta/Facebook Ads deep-dive audit
+
+**Agent**: `ads-audit-meta` (46 checks, 4 categories)
+
+**Quick Usage**: `/agileflow:ads:meta <account-data>`
+<!-- COMPACT_SUMMARY_END -->

package/src/core/commands/ads/microsoft.md

@@ -0,0 +1,115 @@
+---
+description: Microsoft Ads audit with 7 checks for search partner management, UET tag, LinkedIn targeting, and import quality from Google Ads
+argument-hint: "<account-data>"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:ads:microsoft - Microsoft Ads audit"
+    - "Inline command - 7 checks, no separate agent needed"
+    - "Often imported from Google - check import quality"
+  state_fields:
+    - microsoft_score
+---
+
+# /agileflow:ads:microsoft
+
+Run an inline audit on a Microsoft Ads (formerly Bing Ads) account with 7 focused checks. Microsoft Ads often runs as a Google import - verify it's optimized for the platform.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:ads:microsoft <account-data>               # Microsoft Ads audit
+```
+
+---
+
+## The 7 Checks
+
+| # | Check | Severity | Pass Criteria |
+|---|-------|----------|---------------|
+| MS-1 | UET tag installed | CRITICAL | Universal Event Tracking tag on all pages |
+| MS-2 | Search partner performance | HIGH | Syndication partners monitored, disabled if poor |
+| MS-3 | Import quality from Google | HIGH | No broken bid strategies or unsupported features |
+| MS-4 | Bid adjustments set | MEDIUM | Microsoft-specific bids (not just Google copy) |
+| MS-5 | LinkedIn profile targeting | HIGH | LinkedIn demographics used for B2B targeting |
+| MS-6 | Audience ads opt-in reviewed | MEDIUM | Microsoft Audience Network reviewed for performance |
+| MS-7 | Conversion goals defined | HIGH | Microsoft-native conversion tracking active |
+
+---
+
+## Process
+
+### STEP 1: Apply All 7 Checks
+
+Review the account data against each check. For Microsoft Ads specifically:
+
+**Import quality matters**:
+- Google imports often bring unsupported features
+- Automated bid strategies may not transfer correctly
+- Negative keyword lists may not sync
+- Review every imported campaign for Microsoft compatibility
+
+**LinkedIn targeting advantage**:
+- Microsoft Ads uniquely offers LinkedIn profile targeting
+- Target by company, industry, job function
+- Powerful for B2B campaigns not using LinkedIn Ads directly
+- Can be layered on top of keyword targeting
+
+**Search partners**:
+- Microsoft Audience Network reaches Yahoo, AOL, DuckDuckGo
+- Performance varies significantly by partner
+- Review partner performance monthly
+- Disable underperforming partners individually
+
+### STEP 2: Score
+
+```
+Microsoft Score = 100 - sum(severity_deductions)
+```
+
+Deductions: CRITICAL (-15), HIGH (-8), MEDIUM (-4), LOW (-2)
+
+### STEP 3: Output
+
+```markdown
+## Microsoft Ads Audit
+
+**Microsoft Score**: {X}/100
+
+| Check | Status | Notes |
+|-------|--------|-------|
+| MS-1 UET tag | PASS/FAIL | {details} |
+| MS-2 Search partners | PASS/FAIL | {partner performance} |
+| MS-3 Import quality | PASS/FAIL | {import issues found} |
+| MS-4 Bid adjustments | PASS/FAIL | {Microsoft-specific bids} |
+| MS-5 LinkedIn targeting | PASS/FAIL | {targeting usage} |
+| MS-6 Audience Network | PASS/FAIL | {opt-in status} |
+| MS-7 Conversion goals | PASS/FAIL | {goals defined} |
+
+### Key Recommendations
+1. {Top priority fix}
+2. {Second priority}
+3. {Third priority}
+
+### Microsoft-Specific Tips
+- LinkedIn profile targeting is Microsoft's unique advantage
+- Don't just "set and forget" Google imports - optimize for Microsoft
+- Search partner performance varies - monitor and exclude poor performers
+- Microsoft audience skews older and higher income than Google
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:ads:microsoft` - Microsoft Ads audit
+
+**Checks**: 7 (inline, no separate agent)
+
+**Key**: UET tag, import quality, LinkedIn targeting, search partners
+
+**Quick Usage**: `/agileflow:ads:microsoft <account-data>`
+<!-- COMPACT_SUMMARY_END -->

package/src/core/commands/ads/plan.md

@@ -0,0 +1,321 @@
+---
+description: Campaign planning with industry-specific templates, multi-step discovery, budget allocation, and platform recommendations
+argument-hint: "[INDUSTRY=auto] [BUDGET=monthly] [GOAL=conversions]"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:ads:plan - Campaign planning"
+    - "Use AskUserQuestion for multi-step discovery flow"
+    - "Apply industry-specific templates and platform recommendations"
+    - "Include budget allocation matrix and timeline"
+  state_fields:
+    - industry
+    - budget
+    - goal
+    - platforms
+---
+
+# /agileflow:ads:plan
+
+Generate a comprehensive paid advertising campaign plan with industry-specific templates, platform recommendations, budget allocation, and timeline.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:ads:plan                                     # Interactive planning (recommended)
+/agileflow:ads:plan INDUSTRY=saas BUDGET=5000           # Direct with parameters
+/agileflow:ads:plan INDUSTRY=ecommerce GOAL=roas        # E-commerce with ROAS goal
+```
+
+---
+
+## Multi-Step Discovery Flow
+
+### STEP 1: Business Discovery
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[
+  {
+    "question": "What type of business are you advertising for?",
+    "header": "Industry",
+    "multiSelect": false,
+    "options": [
+      {"label": "SaaS / Software", "description": "Software product, free trials, demos, subscriptions"},
+      {"label": "E-commerce / Retail", "description": "Physical or digital products, online store"},
+      {"label": "Local Services", "description": "Service-area business, appointments, phone calls"},
+      {"label": "B2B / Enterprise", "description": "Long sales cycle, demos, enterprise deals"}
+    ]
+  },
+  {
+    "question": "What's your primary advertising goal?",
+    "header": "Goal",
+    "multiSelect": false,
+    "options": [
+      {"label": "Lead generation (Recommended for most)", "description": "Collect leads, demos, sign-ups"},
+      {"label": "Direct sales / ROAS", "description": "Drive purchases with measurable return"},
+      {"label": "Brand awareness", "description": "Reach and frequency for brand building"},
+      {"label": "App installs", "description": "Drive mobile app downloads"}
+    ]
+  },
+  {
+    "question": "What's your monthly advertising budget?",
+    "header": "Budget",
+    "multiSelect": false,
+    "options": [
+      {"label": "$1,000 - $5,000", "description": "Starter budget - focus on 1-2 platforms"},
+      {"label": "$5,000 - $20,000", "description": "Growth budget - 2-3 platforms recommended"},
+      {"label": "$20,000 - $100,000", "description": "Scale budget - multi-platform strategy"},
+      {"label": "$100,000+", "description": "Enterprise budget - full platform coverage"}
+    ]
+  }
+]</parameter>
+</invoke>
+```
+
+### STEP 2: Platform Selection
+
+Based on industry and budget, recommend platforms:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Based on {industry} with ${budget}/mo budget, which platforms do you want to include?",
+  "header": "Platforms",
+  "multiSelect": true,
+  "options": [
+    {"label": "Google Ads (Recommended)", "description": "Search intent capture - best for {reason}"},
+    {"label": "Meta Ads (Recommended)", "description": "Prospecting and retargeting - {audience_size}"},
+    {"label": "LinkedIn Ads", "description": "B2B targeting - min $50/day recommended"},
+    {"label": "TikTok Ads", "description": "Younger demographics - min $50/day campaign"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+### STEP 3: Generate Campaign Plan
+
+Based on discoveries, generate the full plan.
+
+---
+
+## Industry Templates
+
+### SaaS / Software
+```markdown
+## Campaign Structure: SaaS
+
+### Google Ads (40% of budget)
+- **Search - Brand**: Protect brand terms, tCPA bidding
+- **Search - Non-Brand (High Intent)**: "buy", "pricing", "vs", "alternative" keywords
+- **Search - Non-Brand (Research)**: "how to", "best", "what is" keywords
+- **Performance Max**: Product feed + audience signals
+
+### Meta Ads (35% of budget)
+- **Prospecting - Lookalike**: LAL from trial signups/demos
+- **Prospecting - Interest**: Job titles, competitor interests
+- **Retargeting - Website**: 30/60/90 day windows
+- **Retargeting - Engagement**: Video viewers, page engagers
+
+### LinkedIn Ads (25% of budget)
+- **Sponsored Content**: Thought leadership, case studies
+- **Lead Gen Forms**: Direct lead capture (no landing page)
+- **Retargeting**: Website visitors, engagement audiences
+
+### KPIs
+| Metric | Target |
+|--------|--------|
+| CPL (MQL) | $50-150 |
+| CPL (SQL) | $150-400 |
+| Trial-to-Paid | 15-25% |
+| ROAS (12mo LTV) | 5:1+ |
+```
+
+### E-commerce / Retail
+```markdown
+## Campaign Structure: E-commerce
+
+### Google Ads (50% of budget)
+- **Shopping / PMax**: Product feed campaigns
+- **Search - Brand**: Brand protection
+- **Search - Non-Brand**: Product + category keywords
+- **Dynamic Search Ads**: Keyword gap coverage
+
+### Meta Ads (40% of budget)
+- **Advantage+ Shopping**: Automated catalog sales
+- **Prospecting - Lookalike**: LAL from purchasers
+- **Retargeting - DPA**: Dynamic product ads
+- **Retargeting - Cart Abandonment**: 7/14/30 day
+
+### TikTok (10% of budget)
+- **Spark Ads**: Boost organic UGC
+- **Collection Ads**: Catalog-driven
+
+### KPIs
+| Metric | Target |
+|--------|--------|
+| ROAS | 3:1 - 5:1 |
+| CPA (Purchase) | < $30-80 |
+| AOV:CPA | > 3:1 |
+| Cart Abandonment Recovery | 10-15% |
+```
+
+### Local Services
+```markdown
+## Campaign Structure: Local Services
+
+### Google Ads (60% of budget)
+- **Search - Service**: "[service] near me", "[service] [city]"
+- **Search - Brand**: Brand protection
+- **Local Service Ads**: Google Guaranteed (if eligible)
+- **Call-Only Campaigns**: Direct phone calls
+
+### Meta Ads (30% of budget)
+- **Prospecting - Radius**: 15-30 mile radius targeting
+- **Retargeting - Website**: Visitors who didn't convert
+- **Lead Gen Forms**: Quick contact form
+
+### Microsoft Ads (10% of budget)
+- **Search Import**: Import Google campaigns
+
+### KPIs
+| Metric | Target |
+|--------|--------|
+| CPL | $15-50 |
+| Cost Per Call | $20-60 |
+| Booking Rate | 25-40% |
+| Customer LTV:CPA | > 5:1 |
+```
+
+### B2B / Enterprise
+```markdown
+## Campaign Structure: B2B
+
+### LinkedIn Ads (40% of budget)
+- **Sponsored Content**: Whitepapers, case studies
+- **Lead Gen Forms**: Gated content
+- **ABM Campaigns**: Matched audiences for target accounts
+- **Retargeting**: Website visitors
+
+### Google Ads (35% of budget)
+- **Search - High Intent**: "enterprise [solution]", "[category] software"
+- **Search - Competitor**: "[competitor] alternative"
+- **Display - Remarketing**: Content downloaders
+- **YouTube**: Product demos
+
+### Meta Ads (25% of budget)
+- **Prospecting - LAL**: From CRM customer list
+- **Retargeting**: Website + LinkedIn crossover
+- **Content Distribution**: Webinar/event promotion
+
+### KPIs
+| Metric | Target |
+|--------|--------|
+| CPL (MQL) | $100-300 |
+| CPL (SQL) | $300-1000 |
+| Pipeline Contribution | 30-50% |
+| Deal Close Rate | 10-20% |
+```
+
+---
+
+## Budget Allocation Matrix
+
+| Monthly Budget | Platforms | Allocation |
+|---------------|-----------|------------|
+| $1K-5K | 1-2 | 70% primary / 30% secondary |
+| $5K-20K | 2-3 | 50% / 30% / 20% |
+| $20K-100K | 3-4 | 40% / 25% / 20% / 15% |
+| $100K+ | 4-6 | Proportional to ROAS by platform |
+
+Within each platform:
+- **70%** Proven campaigns (known performers)
+- **20%** Testing (new audiences, creatives, keywords)
+- **10%** Experimental (new platforms, formats, strategies)
+
+---
+
+## Output Format
+
+```markdown
+# Paid Advertising Campaign Plan
+
+**Industry**: {type}
+**Monthly Budget**: ${amount}
+**Goal**: {primary goal}
+**Platforms**: {selected platforms}
+**Timeline**: {3/6/12 month}
+
+---
+
+## Executive Summary
+{2-3 sentences on the strategy}
+
+---
+
+## Platform Breakdown
+
+### {Platform 1} ({X}% - ${amount}/mo)
+{Campaign structure from template}
+
+### {Platform 2} ({X}% - ${amount}/mo)
+{Campaign structure from template}
+
+---
+
+## Launch Timeline
+
+### Week 1-2: Foundation
+- [ ] Set up conversion tracking on all platforms
+- [ ] Create audiences and upload customer lists
+- [ ] Build campaign structures (no ads yet)
+
+### Week 3-4: Launch
+- [ ] Launch brand campaigns first
+- [ ] Activate retargeting campaigns
+- [ ] Begin prospecting with proven audiences
+
+### Month 2: Optimize
+- [ ] Review search terms, add negatives
+- [ ] Identify winning/losing creatives
+- [ ] Adjust bids based on early data
+
+### Month 3: Scale
+- [ ] Scale winners (20% budget increase/week max)
+- [ ] Pause underperformers (3x Kill Rule)
+- [ ] Test new audiences and creatives
+
+---
+
+## Measurement Framework
+
+| KPI | Target | Measurement |
+|-----|--------|------------|
+| {kpi} | {target} | {how to measure} |
+
+---
+
+## Budget Scaling Rules
+
+1. Only scale campaigns that have exited learning phase
+2. Maximum 20% budget increase per week
+3. 3x Kill Rule: Pause campaigns with CPA > 3x target
+4. Minimum 2 weeks of data before major changes
+5. Never scale and test simultaneously on same campaign
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:ads:plan` - Campaign planning with industry templates
+
+**Input**: Industry + budget + goal (interactive discovery or parameters)
+
+**Output**: Full campaign plan with platform allocation, structure, timeline, and KPIs
+
+**Usage**: `/agileflow:ads:plan [INDUSTRY=auto] [BUDGET=monthly] [GOAL=conversions]`
+<!-- COMPACT_SUMMARY_END -->

package/src/core/commands/ads/tiktok.md

@@ -0,0 +1,129 @@
+---
+description: TikTok Ads audit with 8 checks for learning phase management, budget minimums, creative safe zones, and platform-specific optimization
+argument-hint: "<account-data>"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:ads:tiktok - TikTok Ads audit"
+    - "Inline command - 8 checks, no separate agent needed"
+    - "Min budget: $50/day campaign, $20/day ad group"
+    - "Learning phase: 50 conversions in 7 days"
+  state_fields:
+    - tiktok_score
+---
+
+# /agileflow:ads:tiktok
+
+Run an inline audit on a TikTok Ads account with 8 focused checks. TikTok requires creative-first strategy and strict learning phase management.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:ads:tiktok <account-data>                  # TikTok Ads audit
+```
+
+---
+
+## The 8 Checks
+
+| # | Check | Severity | Pass Criteria |
+|---|-------|----------|---------------|
+| TT-1 | TikTok Pixel installed | CRITICAL | Pixel on all pages, Events API preferred |
+| TT-2 | Learning phase management | CRITICAL | 50 conversions in 7 days per ad group |
+| TT-3 | Budget meets minimum | CRITICAL | $50/day campaign, $20/day ad group |
+| TT-4 | Creative safe zones | HIGH | Key content within center 720x900px |
+| TT-5 | Video-first creatives | HIGH | All ads are video (no static images) |
+| TT-6 | UGC/authentic style | HIGH | Native-feeling content (not polished ads) |
+| TT-7 | Sound-on design | MEDIUM | Audio is integral, not optional |
+| TT-8 | Creative refresh < 14 days | HIGH | New creatives every 1-2 weeks |
+
+---
+
+## Process
+
+### STEP 1: Apply All 8 Checks
+
+Review the account data against each check. For TikTok specifically:
+
+**Learning phase is critical**:
+- TikTok needs 50 conversions in 7 days per ad group to exit learning
+- At $20/day minimum: $140/week = 50 conversions needed
+- That requires CPA < $2.80 - often unrealistic
+- **Solution**: Optimize for upper-funnel events (View Content, Add to Cart) until volume builds
+
+**Creative safe zones**:
+```
++---------------------------+
+|      Username (130px)     |
+|                           |
+|    +----------------+     |
+|    |                |     |
+|    |   SAFE ZONE    |     |
+|    |  720 x 900px   |     |
+|    |                |     |
+|    +----------------+     |
+|                     |btns |
+|   CTA + Nav (170px) |     |
++---------------------------+
+```
+
+**Creative best practices**:
+- First 3 seconds: Hook with pattern interrupt
+- 15-30 second sweet spot for most objectives
+- Vertical 9:16 only (no landscape)
+- Captions/text overlay for sound-off viewing
+- Trend-aware content outperforms polished ads
+
+### STEP 2: Score
+
+```
+TikTok Score = 100 - sum(severity_deductions)
+```
+
+Deductions: CRITICAL (-15), HIGH (-8), MEDIUM (-4), LOW (-2)
+
+### STEP 3: Output
+
+```markdown
+## TikTok Ads Audit
+
+**TikTok Score**: {X}/100
+
+| Check | Status | Notes |
+|-------|--------|-------|
+| TT-1 Pixel/Events API | PASS/FAIL | {details} |
+| TT-2 Learning phase | PASS/FAIL | {conversion volume} |
+| TT-3 Budget minimum | PASS/FAIL | ${daily}/day |
+| TT-4 Safe zones | PASS/FAIL | {creative analysis} |
+| TT-5 Video-first | PASS/FAIL | {format types} |
+| TT-6 UGC style | PASS/FAIL | {creative style} |
+| TT-7 Sound-on | PASS/FAIL | {audio strategy} |
+| TT-8 Creative refresh | PASS/FAIL | {last refresh date} |
+
+### Key Recommendations
+1. {Top priority fix}
+2. {Second priority}
+3. {Third priority}
+
+### TikTok-Specific Tips
+- "Don't make ads, make TikToks" - native > polished
+- Spark Ads (boosting organic) often outperform traditional ads
+- Creative fatigue hits faster on TikTok (7-14 days vs 30 on Meta)
+- Use Creative Center for trending sounds and formats
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:ads:tiktok` - TikTok Ads audit
+
+**Checks**: 8 (inline, no separate agent)
+
+**Key**: $50/day min, 50 conv/7 days learning, video-only, UGC style
+
+**Quick Usage**: `/agileflow:ads:tiktok <account-data>`
+<!-- COMPACT_SUMMARY_END -->