claude-plugin-wordpress-manager 1.4.0 → 1.7.0

package/skills/wordpress-router/references/decision-tree.md

@@ -1,19 +1,23 @@
-# Router decision tree (v2 — unified development + operations)
+# Router decision tree (v4 — development + local environment + operations)
 
-This routing guide covers both WordPress **development** and **operations** workflows.
+This routing guide covers WordPress **development**, **local environment**, and **operations** workflows.
 
 ## Step 0: determine task category
 
 Before repo triage, classify the user’s intent:
 
 - **Development** (modifying code) → proceed to Step 1
+- **Local Environment** (managing local dev sites) → skip to Step 2c
 - **Operations** (managing live sites) → skip to Step 2b
 
+Keywords that indicate **local environment**:
+local site, Studio, LocalWP, Local by Flywheel, wp-env, local WordPress, start site, stop site, create local site, local development, symlink plugin, local database, switch PHP version, localhost, local preview, detect environment, WASM, SQLite local
+
 Keywords that indicate **operations**:
 deploy, push to production, audit, security check, backup, restore, migrate, move site, create post, manage content, site status, check plugins, performance check, SEO audit
 
 Keywords that indicate **development**:
-create block, block.json, theme.json, register_rest_route, plugin development, hooks, PHPStan, build, test, scaffold
+create block, block.json, theme.json, register_rest_route, plugin development, hooks, PHPStan, build, test, scaffold, i18n, translation, accessibility, a11y, headless, decoupled, WPGraphQL
 
 ## Step 1: classify repo kind (from triage — development only)
 
@@ -53,6 +57,14 @@ Priority: `gutenberg` > `wp-core` > `wp-site` > `wp-block-theme` > `wp-block-plu
   → `wpds` (WordPress Design System)
 - **Playground / disposable WP / blueprint / sandbox / test environment / version switching**
   → `wp-playground`
+- **Test / E2E / Playwright / Jest / PHPUnit / wp-env testing / coverage / visual regression**
+  → `wp-e2e-testing` skill + `wp-test-engineer` agent
+- **i18n / translation / .pot / gettext / text domain / RTL / Polylang / WPML / multilingual**
+  → `wp-i18n`
+- **Accessibility / a11y / WCAG / ARIA / screen reader / keyboard navigation / focus management**
+  → `wp-accessibility` skill + `wp-accessibility-auditor` agent
+- **Headless / decoupled / WPGraphQL / Next.js / Nuxt / Astro / Gatsby / CORS / ISR / SSG / frontend integration**
+  → `wp-headless`
 
 ## Step 2b: route by operational intent (keywords)
 
@@ -60,6 +72,8 @@ Priority: `gutenberg` > `wp-core` > `wp-site` > `wp-block-theme` > `wp-block-plu
   → `wp-deploy` skill + `wp-deployment-engineer` agent
 - **Audit / security check / vulnerability / hacked / health check**
   → `wp-audit` skill + `wp-security-auditor` agent
+- **Harden / permissions / headers / WAF / malware / compromised / incident response / security hardening**
+  → `wp-security` skill + `wp-security-hardener` agent
 - **Backup / snapshot / disaster recovery / restore**
   → `wp-backup` skill
 - **Migrate / move / transfer / clone site / change hosting**
