bmad-plus 0.4.1 → 0.4.2

package/src/bmad-plus/agents/pack-seo/ref/audit-schema.json

@@ -0,0 +1,187 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "BMAD+ SEO Audit Result",
+  "description": "Standardized JSON format for SEO audit results. Compatible with dashboards, MCP Server, and external tools.",
+  "version": "1.0.0",
+  "author": "Laurent Rochetta",
+  "type": "object",
+  "required": ["engine", "version", "domain", "timestamp", "score", "issues"],
+  "properties": {
+    "engine": {
+      "type": "string",
+      "const": "bmad-seo-engine",
+      "description": "Engine identifier"
+    },
+    "version": {
+      "type": "string",
+      "description": "Engine version",
+      "examples": ["2.1.0"]
+    },
+    "domain": {
+      "type": "string",
+      "description": "Audited domain (without protocol)",
+      "examples": ["example.com"]
+    },
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Full URL audited"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of audit completion"
+    },
+    "business_type": {
+      "type": "string",
+      "enum": ["saas", "ecommerce", "local", "publisher", "agency", "other"],
+      "description": "Detected business type"
+    },
+    "pages_analyzed": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Number of pages analyzed"
+    },
+    "score": {
+      "type": "object",
+      "required": ["total", "categories"],
+      "properties": {
+        "total": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100,
+          "description": "Weighted SEO Health Score"
+        },
+        "rating": {
+          "type": "string",
+          "enum": ["excellent", "good", "needs_work", "poor", "critical"],
+          "description": "Score interpretation"
+        },
+        "categories": {
+          "type": "object",
+          "properties": {
+            "technical": { "type": "integer", "minimum": 0, "maximum": 100 },
+            "content_eeat": { "type": "integer", "minimum": 0, "maximum": 100 },
+            "on_page": { "type": "integer", "minimum": 0, "maximum": 100 },
+            "schema": { "type": "integer", "minimum": 0, "maximum": 100 },
+            "performance": { "type": "integer", "minimum": 0, "maximum": 100 },
+            "ai_readiness": { "type": "integer", "minimum": 0, "maximum": 100 },
+            "images": { "type": "integer", "minimum": 0, "maximum": 100 }
+          },
+          "description": "Score per category (0-100)"
+        }
+      }
+    },
+    "issues": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "severity", "category", "title"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique issue identifier",
+            "examples": ["missing-meta-description", "multiple-h1"]
+          },
+          "severity": {
+            "type": "string",
+            "enum": ["critical", "high", "medium", "low"]
+          },
+          "category": {
+            "type": "string",
+            "enum": ["technical", "content", "on_page", "schema", "performance", "geo", "images"]
+          },
+          "title": {
+            "type": "string",
+            "description": "Human-readable issue title"
+          },
+          "description": {
+            "type": "string",
+            "description": "Detailed explanation"
+          },
+          "affected_urls": {
+            "type": "array",
+            "items": { "type": "string", "format": "uri" },
+            "description": "Pages affected by this issue"
+          },
+          "fix": {
+            "type": "string",
+            "description": "Auto-generated fix code (HTML, JSON-LD, etc.)"
+          },
+          "quick_win": {
+            "type": "boolean",
+            "description": "True if high impact / low effort"
+          },
+          "impact": {
+            "type": "string",
+            "enum": ["high", "medium", "low"]
+          },
+          "effort": {
+            "type": "string",
+            "enum": ["high", "medium", "low"]
+          }
+        }
+      }
+    },
+    "pages": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "url": { "type": "string", "format": "uri" },
+          "status": { "type": "integer" },
+          "title": { "type": "string" },
+          "word_count": { "type": "integer" },
+          "schema_types": { "type": "array", "items": { "type": "string" } },
+          "eeat_score": { "type": "integer", "minimum": 0, "maximum": 100 }
+        }
+      },
+      "description": "Per-page analysis data"
+    },
+    "geo": {
+      "type": "object",
+      "properties": {
+        "ai_readiness_score": { "type": "integer", "minimum": 0, "maximum": 100 },
+        "ai_crawlers_allowed": { "type": "array", "items": { "type": "string" } },
+        "has_llms_txt": { "type": "boolean" },
+        "citability_score": { "type": "integer", "minimum": 0, "maximum": 100 }
+      },
+      "description": "GEO / AI search readiness metrics"
+    },
+    "pagespeed": {
+      "type": "object",
+      "properties": {
+        "mobile": {
+          "type": "object",
+          "properties": {
+            "performance": { "type": "integer" },
+            "accessibility": { "type": "integer" },
+            "best_practices": { "type": "integer" },
+            "seo": { "type": "integer" }
+          }
+        },
+        "desktop": {
+          "type": "object",
+          "properties": {
+            "performance": { "type": "integer" },
+            "accessibility": { "type": "integer" },
+            "best_practices": { "type": "integer" },
+            "seo": { "type": "integer" }
+          }
+        }
+      },
+      "description": "PageSpeed Insights scores"
+    },
+    "monitoring": {
+      "type": "object",
+      "properties": {
+        "previous_score": { "type": "integer" },
+        "previous_date": { "type": "string", "format": "date" },
+        "delta": { "type": "integer" },
+        "issues_resolved": { "type": "integer" },
+        "issues_new": { "type": "integer" }
+      },
+      "description": "Comparison with previous audit (if available)"
+    }
+  }
+}

