agileflow 3.4.3 → 4.0.0-alpha.10

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

@@ -1,288 +0,0 @@
----
-description: Ads performance tracker — ingest performance CSVs, establish baselines, detect winners and anomalies, output KPI dashboard with trend analysis
-argument-hint: "<performance-data> [PERIOD=7d] [BASELINE=auto]"
-compact_context:
-  priority: medium
-  preserve_rules:
-    - "ACTIVE COMMAND: /agileflow:ads:track - Performance tracking and winner detection"
-    - "Ingest CSV/pasted performance data, establish baselines, detect anomalies"
-    - "Winner detection: statistical significance, cost efficiency, trend direction"
-    - "Delegate to ads-performance-tracker agent for analysis"
-    - "State persisted in docs/08-project/ads-tracking/"
-  state_fields:
-    - period
-    - baseline
-    - campaigns_tracked
-    - winners
-    - anomalies
----
-
-# /agileflow:ads:track
-
-Ingest ad performance data (CSVs or pasted), establish baselines, detect winners and anomalies, and output a KPI dashboard with trend analysis and actionable recommendations.
-
----
-
-## Quick Reference
-
-```
-/agileflow:ads:track <performance-data>                                # Analyze performance data
-/agileflow:ads:track <csv-file> PERIOD=30d                             # 30-day trend analysis
-/agileflow:ads:track <data> BASELINE=last-report                       # Compare against last saved baseline
-/agileflow:ads:track compare <old-csv> <new-csv>                       # Period-over-period comparison
-```
-
----
-
-## Arguments
-
-| Argument | Values | Default | Description |
-|----------|--------|---------|-------------|
-| performance-data | CSV, pasted text, or file path | Required | Performance metrics to analyze |
-| PERIOD | 1d, 7d, 14d, 30d, 90d | 7d | Analysis period |
-| BASELINE | auto, last-report, or specific date | auto | Baseline for comparison |
-| FORMAT | dashboard, csv, both | dashboard | Output format |
-
----
-
-## Data Formats Accepted
-
-### CSV Export (preferred)
-```csv
-Campaign,Ad Set,Ad,Impressions,Clicks,CTR,CPC,Spend,Conversions,CVR,CPA,ROAS,Date
-Brand - Search,Brand Terms,Ad 1,15234,1843,12.1%,$0.45,$829,234,12.7%,$3.54,8.2,2026-02-28
-```
-
-### Pasted Table
-```
-Campaign         | Spend  | Clicks | CPA    | ROAS
-Brand Search     | $829   | 1,843  | $3.54  | 8.2x
-Non-Brand Search | $2,341 | 987    | $15.20 | 2.1x
-Meta Prospecting | $1,560 | 2,104  | $28.40 | 1.4x
-```
-
-### Platform-Specific Exports
-- Google Ads: Campaign/Ad Group/Keyword reports
-- Meta Ads Manager: Campaign/Ad Set/Ad performance export
-- LinkedIn: Campaign Manager CSV export
-- TikTok: Business Center export
-
----
-
-## Analysis Framework
-
-### STEP 1: Parse & Normalize Data
-
-Delegate to the `ads-performance-tracker` agent:
-
-```xml
-<invoke name="Agent">
-<parameter name="description">Analyze ad performance data</parameter>
-<parameter name="prompt">TASK: Analyze ad performance data and generate KPI dashboard.
-
-PERFORMANCE DATA:
-{data}
-
-PERIOD: {period}
-BASELINE: {baseline}
-
-Follow the full analysis framework in your instructions.
-
-OUTPUT: Complete KPI dashboard with winner detection, anomaly alerts, and recommendations.</parameter>
-<parameter name="subagent_type">ads-performance-tracker</parameter>
-</invoke>
-```
-
-### STEP 2: Establish Baselines
-
-If this is the first analysis or BASELINE=auto:
-- Calculate median and mean for each metric across all campaigns
-- Set thresholds at 1 standard deviation from mean
-- Save baseline to `docs/08-project/ads-tracking/baseline-{YYYYMMDD}.json`
-
-If BASELINE=last-report:
-- Load the most recent baseline from `docs/08-project/ads-tracking/`
-- Compare current metrics against saved baseline
-
-### STEP 3: Winner Detection
-
-Apply statistical winner detection:
-
-| Metric | Winner Threshold | Confidence Requirement |
-|--------|-----------------|----------------------|
-| CPC | < 0.7x median CPC | 100+ clicks |
-| CTR | > 1.5x median CTR | 1000+ impressions |
-| CVR | > 1.5x median CVR | 50+ clicks |
-| CPA | < 0.7x median CPA | 20+ conversions |
-| ROAS | > 1.5x median ROAS | $500+ spend |
-
-**Winner Classification:**
-| Class | Criteria | Action |
-|-------|----------|--------|
-| **Strong Winner** | Beats threshold on 3+ metrics | Scale 20%/week |
-| **Emerging Winner** | Beats threshold on 1-2 metrics | Continue monitoring |
-| **Stable Performer** | Within 1 SD of median on all metrics | Maintain |
-| **Underperformer** | Below median on 2+ metrics | Optimize or pause |
-| **Kill** | CPA > 3x target OR ROAS < 0.5x target | Pause immediately |
-
-### STEP 4: Anomaly Detection
-
-Flag anomalies when:
-- **Spend spike**: Daily spend > 2x average (possible budget cap issue)
-- **CTR drop**: CTR drops > 30% day-over-day (ad fatigue, audience saturation)
-- **CPC surge**: CPC increases > 50% week-over-week (competition, quality score)
-- **Conversion drop**: Conversions drop > 40% with stable traffic (tracking break, landing page issue)
-- **ROAS collapse**: ROAS drops below 1:1 (unprofitable, needs immediate action)
-
-### STEP 5: Trend Analysis
-
-For each campaign, calculate:
-- **7-day rolling average** for CPC, CTR, CVR, CPA
-- **Trend direction**: Improving, Stable, Declining
-- **Velocity**: Rate of change (slow, moderate, rapid)
-- **Projected trajectory**: If trend continues, estimated metrics in 7/14/30 days
-
----
-
-## Output Format
-
-```markdown
-# Ads Performance Dashboard
-
-**Generated**: {YYYY-MM-DD}
-**Period**: {start_date} to {end_date} ({N} days)
-**Platforms**: {platforms}
-**Total Spend**: ${total_spend}
-**Baseline**: {baseline_source}
-
----
-
-## Executive Summary
-
-| Metric | Current | Baseline | Change | Trend |
-|--------|---------|----------|--------|-------|
-| Total Spend | ${current} | ${baseline} | {+/-}% | {→/↑/↓} |
-| Avg CPC | ${current} | ${baseline} | {+/-}% | {→/↑/↓} |
-| Avg CTR | {current}% | {baseline}% | {+/-}% | {→/↑/↓} |
-| Total Conversions | {current} | {baseline} | {+/-}% | {→/↑/↓} |
-| Avg CPA | ${current} | ${baseline} | {+/-}% | {→/↑/↓} |
-| Blended ROAS | {current}x | {baseline}x | {+/-}% | {→/↑/↓} |
-
----
-
-## Winner Detection
-
-### Strong Winners (scale these)
-| Campaign | CPC | CTR | CVR | CPA | ROAS | Action |
-|----------|-----|-----|-----|-----|------|--------|
-| {name} | ${cpc} ✅ | {ctr}% ✅ | {cvr}% ✅ | ${cpa} ✅ | {roas}x | Scale 20%/wk |
-
-### Emerging Winners (monitor closely)
-| Campaign | CPC | CTR | CVR | CPA | ROAS | Action |
-|----------|-----|-----|-----|-----|------|--------|
-| {name} | ${cpc} | {ctr}% ✅ | {cvr}% | ${cpa} | {roas}x | Continue 7d |
-
-### Kill List (pause immediately)
-| Campaign | Issue | CPA vs Target | Spend Wasted | Action |
-|----------|-------|--------------|-------------|--------|
-| {name} | CPA 3.2x target | ${cpa} vs ${target} | ${wasted} | **PAUSE NOW** |
-
----
-
-## Anomaly Alerts
-
-| Alert | Campaign | Metric | Expected | Actual | Severity |
-|-------|----------|--------|----------|--------|----------|
-| ⚠️ | {name} | CPC | ${expected} | ${actual} | HIGH |
-| 🔴 | {name} | Conversions | {expected} | {actual} | CRITICAL |
-
----
-
-## Campaign Performance
-
-### {Campaign Name}
-
-| Metric | Value | vs Baseline | Trend (7d) |
-|--------|-------|-------------|------------|
-| Spend | ${spend} | {+/-}% | {→/↑/↓} |
-| Impressions | {impr} | {+/-}% | {→/↑/↓} |
-| Clicks | {clicks} | {+/-}% | {→/↑/↓} |
-| CTR | {ctr}% | {+/-}% | {→/↑/↓} |
-| CPC | ${cpc} | {+/-}% | {→/↑/↓} |
-| Conversions | {conv} | {+/-}% | {→/↑/↓} |
-| CVR | {cvr}% | {+/-}% | {→/↑/↓} |
-| CPA | ${cpa} | {+/-}% | {→/↑/↓} |
-| ROAS | {roas}x | {+/-}% | {→/↑/↓} |
-
-**Classification**: {Strong Winner / Emerging / Stable / Underperformer / Kill}
-
----
-
-## Budget Reallocation Recommendation
-
-| Campaign | Current Budget | Recommended | Change | Reason |
-|----------|---------------|-------------|--------|--------|
-| {winner} | ${current} | ${recommended} | +20% | Strong winner, scale |
-| {loser} | ${current} | ${recommended} | -100% | 3x kill rule |
-
-**Estimated Impact**: Reallocating ${amount} from underperformers to winners = estimated {X}% CPA reduction
-
----
-
-## Recommendations
-
-### Immediate (this session)
-1. **Pause {campaign}** — CPA ${X} exceeds 3x target (${target})
-2. **Scale {campaign}** — Strong winner, increase budget 20%
-
-### This Week
-3. **Refresh creative for {campaign}** — CTR declining 15% WoW (ad fatigue)
-4. **Check tracking for {campaign}** — Conversions dropped 40% with stable clicks
-
-### This Month
-5. **Test new angles** — Run /agileflow:ads:generate + /agileflow:ads:test-plan
-6. **Platform diversification** — {platform} ROAS declining, test {other_platform}
-```
-
-Save dashboard to `docs/08-project/ads-tracking/dashboard-{YYYYMMDD}.md`.
-Save baseline to `docs/08-project/ads-tracking/baseline-{YYYYMMDD}.json`.
-
----
-
-## Present Results
-
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "Performance dashboard generated. {winners} winners, {kills} to kill, {anomalies} anomalies. Total spend: ${spend}, blended ROAS: {roas}x.",
-  "header": "Next steps",
-  "multiSelect": false,
-  "options": [
-    {"label": "Pause kill-list campaigns now (Recommended)", "description": "Stop wasting ${wasted_amount}/mo on {kill_count} underperforming campaigns"},
-    {"label": "Generate replacement ad copy", "description": "Run /agileflow:ads:generate for fatigued campaigns"},
-    {"label": "Create test plan for winners", "description": "Run /agileflow:ads:test-plan to scale winning angles"},
-    {"label": "Run full ads audit", "description": "Run /agileflow:ads:audit for comprehensive 190-check analysis"}
-  ]
-}]</parameter>
-</invoke>
-```
-
----
-
-<!-- COMPACT_SUMMARY_START -->
-## Compact Summary
-
-**Command**: `/agileflow:ads:track` - Performance tracking with winner detection
-
-**Input**: Performance CSV/data from ad platforms
-
-**Analysis**: Baselines, winner detection (5 classes), anomaly alerts, trend analysis, budget reallocation
-
-**Key Rules**: 3x Kill Rule for CPA, 20% max scaling per week, 100+ clicks for CPC confidence
-
-**Output**: KPI dashboard + baseline JSON + recommendations
-
-**Usage**: `/agileflow:ads:track <data> [PERIOD=7d] [BASELINE=auto]`
-
-**Files**: `docs/08-project/ads-tracking/dashboard-{YYYYMMDD}.md`, `baseline-{YYYYMMDD}.json`
-<!-- COMPACT_SUMMARY_END -->

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

@@ -1,124 +0,0 @@
----
-description: YouTube Ads audit for video campaign types, ad formats, targeting strategy, bidding optimization, and creative effectiveness
-argument-hint: "<account-data>"
-compact_context:
-  priority: medium
-  preserve_rules:
-    - "ACTIVE COMMAND: /agileflow:ads:youtube - YouTube Ads audit"
-    - "Inline command - check video formats, campaign types, targeting"
-    - "YouTube runs through Google Ads platform"
-  state_fields:
-    - youtube_score
----
-
-# /agileflow:ads:youtube
-
-Run an inline audit on YouTube advertising campaigns (managed through Google Ads) focusing on video-specific optimization.
-
----
-
-## Quick Reference
-
-```
-/agileflow:ads:youtube <account-data>                 # YouTube Ads audit
-```
-
----
-
-## The 8 Checks
-
-| # | Check | Severity | Pass Criteria |
-|---|-------|----------|---------------|
-| YT-1 | Campaign type alignment | HIGH | Correct campaign type for objective |
-| YT-2 | Video format coverage | HIGH | Multiple formats tested (skippable, bumper, shorts) |
-| YT-3 | Targeting strategy | HIGH | Audience targeting refined beyond demographics |
-| YT-4 | Bidding strategy | HIGH | CPV/CPM/tCPA based on objective |
-| YT-5 | Creative hook in 5 seconds | CRITICAL | First 5 seconds grab attention (before skip) |
-| YT-6 | Companion banner | MEDIUM | Companion banner uploaded for desktop |
-| YT-7 | Frequency capping | HIGH | Frequency cap set (3-5 per week recommended) |
-| YT-8 | Conversion tracking | CRITICAL | YouTube conversions tracked in Google Ads |
-
----
-
-## Process
-
-### STEP 1: Apply All 8 Checks
-
-Review the account data against each check. For YouTube specifically:
-
-**Campaign types**:
-| Type | Best For | Format |
-|------|---------|--------|
-| Video Reach | Awareness | Bumper (6s) + In-stream |
-| Video Views | Consideration | Skippable in-stream + in-feed |
-| Video Action | Conversions | Skippable in-stream with CTA |
-| Shorts Ads | Awareness + young demo | Vertical 60s max |
-| Demand Gen | Full-funnel | YouTube + Discover + Gmail |
-
-**Creative best practices**:
-- First 5 seconds: Brand + hook (many viewers skip at 5s)
-- CTA overlay throughout (not just at end)
-- Mobile-first: 70%+ YouTube watching is mobile
-- Captions/subtitles: Many watch without sound
-- 15-30 seconds optimal for action campaigns
-- Shorts: Vertical 9:16, authentic style
-
-**Targeting options**:
-- Custom Intent: Based on Google search behavior
-- Affinity: Interest-based broad reach
-- In-Market: Active purchase intent
-- Remarketing: Website visitors, video viewers
-- Customer Match: Upload customer lists
-- Topic/placement: Specific channels/videos
-
-### STEP 2: Score
-
-```
-YouTube Score = 100 - sum(severity_deductions)
-```
-
-Deductions: CRITICAL (-15), HIGH (-8), MEDIUM (-4), LOW (-2)
-
-### STEP 3: Output
-
-```markdown
-## YouTube Ads Audit
-
-**YouTube Score**: {X}/100
-
-| Check | Status | Notes |
-|-------|--------|-------|
-| YT-1 Campaign types | PASS/FAIL | {types in use} |
-| YT-2 Video formats | PASS/FAIL | {formats tested} |
-| YT-3 Targeting | PASS/FAIL | {targeting methods} |
-| YT-4 Bidding | PASS/FAIL | {strategies used} |
-| YT-5 5-second hook | PASS/FAIL | {creative analysis} |
-| YT-6 Companion banner | PASS/FAIL | {banner status} |
-| YT-7 Frequency cap | PASS/FAIL | {cap settings} |
-| YT-8 Conversion tracking | PASS/FAIL | {tracking status} |
-
-### Key Recommendations
-1. {Top priority fix}
-2. {Second priority}
-3. {Third priority}
-
-### YouTube-Specific Tips
-- Video Action campaigns drive most conversions (skippable in-stream with CTA)
-- Custom Intent audiences (based on search) are YouTube's secret weapon
-- Always create Shorts versions of successful long-form ads
-- Test bumper ads (6s) for remarketing - cheap and high frequency
-```
-
----
-
-<!-- COMPACT_SUMMARY_START -->
-## Compact Summary
-
-**Command**: `/agileflow:ads:youtube` - YouTube Ads audit
-
-**Checks**: 8 (inline, no separate agent)
-
-**Key**: 5-second hook, campaign types, Custom Intent targeting, frequency caps
-
-**Quick Usage**: `/agileflow:ads:youtube <account-data>`
-<!-- COMPACT_SUMMARY_END -->

package/src/core/commands/ads.md

@@ -1,140 +0,0 @@
----
-description: Paid advertising audit & planning toolkit - multi-platform account audits, campaign planning, budget optimization, and competitive intelligence
-argument-hint: "[subcommand] [account-data]"
-compact_context:
-  priority: medium
-  preserve_rules:
-    - "ACTIVE COMMAND: /agileflow:ads - Paid advertising router"
-    - "Route to the appropriate sub-command based on user intent"
-    - "If no sub-command specified, show the quick reference guide"
-  state_fields:
-    - subcommand
-    - platforms
----
-
-# /agileflow:ads
-
-Paid advertising audit & planning toolkit for multi-platform account optimization. Routes to specialized sub-commands.
-
----
-
-## Quick Reference
-
-```
-/agileflow:ads:audit <account-data>                    # Full multi-platform audit (6 parallel analyzers)
-/agileflow:ads:health <data+url>                        # Unified marketing health scorecard (ads+SEO+landing)
-/agileflow:ads:generate <product-description>           # Bulk ad copy generation (40+ variants)
-/agileflow:ads:test-plan                                # CPC-first test planning with decision criteria
-/agileflow:ads:track <performance-csv>                  # Performance tracking with winner detection
-/agileflow:ads:plan                                     # Campaign planning with industry templates
-/agileflow:ads:google <account-data>                    # Google Ads deep-dive (74 checks)
-/agileflow:ads:meta <account-data>                      # Meta/Facebook audit (46 checks)
-/agileflow:ads:creative <account-data>                  # Cross-platform creative review (21 checks)
-/agileflow:ads:budget <account-data>                    # Budget allocation & bidding strategy
-/agileflow:ads:landing <URL>                            # Landing page optimization
-/agileflow:ads:competitor <industry>                    # Competitive intelligence
-/agileflow:ads:linkedin <account-data>                  # LinkedIn audit (9 checks)
-/agileflow:ads:tiktok <account-data>                    # TikTok audit (8 checks)
-/agileflow:ads:microsoft <account-data>                 # Microsoft Ads audit (7 checks)
-/agileflow:ads:youtube <account-data>                   # YouTube audit
-```
-
----
-
-## Sub-Commands
-
-| Command | Purpose | When to Use |
-|---------|---------|-------------|
-| **audit** | Full multi-platform audit with Ads Health Score | Starting point for any account |
-| **health** | Unified marketing scorecard (ads+SEO+landing+tracking) | Executive overview of full marketing funnel |
-| **generate** | Bulk ad copy generation (40+ variants) | Creating new ad creative at scale |
-| **test-plan** | CPC-first test planning with decision criteria | Structuring A/B tests with winner/kill rules |
-| **track** | Performance tracking with winner detection | Ongoing campaign monitoring and optimization |
-| **plan** | Campaign planning with industry templates | New campaigns or restructuring |
-| **google** | Google Ads deep-dive (74 checks) | Google-specific optimization |
-| **meta** | Meta/Facebook audit (46 checks) | Meta-specific optimization |
-| **creative** | Cross-platform creative quality | Creative strategy improvement |
-| **budget** | Budget & bidding strategy | Spend optimization |
-| **landing** | Landing page optimization | Conversion rate improvement |
-| **competitor** | Competitive intelligence | Market positioning |
-| **linkedin** | LinkedIn Ads audit | LinkedIn-specific optimization |
-| **tiktok** | TikTok Ads audit | TikTok-specific optimization |
-| **microsoft** | Microsoft Ads audit | Microsoft-specific optimization |
-| **youtube** | YouTube Ads audit | Video campaign optimization |
-
----
-
-## Account Data Formats
-
-The ads commands accept account data in several formats:
-
-1. **Pasted text** - Copy/paste from ad platform exports (CSV, tables)
-2. **File path** - Point to exported CSV/JSON files
-3. **Structured description** - Describe your account setup in plain text
-4. **Screenshots** - Describe what you see in platform dashboards
-
-For best results, include:
-- Campaign names, types, and objectives
-- Budget and spend data
-- Conversion tracking setup
-- Targeting settings
-- Ad creative details
-- Performance metrics (CPA, ROAS, CTR, CVR)
-
----
-
-## Routing Logic
-
-If the user provides data without a sub-command, determine intent:
-
-1. **"audit my ads"** -> `/agileflow:ads:audit`
-2. **"health check" / "marketing score" / "full scorecard"** -> `/agileflow:ads:health`
-3. **"generate ad copy" / "write ads" / "bulk ads" / "ad variants"** -> `/agileflow:ads:generate`
-4. **"test plan" / "A/B test" / "split test" / "CPC test"** -> `/agileflow:ads:test-plan`
-5. **"track performance" / "dashboard" / "winners" / "KPIs"** -> `/agileflow:ads:track`
-6. **"plan a campaign"** -> `/agileflow:ads:plan`
-7. **"check my Google Ads"** -> `/agileflow:ads:google`
-8. **"Meta" / "Facebook ads"** -> `/agileflow:ads:meta`
-9. **"creative review"** -> `/agileflow:ads:creative`
-10. **"budget" / "spend" / "bidding"** -> `/agileflow:ads:budget`
-11. **"landing page"** -> `/agileflow:ads:landing`
-12. **"competitor" / "competitive"** -> `/agileflow:ads:competitor`
-13. **"LinkedIn"** -> `/agileflow:ads:linkedin`
-14. **"TikTok"** -> `/agileflow:ads:tiktok`
-15. **"Microsoft" / "Bing"** -> `/agileflow:ads:microsoft`
-16. **"YouTube" / "video ads"** -> `/agileflow:ads:youtube`
-17. **Unclear** -> Show the quick reference and ask which analysis they want
-
----
-
-## If No Sub-Command Specified
-
-Show the quick reference table above and ask:
-
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "Which advertising analysis would you like to run?",
-  "header": "Ads Analysis",
-  "multiSelect": false,
-  "options": [
-    {"label": "Full multi-platform audit (Recommended)", "description": "Comprehensive 6-analyzer audit with Ads Health Score 0-100"},
-    {"label": "Marketing health scorecard", "description": "Unified score across ads + SEO + landing pages + tracking"},
-    {"label": "Generate ad copy (40+ variants)", "description": "Bulk ad copy from product description with ICP angles + platform CSV"},
-    {"label": "Create A/B test plan", "description": "CPC-first testing with budget allocation and winner/kill rules"}
-  ]
-}]</parameter>
-</invoke>
-```
-
----
-
-<!-- COMPACT_SUMMARY_START -->
-## Compact Summary
-
-**Command**: `/agileflow:ads` - Paid advertising audit & planning router
-
-**Sub-commands**: audit, health, generate, test-plan, track, plan, google, meta, creative, budget, landing, competitor, linkedin, tiktok, microsoft, youtube
-
-**Quick start**: `/agileflow:ads:audit <account-data>` for full analysis
-<!-- COMPACT_SUMMARY_END -->