agileflow 3.2.1 → 3.4.0

package/src/core/commands/seo/schema.md

@@ -0,0 +1,183 @@
+---
+description: Schema markup validation, deprecated type detection, and ready-to-use JSON-LD generation for rich results
+argument-hint: "URL [GENERATE=true]"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:seo:schema - Schema markup analysis"
+    - "Detect existing JSON-LD, Microdata, RDFa on the page"
+    - "Validate against current Google standards (2025-2026)"
+    - "Flag deprecated types (HowTo, SpecialAnnouncement, etc.)"
+    - "If GENERATE=true, produce ready-to-use JSON-LD snippets"
+  state_fields:
+    - target_url
+    - generate
+    - schema_found
+---
+
+# /agileflow:seo:schema
+
+Detect, validate, and generate schema markup (structured data) for rich results in Google Search.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:seo:schema https://example.com                    # Detect and validate existing schema
+/agileflow:seo:schema https://example.com GENERATE=true       # Also generate missing JSON-LD
+/agileflow:seo:schema https://example.com/product             # Analyze product page schema
+```
+
+---
+
+## Arguments
+
+| Argument | Values | Default | Description |
+|----------|--------|---------|-------------|
+| URL | Any valid URL | Required | Page to analyze |
+| GENERATE | true, false | false | Generate ready-to-use JSON-LD for missing schema |
+
+---
+
+## Process
+
+### STEP 1: Fetch and Detect
+
+Use WebFetch to retrieve the page. Extract all structured data:
+- `<script type="application/ld+json">` blocks (JSON-LD)
+- Elements with `itemscope`/`itemtype`/`itemprop` (Microdata)
+- Elements with `typeof`/`property` (RDFa)
+
+### STEP 2: Validate Existing Schema
+
+For each schema block found, check:
+
+**Format**:
+- Valid JSON syntax (for JSON-LD)
+- `@context` uses `https://schema.org` (HTTPS, not HTTP)
+- `@type` is a recognized type
+
+**Required Properties** (per type - see schema-types.md reference):
+- Organization: name, url, logo
+- Product: name, image, offers (price, priceCurrency, availability)
+- Article: headline, image, datePublished, author
+- LocalBusiness: name, address, telephone
+- etc.
+
+**Current Rules**:
+- `returnPolicyCountry` mandatory for Products (March 2025)
+- ISO 8601 dates required
+- Merchant API migration by August 18, 2026
+
+### STEP 3: Flag Deprecated/Restricted Types
+
+**Deprecated (remove immediately)**:
+- HowTo, SpecialAnnouncement, CourseInfo, EstimatedSalary
+- LearningVideo, ClaimReview, VehicleListing, PracticeProblem, Dataset
+
+**Restricted (use only if eligible)**:
+- FAQPage: Only government/healthcare sites since August 2023
+
+### STEP 4: Identify Missing Opportunities
+
+Based on page content, recommend schema that should be present:
+
+| Page Contains | Recommended Schema |
+|--------------|-------------------|
+| Business info | Organization or LocalBusiness |
+| Products | Product with Offer |
+| Blog articles | Article or BlogPosting |
+| Events | Event |
+| Job listings | JobPosting |
+| Videos | VideoObject |
+| Breadcrumbs | BreadcrumbList |
+| Site search | WebSite with SearchAction |
+| Reviews | Review with Rating |
+
+### STEP 5: Generate JSON-LD (if GENERATE=true)
+
+For each missing schema, generate a ready-to-use JSON-LD snippet with placeholder values filled from the actual page content:
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Organization",
+  "name": "[extracted from page]",
+  "url": "[page URL]",
+  "logo": "[detected logo URL]",
+  "sameAs": [
+    "[detected social links]"
+  ]
+}
+```
+
+### STEP 6: Output Report
+
+```markdown
+# Schema Analysis: {URL}
+
+## Existing Schema
+
+| # | Type | Format | Valid | Issues |
+|---|------|--------|-------|--------|
+| 1 | Organization | JSON-LD | Yes | None |
+| 2 | FAQPage | JSON-LD | No | Restricted type (commercial site) |
+
+## Validation Results
+
+### Schema 1: Organization (Valid)
+```json
+{existing schema}
+```
+All required properties present.
+
+### Schema 2: FAQPage (Invalid)
+- Issue: FAQPage restricted to government/healthcare since Aug 2023
+- Action: Remove FAQPage schema from commercial pages
+
+## Missing Schema Opportunities
+
+| Type | Why | Rich Result |
+|------|-----|-------------|
+| BreadcrumbList | Page has breadcrumb nav | Breadcrumb trail in SERP |
+| WebSite | Homepage, has search | Sitelinks search box |
+
+## Generated JSON-LD (if requested)
+
+[Ready-to-use code blocks]
+
+## Schema Score: X/100
+```
+
+### STEP 7: Offer Next Steps
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Schema analysis: {found} types detected, {valid} valid, {issues} issues, {missing} opportunities.",
+  "header": "Next steps",
+  "multiSelect": false,
+  "options": [
+    {"label": "Generate missing JSON-LD (Recommended)", "description": "Create ready-to-use schema for {missing} opportunities"},
+    {"label": "Fix {issues} validation errors", "description": "{top_error_summary}"},
+    {"label": "Test in Rich Results Test", "description": "Validate generated schema at search.google.com/test/rich-results"},
+    {"label": "Run full SEO audit", "description": "/agileflow:seo:audit {domain}"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:seo:schema` - Schema markup validation and generation
+
+**Usage**: `/agileflow:seo:schema URL [GENERATE=true]`
+
+**What It Does**: Detect existing schema → Validate against Google standards → Flag deprecated types → Identify missing opportunities → Generate JSON-LD
+
+**Key References**: schema-types.md (recommended, restricted, deprecated types)
+<!-- COMPACT_SUMMARY_END -->

