agileflow 3.3.0 → 3.4.1

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 -->

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

@@ -0,0 +1,163 @@
+---
+description: Strategic SEO planning with industry-specific templates, competitive positioning, and prioritized roadmap generation
+argument-hint: "URL [TIMEFRAME=3mo|6mo|12mo]"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:seo:plan - Strategic SEO planning"
+    - "Detect business type first, then apply industry template"
+    - "Generate prioritized roadmap with timeframe milestones"
+    - "Reference audit results if available"
+  state_fields:
+    - target_url
+    - business_type
+    - timeframe
+---
+
+# /agileflow:seo:plan
+
+Generate a strategic SEO plan with industry-specific templates, competitive positioning analysis, and a prioritized improvement roadmap.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:seo:plan https://example.com                      # 6-month SEO plan (default)
+/agileflow:seo:plan https://example.com TIMEFRAME=3mo         # 3-month sprint plan
+/agileflow:seo:plan https://example.com TIMEFRAME=12mo        # Annual SEO strategy
+```
+
+---
+
+## Arguments
+
+| Argument | Values | Default | Description |
+|----------|--------|---------|-------------|
+| URL | Any valid URL | Required | Site to plan for |
+| TIMEFRAME | 3mo, 6mo, 12mo | 6mo | Planning horizon |
+
+---
+
+## Process
+
+### STEP 1: Assess Current State
+
+Fetch the site and determine:
+- Business type (SaaS, Local, E-commerce, Publisher, Agency)
+- Current SEO maturity (based on quick checks)
+- Existing audit results (check `docs/08-project/seo-audits/`)
+
+### STEP 2: Apply Industry Template
+
+| Business Type | Priority Areas | Key Strategies |
+|--------------|---------------|----------------|
+| **SaaS** | Content marketing, technical SEO, schema | Blog strategy, documentation SEO, product schema |
+| **Local Business** | Local SEO, Google Business, reviews | NAP consistency, local schema, review generation |
+| **E-commerce** | Product SEO, site structure, CWV | Product schema, faceted navigation, page speed |
+| **Publisher** | Content quality, E-E-A-T, freshness | Author pages, topic clusters, article schema |
+| **Agency** | Authority, portfolio SEO, local | Case studies, service pages, expertise signals |
+
+### STEP 3: Generate Roadmap
+
+Break the plan into phases:
+
+**3-Month Plan**:
+- Month 1: Critical fixes (blocking issues)
+- Month 2: Foundation (technical + schema)
+- Month 3: Content optimization
+
+**6-Month Plan**:
+- Month 1-2: Critical fixes + technical foundation
+- Month 3-4: Content strategy + schema implementation
+- Month 5-6: Authority building + performance optimization
+
+**12-Month Plan**:
+- Q1: Foundation (technical + critical fixes)
+- Q2: Content + schema
+- Q3: Authority + link building
+- Q4: Advanced optimization + monitoring
+
+### STEP 4: Output Plan
+
+```markdown
+# SEO Strategy: {URL}
+
+## Business Type: {type}
+## Timeframe: {timeframe}
+## Current Maturity: {Beginner/Intermediate/Advanced}
+
+---
+
+## Executive Summary
+
+{2-3 sentence overview of the site's SEO status and key opportunities}
+
+---
+
+## Phase 1: {title} (Month 1-X)
+
+### Goals
+- {Goal 1}
+- {Goal 2}
+
+### Actions
+- [ ] {Specific action with expected impact}
+- [ ] {Specific action}
+- [ ] {Specific action}
+
+### KPIs
+- {Metric to track}
+- {Metric to track}
+
+---
+
+## Phase 2: {title} (Month X-Y)
+
+[Same structure]
+
+---
+
+## Content Strategy
+
+### Topic Clusters
+| Pillar | Supporting Content | Target Keywords |
+|--------|-------------------|----------------|
+| {topic} | {subtopics} | {keywords} |
+
+### Content Calendar
+| Month | Content Type | Topic | Goal |
+|-------|-------------|-------|------|
+| 1 | {type} | {topic} | {goal} |
+
+---
+
+## Technical Priorities
+
+[Ranked list from audit findings or quick assessment]
+
+---
+
+## Measurement Framework
+
+| KPI | Current | Target ({timeframe}) |
+|-----|---------|---------------------|
+| Organic traffic | Baseline | +X% |
+| Indexed pages | {N} | {target} |
+| Core Web Vitals | {status} | All Good |
+| Schema types | {N} | {target} |
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:seo:plan` - Strategic SEO planning
+
+**Input**: URL + timeframe (3mo/6mo/12mo)
+
+**Output**: Industry-specific roadmap with phases, content strategy, and KPIs
+
+**Usage**: `/agileflow:seo:plan URL [TIMEFRAME=6mo]`
+<!-- COMPACT_SUMMARY_END -->

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

@@ -0,0 +1,131 @@
+---
+description: Programmatic SEO quality gates - validate bulk-generated pages for uniqueness, thin content, duplicate titles, and scale limits
+argument-hint: "URL [MAX_SAMPLE=20]"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:seo:programmatic - Programmatic SEO QA"
+    - "Check quality gates from quality-gates.md reference"
+    - "Sample pages to assess uniqueness and content quality"
+    - "Flag when thresholds are exceeded"
+  state_fields:
+    - target_url
+    - max_sample
+    - pages_sampled
+    - gate_violations
+---
+
+# /agileflow:seo:programmatic
+
+Quality gate enforcement for programmatic SEO. Validate bulk-generated pages for uniqueness, thin content, duplicate elements, and scale safety limits.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:seo:programmatic https://example.com               # Sample 20 pages for QA
+/agileflow:seo:programmatic https://example.com MAX_SAMPLE=50  # Larger sample
+```
+
+---
+
+## Arguments
+
+| Argument | Values | Default | Description |
+|----------|--------|---------|-------------|
+| URL | Any valid URL | Required | Site with programmatic pages |
+| MAX_SAMPLE | 5-100 | 20 | Number of pages to sample and analyze |
+
+---
+
+## Quality Gates (from quality-gates.md)
+
+| Metric | Warning | Hard Stop |
+|--------|---------|-----------|
+| Pages without audit | 100+ | 500+ |
+| Unique content per page | < 40% | < 20% |
+| Location pages | 30+ | 50+ |
+| Thin pages (< 300 words) | 10+ | 50+ |
+| Duplicate title tags | 5+ | 20+ |
+| Duplicate meta descriptions | 10+ | 30+ |
+| Pages with no internal links in | 5+ | 20+ |
+| 404 errors | 5+ | 20+ |
+
+---
+
+## Process
+
+### STEP 1: Discover Programmatic Pages
+
+Fetch sitemap to identify programmatic page patterns:
+- `/locations/*`, `/cities/*` (location pages)
+- `/products/*`, `/categories/*` (product pages)
+- `/topics/*`, `/tags/*` (topic pages)
+- Any repeating URL pattern with varying slugs
+
+### STEP 2: Sample Pages
+
+Select a representative sample:
+- Random selection across the pattern
+- Include first, middle, and last pages
+- Include edge cases (short slugs, long slugs)
+
+### STEP 3: Analyze Each Sampled Page
+
+For each page, check:
+
+| Check | What | Threshold |
+|-------|------|-----------|
+| **Word count** | Total content words | ≥ 300 (product), ≥ 500 (location) |
+| **Unique content %** | Content not shared with template | ≥ 40% |
+| **Title uniqueness** | Not identical to other sampled pages | Unique |
+| **Meta description** | Present and unique | Not duplicate |
+| **Internal links** | Links pointing to this page | ≥ 1 |
+| **Structured data** | Schema present and valid | Present |
+| **Content quality** | Not just template with city name swapped | Substantive |
+
+### STEP 4: Aggregate and Report
+
+```markdown
+# Programmatic SEO QA: {URL}
+
+## Pages Sampled: {N} of ~{total estimated}
+
+## Quality Gate Results
+
+| Gate | Status | Value | Threshold |
+|------|--------|-------|-----------|
+| Unique content | PASS/WARN/FAIL | {avg}% | ≥ 40% |
+| Thin content | PASS/WARN/FAIL | {N} pages < 300w | < 10 |
+| Duplicate titles | PASS/WARN/FAIL | {N} duplicates | < 5 |
+| Duplicate descriptions | PASS/WARN/FAIL | {N} duplicates | < 10 |
+| Internal links | PASS/WARN/FAIL | {N} orphans | < 5 |
+| Schema present | PASS/WARN/FAIL | {N} missing | 0 |
+
+## Sample Analysis
+
+| Page | Words | Unique % | Title Unique | Schema |
+|------|-------|----------|-------------|--------|
+| /locations/new-york | 450 | 52% | Yes | Yes |
+| /locations/los-angeles | 420 | 48% | Yes | Yes |
+| /locations/chicago | 280 | 35% | No (dup) | No |
+
+## Recommendations
+
+1. {Priority recommendation}
+2. {Next priority}
+3. {Next priority}
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:seo:programmatic` - Programmatic SEO quality gates
+
+**Checks**: Content uniqueness, thin pages, duplicate titles/descriptions, orphan pages
+
+**Usage**: `/agileflow:seo:programmatic URL [MAX_SAMPLE=20]`
+<!-- COMPACT_SUMMARY_END -->

package/src/core/commands/seo/references/cwv-thresholds.md

@@ -0,0 +1,64 @@
+# Core Web Vitals Thresholds
+
+Reference data for SEO performance analysis. Updated February 2026.
+
+---
+
+## Primary Metrics (75th Percentile)
+
+| Metric | Good | Needs Improvement | Poor |
+|--------|------|-------------------|------|
+| **LCP** (Largest Contentful Paint) | ≤ 2.5s | 2.5s - 4.0s | > 4.0s |
+| **INP** (Interaction to Next Paint) | ≤ 200ms | 200ms - 500ms | > 500ms |
+| **CLS** (Cumulative Layout Shift) | ≤ 0.1 | 0.1 - 0.25 | > 0.25 |
+
+**Note**: INP replaced FID (First Input Delay) as of March 2024.
+
+---
+
+## LCP Component Breakdown
+
+| Component | Target | Description |
+|-----------|--------|-------------|
+| TTFB (Time to First Byte) | < 800ms | Server response time |
+| Resource load delay | Minimize | Time between TTFB and resource request |
+| Resource load time | Minimize | Time to download LCP resource |
+| Element render delay | Minimize | Time between download and render |
+
+**Common LCP elements**: Hero images, heading text, video poster images, background images via CSS.
+
+---
+
+## Industry Adoption (Oct 2025)
+
+| Device | Meeting All Three CWV |
+|--------|----------------------|
+| Desktop | 57% |
+| Mobile | 50% |
+
+---
+
+## Mobile-Specific (Dec 2025 Update)
+
+- Mobile CWV now weighted heavier in ranking
+- Mobile performance is a critical ranking factor
+- Test with 4G throttling (1.6 Mbps down, 750 Kbps up, 150ms RTT)
+
+---
+
+## Scoring Ranges (for SEO audit)
+
+| Score | CWV Status | Meaning |
+|-------|-----------|---------|
+| 90-100 | All Good | All three metrics in "Good" range |
+| 70-89 | Mostly Good | 2 of 3 metrics Good, 1 Needs Improvement |
+| 50-69 | Needs Work | 1+ metrics in Needs Improvement |
+| 0-49 | Poor | 1+ metrics in Poor range |
+
+---
+
+## Data Sources
+
+- **Field data**: Chrome User Experience Report (CrUX), PageSpeed Insights API
+- **Lab data**: Lighthouse, WebPageTest, Chrome DevTools
+- **Recommendation**: Always prefer field data over lab data when available