npm - @lebtiga/sonic-agent - Versions diffs - 1.0.0 - Mend

@lebtiga/sonic-agent 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (62) hide show

package/plugin/skills/accessibility-qa/SKILL.md ADDED Viewed

@@ -0,0 +1,160 @@
+---
+name: accessibility-qa
+version: 1.0.0
+description: Audit a WordPress site against WCAG 2.1 AA standards (the legal compliance bar for ADA accessibility). Catches contrast issues, missing alt text, missing form labels, keyboard traps, missing ARIA, heading hierarchy, and other accessibility violations. Generates audit report and applies fixes via WP REST API. CRITICAL for healthcare, legal, government, and education clients — these industries get sued for non-compliance.
+---
+# Accessibility QA Skill
+WCAG 2.1 AA compliance audit and remediation. Run alongside `seo-qa` before closing any project — but ESPECIALLY for healthcare, legal, education, and government clients where ADA lawsuits are common.
+## When to use this
+- After Stage 5 (bulk page generation) and before project handoff
+- Anytime the user asks "is this ADA compliant?" or "WCAG compliant?"
+- For ALL healthcare, legal, financial, education, or government client work
+- Before delivering any site to a client whose business has accessibility risk exposure
+## What WCAG 2.1 AA covers
+The legal bar most US businesses are measured against. Failure = lawsuit risk.
+### 🔴 Critical (level A — must pass)
+1. **Image alt text** — every `<img>` must have descriptive `alt` (or `alt=""` if decorative)
+2. **Heading hierarchy** — exactly one `<h1>` per page; never skip levels (h2 → h4 ❌)
+3. **Form labels** — every `<input>`, `<select>`, `<textarea>` must have an associated `<label>` or `aria-label`
+4. **Language attribute** — `<html lang="en">` (or appropriate language)
+5. **Keyboard accessible** — all interactive elements (buttons, links, forms) must work without a mouse
+6. **No keyboard traps** — user can tab through entire page and back out
+7. **Skip-to-content link** — first focusable element on every page
+8. **Focus visible** — `:focus` styles on all interactive elements
+9. **Page titles** — every page must have a unique, descriptive `<title>`
+10. **Link purpose** — `<a>` tags must describe destination ("Click here" ❌)
+### 🟡 Important (level AA — required for most compliance)
+11. **Color contrast** — 4.5:1 for body text, 3:1 for large text (18pt+ or 14pt bold+)
+12. **Resizable text** — page must work at 200% zoom without breaking
+13. **Multiple navigation methods** — at least one of: nav menu, search, sitemap
+14. **Heading describes content** — no generic "Section 1" headings
+15. **Focus order** — tab order must follow visual order
+16. **Form errors** — clearly identified, suggested fixes provided
+17. **Required fields** — marked as required, not just colored
+18. **Captions on video** — if video exists
+19. **Audio descriptions** — if video has visual info
+### 🟢 Nice-to-have (level AAA — gold standard)
+20. **Sign language** — for video content
+21. **Extended audio descriptions** — for complex video
+22. **Reading level** — content at 9th grade level or below where possible
+23. **Pronunciation** — for ambiguous terms
+24. **Context-sensitive help** — for forms
+## How to run the audit
+### Step 1: Pull all pages from WP
+```
+GET /wp-json/wp/v2/pages?per_page=100
+GET /wp-json/wp/v2/posts?per_page=100
+```
+### Step 2: Fetch each page's rendered HTML
+For each page, parse:
+- `<img>` tags → check `alt` attribute
+- `<h1>` through `<h6>` → check hierarchy and uniqueness
+- `<form>`, `<input>`, `<label>` → check association
+- `<a>` tags → check link text quality
+- `<html>` → check `lang` attribute
+- `<title>` → check uniqueness and descriptiveness
+- Inline styles + computed CSS → check color contrast (foreground vs background)
+- ARIA attributes on interactive elements
+### Step 3: Color contrast check
+For every text element:
+- Extract foreground color
+- Extract background color (compute through layers)
+- Calculate contrast ratio: `(L1 + 0.05) / (L2 + 0.05)`
+  - Where L1 = lighter color luminance, L2 = darker
+- Body text needs ≥ 4.5:1
+- Large text (18pt+ or 14pt bold) needs ≥ 3:1
+- Flag any failures
+### Step 4: Keyboard accessibility check
+Test each interactive element:
+- Has `tabindex` (0 or positive)
+- Has visible focus styles
+- Doesn't trap focus
+### Step 5: Generate ACCESSIBILITY-QA-REPORT.md
+- Per-page checklist (pass/fail per check)
+- Site-wide issues (consistent missing alt patterns, etc.)
+- Critical violations count (block ship)
+- Important violations count
+- Specific URLs + element selectors needing fixes
+### Step 6: Apply fixes
+With user confirmation:
+- Generate alt text for missing images (use image filename + page context)
+- Fix heading hierarchy (rename misordered headings)
+- Add `aria-label` to unlabeled form inputs
+- Add skip-to-content link to theme header
+- Fix low-contrast colors (suggest darker/lighter alternatives that match brand)
+- Update theme CSS with `:focus` styles where missing
+### Step 7: Re-scan
+After fixes, run audit again. Confirm:
+- ✅ All Level A criteria pass
+- ✅ All Level AA criteria pass
+- ✅ Document remaining issues (rare cases that need manual review)
+## Output
+Save `ACCESSIBILITY-QA-REPORT.md` at project root.
+For high-stakes clients (healthcare, legal, govt), also generate:
+- `WCAG-COMPLIANCE-STATEMENT.md` — formal statement of conformance, dated, ready to add to the client's site footer
+- `ACCESSIBILITY-FIXES-LOG.md` — what was changed and why (audit trail)
+## Templates
+See:
+- `templates/accessibility-qa-report-template.md`
+- `templates/wcag-compliance-statement.md`
+## Hard rules
+- ❌ Never deliver to healthcare/legal/govt/education clients without running this skill
+- ❌ Never claim "WCAG 2.1 AA compliant" unless this skill has actually been run and passed
+- ✅ Always offer compliance-grade clients a formal Compliance Statement document
+- ✅ Always include accessibility QA in Stage 6 of the build flow
+## Common patterns to fix
+### Generic "click here" links
+**Bad:** `<a href="/services">Click here</a>`
+**Fix:** `<a href="/services">View our HVAC services</a>`
+### Missing form labels
+**Bad:** `<input type="email" placeholder="Email">`
+**Fix:** `<label for="email">Email</label><input id="email" type="email">`
+### Low-contrast text on hero
+**Bad:** white text on light blue background (3.2:1 — fails)
+**Fix:** darker text or darker background (4.5:1+)
+### Missing skip-to-content
+**Bad:** keyboard user must tab through 30 nav items to reach content
+**Fix:** Add as first focusable element:
+```html
+<a class="skip-to-content" href="#main">Skip to main content</a>
+```
+### Heading skipped levels
+**Bad:** `<h1>` → `<h3>` (skipped h2)
+**Fix:** `<h1>` → `<h2>` → `<h3>` proper sequence
+## Why this matters for SALES
+Healthcare/legal/govt clients have HIGH ADA lawsuit exposure. If an agency promises "WCAG compliant" sites without actually delivering compliance, they're creating legal liability for themselves AND their clients. This skill is what lets you confidently sell to compliance-sensitive industries — and **price accordingly** ($5K-$10K vs $1K-$3K for low-stakes industries).

