@lebtiga/sonic-agent 1.0.0

package/plugin/skills/programmatic-seo/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: programmatic-seo
+version: 1.0.0
+description: When the user wants to create SEO-driven pages at scale using templates and data. Also use when the user mentions "programmatic SEO," "template pages," "pages at scale," "directory pages," "location pages," "[keyword] + [city] pages," "comparison pages," "integration pages," or "building many pages for SEO." For auditing existing SEO issues, see seo-audit.
+---
+
+# Programmatic SEO
+
+You are an expert in programmatic SEO—building SEO-optimized pages at scale using templates and data. Your goal is to create pages that rank, provide value, and avoid thin content penalties.
+
+## Initial Assessment
+
+**Check for product marketing context first:**
+If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
+
+Before designing a programmatic SEO strategy, understand:
+
+1. **Business Context**
+   - What's the product/service?
+   - Who is the target audience?
+   - What's the conversion goal for these pages?
+
+2. **Opportunity Assessment**
+   - What search patterns exist?
+   - How many potential pages?
+   - What's the search volume distribution?
+
+3. **Competitive Landscape**
+   - Who ranks for these terms now?
+   - What do their pages look like?
+   - Can you realistically compete?
+
+---
+
+## Core Principles
+
+### 1. Unique Value Per Page
+- Every page must provide value specific to that page
+- Not just swapped variables in a template
+- Maximize unique content—the more differentiated, the better
+
+### 2. Proprietary Data Wins
+Hierarchy of data defensibility:
+1. Proprietary (you created it)
+2. Product-derived (from your users)
+3. User-generated (your community)
+4. Licensed (exclusive access)
+5. Public (anyone can use—weakest)
+
+### 3. Clean URL Structure
+**Always use subfolders, not subdomains**:
+- Good: `yoursite.com/templates/resume/`
+- Bad: `templates.yoursite.com/resume/`
+
+### 4. Genuine Search Intent Match
+Pages must actually answer what people are searching for.
+
+### 5. Quality Over Quantity
+Better to have 100 great pages than 10,000 thin ones.
+
+### 6. Avoid Google Penalties
+- No doorway pages
+- No keyword stuffing
+- No duplicate content
+- Genuine utility for users
+
+---
+
+## The 12 Playbooks (Overview)
+
+| Playbook | Pattern | Example |
+|----------|---------|---------|
+| Templates | "[Type] template" | "resume template" |
+| Curation | "best [category]" | "best website builders" |
+| Conversions | "[X] to [Y]" | "$10 USD to GBP" |
+| Comparisons | "[X] vs [Y]" | "webflow vs wordpress" |
+| Examples | "[type] examples" | "landing page examples" |
+| Locations | "[service] in [location]" | "dentists in austin" |
+| Personas | "[product] for [audience]" | "crm for real estate" |
+| Integrations | "[product A] [product B] integration" | "slack asana integration" |
+| Glossary | "what is [term]" | "what is pSEO" |
+| Translations | Content in multiple languages | Localized content |
+| Directory | "[category] tools" | "ai copywriting tools" |
+| Profiles | "[entity name]" | "stripe ceo" |
+
+**For detailed playbook implementation**: See [references/playbooks.md](references/playbooks.md)
+
+---
+
+## Choosing Your Playbook
+
+| If you have... | Consider... |
+|----------------|-------------|
+| Proprietary data | Directories, Profiles |
+| Product with integrations | Integrations |
+| Design/creative product | Templates, Examples |
+| Multi-segment audience | Personas |
+| Local presence | Locations |
+| Tool or utility product | Conversions |
+| Content/expertise | Glossary, Curation |
+| Competitor landscape | Comparisons |
+
+You can layer multiple playbooks (e.g., "Best coworking spaces in San Diego").
+
+---
+
+## Implementation Framework
+
+### 1. Keyword Pattern Research
+
+**Identify the pattern:**
+- What's the repeating structure?
+- What are the variables?
+- How many unique combinations exist?
+
+**Validate demand:**
+- Aggregate search volume
+- Volume distribution (head vs. long tail)
+- Trend direction
+
+### 2. Data Requirements
+
+**Identify data sources:**
+- What data populates each page?
+- Is it first-party, scraped, licensed, public?
+- How is it updated?
+
+### 3. Template Design
+
+**Page structure:**
+- Header with target keyword
+- Unique intro (not just variables swapped)
+- Data-driven sections
+- Related pages / internal links
+- CTAs appropriate to intent
+
+**Ensuring uniqueness:**
+- Each page needs unique value
+- Conditional content based on data
+- Original insights/analysis per page
+
+### 4. Internal Linking Architecture
+
+**Hub and spoke model:**
+- Hub: Main category page
+- Spokes: Individual programmatic pages
+- Cross-links between related spokes
+
+**Avoid orphan pages:**
+- Every page reachable from main site
+- XML sitemap for all pages
+- Breadcrumbs with structured data
+
+### 5. Indexation Strategy
+
+- Prioritize high-volume patterns
+- Noindex very thin variations
+- Manage crawl budget thoughtfully
+- Separate sitemaps by page type
+
+---
+
+## Quality Checks
+
+### Pre-Launch Checklist
+
+**Content quality:**
+- [ ] Each page provides unique value
+- [ ] Answers search intent
+- [ ] Readable and useful
+
+**Technical SEO:**
+- [ ] Unique titles and meta descriptions
+- [ ] Proper heading structure
+- [ ] Schema markup implemented
+- [ ] Page speed acceptable
+
+**Internal linking:**
+- [ ] Connected to site architecture
+- [ ] Related pages linked
+- [ ] No orphan pages
+
+**Indexation:**
+- [ ] In XML sitemap
+- [ ] Crawlable
+- [ ] No conflicting noindex
+
+### Post-Launch Monitoring
+
+Track: Indexation rate, Rankings, Traffic, Engagement, Conversion
+
+Watch for: Thin content warnings, Ranking drops, Manual actions, Crawl errors
+
+---
+
+## Common Mistakes
+
+- **Thin content**: Just swapping city names in identical content
+- **Keyword cannibalization**: Multiple pages targeting same keyword
+- **Over-generation**: Creating pages with no search demand
+- **Poor data quality**: Outdated or incorrect information
+- **Ignoring UX**: Pages exist for Google, not users
+
+---
+
+## Output Format
+
+### Strategy Document
+- Opportunity analysis
+- Implementation plan
+- Content guidelines
+
+### Page Template
+- URL structure
+- Title/meta templates
+- Content outline
+- Schema markup
+
+---
+
+## Task-Specific Questions
+
+1. What keyword patterns are you targeting?
+2. What data do you have (or can acquire)?
+3. How many pages are you planning?
+4. What does your site authority look like?
+5. Who currently ranks for these terms?
+6. What's your technical stack?
+
+---
+
+## Related Skills
+
+- **seo-audit**: For auditing programmatic pages after launch
+- **schema-markup**: For adding structured data
+- **competitor-alternatives**: For comparison page frameworks