package/src/bmad-plus/agents/pack-seo/ref/cwv-thresholds.md

@@ -0,0 +1,87 @@
+# Core Web Vitals — Thresholds & Optimization Guide (March 2026)
+
+> Author: Laurent Rochetta | BMAD+ SEO Engine v2.0
+
+## Current Metrics
+
+| Metric | Good | Needs Improvement | Poor |
+|--------|------|-------------------|------|
+| **LCP** (Largest Contentful Paint) | ≤2.5s | 2.5–4.0s | >4.0s |
+| **INP** (Interaction to Next Paint) | ≤200ms | 200–500ms | >500ms |
+| **CLS** (Cumulative Layout Shift) | ≤0.1 | 0.1–0.25 | >0.25 |
+
+> **INP replaced FID on March 12, 2024.** FID was fully removed from all Chrome tools on September 9, 2024. Never reference FID.
+
+## Key Facts
+- Evaluation uses the **75th percentile** of real user data (CrUX field data)
+- Assessment at **page level** AND **origin level**
+- CWV is a **tiebreaker** signal — matters most when content quality is similar
+- Thresholds **unchanged since original definitions**
+- December 2025 core update appeared to weight **mobile CWV more heavily**
+- As of October 2025: 57.1% desktop, 49.7% mobile sites pass all three CWV
+- **Mobile-first indexing 100% complete** since July 5, 2024
+
+## LCP Diagnostic Subparts (Feb 2025 CrUX)
+
+| Subpart | Description | Target |
+|---------|-------------|--------|
+| TTFB | Server response time | <800ms |
+| Resource Load Delay | TTFB to resource request | Minimize |
+| Resource Load Time | LCP resource download | Size-dependent |
+| Element Render Delay | Loaded to painted | Minimize |
+
+**Total LCP = TTFB + Load Delay + Load Time + Render Delay**
+
+## Common Bottlenecks
+
+### LCP
+- Unoptimized hero images → use WebP/AVIF, add `<link rel="preload">`
+- Render-blocking CSS/JS → defer, async, critical CSS inline
+- Slow TTFB (>200ms) → CDN, caching, edge compute
+- Third-party blocking → defer analytics, chat widgets
+- Font delay → `font-display: swap` + preload
+
+### INP
+- Long JS tasks on main thread → break tasks <50ms, use `scheduler.yield()`
+- Heavy event handlers → debounce, requestAnimationFrame
+- Excessive DOM (>1,500 elements)
+- Third-party scripts hijacking main thread
+- Layout thrashing (forced reflows)
+
+### CLS
+- Images/iframes without width/height dimensions
+- Dynamic content injected above existing content
+- Font swap causing layout shift → preload + font-display
+- Ads/embeds without reserved space
+
+## Measurement Sources
+
+### Field Data (used for ranking)
+- Chrome User Experience Report (CrUX)
+- PageSpeed Insights (uses CrUX)
+- Search Console Core Web Vitals report
+
+### Lab Data (for debugging)
+- Lighthouse 13.0 (Oct 2025, restructured audits)
+- WebPageTest
+- Chrome DevTools
+
+## Optimization Priority
+1. **LCP** — Most impactful for perceived performance
+2. **CLS** — Most common UX issue
+3. **INP** — Critical for interactive applications
+
+## API Tools
+```bash
+# PageSpeed Insights API
+curl "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=URL&key=API_KEY"
+
+# Lighthouse CLI
+npx lighthouse URL --output json --output-path report.json
+```
+
+## 2025–2026 Updates
+- **Lighthouse 13.0** (Oct 2025): reorganized performance categories
+- **CrUX Vis** replaced CrUX Dashboard (Nov 2025) → cruxvis.withgoogle.com
+- **LCP subparts** in CrUX (Feb 2025)
+- **Soft Navigations API** (Chrome 139+, July 2025): experimental SPA CWV measurement — no ranking impact yet

