bmad-plus 0.4.1 → 0.4.3

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

@@ -0,0 +1,356 @@
+{
+  "meta": {
+    "author": "Laurent Rochetta",
+    "engine": "BMAD+ SEO Engine v2.0",
+    "schema_org_version": "29.4",
+    "last_updated": "2026-03-19"
+  },
+  "templates": [
+    {
+      "type": "Organization",
+      "use_case": "Company/brand homepage",
+      "template": {
+        "@context": "https://schema.org",
+        "@type": "Organization",
+        "name": "[Company Name]",
+        "url": "[Website URL]",
+        "logo": "[Logo URL]",
+        "description": "[Company description]",
+        "foundingDate": "[YYYY]",
+        "contactPoint": {
+          "@type": "ContactPoint",
+          "telephone": "[Phone]",
+          "contactType": "customer service",
+          "availableLanguage": ["English", "French"]
+        },
+        "sameAs": [
+          "[Facebook URL]",
+          "[LinkedIn URL]",
+          "[Twitter URL]",
+          "[YouTube URL]"
+        ]
+      }
+    },
+    {
+      "type": "LocalBusiness",
+      "use_case": "Physical business location",
+      "template": {
+        "@context": "https://schema.org",
+        "@type": "LocalBusiness",
+        "name": "[Business Name]",
+        "url": "[Website URL]",
+        "image": "[Photo URL]",
+        "telephone": "[Phone]",
+        "priceRange": "[$$]",
+        "address": {
+          "@type": "PostalAddress",
+          "streetAddress": "[Street]",
+          "addressLocality": "[City]",
+          "addressRegion": "[State/Region]",
+          "postalCode": "[ZIP]",
+          "addressCountry": "[Country Code]"
+        },
+        "geo": {
+          "@type": "GeoCoordinates",
+          "latitude": "[Lat]",
+          "longitude": "[Long]"
+        },
+        "openingHoursSpecification": [
+          {
+            "@type": "OpeningHoursSpecification",
+            "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
+            "opens": "09:00",
+            "closes": "18:00"
+          }
+        ]
+      }
+    },
+    {
+      "type": "Article",
+      "use_case": "Blog posts, articles",
+      "template": {
+        "@context": "https://schema.org",
+        "@type": "Article",
+        "headline": "[Title - max 110 chars]",
+        "description": "[Summary]",
+        "author": {
+          "@type": "Person",
+          "name": "[Author Name]",
+          "url": "[Author Profile URL]"
+        },
+        "datePublished": "[YYYY-MM-DD]",
+        "dateModified": "[YYYY-MM-DD]",
+        "image": "[Featured Image URL]",
+        "publisher": {
+          "@type": "Organization",
+          "name": "[Publisher Name]",
+          "logo": {
+            "@type": "ImageObject",
+            "url": "[Logo URL]"
+          }
+        },
+        "mainEntityOfPage": {
+          "@type": "WebPage",
+          "@id": "[Page URL]"
+        }
+      }
+    },
+    {
+      "type": "Product",
+      "use_case": "E-commerce product pages",
+      "template": {
+        "@context": "https://schema.org",
+        "@type": "Product",
+        "name": "[Product Name]",
+        "image": "[Product Image URL]",
+        "description": "[Product Description]",
+        "sku": "[SKU]",
+        "brand": {
+          "@type": "Brand",
+          "name": "[Brand Name]"
+        },
+        "offers": {
+          "@type": "Offer",
+          "url": "[Product URL]",
+          "price": "[Price]",
+          "priceCurrency": "[Currency Code]",
+          "availability": "https://schema.org/InStock",
+          "seller": {
+            "@type": "Organization",
+            "name": "[Seller Name]"
+          }
+        },
+        "aggregateRating": {
+          "@type": "AggregateRating",
+          "ratingValue": "[4.5]",
+          "reviewCount": "[120]"
+        }
+      }
+    },
+    {
+      "type": "WebSite",
+      "use_case": "Site-level with sitelinks search box",
+      "template": {
+        "@context": "https://schema.org",
+        "@type": "WebSite",
+        "name": "[Site Name]",
+        "url": "[Homepage URL]",
+        "potentialAction": {
+          "@type": "SearchAction",
+          "target": {
+            "@type": "EntryPoint",
+            "urlTemplate": "[Search URL]?q={search_term_string}"
+          },
+          "query-input": "required name=search_term_string"
+        }
+      }
+    },
+    {
+      "type": "BreadcrumbList",
+      "use_case": "Navigation breadcrumbs",
+      "template": {
+        "@context": "https://schema.org",
+        "@type": "BreadcrumbList",
+        "itemListElement": [
+          {
+            "@type": "ListItem",
+            "position": 1,
+            "name": "Home",
+            "item": "[Homepage URL]"
+          },
+          {
+            "@type": "ListItem",
+            "position": 2,
+            "name": "[Category]",
+            "item": "[Category URL]"
+          },
+          {
+            "@type": "ListItem",
+            "position": 3,
+            "name": "[Current Page]"
+          }
+        ]
+      }
+    },
+    {
+      "type": "Person",
+      "use_case": "Author/team member profiles (E-E-A-T)",
+      "template": {
+        "@context": "https://schema.org",
+        "@type": "Person",
+        "name": "[Full Name]",
+        "jobTitle": "[Job Title]",
+        "url": "[Profile URL]",
+        "image": "[Photo URL]",
+        "description": "[Professional bio]",
+        "worksFor": {
+          "@type": "Organization",
+          "name": "[Company Name]"
+        },
+        "sameAs": [
+          "[LinkedIn URL]",
+          "[Twitter URL]",
+          "[GitHub URL]"
+        ]
+      }
+    },
+    {
+      "type": "Service",
+      "use_case": "Service business pages",
+      "template": {
+        "@context": "https://schema.org",
+        "@type": "Service",
+        "name": "[Service Name]",
+        "description": "[Service Description]",
+        "provider": {
+          "@type": "Organization",
+          "name": "[Provider Name]",
+          "url": "[Provider URL]"
+        },
+        "areaServed": {
+          "@type": "City",
+          "name": "[Service Area]"
+        },
+        "offers": {
+          "@type": "Offer",
+          "price": "[Starting Price]",
+          "priceCurrency": "[Currency]"
+        }
+      }
+    },
+    {
+      "type": "VideoObject",
+      "use_case": "Video content pages",
+      "template": {
+        "@context": "https://schema.org",
+        "@type": "VideoObject",
+        "name": "[Video Title]",
+        "description": "[Video Description]",
+        "thumbnailUrl": "[Thumbnail URL]",
+        "uploadDate": "[YYYY-MM-DD]",
+        "duration": "[PT1H30M]",
+        "contentUrl": "[Video File URL]",
+        "embedUrl": "[Embed URL]",
+        "publisher": {
+          "@type": "Organization",
+          "name": "[Publisher]"
+        }
+      }
+    },
+    {
+      "type": "Event",
+      "use_case": "Events and conferences",
+      "template": {
+        "@context": "https://schema.org",
+        "@type": "Event",
+        "name": "[Event Name]",
+        "description": "[Event Description]",
+        "startDate": "[YYYY-MM-DDTHH:MM]",
+        "endDate": "[YYYY-MM-DDTHH:MM]",
+        "location": {
+          "@type": "Place",
+          "name": "[Venue Name]",
+          "address": {
+            "@type": "PostalAddress",
+            "streetAddress": "[Street]",
+            "addressLocality": "[City]",
+            "addressCountry": "[Country]"
+          }
+        },
+        "organizer": {
+          "@type": "Organization",
+          "name": "[Organizer Name]",
+          "url": "[Organizer URL]"
+        },
+        "offers": {
+          "@type": "Offer",
+          "price": "[Price]",
+          "priceCurrency": "[Currency]",
+          "url": "[Ticket URL]",
+          "availability": "https://schema.org/InStock"
+        }
+      }
+    },
+    {
+      "type": "SoftwareApplication",
+      "use_case": "SaaS and app pages",
+      "template": {
+        "@context": "https://schema.org",
+        "@type": "SoftwareApplication",
+        "name": "[App Name]",
+        "description": "[App Description]",
+        "applicationCategory": "[Category]",
+        "operatingSystem": "[OS]",
+        "offers": {
+          "@type": "Offer",
+          "price": "[Price or 0]",
+          "priceCurrency": "[Currency]"
+        },
+        "aggregateRating": {
+          "@type": "AggregateRating",
+          "ratingValue": "[Rating]",
+          "ratingCount": "[Count]"
+        }
+      }
+    },
+    {
+      "type": "ProfilePage",
+      "use_case": "Author/creator profile pages (E-E-A-T)",
+      "template": {
+        "@context": "https://schema.org",
+        "@type": "ProfilePage",
+        "mainEntity": {
+          "@type": "Person",
+          "name": "[Author Name]",
+          "url": "[Profile URL]",
+          "description": "[Bio and expertise]",
+          "sameAs": ["[LinkedIn]", "[Twitter]"]
+        }
+      }
+    },
+    {
+      "type": "ProductGroup",
+      "use_case": "E-commerce product variants",
+      "template": {
+        "@context": "https://schema.org",
+        "@type": "ProductGroup",
+        "name": "[Product Name]",
+        "description": "[Group description]",
+        "productGroupID": "[Group ID]",
+        "variesBy": ["https://schema.org/size", "https://schema.org/color"],
+        "hasVariant": [
+          {
+            "@type": "Product",
+            "name": "[Variant Name]",
+            "sku": "[SKU]",
+            "color": "[Color]",
+            "size": "[Size]",
+            "offers": {
+              "@type": "Offer",
+              "price": "[Price]",
+              "priceCurrency": "[Currency]",
+              "availability": "https://schema.org/InStock"
+            }
+          }
+        ]
+      }
+    },
+    {
+      "type": "Certification",
+      "use_case": "Product certifications (April 2025)",
+      "template": {
+        "@context": "https://schema.org",
+        "@type": "Product",
+        "name": "[Product Name]",
+        "hasCertification": {
+          "@type": "Certification",
+          "certificationIdentification": "[Certification Name]",
+          "issuedBy": {
+            "@type": "Organization",
+            "name": "[Issuing Organization]"
+          }
+        }
+      }
+    }
+  ]
+}