package/plugin/skills/accessibility-qa/templates/accessibility-qa-report-template.md ADDED Viewed

@@ -0,0 +1,123 @@
+# ACCESSIBILITY QA REPORT — [Site Name]
+**Audit Date:** [Date]
+**Pages scanned:** [N]
+**Compliance Standard:** WCAG 2.1 Level AA
+**Overall Status:** [✅ COMPLIANT / ⚠️ ISSUES FOUND / 🔴 NON-COMPLIANT]
+## 📊 Summary
+| Severity | Count | Status |
+|----------|-------|--------|
+| 🔴 Level A failures | [N] | [Block ship] |
+| 🟡 Level AA failures | [N] | [Fix recommended] |
+| 🟢 Level AAA suggestions | [N] | [Optional] |
+## 🔴 Level A Failures (BLOCKERS)
+### Missing alt text
+[N] images have no alt attribute or empty alt for non-decorative content.
+**Affected pages:**
+- [URL] — `<img src="hero.jpg">` (line 42)
+- [URL] — `<img src="team-photo.jpg">` (line 18)
+**Fix:** Add descriptive alt text via WP REST API.
+---
+### Heading hierarchy violations
+[N] pages skip heading levels.
+**Examples:**
+- [URL] — `<h1>` jumps to `<h3>` (no h2)
+- [URL] — Multiple `<h1>` tags on one page
+**Fix:** Rebuild headings in proper sequence (h1 → h2 → h3).
+---
+### Form labels missing
+[N] form inputs lack proper labels.
+**Affected:**
+- [URL] — Contact form has unlabeled email field
+- [URL] — Newsletter signup missing label
+**Fix:** Add `<label for="...">` or `aria-label` to each input.
+---
+## 🟡 Level AA Failures
+### Color contrast violations
+[N] text elements fail 4.5:1 (body) or 3:1 (large text) ratio.
+**Examples:**
+- [URL] — Body text `#7A7A7A` on `#FFFFFF` = 4.07:1 (needs 4.5:1)
+- [URL] — Button text `#FFFFFF` on `#A8C9DC` = 2.4:1 (needs 4.5:1)
+**Fix:** Adjust colors to meet contrast minimums.
+---
+### Missing focus styles
+Theme CSS lacks `:focus` indicators on [N] interactive element types.
+**Fix:** Add visible focus outlines to theme CSS:
+```css
+a:focus, button:focus, input:focus { outline: 3px solid #0066CC; outline-offset: 2px; }
+```
+---
+### Missing skip-to-content link
+No skip link found in theme header.
+**Fix:** Add as first focusable element of every page:
+```html
+<a class="skip-to-content" href="#main">Skip to main content</a>
+```
+---
+## ✅ Passing Checks
+- [x] Language attribute present (`<html lang="en">`)
+- [x] Page titles unique and descriptive
+- [x] Link purpose clear (no "click here" links found)
+- [x] Tab order follows visual order
+- [x] No keyboard traps detected
+## 📋 Compliance Status
+**This site:** [✅ Meets / ⚠️ Partially Meets / ❌ Does Not Meet] **WCAG 2.1 Level AA**
+If "Meets" — generate `WCAG-COMPLIANCE-STATEMENT.md` for the client's footer.
+## 🛠️ Next Steps
+1. Apply fixes for all Level A failures (REQUIRED)
+2. Apply fixes for all Level AA failures (REQUIRED for ADA compliance)
+3. Re-run audit
+4. If passing, generate compliance statement document
+5. Brief the client on ongoing accessibility maintenance
+## ⚠️ Important Disclaimer
+This automated audit catches the most common WCAG violations but is not a substitute for:
+- Manual screen reader testing (NVDA, JAWS, VoiceOver)
+- User testing with people who use assistive technology
+- Legal compliance review by an accessibility specialist
+For high-risk industries (healthcare, legal, government, education), recommend a manual audit by a certified accessibility professional after this automated pass.
+---
+*Report generated by Sonic ⚡ Accessibility QA skill*