package/src/bmad-plus/agents/pack-seo/ref/eeat-criteria.md

@@ -0,0 +1,123 @@
+# E-E-A-T Evaluation Criteria (March 2026)
+
+> Author: Laurent Rochetta | BMAD+ SEO Engine v2.0
+> Based on: Google Quality Rater Guidelines (September 2025 update)
+
+## Overview
+
+E-E-A-T = **Experience, Expertise, Authoritativeness, Trustworthiness**
+
+Google's quality raters evaluate pages on these four dimensions. While not a direct ranking factor, E-E-A-T signals influence how Google's algorithms assess content quality and YMYL (Your Money or Your Life) pages.
+
+> Since March 2024, the Helpful Content System is merged into Google's core algorithm. Enforcement is continuous, not via separate HCU updates.
+
+---
+
+## Experience (25 points)
+
+First-hand, real-world experience with the topic.
+
+| Signal | Points | How to Detect |
+|--------|--------|---------------|
+| Original research or case studies | 8 | Unique data, before/after results, proprietary findings |
+| First-hand process documentation | 6 | Step-by-step from personal experience, production screenshots |
+| Unique media from direct experience | 6 | Original photos, self-recorded videos, personal screenshots |
+| Specific examples and anecdotes | 5 | Named examples, concrete details, real scenarios |
+
+**Red flags**: Generic advice that could come from any source, stock photos only, no personal perspective.
+
+---
+
+## Expertise (25 points)
+
+Demonstrable knowledge and skill in the subject area.
+
+| Signal | Points | How to Detect |
+|--------|--------|---------------|
+| Author credentials visible | 7 | Bio with qualifications, certifications, professional background |
+| Technical depth appropriate | 7 | Correct terminology, nuanced explanations, awareness of edge cases |
+| Well-sourced claims | 6 | Citations to studies, official documentation, linked sources |
+| Comprehensive topic coverage | 5 | Covers subtopics, addresses counterarguments, FAQ sections |
+
+**Red flags**: No author identified, surface-level coverage, factual errors, outdated information.
+
+---
+
+## Authoritativeness (25 points)
+
+Recognition as a trusted source by peers and industry.
+
+| Signal | Points | How to Detect |
+|--------|--------|---------------|
+| External citations / references | 7 | Backlinks from authoritative sites, cited in industry publications |
+| Brand recognition signals | 7 | Awards, partnerships, media mentions, client logos |
+| Author published elsewhere | 6 | Guest posts, conference talks, books, academic papers |
+| Expert endorsements | 5 | Testimonials from peers, quoted by other experts |
+
+**Red flags**: Brand-new domain with no web presence, no external references, no social proof.
+
+---
+
+## Trustworthiness (25 points)
+
+Transparency, accuracy, and confidence in the source.
+
+| Signal | Points | How to Detect |
+|--------|--------|---------------|
+| Contact info and physical address | 7 | Phone, email, postal address, About page |
+| Privacy policy and terms | 5 | Legal pages present, accessible, and up-to-date |
+| HTTPS and security signals | 5 | Valid SSL, HSTS, security headers present |
+| Transparent authorship and dates | 5 | Author byline, publication date, last updated date |
+| Customer proof | 3 | Verified reviews, testimonials, case studies |
+
+**Red flags**: No contact information, anonymous content, no dates, misleading claims, HTTP only.
+
+---
+
+## YMYL Pages — Higher Standards
+
+YMYL (Your Money or Your Life) topics require **elevated E-E-A-T**:
+
+| YMYL Category | Examples | E-E-A-T Bar |
+|---------------|----------|-------------|
+| Health | Medical advice, symptoms, treatments | Very High — requires medical expertise |
+| Finance | Investment, tax, insurance, banking | Very High — requires financial credentials |
+| Safety | Product safety, emergency info | Very High |
+| Legal | Legal rights, contracts, regulations | Very High — requires legal expertise |
+| News | Current events, political coverage | High — requires journalistic standards |
+| Shopping | Product reviews, comparisons | Moderate-High |
+
+---
+
+## AI Content Assessment (Sept 2025 QRG Addition)
+
+Google raters now formally assess AI-generated content.
+
+### Acceptable AI Content
+- Demonstrates genuine E-E-A-T despite AI assistance
+- Provides unique value (not just rephrased existing content)
+- Has clear human oversight and editing
+- Contains original analysis, insights, or perspective
+- Includes first-party data or real-world evidence
+
+### Low-Quality AI Content Markers
+- Generic phrasing with no specificity
+- Repetitive structure across multiple pages (cookie-cutter)
+- No original insights or unique data
+- Missing author attribution entirely
+- Factual inaccuracies or hallucinated statistics
+- Excessive use of filler words and hedging language
+
+---
+
+## Scoring Methodology
+
+**Total E-E-A-T Score = Experience + Expertise + Authoritativeness + Trustworthiness (out of 100)**
+
+| Range | Rating | Interpretation |
+|-------|--------|---------------|
+| 80–100 | Excellent | Strong signals across all dimensions |
+| 60–79 | Good | Solid foundation with room to improve |
+| 40–59 | Needs Work | Significant gaps in one or more areas |
+| 20–39 | Poor | Major deficiencies undermining credibility |
+| 0–19 | Critical | Lacking basic trust and expertise signals |

