agileflow 3.3.0 → 3.4.0

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

@@ -0,0 +1,229 @@
+---
+description: Generative Engine Optimization (GEO) - analyze and optimize content for AI search platforms like ChatGPT, Google AI Overviews, and Perplexity
+argument-hint: "URL"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:seo:geo - AI search optimization"
+    - "Assess 5 GEO dimensions: Citability, Structure, Multimodal, Authority, Technical Access"
+    - "Check robots.txt for AI bot access (GPTBot, ClaudeBot, PerplexityBot)"
+    - "Check for /llms.txt file"
+    - "Optimize for 134-167 word citation blocks"
+  state_fields:
+    - target_url
+    - geo_score
+    - ai_bot_access
+---
+
+# /agileflow:seo:geo
+
+Analyze and optimize content for AI search platforms (Generative Engine Optimization). Ensure your content gets cited by ChatGPT, Google AI Overviews, Perplexity, and Claude.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:seo:geo https://example.com                      # Full GEO analysis
+/agileflow:seo:geo https://example.com/blog/guide            # Analyze specific content page
+```
+
+---
+
+## Background
+
+**GEO (Generative Engine Optimization)** optimizes content for AI-powered search platforms:
+- Google AI Overviews
+- ChatGPT (with Browse/Search)
+- Perplexity
+- Claude
+
+**Key insight**: Brand correlation is 3x stronger than backlinks for AI visibility. 92% of AI citations come from top-10 traditional search results.
+
+---
+
+## Arguments
+
+| Argument | Values | Default | Description |
+|----------|--------|---------|-------------|
+| URL | Any valid URL | Required | Page or site to analyze |
+
+---
+
+## GEO Assessment Framework
+
+### 1. Citability (25%)
+
+AI platforms cite content that contains self-contained, quotable blocks:
+
+| Signal | Good | Poor |
+|--------|------|------|
+| Answer blocks | 134-167 word self-contained paragraphs | Long unbroken paragraphs |
+| Specific facts | Numbers, dates, names, percentages | Vague generalizations |
+| Definitions | Clear "X is Y" statements | Implied definitions |
+| Lists | Numbered/bulleted key points | Points buried in prose |
+| Attribution | "According to [source]..." | Unsourced claims |
+
+**Check**: Count paragraphs in the 134-167 word range. Assess whether they answer specific questions independently.
+
+### 2. Structure (20%)
+
+AI platforms parse structured content more effectively:
+
+| Signal | Good | Poor |
+|--------|------|------|
+| Question headers | H2/H3 as questions (Who, What, How) | Generic headings |
+| Short paragraphs | 2-4 sentences | Wall of text |
+| Tables | Comparison data in tables | Comparisons in prose |
+| Numbered steps | Step-by-step instructions | Instructions in paragraphs |
+| TL;DR / Summary | Key takeaway at top or bottom | No summary |
+
+### 3. Multimodal Content (15%)
+
+Pages with multiple content types get 156% higher AI citation rates:
+
+| Signal | Good | Poor |
+|--------|------|------|
+| Text + Images | Informative images with good alt text | Text only |
+| Text + Video | Embedded video with transcript | No video |
+| Text + Tables | Data visualization | Numbers in paragraphs |
+| Interactive | Calculators, tools, quizzes | Static content only |
+| Infographics | Visual summaries | No visual aids |
+
+### 4. Authority (20%)
+
+AI platforms prioritize authoritative sources:
+
+| Signal | Good | Poor |
+|--------|------|------|
+| Author credentials | Named author with bio/credentials | No attribution |
+| Publication dates | Recent, prominently displayed | No dates or old |
+| Primary sources | Original data, research, case studies | Only secondary sources |
+| Citations | Links to authoritative references | No outbound links |
+| Brand presence | Wikipedia, Reddit, YouTube mentions | No cross-platform presence |
+
+### 5. Technical Access (20%)
+
+AI bots must be able to access your content:
+
+| Signal | Good | Poor |
+|--------|------|------|
+| GPTBot allowed | Not blocked in robots.txt | Blocked |
+| ClaudeBot allowed | Not blocked in robots.txt | Blocked |
+| PerplexityBot allowed | Not blocked in robots.txt | Blocked |
+| Google-Extended allowed | Not blocked | Blocked |
+| `/llms.txt` present | Exists at root | Missing |
+| Server-side rendering | Content in HTML source | JS-only rendering |
+| Fast response | Quick TTFB | Slow or rate-limited |
+
+---
+
+## Process
+
+### STEP 1: Fetch Target Page
+
+Use WebFetch to retrieve the page content.
+
+### STEP 2: Fetch robots.txt
+
+Check `{domain}/robots.txt` for AI bot rules:
+```
+User-agent: GPTBot
+User-agent: ClaudeBot
+User-agent: PerplexityBot
+User-agent: Google-Extended
+```
+
+### STEP 3: Check for llms.txt
+
+Fetch `{domain}/llms.txt` - a machine-readable site description for AI platforms.
+
+### STEP 4: Analyze Each Dimension
+
+Score each of the 5 dimensions out of 100, then apply weights:
+
+| Dimension | Weight |
+|-----------|--------|
+| Citability | 25% |
+| Structure | 20% |
+| Multimodal | 15% |
+| Authority | 20% |
+| Technical Access | 20% |
+
+### STEP 5: Output Report
+
+```markdown
+# GEO Analysis: {URL}
+
+## AI Search Readiness Score: {X}/100
+
+| Dimension | Score | Weight | Weighted | Key Finding |
+|-----------|-------|--------|----------|-------------|
+| Citability | {X}/100 | 25% | {X} | {finding} |
+| Structure | {X}/100 | 20% | {X} | {finding} |
+| Multimodal | {X}/100 | 15% | {X} | {finding} |
+| Authority | {X}/100 | 20% | {X} | {finding} |
+| Technical Access | {X}/100 | 20% | {X} | {finding} |
+
+## AI Bot Access Status
+
+| Bot | Status | robots.txt |
+|-----|--------|-----------|
+| GPTBot (ChatGPT) | Allowed/Blocked | {rule or "No rule"} |
+| ClaudeBot (Claude) | Allowed/Blocked | {rule or "No rule"} |
+| PerplexityBot | Allowed/Blocked | {rule or "No rule"} |
+| Google-Extended (AI Overviews) | Allowed/Blocked | {rule or "No rule"} |
+
+## llms.txt: {Present/Missing}
+
+## Citability Analysis
+
+- Citation-ready blocks found: {N}
+- Average paragraph length: {N} words
+- Self-contained answer blocks: {N}
+
+## Recommendations
+
+### Quick Wins
+1. {highest impact, easiest change}
+2. {next priority}
+
+### Content Improvements
+1. {content change for better citability}
+2. {structural improvement}
+
+### Technical Changes
+1. {robots.txt or llms.txt change}
+```
+
+### STEP 6: Offer Next Steps
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "GEO analysis: AI Search Readiness {X}/100. {bot_status}. {N} citation-ready blocks found.",
+  "header": "Next steps",
+  "multiSelect": false,
+  "options": [
+    {"label": "Improve citability (Recommended)", "description": "Restructure content into 134-167 word answer blocks"},
+    {"label": "Fix AI bot access", "description": "Update robots.txt to allow GPTBot, ClaudeBot, PerplexityBot"},
+    {"label": "Create llms.txt", "description": "Generate machine-readable site description"},
+    {"label": "Run full SEO audit", "description": "/agileflow:seo:audit {domain}"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:seo:geo` - AI search optimization (Generative Engine Optimization)
+
+**5 Dimensions**: Citability 25%, Structure 20%, Multimodal 15%, Authority 20%, Technical Access 20%
+
+**Key Checks**: AI bot access in robots.txt, llms.txt presence, 134-167 word citation blocks
+
+**Target Platforms**: Google AI Overviews, ChatGPT, Perplexity, Claude
+<!-- COMPACT_SUMMARY_END -->

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