package/src/core/commands/seo/sitemap.md

@@ -0,0 +1,97 @@
+---
+description: XML sitemap validation, URL coverage analysis, quality gate enforcement, and sitemap generation assistance
+argument-hint: "URL [GENERATE=true]"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:seo:sitemap - Sitemap validation"
+    - "Deploy seo-analyzer-sitemap for comprehensive sitemap audit"
+    - "Check existence, structure, coverage, quality gates"
+    - "If GENERATE=true, help create or fix the sitemap"
+  state_fields:
+    - target_url
+    - generate
+    - sitemap_found
+---
+
+# /agileflow:seo:sitemap
+
+Validate XML sitemap structure, assess URL coverage, enforce quality gates, and optionally generate or fix sitemaps.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:seo:sitemap https://example.com                   # Validate existing sitemap
+/agileflow:seo:sitemap https://example.com GENERATE=true      # Also generate improvements
+```
+
+---
+
+## Arguments
+
+| Argument | Values | Default | Description |
+|----------|--------|---------|-------------|
+| URL | Any valid URL (domain) | Required | Site to analyze |
+| GENERATE | true, false | false | Generate or fix sitemap XML |
+
+---
+
+## Process
+
+### STEP 1: Deploy Sitemap Analyzer
+
+```xml
+<invoke name="Task">
+<parameter name="description">Sitemap validation analysis</parameter>
+<parameter name="prompt">TASK: Validate XML sitemap comprehensively.
+
+TARGET URL: {url}
+
+Check:
+1. Locate sitemap: robots.txt Sitemap: directive, /sitemap.xml, /sitemap_index.xml
+2. Structure: Valid XML, correct namespace, proper elements
+3. URL quality: Status codes, canonical match, not noindexed, HTTPS
+4. Coverage: Important pages included, no orphans
+5. Quality: lastmod dates present and valid, under 50k URLs / 50MB
+6. robots.txt: Sitemap declared in robots.txt
+
+Quality gates:
+- Non-200 URLs: Warning >5%, Critical >15%
+- Missing lastmod: Warning >20%, Critical >50%
+- Stale lastmod (>1 year): Warning >30%, Critical >60%
+- Duplicate URLs: Any = Warning
+
+OUTPUT: Sitemap Score X/100 with detailed findings.</parameter>
+<parameter name="subagent_type">seo-analyzer-sitemap</parameter>
+</invoke>
+```
+
+### STEP 2: Present Results and Optionally Generate
+
+If GENERATE=true and issues found, help create a corrected sitemap or generate one from scratch based on discovered pages.
+
+---
+
+## Quality Gates
+
+| Metric | Warning | Critical |
+|--------|---------|----------|
+| Non-200 URLs | > 5% | > 15% |
+| Missing lastmod | > 20% | > 50% |
+| Stale lastmod | > 30% | > 60% |
+| Not in robots.txt | Always | - |
+| No sitemap at all | - | Always |
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:seo:sitemap` - XML sitemap validation
+
+**Checks**: Existence, XML structure, URL coverage, lastmod quality, robots.txt reference
+
+**Usage**: `/agileflow:seo:sitemap URL [GENERATE=true]`
+<!-- COMPACT_SUMMARY_END -->

