bmad-plus 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to BMAD+ will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.3] — 2026-03-19
+
+### 🧪 SEO Engine — Quality & Security (Sprint 3)
+
+### Added
+- **Unit tests** — 50 pytest tests covering all Python scripts (fetch, parse, crawl, APIs)
+- **Pre-commit hook** — `hooks/seo-check.sh` validates HTML for title, meta, alt, H1 before commit
+- **Audit JSON schema** — `ref/audit-schema.json` standardized export format for dashboard/API integration
+- **Test fixture** — `tests/fixtures/sample_page.html` with known SEO elements
+
+---
+
+## [0.3.2] — 2026-03-19
+
+### 📊 SEO Engine — Reports, Competitor & Hreflang (Sprint 2)
+
+### Added
+- **seo_report.py** — Professional HTML report generator with inline SVG radar chart, color-coded issue cards, quick wins section, and print-friendly CSS
+- **Benchmarker role** — Added to Chief agent for `/seo competitor` command (side-by-side site comparison with delta scoring)
+- **hreflang-rules.md** — Complete hreflang audit reference with 7 validation rules, 6 common error patterns, and 12-point checklist
+
+---
+
 ## [0.3.1] — 2026-03-19
 
 ### 🔧 SEO Engine Enhancements (Sprint 1)

package/oveanet-pack/seo-audit-360/agent/seo-chief.md

@@ -29,6 +29,25 @@ You are **Chief**, the strategist and reporting agent of the BMAD+ SEO Engine. Y
 - Generate executive summary for non-technical stakeholders
 - Create monitoring comparison reports (vs previous audit)
 - Format reports for different audiences (developer, marketing, executive)
+- Generate **HTML reports** via `scripts/seo_report.py` from audit JSON
+
+### Role: Benchmarker
+**Trigger**: `/seo competitor`, competitive analysis, benchmark
+- Run full audit on **two sites simultaneously** (Scout + Judge on each)
+- Compare scores side-by-side with delta indicators:
+
+| Metric | My Site | Competitor | Delta |
+|--------|---------|-----------|-------|
+| SEO Score | 72 | 85 | -13 🔴 |
+| E-E-A-T | 65 | 78 | -13 🔴 |
+| Schema types | 3 | 7 | -4 🟠 |
+| GEO/AI Score | 55 | 70 | -15 🔴 |
+| PageSpeed | 92 | 88 | +4 🟢 |
+
+- Identify **competitive gaps** (where rival is better)
+- Identify **competitive advantages** (where we're better)
+- Generate actionable plan: "To match competitor, prioritize: ..."
+- Output: Markdown comparison report + optional HTML via `seo_report.py`
 
 ---
 

package/oveanet-pack/seo-audit-360/hooks/seo-check.sh

@@ -0,0 +1,95 @@
+#!/bin/bash
+# SEO Pre-Commit Hook — Catches common SEO issues before commit.
+# Install: cp hooks/seo-check.sh .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
+#
+# Author: Laurent Rochetta | BMAD+ SEO Engine
+
+ERRORS=0
+WARNINGS=0
+
+echo "🔎 BMAD+ SEO Pre-Commit Check..."
+
+# Only check staged HTML files
+HTML_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -iE '\.(html|htm|php|jsx|tsx)$')
+
+if [ -z "$HTML_FILES" ]; then
+    echo "  No HTML files staged, skipping SEO check."
+    exit 0
+fi
+
+for FILE in $HTML_FILES; do
+    # Skip node_modules and vendor
+    if echo "$FILE" | grep -qE '(node_modules|vendor|dist|build|\.min\.)'; then
+        continue
+    fi
+
+    CONTENT=$(git show ":$FILE" 2>/dev/null)
+    if [ -z "$CONTENT" ]; then
+        continue
+    fi
+
+    # Check 1: Missing <title> tag
+    if ! echo "$CONTENT" | grep -qi '<title'; then
+        echo "  🔴 $FILE — Missing <title> tag"
+        ERRORS=$((ERRORS + 1))
+    fi
+
+    # Check 2: Empty <title> tag
+    if echo "$CONTENT" | grep -qiE '<title>\s*</title>'; then
+        echo "  🔴 $FILE — Empty <title> tag"
+        ERRORS=$((ERRORS + 1))
+    fi
+
+    # Check 3: Missing meta description
+    if ! echo "$CONTENT" | grep -qi 'name="description"'; then
+        echo "  🟠 $FILE — Missing <meta name=\"description\">"
+        WARNINGS=$((WARNINGS + 1))
+    fi
+
+    # Check 4: Images without alt attribute
+    IMG_NO_ALT=$(echo "$CONTENT" | grep -ciE '<img[^>]*(?!alt)[^>]*>' 2>/dev/null || echo "0")
+    # More reliable: count <img> without alt
+    TOTAL_IMGS=$(echo "$CONTENT" | grep -ci '<img' 2>/dev/null || echo "0")
+    IMGS_WITH_ALT=$(echo "$CONTENT" | grep -ci '<img[^>]*alt=' 2>/dev/null || echo "0")
+    MISSING_ALT=$((TOTAL_IMGS - IMGS_WITH_ALT))
+
+    if [ "$MISSING_ALT" -gt 0 ]; then
+        echo "  🟠 $FILE — $MISSING_ALT image(s) without alt attribute"
+        WARNINGS=$((WARNINGS + 1))
+    fi
+
+    # Check 5: Multiple H1 tags
+    H1_COUNT=$(echo "$CONTENT" | grep -ci '<h1' 2>/dev/null || echo "0")
+    if [ "$H1_COUNT" -gt 1 ]; then
+        echo "  🟡 $FILE — Multiple H1 tags ($H1_COUNT found, should be 1)"
+        WARNINGS=$((WARNINGS + 1))
+    fi
+
+    # Check 6: No H1 tag at all
+    if [ "$H1_COUNT" -eq 0 ]; then
+        echo "  🟠 $FILE — No H1 tag found"
+        WARNINGS=$((WARNINGS + 1))
+    fi
+
+    # Check 7: "Click here" or "Learn more" anchor text
+    BAD_ANCHORS=$(echo "$CONTENT" | grep -ciE '>click here<|>learn more<|>read more<|>here<' 2>/dev/null || echo "0")
+    if [ "$BAD_ANCHORS" -gt 0 ]; then
+        echo "  🟡 $FILE — $BAD_ANCHORS link(s) with generic anchor text (\"click here\", \"learn more\")"
+        WARNINGS=$((WARNINGS + 1))
+    fi
+done
+
+echo ""
+echo "  Results: $ERRORS error(s), $WARNINGS warning(s)"
+
+if [ "$ERRORS" -gt 0 ]; then
+    echo "  ❌ Commit blocked — fix critical SEO issues first!"
+    exit 1
+else
+    if [ "$WARNINGS" -gt 0 ]; then
+        echo "  ⚠️ Commit allowed with warnings — consider fixing these issues."
+    else
+        echo "  ✅ All SEO checks passed!"
+    fi
+    exit 0
+fi