@@ -73,6 +87,40 @@ Priority: `gutenberg` > `wp-core` > `wp-site` > `wp-block-theme` > `wp-block-plu
 - **DNS / domain / SSL / hosting configuration**
   → `wp-site-manager` agent (Hostinger MCP tools)
 
+## Step 2c: route by local environment intent (keywords)
+
+First, run detection to discover installed tools and sites:
+```bash
+node skills/wp-local-env/scripts/detect_local_env.mjs
+```
+
+Then route by intent:
+
+- **Create / new site / setup local / install WordPress locally**
+  → `wp-local-env` skill (Section 1: Site lifecycle → Create)
+- **Start site / stop site / delete site / site status**
+  → `wp-local-env` skill (Section 1: Site lifecycle)
+- **WP-CLI / plugin list / scaffold / export / local command**
+  → `wp-local-env` skill (Section 2: WP-CLI operations)
+- **Symlink / link plugin / develop locally / local dev workflow**
+  → `wp-local-env` skill (Section 3: Development workflow)
+- **Local REST API / localhost API / application password local**
+  → `wp-local-env` skill (Section 4: REST API access)
+- **Local database / SQLite / export DB / backup local / mysql local**
+  → `wp-local-env` skill (Section 5: Database operations)
+- **Switch PHP / switch WordPress version / test version / local testing**
+  → `wp-local-env` skill (Section 6: Testing and version switching)
+- **Preview / share local / ngrok / tunnel / demo site**
+  → `wp-local-env` skill (Section 7: Preview and share)
+- **MCP adapter / local MCP / WordPress MCP server**
+  → `wp-local-env` skill (Section 8: MCP integration) + `references/mcp-adapter-setup.md`
+- **Which tool / Studio vs LocalWP / which local env / recommend tool**
+  → `wp-local-env` skill (run detection, present comparison)
+
+**Overlap with Development**: If the user is developing a plugin/theme AND needs a local site to test it, route to `wp-local-env` first (symlink workflow), then to development skills for the code changes.
+
+**Overlap with Operations**: If the user mentions "deploy from local" or "push local to production", route to `wp-local-env` for export, then to `wp-deploy` for the deployment.
+
 ## Step 3: guardrails checklist (always)
 
 ### Development guardrails
@@ -80,6 +128,14 @@ Priority: `gutenberg` > `wp-core` > `wp-site` > `wp-block-theme` > `wp-block-plu
 - Prefer existing lint/test scripts if present.
 - If version constraints aren’t detectable, ask for target WP core and PHP versions.
 
+### Local environment guardrails
+- Run `detect_local_env.mjs` before assuming which tool is available.
+- For LocalWP: verify the site is started (GUI) before WP-CLI or DB operations.
+- For Studio: verify the Studio app is running before CLI operations.
+- For wp-env: verify Docker is running (`docker info`) before starting.
+- Never delete a local site without explicit user confirmation.
+- When multiple tools are detected, use the `recommended` field from detection output.
+
 ### Operations guardrails
 - Confirm target site before any operation.
 - Verify backups exist before destructive operations (deploy, migrate, restore).