@@ -0,0 +1,140 @@
+---
+description: Multi-language SEO validation - hreflang tag correctness, reciprocity checks, language code validation, and international targeting
+argument-hint: "URL"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:seo:hreflang - Multi-language SEO"
+    - "Check hreflang tags, reciprocity, language codes, x-default"
+    - "Verify all language versions reference each other"
+  state_fields:
+    - target_url
+    - languages_found
+    - reciprocity_issues
+---
+
+# /agileflow:seo:hreflang
+
+Validate multi-language SEO implementation: hreflang tags, reciprocity, language codes, x-default, and international targeting.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:seo:hreflang https://example.com                  # Check hreflang implementation
+/agileflow:seo:hreflang https://example.com/es/              # Check from Spanish version
+```
+
+---
+
+## Arguments
+
+| Argument | Values | Default | Description |
+|----------|--------|---------|-------------|
+| URL | Any valid URL | Required | Page to check hreflang |
+
+---
+
+## What Gets Checked
+
+### 1. Hreflang Tag Detection
+
+Look for hreflang in three possible locations:
+- HTML `<head>`: `<link rel="alternate" hreflang="es" href="...">`
+- HTTP headers: `Link: <...>; rel="alternate"; hreflang="es"`
+- XML sitemap: `<xhtml:link rel="alternate" hreflang="es" href="..."/>`
+
+### 2. Validation Rules
+
+| Rule | Check | Common Error |
+|------|-------|-------------|
+| **Valid language codes** | ISO 639-1 (2-letter) | "eng" instead of "en" |
+| **Valid region codes** | ISO 3166-1 (2-letter) | "uk" instead of "gb" |
+| **x-default present** | Fallback for unmatched | Missing x-default |
+| **Self-referencing** | Page includes itself | Missing self-reference |
+| **Reciprocity** | A→B means B→A | One-way hreflang |
+| **Consistent URLs** | Match canonical | hreflang to non-canonical |
+| **Absolute URLs** | Full https:// URLs | Relative paths |
+| **Return 200** | All hreflang URLs live | 404 or redirect targets |
+
+### 3. Reciprocity Check
+
+For each language version:
+1. Fetch the page
+2. Check that it links back to all other versions
+3. Flag any broken reciprocity chains
+
+```
+Page A (en) → B (es), C (fr)
+Page B (es) → A (en), C (fr)  ← Must reference A and C
+Page C (fr) → A (en), B (es)  ← Must reference A and B
+```
+
+### 4. Common Issues
+
+| Issue | Severity | Fix |
+|-------|----------|-----|
+| Missing x-default | HIGH | Add x-default pointing to canonical version |
+| Broken reciprocity | HIGH | Ensure all versions reference each other |
+| Invalid language code | MEDIUM | Use ISO 639-1 codes |
+| hreflang to redirect | MEDIUM | Point to final destination URL |
+| hreflang to noindex | HIGH | Don't noindex alternate versions |
+| Mixed implementation | LOW | Use one method consistently |
+
+---
+
+## Process
+
+### STEP 1: Fetch the Target Page
+
+Use WebFetch to retrieve the page. Extract hreflang tags from HTML head.
+
+### STEP 2: Map All Language Versions
+
+Build a matrix of all language versions and their hreflang references.
+
+### STEP 3: Verify Reciprocity
+
+Fetch each alternate version and verify it references back to all other versions.
+
+### STEP 4: Output Report
+
+```markdown
+# Hreflang Analysis: {URL}
+
+## Language Versions Found
+
+| Language | Region | URL | Status |
+|----------|--------|-----|--------|
+| en | - | https://example.com/ | 200 |
+| es | - | https://example.com/es/ | 200 |
+| fr | FR | https://example.com/fr/ | 200 |
+| x-default | - | https://example.com/ | 200 |
+
+## Reciprocity Matrix
+
+| Page | → en | → es | → fr | → x-default |
+|------|------|------|------|-------------|
+| /en/ | self | yes | yes | yes |
+| /es/ | yes | self | NO | yes |
+| /fr/ | yes | yes | self | yes |
+
+## Issues Found
+
+[Detailed findings]
+
+## Hreflang Score: X/100
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:seo:hreflang` - Multi-language SEO validation
+
+**Checks**: hreflang tags, reciprocity, language codes, x-default, canonical consistency
+
+**Usage**: `/agileflow:seo:hreflang URL`
+<!-- COMPACT_SUMMARY_END -->

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

@@ -0,0 +1,96 @@
+---
+description: Image optimization analysis - alt text quality, sizing for CLS, WebP/AVIF format detection, lazy loading, and responsive images
+argument-hint: "URL"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:seo:images - Image optimization analysis"
+    - "Deploy seo-analyzer-images for comprehensive image audit"
+    - "Check alt text, sizing, formats, lazy loading, LCP priority, responsive srcset"
+  state_fields:
+    - target_url
+    - image_count
+    - issues_found
+---
+
+# /agileflow:seo:images
+
+Analyze image optimization on a page: alt text quality, explicit sizing for CLS prevention, modern formats (WebP/AVIF), lazy loading, LCP image priority, and responsive images.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:seo:images https://example.com                    # Image audit for homepage
+/agileflow:seo:images https://example.com/products/item       # Product page images
+```
+
+---
+
+## Arguments
+
+| Argument | Values | Default | Description |
+|----------|--------|---------|-------------|
+| URL | Any valid URL | Required | Page to analyze |
+
+---
+
+## Process
+
+### STEP 1: Deploy Image Analyzer
+
+```xml
+<invoke name="Task">
+<parameter name="description">Image optimization analysis</parameter>
+<parameter name="prompt">TASK: Perform comprehensive image optimization analysis.
+
+TARGET URL: {url}
+
+For every image on the page, check:
+1. Alt text: Present, descriptive (10-125 chars), not filename-based, not keyword-stuffed
+2. Sizing: width and height attributes present (CLS prevention)
+3. Format: WebP/AVIF (modern) vs JPEG/PNG (legacy) vs BMP/TIFF (never)
+4. Lazy loading: Below-fold images have loading="lazy"
+5. LCP priority: Hero/above-fold image has fetchpriority="high"
+6. Responsive: srcset and sizes for responsive delivery
+7. Decorative: Decorative images correctly use alt=""
+
+Also check for:
+- CSS background images (can't have alt text)
+- <picture> elements with format fallbacks
+- Missing <link rel="preload"> for LCP image
+
+OUTPUT: Image Optimization Score X/100 with per-image findings.</parameter>
+<parameter name="subagent_type">seo-analyzer-images</parameter>
+</invoke>
+```
+
+### STEP 2: Present Results
+
+Show image-by-image findings table and prioritized fixes.
+
+---
+
+## What Gets Checked
+
+| Aspect | Weight | Impact |
+|--------|--------|--------|
+| Alt text quality | 30% | Accessibility + image search rankings |
+| Sizing (CLS) | 20% | Core Web Vitals - layout stability |
+| Modern formats | 15% | Page speed + LCP |
+| Lazy loading | 15% | Page speed |
+| LCP optimization | 10% | Core Web Vitals - largest paint |
+| Responsive images | 10% | Mobile performance |
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:seo:images` - Image optimization analysis
+
+**Checks**: Alt text, sizing/CLS, WebP/AVIF, lazy loading, LCP priority, responsive srcset
+
+**Usage**: `/agileflow:seo:images URL`
+<!-- COMPACT_SUMMARY_END -->

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

@@ -0,0 +1,198 @@
+---
+description: Deep single-page SEO analysis across 6 dimensions - on-page, content, technical, schema, images, and performance
+argument-hint: "URL [FOCUS=all|on-page|content|technical|schema|images|performance]"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:seo:page - Single page SEO analysis"
+    - "Fetch the page with WebFetch, then analyze across 6 dimensions"
+    - "FOCUS parameter narrows analysis to specific dimension"
+    - "Output a scored report card per dimension"
+  state_fields:
+    - target_url
+    - focus
+    - page_scores
+---
+
+# /agileflow:seo:page
+
+Deep analysis of a single page across 6 SEO dimensions. More thorough than the full-site audit for individual pages.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:seo:page https://example.com/about              # Full 6-dimension analysis
+/agileflow:seo:page https://example.com/blog/post FOCUS=content   # Content quality only
+/agileflow:seo:page https://example.com/product FOCUS=schema      # Schema markup only
+/agileflow:seo:page https://example.com FOCUS=on-page             # On-page SEO elements
+```
+
+---
+
+## Arguments
+
+| Argument | Values | Default | Description |
+|----------|--------|---------|-------------|
+| URL | Any valid page URL | Required | Page to analyze |
+| FOCUS | all, on-page, content, technical, schema, images, performance | all | Which dimension(s) to analyze |
+
+---
+
+## Analysis Dimensions
+
+### 1. On-Page SEO
+
+Analyze the fundamental on-page elements:
+
+| Element | Check | Good | Issue |
+|---------|-------|------|-------|
+| **Title tag** | Present, 30-60 chars, keyword-forward | Unique, relevant | Missing, duplicate, wrong length |
+| **Meta description** | Present, 120-160 chars, has CTA | Compelling, keyword-rich | Missing, duplicate, wrong length |
+| **H1** | Exactly 1, contains target keyword | Clear, descriptive | Missing, multiple, keyword-stuffed |
+| **H2-H6** | Logical hierarchy, no skipped levels | Organized structure | Skipped levels, flat structure |
+| **Internal links** | 2-10 per page, descriptive anchors | Relevant, contextual | None, generic "click here" |
+| **External links** | Authoritative sources | Relevant citations | Broken, spammy |
+| **URL** | Clean, short, keyword-relevant | Descriptive path | Parameters, long, irrelevant |
+| **Canonical** | Self-referencing or correct target | Present, valid | Missing, pointing wrong |
+| **Open Graph** | og:title, og:description, og:image | All present | Missing key tags |
+
+### 2. Content Quality
+
+Assess using E-E-A-T framework (see eeat-framework.md reference):
+- Word count vs page type minimum
+- Content uniqueness (not boilerplate)
+- Readability level
+- Author attribution
+- E-E-A-T signals present
+- AI citation readiness (134-167 word blocks)
+
+### 3. Technical
+
+Page-level technical checks:
+- HTTP status code
+- Response time / TTFB
+- HTTPS
+- Mobile viewport
+- Canonical tag correctness
+- Robots directives (index/noindex)
+- Structured data presence
+- Language declaration
+
+### 4. Schema
+
+Structured data on this specific page:
+- What JSON-LD/Microdata is present
+- Validation of existing schema
+- Missing schema opportunities for this page type
+- Rich result eligibility
+
+### 5. Images
+
+All images on the page:
+- Alt text quality
+- Width/height attributes
+- Format (WebP/AVIF vs legacy)
+- Lazy loading
+- LCP image optimization
+
+### 6. Performance
+
+Page-level performance indicators:
+- Render-blocking resources
+- Script loading (async/defer)
+- Image optimization
+- Third-party resources
+- Font loading
+- Estimated CWV impact
+
+---
+
+## Process
+
+### STEP 1: Fetch the Page
+
+Use WebFetch to retrieve the target URL. Extract full HTML content.
+
+### STEP 2: Analyze Per Focus
+
+If `FOCUS=all`, analyze all 6 dimensions. Otherwise, analyze only the specified dimension.
+
+For each dimension, produce a score out of 100 and a findings list.
+
+### STEP 3: Generate Report Card
+
+Output a report card:
+
+```markdown
+# Page SEO Report: {URL}
+
+## Report Card
+
+| Dimension | Score | Key Finding |
+|-----------|-------|-------------|
+| On-Page SEO | {X}/100 | {top issue or "All good"} |
+| Content Quality | {X}/100 | {top issue or "All good"} |
+| Technical | {X}/100 | {top issue or "All good"} |
+| Schema | {X}/100 | {top issue or "All good"} |
+| Images | {X}/100 | {top issue or "All good"} |
+| Performance | {X}/100 | {top issue or "All good"} |
+
+**Page Score: {average}/100**
+
+---
+
+## Detailed Findings
+
+### On-Page SEO ({X}/100)
+
+| Element | Status | Details |
+|---------|--------|---------|
+| Title | {pass/fail} | "{actual title}" ({length} chars) |
+| Meta Description | {pass/fail} | "{actual}" ({length} chars) |
+| H1 | {pass/fail} | "{actual H1}" |
+| ...
+
+[Findings for each dimension]
+
+---
+
+## Quick Fixes
+
+1. {Highest impact, easiest fix}
+2. {Next priority}
+3. {Next priority}
+```
+
+### STEP 4: Offer Next Steps
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Page analysis complete: {URL} scored {X}/100. Lowest dimension: {dim} ({score}/100).",
+  "header": "Next steps",
+  "multiSelect": false,
+  "options": [
+    {"label": "Fix {top_issue} (Recommended)", "description": "{specific fix description}"},
+    {"label": "Generate schema markup", "description": "Create JSON-LD for this page type"},
+    {"label": "Run full site audit", "description": "/agileflow:seo:audit {domain}"},
+    {"label": "Analyze another page", "description": "Run /agileflow:seo:page on a different URL"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:seo:page` - Single page SEO analysis across 6 dimensions
+
+**Dimensions**: On-Page, Content, Technical, Schema, Images, Performance
+
+**Usage**: `/agileflow:seo:page URL [FOCUS=dimension]`
+
+**Output**: Scored report card per dimension + prioritized fixes
+<!-- COMPACT_SUMMARY_END -->