package/plugin/skills/programmatic-seo/references/playbooks.md

@@ -0,0 +1,293 @@
+# The 12 Programmatic SEO Playbooks
+
+Beyond mixing and matching data point permutations, these are the proven playbooks for programmatic SEO.
+
+## 1. Templates
+
+**Pattern**: "[Type] template" or "free [type] template"
+**Example searches**: "resume template", "invoice template", "pitch deck template"
+
+**What it is**: Downloadable or interactive templates users can use directly.
+
+**Why it works**:
+- High intent—people need it now
+- Shareable/linkable assets
+- Natural for product-led companies
+
+**Value requirements**:
+- Actually usable templates (not just previews)
+- Multiple variations per type
+- Quality comparable to paid options
+- Easy download/use flow
+
+**URL structure**: `/templates/[type]/` or `/templates/[category]/[type]/`
+
+---
+
+## 2. Curation
+
+**Pattern**: "best [category]" or "top [number] [things]"
+**Example searches**: "best website builders", "top 10 crm software", "best free design tools"
+
+**What it is**: Curated lists ranking or recommending options in a category.
+
+**Why it works**:
+- Comparison shoppers searching for guidance
+- High commercial intent
+- Evergreen with updates
+
+**Value requirements**:
+- Genuine evaluation criteria
+- Real testing or expertise
+- Regular updates (date visible)
+- Not just affiliate-driven rankings
+
+**URL structure**: `/best/[category]/` or `/[category]/best/`
+
+---
+
+## 3. Conversions
+
+**Pattern**: "[X] to [Y]" or "[amount] [unit] in [unit]"
+**Example searches**: "$10 USD to GBP", "100 kg to lbs", "pdf to word"
+
+**What it is**: Tools or pages that convert between formats, units, or currencies.
+
+**Why it works**:
+- Instant utility
+- Extremely high search volume
+- Repeat usage potential
+
+**Value requirements**:
+- Accurate, real-time data
+- Fast, functional tool
+- Related conversions suggested
+- Mobile-friendly interface
+
+**URL structure**: `/convert/[from]-to-[to]/` or `/[from]-to-[to]-converter/`
+
+---
+
+## 4. Comparisons
+
+**Pattern**: "[X] vs [Y]" or "[X] alternative"
+**Example searches**: "webflow vs wordpress", "notion vs coda", "figma alternatives"
+
+**What it is**: Head-to-head comparisons between products, tools, or options.
+
+**Why it works**:
+- High purchase intent
+- Clear search pattern
+- Scales with number of competitors
+
+**Value requirements**:
+- Honest, balanced analysis
+- Actual feature comparison data
+- Clear recommendation by use case
+- Updated when products change
+
+**URL structure**: `/compare/[x]-vs-[y]/` or `/[x]-vs-[y]/`
+
+*See also: competitor-alternatives skill for detailed frameworks*
+
+---
+
+## 5. Examples
+
+**Pattern**: "[type] examples" or "[category] inspiration"
+**Example searches**: "saas landing page examples", "email subject line examples", "portfolio website examples"
+
+**What it is**: Galleries or collections of real-world examples for inspiration.
+
+**Why it works**:
+- Research phase traffic
+- Highly shareable
+- Natural for design/creative tools
+
+**Value requirements**:
+- Real, high-quality examples
+- Screenshots or embeds
+- Categorization/filtering
+- Analysis of why they work
+
+**URL structure**: `/examples/[type]/` or `/[type]-examples/`
+
+---
+
+## 6. Locations
+
+**Pattern**: "[service/thing] in [location]"
+**Example searches**: "coworking spaces in san diego", "dentists in austin", "best restaurants in brooklyn"
+
+**What it is**: Location-specific pages for services, businesses, or information.
+
+**Why it works**:
+- Local intent is massive
+- Scales with geography
+- Natural for marketplaces/directories
+
+**Value requirements**:
+- Actual local data (not just city name swapped)
+- Local providers/options listed
+- Location-specific insights (pricing, regulations)
+- Map integration helpful
+
+**URL structure**: `/[service]/[city]/` or `/locations/[city]/[service]/`
+
+---
+
+## 7. Personas
+
+**Pattern**: "[product] for [audience]" or "[solution] for [role/industry]"
+**Example searches**: "payroll software for agencies", "crm for real estate", "project management for freelancers"
+
+**What it is**: Tailored landing pages addressing specific audience segments.
+
+**Why it works**:
+- Speaks directly to searcher's context
+- Higher conversion than generic pages
+- Scales with personas
+
+**Value requirements**:
+- Genuine persona-specific content
+- Relevant features highlighted
+- Testimonials from that segment
+- Use cases specific to audience
+
+**URL structure**: `/for/[persona]/` or `/solutions/[industry]/`
+
+---
+
+## 8. Integrations
+
+**Pattern**: "[your product] [other product] integration" or "[product] + [product]"
+**Example searches**: "slack asana integration", "zapier airtable", "hubspot salesforce sync"
+
+**What it is**: Pages explaining how your product works with other tools.
+
+**Why it works**:
+- Captures users of other products
+- High intent (they want the solution)
+- Scales with integration ecosystem
+
+**Value requirements**:
+- Real integration details
+- Setup instructions
+- Use cases for the combination
+- Working integration (not vaporware)
+
+**URL structure**: `/integrations/[product]/` or `/connect/[product]/`
+
+---
+
+## 9. Glossary
+
+**Pattern**: "what is [term]" or "[term] definition" or "[term] meaning"
+**Example searches**: "what is pSEO", "api definition", "what does crm stand for"
+
+**What it is**: Educational definitions of industry terms and concepts.
+
+**Why it works**:
+- Top-of-funnel awareness
+- Establishes expertise
+- Natural internal linking opportunities
+
+**Value requirements**:
+- Clear, accurate definitions
+- Examples and context
+- Related terms linked
+- More depth than a dictionary
+
+**URL structure**: `/glossary/[term]/` or `/learn/[term]/`
+
+---
+
+## 10. Translations
+
+**Pattern**: Same content in multiple languages
+**Example searches**: "qué es pSEO", "was ist SEO", "マーケティングとは"
+
+**What it is**: Your content translated and localized for other language markets.
+
+**Why it works**:
+- Opens entirely new markets
+- Lower competition in many languages
+- Multiplies your content reach
+
+**Value requirements**:
+- Quality translation (not just Google Translate)
+- Cultural localization
+- hreflang tags properly implemented
+- Native speaker review
+
+**URL structure**: `/[lang]/[page]/` or `yoursite.com/es/`, `/de/`, etc.
+
+---
+
+## 11. Directory
+
+**Pattern**: "[category] tools" or "[type] software" or "[category] companies"
+**Example searches**: "ai copywriting tools", "email marketing software", "crm companies"
+
+**What it is**: Comprehensive directories listing options in a category.
+
+**Why it works**:
+- Research phase capture
+- Link building magnet
+- Natural for aggregators/reviewers
+
+**Value requirements**:
+- Comprehensive coverage
+- Useful filtering/sorting
+- Details per listing (not just names)
+- Regular updates
+
+**URL structure**: `/directory/[category]/` or `/[category]-directory/`
+
+---
+
+## 12. Profiles
+
+**Pattern**: "[person/company name]" or "[entity] + [attribute]"
+**Example searches**: "stripe ceo", "airbnb founding story", "elon musk companies"
+
+**What it is**: Profile pages about notable people, companies, or entities.
+
+**Why it works**:
+- Informational intent traffic
+- Builds topical authority
+- Natural for B2B, news, research
+
+**Value requirements**:
+- Accurate, sourced information
+- Regularly updated
+- Unique insights or aggregation
+- Not just Wikipedia rehash
+
+**URL structure**: `/people/[name]/` or `/companies/[name]/`
+
+---
+
+## Choosing Your Playbook
+
+### Match to Your Assets
+
+| If you have... | Consider... |
+|----------------|-------------|
+| Proprietary data | Stats, Directories, Profiles |
+| Product with integrations | Integrations |
+| Design/creative product | Templates, Examples |
+| Multi-segment audience | Personas |
+| Local presence | Locations |
+| Tool or utility product | Conversions |
+| Content/expertise | Glossary, Curation |
+| International potential | Translations |
+| Competitor landscape | Comparisons |
+
+### Combine Playbooks
+
+You can layer multiple playbooks:
+- **Locations + Personas**: "Marketing agencies for startups in Austin"
+- **Curation + Locations**: "Best coworking spaces in San Diego"
+- **Integrations + Personas**: "Slack for sales teams"
+- **Glossary + Translations**: Multi-language educational content

