codehava-agent-kit 1.0.1 → 3.0.0

package/templates/.agent/skills/seo-plan/assets/agency.md

@@ -0,0 +1,175 @@
+<!-- Updated: 2026-02-07 -->
+# Agency/Consultancy SEO Strategy Template
+
+## Industry Characteristics
+
+- Service-based, high-value transactions
+- Expertise and trust are paramount
+- Long consideration cycles
+- Portfolio/case study driven decisions
+- Relationship-based sales
+- Niche specialization benefits
+
+## Recommended Site Architecture
+
+```
+/
+├── Home
+├── /services
+│   ├── /service-1
+│   │   ├── /sub-service-1
+│   │   └── ...
+│   └── /service-2
+├── /industries
+│   ├── /industry-1
+│   ├── /industry-2
+│   └── ...
+├── /work (or /case-studies)
+│   ├── /case-study-1
+│   ├── /case-study-2
+│   └── ...
+├── /about
+│   ├── /team
+│   │   ├── /team-member-1
+│   │   └── ...
+│   ├── /culture
+│   └── /careers
+├── /insights (or /blog)
+│   ├── /articles
+│   ├── /guides
+│   ├── /webinars
+│   └── /podcasts
+├── /contact
+├── /process
+└── /faq
+```
+
+## Schema Recommendations
+
+| Page Type | Schema Types |
+|-----------|-------------|
+| Homepage | Organization, ProfessionalService |
+| Service Page | Service, ProfessionalService |
+| Case Study | Article, Organization (client) |
+| Team Member | Person, ProfilePage |
+| Blog | Article, BlogPosting |
+
+### ProfessionalService Schema Example
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "ProfessionalService",
+  "name": "Agency Name",
+  "description": "What the agency does",
+  "url": "https://example.com",
+  "logo": "https://example.com/logo.png",
+  "address": {
+    "@type": "PostalAddress",
+    "streetAddress": "123 Agency St",
+    "addressLocality": "City",
+    "addressRegion": "State",
+    "postalCode": "12345"
+  },
+  "telephone": "+1-555-555-5555",
+  "areaServed": "National",
+  "hasOfferCatalog": {
+    "@type": "OfferCatalog",
+    "name": "Services",
+    "itemListElement": [
+      {
+        "@type": "Offer",
+        "itemOffered": {
+          "@type": "Service",
+          "name": "Service 1"
+        }
+      }
+    ]
+  }
+}
+```
+
+## E-E-A-T Requirements
+
+### Team Pages Must Include
+- Professional headshots
+- Detailed bios with credentials
+- Industry experience
+- Speaking engagements
+- Publications
+- Social profiles
+
+### Case Studies Must Include
+- Client name (with permission) or industry
+- Challenge/problem statement
+- Approach/methodology
+- Results with specific metrics
+- Timeline
+- Testimonial quote
+
+## Content Priorities
+
+### High Priority
+1. Service pages (detailed, specific)
+2. Industry pages (vertical expertise)
+3. 3-5 detailed case studies
+4. Team/leadership pages
+
+### Medium Priority
+1. Methodology/process page
+2. Blog with thought leadership
+3. Comparison content (vs alternatives)
+4. FAQ page
+
+### Thought Leadership Topics
+- Industry trend analysis
+- How-to guides (non-competitive)
+- Original research/surveys
+- Event recaps and insights
+- Expert interviews
+- Tool/technology reviews
+
+## Content Strategy
+
+### Service Pages (min 800 words)
+- Clear value proposition
+- Methodology overview
+- Deliverables list
+- Relevant case studies
+- Team members who deliver this service
+- CTA to schedule consultation
+
+### Industry Pages (min 800 words)
+- Industry-specific challenges
+- How you solve them differently
+- Relevant case studies
+- Industry credentials/experience
+- Client logos (with permission)
+
+### Case Studies (min 1,000 words)
+- Executive summary
+- Client background
+- Challenge details
+- Solution approach
+- Implementation process
+- Measurable results
+- Client testimonial
+- Related services/CTA
+
+## Key Metrics to Track
+
+- Organic traffic to service pages
+- Case study page views
+- Contact form submissions from organic
+- Time on page for key content
+- Blog → service page conversion
+
+## Generative Engine Optimization (GEO) for Agencies
+
+- [ ] Publish original case studies with specific, citable metrics and results
+- [ ] Use Person schema with sameAs links for all team members (builds entity authority)
+- [ ] Use ProfilePage schema for team member pages
+- [ ] Include clear, quotable expertise statements in service page descriptions
+- [ ] Produce original industry research and surveys AI systems can cite
+- [ ] Structure thought leadership content with clear headings and extractable insights
+- [ ] Maintain consistent agency entity information across directories, social profiles, and industry sites
+- [ ] Monitor AI citation in ChatGPT, Perplexity, and Google AI Overviews for brand and key service terms

package/templates/.agent/skills/seo-plan/assets/ecommerce.md

@@ -0,0 +1,167 @@
+<!-- Updated: 2026-02-07 -->
+# E-commerce SEO Strategy Template
+
+## Industry Characteristics
+
+- High transaction intent
+- Product comparison behavior
+- Price sensitivity
+- Visual-first decision making
+- Seasonal demand patterns
+- Competitive marketplace listings
+
+## Recommended Site Architecture
+
+```
+/
+├── Home
+├── /collections (or /categories)
+│   ├── /category-1
+│   │   ├── /subcategory-1
+│   │   └── ...
+│   ├── /category-2
+│   └── ...
+├── /products
+│   ├── /product-1
+│   ├── /product-2
+│   └── ...
+├── /brands
+│   ├── /brand-1
+│   └── ...
+├── /sale (or /deals)
+├── /new-arrivals
+├── /best-sellers
+├── /gift-guide
+├── /blog
+│   ├── /buying-guides
+│   ├── /how-to
+│   └── /trends
+├── /about
+├── /contact
+├── /shipping
+├── /returns
+└── /faq
+```
+
+## Schema Recommendations
+
+| Page Type | Schema Types |
+|-----------|-------------|
+| Product Page | Product, Offer, AggregateRating, Review, BreadcrumbList |
+| Category Page | CollectionPage, ItemList, BreadcrumbList |
+| Brand Page | Brand, Organization |
+| Blog | Article, BlogPosting |
+
+### Additional E-commerce Schema (2025)
+
+- **ProductGroup**: Use for products with variants (size, color). Wraps individual Product entries with `variesBy` and `hasVariant` properties. See `schema/templates.json`.
+- **Certification**: For product certifications (Energy Star, safety, organic). Replaced EnergyConsumptionDetails (April 2025). Use `hasCertification` on Product.
+- **OfferShippingDetails**: Include shipping rate, handling time, and transit time. Critical for Merchant Center eligibility.
+
+> **Google Merchant Center Free Listings:** Products can appear in Google Shopping for free. Ensure Product structured data is in the initial server-rendered HTML (not JavaScript-injected) with required properties: `name`, `image`, `price`, `priceCurrency`, `availability`.
+
+> **JS Rendering Note:** Product structured data should be in initial server-rendered HTML: not dynamically injected via JavaScript (per December 2025 Google JS SEO guidance).
+
+### Product Schema Example
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Product",
+  "name": "Product Name",
+  "image": ["https://example.com/product.jpg"],
+  "description": "Product description",
+  "sku": "SKU123",
+  "brand": {
+    "@type": "Brand",
+    "name": "Brand Name"
+  },
+  "offers": {
+    "@type": "Offer",
+    "price": "99.99",
+    "priceCurrency": "USD",
+    "availability": "https://schema.org/InStock",
+    "url": "https://example.com/product"
+  },
+  "aggregateRating": {
+    "@type": "AggregateRating",
+    "ratingValue": "4.5",
+    "reviewCount": "42"
+  }
+}
+```
+
+## Content Requirements
+
+### Product Pages (min 400 words)
+- Unique product descriptions (not manufacturer copy)
+- Feature highlights
+- Use cases / who it's for
+- Specifications table
+- Size/fit guide (for apparel)
+- Care instructions
+- Customer reviews
+
+### Category Pages (min 400 words)
+- Category introduction
+- Buying guide excerpt
+- Featured products
+- Subcategory links
+- Filter/sort options
+
+## Technical Considerations
+
+### Pagination
+- Use rel="next"/rel="prev" or load-more
+- Ensure all products are crawlable
+- Canonical to main category page
+
+### Faceted Navigation
+- Noindex filter combinations that create duplicate content
+- Use canonical tags appropriately
+- Ensure popular filters are indexable
+
+### Product Variations
+- Single URL for parent product with variants
+- Or separate URLs with canonical to parent
+- Structured data for all variants
+
+## Content Priorities
+
+### High Priority
+1. Category pages (top level)
+2. Best-selling product pages
+3. Homepage
+4. Buying guides for main categories
+
+### Medium Priority
+1. Subcategory pages
+2. Brand pages
+3. Comparison content
+4. Seasonal landing pages
+
+### Blog Topics
+- Buying guides ("How to Choose...")
+- Product comparisons
+- Trend reports
+- Use cases and inspiration
+- Care and maintenance guides
+
+## Key Metrics to Track
+
+- Revenue from organic search
+- Product page rankings
+- Category page rankings
+- Click-through rate (rich results)
+- Average order value from organic
+
+## Generative Engine Optimization (GEO) for E-commerce
+
+AI search platforms increasingly answer product queries directly. Optimize for AI citation:
+
+- [ ] Include clear product specifications, dimensions, materials in structured format
+- [ ] Use ProductGroup schema for variant products
+- [ ] Provide original product photography with descriptive alt text
+- [ ] Include genuine customer review content (AggregateRating schema)
+- [ ] Maintain consistent product entity data across all platforms (site, Amazon, Merchant Center)
+- [ ] Structure comparison content with clear feature tables AI can parse
+- [ ] Add detailed FAQ content for common product questions

