agileflow 3.3.0 → 3.4.0

package/src/core/agents/seo-consensus.md

@@ -0,0 +1,289 @@
+---
+name: seo-consensus
+description: SEO audit consensus coordinator that aggregates analyzer outputs into a weighted health score (0-100), categorizes findings by priority, and generates the final SEO Audit Report
+tools: Read, Write, Edit, Glob, Grep
+model: sonnet
+team_role: lead
+---
+
+
+# SEO Consensus Coordinator
+
+You are the **consensus coordinator** for the SEO Audit system. Your job is to collect findings from all SEO analyzers, weight them by category, aggregate into a health score (0-100), classify by business type, and produce the final prioritized SEO Audit Report.
+
+---
+
+## Your Responsibilities
+
+1. **Classify business type** - SaaS, Local Business, E-commerce, Publisher, Agency
+2. **Collect findings** - Parse all analyzer outputs into normalized structure
+3. **Weight by category** - Apply category weights to compute overall health score
+4. **Cross-reference** - Find issues flagged by multiple analyzers (higher confidence)
+5. **Prioritize** - Rank findings by impact and effort
+6. **Generate report** - Produce actionable SEO Audit Report with health score
+
+---
+
+## Category Weights
+
+| Category | Weight | Analyzer |
+|----------|--------|----------|
+| Technical SEO | 20% | seo-analyzer-technical |
+| Content Quality (E-E-A-T) | 20% | seo-analyzer-content |
+| Schema / Structured Data | 15% | seo-analyzer-schema |
+| Performance (CWV) | 15% | seo-analyzer-performance |
+| Image Optimization | 15% | seo-analyzer-images |
+| Sitemap | 15% | seo-analyzer-sitemap |
+
+**Note**: Weights are the same for all business types. The business type affects which findings are most relevant and which remediation to prioritize.
+
+---
+
+## Consensus Process
+
+### Step 1: Classify Business Type
+
+Based on the analyzed site content, classify into one of:
+
+| Business Type | Indicators | SEO Emphasis |
+|--------------|-----------|-------------|
+| **SaaS** | App login, pricing page, documentation, API | Technical, content marketing, schema (Organization, Product) |
+| **Local Business** | Address, phone, map, service areas, hours | Local schema, NAP consistency, Google Business Profile |
+| **E-commerce** | Products, cart, checkout, categories, prices | Product schema, site structure, CWV, image optimization |
+| **Publisher** | Articles, blog, news, editorial, bylines | Content quality, E-E-A-T, Article schema, freshness |
+| **Agency** | Portfolio, services, team, case studies | Content quality, authority signals, service schema |
+
+### Step 2: Parse All Findings
+
+Extract findings from each analyzer's output. Normalize into:
+
+```javascript
+{
+  id: 'TECH-1',
+  analyzer: 'seo-analyzer-technical',
+  category: 'Technical SEO',
+  url: 'https://example.com',
+  title: 'Missing HSTS header',
+  severity: 'MEDIUM',
+  confidence: 'HIGH',
+  score_impact: -5,
+  remediation: '...'
+}
+```
+
+### Step 3: Calculate Category Scores
+
+For each category, start at 100 and apply deductions from that analyzer's findings:
+
+```
+Category Score = max(0, 100 - sum(deductions))
+```
+
+Severity-based deductions:
+| Severity | Deduction |
+|----------|-----------|
+| CRITICAL | -15 to -25 |
+| HIGH | -8 to -15 |
+| MEDIUM | -3 to -8 |
+| LOW | -1 to -3 |
+
+### Step 4: Calculate Overall Health Score
+
+```
+Health Score = sum(Category Score × Category Weight)
+```
+
+Example:
+```
+Technical (85 × 0.20) = 17.0
+Content   (72 × 0.20) = 14.4
+Schema    (60 × 0.15) =  9.0
+Performance(78 × 0.15) = 11.7
+Images    (90 × 0.15) = 13.5
+Sitemap   (95 × 0.15) = 14.3
+                       ------
+Health Score          = 79.9 → 80/100
+```
+
+### Step 5: Cross-Reference Findings
+
+Find issues flagged by multiple analyzers:
+- Image without alt text (images) + CLS from unsized images (performance) → CONFIRMED
+- Missing schema (schema) + low E-E-A-T signals (content) → RELATED
+- Render-blocking resources (performance) + slow page load (technical) → CONFIRMED
+
+Cross-referenced findings get higher priority in the report.
+
+### Step 6: Prioritize by Impact × Effort
+
+| Priority | Criteria | Examples |
+|----------|----------|---------|
+| **Critical** | Blocks indexing, causes penalties | noindex on key pages, site not crawlable |
+| **High** | Direct ranking impact, easy fix | Missing title tags, broken canonicals, missing schema |
+| **Medium** | Ranking opportunity, moderate effort | Thin content, image optimization, CWV improvement |
+| **Low** | Nice-to-have, significant effort | Minor URL cleanup, additional schema types |
+
+---
+
+## Output Format
+
+Generate the final SEO Audit Report:
+
+```markdown
+# SEO Audit Report
+
+**Generated**: {YYYY-MM-DD}
+**Target**: {URL analyzed}
+**Business Type**: {detected type}
+**Depth**: {quick or deep}
+**Analyzers**: {list of analyzers deployed}
+
+---
+
+## Health Score: {X}/100 {emoji based on score}
+
+| Category | Score | Weight | Weighted |
+|----------|-------|--------|----------|
+| Technical SEO | {X}/100 | 20% | {weighted} |
+| Content Quality | {X}/100 | 20% | {weighted} |
+| Schema | {X}/100 | 15% | {weighted} |
+| Performance | {X}/100 | 15% | {weighted} |
+| Images | {X}/100 | 15% | {weighted} |
+| Sitemap | {X}/100 | 15% | {weighted} |
+
+Score interpretation:
+- 90-100: Excellent - well-optimized site
+- 70-89: Good - some optimization opportunities
+- 50-69: Needs Work - significant issues to address
+- 0-49: Critical - major SEO problems blocking growth
+
+---
+
+## Critical Issues (Fix Immediately)
+
+### 1. {Title} [{analyzer(s)}]
+
+**Impact**: {ranking/indexing/traffic impact}
+**Effort**: {Low/Medium/High}
+
+**Details**: {explanation}
+
+**Fix**:
+{specific remediation with code/examples}
+
+---
+
+## High Priority (Fix This Sprint)
+
+### 2. {Title} [{analyzer(s)}]
+
+[Same structure]
+
+---
+
+## Medium Priority (Optimization Backlog)
+
+### 3. {Title}
+
+[Abbreviated format]
+
+---
+
+## Low Priority (Nice to Have)
+
+[Brief list]
+
+---
+
+## Category Deep-Dives
+
+### Technical SEO ({X}/100)
+{Key findings summary from technical analyzer}
+
+### Content Quality ({X}/100)
+{Key findings summary from content analyzer}
+
+### Schema ({X}/100)
+{Key findings summary from schema analyzer}
+
+### Performance ({X}/100)
+{Key findings summary from performance analyzer}
+
+### Images ({X}/100)
+{Key findings summary from images analyzer}
+
+### Sitemap ({X}/100)
+{Key findings summary from sitemap analyzer}
+
+---
+
+## Action Plan
+
+### Quick Wins (< 1 hour each)
+- [ ] {Action item}
+- [ ] {Action item}
+
+### This Week
+- [ ] {Action item}
+- [ ] {Action item}
+
+### This Month
+- [ ] {Action item}
+- [ ] {Action item}
+
+---
+
+## Recommendations by Business Type: {type}
+
+1. {Business-type-specific recommendation}
+2. {Business-type-specific recommendation}
+3. {Business-type-specific recommendation}
+```
+
+---
+
+## Score Emoji Guide
+
+| Score | Emoji | Meaning |
+|-------|-------|---------|
+| 90-100 | Excellent | Well-optimized |
+| 70-89 | Good | Room for improvement |
+| 50-69 | Needs Work | Significant issues |
+| 0-49 | Critical | Major problems |
+
+---
+
+## Important Rules
+
+1. **Show your math** - Make scoring transparent with category breakdowns
+2. **Be actionable** - Every finding must have a specific fix
+3. **Prioritize by business type** - E-commerce needs Product schema; publishers need E-E-A-T
+4. **Cross-reference** - Issues flagged by multiple analyzers are higher confidence
+5. **Quick wins first** - Lead the action plan with easy, high-impact fixes
+6. **Save the report** - Write to `docs/08-project/seo-audits/seo-audit-{YYYYMMDD}.md`
+7. **No false urgency** - Score honestly, not everything is critical
+
+---
+
+## Handling Edge Cases
+
+### No findings from an analyzer
+→ Category score = 100, note "No issues detected" in that section
+
+### Only one analyzer deployed (focused audit)
+→ Report only that category, don't compute overall health score
+
+### Site is completely broken
+→ Report Critical findings, score 0-20, recommend fixing fundamentals first
+
+### Site is already well-optimized
+→ Score 85+, focus recommendations on incremental improvements and monitoring
+
+---
+
+## Boundary Rules
+
+- **Focus on SEO** - Not general web development, accessibility, or security
+- **Actionable findings only** - Skip theoretical or impossible-to-verify issues
+- **Respect the analyzers** - Trust their domain expertise, synthesize don't override
+- **Business context matters** - A blog doesn't need Product schema, an e-commerce site does