package/plugin/skills/accessibility-qa/templates/wcag-compliance-statement.md ADDED Viewed

@@ -0,0 +1,70 @@
+# Accessibility Statement
+**Last updated:** [Date]
+## Our Commitment
+[BUSINESS NAME] is committed to ensuring digital accessibility for people with disabilities. We are continually improving the user experience for everyone and applying the relevant accessibility standards.
+## Conformance Status
+The Web Content Accessibility Guidelines (WCAG) define requirements for designers and developers to improve accessibility for people with disabilities. They define three levels of conformance: Level A, Level AA, and Level AAA.
+**[BUSINESS NAME] website is fully conformant with WCAG 2.1 level AA.**
+Fully conformant means that the content fully conforms to the accessibility standard without any exceptions.
+## Compatibility with Browsers and Assistive Technology
+This website is designed to be compatible with the following assistive technologies:
+- Recent versions of major screen readers (NVDA, JAWS, VoiceOver)
+- Voice recognition software
+- Operating system screen magnifiers
+- Operating system keyboard shortcuts
+- Browser keyboard navigation
+This website is compatible with recent versions of:
+- Chrome / Edge
+- Firefox
+- Safari
+## Technical Specifications
+Accessibility of [BUSINESS NAME] relies on the following technologies to work with the particular combination of web browser and any assistive technologies or plugins installed on your computer:
+- HTML
+- WAI-ARIA
+- CSS
+- JavaScript
+These technologies are relied upon for conformance with the accessibility standards used.
+## Assessment Approach
+[BUSINESS NAME] assessed the accessibility of this website by the following approaches:
+- ✅ Automated scanning against WCAG 2.1 AA criteria
+- ✅ Manual review of key pages and components
+- ✅ Color contrast analysis on all interactive elements
+- ✅ Keyboard navigation testing
+- ✅ Screen reader compatibility checks
+## Feedback
+We welcome your feedback on the accessibility of [BUSINESS NAME]. Please let us know if you encounter accessibility barriers:
+- **Email:** [contact email]
+- **Phone:** [contact phone]
+- **Postal Address:** [business address]
+We try to respond to feedback within 5 business days.
+## Date
+This statement was created on [DATE] using the [BUSINESS NAME] accessibility assessment process.
+---
+*Accessibility audit performed using Sonic Agent Accessibility QA, [DATE]. For complex compliance situations, [BUSINESS NAME] also engages [or recommends engaging] certified accessibility professionals for manual review.*