package/skills/wp-accessibility/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: wp-accessibility
+description: "Use when improving WordPress accessibility: block accessibility (ARIA, keyboard navigation), theme accessibility (landmarks, skip links, color contrast), interactive component accessibility, media accessibility (alt text, captions, transcripts), and automated/manual a11y testing with WCAG 2.2 compliance."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node."
+version: 1.0.0
+source: "vinmor/wordpress-manager"
+---
+
+# WP Accessibility
+
+## When to use
+
+Use this skill for accessibility work such as:
+
+- Making custom blocks accessible (ARIA roles, keyboard navigation, screen reader support)
+- Ensuring a theme meets WCAG 2.2 AA requirements
+- Fixing accessibility audit findings (axe-core violations, Lighthouse issues)
+- Adding keyboard navigation to interactive components (modals, tabs, dropdowns, accordions)
+- Implementing ARIA patterns from the APG (ARIA Authoring Practices Guide)
+- Making media accessible (alt text, captions, transcripts, audio descriptions)
+- Preparing a theme for WordPress.org `accessibility-ready` tag
+- Setting up automated a11y testing in CI pipelines
+
+## Inputs required
+
+- Repo root and target (plugin, theme, or block).
+- Project kind: plugin, theme, block, or full site.
+- Target WCAG level: AA (default) or AAA.
+- Specific a11y issues reported (audit results, user feedback, review team comments).
+
+## Procedure
+
+### 0) Understand WordPress a11y standards
+
+WordPress core has a dedicated Accessibility Team. Key principles:
+
+1. **WordPress.org theme review** requires `accessibility-ready` themes to pass tests covering skip links, keyboard navigation, contrast, heading hierarchy, landmarks, and form labels.
+2. **Block editor** blocks must meet core a11y standards: `useBlockProps()` provides baseline ARIA attributes; interactive blocks must handle keyboard events.
+3. **WCAG 2.2** is the target standard. WordPress aims for Level AA at minimum.
+
+For automated a11y testing setup, reference the `wp-e2e-testing` skill.
+
+Run project triage:
+```bash
+node skills/wp-project-triage/scripts/detect_wp_project.mjs
+```
+
+### 1) Block accessibility
+
+Ensure custom blocks are accessible to keyboard and screen reader users.
+
+Key areas:
+- ARIA roles and properties for custom block markup
+- Keyboard interaction patterns for block controls
+- Focus management when blocks are inserted, removed, or transformed
+- Screen reader announcements via `wp.a11y.speak()`
+- Block supports: `anchor`, `ariaLabel`
+
+Read: `references/block-a11y.md`
+
+### 2) Theme accessibility
+
+Ensure the theme meets WCAG 2.2 and `accessibility-ready` requirements.
+
+Key areas:
+- Landmark roles: `<header>`, `<nav>`, `<main>`, `<footer>`, `<aside>`
+- Skip links to main content
+- Heading hierarchy (single H1, logical nesting)
+- Color contrast (4.5:1 normal text, 3:1 large text at AA)
+- Visible focus indicators (`:focus-visible`)
+- `prefers-reduced-motion` and `prefers-contrast` media queries
+- `theme.json` color palette contrast compliance
+
+Read: `references/theme-a11y.md`
+
+### 3) Interactive component accessibility
+
+Implement ARIA design patterns from the APG for interactive UI components.
+
+Key areas:
+- Modal/dialog: focus trap, Escape to close, return focus to trigger
+- Dropdown/menu: arrow key navigation, typeahead
+- Tabs: arrow keys to switch, Home/End support
+- Accordion: `aria-expanded`, Enter/Space to toggle
+- Carousel: pause on hover/focus, slide announcements
+- Live regions for dynamic content updates
+- WordPress Interactivity API + a11y: pair `data-wp-on--click` with `data-wp-on--keydown`
+
+Read: `references/interactive-a11y.md`
+
+### 4) Media accessibility
+
+Ensure all media content has appropriate text alternatives.
+
+Key areas:
+- Alt text for images (meaningful vs decorative `alt=""`)
+- Video captions (`<track kind="captions">`) and audio descriptions
+- Audio transcripts as text alternatives
+- SVG accessibility: `role="img"` + `aria-label` or `<title>`
+- WordPress media library alt text handling
+
+Read: `references/media-a11y.md`
+
+### 5) Automated a11y testing
+
+Set up automated accessibility testing to catch regressions early.
+
+Key areas:
+- axe-core integration with Playwright (`@axe-core/playwright`)
+- pa11y for quick page-level checks
+- Lighthouse accessibility audits
+- CI pipeline integration
+- Interpreting and prioritizing violations
+
+Read: `references/a11y-audit-tools.md`
+
+### 6) Manual a11y testing
+
+Automated tools catch only ~30-40% of a11y issues. Manual testing is essential.
+
+Key areas:
+- Keyboard-only navigation testing
+- Screen reader testing (NVDA, VoiceOver, TalkBack)
+- Zoom testing (200% and 400%)
+- Color contrast verification
+- Reduced motion preference testing
+- Systematic per-page testing checklist
+
+Read: `references/a11y-testing.md`
+
+## Verification
+
+- **axe-core** returns 0 violations at the target WCAG level
+- **Keyboard** works for all interactive elements: focusable, operable, visible focus
+- **Screen reader** announces correctly: landmarks, headings, form labels, updates
+- **Color contrast** passes: 4.5:1 normal text, 3:1 large text (AA)
+- **Heading hierarchy** is logical: single H1, no skipped levels
+- **Skip link** is present and functional
+- **Zoom to 400%** causes no content loss or horizontal scroll
+- **Reduced motion** is respected: animations disabled when preference set
+
+```bash
+npx pa11y http://localhost:8888
+npx lighthouse http://localhost:8888 --only-categories=accessibility --output=json
+```
+
+## Failure modes / debugging
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| "Insufficient color contrast" | Ratio below 4.5:1 | Adjust in `theme.json` or CSS |
+| "Images must have alt text" | Missing `alt` | Add via media library or `wp_get_attachment_image()` |
+| "No main landmark" | Missing `<main>` | Add `<main id="main-content">` |
+| "No level-one heading" | Missing/multiple H1 | Single `<h1>` per page |
+| Can't reach element via keyboard | Non-interactive element | Use `<button>` or `<a>` instead of `<div>` |
+| Focus trapped | Bad focus trap | Only trap in modals; release on close |
+| No announcement on update | Missing live region | `aria-live="polite"` or `wp.a11y.speak()` |
+| Wrong reading order | DOM/visual mismatch | Align DOM with visual order |
+| Focus not visible | Outline removed | Use `:focus-visible` with visible style |
+
+## Escalation
+
+- WordPress Accessibility Handbook: https://make.wordpress.org/accessibility/handbook/
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- ARIA Authoring Practices Guide: https://www.w3.org/WAI/ARIA/apg/
+- WordPress Accessibility Coding Standards: https://developer.wordpress.org/coding-standards/wordpress-coding-standards/accessibility/
+
+## Recommended Agent
+
+For automated accessibility scanning and WCAG compliance reports, use the **`wp-accessibility-auditor`** agent.

