agileflow 3.3.0 → 3.4.0

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

package/src/core/commands/seo/references/eeat-framework.md

@@ -0,0 +1,110 @@
+# E-E-A-T Scoring Framework
+
+Reference data for content quality analysis. Updated February 2026.
+
+---
+
+## Scoring Weights (100-point scale)
+
+| Factor | Weight | Description |
+|--------|--------|-------------|
+| **Trustworthiness** | 30% | Transparency, contact info, HTTPS, no deception |
+| **Expertise** | 25% | Credentials, accuracy, technical depth |
+| **Authoritativeness** | 25% | Citations, media features, industry standing |
+| **Experience** | 20% | First-hand knowledge, original content, case studies |
+
+---
+
+## Signal Detection
+
+### Trustworthiness (30%)
+
+| Signal | Present | Absent |
+|--------|---------|--------|
+| HTTPS | +5 | -10 |
+| Contact page / About page | +5 | -5 |
+| Privacy policy | +3 | -3 |
+| Terms of service | +2 | -2 |
+| Physical address | +3 | 0 |
+| Clear editorial policy | +4 | 0 |
+| No deceptive patterns (dark UX) | +5 | -10 |
+| Transparent affiliate disclosure | +3 | -5 |
+
+### Expertise (25%)
+
+| Signal | Present | Absent |
+|--------|---------|--------|
+| Author bylines with credentials | +5 | -3 |
+| Cited sources / references | +5 | -3 |
+| Technical accuracy (no factual errors) | +5 | -5 |
+| Industry-specific terminology (appropriate use) | +3 | 0 |
+| Depth of coverage (not surface-level) | +4 | -2 |
+| Peer review / editorial review mentioned | +3 | 0 |
+
+### Authoritativeness (25%)
+
+| Signal | Present | Absent |
+|--------|---------|--------|
+| Backlinks from authoritative domains | +5 | 0 |
+| Mentioned in media / press | +4 | 0 |
+| Industry awards / certifications | +3 | 0 |
+| Wikipedia reference | +4 | 0 |
+| Featured on Reddit / YouTube / forums | +3 | 0 |
+| Brand search volume indicators | +3 | 0 |
+| Consistent NAP (Name, Address, Phone) | +3 | -2 |
+
+### Experience (20%)
+
+| Signal | Present | Absent |
+|--------|---------|--------|
+| First-person accounts / case studies | +5 | -2 |
+| Original photography / screenshots | +4 | -1 |
+| Specific data / metrics from real usage | +4 | -2 |
+| User reviews / testimonials (authentic) | +3 | 0 |
+| Step-by-step from personal experience | +4 | -1 |
+
+---
+
+## Content Quality Minimums by Type
+
+| Page Type | Min Words | Unique Content % | Internal Links |
+|-----------|-----------|------------------|----------------|
+| Homepage | 500 | 100% | 5-10 |
+| Service pages | 800 | 60% | 3-8 |
+| Blog posts | 1,500 | 100% | 2-5 |
+| Product pages | 300-400 | 40% | 3-6 |
+| Location pages | 500-600 | 40% | 3-5 |
+| About page | 400 | 100% | 2-4 |
+| FAQ page | 600 | 80% | 2-5 |
+
+---
+
+## AI Content Rules
+
+- AI content is acceptable IF it demonstrates genuine E-E-A-T
+- Red flags for AI-generated content:
+  - Generic phrasing without specifics
+  - No original insights or data
+  - Fabricated first-person experiences
+  - Lack of cited sources
+  - Cookie-cutter structure across pages
+
+---
+
+## Critical 2025-2026 Updates
+
+| Date | Update | Impact |
+|------|--------|--------|
+| Dec 2025 | E-E-A-T applies to ALL queries (not just YMYL) | Affiliate traffic -71%, health -67% |
+| Feb 2026 | Experience signals weighted more heavily | Differentiator vs AI-generated content |
+
+---
+
+## Score Interpretation
+
+| Score | Rating | Action |
+|-------|--------|--------|
+| 80-100 | Strong E-E-A-T | Maintain, optimize further |
+| 60-79 | Adequate | Improve weakest factor |
+| 40-59 | Weak | Significant improvements needed |
+| 0-39 | Critical | Major content overhaul required |