package/plugin/skills/aka-wireframe-wp/SKILL.md ADDED Viewed

@@ -0,0 +1,149 @@
+---
+name: aka-wireframe-wp
+description: Build complete WordPress authority sites (200+ pages) using the Authority-Knowledge-Answer (AKA) content framework. Use when the user wants to create large-scale WordPress sites with topical clustering, programmatic content generation, SEO optimization, or mentions "AKA framework", "authority site", "topical authority", "content hub", "pillar content", "200 page site", or "wireframe WordPress".
+---
+# AKA Wireframe WordPress
+Build complete WordPress authority sites automatically using the Authority-Knowledge-Answer (AKA) content framework. Generate 200+ page sites with proper topical clustering, internal linking, and SEO optimization.
+**Generate in 1-2 hours what typically takes 4-6 weeks manually.**
+## The AKA Framework
+```
+Authority Pages (5-7 hubs)
+├── 4,000 words, comprehensive guides
+├── Head keywords, hub for all related content
+│
+├── Knowledge Pages (12-15 per hub)
+│   ├── 2,000 words, deep-dive content
+│   ├── Mid-tail keywords
+│   └── Specific topics and solutions
+│
+└── Answer Pages (20-30 per hub)
+    ├── 1,000 words, FAQ format
+    ├── Long-tail questions
+    └── Featured snippet optimized
+```
+## Output Per Hub (~20 minutes)
+- 1 Authority page (4,000 words)
+- 15 Knowledge pages (30,000 words)
+- 25 Answer pages (25,000 words)
+- 300+ internal links
+- Complete SEO optimization
+## Full Site (5 hubs, 1-2 hours)
+- 5 Authority hubs
+- 75 Knowledge pages
+- 125 Answer pages
+- **205 total pages**
+- 1,500+ internal links
+## Quick Start Workflow
+### Step 1: Setup (5 min)
+Collect 15 business variables:
+1. Business name
+2. Industry
+3. Location (City, State)
+4. Service radius
+5. Primary service (→ first Authority Hub)
+6. Secondary services (→ more Authority Hubs)
+7. Target audience
+8. Top 3 pain points
+9. Brand voice
+10. Unique value proposition
+11. Phone number
+12. Email
+13. Business address
+14. Hours of operation
+15. Trust signals (years, clients, awards)
+Save to: `.factory/config/aka-wireframe/business-config.json`
+### Step 2: Generate Strategy (2 min)
+Create complete AKA wireframe:
+- 5-7 Authority Hub topics
+- 12-15 Knowledge pages per hub
+- 20-30 Answer questions per hub
+- Complete URL structure
+- Keyword mapping
+Save to: `.factory/config/aka-wireframe/aka-strategy-output.json`
+### Step 3: Generate Content (8 min/hub)
+Create all content with variable injection:
+- Authority page (4,000 words)
+- Knowledge pages (15 × 2,000 words)
+- Answer pages (25 × 1,000 words)
+- Add `[LINK:slug|anchor]` placeholders
+Save to: `generated-content/hub-N/`
+### Step 4: Process Internal Links (2 min/hub)
+- Convert `[LINK:...]` placeholders to URLs
+- Add AI contextual links
+- Validate AKA structure
+- No broken links, no orphans
+### Step 5: Deploy to WordPress (3 min/hub)
+- Create pages with hierarchy
+- Set parent-child relationships
+- Add SEO metadata
+- Insert schema markup
+- Create navigation menus
+## Reference Files
+For detailed implementation, load these references as needed:
+| Reference | When to Load |
+|-----------|--------------|
+| `references/orchestrator.md` | Coordinating full workflow |
+| `references/strategy-planner.md` | Generating AKA strategy |
+| `references/content-generator.md` | Creating page content |
+| `references/internal-linker.md` | Processing links |
+| `references/wordpress-deployer.md` | Deploying to WordPress |
+| `references/seo-optimizer.md` | SEO auditing |
+## Industry Applications
+Works for any vertical:
+- **Law Firms**: Personal injury, family law, criminal defense
+- **Financial Services**: Title loans, mortgages, insurance
+- **Home Services**: HVAC, plumbing, roofing, landscaping
+- **Healthcare**: Medical practices, dental, chiropractic
+- **Professional Services**: Consulting, real estate, agencies
+## Content Structure Example
+**HVAC Company - Hub 1: AC Repair**
+```
+ac-repair-services/ (Authority - 4,000 words)
+├── ac-not-cooling/ (Knowledge)
+├── ac-making-noise/ (Knowledge)
+├── ac-refrigerant-leak/ (Knowledge)
+├── ...15 Knowledge pages
+├── how-much-ac-repair-cost/ (Answer)
+├── why-ac-blowing-warm-air/ (Answer)
+├── when-replace-vs-repair-ac/ (Answer)
+└── ...25 Answer pages
+```
+## Key Principles
+1. **Variable Injection**: All content uses `{{BUSINESS_NAME}}`, `{{LOCATION}}`, etc.
+2. **Two-Phase Linking**: Placeholders first, then conversion + AI contextual links
+3. **SEO-First**: Every page has title, meta, schema, keywords mapped
+4. **Hierarchy**: Proper parent-child relationships for Google
+5. **No Orphans**: Every page linked from multiple sources
+## WordPress Requirements
+- WordPress REST API enabled
+- Application passwords or admin credentials
+- Permalinks set to `/%postname%/`
+- AKA Framework Theme (included in assets)