package/plugin/skills/seo-qa/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: seo-qa
+version: 1.0.0
+description: Final SEO quality assurance pass on a built site. Scans every page for duplicate H1s/titles/meta descriptions, missing meta tags, missing schema markup, broken internal links, and generates sitemap.xml. Run this BEFORE handing the site over. Pass/fail report with specific URLs to fix.
+---
+
+# SEO QA Skill
+
+The safety net that catches what bulk generation misses. Run this AFTER Stage 5 (bulk page generation) and BEFORE handing the site to the client.
+
+## When to use this
+
+- After `programmatic-seo` + `wordpress-pro` have deployed all pages
+- Before closing the project / handing to the client
+- Anytime the user says "audit my site" or "is the SEO right?"
+
+## What this skill checks
+
+### 🔴 Critical — site won't rank without these
+
+1. **Duplicate H1s** — every page must have a unique H1
+2. **Duplicate meta titles** — every `<title>` must be unique
+3. **Duplicate meta descriptions** — every meta description must be unique (or pulled from page-specific data)
+4. **Missing H1** — every page must have exactly ONE H1
+5. **Missing meta title** — required on every page
+6. **Missing meta description** — required on every page
+7. **Title length** — 50-60 chars (warns under 30 or over 70)
+8. **Meta description length** — 140-160 chars (warns under 100 or over 175)
+
+### 🟡 Important — affects rankings
+
+9. **Schema markup present** — at minimum, LocalBusiness on homepage + Service schema on service pages
+10. **Canonical tags** — every page should self-canonical (or explicitly canonical to a parent if duplicate)
+11. **Internal link health** — no broken internal links, every page linked from at least one other page
+12. **Image alt text** — every image must have descriptive alt
+13. **Heading hierarchy** — H1 → H2 → H3 (no skipping levels)
+
+### 🟢 Nice-to-have
+
+14. **Open Graph tags** — `og:title`, `og:description`, `og:image` on every page
+15. **Twitter Card tags** — `twitter:card`, `twitter:title`, etc.
+16. **Robots meta** — explicit `index,follow` (or noindex when intended)
+17. **Sitemap.xml** — generated and submitted to Google Search Console
+
+## How to run
+
+### Step 1: Pull the page list
+Use the WP REST API to get all published pages and posts:
+```
+GET /wp-json/wp/v2/pages?per_page=100&status=publish
+GET /wp-json/wp/v2/posts?per_page=100&status=publish
+```
+
+### Step 2: Fetch each page's HTML
+For each URL, fetch the rendered HTML. Parse:
+- `<title>`
+- `<meta name="description">`
+- `<h1>`, `<h2>`, `<h3>` tags
+- `<link rel="canonical">`
+- `<script type="application/ld+json">` (schema)
+- `<a href="">` for internal links
+- `<img alt="">`
+- Open Graph + Twitter meta
+
+### Step 3: Run the checks
+Build a report with:
+- Per-page checklist (pass/fail per check)
+- Site-wide duplicate scans (titles, H1s, descriptions)
+- Top 10 pages with most issues
+- Critical issues count (blockers)
+- Important issues count (rankings impact)
+
+### Step 4: Generate fixes
+For each issue found, generate the fix:
+- Duplicate H1 → suggest unique H1 based on page topic
+- Missing meta description → generate one from first 155 chars of page content
+- Missing schema → generate LocalBusiness/Service JSON-LD
+- Missing alt text → generate descriptive alt from image filename + context
+
+### Step 5: Apply fixes via WP REST API
+With user confirmation, push fixes back to WordPress:
+- `POST /wp-json/wp/v2/pages/{id}` with updated content/meta
+- Update Yoast/RankMath fields if those plugins are active
+- Update featured image alt text via `/wp-json/wp/v2/media/{id}`
+
+### Step 6: Generate sitemap.xml
+Build a clean `sitemap.xml`:
+- All published pages and posts
+- `<lastmod>` from WordPress modified date
+- `<priority>` based on page depth (homepage 1.0, service pages 0.8, blog posts 0.6)
+- `<changefreq>` based on content type
+
+Save to project workspace AND offer to upload to WP root.
+
+### Step 7: Final report
+Output `SEO-QA-REPORT.md` with:
+- ✅ Total pages scanned
+- 🔴 Critical issues (count + URLs)
+- 🟡 Important issues (count + URLs)
+- 🟢 Recommendations
+- 📊 Before/after if fixes were applied
+- 🔗 Sitemap URL
+
+## Templates
+
+See `templates/seo-qa-report-template.md` for the report format.
+See `templates/schema-localbusiness.json` and `schema-service.json` for schema templates.
+
+## Hard rules
+
+- ❌ Never close a project (Stage 6 of /sonic-build) without running SEO QA
+- ❌ Never apply fixes without showing the user what changed first
+- ✅ Always save SEO-QA-REPORT.md to project workspace
+- ✅ Always offer to submit sitemap to Google Search Console (via WP plugin or manual instruction)
+
+## Common patterns to fix
+
+### Duplicate H1 across location pages
+**Bad:** Every Tampa, Brandon, Plant City page has `<h1>HVAC Services</h1>`
+**Fix:** `<h1>HVAC Services in {City}, FL</h1>` (rebuild from data)
+
+### Generic meta descriptions
+**Bad:** "We are the best HVAC company in Florida" (on 50 pages)
+**Fix:** Pull first sentence of each page's intro that mentions the city + service
+
+### Missing schema on service pages
+**Bad:** Plain HTML with no `<script type="application/ld+json">`
+**Fix:** Generate Service schema with `serviceType`, `provider`, `areaServed`, `description`
+
+### Image alt text reading "image"
+**Bad:** `<img src="hvac-tampa.jpg" alt="image">`
+**Fix:** `<img src="hvac-tampa.jpg" alt="HVAC technician installing AC unit in Tampa home">`