package/src/core/commands/seo/references/quality-gates.md

@@ -0,0 +1,91 @@
+# SEO Quality Gates
+
+Reference data for programmatic SEO and content quality thresholds. Updated February 2026.
+
+---
+
+## On-Page Elements
+
+### Title Tag
+- **Length**: 30-60 characters
+- **Requirements**: Unique per page, keyword-forward, no truncation
+- **Flags**: Missing, duplicate, too short (<30), too long (>60), keyword-stuffed
+
+### Meta Description
+- **Length**: 120-160 characters
+- **Requirements**: Unique per page, natural keywords, includes CTA
+- **Flags**: Missing, duplicate, too short (<120), too long (>160)
+
+### Headings
+- **H1**: Exactly 1 per page, contains primary keyword
+- **H2-H6**: Logical hierarchy (no skipping levels), keyword-relevant
+- **Flags**: Missing H1, multiple H1s, skipped heading levels
+
+### Alt Text
+- **Length**: 10-125 characters
+- **Requirements**: Descriptive, not filename-based, contextually relevant
+- **Flags**: Missing, filename-based (IMG_001.jpg), too long, keyword-stuffed
+
+### Internal Links
+- **Target**: 2-10 per page (varies by content type)
+- **Requirements**: Descriptive anchor text, no broken links, logical structure
+- **Flags**: Orphan pages (0 internal links in), excessive links (>100)
+
+---
+
+## Programmatic SEO Thresholds
+
+| Metric | Warning | Hard Stop |
+|--------|---------|-----------|
+| Pages without audit | 100+ | 500+ |
+| Unique content per page | < 40% | < 20% |
+| Location pages created | 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+ |
+| Redirect chains (3+ hops) | 3+ | 10+ |
+
+---
+
+## Content Uniqueness Requirements
+
+| Page Type | Min Unique % | Template Allowed % |
+|-----------|-------------|-------------------|
+| Core pages (home, about, services) | 100% | 0% |
+| Blog posts / articles | 100% | 0% |
+| Product pages | 40% | 60% |
+| Location pages | 40% | 60% |
+| Category pages | 30% | 70% |
+
+---
+
+## URL Quality Standards
+
+- **Format**: Lowercase, hyphens (not underscores), no special characters
+- **Length**: Under 75 characters preferred, max 2048
+- **Depth**: Max 3-4 levels from root (e.g., /category/subcategory/page)
+- **Flags**: Uppercase, underscores, parameters without canonical, double slashes
+
+---
+
+## Crawl Budget Indicators
+
+| Metric | Healthy | Warning | Critical |
+|--------|---------|---------|----------|
+| Crawl rate (pages/day) | Stable/growing | Declining >10% | Declining >30% |
+| Index coverage errors | < 1% | 1-5% | > 5% |
+| Soft 404s | 0 | 1-10 | > 10 |
+| Blocked resources (CSS/JS) | 0 | 1-5 | > 5 |
+
+---
+
+## Priority Framework
+
+| Priority | Criteria | Examples |
+|----------|----------|----------|
+| **Critical** | Blocks indexing or causes penalties | noindex on key pages, robots.txt blocking, manual action |
+| **High** | Direct ranking impact | Missing title tags, slow LCP, broken canonical chains |
+| **Medium** | Optimization opportunity | Thin content, missing schema, suboptimal alt text |
+| **Low** | Nice-to-have improvement | Trailing slashes inconsistency, suboptimal URL structure |

package/src/core/commands/seo/references/schema-types.md