package/src/bmad-plus/agents/pack-seo/ref/geo-signals.md

@@ -0,0 +1,167 @@
+# GEO Signals — AI Search Optimization Guide (March 2026)
+
+> Author: Laurent Rochetta | BMAD+ SEO Engine v2.0
+
+## What is GEO?
+
+**Generative Engine Optimization (GEO)** is the discipline of optimizing content for AI-generated answers across Google AI Overviews, ChatGPT, Perplexity, Bing Copilot, and other AI-powered search experiences.
+
+## AI Search Landscape
+
+| Platform | Reach | Key Citation Sources |
+|----------|-------|---------------------|
+| Google AI Overviews | 1.5B users/month, 200+ countries, 50%+ query coverage | Top-10 ranking pages (92%) |
+| Google AI Mode | Full conversational search (May 2025), zero organic links | Citation is the only visibility mechanism |
+| ChatGPT Search | 900M weekly active users | Wikipedia (47.9%), Reddit (11.3%) |
+| Perplexity | 500M+ monthly queries | Reddit (46.7%), Wikipedia |
+| Bing Copilot | Integrated in Edge/Windows | Bing index, authoritative sites |
+
+> AI-referred sessions grew **527%** between January and May 2025 (SparkToro).
+
+---
+
+## The Brand Mention Revolution
+
+**Brand mentions correlate 3× more strongly with AI visibility than backlinks.**
+(Ahrefs December 2025 study, 75,000 brands)
+
+| Signal | Correlation with AI Citations |
+|--------|-------------------------------|
+| YouTube mentions | ~0.737 (strongest) |
+| Reddit mentions | High |
+| Wikipedia presence | High |
+| LinkedIn presence | Moderate |
+| Domain Rating (backlinks) | ~0.266 (weak) |
+
+> Only **11%** of domains are cited by both ChatGPT and Google AI Overviews for the same query — platform-specific optimization is essential.
+
+---
+
+## GEO Scoring Criteria
+
+### 1. Citability (25%)
+
+**Optimal passage length: 134–167 words** for AI citation.
+
+| Signal | Strong | Weak |
+|--------|--------|------|
+| Quotable statements with facts/stats | ✅ | Vague generic statements |
+| Self-contained answer blocks | ✅ | Requires surrounding context |
+| Direct answer in first 40–60 words | ✅ | Buried conclusions |
+| "X is..." / "X refers to..." patterns | ✅ | No definitions |
+| Unique data not found elsewhere | ✅ | Commonly available info |
+
+### 2. Structural Readability (20%)
+
+92% of AI Overview citations come from top-10 pages, but 47% come from pages below position 5 — demonstrating different selection logic.
+
+| Signal | Strong | Weak |
+|--------|--------|------|
+| Clean H1→H2→H3 hierarchy | ✅ | Wall of text |
+| Question-based headings | ✅ | Vague headings |
+| Short paragraphs (2-4 sentences) | ✅ | Long unbroken paragraphs |
+| Tables for comparative data | ✅ | No structured data display |
+| Lists for multi-item content | ✅ | Inline lists in sentences |
+
+### 3. Multi-Modal Content (15%)
+
+Content with multi-modal elements sees **156% higher selection rates**.
+
+- Text + relevant images
+- Video content (embedded or linked)
+- Infographics and charts
+- Interactive tools (calculators, assessments)
+- Structured data supporting media
+
+### 4. Authority & Brand Signals (20%)
+
+- Author byline with credentials
+- Publication and last-updated dates
+- Citations to primary sources
+- Organization credentials
+- Entity presence in Wikipedia, Wikidata
+- Active presence on Reddit, YouTube, LinkedIn
+
+### 5. Technical Accessibility (20%)
+
+**AI crawlers do NOT execute JavaScript** — SSR is critical.
+
+- Server-side rendering for core content
+- AI crawler access in robots.txt
+- llms.txt file presence
+- RSL 1.0 licensing terms
+
+---
+
+## AI Crawler Registry
+
+| Crawler | Owner | Purpose | Recommend |
+|---------|-------|---------|-----------|
+| GPTBot | OpenAI | ChatGPT web search + training | Allow |
+| OAI-SearchBot | OpenAI | OpenAI search features | Allow |
+| ChatGPT-User | OpenAI | ChatGPT browsing | Allow |
+| ClaudeBot | Anthropic | Claude web features | Allow |
+| PerplexityBot | Perplexity | Perplexity search | Allow |
+| Applebot-Extended | Apple | Apple Intelligence features | Allow |
+| Google-Extended | Google | Gemini training (NOT Search) | Optional |
+| CCBot | Common Crawl | Open dataset training | Optional/Block |
+| Bytespider | ByteDance | TikTok/Douyin AI training | Block |
+| anthropic-ai | Anthropic | Claude training | Optional |
+| cohere-ai | Cohere | Cohere models | Optional |
+
+---
+
+## llms.txt Standard
+
+File at `/llms.txt` (domain root). Provides structured guidance to AI crawlers.
+
+```
+# Site Name
+> One-line description
+
+## Main Sections
+- [Page Title](url): Description
+- [Another Page](url): Description
+
+## Key Facts
+- Important fact 1
+- Important fact 2
+```
+
+Also check for `/llms-full.txt` (expanded version).
+
+---
+
+## RSL 1.0 (Really Simple Licensing)
+
+Machine-readable AI licensing standard (December 2025).
+Backed by: Reddit, Yahoo, Medium, Quora, Cloudflare, Akamai, Creative Commons.
+
+Check for RSL implementation and appropriate licensing terms.
+
+---
+
+## Quick Wins for AI Visibility
+
+### Immediate (1 day)
+1. Add "What is [topic]?" definition in first 60 words of key pages
+2. Create 134–167 word self-contained answer blocks
+3. Add question-based H2/H3 headings
+4. Include specific statistics with source attribution
+5. Add publication and update dates
+6. Allow key AI crawlers in robots.txt (GPTBot, ClaudeBot, PerplexityBot)
+
+### Short-term (1 week)
+1. Create `/llms.txt` file
+2. Add author bios with credentials + Wikipedia/LinkedIn links
+3. Implement Person and Organization schema
+4. Add comparison tables with structured data
+5. Ensure SSR for all critical content
+
+### Strategic (1-3 months)
+1. Build Wikipedia presence for brand and key people
+2. Create original research or surveys (unique citability)
+3. Establish active YouTube channel
+4. Build Reddit community presence
+5. Implement comprehensive entity linking (sameAs across platforms)
+6. Develop unique tools, calculators, or interactive content