bmad-plus 0.4.1 → 0.4.2

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 (27) hide show
  1. package/CHANGELOG.md +11 -0
  2. package/README.md +3 -2
  3. package/package.json +1 -1
  4. package/readme-international/README.de.md +1 -1
  5. package/readme-international/README.es.md +1 -1
  6. package/readme-international/README.fr.md +1 -1
  7. package/src/bmad-plus/agents/pack-animated/animated-website-agent.md +325 -0
  8. package/src/bmad-plus/agents/pack-animated/templates/animated-website-workflow.md +55 -0
  9. package/src/bmad-plus/agents/pack-backup/backup-agent.md +71 -0
  10. package/src/bmad-plus/agents/pack-backup/templates/backup-workflow.md +51 -0
  11. package/src/bmad-plus/agents/pack-seo/SKILL.md +171 -0
  12. package/src/bmad-plus/agents/pack-seo/checklist.md +140 -0
  13. package/src/bmad-plus/agents/pack-seo/pagespeed-playbook.md +320 -0
  14. package/src/bmad-plus/agents/pack-seo/ref/audit-schema.json +187 -0
  15. package/src/bmad-plus/agents/pack-seo/ref/cwv-thresholds.md +87 -0
  16. package/src/bmad-plus/agents/pack-seo/ref/eeat-criteria.md +123 -0
  17. package/src/bmad-plus/agents/pack-seo/ref/geo-signals.md +167 -0
  18. package/src/bmad-plus/agents/pack-seo/ref/hreflang-rules.md +153 -0
  19. package/src/bmad-plus/agents/pack-seo/ref/quality-gates.md +133 -0
  20. package/src/bmad-plus/agents/pack-seo/ref/schema-catalog.md +91 -0
  21. package/src/bmad-plus/agents/pack-seo/ref/schema-templates.json +356 -0
  22. package/src/bmad-plus/agents/pack-seo/seo-chief.md +294 -0
  23. package/src/bmad-plus/agents/pack-seo/seo-judge.md +241 -0
  24. package/src/bmad-plus/agents/pack-seo/seo-scout.md +171 -0
  25. package/src/bmad-plus/agents/pack-seo/templates/seo-audit-workflow.md +241 -0
  26. package/tools/cli/commands/install.js +15 -14
  27. package/tools/cli/i18n.js +10 -10