package/oveanet-pack/seo-audit-360/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/oveanet-pack/seo-audit-360/ref/hreflang-rules.md

@@ -0,0 +1,153 @@
+# Hreflang — Audit Rules & Best Practices (March 2026)
+
+> Author: Laurent Rochetta | BMAD+ SEO Engine v2.0
+
+## What is Hreflang?
+
+`hreflang` tells search engines which language/region version of a page to serve.
+Errors cause wrong language indexing, duplicate content penalties, and lost organic traffic.
+
+---
+
+## Implementation Methods
+
+| Method | Best For | Max Pages |
+|--------|----------|-----------|
+| `<link>` in `<head>` | Small sites (<50 pages) | ~50 |
+| HTTP header `Link:` | Non-HTML files (PDFs) | ~50 |
+| Sitemap `<xhtml:link>` | Large sites (50+) | Unlimited |
+
+> **Recommendation**: Use sitemap for sites with 50+ pages. HTTP headers for non-HTML resources.
+
+---
+
+## Validation Rules
+
+### Rule 1: Valid Language Codes
+- Use **ISO 639-1** (2-letter): `en`, `fr`, `de`, `es`, `ja`, `zh`
+- Optional **ISO 3166-1 Alpha-2** for region: `en-US`, `en-GB`, `fr-FR`, `fr-CA`, `pt-BR`
+- **Case insensitive** but convention is lowercase lang, uppercase country
+
+| ✅ Valid | ❌ Invalid | Why |
+|---------|-----------|-----|
+| `en` | `english` | Must be ISO 639-1 |
+| `fr-FR` | `fr-FRA` | Country must be 2-letter |
+| `zh-Hans` | `cn` | `cn` is not a valid language code |
+| `x-default` | `default` | Must use exact `x-default` |
+
+### Rule 2: Self-Referencing (MANDATORY)
+Every page MUST include a hreflang tag pointing to itself.
+
+```html
+<!-- On the English page (example.com/en/) -->
+<link rel="alternate" hreflang="en" href="https://example.com/en/" />
+<link rel="alternate" hreflang="fr" href="https://example.com/fr/" />
+<link rel="alternate" hreflang="x-default" href="https://example.com/en/" />
+```
+
+**Error if missing**: Google may ignore all hreflang tags on that page.
+
+### Rule 3: Return Tags (MANDATORY)
+If page A links to page B with hreflang, page B MUST link back to page A.
+
+```
+Page A (en) → hreflang="fr" → Page B (fr)
+Page B (fr) → hreflang="en" → Page A (en)   ← MANDATORY
+```
+
+**Error if missing**: Called "orphan hreflang" — Google ignores the one-way tag.
+
+### Rule 4: x-default (STRONGLY RECOMMENDED)
+Designate a fallback page for users whose language/region doesn't match any variant.
+
+```html
+<link rel="alternate" hreflang="x-default" href="https://example.com/" />
+```
+
+Common choices for x-default:
+- Language selector/redirect page
+- English version (most common)
+- Homepage of the main domain
+
+### Rule 5: Canonical + Hreflang Consistency
+- Each hreflang URL **must be the canonical version** (not a redirect, not a URL with parameters)
+- If a page has `rel="canonical"` pointing elsewhere, hreflang tags on that page are **ignored**
+- Canonical and hreflang must agree: don't have hreflang point to a URL that canonicalizes to a different URL
+
+### Rule 6: Absolute URLs Only
+```html
+<!-- ✅ Correct -->
+<link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
+
+<!-- ❌ Wrong -->
+<link rel="alternate" hreflang="fr" href="/fr/page" />
+```
+
+### Rule 7: No Hreflang on Non-200 Pages
+- Don't include hreflang tags on pages that return 3xx, 4xx, or 5xx
+- Don't point hreflang to pages that redirect
+
+---
+
+## Common Error Patterns
+
+### Error 1: Missing Return Tags
+**Symptom**: hreflang is configured on the main language but not on alternate versions.
+**Fix**: Add reciprocal hreflang tags on ALL language variants.
+
+### Error 2: Wrong Canonical + Hreflang
+**Symptom**: Page A hreflang → Page B, but Page B canonical → Page C.
+**Fix**: Align canonical and hreflang targets.
+
+### Error 3: Missing Self-Reference
+**Symptom**: Page lists other language versions but not itself.
+**Fix**: Add `hreflang` tag with the current page's own language/URL.
+
+### Error 4: Inconsistent URLs
+**Symptom**: hreflang uses `http://` but site is on `https://`, or trailing slash mismatch.
+**Fix**: Use exact canonical URL (protocol, www/non-www, trailing slash).
+
+### Error 5: Language vs Region Confusion
+**Symptom**: Using `hreflang="fr"` for France and `hreflang="fr"` for Canada.
+**Fix**: Use `hreflang="fr-FR"` and `hreflang="fr-CA"` to differentiate.
+
+### Error 6: Missing x-default
+**Symptom**: Users in unsupported regions see random language version.
+**Fix**: Add `x-default` pointing to language selector or English version.
+
+---
+
+## Sitemap Implementation (Recommended for 50+ pages)
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
+        xmlns:xhtml="http://www.w3.org/1999/xhtml">
+  <url>
+    <loc>https://example.com/en/page</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/page"/>
+    <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/page"/>
+    <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/page"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/en/page"/>
+  </url>
+</urlset>
+```
+
+---
+
+## Audit Checklist
+
+| # | Check | Priority |
+|---|-------|----------|
+| 1 | All hreflang language codes are valid ISO 639-1 | 🔴 Critical |
+| 2 | All hreflang country codes are valid ISO 3166-1 | 🔴 Critical |
+| 3 | Every page has self-referencing hreflang | 🔴 Critical |
+| 4 | All hreflang tags have return tags | 🔴 Critical |
+| 5 | All hreflang URLs are absolute | 🔴 Critical |
+| 6 | x-default is specified | 🟠 High |
+| 7 | Hreflang URLs match canonical URLs | 🟠 High |
+| 8 | No hreflang on non-200 pages | 🟠 High |
+| 9 | No hreflang pointing to redirecting URLs | 🟠 High |
+| 10 | Consistent protocol (https) and www/non-www | 🟡 Medium |
+| 11 | Language/region differentiation correct | 🟡 Medium |
+| 12 | Sitemap implementation for 50+ pages | 🟡 Medium |