package/templates/.agent/skills/seo-plan/assets/generic.md

@@ -0,0 +1,144 @@
+<!-- Updated: 2026-02-07 -->
+# Generic Business SEO Strategy Template
+
+## Overview
+
+This template applies to businesses that don't fit neatly into SaaS, local service, e-commerce, publisher, or agency categories. Customize based on your specific business model.
+
+## Recommended Site Architecture
+
+```
+/
+├── Home
+├── /products (or /services)
+│   ├── /product-1
+│   ├── /product-2
+│   └── ...
+├── /solutions (if applicable)
+│   ├── /solution-1
+│   └── ...
+├── /about
+│   ├── /team
+│   ├── /history
+│   └── /values
+├── /resources
+│   ├── /blog
+│   ├── /guides
+│   ├── /faq
+│   └── /glossary
+├── /contact
+├── /support
+└── /legal
+    ├── /privacy
+    └── /terms
+```
+
+## Universal SEO Principles
+
+### Every Page Should Have
+- Unique title tag (30-60 chars)
+- Unique meta description (120-160 chars)
+- Single H1 matching page intent
+- Logical heading hierarchy (H1→H2→H3)
+- Internal links to related content
+- Clear call-to-action
+
+### Schema for All Sites
+| Page Type | Schema Types |
+|-----------|-------------|
+| Homepage | Organization, WebSite |
+| About | Organization, AboutPage |
+| Contact | ContactPage |
+| Blog | Article, BlogPosting |
+| FAQ | (FAQPage only for gov/health) |
+| Product/Service | Product or Service |
+
+## Content Quality Standards
+
+### Minimum Word Counts
+| Page Type | Min Words |
+|-----------|-----------|
+| Homepage | 500 |
+| Product/Service | 800 |
+| Blog Post | 1,500 |
+| About Page | 400 |
+| Landing Page | 600 |
+
+### E-E-A-T Essentials
+1. **Experience**: Share real examples and case studies
+2. **Expertise**: Display credentials and qualifications
+3. **Authoritativeness**: Earn mentions and citations
+4. **Trustworthiness**: Full contact info, policies visible
+
+## Technical Foundations
+
+### Must-Haves
+- [ ] HTTPS enabled
+- [ ] Mobile-responsive design
+- [ ] robots.txt configured
+- [ ] XML sitemap submitted
+- [ ] Google Search Console verified
+- [ ] Core Web Vitals passing (LCP <2.5s, INP <200ms, CLS <0.1)
+
+### Should-Haves
+- [ ] Structured data on key pages
+- [ ] Internal linking strategy
+- [ ] 404 error page optimized
+- [ ] Redirect chains eliminated
+- [ ] Image optimization (WebP, lazy loading)
+
+## Content Priorities
+
+### Phase 1: Foundation (weeks 1-4)
+1. Homepage optimization
+2. Core product/service pages
+3. About and contact pages
+4. Basic schema implementation
+
+### Phase 2: Expansion (weeks 5-12)
+1. Blog launch (2-4 posts/month)
+2. FAQ page
+3. Additional product/service pages
+4. Internal linking audit
+
+### Phase 3: Growth (weeks 13-24)
+1. Consistent content publishing
+2. Link building outreach
+3. GEO optimization
+4. Performance optimization
+
+### Phase 4: Authority (months 7-12)
+1. Thought leadership content
+2. Original research
+3. PR and media mentions
+4. Advanced schema
+
+## Key Metrics to Track
+
+- Organic traffic (overall and by section)
+- Keyword rankings (branded and non-branded)
+- Conversion rate from organic
+- Pages indexed
+- Core Web Vitals scores
+- Backlinks acquired
+
+## Customization Points
+
+Adjust this template based on:
+
+1. **Business Model**: B2B vs B2C vs D2C
+2. **Geographic Scope**: Local, national, or international
+3. **Content Type**: Product-focused vs content-heavy
+4. **Competition Level**: Niche vs competitive market
+5. **Resources**: Budget and team capacity
+
+## Generative Engine Optimization (GEO) Checklist
+
+- [ ] Include clear, quotable facts and statistics that AI systems can extract and cite
+- [ ] Use structured data (Schema.org) to help AI systems understand content
+- [ ] Build topical authority through comprehensive content clusters
+- [ ] Provide original data, research, or unique perspectives AI cannot find elsewhere
+- [ ] Maintain consistent entity information (brand, people, products) across the web
+- [ ] Structure content with clear headings, definitions, and step-by-step formats
+- [ ] Consider adding an `llms.txt` file at site root (emerging convention for AI crawlers: Google treats it as a regular text file)
+- [ ] Monitor AI citation across Google AI Overviews, ChatGPT, Perplexity, and Bing Copilot

