bmad-plus 0.2.0 → 0.3.1

package/oveanet-pack/seo-audit-360/scripts/seo_parse.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+"""
+SEO Parse — HTML parser for SEO element extraction.
+
+Extracts: title, meta tags, canonicals, headings, images, links (internal/external),
+schema (JSON-LD), Open Graph, Twitter Cards, hreflang, word count, text/code ratio.
+
+Author: Laurent Rochetta
+License: MIT
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+from typing import Optional
+from urllib.parse import urljoin, urlparse
+
+try:
+    from bs4 import BeautifulSoup
+except ImportError:
+    print("Error: beautifulsoup4 required. Install: pip install beautifulsoup4", file=sys.stderr)
+    sys.exit(1)
+
+# Use lxml if available for speed, fallback to html.parser
+try:
+    import lxml  # noqa: F401
+    HTML_PARSER = "lxml"
+except ImportError:
+    HTML_PARSER = "html.parser"
+
+
+def parse_html(html: str, base_url: Optional[str] = None) -> dict:
+    """
+    Parse HTML and extract all SEO-relevant elements.
+
+    Args:
+        html: Raw HTML content
+        base_url: Base URL for resolving relative links
+
+    Returns:
+        Comprehensive dictionary of SEO data
+    """
+    soup = BeautifulSoup(html, HTML_PARSER)
+
+    result = {
+        "title": None,
+        "title_length": 0,
+        "meta_description": None,
+        "meta_description_length": 0,
+        "meta_robots": None,
+        "meta_viewport": None,
+        "canonical": None,
+        "headings": {"h1": [], "h2": [], "h3": [], "h4": []},
+        "images": [],
+        "links": {"internal": [], "external": [], "broken_candidates": []},
+        "schema_blocks": [],
+        "open_graph": {},
+        "twitter_card": {},
+        "hreflang": [],
+        "word_count": 0,
+        "html_size_bytes": len(html.encode("utf-8")),
+        "text_ratio": 0.0,
+        "has_lang_attr": False,
+        "lang": None,
+        "scripts_count": 0,
+        "stylesheets_count": 0,
+        "dom_depth_estimate": 0,
+        "security_headers_hints": {},
+    }
+
+    # ── Title ──
+    title_tag = soup.find("title")
+    if title_tag:
+        result["title"] = title_tag.get_text(strip=True)
+        result["title_length"] = len(result["title"])
+
+    # ── Meta Tags ──
+    for meta in soup.find_all("meta"):
+        name = (meta.get("name") or "").lower()
+        property_attr = (meta.get("property") or "").lower()
+        content = meta.get("content", "")
+
+        if name == "description":
+            result["meta_description"] = content
+            result["meta_description_length"] = len(content)
+        elif name == "robots":
+            result["meta_robots"] = content
+        elif name == "viewport":
+            result["meta_viewport"] = content
+
+        # Open Graph
+        if property_attr.startswith("og:"):
+            result["open_graph"][property_attr] = content
+
+        # Twitter Card
+        if name.startswith("twitter:"):
+            result["twitter_card"][name] = content
+
+    # ── Language ──
+    html_tag = soup.find("html")
+    if html_tag and html_tag.get("lang"):
+        result["has_lang_attr"] = True
+        result["lang"] = html_tag.get("lang")
+
+    # ── Canonical ──
+    canonical = soup.find("link", rel="canonical")
+    if canonical:
+        result["canonical"] = canonical.get("href")
+
+    # ── Hreflang ──
+    for link in soup.find_all("link", rel="alternate"):
+        hreflang = link.get("hreflang")
+        if hreflang:
+            result["hreflang"].append({
+                "lang": hreflang,
+                "href": link.get("href"),
+            })
+
+    # ── Headings ──
+    for level in ["h1", "h2", "h3", "h4"]:
+        for tag in soup.find_all(level):
+            text = tag.get_text(strip=True)
+            if text:
+                result["headings"][level].append(text)
+
+    # ── Images ──
+    for img in soup.find_all("img"):
+        src = img.get("src", "")
+        if base_url and src:
+            src = urljoin(base_url, src)
+
+        has_alt = img.get("alt") is not None
+        alt_text = img.get("alt", "")
+        has_dimensions = bool(img.get("width") and img.get("height"))
+
+        result["images"].append({
+            "src": src,
+            "alt": alt_text,
+            "has_alt": has_alt,
+            "alt_empty": has_alt and alt_text.strip() == "",
+            "width": img.get("width"),
+            "height": img.get("height"),
+            "has_dimensions": has_dimensions,
+            "loading": img.get("loading"),
+            "srcset": img.get("srcset") is not None,
+        })
+
+    # ── Links ──
+    if base_url:
+        base_domain = urlparse(base_url).netloc
+
+        for a in soup.find_all("a", href=True):
+            href = a.get("href", "")
+            if not href or href.startswith("#") or href.startswith("javascript:"):
+                continue
+
+            full_url = urljoin(base_url, href)
+            parsed = urlparse(full_url)
+
+            link_data = {
+                "href": full_url,
+                "text": a.get_text(strip=True)[:100],
+                "rel": a.get("rel", []),
+                "is_nofollow": "nofollow" in (a.get("rel") or []),
+                "target": a.get("target"),
+            }
+
+            if parsed.netloc == base_domain:
+                result["links"]["internal"].append(link_data)
+            else:
+                result["links"]["external"].append(link_data)
+
+    # ── Schema (JSON-LD) ──
+    for script in soup.find_all("script", type="application/ld+json"):
+        try:
+            schema_data = json.loads(script.string)
+            if isinstance(schema_data, dict):
+                result["schema_blocks"].append({
+                    "type": schema_data.get("@type", "unknown"),
+                    "data": schema_data,
+                })
+            elif isinstance(schema_data, list):
+                for item in schema_data:
+                    if isinstance(item, dict):
+                        result["schema_blocks"].append({
+                            "type": item.get("@type", "unknown"),
+                            "data": item,
+                        })
+        except (json.JSONDecodeError, TypeError):
+            result["schema_blocks"].append({"type": "PARSE_ERROR", "data": None})
+
+    # ── Resource Counts ──
+    result["scripts_count"] = len(soup.find_all("script"))
+    result["stylesheets_count"] = len(soup.find_all("link", rel="stylesheet"))
+
+    # ── Word Count & Text Ratio ──
+    text_soup = BeautifulSoup(html, HTML_PARSER)
+    for element in text_soup(["script", "style", "nav", "footer", "header", "noscript"]):
+        element.decompose()
+
+    visible_text = text_soup.get_text(separator=" ", strip=True)
+    words = re.findall(r"\b\w+\b", visible_text)
+    result["word_count"] = len(words)
+
+    text_bytes = len(visible_text.encode("utf-8"))
+    if result["html_size_bytes"] > 0:
+        result["text_ratio"] = round(text_bytes / result["html_size_bytes"], 3)
+
+    return result
+
+
+# ── CLI ────────────────────────────────────────────────────────────
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="SEO Parse — HTML parser for SEO analysis (BMAD+ SEO Engine)"
+    )
+    parser.add_argument("file", nargs="?", help="HTML file to parse")
+    parser.add_argument("--url", "-u", help="Base URL for resolving relative links")
+    parser.add_argument("--json", "-j", action="store_true", help="Output as JSON")
+
+    args = parser.parse_args()
+
+    if args.file:
+        real_path = os.path.realpath(args.file)
+        if not os.path.isfile(real_path):
+            print(f"Error: File not found: {args.file}", file=sys.stderr)
+            sys.exit(1)
+        with open(real_path, "r", encoding="utf-8") as f:
+            html = f.read()
+    else:
+        html = sys.stdin.read()
+
+    result = parse_html(html, args.url)
+
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        print(f"Title: {result['title']} ({result['title_length']} chars)")
+        print(f"Meta Description: {result['meta_description'][:80] + '...' if result['meta_description'] and len(result['meta_description']) > 80 else result['meta_description']}")
+        print(f"Canonical: {result['canonical']}")
+        print(f"Language: {result['lang']}")
+        print(f"H1: {len(result['headings']['h1'])} | H2: {len(result['headings']['h2'])} | H3: {len(result['headings']['h3'])}")
+        print(f"Images: {len(result['images'])} (missing alt: {sum(1 for i in result['images'] if not i['has_alt'])})")
+        print(f"Internal Links: {len(result['links']['internal'])} | External: {len(result['links']['external'])}")
+        print(f"Schema Blocks: {len(result['schema_blocks'])} ({', '.join(s['type'] for s in result['schema_blocks'])})")
+        print(f"Word Count: {result['word_count']:,}")
+        print(f"Text/HTML Ratio: {result['text_ratio']:.1%}")
+        print(f"Scripts: {result['scripts_count']} | Stylesheets: {result['stylesheets_count']}")
+
+
+if __name__ == "__main__":
+    main()

package/oveanet-pack/seo-audit-360/scripts/seo_screenshot.py

@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+"""
+SEO Screenshot — Viewport screenshot capture for visual SEO analysis.
+
+Features:
+- Mobile and desktop viewport presets
+- Above-the-fold element detection
+- Full-page capture option
+- PNG output with configurable quality
+
+Requires: playwright (pip install playwright && playwright install chromium)
+
+Author: Laurent Rochetta
+License: MIT
+"""
+
+import argparse
+import sys
+
+
+VIEWPORTS = {
+    "mobile": {"width": 375, "height": 812, "device_scale_factor": 3, "is_mobile": True},
+    "tablet": {"width": 768, "height": 1024, "device_scale_factor": 2, "is_mobile": True},
+    "desktop": {"width": 1440, "height": 900, "device_scale_factor": 1, "is_mobile": False},
+    "desktop-hd": {"width": 1920, "height": 1080, "device_scale_factor": 1, "is_mobile": False},
+}
+
+
+def capture_screenshot(
+    url: str,
+    output: str = "screenshot.png",
+    viewport: str = "desktop",
+    full_page: bool = False,
+    wait_ms: int = 2000,
+):
+    """
+    Capture a viewport screenshot of a URL using Playwright.
+
+    Args:
+        url: URL to capture
+        output: Output file path (.png)
+        viewport: Viewport preset (mobile, tablet, desktop, desktop-hd)
+        full_page: Capture full page scroll or just viewport
+        wait_ms: Wait time after page load (ms)
+    """
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError:
+        print(
+            "Error: playwright required.\n"
+            "Install: pip install playwright && playwright install chromium",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    vp = VIEWPORTS.get(viewport, VIEWPORTS["desktop"])
+
+    with sync_playwright() as p:
+        browser = p.chromium.launch(headless=True)
+        context = browser.new_context(
+            viewport={"width": vp["width"], "height": vp["height"]},
+            device_scale_factor=vp["device_scale_factor"],
+            is_mobile=vp["is_mobile"],
+            user_agent=(
+                "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) "
+                "AppleWebKit/605.1.15 Mobile/15E148 Safari/604.1"
+                if vp["is_mobile"]
+                else "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+                "(KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36 BMADSEOEngine/2.0"
+            ),
+        )
+
+        page = context.new_page()
+
+        try:
+            page.goto(url, wait_until="networkidle", timeout=30000)
+        except Exception:
+            # Fallback: wait for load event instead
+            page.goto(url, wait_until="load", timeout=30000)
+
+        # Wait for dynamic content
+        page.wait_for_timeout(wait_ms)
+
+        # Capture screenshot
+        page.screenshot(path=output, full_page=full_page)
+
+        # Gather above-the-fold metrics
+        metrics = page.evaluate("""() => {
+            const viewportHeight = window.innerHeight;
+            const viewportWidth = window.innerWidth;
+
+            // Find CTAs above the fold
+            const ctas = [];
+            const buttons = document.querySelectorAll('a, button, [role="button"]');
+            buttons.forEach(el => {
+                const rect = el.getBoundingClientRect();
+                if (rect.top < viewportHeight && rect.bottom > 0) {
+                    const text = el.textContent.trim().substring(0, 50);
+                    if (text && (
+                        /sign.?up|get.?start|try|buy|contact|demo|free|download|subscribe/i.test(text)
+                    )) {
+                        ctas.push({
+                            text: text,
+                            tag: el.tagName,
+                            top: Math.round(rect.top),
+                            visible: rect.width > 0 && rect.height > 0,
+                        });
+                    }
+                }
+            });
+
+            // Find hero/LCP candidate
+            const images = document.querySelectorAll('img');
+            let largestImage = null;
+            let largestArea = 0;
+            images.forEach(img => {
+                const rect = img.getBoundingClientRect();
+                const area = rect.width * rect.height;
+                if (area > largestArea && rect.top < viewportHeight) {
+                    largestArea = area;
+                    largestImage = {
+                        src: img.src.substring(0, 100),
+                        width: Math.round(rect.width),
+                        height: Math.round(rect.height),
+                        top: Math.round(rect.top),
+                    };
+                }
+            });
+
+            // Check for horizontal scroll
+            const hasHorizontalScroll = document.documentElement.scrollWidth > viewportWidth;
+
+            // Font size check
+            const body = document.body;
+            const bodyFontSize = body ? parseFloat(getComputedStyle(body).fontSize) : 16;
+
+            return {
+                viewportWidth,
+                viewportHeight,
+                ctas_above_fold: ctas.length,
+                cta_details: ctas.slice(0, 5),
+                largest_image_above_fold: largestImage,
+                has_horizontal_scroll: hasHorizontalScroll,
+                body_font_size_px: bodyFontSize,
+                dom_element_count: document.querySelectorAll('*').length,
+            };
+        }""")
+
+        browser.close()
+
+    return metrics
+
+
+# ── CLI ────────────────────────────────────────────────────────────
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="SEO Screenshot — Viewport capture (BMAD+ SEO Engine)"
+    )
+    parser.add_argument("url", help="URL to capture")
+    parser.add_argument("--output", "-o", default="screenshot.png", help="Output file path")
+    parser.add_argument(
+        "--viewport", "-v",
+        choices=list(VIEWPORTS.keys()), default="desktop",
+        help="Viewport preset"
+    )
+    parser.add_argument("--full", action="store_true", help="Capture full page (not just viewport)")
+    parser.add_argument("--wait", "-w", type=int, default=2000, help="Wait after load (ms)")
+    parser.add_argument("--json", "-j", action="store_true", help="Output metrics as JSON")
+
+    args = parser.parse_args()
+
+    import json
+
+    metrics = capture_screenshot(
+        url=args.url,
+        output=args.output,
+        viewport=args.viewport,
+        full_page=args.full,
+        wait_ms=args.wait,
+    )
+
+    print(f"Screenshot saved: {args.output}", file=sys.stderr)
+
+    if args.json:
+        print(json.dumps(metrics, indent=2))
+    else:
+        print(f"\nAbove-the-Fold Analysis ({args.viewport}):")
+        print(f"  Viewport: {metrics['viewportWidth']}×{metrics['viewportHeight']}")
+        print(f"  CTAs above fold: {metrics['ctas_above_fold']}")
+        for cta in metrics.get("cta_details", []):
+            print(f"    - \"{cta['text']}\" ({cta['tag']}, top: {cta['top']}px)")
+        if metrics.get("largest_image_above_fold"):
+            img = metrics["largest_image_above_fold"]
+            print(f"  Largest image: {img['width']}×{img['height']} at y={img['top']}px")
+        print(f"  Horizontal scroll: {'⚠️ YES' if metrics['has_horizontal_scroll'] else '✅ No'}")
+        print(f"  Body font size: {metrics['body_font_size_px']}px {'✅' if metrics['body_font_size_px'] >= 16 else '⚠️ <16px'}")
+        print(f"  DOM elements: {metrics['dom_element_count']:,}")
+
+
+if __name__ == "__main__":
+    main()

package/oveanet-pack/seo-audit-360/templates/seo-audit-workflow.md

@@ -0,0 +1,241 @@
+# SEO Audit Workflow — BMAD+ SEO Engine v2.0
+
+> Author: Laurent Rochetta | By Oveanet × Laurent Rochetta
+
+## Overview
+
+This workflow orchestrates the 3 SEO Engine agents (Scout, Judge, Chief) through 6 phases to produce a comprehensive audit with scored results and actionable fixes.
+
+---
+
+## Phase 1 — Reconnaissance (Scout solo)
+
+**Duration**: ~2 min | **Agent**: Scout (Crawler role)
+
+1. Fetch homepage + `/robots.txt` + `/sitemap.xml`
+2. Detect business type (SaaS, e-commerce, local, publisher, agency)
+3. Mini-crawl: discover 10–25 pages via sitemap + internal links
+4. Detect rendering architecture (SSR / CSR / hybrid)
+5. Check for `/llms.txt` and `/llms-full.txt`
+
+**Checkpoint**: "Identified a [type] site with [N] pages. Continue full audit?"
+
+**Tools**:
+```bash
+python scripts/seo_fetch.py [URL] --json
+python scripts/seo_crawl.py [URL] --depth 2 --max 25 --json
+```
+
+---
+
+## Phase 2 — Deep Scan (Scout + Judge in PARALLEL)
+
+**Duration**: ~5 min | **Agents**: Scout (Inspector) + Judge (Content Expert + Schema Master)
+
+### Scout inspects (9 categories):
+1. Crawlability (robots.txt, noindex, crawl depth)
+2. Indexability (canonicals, duplicates, pagination)
+3. Security (HTTPS, HSTS, CSP, X-Frame-Options)
+4. URL Structure (clean URLs, redirects, trailing slashes)
+5. Mobile (viewport, touch targets, font size)
+6. Core Web Vitals signals from source HTML
+7. Structured Data detection (pass to Judge)
+8. JavaScript rendering (CSR/SSR, SPA detection)
+9. IndexNow protocol
+
+### Judge analyzes (in parallel):
+1. E-E-A-T evaluation (Experience, Expertise, Authority, Trust)
+2. Content quality (word count, readability, keyword optimization)
+3. Schema validation (JSON-LD, types, deprecation status)
+4. Image audit (alt text, dimensions, format, lazy loading)
+5. Internal/external link analysis
+6. AI content detection markers
+
+**Tools**:
+```bash
+python scripts/seo_parse.py page.html --url [URL] --json
+python scripts/seo_screenshot.py [URL] --viewport mobile --json
+python scripts/seo_screenshot.py [URL] --viewport desktop --json
+```
+
+---
+
+## Phase 3 — AI Readiness & GEO (Judge solo)
+
+**Duration**: ~3 min | **Agent**: Judge (GEO Analyst role)
+
+1. Check AI crawler access (GPTBot, ClaudeBot, PerplexityBot, OAI-SearchBot)
+2. Verify llms.txt compliance
+3. Check RSL 1.0 licensing
+4. Score passage-level citability (134–167 word blocks)
+5. Analyze brand mention signals
+6. Compute **AI Readiness Score (0–100)**
+
+Reference: `ref/geo-signals.md`
+
+---
+
+## Phase 4 — Scoring & Synthesis (Chief solo)
+
+**Duration**: ~2 min | **Agent**: Chief (Scorer role)
+
+Compute **SEO Health Score (0–100)** from weighted categories:
+
+| Category | Weight |
+|----------|--------|
+| Technical SEO | 20% |
+| Content & E-E-A-T | 22% |
+| On-Page SEO | 18% |
+| Schema | 10% |
+| Performance (CWV) | 12% |
+| AI Readiness (GEO) | 12% |
+| Images | 6% |
+
+Output: Score breakdown with visual indicators per category.
+
+---
+
+## Phase 5 — Action Plan & Auto-Fixes (Chief solo)
+
+**Duration**: ~3 min | **Agent**: Chief (Strategist role)
+
+1. Classify all issues: 🔴 Critical → 🟠 High → 🟡 Medium → 🟢 Low
+2. Identify Quick Wins (high impact / low effort)
+3. Generate 30/60/90-day roadmap
+4. **Auto-generate code fixes** for:
+   - Missing/broken meta tags (title, description)
+   - Schema JSON-LD blocks (from templates)
+   - robots.txt improvements (AI crawler access)
+   - llms.txt file generation
+   - Image alt text suggestions
+5. **Checkpoint**: "Here's the plan. Want me to apply the fixes automatically?"
+
+---
+
+## Phase 5b — PageSpeed Perfection Loop (Scout + Chief iterative)
+
+> **This is the battle-tested loop from our oveanet.ch optimization.**
+> Goal: Achieve **100% on all 4 PageSpeed Insights categories** (Performance, Accessibility, Best Practices, SEO).
+
+### The Loop
+
+```
+┌─────────────────────────────────────┐
+│  1. Run PageSpeed Insights audit    │
+│     (via API or manual)             │
+│           │                         │
+│           ▼                         │
+│  2. Parse failing audits            │
+│     Group by category + priority    │
+│           │                         │
+│           ▼                         │
+│  3. Apply top-priority fix          │
+│     (one fix at a time)             │
+│           │                         │
+│           ▼                         │
+│  4. Re-run PageSpeed                │
+│     Verify fix + no regressions     │
+│           │                         │
+│           ▼                         │
+│  5. Score improved?                 │
+│     YES → Continue to next fix      │
+│     NO → Revert and try different   │
+│           approach                  │
+│           │                         │
+│           ▼                         │
+│  6. All 4 categories = 100%?        │
+│     YES → Done ✅                   │
+│     NO → Go to step 2              │
+└─────────────────────────────────────┘
+```
+
+### PageSpeed Fix Priority Order
+1. **Performance** (hardest — tackle first):
+   - Eliminate render-blocking resources
+   - Properly size images (WebP/AVIF + responsive)
+   - Reduce unused CSS/JS
+   - Defer offscreen images
+   - Minimize main-thread work
+   - Reduce server response time (TTFB)
+   - Preload LCP image
+
+2. **Accessibility** (usually quick wins):
+   - Add alt text to all images
+   - Fix color contrast ratios (4.5:1 minimum)
+   - Add ARIA labels to interactive elements
+   - Ensure heading hierarchy
+   - Add lang attribute to HTML
+   - Ensure form labels
+
+3. **Best Practices**:
+   - HTTPS + no mixed content
+   - No browser errors in console
+   - Remove deprecated APIs
+   - Add proper CSP headers
+
+4. **SEO** (usually easiest):
+   - Add meta description
+   - Ensure crawlable links
+   - Valid robots.txt
+   - Proper viewport meta
+   - Descriptive link text
+
+### Key Rules
+- **One fix at a time** — never batch multiple changes, you need to isolate impact
+- **Always re-test** — PageSpeed scores can regress with seemingly unrelated changes
+- **Mobile first** — always test mobile viewport (Google uses mobile for indexing)
+- **Field vs Lab** — Lab scores (Lighthouse) can differ from field data (CrUX). Target lab 100% first
+
+---
+
+## Phase 6 — Monitoring (Scout, optional)
+
+**Duration**: ongoing | **Agent**: Scout (Crawler role)
+
+1. Save audit results to `.bmad-seo/history/[domain]-[date].json`
+2. On re-audit: compare with previous results
+3. Track: issues resolved, new issues, score evolution
+4. Generate progress report with deltas
+
+---
+
+## Command Quick Reference
+
+```bash
+# Full audit (all 6 phases)
+/seo full https://example.com
+
+# Quick audit (Phases 1-4 only)
+/seo quick https://example.com
+
+# Individual commands
+/seo technical https://example.com
+/seo content https://example.com
+/seo geo https://example.com
+/seo schema https://example.com
+/seo images https://example.com
+/seo hreflang https://example.com
+
+# PageSpeed perfection loop
+/seo pagespeed https://example.com
+
+# Strategic planning
+/seo plan saas|ecommerce|local|publisher|agency
+
+# Auto-fix generation
+/seo fix
+
+# Monitoring
+/seo history
+/seo compare
+```
+
+---
+
+## Tips for Best Results
+
+1. **Start with `/seo full`** for the first audit — it gives you the complete picture
+2. **Use `/seo pagespeed`** after fixing major issues to chase 100% scores
+3. **Re-run monthly** with `/seo compare` to track progress
+4. **Feed the AI crawlers**: Allow GPTBot + ClaudeBot + PerplexityBot in robots.txt
+5. **Check GEO separately**: AI search visibility evolves fast, audit quarterly with `/seo geo`