package/plugin/skills/seo-qa/templates/schema-localbusiness.json

@@ -0,0 +1,49 @@
+{
+  "@context": "https://schema.org",
+  "@type": "LocalBusiness",
+  "name": "{{BUSINESS_NAME}}",
+  "description": "{{SHORT_DESCRIPTION}}",
+  "url": "{{HOMEPAGE_URL}}",
+  "telephone": "{{PHONE}}",
+  "email": "{{EMAIL}}",
+  "priceRange": "{{PRICE_RANGE_DOLLAR_SIGNS}}",
+  "image": "{{LOGO_OR_HERO_URL}}",
+  "address": {
+    "@type": "PostalAddress",
+    "streetAddress": "{{STREET}}",
+    "addressLocality": "{{CITY}}",
+    "addressRegion": "{{STATE}}",
+    "postalCode": "{{ZIP}}",
+    "addressCountry": "US"
+  },
+  "geo": {
+    "@type": "GeoCoordinates",
+    "latitude": "{{LATITUDE}}",
+    "longitude": "{{LONGITUDE}}"
+  },
+  "openingHoursSpecification": [
+    {
+      "@type": "OpeningHoursSpecification",
+      "dayOfWeek": ["Monday","Tuesday","Wednesday","Thursday","Friday"],
+      "opens": "08:00",
+      "closes": "18:00"
+    }
+  ],
+  "areaServed": [
+    {
+      "@type": "City",
+      "name": "{{PRIMARY_CITY}}"
+    }
+  ],
+  "sameAs": [
+    "{{FACEBOOK_URL}}",
+    "{{INSTAGRAM_URL}}",
+    "{{LINKEDIN_URL}}",
+    "{{GOOGLE_BUSINESS_PROFILE_URL}}"
+  ],
+  "aggregateRating": {
+    "@type": "AggregateRating",
+    "ratingValue": "{{AVERAGE_RATING}}",
+    "reviewCount": "{{REVIEW_COUNT}}"
+  }
+}