package/templates/.agent/skills/seo-plan/assets/local-service.md

@@ -0,0 +1,160 @@
+<!-- Updated: 2026-02-07 -->
+# Local Service Business SEO Strategy Template
+
+## Industry Characteristics
+
+- Geographic-focused searches
+- High intent, quick decision making
+- Reviews heavily influence decisions
+- Phone calls are primary conversion
+- Mobile-first user behavior
+- Emergency/urgent service needs
+
+## Recommended Site Architecture
+
+```
+/
+├── Home
+├── /services
+│   ├── /service-1
+│   ├── /service-2
+│   └── ...
+├── /locations
+│   ├── /city-1
+│   │   ├── /service-1-city-1
+│   │   └── ...
+│   ├── /city-2
+│   └── ...
+├── /about
+├── /reviews
+├── /gallery (or /portfolio)
+├── /blog
+├── /contact
+├── /emergency (if applicable)
+└── /faq
+```
+
+## Quality Gates
+
+### Location Page Limits
+- ⚠️ **WARNING** at 30+ location pages
+- 🛑 **HARD STOP** at 50+ location pages
+
+### Unique Content Requirements
+| Page Type | Min Words | Unique % |
+|-----------|-----------|----------|
+| Primary Location | 600 | 60%+ |
+| Service Area | 500 | 40%+ |
+| Service Page | 800 | 100% |
+
+### What Makes Location Pages Unique
+- Local landmarks and neighborhoods
+- Specific services offered at that location
+- Local team members
+- Location-specific testimonials
+- Community involvement
+- Local regulations or considerations
+
+## Schema Recommendations
+
+| Page Type | Schema Types |
+|-----------|-------------|
+| Homepage | LocalBusiness, Organization |
+| Service Pages | Service, LocalBusiness |
+| Location Pages | LocalBusiness (with geo) |
+| Contact | ContactPage, LocalBusiness |
+| Reviews | LocalBusiness (with AggregateRating) |
+
+### LocalBusiness Schema Example
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "LocalBusiness",
+  "name": "Business Name",
+  "address": {
+    "@type": "PostalAddress",
+    "streetAddress": "123 Main St",
+    "addressLocality": "City",
+    "addressRegion": "State",
+    "postalCode": "12345"
+  },
+  "telephone": "+1-555-555-5555",
+  "openingHours": "Mo-Fr 08:00-18:00",
+  "geo": {
+    "@type": "GeoCoordinates",
+    "latitude": "40.7128",
+    "longitude": "-74.0060"
+  },
+  "areaServed": ["City 1", "City 2"],
+  "priceRange": "$$"
+}
+```
+
+## Google Business Profile Integration
+
+- Ensure NAP consistency (Name, Address, Phone)
+- Sync service categories
+- Regular post updates
+- Photo uploads
+- Review response strategy
+
+### Google Business Profile Updates (2025-2026)
+
+- **Video verification** is now standard: postcard verification has been largely phased out. Prepare for a short video verification process showing the business location or service area.
+- **WhatsApp integration** replaced Google Business Chat (deprecated). Businesses can connect WhatsApp as their primary messaging channel.
+- **Q&A removed from Maps**: replaced by AI-generated answers. Ensure your GBP description, services, and website FAQ are comprehensive, as Google AI uses them to answer queries.
+- **Business hours are a top-5 ranking factor**: "Business is open at time of search" ranked as a top individual factor for the first time (Whitespark 2026 Local Search Ranking Factors Report). Keep hours accurate; consider extended hours if feasible.
+- **Review "Stories" format**: Google Maps now shows review snippets in a swipeable Stories format on mobile. Encourage detailed, descriptive reviews with photos.
+
+### Service Area Business (SAB) Update (June 2025)
+
+Google updated SAB guidelines to **disallow entire states or countries** as service areas. SABs must specify: cities, postal/ZIP codes, or neighborhoods. If you serve an entire metro area, list the major cities within it rather than the state.
+
+### AI Visibility for Local Businesses
+
+AI Overviews appear for only ~0.14% of local keywords (March 2025 data), local SEO faces significantly less AI disruption than other verticals. However, ChatGPT and Perplexity are increasingly used for local recommendations.
+
+To optimize for AI local visibility:
+- Ensure presence on expert-curated "best of" lists (ranked #1 AI visibility factor in Whitespark 2026 report)
+- Maintain consistent NAP (Name, Address, Phone) across all platforms
+- Build genuine review volume and quality
+- Use LocalBusiness schema with complete properties (geo, openingHours, priceRange, areaServed)
+
+## Content Priorities
+
+### High Priority
+1. Homepage with clear service area
+2. Core service pages
+3. Primary city page
+4. Contact page with all locations
+
+### Medium Priority
+1. Service + location combination pages
+2. FAQ page
+3. About/team page
+4. Reviews/testimonials page
+
+### Blog Topics
+- Seasonal maintenance tips
+- How to choose a [service provider]
+- Warning signs of [problem]
+- DIY vs professional comparisons
+- Local regulations and permits
+
+## Key Metrics to Track
+
+- Local pack rankings
+- Phone call volume from organic
+- Direction requests
+- Google Business Profile insights
+- Reviews count and rating
+
+## Generative Engine Optimization (GEO) for Local
+
+- [ ] Include clear, quotable service descriptions and pricing ranges
+- [ ] Use LocalBusiness schema with complete geo, openingHours, and areaServed
+- [ ] Build presence on curated "best of" and local directory lists
+- [ ] Maintain consistent NAP across all platforms (Google, Yelp, Apple Maps)
+- [ ] Include original photos of work, team, and location
+- [ ] Structure FAQ content for common local service questions
+- [ ] Monitor AI citation in ChatGPT and Perplexity local recommendations