agileflow 3.4.3 → 4.0.0-alpha.2

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

@@ -1,317 +0,0 @@
----
-description: CPC-first test planning — structured test matrix with budget allocation, CPC thresholds, winner/kill rules, and graduation criteria
-argument-hint: "[BUDGET=100] [DURATION=3d] [VARIANTS=from-generate]"
-compact_context:
-  priority: medium
-  preserve_rules:
-    - "ACTIVE COMMAND: /agileflow:ads:test-plan - CPC-first test planning"
-    - "Generate structured test matrix with decision criteria"
-    - "CPC threshold methodology: $100/3-day test, winner/kill rules"
-    - "Output includes budget allocation, measurement criteria, graduation rules"
-  state_fields:
-    - test_budget
-    - duration
-    - variants
-    - platform
----
-
-# /agileflow:ads:test-plan
-
-Generate a structured A/B testing plan with budget allocation, CPC-first decision criteria, winner/kill rules, and graduation strategy. Based on the CPC-first testing methodology where cheap clicks validate messaging before optimizing for conversions.
-
----
-
-## Quick Reference
-
-```
-/agileflow:ads:test-plan                                               # Interactive (recommended)
-/agileflow:ads:test-plan BUDGET=300 DURATION=5d                        # Custom budget/duration
-/agileflow:ads:test-plan VARIANTS=from-generate                        # Use variants from /ads:generate
-/agileflow:ads:test-plan BUDGET=100 PLATFORM=meta                      # Meta-specific test plan
-```
-
----
-
-## Arguments
-
-| Argument | Values | Default | Description |
-|----------|--------|---------|-------------|
-| BUDGET | Dollar amount | $100 | Total test budget per round |
-| DURATION | Days | 3d | Test duration before decision |
-| VARIANTS | from-generate, manual, or count | from-generate | Source of ad variants to test |
-| PLATFORM | meta, google, linkedin, tiktok | meta | Platform to test on |
-
----
-
-## CPC-First Testing Methodology
-
-### Why CPC First?
-
-```
-Traditional: Optimize for conversions → need 50+ conversions per variant → $$$
-CPC-First:   Optimize for clicks → need 100+ clicks per variant → $
-
-CPC validates MESSAGE RESONANCE at 1/50th the cost.
-Only graduate winners to conversion optimization.
-```
-
-### The 3-Stage Funnel
-
-```
-Stage 1: CPC Test ($100, 3 days)
-  → Does the message resonate? (CTR + CPC)
-  → Kill: CPC > 2x average
-  → Graduate: CPC < average AND CTR > 1%
-
-Stage 2: Landing Page Test ($300, 7 days)
-  → Do clicks convert? (CVR + CPA)
-  → Kill: CVR < 1% after 200+ clicks
-  → Graduate: CPA < 2x target
-
-Stage 3: Scale Test ($1000+, 14 days)
-  → Does it scale profitably? (ROAS + volume)
-  → Kill: ROAS < 1.5x at 2x budget
-  → Graduate: ROAS > 2x → move to always-on
-```
-
----
-
-## Multi-Step Discovery Flow
-
-### STEP 1: Test Context
-
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[
-  {
-    "question": "What stage of testing are you at?",
-    "header": "Test Stage",
-    "multiSelect": false,
-    "options": [
-      {"label": "Stage 1: Message testing (Recommended)", "description": "CPC-first — validate which angles/hooks resonate before spending on conversions"},
-      {"label": "Stage 2: Landing page testing", "description": "I have winning ad copy, now testing landing page variants"},
-      {"label": "Stage 3: Scale testing", "description": "I have winning ads + landing pages, testing budget scaling"},
-      {"label": "Full funnel from scratch", "description": "Generate a complete 3-stage test plan"}
-    ]
-  },
-  {
-    "question": "How many ad variants do you want to test?",
-    "header": "Variants",
-    "multiSelect": false,
-    "options": [
-      {"label": "Use variants from /ads:generate (Recommended)", "description": "Pull variants from the most recent ads-copy generation"},
-      {"label": "5 variants (minimum viable test)", "description": "Test 5 angles with $20 each"},
-      {"label": "10 variants (standard test)", "description": "Test 10 variants with $10 each"},
-      {"label": "20 variants (comprehensive)", "description": "Test 20 variants — requires $200+ budget"}
-    ]
-  }
-]</parameter>
-</invoke>
-```
-
-### STEP 2: Check for Existing Variants
-
-If VARIANTS=from-generate, look for recent ad copy:
-
-```
-docs/08-project/ads-copy/ads-copy-{YYYYMMDD}.md
-```
-
-If found, extract angle names and variant counts. If not found, suggest running `/agileflow:ads:generate` first.
-
-### STEP 3: Generate Test Plan
-
-Based on stage, budget, and variants, generate the test matrix.
-
----
-
-## Output Format
-
-```markdown
-# Ad Testing Plan
-
-**Generated**: {YYYY-MM-DD}
-**Platform**: {platform}
-**Total Budget**: ${total across all stages}
-**Methodology**: CPC-First → CVR → Scale
-
----
-
-## Stage 1: Message Resonance Test (CPC-First)
-
-**Budget**: ${budget}
-**Duration**: {duration}
-**Objective**: Traffic (optimize for link clicks)
-**Bidding**: Lowest cost (no cap)
-
-### Test Matrix
-
-| Variant | Angle | Headline | Daily Budget | Min Clicks | Decision By |
-|---------|-------|----------|-------------|------------|-------------|
-| A | Pain Point | "{headline}" | ${daily} | 33 | {date} |
-| B | Outcome | "{headline}" | ${daily} | 33 | {date} |
-| C | Social Proof | "{headline}" | ${daily} | 33 | {date} |
-| D | Urgency | "{headline}" | ${daily} | 33 | {date} |
-| E | Contrarian | "{headline}" | ${daily} | 33 | {date} |
-
-### Decision Criteria
-
-| Metric | Kill | Hold | Graduate |
-|--------|------|------|----------|
-| **CPC** | > ${2x_avg} | ${avg} - ${2x_avg} | < ${avg} |
-| **CTR** | < 0.5% | 0.5% - 1.0% | > 1.0% |
-| **Impressions** | < 500 (insufficient data) | 500-1000 | > 1000 |
-
-### Decision Rules
-
-1. **Kill immediately** if CPC > 2x average after 50+ clicks
-2. **Hold** if CPC is average but CTR is borderline — extend 2 more days
-3. **Graduate** if CPC < average AND CTR > 1.0% — move to Stage 2
-4. **Minimum data**: Do NOT make decisions with < 100 impressions per variant
-5. **Time minimum**: Run at least 48 hours to capture day-of-week variance
-
-### Expected Outcomes
-
-At $100 budget with ~$1.50 CPC:
-- ~67 total clicks across 5 variants
-- ~13 clicks per variant (marginal — consider $200 for statistical confidence)
-- Expected: 1-2 clear winners, 1-2 kills, 1-2 holds
-
-### Budget Scaling (if budget allows)
-
-| Budget | Variants | Clicks/Variant | Confidence |
-|--------|----------|---------------|------------|
-| $100 | 5 | ~13 | Low (directional only) |
-| $200 | 5 | ~27 | Medium (clear signal) |
-| $300 | 5 | ~40 | High (statistically significant) |
-| $500 | 10 | ~33 | High (wider angle coverage) |
-
----
-
-## Stage 2: Conversion Validation Test
-
-**Budget**: ${stage2_budget}
-**Duration**: 7 days
-**Objective**: Conversions (optimize for leads/purchases)
-**Bidding**: Target CPA (set at 1.5x current CPA)
-
-### Graduates from Stage 1
-{Only variants that passed Stage 1 criteria}
-
-| Variant | Angle | Stage 1 CPC | Stage 1 CTR | Daily Budget |
-|---------|-------|-------------|-------------|-------------|
-| {winner} | {angle} | ${cpc} | {ctr}% | ${daily} |
-
-### Decision Criteria
-
-| Metric | Kill | Hold | Graduate |
-|--------|------|------|----------|
-| **CPA** | > 3x target | 1.5x - 3x target | < 1.5x target |
-| **CVR** | < 1% after 200+ clicks | 1% - 3% | > 3% |
-| **ROAS** (e-commerce) | < 1:1 | 1:1 - 2:1 | > 2:1 |
-
-### The 3x Kill Rule
-
-> **If any campaign's CPA exceeds 3x your target CPA, pause it immediately.**
-> No exceptions. No "let it learn longer." Kill it, iterate the creative, relaunch.
-
----
-
-## Stage 3: Scale Test
-
-**Budget**: ${stage3_budget}
-**Duration**: 14 days
-**Objective**: Profitable scale
-**Bidding**: Target CPA or Target ROAS
-
-### Scaling Rules
-
-1. **20% Rule**: Never increase budget more than 20% per day
-2. **Learning Phase**: After budget changes, wait 3-5 days before judging
-3. **Diminishing Returns**: Track CPA at each budget level:
-
-| Budget Level | Expected CPA | Actual CPA | CPA Delta | Action |
-|-------------|-------------|-----------|-----------|--------|
-| Baseline ${x} | ${target} | — | — | — |
-| +20% ${x*1.2} | ${target*1.1} | — | — | Continue if < 1.5x |
-| +20% ${x*1.44} | ${target*1.2} | — | — | Pause if > 2x |
-| +20% ${x*1.73} | ${target*1.3} | — | — | — |
-
-4. **Exit criteria**: Stop scaling when CPA increase per 20% budget step exceeds 15%
-
----
-
-## Test Calendar
-
-| Week | Stage | Action | Budget | Key Metric |
-|------|-------|--------|--------|-----------|
-| 1 | Setup | Create campaigns, install tracking | $0 | Pixel fires ✓ |
-| 1-2 | Stage 1 | CPC message test | ${s1} | CPC + CTR |
-| 2 | Decision | Kill/Hold/Graduate | — | — |
-| 2-3 | Stage 2 | Conversion test (winners) | ${s2} | CPA + CVR |
-| 3 | Decision | Kill/Graduate | — | — |
-| 4-5 | Stage 3 | Scale test | ${s3} | ROAS at scale |
-| 6 | Evergreen | Move winners to always-on | ${ongoing} | Monitor weekly |
-
----
-
-## Tracking Requirements
-
-Before starting ANY test:
-
-- [ ] Conversion pixel/tag installed and firing
-- [ ] Conversion events defined (lead, purchase, sign-up)
-- [ ] UTM parameters on all ad URLs: `utm_source={platform}&utm_medium=paid&utm_campaign={test_name}&utm_content={variant}`
-- [ ] Google Analytics or equivalent receiving data
-- [ ] Baseline metrics recorded (current CPC, CTR, CPA if available)
-
----
-
-## Post-Test Analysis Template
-
-After each stage, record:
-
-| Variant | Impressions | Clicks | CTR | CPC | Conversions | CVR | CPA | Decision |
-|---------|------------|--------|-----|-----|------------|-----|-----|----------|
-| A | — | — | — | — | — | — | — | Kill/Hold/Graduate |
-```
-
-Save test plan to `docs/08-project/ads-test-plans/test-plan-{YYYYMMDD}.md`.
-
----
-
-## Present Results
-
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "Test plan generated: {N} variants across {stages} stages, ${total_budget} total budget, {duration} timeline. Ready to launch?",
-  "header": "Next steps",
-  "multiSelect": false,
-  "options": [
-    {"label": "Generate ad variants to test (Recommended)", "description": "Run /agileflow:ads:generate to create the ad copy for this test plan"},
-    {"label": "Adjust budget or duration", "description": "Modify the test parameters before finalizing"},
-    {"label": "Review tracking setup", "description": "Verify conversion tracking is properly configured before testing"},
-    {"label": "Export for platform", "description": "Format the test plan as platform-specific campaign structure"}
-  ]
-}]</parameter>
-</invoke>
-```
-
----
-
-<!-- COMPACT_SUMMARY_START -->
-## Compact Summary
-
-**Command**: `/agileflow:ads:test-plan` - CPC-first A/B test planning
-
-**Methodology**: Stage 1 (CPC message test, $100/3d) → Stage 2 (CVR validation, $300/7d) → Stage 3 (Scale test, $1000+/14d)
-
-**Key Rules**: 3x Kill Rule, 20% scaling rule, 48h minimum data, 100+ impressions before decisions
-
-**Output**: Test matrix with decision criteria, scaling rules, and timeline
-
-**Usage**: `/agileflow:ads:test-plan [BUDGET=100] [DURATION=3d] [VARIANTS=from-generate]`
-
-**File**: `docs/08-project/ads-test-plans/test-plan-{YYYYMMDD}.md`
-<!-- COMPACT_SUMMARY_END -->

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

@@ -1,129 +0,0 @@
----
-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 -->