agileflow 3.3.0 → 3.4.1

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

@@ -0,0 +1,97 @@
+---
+description: Budget allocation and bidding strategy optimizer with industry benchmarks, platform minimums, scaling rules, and reallocation recommendations
+argument-hint: "<account-data>"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:ads:budget - Budget & bidding strategy"
+    - "Delegate to ads-audit-budget agent for 24 checks"
+    - "Include platform minimums and scaling rules"
+  state_fields:
+    - budget_score
+    - total_spend
+---
+
+# /agileflow:ads:budget
+
+Run a budget allocation and bidding strategy audit using the `ads-audit-budget` agent with 24 checks, including industry benchmarks and specific reallocation recommendations.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:ads:budget <account-data>                  # Full budget audit
+```
+
+---
+
+## Process
+
+### STEP 1: Validate Input
+
+If no data provided, ask for:
+- Monthly spend per platform
+- Campaign-level budgets and performance
+- Bid strategies in use
+- Conversion data (volume, CPA, ROAS)
+- Industry and target metrics
+
+### STEP 2: Deploy Budget Analyzer
+
+```xml
+<invoke name="Task">
+<parameter name="description">Budget and bidding audit</parameter>
+<parameter name="prompt">TASK: Audit budget allocation and bidding strategy.
+
+ACCOUNT DATA:
+{budget_data}
+
+Apply ALL 24 checks across 4 categories:
+- Budget Allocation (35%) - 8 checks
+- Bidding Strategy (30%) - 8 checks
+- Scaling & Pacing (20%) - 4 checks
+- Platform Mix (15%) - 4 checks
+
+Enforce platform minimums, scaling rules, and 3x Kill Rule.
+Include specific dollar reallocation recommendations.
+
+OUTPUT: Full findings with Budget Score X/100</parameter>
+<parameter name="subagent_type">ads-audit-budget</parameter>
+</invoke>
+```
+
+### STEP 3: Present Results
+
+Show Budget Score with specific reallocation recommendations.
+
+---
+
+## Platform Minimums
+
+| Platform | Campaign Minimum | Ad Set/Group Minimum |
+|----------|-----------------|---------------------|
+| Google Ads | $10/day | $5/day |
+| Meta Ads | $20/day | $10/day |
+| LinkedIn Ads | $50/day | $25/day |
+| TikTok Ads | $50/day campaign | $20/day ad group |
+| Microsoft Ads | $10/day | $5/day |
+
+## Scaling Rules
+
+1. Max 20% budget increase per week
+2. Only scale campaigns that exited learning phase
+3. 3x Kill Rule: Pause if CPA > 3x target
+4. Minimum 2 weeks data before major changes
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:ads:budget` - Budget & bidding strategy audit
+
+**Agent**: `ads-audit-budget` (24 checks, 4 categories)
+
+**Quick Usage**: `/agileflow:ads:budget <account-data>`
+<!-- COMPACT_SUMMARY_END -->

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