package/src/core/commands/seo/technical.md

@@ -0,0 +1,100 @@
+---
+description: Deep technical SEO analysis - crawlability, indexability, security headers, URL structure, mobile-friendliness, and rendering
+argument-hint: "URL [FOCUS=crawl|index|security|urls|mobile|rendering|all]"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:seo:technical - Technical SEO deep-dive"
+    - "Deploy seo-analyzer-technical agent for comprehensive assessment"
+    - "8 categories: crawl, index, security, urls, mobile, rendering, international, performance"
+  state_fields:
+    - target_url
+    - focus
+    - tech_score
+---
+
+# /agileflow:seo:technical
+
+Deep technical SEO analysis covering crawlability, indexability, security headers, URL structure, mobile-friendliness, JavaScript rendering, and international signals.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:seo:technical https://example.com                 # Full 8-category assessment
+/agileflow:seo:technical https://example.com FOCUS=crawl      # Crawlability only
+/agileflow:seo:technical https://example.com FOCUS=security   # Security headers only
+/agileflow:seo:technical https://example.com FOCUS=mobile     # Mobile-friendliness only
+```
+
+---
+
+## Arguments
+
+| Argument | Values | Default | Description |
+|----------|--------|---------|-------------|
+| URL | Any valid URL | Required | Site to analyze |
+| FOCUS | crawl, index, security, urls, mobile, rendering, international, all | all | Narrow to specific area |
+
+---
+
+## Process
+
+### STEP 1: Deploy Technical Analyzer
+
+```xml
+<invoke name="Task">
+<parameter name="description">Technical SEO deep-dive</parameter>
+<parameter name="prompt">TASK: Perform a deep technical SEO analysis.
+
+TARGET URL: {url}
+FOCUS: {focus or "all 8 categories"}
+
+Analyze all 8 categories in depth:
+1. Crawlability: robots.txt, meta robots, canonicals, redirect chains, crawl budget
+2. Indexability: noindex directives, orphan pages, sitemap coverage, crawl depth
+3. Security: HTTPS, HSTS, X-Content-Type-Options, CSP, X-Frame-Options, Referrer-Policy
+4. URL Structure: Cleanliness, hierarchy, parameters, consistency, depth
+5. Mobile: Viewport, responsive design, tap targets, font sizes, no horizontal scroll
+6. JavaScript Rendering: Client-side content, JS-dependent elements, hydration
+7. International: hreflang, language tags, geo-targeting, content localization
+8. Performance Indicators: TTFB, render-blocking, resource hints, compression
+
+For each category, provide specific findings with evidence and a category score out of 100.
+
+OUTPUT: Technical SEO Score X/100 with category breakdown.</parameter>
+<parameter name="subagent_type">seo-analyzer-technical</parameter>
+</invoke>
+```
+
+### STEP 2: Present Results
+
+Show the technical assessment with category scores and offer targeted fixes.
+
+---
+
+## 8 Categories
+
+| Category | Weight | Key Checks |
+|----------|--------|-----------|
+| Crawlability | 25% | robots.txt, canonicals, redirects |
+| Indexability | 20% | noindex, orphans, sitemap coverage |
+| Security | 15% | HTTPS, HSTS, CSP, security headers |
+| URL Structure | 15% | Clean URLs, hierarchy, consistency |
+| Mobile | 15% | Viewport, responsive, tap targets |
+| JS Rendering | 5% | Client-side content visibility |
+| International | 3% | hreflang, language declarations |
+| Performance | 2% | TTFB, resource hints, compression |
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:seo:technical` - Deep technical SEO analysis
+
+**8 Categories**: Crawlability, Indexability, Security, URLs, Mobile, JS Rendering, International, Performance
+
+**Usage**: `/agileflow:seo:technical URL [FOCUS=category]`
+<!-- COMPACT_SUMMARY_END -->

package/src/core/commands/seo.md

