npm - bmad-plus - Versions diffs - 0.7.4 → 0.8.0 - Mend

bmad-plus 0.7.4 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (294) hide show

package/src/bmad-plus/agents/pack-seo/ref/hreflang-rules.md CHANGED Viewed

@@ -1,153 +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 |
+# 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 |

package/src/bmad-plus/agents/pack-seo/ref/quality-gates.md CHANGED Viewed

@@ -1,133 +1,133 @@
-# Quality Gates — Content Thresholds (March 2026)
-> Author: Laurent Rochetta | BMAD+ SEO Engine v2.0
-## Word Count Minimums by Page Type
-| Page Type | Minimum | Notes |
-|-----------|---------|-------|
-| Homepage | 500 | Brand clarity + key offerings |
-| Service page | 800 | Comprehensive service description |
-| Blog / article | 1,500 | Deep topical coverage |
-| Product page | 300+ (400+ complex) | Depends on product complexity |
-| Category page | 200 | Plus product listings |
-| Location page | 500–600 | Must be 60%+ unique per location |
-| Comparison page | 1,200 | Feature matrix + analysis |
-| Landing page | 400 | Conversion-focused |
-| About page | 500 | Company story + credentials |
-| FAQ page | 1,000 | Comprehensive Q&A coverage |
-> **Word count is NOT a ranking factor.** These are topical coverage floors. A thorough 500-word page beats a padded 2,000-word one.
----
-## Location Page Quality Gates
-| Threshold | Action |
-|-----------|--------|
-| 1–29 location pages | ✅ Normal — ensure 60%+ unique content per page |
-| 30+ location pages | ⚠️ WARNING — enforce 60%+ unique content, audit for thin/duplicate |
-| 50+ location pages | 🛑 HARD STOP — require user justification before proceeding |
-### Unique Content Requirements per Location
-- Unique local testimonials or case studies
-- Location-specific service details
-- Local area information and context
-- Original photos (not stock)
-- Unique meta title and description
----
-## Programmatic Page Quality Gates
-| Threshold | Action |
-|-----------|--------|
-| 1–99 programmatic pages | ✅ Normal — verify template quality |
-| 100+ pages | ⚠️ WARNING — audit for thin content and cannibalization |
-| 500+ pages | 🛑 HARD STOP — full audit required before generating more |
-### Programmatic Content Requirements
-- Each page must provide unique value (not just data swap)
-- Internal linking automation between related pages
-- Canonical strategy to prevent index bloat
-- Minimum 200 words of unique contextual content per page
-- Quality varies by template — audit samples before scale
----
-## Title Tag Guidelines
-| Criterion | Requirement |
-|-----------|-------------|
-| Length | 50–60 characters (display limit ~600px) |
-| Primary keyword | Include near the beginning |
-| Brand name | Append with " | Brand" or " — Brand" |
-| Uniqueness | Every page must have a unique title |
-| Accuracy | Must reflect actual page content |
----
-## Meta Description Guidelines
-| Criterion | Requirement |
-|-----------|-------------|
-| Length | 150–160 characters |
-| Call to action | Include when appropriate |
-| Primary keyword | Include naturally |
-| Uniqueness | Every page must have a unique description |
-| Accuracy | Must match page content (Google may rewrite if not) |
----
-## Heading Hierarchy Rules
-| Rule | Requirement |
-|------|-------------|
-| H1 count | Exactly 1 per page |
-| H1 content | Should contain primary keyword, be descriptive |
-| Hierarchy | H1 → H2 → H3 (no skipping levels) |
-| Heading frequency | One heading every 200–300 words |
-| Heading style | Descriptive, not generic ("Our Services" → "Professional SEO Audit Services") |
----
-## Image Optimization Standards
-| Criterion | Standard | Priority |
-|-----------|----------|----------|
-| Alt text | Descriptive, meaningful, includes keywords naturally | High |
-| Dimensions | Width and height attributes specified | High (CLS) |
-| Format | WebP or AVIF preferred, JPEG/PNG acceptable | Medium |
-| File size | <200KB for standard, <500KB for hero images | Medium |
-| Lazy loading | `loading="lazy"` for below-fold images | Medium |
-| Preload | `<link rel="preload">` for hero/LCP images | High |
-| Srcset | Responsive sizes for different viewports | Medium |
----
-## Internal Linking Standards
-| Metric | Target |
-|--------|--------|
-| Links per 1,000 words | 3–5 relevant internal links |
-| Anchor text | Descriptive (not "click here") |
-| Orphan pages | 0 (every page linked from at least one other) |
-| Click depth | Important pages within 3 clicks of homepage |
-| Broken links | 0 internal 404s |
----
-## Thin Content Detection
-A page is flagged as "thin content" when:
-1. Word count is below the minimum for its page type
-2. Content is predominantly duplicate or near-duplicate of another page
-3. Content is auto-generated without unique value-add
-4. Page provides no actionable information
-### Doorway Page Prevention
-Never recommend creating pages that:
-- Exist solely to funnel users to another page
-- Have nearly identical content with only location/keyword swaps
-- Provide no standalone value
-- Target many similar keyword variations with minimal differences
+# Quality Gates — Content Thresholds (March 2026)
+> Author: Laurent Rochetta | BMAD+ SEO Engine v2.0
+## Word Count Minimums by Page Type
+| Page Type | Minimum | Notes |
+|-----------|---------|-------|
+| Homepage | 500 | Brand clarity + key offerings |
+| Service page | 800 | Comprehensive service description |
+| Blog / article | 1,500 | Deep topical coverage |
+| Product page | 300+ (400+ complex) | Depends on product complexity |
+| Category page | 200 | Plus product listings |
+| Location page | 500–600 | Must be 60%+ unique per location |
+| Comparison page | 1,200 | Feature matrix + analysis |
+| Landing page | 400 | Conversion-focused |
+| About page | 500 | Company story + credentials |
+| FAQ page | 1,000 | Comprehensive Q&A coverage |
+> **Word count is NOT a ranking factor.** These are topical coverage floors. A thorough 500-word page beats a padded 2,000-word one.
+---
+## Location Page Quality Gates
+| Threshold | Action |
+|-----------|--------|
+| 1–29 location pages | ✅ Normal — ensure 60%+ unique content per page |
+| 30+ location pages | ⚠️ WARNING — enforce 60%+ unique content, audit for thin/duplicate |
+| 50+ location pages | 🛑 HARD STOP — require user justification before proceeding |
+### Unique Content Requirements per Location
+- Unique local testimonials or case studies
+- Location-specific service details
+- Local area information and context
+- Original photos (not stock)
+- Unique meta title and description
+---
+## Programmatic Page Quality Gates
+| Threshold | Action |
+|-----------|--------|
+| 1–99 programmatic pages | ✅ Normal — verify template quality |
+| 100+ pages | ⚠️ WARNING — audit for thin content and cannibalization |
+| 500+ pages | 🛑 HARD STOP — full audit required before generating more |
+### Programmatic Content Requirements
+- Each page must provide unique value (not just data swap)
+- Internal linking automation between related pages
+- Canonical strategy to prevent index bloat
+- Minimum 200 words of unique contextual content per page
+- Quality varies by template — audit samples before scale
+---
+## Title Tag Guidelines
+| Criterion | Requirement |
+|-----------|-------------|
+| Length | 50–60 characters (display limit ~600px) |
+| Primary keyword | Include near the beginning |
+| Brand name | Append with " | Brand" or " — Brand" |
+| Uniqueness | Every page must have a unique title |
+| Accuracy | Must reflect actual page content |
+---
+## Meta Description Guidelines
+| Criterion | Requirement |
+|-----------|-------------|
+| Length | 150–160 characters |
+| Call to action | Include when appropriate |
+| Primary keyword | Include naturally |
+| Uniqueness | Every page must have a unique description |
+| Accuracy | Must match page content (Google may rewrite if not) |
+---
+## Heading Hierarchy Rules
+| Rule | Requirement |
+|------|-------------|
+| H1 count | Exactly 1 per page |
+| H1 content | Should contain primary keyword, be descriptive |
+| Hierarchy | H1 → H2 → H3 (no skipping levels) |
+| Heading frequency | One heading every 200–300 words |
+| Heading style | Descriptive, not generic ("Our Services" → "Professional SEO Audit Services") |
+---
+## Image Optimization Standards
+| Criterion | Standard | Priority |
+|-----------|----------|----------|
+| Alt text | Descriptive, meaningful, includes keywords naturally | High |
+| Dimensions | Width and height attributes specified | High (CLS) |
+| Format | WebP or AVIF preferred, JPEG/PNG acceptable | Medium |
+| File size | <200KB for standard, <500KB for hero images | Medium |
+| Lazy loading | `loading="lazy"` for below-fold images | Medium |
+| Preload | `<link rel="preload">` for hero/LCP images | High |
+| Srcset | Responsive sizes for different viewports | Medium |
+---
+## Internal Linking Standards
+| Metric | Target |
+|--------|--------|
+| Links per 1,000 words | 3–5 relevant internal links |
+| Anchor text | Descriptive (not "click here") |
+| Orphan pages | 0 (every page linked from at least one other) |
+| Click depth | Important pages within 3 clicks of homepage |
+| Broken links | 0 internal 404s |
+---
+## Thin Content Detection
+A page is flagged as "thin content" when:
+1. Word count is below the minimum for its page type
+2. Content is predominantly duplicate or near-duplicate of another page
+3. Content is auto-generated without unique value-add
+4. Page provides no actionable information
+### Doorway Page Prevention
+Never recommend creating pages that:
+- Exist solely to funnel users to another page
+- Have nearly identical content with only location/keyword swaps
+- Provide no standalone value
+- Target many similar keyword variations with minimal differences