package/src/bmad-plus/agents/pack-seo/seo-chief.md

@@ -0,0 +1,294 @@
+# SEO Chief — Strategist & Reporter Agent
+
+> *"I turn raw data into scored insights and actionable roadmaps."*
+
+## Identity
+
+You are **Chief**, the strategist and reporting agent of the BMAD+ SEO Engine. You aggregate findings from Scout and Judge, compute the SEO Health Score, generate prioritized action plans, and produce publication-ready reports.
+
+## Roles
+
+### Role: Scorer
+**Trigger**: Score calculation, audit synthesis, category aggregation
+- Compute the **SEO Health Score (0–100)** from weighted category inputs
+- Break down scores per category with visual indicators
+- Compare against industry benchmarks
+- Flag score changes when monitoring is active
+
+### Role: Strategist
+**Trigger**: Action plan, roadmap, quick wins, fix generation
+- Generate prioritized issue lists (Critical → High → Medium → Low)
+- Identify quick wins (highest impact/effort ratio)
+- Create 30/60/90-day roadmaps
+- **Auto-generate code fixes** for common issues (meta tags, schema JSON-LD, robots.txt improvements)
+- Estimate impact and effort for each recommendation
+
+### Role: Reporter
+**Trigger**: Report generation, export, summary
+- Produce structured Markdown reports
+- 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`
+
+---
+
+## SEO Health Score — Weighting System
+
+| Category | Weight | Source Agent | Phase |
+|----------|--------|-------------|-------|
+| Technical SEO | 20% | Scout | Phase 2 |
+| Content & E-E-A-T | 22% | Judge | Phase 2 |
+| On-Page SEO | 18% | Scout + Judge | Phase 2 |
+| Schema & Structured Data | 10% | Judge | Phase 2 |
+| Performance (CWV) | 12% | Scout | Phase 2 |
+| AI Search Readiness (GEO) | 12% | Judge | Phase 3 |
+| Images & Media | 6% | Judge | Phase 2 |
+
+### Score Interpretation
+| Score Range | Rating | Actions Required |
+|-------------|--------|-----------------|
+| 90–100 | 🟢 Excellent | Monitoring + minor optimizations |
+| 75–89 | 🔵 Good | Targeted improvements recommended |
+| 60–74 | 🟡 Needs Work | Significant optimizations required |
+| 40–59 | 🟠 Poor | Major overhaul needed |
+| 0–39 | 🔴 Critical | Fundamental issues blocking performance |
+
+### Category Score Calculation
+Each category is scored 0–100 based on the checklist pass rate:
+- ✅ Pass = full points for that item
+- ⚠️ Warning = 50% points (issue exists but not blocking)
+- ❌ Fail = 0 points (blocking issue)
+
+**Final Score** = Σ(category_score × category_weight)
+
+---
+
+## Issue Priority Classification
+
+### 🔴 Critical (fix immediately)
+- Blocks indexing entirely (noindex on important pages)
+- Causes penalties (cloaking, hidden text, doorway pages)
+- Security vulnerabilities (no HTTPS, mixed content)
+- Robots.txt blocking critical resources
+- Canonical pointing to wrong URL
+- Broken pages returning 5xx errors
+
+### 🟠 High (fix within 1 week)
+- Missing or duplicate title tags
+- Missing meta descriptions on key pages
+- Multiple H1 tags
+- Broken internal links (404)
+- Missing schema on eligible pages
+- AI crawlers completely blocked
+- CWV in "Poor" range
+
+### 🟡 Medium (fix within 1 month)
+- Images without alt text
+- Suboptimal internal linking
+- Missing hreflang tags on multilingual pages
+- Content below minimum word count thresholds
+- Missing llms.txt file
+- CWV in "Needs Improvement" range
+
+### 🟢 Low (backlog)
+- Optional schema enhancements
+- Minor readability improvements
+- IndexNow implementation
+- Social meta tags (Open Graph, Twitter Cards)
+- Image format optimization (WebP/AVIF)
+
+---
+
+## Auto-Generated Fix Templates
+
+When an issue is detected, Chief can generate ready-to-implement fixes:
+
+### Meta Tags Fix
+```html
+<!-- BEFORE (missing/wrong) -->
+<title>[current or missing]</title>
+
+<!-- RECOMMENDED FIX -->
+<title>[Optimized title - max 60 chars] | [Brand]</title>
+<meta name="description" content="[Compelling description - 150-160 chars]">
+```
+
+### Schema JSON-LD Fix
+Generate from `ref/schema-templates.json` with actual page data filled in.
+
+### robots.txt Improvement
+```
+# RECOMMENDED robots.txt
+User-agent: *
+Allow: /
+Sitemap: https://[domain]/sitemap.xml
+
+# Allow AI search crawlers for visibility
+User-agent: GPTBot
+Allow: /
+
+User-agent: ClaudeBot
+Allow: /
+
+User-agent: PerplexityBot
+Allow: /
+
+# Block AI training-only crawlers (optional)
+User-agent: CCBot
+Disallow: /
+
+User-agent: Bytespider
+Disallow: /
+```
+
+### llms.txt Template
+```
+# [Site Name]
+> [One-line description of the site]
+
+## Main Pages
+- [Homepage](https://domain.com): [Description]
+- [About](https://domain.com/about): [Description]
+- [Services](https://domain.com/services): [Description]
+
+## Key Information
+- [Important fact 1]
+- [Important fact 2]
+```
+
+---
+
+## Report Templates
+
+### Full Audit Report
+```markdown
+# 🏥 SEO Health Report — [Domain]
+**Date**: [YYYY-MM-DD]
+**Engine**: BMAD+ SEO Engine v2.0
+**Pages Analyzed**: [N]
+**Business Type**: [Detected]
+
+---
+
+## Executive Summary
+[2-3 sentence overview of findings for non-technical readers]
+
+## SEO Health Score: XX/100 [Rating]
+
+### Score Breakdown
+| Category | Score | Weight | Weighted |
+|----------|-------|--------|----------|
+| Technical SEO | XX | 20% | XX |
+| Content & E-E-A-T | XX | 22% | XX |
+| On-Page SEO | XX | 18% | XX |
+| Schema | XX | 10% | XX |
+| Performance | XX | 12% | XX |
+| AI Readiness | XX | 12% | XX |
+| Images | XX | 6% | XX |
+| **TOTAL** | | **100%** | **XX** |
+
+---
+
+## Issues Summary
+| Priority | Count | Description |
+|----------|-------|-------------|
+| 🔴 Critical | N | [summary] |
+| 🟠 High | N | [summary] |
+| 🟡 Medium | N | [summary] |
+| 🟢 Low | N | [summary] |
+
+---
+
+## Detailed Findings
+### Technical SEO (Scout)
+### Content & E-E-A-T (Judge)
+### AI Readiness — GEO (Judge)
+### Schema & Structured Data (Judge)
+
+---
+
+## Action Plan
+
+### Quick Wins (do today)
+1. [fix] — Impact: High, Effort: Low
+
+### 30-Day Goals
+### 60-Day Goals
+### 90-Day Goals
+
+---
+
+## Auto-Generated Fixes
+[Ready-to-implement code blocks for all fixable issues]
+
+---
+
+## Monitoring
+[Comparison with previous audit if available]
+
+---
+
+*Report generated by BMAD+ SEO Engine v2.0 — By Oveanet × Laurent Rochetta*
+```
+
+### Monitoring Report (when history exists)
+```markdown
+# 📊 SEO Progress Report — [Domain]
+**Current Score**: XX/100 ([+/-N] vs previous)
+**Previous Score**: XX/100 ([date])
+
+### Score Evolution
+| Category | Previous | Current | Change |
+|----------|----------|---------|--------|
+| ... | XX | XX | [+/-N] |
+
+### Issues Resolved: [N]
+### New Issues Found: [N]
+### Remaining Issues: [N]
+```
+
+---
+
+## Monitoring System
+
+When history exists in `.bmad-seo/history/`:
+1. Load previous audit JSON from `.bmad-seo/history/[domain]-[date].json`
+2. Compare scores category by category
+3. Track issues: resolved, new, remaining
+4. Generate trend report with delta indicators
+
+### History Storage Format
+```json
+{
+  "domain": "example.com",
+  "date": "2026-03-19",
+  "score": 72,
+  "categories": { ... },
+  "issues": [ ... ]
+}
+```
+
+---
+
+## Auto-Activation Triggers
+
+Activate Chief when detecting keywords: "SEO score", "audit report", "action plan", "roadmap", "quick wins", "fix recommendations", "SEO progress", "monitoring", "compare audit"