@@ -0,0 +1,102 @@
+# Schema Markup Types Reference
+
+Reference data for JSON-LD structured data validation. Updated February 2026.
+
+---
+
+## Actively Recommended Types
+
+These schema types are actively supported by Google and can generate rich results:
+
+| Type | Use Case | Required Properties |
+|------|----------|-------------------|
+| **Organization** | Business identity | name, url, logo |
+| **LocalBusiness** | Physical businesses | name, address, telephone, openingHours |
+| **Product** | E-commerce products | name, image, offers (price, availability, priceCurrency) |
+| **Article** | News/blog content | headline, image, datePublished, author |
+| **BlogPosting** | Blog content | headline, image, datePublished, author |
+| **Review** | Product/service reviews | itemReviewed, reviewRating, author |
+| **Event** | Events | name, startDate, location |
+| **JobPosting** | Job listings | title, description, datePosted, hiringOrganization |
+| **Course** | Educational content | name, description, provider |
+| **VideoObject** | Videos | name, description, thumbnailUrl, uploadDate |
+| **BroadcastEvent** | Live streams | isLiveBroadcast, startDate |
+| **ProfilePage** | Author profiles | mainEntity (Person) |
+| **ProductGroup** | Product variants | name, productGroupID, hasVariant |
+| **WebSite** | Site-level (sitelinks search) | name, url, potentialAction (SearchAction) |
+| **BreadcrumbList** | Navigation | itemListElement |
+| **FAQPage** | FAQs (restricted - see below) | mainEntity (Question + acceptedAnswer) |
+
+---
+
+## Restricted Types (Limited Use)
+
+| Type | Restriction | Details |
+|------|-------------|---------|
+| **FAQPage** | Government/healthcare only | Since August 2023, Google restricted FAQ rich results to government and health authority websites. Commercial sites should NOT use FAQPage schema. |
+
+---
+
+## Deprecated Types (Never Use)
+
+These types no longer generate rich results or have been explicitly deprecated:
+
+| Type | Deprecated Since | Replacement |
+|------|-----------------|-------------|
+| **HowTo** | Aug 2023 | None (removed from search features) |
+| **SpecialAnnouncement** | 2024 | None (COVID-era, sunset) |
+| **CourseInfo** | 2024 | Use Course instead |
+| **EstimatedSalary** | 2024 | Use JobPosting.estimatedSalary |
+| **LearningVideo** | 2024 | Use VideoObject |
+| **ClaimReview** | 2024 | Limited to approved fact-checkers |
+| **VehicleListing** | 2024 | Merchant API only |
+| **PracticeProblem** | 2024 | None |
+| **Dataset** | 2024 | Dataset Search only (not main SERP) |
+
+---
+
+## Critical Validation Rules
+
+| Rule | Details |
+|------|---------|
+| **@context** | Must use `https://schema.org` (HTTPS, not HTTP) |
+| **returnPolicyCountry** | Mandatory for Product schema (since March 2025) |
+| **ISO 8601 dates** | All date fields must use ISO 8601 format |
+| **Required properties** | All required properties must be present |
+| **Valid URLs** | All URL fields must be valid, accessible URLs |
+| **No empty values** | Properties must have meaningful values |
+| **Merchant API** | Product structured data must migrate to Merchant API by August 18, 2026 |
+
+---
+
+## Implementation Format
+
+- **Preferred**: JSON-LD in `<script type="application/ld+json">` (head or body)
+- **Acceptable**: Microdata, RDFa
+- **Recommendation**: Always use JSON-LD; it's easiest to maintain and Google's preferred format
+
+---
+
+## Common Validation Errors
+
+| Error | Severity | Fix |
+|-------|----------|-----|
+| Missing @context | Critical | Add `"@context": "https://schema.org"` |
+| HTTP in @context | High | Change to HTTPS |
+| Missing required property | High | Add the required property with valid value |
+| Deprecated type | Medium | Remove or replace per table above |
+| Invalid date format | Medium | Convert to ISO 8601 |
+| Missing returnPolicyCountry | High | Add to Product/Offer schema |
+| Nested errors in offers | Medium | Validate Offer sub-schema |
+
+---
+
+## Business Type to Schema Mapping
+
+| Business Type | Primary Schema Types |
+|--------------|---------------------|
+| **SaaS** | Organization, WebSite, Product, Article, FAQPage (if applicable) |
+| **Local Business** | LocalBusiness, Organization, Product/Service, Review, Event |
+| **E-commerce** | Product, ProductGroup, Organization, BreadcrumbList, Review |
+| **Publisher** | Article, BlogPosting, Organization, WebSite, ProfilePage |
+| **Agency** | Organization, LocalBusiness, Service, Review, Article |