@@ -0,0 +1,112 @@
+---
+description: Competitive intelligence for paid advertising - market positioning, messaging gaps, ad copy analysis, and strategic recommendations
+argument-hint: "<industry-or-competitors>"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:ads:competitor - Competitive intelligence"
+    - "Use WebSearch for competitor research"
+    - "Focus on ad-specific competitive factors"
+  state_fields:
+    - industry
+    - competitors
+---
+
+# /agileflow:ads:competitor
+
+Analyze competitive landscape for paid advertising, including competitor ad strategies, messaging positioning, and market gaps.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:ads:competitor "SaaS project management"      # Industry research
+/agileflow:ads:competitor "competitor1, competitor2"       # Specific competitors
+```
+
+---
+
+## Process
+
+### STEP 1: Identify Competitors
+
+If competitors not specified, use WebSearch to identify top advertisers in the space:
+- Search for industry keywords and note who's advertising
+- Look for "Sponsored" results on Google
+- Check Meta Ad Library for active advertisers
+
+### STEP 2: Analyze Competitor Ads
+
+For each competitor, research:
+
+| Factor | How to Find | What to Note |
+|--------|------------|-------------|
+| **Ad copy themes** | Google search, Ad Library | Headlines, CTAs, value props |
+| **Landing pages** | Click through ads | Page structure, offers, forms |
+| **Platforms active** | Ad libraries, social | Which platforms they invest in |
+| **Offer positioning** | Ad copy, landing pages | Free trial, discount, demo |
+| **Audience signals** | LinkedIn ads, social targeting | Who they're targeting |
+| **Creative style** | Ad Library | Video vs image, UGC, professional |
+
+### STEP 3: Gap Analysis
+
+Identify opportunities the user can exploit:
+
+```markdown
+## Competitive Intelligence Report
+
+### Competitor Overview
+
+| Competitor | Platforms | Key Message | Offer | Ad Style |
+|-----------|-----------|------------|-------|---------|
+| {name} | {platforms} | {message} | {offer} | {style} |
+
+### Messaging Gaps
+{Where competitors are NOT messaging - opportunities for differentiation}
+
+### Ad Format Gaps
+{Ad types/platforms competitors aren't using}
+
+### Positioning Recommendations
+1. **Differentiate on**: {unique angle}
+2. **Counter-position**: {how to position against top competitor}
+3. **Underserved keyword themes**: {keyword areas competitors miss}
+
+### Suggested Ad Copy Angles
+- **Angle 1**: {headline idea} - Why: {competitive reason}
+- **Angle 2**: {headline idea} - Why: {competitive reason}
+- **Angle 3**: {headline idea} - Why: {competitive reason}
+```
+
+### STEP 4: Offer Next Steps
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Competitive analysis complete. {N} competitors analyzed, {M} messaging gaps found.",
+  "header": "Next steps",
+  "multiSelect": false,
+  "options": [
+    {"label": "Build campaign plan using these insights (Recommended)", "description": "Run /agileflow:ads:plan with competitive positioning"},
+    {"label": "Audit our current ads against findings", "description": "Compare your ads to competitor strategies"},
+    {"label": "Deep-dive into specific competitor", "description": "More detailed analysis of one competitor"},
+    {"label": "Generate ad copy based on gaps", "description": "Create ad copy exploiting found gaps"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:ads:competitor` - Competitive intelligence for ads
+
+**Input**: Industry or competitor names
+
+**Output**: Competitor ad analysis, messaging gaps, positioning recommendations
+
+**Quick Usage**: `/agileflow:ads:competitor <industry-or-competitors>`
+<!-- COMPACT_SUMMARY_END -->

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

@@ -0,0 +1,85 @@
+---
+description: Cross-platform creative quality review with 21 checks for ad copy effectiveness, visual compliance, format coverage, and performance testing
+argument-hint: "<account-data>"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:ads:creative - Creative quality review"
+    - "Delegate to ads-audit-creative agent for 21 checks"
+  state_fields:
+    - creative_score
+---
+
+# /agileflow:ads:creative
+
+Run a creative quality audit across all ad platforms using the `ads-audit-creative` agent with 21 checks.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:ads:creative <account-data>                # Cross-platform creative review
+```
+
+---
+
+## Process
+
+### STEP 1: Validate Input
+
+If no data provided, ask the user to share:
+- Ad copy (headlines, descriptions, primary text)
+- Creative assets (image specs, video details)
+- Platform-specific formatting
+- Performance metrics (CTR, CPC, frequency)
+
+### STEP 2: Deploy Creative Analyzer
+
+```xml
+<invoke name="Task">
+<parameter name="description">Creative quality audit</parameter>
+<parameter name="prompt">TASK: Audit creative quality across all platforms.
+
+ACCOUNT DATA:
+{creative_data}
+
+Apply ALL 21 checks across 4 categories:
+- Ad Copy Effectiveness (30%) - 7 checks
+- Visual & Format Compliance (25%) - 6 checks
+- Platform-Specific Requirements (25%) - 4 checks
+- Performance & Testing (20%) - 4 checks
+
+Check safe zones (TikTok, Meta Stories), character limits, and restricted content.
+
+OUTPUT: Full findings with Creative Score X/100</parameter>
+<parameter name="subagent_type">ads-audit-creative</parameter>
+</invoke>
+```
+
+### STEP 3: Present Results
+
+Show Creative Score and offer actionable next steps.
+
+---
+
+## 21 Checks Overview
+
+| Category | Weight | Checks | Focus |
+|----------|--------|--------|-------|
+| Ad Copy Effectiveness | 30% | 7 | Value prop, CTA, social proof, keyword alignment |
+| Visual & Format | 25% | 6 | Resolution, text overlay, brand, mobile-first |
+| Platform Requirements | 25% | 4 | Format coverage, native style, char limits, compliance |
+| Performance & Testing | 20% | 4 | Diversity, winner ID, refresh cadence, A/B testing |
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:ads:creative` - Cross-platform creative quality review
+
+**Agent**: `ads-audit-creative` (21 checks, 4 categories)
+
+**Quick Usage**: `/agileflow:ads:creative <account-data>`
+<!-- COMPACT_SUMMARY_END -->

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

@@ -0,0 +1,238 @@
+---
+description: Bulk ad copy generation — produce 40+ headline/body/CTA variants from product description + ICP angles, formatted for Meta bulk upload and Google Ads Editor
+argument-hint: "<product-description> [PLATFORM=all] [VARIANTS=40] [ANGLES=auto]"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:ads:generate - Bulk ad copy generation"
+    - "Generate headline/body/CTA variants from product description + ICP angles"
+    - "Output structured markdown AND CSV formatted for Meta bulk upload"
+    - "Delegate to ads-generate agent for variant production"
+  state_fields:
+    - product_description
+    - platform
+    - variant_count
+    - angles
+---
+
+# /agileflow:ads:generate
+
+Generate bulk ad copy variants from a product description and ideal customer profile (ICP) angles. Outputs structured markdown for review AND platform-ready CSV for direct upload.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:ads:generate <product-description>                          # 40 variants, all platforms
+/agileflow:ads:generate <product-description> PLATFORM=meta            # Meta-optimized variants
+/agileflow:ads:generate <product-description> PLATFORM=google          # Google Ads Editor format
+/agileflow:ads:generate <product-description> VARIANTS=80 ANGLES=5     # 80 variants across 5 angles
+```
+
+---
+
+## Arguments
+
+| Argument | Values | Default | Description |
+|----------|--------|---------|-------------|
+| product-description | Text, URL, or file path | Required | Product/service description to generate copy for |
+| PLATFORM | all, meta, google, linkedin, tiktok | all | Target platform(s) for format optimization |
+| VARIANTS | 20-100 | 40 | Number of ad variants to generate |
+| ANGLES | 1-10 or auto | auto (5) | Number of ICP angles to explore |
+
+---
+
+## Multi-Step Discovery Flow
+
+### STEP 1: Product Discovery
+
+If product description is minimal or missing, gather context:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[
+  {
+    "question": "What are you advertising? Provide a product/service description, landing page URL, or paste your existing ad copy.",
+    "header": "Product",
+    "multiSelect": false,
+    "options": [
+      {"label": "Paste product description (Recommended)", "description": "Copy/paste from your website, pitch deck, or product brief"},
+      {"label": "Provide landing page URL", "description": "I'll analyze the page and extract product details"},
+      {"label": "Describe verbally", "description": "I'll ask follow-up questions to build the brief"}
+    ]
+  },
+  {
+    "question": "Who is your ideal customer?",
+    "header": "ICP",
+    "multiSelect": false,
+    "options": [
+      {"label": "B2B decision makers", "description": "CTOs, VPs, Directors making software/service purchasing decisions"},
+      {"label": "SMB owners", "description": "Small business owners looking for solutions to operational problems"},
+      {"label": "Consumers", "description": "Individual consumers making personal purchasing decisions"},
+      {"label": "Let me describe", "description": "I'll provide specific ICP details"}
+    ]
+  }
+]</parameter>
+</invoke>
+```
+
+### STEP 2: Angle Generation
+
+From the product description and ICP, generate 5 differentiated messaging angles:
+
+**Standard Angle Framework:**
+
+| # | Angle | What It Emphasizes |
+|---|-------|--------------------|
+| 1 | **Pain Point** | The problem your ICP faces without this product |
+| 2 | **Outcome/Benefit** | The result/transformation after using the product |
+| 3 | **Social Proof** | Numbers, testimonials, authority signals |
+| 4 | **Urgency/Scarcity** | Time-limited offer, competitive pressure, FOMO |
+| 5 | **Contrarian/Pattern Interrupt** | Challenges assumptions, stands out in feed |
+
+If ANGLES > 5, add from:
+| 6 | **Comparison** | Direct or indirect competitor comparison |
+| 7 | **How-It-Works** | Simplicity, 3-step process, ease of use |
+| 8 | **Identity** | "For people who..." — tribe/identity-based |
+| 9 | **Risk Reversal** | Guarantee, free trial, money-back |
+| 10 | **Curiosity** | Open loops, questions, intrigue |
+
+### STEP 3: Generate Variants
+
+Delegate to the `ads-generate` agent for variant production:
+
+```xml
+<invoke name="Agent">
+<parameter name="description">Generate ad copy variants</parameter>
+<parameter name="prompt">TASK: Generate {VARIANTS} ad copy variants for bulk upload.
+
+PRODUCT:
+{product_description}
+
+ICP:
+{icp_description}
+
+ANGLES:
+{angle_list_with_descriptions}
+
+PLATFORMS: {platform}
+
+## Generation Rules
+
+1. **Per angle**: Generate {VARIANTS / ANGLES} variants per angle
+2. **Per variant**: Generate headline + body + CTA as a set
+3. **Platform compliance**: Respect character limits per platform
+4. **Diversity**: No two variants should have the same opening word
+5. **Specificity**: Include numbers, timeframes, or concrete outcomes where possible
+6. **CTA variety**: Mix of "Learn More", "Get Started", "Try Free", "See How", "Book Demo"
+
+## Platform Character Limits
+
+### Meta Ads
+- Primary Text: 125 chars (above fold), 1000 max
+- Headline: 27 chars (recommended), 255 max
+- Description: 27 chars (recommended), 255 max
+- CTA: Select from preset list
+
+### Google Ads (RSA)
+- Headline: 30 chars max (generate 15 headlines)
+- Description: 90 chars max (generate 4 descriptions)
+- Path: 15 chars per path segment
+
+### LinkedIn
+- Intro text: 150 chars (above fold), 600 max
+- Headline: 70 chars max
+- Description: 100 chars max
+
+### TikTok
+- Ad text: 100 chars (recommended)
+- No headline separate from creative
+
+## Output Format
+
+OUTPUT your response in TWO sections:
+
+### Section 1: Review Format (Markdown Table)
+
+| # | Angle | Headline | Body | CTA | Platform |
+|---|-------|----------|------|-----|----------|
+| 1 | Pain Point | ... | ... | Learn More | Meta |
+| ... | ... | ... | ... | ... | ... |
+
+### Section 2: Meta Bulk Upload CSV
+
+```csv
+Ad Name,Primary Text,Headline,Description,Call to Action,Website URL
+{angle}-{number},"{body}","{headline}","{description}",LEARN_MORE,{url}
+```
+
+### Section 3: Google Ads Editor CSV (if PLATFORM includes google)
+
+```csv
+Campaign,Ad Group,Headline 1,Headline 2,Headline 3,Description 1,Description 2,Path 1,Path 2
+```
+
+Flag any variants that push character limits with ⚠️.</parameter>
+<parameter name="subagent_type">ads-generate</parameter>
+</invoke>
+```
+
+### STEP 4: Present Results
+
+After generation completes, present summary and offer next steps:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Generated {N} ad variants across {M} angles. {platform_count} platform format(s) ready. Files saved to docs/08-project/ads-copy/.",
+  "header": "Next steps",
+  "multiSelect": false,
+  "options": [
+    {"label": "Generate more variants for winning angles (Recommended)", "description": "Double down on the strongest 2-3 angles with more variations"},
+    {"label": "Create test plan for these variants", "description": "Run /agileflow:ads:test-plan to structure A/B tests with decision criteria"},
+    {"label": "Adapt for additional platforms", "description": "Reformat variants for Google, LinkedIn, or TikTok specifications"},
+    {"label": "Review and refine specific variants", "description": "Edit individual variants or regenerate specific angles"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+## Output Files
+
+The agent saves artifacts to:
+- `docs/08-project/ads-copy/ads-copy-{YYYYMMDD}.md` — Full review format with all variants
+- `docs/08-project/ads-copy/meta-bulk-upload-{YYYYMMDD}.csv` — Meta Ads Manager bulk upload format
+- `docs/08-project/ads-copy/google-ads-editor-{YYYYMMDD}.csv` — Google Ads Editor import format (if applicable)
+
+---
+
+## Example Output
+
+For a SaaS product "TaskFlow — AI project management":
+
+| # | Angle | Headline | Body | CTA |
+|---|-------|----------|------|-----|
+| 1 | Pain Point | Stop losing tasks in Slack threads | Your team wastes 5 hours/week searching for decisions buried in chat. TaskFlow surfaces action items automatically. | Try Free |
+| 2 | Outcome | Ship 2x faster with AI project management | TaskFlow auto-generates tasks from meetings, prioritizes your backlog, and predicts blockers before they happen. | Get Started |
+| 3 | Social Proof | 2,847 teams shipped faster this month | "We cut our sprint planning from 3 hours to 20 minutes" — VP Eng, Series B startup | See How |
+| 4 | Urgency | Your competitors already use AI for PM | 73% of high-growth startups adopted AI project management in 2025. Don't get left behind. | Start Free Trial |
+| 5 | Contrarian | Project management tools are the problem | More tools = more context switching. TaskFlow replaces your PM tool, not adds to it. | Learn More |
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:ads:generate` - Bulk ad copy generation with ICP angles
+
+**Input**: Product description + ICP + platform (interactive or parameters)
+
+**Output**: 40+ ad variants in review markdown + platform-ready CSV (Meta bulk upload, Google Ads Editor)
+
+**Usage**: `/agileflow:ads:generate <product-description> [PLATFORM=all] [VARIANTS=40] [ANGLES=auto]`
+
+**Files**: `docs/08-project/ads-copy/ads-copy-{YYYYMMDD}.md`, `*-bulk-upload-*.csv`
+<!-- COMPACT_SUMMARY_END -->

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

@@ -0,0 +1,112 @@
+---
+description: Google Ads deep-dive audit with 74 deterministic checks across conversion tracking, spend efficiency, account structure, keywords, ad copy, and settings
+argument-hint: "<account-data>"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:ads:google - Google Ads deep-dive"
+    - "Delegate to ads-audit-google agent for 74 checks"
+    - "Quality gates: tracking required, no Broad without Smart Bidding, 3x Kill Rule"
+  state_fields:
+    - google_score
+---
+
+# /agileflow:ads:google
+
+Run a deep-dive audit on a Google Ads account using the `ads-audit-google` agent with 74 deterministic checks across 6 categories.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:ads:google <account-data>                  # Full Google Ads audit
+```
+
+---
+
+## Process
+
+### STEP 1: Validate Input
+
+If no account data provided, ask the user to paste or describe their Google Ads setup including:
+- Campaign types and objectives
+- Budget and spend data
+- Keyword match types and Quality Scores
+- Ad copy and extensions
+- Conversion tracking setup
+- Bid strategies in use
+
+### STEP 2: Deploy Google Ads Analyzer
+
+```xml
+<invoke name="Task">
+<parameter name="description">Google Ads deep-dive audit</parameter>
+<parameter name="prompt">TASK: Run a comprehensive Google Ads audit.
+
+ACCOUNT DATA:
+{account_data}
+
+Apply ALL 74 checks across 6 weighted categories:
+- Conversion Tracking (25%) - 12 checks
+- Wasted Spend (25%) - 15 checks
+- Account Structure (15%) - 12 checks
+- Keyword Strategy (15%) - 14 checks
+- Ad Copy Quality (10%) - 11 checks
+- Campaign Settings (10%) - 10 checks
+
+Enforce ALL quality gates:
+1. No optimization without conversion tracking
+2. No Broad Match without Smart Bidding
+3. 3x Kill Rule for CPA
+4. Brand/non-brand separation
+
+OUTPUT: Full findings with Google Ads Score X/100</parameter>
+<parameter name="subagent_type">ads-audit-google</parameter>
+</invoke>
+```
+
+### STEP 3: Present Results
+
+Show the Google Ads Score and key findings, then offer next steps:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Google Ads Audit: Score {X}/100. {N} findings ({critical} critical). Quality gates: {status}.",
+  "header": "Next steps",
+  "multiSelect": false,
+  "options": [
+    {"label": "Fix critical issues (Recommended)", "description": "{top issues}"},
+    {"label": "Run full multi-platform audit", "description": "Check all platforms together"},
+    {"label": "Optimize budget allocation", "description": "Run /agileflow:ads:budget"},
+    {"label": "Review creative quality", "description": "Run /agileflow:ads:creative"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+## 74 Checks Overview
+
+| Category | Weight | Checks | Focus |
+|----------|--------|--------|-------|
+| Conversion Tracking | 25% | 12 | Tag, enhanced conversions, CAPI, consent mode |
+| Wasted Spend | 25% | 15 | Negatives, search terms, 3x rule, QS, network |
+| Account Structure | 15% | 12 | Naming, ad groups, PMax isolation, experiments |
+| Keyword Strategy | 15% | 14 | Match types, QS distribution, intent alignment |
+| Ad Copy Quality | 10% | 11 | RSAs, headlines, CTAs, extensions, testing |
+| Campaign Settings | 10% | 10 | Bidding, location, auto-apply, remarketing |
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:ads:google` - Google Ads deep-dive audit
+
+**Agent**: `ads-audit-google` (74 checks, 6 categories)
+
+**Quick Usage**: `/agileflow:ads:google <account-data>`
+<!-- COMPACT_SUMMARY_END -->