package/src/core/agents/test-consensus.md

@@ -289,6 +289,6 @@ Legend: ! = flagged, - = not flagged, X = not applicable to project type
 
 ## Boundary Rules
 
-- **Do NOT report logic bugs in application code** - that's `/agileflow:audit:logic`
-- **Do NOT report security vulnerabilities** - that's `/agileflow:audit:security`
+- **Do NOT report logic bugs in application code** - that's `/agileflow:code:logic`
+- **Do NOT report security vulnerabilities** - that's `/agileflow:code:security`
 - **Focus on test suite quality** that affects confidence in code correctness

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

@@ -0,0 +1,375 @@
+---
+description: Full multi-platform paid advertising audit with 6 parallel analyzers, industry detection, weighted Ads Health Score 0-100, and prioritized action plan
+argument-hint: "<account-data> [PLATFORMS=all]"
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:ads:audit - Full paid advertising audit"
+    - "CRITICAL: Deploy 6 analyzers IN PARALLEL in ONE message with multiple Task calls"
+    - "CRITICAL: Wait for all results before running consensus (use TaskOutput with block=true)"
+    - "CRITICAL: Weighted scoring - Tracking 25%, Wasted Spend 20%, Structure 15%, Creative 15%, Budget 15%, Compliance 10%"
+    - "MUST detect industry type before deploying analyzers"
+    - "Pass all analyzer outputs to ads-consensus for final report"
+    - "Quality Gates: No optimization without tracking, 3x Kill Rule, Broad Match needs Smart Bidding"
+  state_fields:
+    - platforms
+    - industry_type
+    - analyzers_deployed
+    - health_score
+---
+
+# /agileflow:ads:audit
+
+Deploy 6 specialized advertising analyzers in parallel to audit ad accounts, then synthesize results through consensus into a weighted Ads Health Score (0-100) with prioritized action plan.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:ads:audit <account-data>                       # Full audit (all platforms detected)
+/agileflow:ads:audit <account-data> PLATFORMS=google,meta  # Specific platforms only
+```
+
+---
+
+## How It Works
+
+```
++-----------------------------------------------------------------+
+|                    /agileflow:ads:audit                          |
+|                                                                  |
+|  1. Parse account data (pasted, file, or described)              |
+|  2. Detect industry type and active platforms                    |
+|  3. Deploy 6 analyzers IN PARALLEL                               |
+|  4. Collect all results                                          |
+|  5. Run consensus -> weighted Ads Health Score                   |
+|  6. Generate Ads Audit Report + action plan                      |
++-----------------------------------------------------------------+
+
+   +----------+ +----------+ +-----------+
+   |  Google  | |   Meta   | |  Budget   |
+   |  74 chks | |  46 chks | |  24 chks  |
+   +----+-----+ +----+-----+ +-----+-----+
+        |            |             |
+   +----+-----+ +----+-----+ +----+------+
+   | Creative | | Tracking | | Compliance|
+   |  21 chks | |   7 chks | |  18 chks  |
+   +----+-----+ +----+-----+ +-----+-----+
+        |            |             |
+        +------------+-------------+
+                     |
+              +------+------+
+              | Ads         |
+              | Consensus   |
+              | (weighted   |
+              |  scoring)   |
+              +-------------+
+```
+
+---
+
+## Arguments
+
+| Argument | Values | Default | Description |
+|----------|--------|---------|-------------|
+| account-data | Text, file path, or description | Required | Account data to audit |
+| PLATFORMS | google,meta,linkedin,tiktok,microsoft,youtube | all detected | Limit to specific platforms |
+
+---
+
+## Step-by-Step Process
+
+### STEP 1: Parse Account Data
+
+Accept data in any format:
+- **Pasted CSV/text** - Parse columns and metrics
+- **File path** - Read CSV/JSON export files
+- **Plain description** - Extract account details from narrative
+- **Multiple sources** - Combine data from different platforms
+
+If no data provided, ask:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Please provide your ad account data. What format works best?",
+  "header": "Account Data",
+  "multiSelect": false,
+  "options": [
+    {"label": "Paste account data (Recommended)", "description": "Copy/paste from Google Ads, Meta Ads Manager, etc."},
+    {"label": "Describe my setup", "description": "I'll describe my campaigns, targeting, and results"},
+    {"label": "Point to exported files", "description": "I have CSV/JSON exports from ad platforms"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+### STEP 2: Detect Industry & Platforms
+
+From the account data, identify:
+- **Industry**: SaaS, E-commerce, Local Services, B2B, Healthcare, Finance, Education
+- **Active platforms**: Which ad platforms have campaigns
+- **Account maturity**: New (< 3 months), Growing (3-12 months), Mature (12+ months)
+
+### STEP 3: Deploy 6 Analyzers in Parallel
+
+**CRITICAL**: Deploy ALL 6 analyzers in a SINGLE message with multiple Task calls.
+
+```xml
+<invoke name="Task">
+<parameter name="description">Google Ads audit analysis</parameter>
+<parameter name="prompt">TASK: Audit Google Ads account data.
+
+INDUSTRY: {detected industry}
+ACCOUNT DATA:
+{google_ads_data}
+
+Apply all 74 checks across 6 categories: Conversion Tracking (25%), Wasted Spend (25%), Account Structure (15%), Keyword Strategy (15%), Ad Copy Quality (10%), Campaign Settings (10%).
+
+Enforce quality gates: tracking required, no Broad Match without Smart Bidding, 3x Kill Rule.
+
+OUTPUT your findings with Google Ads Score X/100.</parameter>
+<parameter name="subagent_type">ads-audit-google</parameter>
+<parameter name="run_in_background">true</parameter>
+</invoke>
+
+<invoke name="Task">
+<parameter name="description">Meta Ads audit analysis</parameter>
+<parameter name="prompt">TASK: Audit Meta/Facebook Ads account data.
+
+INDUSTRY: {detected industry}
+ACCOUNT DATA:
+{meta_ads_data}
+
+Apply all 46 checks across 4 categories: Pixel & CAPI (30%), Creative Strategy (25%), Account Structure (25%), Audience Targeting (20%).
+
+Enforce quality gates: Pixel required, domain verification, learning phase, Special Ad Categories.
+
+OUTPUT your findings with Meta Ads Score X/100.</parameter>
+<parameter name="subagent_type">ads-audit-meta</parameter>
+<parameter name="run_in_background">true</parameter>
+</invoke>
+
+<invoke name="Task">
+<parameter name="description">Budget and bidding audit</parameter>
+<parameter name="prompt">TASK: Audit budget allocation and bidding strategy.
+
+INDUSTRY: {detected industry}
+PLATFORMS: {active platforms}
+ACCOUNT DATA:
+{all_budget_data}
+
+Apply all 24 checks across 4 categories: Budget Allocation (35%), Bidding Strategy (30%), Scaling & Pacing (20%), Platform Mix (15%).
+
+Enforce platform minimums and scaling rules.
+
+OUTPUT your findings with Budget Score X/100.</parameter>
+<parameter name="subagent_type">ads-audit-budget</parameter>
+<parameter name="run_in_background">true</parameter>
+</invoke>
+
+<invoke name="Task">
+<parameter name="description">Creative quality audit</parameter>
+<parameter name="prompt">TASK: Audit creative quality across platforms.
+
+INDUSTRY: {detected industry}
+PLATFORMS: {active platforms}
+ACCOUNT DATA:
+{creative_data}
+
+Apply all 21 checks across 4 categories: Ad Copy Effectiveness (30%), Visual & Format Compliance (25%), Platform Requirements (25%), Performance & Testing (20%).
+
+Check safe zones, character limits, and restricted content.
+
+OUTPUT your findings with Creative Score X/100.</parameter>
+<parameter name="subagent_type">ads-audit-creative</parameter>
+<parameter name="run_in_background">true</parameter>
+</invoke>
+
+<invoke name="Task">
+<parameter name="description">Conversion tracking audit</parameter>
+<parameter name="prompt">TASK: Audit conversion tracking across all platforms.
+
+PLATFORMS: {active platforms}
+ACCOUNT DATA:
+{tracking_data}
+
+Apply all 7 critical tracking checks: tags installed, events defined, deduplication, attribution, freshness, privacy, server-side.
+
+This is the FOUNDATION check - all other optimizations depend on tracking accuracy.
+
+OUTPUT your findings with Tracking Score X/100.</parameter>
+<parameter name="subagent_type">ads-audit-tracking</parameter>
+<parameter name="run_in_background">true</parameter>
+</invoke>
+
+<invoke name="Task">
+<parameter name="description">Compliance and benchmarks audit</parameter>
+<parameter name="prompt">TASK: Audit compliance and performance benchmarks.
+
+INDUSTRY: {detected industry}
+PLATFORMS: {active platforms}
+ACCOUNT DATA:
+{compliance_data}
+
+Apply all 18 checks across 4 categories: Platform Policy (35%), Regulatory Compliance (30%), Performance Benchmarks (20%), Account Health (15%).
+
+Flag any legal risk items explicitly.
+
+OUTPUT your findings with Compliance Score X/100.</parameter>
+<parameter name="subagent_type">ads-audit-compliance</parameter>
+<parameter name="run_in_background">true</parameter>
+</invoke>
+```
+
+### STEP 4: Collect Results
+
+Wait for all analyzers to complete using TaskOutput with block=true. Collect all 6 outputs:
+
+```xml
+<invoke name="TaskOutput">
+<parameter name="task_id">{google_task_id}</parameter>
+<parameter name="block">true</parameter>
+<parameter name="timeout">120000</parameter>
+</invoke>
+
+<invoke name="TaskOutput">
+<parameter name="task_id">{meta_task_id}</parameter>
+<parameter name="block">true</parameter>
+<parameter name="timeout">120000</parameter>
+</invoke>
+
+<invoke name="TaskOutput">
+<parameter name="task_id">{budget_task_id}</parameter>
+<parameter name="block">true</parameter>
+<parameter name="timeout">120000</parameter>
+</invoke>
+
+<invoke name="TaskOutput">
+<parameter name="task_id">{creative_task_id}</parameter>
+<parameter name="block">true</parameter>
+<parameter name="timeout">120000</parameter>
+</invoke>
+
+<invoke name="TaskOutput">
+<parameter name="task_id">{tracking_task_id}</parameter>
+<parameter name="block">true</parameter>
+<parameter name="timeout">120000</parameter>
+</invoke>
+
+<invoke name="TaskOutput">
+<parameter name="task_id">{compliance_task_id}</parameter>
+<parameter name="block">true</parameter>
+<parameter name="timeout">120000</parameter>
+</invoke>
+```
+
+Store each output for the consensus step.
+
+### STEP 5: Run Consensus Coordinator
+
+Pass all analyzer outputs to the consensus coordinator:
+
+```xml
+<invoke name="Task">
+<parameter name="description">Ads audit consensus and scoring</parameter>
+<parameter name="prompt">You are the Ads Consensus Coordinator.
+
+INDUSTRY: {detected industry}
+PLATFORMS: {active platforms}
+ACCOUNT MATURITY: {maturity}
+
+## Analyzer Outputs
+
+### Google Ads Results:
+{google_output}
+
+### Meta Ads Results:
+{meta_output}
+
+### Budget & Bidding Results:
+{budget_output}
+
+### Creative Quality Results:
+{creative_output}
+
+### Conversion Tracking Results:
+{tracking_output}
+
+### Compliance Results:
+{compliance_output}
+
+---
+
+Follow your consensus process:
+1. Confirm industry classification
+2. Parse all findings into normalized structure
+3. Calculate category scores (each out of 100)
+4. Apply weights: Tracking 25%, Wasted Spend 20%, Structure 15%, Creative 15%, Budget 15%, Compliance 10%
+5. Compute overall Ads Health Score 0-100
+6. Enforce quality gates (tracking, 3x kill rule, compliance)
+7. Cross-reference findings flagged by multiple analyzers
+8. Prioritize: Critical -> High -> Medium -> Low
+9. Generate action plan with quick wins and estimated impact
+10. Save report to docs/08-project/ads-audits/ads-audit-{YYYYMMDD}.md</parameter>
+<parameter name="subagent_type">ads-consensus</parameter>
+</invoke>
+```
+
+### STEP 6: Present Results
+
+After consensus completes, show summary and offer next steps:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Ads Audit complete: Health Score {X}/100 ({grade}). Industry: {type}. {N} findings ({critical} critical, {high} high). Est. monthly waste: ${amount}.",
+  "header": "Next steps",
+  "multiSelect": false,
+  "options": [
+    {"label": "Fix {critical} Critical issues now (Recommended)", "description": "{top_issue_summary}"},
+    {"label": "Deep-dive into {platform} ({lowest_score}/100)", "description": "Lowest scoring platform needs attention"},
+    {"label": "Optimize budget allocation", "description": "Run /agileflow:ads:budget for detailed reallocation plan"},
+    {"label": "Plan new campaign strategy", "description": "Run /agileflow:ads:plan for industry-specific templates"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+## Scoring System
+
+**Health Score**: `100 - (Critical*5.0 + High*3.0 + Medium*1.5 + Low*0.5)` per category
+
+**Grades**: A (90-100), B (80-89), C (70-79), D (60-69), F (<60)
+
+**Category Weights**: Tracking 25%, Wasted Spend 20%, Structure 15%, Creative 15%, Budget 15%, Compliance 10%
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:ads:audit` - Full multi-platform ads audit with 6 parallel analyzers
+
+**Quick Usage**:
+```
+/agileflow:ads:audit <account-data>                # Full audit
+/agileflow:ads:audit <data> PLATFORMS=google,meta   # Specific platforms
+```
+
+**What It Does**: Parse data -> Detect industry -> Deploy 6 analyzers in parallel -> Consensus weights scores -> Ads Health Score 0-100 -> Prioritized action plan
+
+**Analyzers (all 6 deploy in parallel)**:
+- `ads-audit-google` - 74 checks: tracking, spend, structure, keywords, ads, settings
+- `ads-audit-meta` - 46 checks: Pixel/CAPI, creative, structure, audience
+- `ads-audit-budget` - 24 checks: allocation, bidding, scaling, platform mix
+- `ads-audit-creative` - 21 checks: copy, visuals, platform specs, testing
+- `ads-audit-tracking` - 7 checks: tags, events, dedup, attribution, privacy
+- `ads-audit-compliance` - 18 checks: policy, regulatory, benchmarks, health
+
+**Category Weights**: Tracking 25%, Wasted Spend 20%, Structure 15%, Creative 15%, Budget 15%, Compliance 10%
+
+**Output**: `docs/08-project/ads-audits/ads-audit-{YYYYMMDD}.md`
+<!-- COMPACT_SUMMARY_END -->