package/skills/wp-accessibility/references/a11y-audit-tools.md

@@ -0,0 +1,248 @@
+# Accessibility Audit Tools
+
+Use this file when selecting and configuring tools for accessibility testing.
+
+## Automated testing tools
+
+### axe-core (Deque)
+
+Industry standard engine. Used by Google Lighthouse, Microsoft Accessibility Insights.
+
+```bash
+# CLI testing
+npx @axe-core/cli https://localhost:8888/
+
+# With specific tags
+npx @axe-core/cli https://localhost:8888/ --tags wcag2a,wcag2aa
+
+# Save results
+npx @axe-core/cli https://localhost:8888/ --save results.json
+```
+
+Browser extensions:
+- **axe DevTools** (Chrome/Firefox) — free version covers most WCAG checks
+- **Accessibility Insights** (Microsoft, Chrome) — guided assessments
+
+### Playwright integration
+
+```js
+import { test, expect } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+test('homepage has no a11y violations', async ({ page }) => {
+    await page.goto('/');
+
+    const results = await new AxeBuilder({ page })
+        .withTags(['wcag2a', 'wcag2aa'])
+        .exclude('.third-party-widget') // exclude elements you don't control
+        .analyze();
+
+    expect(results.violations).toEqual([]);
+});
+
+test('editor page is accessible', async ({ page }) => {
+    await page.goto('/wp-admin/post-new.php');
+
+    const results = await new AxeBuilder({ page })
+        .include('.editor-styles-wrapper') // focus on specific area
+        .withTags(['wcag2a', 'wcag2aa'])
+        .analyze();
+
+    expect(results.violations).toEqual([]);
+});
+```
+
+### pa11y
+
+```bash
+# Single page
+npx pa11y https://localhost:8888/
+
+# With specific standard
+npx pa11y --standard WCAG2AA https://localhost:8888/
+
+# Multiple pages
+npx pa11y-ci --config .pa11yci.json
+```
+
+`.pa11yci.json`:
+```json
+{
+    "defaults": {
+        "standard": "WCAG2AA",
+        "timeout": 30000,
+        "wait": 1000
+    },
+    "urls": [
+        "http://localhost:8888/",
+        "http://localhost:8888/sample-page/",
+        "http://localhost:8888/blog/",
+        "http://localhost:8888/contact/"
+    ]
+}
+```
+
+### Lighthouse
+
+```bash
+# Accessibility audit via CLI
+npx lighthouse https://localhost:8888/ --only-categories=accessibility --output=json --output-path=a11y-report.json
+
+# Chrome DevTools: Lighthouse tab → Accessibility checkbox → Generate report
+```
+
+## WordPress-specific tools
+
+### WordPress Accessibility Checker plugin
+
+Dashboard widget showing issues per page/post.
+
+### FLAVOR (by WordPress a11y team)
+
+Browser extension specifically for WordPress theme review. Tests `accessibility-ready` requirements.
+
+### WP-CLI health check
+
+```bash
+# Check theme support for accessibility features
+wp theme mod list
+wp eval "var_dump(current_theme_supports('html5'));"
+```
+
+## Color contrast tools
+
+### WebAIM Contrast Checker
+
+https://webaim.org/resources/contrastchecker/
+
+| Ratio | WCAG Level | Applies to |
+|-------|-----------|-----------|
+| 4.5:1 | AA | Normal text (< 24px / 18.66px bold) |
+| 3:1 | AA | Large text (≥ 24px / 18.66px bold) |
+| 7:1 | AAA | Normal text |
+| 4.5:1 | AAA | Large text |
+| 3:1 | AA | UI components and graphical objects |
+
+### Programmatic contrast checking
+
+```js
+// Calculate relative luminance
+function luminance(r, g, b) {
+    const [rs, gs, bs] = [r, g, b].map((c) => {
+        c = c / 255;
+        return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+    });
+    return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
+}
+
+function contrastRatio(rgb1, rgb2) {
+    const l1 = luminance(...rgb1);
+    const l2 = luminance(...rgb2);
+    const lighter = Math.max(l1, l2);
+    const darker = Math.min(l1, l2);
+    return (lighter + 0.05) / (darker + 0.05);
+}
+```
+
+### Browser DevTools
+
+Chrome DevTools: Inspect element → Color picker → Shows contrast ratio and WCAG compliance.
+
+Firefox: Accessibility tab in DevTools → Check for Issues → Contrast.
+
+## Screen readers
+
+### Testing matrix
+
+| OS | Screen Reader | Browser |
+|----|--------------|---------|
+| Windows | NVDA (free) | Firefox or Chrome |
+| Windows | JAWS | Chrome or Edge |
+| macOS | VoiceOver (built-in) | Safari |
+| iOS | VoiceOver (built-in) | Safari |
+| Android | TalkBack (built-in) | Chrome |
+
+### NVDA quick reference
+
+| Key | Action |
+|-----|--------|
+| Insert+Space | Toggle focus/browse mode |
+| H | Next heading |
+| Shift+H | Previous heading |
+| D | Next landmark |
+| Tab | Next focusable element |
+| Insert+F7 | Elements list (links, headings, landmarks) |
+
+### VoiceOver quick reference (macOS)
+
+| Key | Action |
+|-----|--------|
+| Cmd+F5 | Toggle VoiceOver |
+| VO+Right | Next element |
+| VO+Left | Previous element |
+| VO+U | Rotor (navigate by headings, links, etc.) |
+| Tab | Next focusable element |
+
+(VO = Control+Option)
+
+## CI/CD integration
+
+### GitHub Actions
+
+```yaml
+name: Accessibility Tests
+on: [push, pull_request]
+
+jobs:
+  a11y:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Start WordPress
+        run: npx wp-env start
+
+      - name: Run axe tests
+        run: npx @axe-core/cli http://localhost:8888/ --tags wcag2a,wcag2aa --exit
+
+      - name: Run pa11y
+        run: npx pa11y-ci --config .pa11yci.json
+```
+
+## Audit report template
+
+```markdown
+## Accessibility Audit Report
+
+**Date:** YYYY-MM-DD
+**Standard:** WCAG 2.2 Level AA
+**Tool:** axe-core 4.x + manual testing
+
+### Summary
+- Critical: X issues
+- Serious: X issues
+- Moderate: X issues
+- Minor: X issues
+
+### Critical Issues
+1. **[Rule ID]** — Description
+   - Location: page/element
+   - Impact: who is affected
+   - Fix: recommended remediation
+
+### Manual Testing Results
+- [ ] Keyboard navigation: Pass/Fail
+- [ ] Screen reader: Pass/Fail
+- [ ] Color contrast: Pass/Fail
+- [ ] Zoom 200%: Pass/Fail
+- [ ] Reduced motion: Pass/Fail
+```
+
+## Verification
+
+Automated tools catch ~30-40% of accessibility issues. Always supplement with:
+1. Keyboard-only navigation test
+2. Screen reader walk-through
+3. Color contrast verification
+4. Content zoom to 200%
+5. Reduced motion preference test