package/plugin/skills/aka-wireframe-wp/assets/aka-framework-theme/README.md ADDED Viewed

@@ -0,0 +1,190 @@
+# AKA Framework WordPress Theme
+Simple, clean WordPress theme optimized for the **AKA (Authority-Knowledge-Answer)** framework.
+## Features
+### Three Custom Page Templates
+- **Authority Hub** - Main hub pages with child navigation
+- **Knowledge Page** - Deep-dive content with related topics
+- **Answer Page** - FAQ format optimized for featured snippets
+### Built-in Components
+- ✅ Breadcrumbs navigation
+- ✅ Related topics/questions
+- ✅ Quick navigation for hubs
+- ✅ CTA boxes
+- ✅ Mobile-responsive design
+- ✅ SEO-optimized structure
+- ✅ Clean, minimal design
+### Easy Customization
+- CSS variables for colors/spacing
+- WordPress Customizer support
+- Custom logo support
+- Multiple navigation menus
+- Widget-ready footer
+## Installation
+### Option 1: Upload via WordPress Admin
+1. Go to **Appearance → Themes → Add New**
+2. Click **Upload Theme**
+3. Choose the `aka-framework-theme.zip` file
+4. Click **Install Now**
+5. Activate the theme
+### Option 2: Manual Installation
+1. Upload the `aka-framework-theme` folder to `/wp-content/themes/`
+2. Go to **Appearance → Themes**
+3. Activate **AKA Framework Theme**
+## Usage
+### Creating an Authority Hub
+1. Create a new page in WordPress
+2. Assign **Authority Hub** template
+3. This becomes your main hub page
+4. All child pages will appear in the quick navigation
+### Creating Knowledge Pages
+1. Create a new page
+2. Set parent to your Authority Hub
+3. Assign **Knowledge Page** template
+4. Related sibling knowledge pages will auto-link
+### Creating Answer Pages
+1. Create a new page
+2. Set parent to your Authority Hub
+3. Assign **Answer Page** template
+4. Use the excerpt for the "Quick Answer" box (featured snippet optimization)
+5. Related questions will auto-link
+## Page Structure Example
+```
+Authority Hub: Atlanta Car Accident Lawyer
+├── Knowledge: Types of Car Accident Claims
+├── Knowledge: Georgia Car Accident Laws
+├── Knowledge: Insurance Claims Process
+├── Answer: How long do I have to file a claim?
+├── Answer: What is my case worth?
+└── Answer: Do I need a lawyer?
+```
+## Customization
+### Change Colors
+**Method 1: WordPress Customizer**
+- Go to **Appearance → Customize → Colors**
+- Change Primary Color
+**Method 2: Edit CSS Variables** (in `style.css`)
+```css
+:root {
+  --primary-color: #2563eb;    /* Your brand color */
+  --secondary-color: #1e40af;  /* Darker shade */
+  --accent-color: #f59e0b;     /* Call-to-action color */
+}
+```
+### Add Phone Number
+1. Go to **Appearance → Customize**
+2. Find "Phone Number" setting
+3. Enter your phone number
+4. It will appear in the footer
+### Navigation Menus
+Create two menus:
+- **Primary Menu** - Main navigation (header)
+- **Footer Menu** - Footer links
+Go to **Appearance → Menus** to create them.
+## File Structure
+```
+aka-framework-theme/
+├── style.css                 # Main stylesheet with all CSS
+├── functions.php             # Theme functions and helpers
+├── header.php                # Site header
+├── footer.php                # Site footer
+├── index.php                 # Fallback template
+├── page-authority-hub.php    # Authority Hub template
+├── page-knowledge.php        # Knowledge Page template
+├── page-answer.php           # Answer Page template
+└── README.md                 # This file
+```
+## Theme Functions
+The theme includes helper functions you can use in templates:
+```php
+// Get hub navigation (child pages)
+echo aka_get_hub_navigation();
+// Get breadcrumbs
+echo aka_get_breadcrumbs();
+// Get related topics
+echo aka_get_related_topics();
+// Get related questions
+echo aka_get_related_questions();
+// Display CTA box
+echo aka_get_cta_box( 'Title', 'Description', 'Button Text', 'Button URL' );
+```
+## CSS Classes
+Utility classes available:
+```css
+.text-center, .text-left, .text-right   /* Text alignment */
+.mt-sm, .mt-md, .mt-lg                  /* Margin top */
+.mb-sm, .mb-md, .mb-lg                  /* Margin bottom */
+```
+## Browser Support
+- ✅ Chrome (latest)
+- ✅ Firefox (latest)
+- ✅ Safari (latest)
+- ✅ Edge (latest)
+- ✅ Mobile browsers (iOS Safari, Chrome Mobile)
+## Requirements
+- WordPress 5.0 or higher
+- PHP 7.4 or higher
+## License
+MIT License - Free for personal and commercial use
+## Support
+For issues or questions:
+- GitHub: https://github.com/lebtiga/aka-wireframe-wp-system
+- Documentation: See AKA-WIREFRAME-WP-COMPLETE.md
+## Changelog
+### Version 1.0.0
+- Initial release
+- Three custom page templates
+- Mobile-responsive design
+- SEO optimized structure
+- Basic customization options
+---
+Built specifically for the AKA Wireframe WordPress system.