package/src/bmad-plus/agents/pack-seo/ref/hreflang-rules.md ADDED
@@ -0,0 +1,153 @@
1
+ # Hreflang — Audit Rules & Best Practices (March 2026)
2
+
3
+ > Author: Laurent Rochetta | BMAD+ SEO Engine v2.0
4
+
5
+ ## What is Hreflang?
6
+
7
+ `hreflang` tells search engines which language/region version of a page to serve.
8
+ Errors cause wrong language indexing, duplicate content penalties, and lost organic traffic.
9
+
10
+ ---
11
+
12
+ ## Implementation Methods
13
+
14
+ | Method | Best For | Max Pages |
15
+ |--------|----------|-----------|
16
+ | `<link>` in `<head>` | Small sites (<50 pages) | ~50 |
17
+ | HTTP header `Link:` | Non-HTML files (PDFs) | ~50 |
18
+ | Sitemap `<xhtml:link>` | Large sites (50+) | Unlimited |
19
+
20
+ > **Recommendation**: Use sitemap for sites with 50+ pages. HTTP headers for non-HTML resources.
21
+
22
+ ---
23
+
24
+ ## Validation Rules
25
+
26
+ ### Rule 1: Valid Language Codes
27
+ - Use **ISO 639-1** (2-letter): `en`, `fr`, `de`, `es`, `ja`, `zh`
28
+ - Optional **ISO 3166-1 Alpha-2** for region: `en-US`, `en-GB`, `fr-FR`, `fr-CA`, `pt-BR`
29
+ - **Case insensitive** but convention is lowercase lang, uppercase country
30
+
31
+ | ✅ Valid | ❌ Invalid | Why |
32
+ |---------|-----------|-----|
33
+ | `en` | `english` | Must be ISO 639-1 |
34
+ | `fr-FR` | `fr-FRA` | Country must be 2-letter |
35
+ | `zh-Hans` | `cn` | `cn` is not a valid language code |
36
+ | `x-default` | `default` | Must use exact `x-default` |
37
+
38
+ ### Rule 2: Self-Referencing (MANDATORY)
39
+ Every page MUST include a hreflang tag pointing to itself.
40
+
41
+ ```html
42
+ <!-- On the English page (example.com/en/) -->
43
+ <link rel="alternate" hreflang="en" href="https://example.com/en/" />
44
+ <link rel="alternate" hreflang="fr" href="https://example.com/fr/" />
45
+ <link rel="alternate" hreflang="x-default" href="https://example.com/en/" />
46
+ ```
47
+
48
+ **Error if missing**: Google may ignore all hreflang tags on that page.
49
+
50
+ ### Rule 3: Return Tags (MANDATORY)
51
+ If page A links to page B with hreflang, page B MUST link back to page A.
52
+
53
+ ```
54
+ Page A (en) → hreflang="fr" → Page B (fr)
55
+ Page B (fr) → hreflang="en" → Page A (en) ← MANDATORY
56
+ ```
57
+
58
+ **Error if missing**: Called "orphan hreflang" — Google ignores the one-way tag.
59
+
60
+ ### Rule 4: x-default (STRONGLY RECOMMENDED)
61
+ Designate a fallback page for users whose language/region doesn't match any variant.
62
+
63
+ ```html
64
+ <link rel="alternate" hreflang="x-default" href="https://example.com/" />
65
+ ```
66
+
67
+ Common choices for x-default:
68
+ - Language selector/redirect page
69
+ - English version (most common)
70
+ - Homepage of the main domain
71
+
72
+ ### Rule 5: Canonical + Hreflang Consistency
73
+ - Each hreflang URL **must be the canonical version** (not a redirect, not a URL with parameters)
74
+ - If a page has `rel="canonical"` pointing elsewhere, hreflang tags on that page are **ignored**
75
+ - Canonical and hreflang must agree: don't have hreflang point to a URL that canonicalizes to a different URL
76
+
77
+ ### Rule 6: Absolute URLs Only
78
+ ```html
79
+ <!-- ✅ Correct -->
80
+ <link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
81
+
82
+ <!-- ❌ Wrong -->
83
+ <link rel="alternate" hreflang="fr" href="/fr/page" />
84
+ ```
85
+
86
+ ### Rule 7: No Hreflang on Non-200 Pages
87
+ - Don't include hreflang tags on pages that return 3xx, 4xx, or 5xx
88
+ - Don't point hreflang to pages that redirect
89
+
90
+ ---
91
+
92
+ ## Common Error Patterns
93
+
94
+ ### Error 1: Missing Return Tags
95
+ **Symptom**: hreflang is configured on the main language but not on alternate versions.
96
+ **Fix**: Add reciprocal hreflang tags on ALL language variants.
97
+
98
+ ### Error 2: Wrong Canonical + Hreflang
99
+ **Symptom**: Page A hreflang → Page B, but Page B canonical → Page C.
100
+ **Fix**: Align canonical and hreflang targets.
101
+
102
+ ### Error 3: Missing Self-Reference
103
+ **Symptom**: Page lists other language versions but not itself.
104
+ **Fix**: Add `hreflang` tag with the current page's own language/URL.
105
+
106
+ ### Error 4: Inconsistent URLs
107
+ **Symptom**: hreflang uses `http://` but site is on `https://`, or trailing slash mismatch.
108
+ **Fix**: Use exact canonical URL (protocol, www/non-www, trailing slash).
109
+
110
+ ### Error 5: Language vs Region Confusion
111
+ **Symptom**: Using `hreflang="fr"` for France and `hreflang="fr"` for Canada.
112
+ **Fix**: Use `hreflang="fr-FR"` and `hreflang="fr-CA"` to differentiate.
113
+
114
+ ### Error 6: Missing x-default
115
+ **Symptom**: Users in unsupported regions see random language version.
116
+ **Fix**: Add `x-default` pointing to language selector or English version.
117
+
118
+ ---
119
+
120
+ ## Sitemap Implementation (Recommended for 50+ pages)
121
+
122
+ ```xml
123
+ <?xml version="1.0" encoding="UTF-8"?>
124
+ <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
125
+ xmlns:xhtml="http://www.w3.org/1999/xhtml">
126
+ <url>
127
+ <loc>https://example.com/en/page</loc>
128
+ <xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/page"/>
129
+ <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/page"/>
130
+ <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/page"/>
131
+ <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/en/page"/>
132
+ </url>
133
+ </urlset>
134
+ ```
135
+
136
+ ---
137
+
138
+ ## Audit Checklist
139
+
140
+ | # | Check | Priority |
141
+ |---|-------|----------|
142
+ | 1 | All hreflang language codes are valid ISO 639-1 | 🔴 Critical |
143
+ | 2 | All hreflang country codes are valid ISO 3166-1 | 🔴 Critical |
144
+ | 3 | Every page has self-referencing hreflang | 🔴 Critical |
145
+ | 4 | All hreflang tags have return tags | 🔴 Critical |
146
+ | 5 | All hreflang URLs are absolute | 🔴 Critical |
147
+ | 6 | x-default is specified | 🟠 High |
148
+ | 7 | Hreflang URLs match canonical URLs | 🟠 High |
149
+ | 8 | No hreflang on non-200 pages | 🟠 High |
150
+ | 9 | No hreflang pointing to redirecting URLs | 🟠 High |
151
+ | 10 | Consistent protocol (https) and www/non-www | 🟡 Medium |
152
+ | 11 | Language/region differentiation correct | 🟡 Medium |
153
+ | 12 | Sitemap implementation for 50+ pages | 🟡 Medium |
package/src/bmad-plus/agents/pack-seo/ref/quality-gates.md ADDED
@@ -0,0 +1,133 @@
1
+ # Quality Gates — Content Thresholds (March 2026)
2
+
3
+ > Author: Laurent Rochetta | BMAD+ SEO Engine v2.0
4
+
5
+ ## Word Count Minimums by Page Type
6
+
7
+ | Page Type | Minimum | Notes |
8
+ |-----------|---------|-------|
9
+ | Homepage | 500 | Brand clarity + key offerings |
10
+ | Service page | 800 | Comprehensive service description |
11
+ | Blog / article | 1,500 | Deep topical coverage |
12
+ | Product page | 300+ (400+ complex) | Depends on product complexity |
13
+ | Category page | 200 | Plus product listings |
14
+ | Location page | 500–600 | Must be 60%+ unique per location |
15
+ | Comparison page | 1,200 | Feature matrix + analysis |
16
+ | Landing page | 400 | Conversion-focused |
17
+ | About page | 500 | Company story + credentials |
18
+ | FAQ page | 1,000 | Comprehensive Q&A coverage |
19
+
20
+ > **Word count is NOT a ranking factor.** These are topical coverage floors. A thorough 500-word page beats a padded 2,000-word one.
21
+
22
+ ---
23
+
24
+ ## Location Page Quality Gates
25
+
26
+ | Threshold | Action |
27
+ |-----------|--------|
28
+ | 1–29 location pages | ✅ Normal — ensure 60%+ unique content per page |
29
+ | 30+ location pages | ⚠️ WARNING — enforce 60%+ unique content, audit for thin/duplicate |
30
+ | 50+ location pages | 🛑 HARD STOP — require user justification before proceeding |
31
+
32
+ ### Unique Content Requirements per Location
33
+ - Unique local testimonials or case studies
34
+ - Location-specific service details
35
+ - Local area information and context
36
+ - Original photos (not stock)
37
+ - Unique meta title and description
38
+
39
+ ---
40
+
41
+ ## Programmatic Page Quality Gates
42
+
43
+ | Threshold | Action |
44
+ |-----------|--------|
45
+ | 1–99 programmatic pages | ✅ Normal — verify template quality |
46
+ | 100+ pages | ⚠️ WARNING — audit for thin content and cannibalization |
47
+ | 500+ pages | 🛑 HARD STOP — full audit required before generating more |
48
+
49
+ ### Programmatic Content Requirements
50
+ - Each page must provide unique value (not just data swap)
51
+ - Internal linking automation between related pages
52
+ - Canonical strategy to prevent index bloat
53
+ - Minimum 200 words of unique contextual content per page
54
+ - Quality varies by template — audit samples before scale
55
+
56
+ ---
57
+
58
+ ## Title Tag Guidelines
59
+
60
+ | Criterion | Requirement |
61
+ |-----------|-------------|
62
+ | Length | 50–60 characters (display limit ~600px) |
63
+ | Primary keyword | Include near the beginning |
64
+ | Brand name | Append with " | Brand" or " — Brand" |
65
+ | Uniqueness | Every page must have a unique title |
66
+ | Accuracy | Must reflect actual page content |
67
+
68
+ ---
69
+
70
+ ## Meta Description Guidelines
71
+
72
+ | Criterion | Requirement |
73
+ |-----------|-------------|
74
+ | Length | 150–160 characters |
75
+ | Call to action | Include when appropriate |
76
+ | Primary keyword | Include naturally |
77
+ | Uniqueness | Every page must have a unique description |
78
+ | Accuracy | Must match page content (Google may rewrite if not) |
79
+
80
+ ---
81
+
82
+ ## Heading Hierarchy Rules
83
+
84
+ | Rule | Requirement |
85
+ |------|-------------|
86
+ | H1 count | Exactly 1 per page |
87
+ | H1 content | Should contain primary keyword, be descriptive |
88
+ | Hierarchy | H1 → H2 → H3 (no skipping levels) |
89
+ | Heading frequency | One heading every 200–300 words |
90
+ | Heading style | Descriptive, not generic ("Our Services" → "Professional SEO Audit Services") |
91
+
92
+ ---
93
+
94
+ ## Image Optimization Standards
95
+
96
+ | Criterion | Standard | Priority |
97
+ |-----------|----------|----------|
98
+ | Alt text | Descriptive, meaningful, includes keywords naturally | High |
99
+ | Dimensions | Width and height attributes specified | High (CLS) |
100
+ | Format | WebP or AVIF preferred, JPEG/PNG acceptable | Medium |
101
+ | File size | <200KB for standard, <500KB for hero images | Medium |
102
+ | Lazy loading | `loading="lazy"` for below-fold images | Medium |
103
+ | Preload | `<link rel="preload">` for hero/LCP images | High |
104
+ | Srcset | Responsive sizes for different viewports | Medium |
105
+
106
+ ---
107
+
108
+ ## Internal Linking Standards
109
+
110
+ | Metric | Target |
111
+ |--------|--------|
112
+ | Links per 1,000 words | 3–5 relevant internal links |
113
+ | Anchor text | Descriptive (not "click here") |
114
+ | Orphan pages | 0 (every page linked from at least one other) |
115
+ | Click depth | Important pages within 3 clicks of homepage |
116
+ | Broken links | 0 internal 404s |
117
+
118
+ ---
119
+
120
+ ## Thin Content Detection
121
+
122
+ A page is flagged as "thin content" when:
123
+ 1. Word count is below the minimum for its page type
124
+ 2. Content is predominantly duplicate or near-duplicate of another page
125
+ 3. Content is auto-generated without unique value-add
126
+ 4. Page provides no actionable information
127
+
128
+ ### Doorway Page Prevention
129
+ Never recommend creating pages that:
130
+ - Exist solely to funnel users to another page
131
+ - Have nearly identical content with only location/keyword swaps
132
+ - Provide no standalone value
133
+ - Target many similar keyword variations with minimal differences
package/src/bmad-plus/agents/pack-seo/ref/schema-catalog.md ADDED
@@ -0,0 +1,91 @@
1
+ # Schema.org — Type Catalog & Deprecation Status (March 2026)
2
+
3
+ > Author: Laurent Rochetta | BMAD+ SEO Engine v2.0 | Schema.org v29.4
4
+
5
+ ## Format: Always JSON-LD
6
+ `<script type="application/ld+json">` — Google's explicit recommendation.
7
+ Content with schema has ~2.5× higher AI citation probability (Google/Microsoft, March 2025).
8
+
9
+ ## Active — Recommend Freely
10
+
11
+ | Type | Use Case | Key Properties |
12
+ |------|----------|----------------|
13
+ | Organization | Company/brand | name, url, logo, contactPoint, sameAs |
14
+ | LocalBusiness | Physical location | name, address, telephone, openingHours, geo, priceRange |
15
+ | SoftwareApplication | Apps | name, operatingSystem, applicationCategory, offers |
16
+ | WebApplication | SaaS | name, applicationCategory, offers, featureList |
17
+ | Product | Products | name, image, description, sku, brand, offers, review |
18
+ | ProductGroup | Variants | name, productGroupID, variesBy, hasVariant |
19
+ | Offer | Pricing | price, priceCurrency, availability, url |
20
+ | Service | Services | name, provider, areaServed, description, offers |
21
+ | Article | Articles | headline, author, datePublished, dateModified, image, publisher |
22
+ | BlogPosting | Blog content | Same as Article + blog context |
23
+ | NewsArticle | News | Same as Article + news context |
24
+ | Review | Reviews | reviewRating, author, itemReviewed, reviewBody |
25
+ | AggregateRating | Ratings | ratingValue, reviewCount, bestRating |
26
+ | BreadcrumbList | Navigation | itemListElement with position, name, item |
27
+ | WebSite | Site-level | name, url, potentialAction (SearchAction) |
28
+ | WebPage | Page-level | name, description, datePublished, dateModified |
29
+ | Person | Authors/team | name, jobTitle, url, sameAs, image, worksFor |
30
+ | ProfilePage | Profiles | mainEntity (Person), name, sameAs |
31
+ | ContactPage | Contact | name, url |
32
+ | VideoObject | Video | name, description, thumbnailUrl, uploadDate, duration |
33
+ | ImageObject | Images | contentUrl, caption, creator |
34
+ | Event | Events | name, startDate, endDate, location, organizer |
35
+ | JobPosting | Jobs | title, description, datePosted, hiringOrganization |
36
+ | Course | Education | name, description, provider, hasCourseInstance |
37
+ | DiscussionForumPosting | Forums | headline, author, datePublished, text |
38
+ | Certification | Certifications | certificationIdentification, issuedBy (April 2025) |
39
+ | BroadcastEvent | Live streams | isLiveBroadcast, startDate, endDate |
40
+ | Clip | Video chapters | name, startOffset, endOffset, url |
41
+ | SeekToAction | Video seek | target with timestamp parameter |
42
+ | SoftwareSourceCode | Repos | codeRepository, programmingLanguage, license |
43
+
44
+ ## Restricted — Specific Sites Only
45
+
46
+ | Type | Restriction | Since |
47
+ |------|------------|-------|
48
+ | FAQPage | Government & healthcare ONLY | Aug 2023 |
49
+
50
+ > FAQPage still benefits AI/LLM citation (ChatGPT, Perplexity) even without Google rich results. Existing FAQPage on commercial sites: Info priority, not Critical.
51
+
52
+ ## Deprecated — NEVER Recommend
53
+
54
+ | Type | Since | Notes |
55
+ |------|-------|-------|
56
+ | HowTo | Sept 2023 | Rich results fully removed |
57
+ | SpecialAnnouncement | July 2025 | COVID-era, no longer processed |
58
+ | CourseInfo | June 2025 | Merged into Course |
59
+ | EstimatedSalary | June 2025 | No longer displayed |
60
+ | LearningVideo | June 2025 | Use VideoObject instead |
61
+ | ClaimReview | June 2025 | Fact-check markup discontinued |
62
+ | VehicleListing | June 2025 | Vehicle listings discontinued |
63
+ | Practice Problem | Late 2025 | Educational problems discontinued |
64
+ | Dataset | Late 2025 | Dataset Search discontinued |
65
+
66
+ ## Recent Additions (2024–2026)
67
+
68
+ | Feature | When | Notes |
69
+ |---------|------|-------|
70
+ | Product Certification | April 2025 | Replaces EnergyConsumptionDetails |
71
+ | ProductGroup | 2025 | E-commerce variants |
72
+ | ProfilePage | 2025 | E-E-A-T author pages |
73
+ | DiscussionForumPosting | 2024 | Forum content |
74
+ | LoyaltyProgram | June 2025 | Member pricing |
75
+ | ConferenceEvent | Dec 2025 | Schema.org v29.4 |
76
+ | PerformingArtsEvent | Dec 2025 | Schema.org v29.4 |
77
+
78
+ ## Validation Checklist
79
+ 1. ✅ `@context` = `"https://schema.org"` (not http)
80
+ 2. ✅ `@type` valid + non-deprecated
81
+ 3. ✅ Required properties present
82
+ 4. ✅ Correct data types
83
+ 5. ✅ No placeholder text
84
+ 6. ✅ Absolute URLs only
85
+ 7. ✅ ISO 8601 dates
86
+ 8. ✅ Valid image URLs
87
+
88
+ ## E-Commerce Notes
89
+ - `returnPolicyCountry` required in MerchantReturnPolicy (March 2025)
90
+ - Content API for Shopping sunsets August 18, 2026 → migrate to Merchant API
91
+ - JS-injected Product schema may face delayed processing → include in server HTML