@@ -0,0 +1,107 @@
+---
+description: SEO analysis toolkit - comprehensive website audits, page analysis, schema validation, AI search optimization, and more
+argument-hint: "[subcommand] [URL]"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:seo - SEO analysis router"
+    - "Route to the appropriate sub-command based on user intent"
+    - "If no sub-command specified, show the quick reference guide"
+  state_fields:
+    - subcommand
+    - target_url
+---
+
+# /agileflow:seo
+
+SEO analysis toolkit for comprehensive website optimization. Routes to specialized sub-commands.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:seo:audit https://example.com                  # Full site audit (6 parallel analyzers)
+/agileflow:seo:page https://example.com/about              # Single page deep analysis
+/agileflow:seo:schema https://example.com                  # Schema/structured data validation
+/agileflow:seo:geo https://example.com                     # AI search optimization (GEO)
+/agileflow:seo:technical https://example.com               # Technical SEO deep-dive
+/agileflow:seo:content https://example.com                 # E-E-A-T & content quality
+/agileflow:seo:images https://example.com                  # Image optimization analysis
+/agileflow:seo:sitemap https://example.com                 # Sitemap validation
+/agileflow:seo:hreflang https://example.com                # Multi-language SEO
+/agileflow:seo:plan https://example.com                    # Strategic SEO planning
+/agileflow:seo:programmatic https://example.com            # Programmatic SEO quality gates
+/agileflow:seo:competitor https://example.com              # Competitor comparison pages
+```
+
+---
+
+## Sub-Commands
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| **audit** | Full site audit with health score | Starting point for any site |
+| **page** | Single page analysis (6 dimensions) | Optimize a specific page |
+| **schema** | Structured data validation + generation | Rich results optimization |
+| **geo** | AI search platform optimization | Optimize for ChatGPT, AI Overviews |
+| **technical** | Crawlability, indexing, security | Technical foundation issues |
+| **content** | E-E-A-T scoring + content quality | Content strategy improvement |
+| **images** | Alt text, sizing, formats, lazy loading | Image-heavy pages |
+| **sitemap** | XML sitemap validation | Crawl coverage concerns |
+| **hreflang** | Multi-language/region SEO | International sites |
+| **plan** | Strategic SEO roadmap | Planning SEO improvements |
+| **programmatic** | Bulk page quality gates | Programmatic SEO at scale |
+| **competitor** | Comparison page generation | Competitive positioning |
+
+---
+
+## Routing Logic
+
+If the user provides a URL without a sub-command, determine intent:
+
+1. **"audit my site"** → `/agileflow:seo:audit`
+2. **"check this page"** → `/agileflow:seo:page`
+3. **"structured data" / "schema" / "JSON-LD"** → `/agileflow:seo:schema`
+4. **"AI search" / "GEO" / "ChatGPT"** → `/agileflow:seo:geo`
+5. **"technical" / "crawl" / "robots"** → `/agileflow:seo:technical`
+6. **"content quality" / "E-E-A-T"** → `/agileflow:seo:content`
+7. **"images" / "alt text"** → `/agileflow:seo:images`
+8. **"sitemap"** → `/agileflow:seo:sitemap`
+9. **"international" / "hreflang" / "languages"** → `/agileflow:seo:hreflang`
+10. **"strategy" / "plan" / "roadmap"** → `/agileflow:seo:plan`
+11. **Unclear** → Show the quick reference and ask which analysis they want
+
+---
+
+## If No Sub-Command Specified
+
+Show the quick reference table above and ask:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Which SEO analysis would you like to run?",
+  "header": "SEO Analysis",
+  "multiSelect": false,
+  "options": [
+    {"label": "Full site audit (Recommended)", "description": "Comprehensive 6-analyzer audit with health score 0-100"},
+    {"label": "Single page analysis", "description": "Deep-dive into one specific page across 6 dimensions"},
+    {"label": "Schema validation", "description": "Check structured data, flag deprecated types, generate JSON-LD"},
+    {"label": "AI search optimization (GEO)", "description": "Optimize for ChatGPT, AI Overviews, Perplexity"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:seo` - SEO analysis router
+
+**Sub-commands**: audit, page, schema, geo, technical, content, images, sitemap, hreflang, plan, programmatic, competitor
+
+**Quick start**: `/agileflow:seo:audit https://example.com` for full analysis
+<!-- COMPACT_SUMMARY_END -->