claude-plugin-wordpress-manager 2.4.0 → 2.9.0

package/skills/wp-alerting/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: wp-alerting
+description: This skill should be used when the user asks about "alerting",
+  "alerts", "Slack notifications", "email alerts", "monitoring alerts",
+  "threshold alerts", "health reports", "escalation", "incident notifications",
+  "uptime alerts", "error alerts", "performance alerts", "scheduled reports",
+  or mentions setting up notification channels for WordPress monitoring events.
+version: 1.0.0
+tags: [alerting, slack, notifications, monitoring, email]
+---
+
+# WordPress Alerting Skill
+
+## Overview
+
+Cross-cutting alerting system combining Slack (webhook + Bot Token) and SendGrid email for WordPress monitoring events. Provides severity-based routing, configurable thresholds, escalation paths, and scheduled health reports. This skill connects monitoring data from other skills (analytics, performance, uptime) to notification channels, ensuring the right people are informed at the right time with the right level of urgency.
+
+## When to Use
+
+- User wants to set up Slack notifications for WordPress events
+- User needs email alerts for critical site issues (downtime, errors)
+- User asks about alert thresholds (CWV scores, error rates, disk usage)
+- User wants to configure escalation rules (info vs warning vs critical)
+- User needs scheduled health reports (daily digest, weekly summary)
+- User asks about alert cooldown, deduplication, or routing logic
+- User wants to integrate monitoring data with notification channels
+- User needs to test alert delivery (Slack webhook or SendGrid)
+
+## Decision Tree
+
+1. **What notification channel?**
+   - "Slack webhook" / "simple alerts" → Slack Webhook Setup (Procedure 1)
+   - "Slack bot" / "Block Kit" / "advanced Slack" → Slack Bot Setup (Procedure 2)
+   - "email alerts" / "SendGrid alerts" → Use SendGrid config from `wp-social-email`
+   - "both" / "escalation" → Alert Dispatch with severity routing (Procedure 4)
+
+2. **Run detection first:**
+   ```bash
+   node skills/wp-alerting/scripts/alerting_inspect.mjs [--cwd=/path/to/project]
+   ```
+   This identifies configured Slack credentials, SendGrid keys, and monitoring plugins.
+
+## Procedures
+
+### Procedure 1: Slack Webhook Setup (Simple Alerts)
+
+See `references/slack-integration.md`
+- Create Incoming Webhook in Slack App dashboard
+- Add `slack_webhook_url` to WP_SITES_CONFIG
+- Optionally set `slack_channel` for default channel override
+- Send test message via `slack_send_webhook` tool
+- Validate delivery and format
+
+### Procedure 2: Slack Bot Setup (Advanced Messaging)
+
+See `references/slack-integration.md`
+- Create Slack App with Bot Token (OAuth scopes: `chat:write`, `channels:read`)
+- Add `slack_bot_token` and `slack_channel` to WP_SITES_CONFIG
+- Use Block Kit formatting for structured alert messages
+- Support for threaded replies, reactions, and channel management
+- Send test message via `slack_send_message` tool
+
+### Procedure 3: Alert Threshold Configuration
+
+See `references/alert-thresholds.md`
+- Define thresholds for Core Web Vitals (LCP, CLS, INP, FCP, TTFB)
+- Set uptime and error rate thresholds (5xx rate, response time)
+- Configure disk usage and resource limits
+- Set plugin update and content freshness alerts
+- Map each threshold to a severity level (info, warning, critical)
+
+### Procedure 4: Alert Dispatch (Severity-Based Routing)
+
+See `references/escalation-paths.md`
+- **Info** — Slack message only (general channel)
+- **Warning** — Slack message + threaded details
+- **Critical** — Slack message + email notification (SendGrid) + urgent flag
+- Cooldown periods to prevent alert fatigue
+- Deduplication rules to avoid repeated notifications
+- Acknowledgment tracking for critical alerts
+
+### Procedure 5: Scheduled Health Reports
+
+See `references/report-scheduling.md`
+- Daily digest: key metrics summary, new alerts, resolved alerts
+- Weekly performance summary: CWV trends, traffic changes, uptime stats
+- Monthly analytics report: comprehensive overview with comparisons
+- On-demand report generation via command
+- Report format templates using Slack Block Kit
+
+## MCP Tools Reference
+
+| Tool | Description |
+|------|-------------|
+| `slack_send_webhook` | Send alert via Slack Incoming Webhook URL |
+| `slack_send_message` | Send alert via Slack Bot Token (supports Block Kit) |
+| `slack_list_channels` | List available Slack channels for alert routing |
+| `sg_send_email` | Send alert email via SendGrid |
+| `sg_send_template_email` | Send templated alert email via SendGrid |
+| `sg_list_templates` | List available SendGrid email templates |
+| `sg_create_template` | Create a new alert email template |
+| `sg_get_template` | Get alert email template details |
+| `sg_validate_email` | Validate alert recipient email address |
+
+## Reference Files
+
+| File | Content |
+|------|---------|
+| `references/slack-integration.md` | Slack Incoming Webhook + Bot Token setup, Block Kit formatting, best practices |
+| `references/alert-thresholds.md` | Threshold definitions for CWV, uptime, error rate, disk, plugins, content |
+| `references/escalation-paths.md` | Severity levels, routing rules, cooldown, dedup, acknowledgment |
+| `references/report-scheduling.md` | Scheduled reports: daily, weekly, monthly, on-demand, Block Kit templates |
+
+## Recommended Agent
+
+Use the **`wp-monitoring-agent`** for automated alerting workflows that combine threshold monitoring, severity-based dispatch, and scheduled health report generation.
+
+## Related Skills
+
+- **`wp-monitoring`** — source of monitoring data that triggers alerts
+- **`wp-analytics`** — analytics metrics used in threshold evaluation and reports
+- **`wp-social-email`** — shares SendGrid configuration for email delivery
+
+## Cross-references
+
+- Alert thresholds pair with `wp-analytics` CWV data for performance alerting
+- Slack integration connects to `wp-monitoring` for uptime and health alerts
+- SendGrid config is shared with `wp-social-email` for consistent email delivery
+- Scheduled reports aggregate data from `wp-analytics` and `wp-monitoring`
+
+## Troubleshooting
+
+| Issue | Cause | Resolution |
+|-------|-------|------------|
+| Slack webhook returns 404 | Webhook URL invalid or deleted | Recreate webhook in Slack App dashboard and update WP_SITES_CONFIG |
+| Slack bot "not_in_channel" | Bot not invited to target channel | Invite bot to channel with `/invite @botname` or use `channels:join` scope |
+| Slack bot "missing_scope" | Bot token lacks required OAuth scopes | Add `chat:write` and `channels:read` scopes in Slack App settings |
+| Slack rate limited (429) | Too many messages per second | Implement cooldown periods; batch non-critical alerts |
+| SendGrid 403 error | API key lacks Mail Send permission | Regenerate API key with "Mail Send" access in SendGrid dashboard |
+| Alerts not firing | Thresholds not configured or too high | Review threshold config; lower thresholds for testing |
+| Duplicate alerts | No dedup rules configured | Enable deduplication with cooldown period per alert type |
+| Detection script exit 1 | No alerting config found | Add slack_webhook_url, slack_bot_token, or sg_api_key to WP_SITES_CONFIG |

package/skills/wp-alerting/references/alert-thresholds.md

@@ -0,0 +1,79 @@
+# Alert Threshold Definitions
+
+## Core Web Vitals Thresholds
+
+| Metric | Good | Warning | Critical | Unit |
+|--------|------|---------|----------|------|
+| LCP (Largest Contentful Paint) | < 2.5s | 2.5s - 4.0s | > 4.0s | seconds |
+| FCP (First Contentful Paint) | < 1.8s | 1.8s - 3.0s | > 3.0s | seconds |
+| CLS (Cumulative Layout Shift) | < 0.1 | 0.1 - 0.25 | > 0.25 | score |
+| INP (Interaction to Next Paint) | < 200ms | 200ms - 500ms | > 500ms | milliseconds |
+| TTFB (Time to First Byte) | < 800ms | 800ms - 1800ms | > 1800ms | milliseconds |
+
+These follow Google's published CWV thresholds. A warning indicates "needs improvement," critical indicates "poor."
+
+## Uptime & Availability Thresholds
+
+| Metric | Warning | Critical | Window |
+|--------|---------|----------|--------|
+| HTTP 5xx error rate | > 2% of requests | > 5% of requests | per hour |
+| Response time (avg) | > 2s | > 5s | per 15 minutes |
+| Response time (p95) | > 4s | > 10s | per 15 minutes |
+| Downtime duration | > 1 minute | > 5 minutes | consecutive |
+| SSL certificate expiry | < 30 days | < 7 days | daily check |
+
+## Error Rate Thresholds
+
+| Metric | Warning | Critical | Notes |
+|--------|---------|----------|-------|
+| PHP fatal errors | > 5/hour | > 20/hour | Check `debug.log` or error tracking |
+| PHP warnings | > 50/hour | > 200/hour | May indicate plugin conflicts |
+| JavaScript errors | > 10/hour | > 50/hour | Frontend console errors |
+| 404 rate | > 5% of requests | > 15% of requests | May indicate broken links or attacks |
+| Database query errors | > 1/hour | > 10/hour | Check slow query log |
+
+## Resource Usage Thresholds
+
+| Metric | Warning | Critical | Notes |
+|--------|---------|----------|-------|
+| Disk usage | > 80% | > 95% | Check uploads, logs, backups |
+| PHP memory usage | > 80% of limit | > 95% of limit | Per-request memory |
+| Database size growth | > 10%/week | > 25%/week | May indicate spam or logging |
+| Backup age | > 24 hours | > 72 hours | Last successful backup |
+
+## Plugin & Update Thresholds
+
+| Metric | Severity | Notes |
+|--------|----------|-------|
+| Plugin updates available | Info (1-2), Warning (3-5), Critical (6+) | Security updates always critical |
+| Theme updates available | Warning | Check compatibility first |
+| WordPress core update | Warning (minor), Critical (security) | Security patches are urgent |
+| Plugin vulnerability found | Critical | Immediate action required |
+
+## Content Freshness Thresholds
+
+| Metric | Warning | Critical | Notes |
+|--------|---------|----------|-------|
+| Last published post | > 14 days | > 30 days | Blog/news sites |
+| Stale draft count | > 10 drafts | > 25 drafts | Content pipeline health |
+| Broken internal links | > 5 | > 20 | SEO and UX impact |
+| Missing alt text (new images) | > 10% | > 25% | Accessibility compliance |
+
+## Custom Threshold Configuration
+
+Thresholds are configurable per site via `WP_SITES_CONFIG`:
+
+```json
+{
+  "alert_thresholds": {
+    "lcp_warning": 2.5,
+    "lcp_critical": 4.0,
+    "error_rate_warning": 0.02,
+    "error_rate_critical": 0.05,
+    "disk_warning": 0.80,
+    "disk_critical": 0.95
+  }
+}
+```
+
+Override defaults by adding the `alert_thresholds` object to any site entry. Unspecified thresholds fall back to the defaults listed above.

package/skills/wp-alerting/references/escalation-paths.md

@@ -0,0 +1,92 @@
+# Escalation Paths
+
+## Severity Levels
+
+| Level | Icon | Description | Example Triggers |
+|-------|------|-------------|-----------------|
+| **Info** | :information_source: | Informational, no action needed | Plugin updates available, backup completed, content published |
+| **Warning** | :warning: | Needs attention within hours | LCP > 2.5s, error rate > 2%, disk > 80%, SSL < 30 days |
+| **Critical** | :rotating_light: | Immediate action required | Site down, LCP > 4s, error rate > 5%, disk > 95%, security vulnerability |
+
+## Routing Rules
+
+### Info Severity
+
+- **Slack**: Post to general alerts channel (`#wp-alerts`)
+- **Email**: None
+- **Format**: Simple text message
+- **Threading**: No thread — standalone message
+- **Mention**: None
+
+### Warning Severity
+
+- **Slack**: Post to alerts channel + create thread with details
+- **Email**: None (unless configured in escalation override)
+- **Format**: Block Kit section with fields
+- **Threading**: Main message + detail thread
+- **Mention**: None (or `@here` if configured)
+
+### Critical Severity
+
+- **Slack**: Post to critical channel (`#wp-critical`) + thread with diagnostics
+- **Email**: Send via SendGrid to configured alert recipients
+- **Format**: Block Kit header + sections + action buttons
+- **Threading**: Main message + detail thread + follow-up updates
+- **Mention**: `<!channel>` in Slack, priority flag in email
+
+## Cooldown Periods
+
+Prevent alert fatigue by enforcing minimum intervals between repeat alerts:
+
+| Severity | Cooldown | Notes |
+|----------|----------|-------|
+| Info | 60 minutes | Same alert type on same site |
+| Warning | 30 minutes | Same metric on same site |
+| Critical | 10 minutes | Same incident on same site |
+
+### Cooldown Logic
+
+1. Before sending an alert, check the last alert timestamp for the same `(site, metric, severity)` tuple.
+2. If within cooldown window, skip the alert (log silently).
+3. If the severity **escalates** (warning -> critical), send immediately regardless of cooldown.
+4. Reset the cooldown timer on each sent alert.
+
+## Deduplication Rules
+
+| Rule | Description |
+|------|-------------|
+| Same metric + same site + same severity | Deduplicate within cooldown window |
+| Severity escalation | Always send (warning->critical bypasses dedup) |
+| Severity de-escalation | Send recovery notification (critical->warning->resolved) |
+| Recovery after critical | Always send "resolved" message to close the incident |
+
+### Dedup Key Format
+
+```
+{site_id}:{metric}:{severity}
+```
+
+Example: `mysite:lcp:warning`, `mysite:uptime:critical`
+
+## Acknowledgment Tracking
+
+For critical alerts, track acknowledgment status:
+
+1. Critical alert sent with "Acknowledge" button (Slack Block Kit action).
+2. If not acknowledged within **15 minutes**, re-send with escalation mention.
+3. If not acknowledged within **30 minutes**, send email to backup contacts.
+4. Mark incident as acknowledged when button clicked or manual response received.
+
+## Recovery Notifications
+
+When a metric returns to normal after an alert:
+
+- **Info**: No recovery notification.
+- **Warning**: Post recovery message to same channel (with reference to original alert).
+- **Critical**: Post recovery message + reply in original thread + send recovery email.
+
+Recovery message format:
+```
+:white_check_mark: RESOLVED: {metric} on {site} returned to normal.
+Duration: {alert_duration}. Current value: {current_value}.
+```

package/skills/wp-alerting/references/report-scheduling.md

@@ -0,0 +1,142 @@
+# Report Scheduling
+
+## Report Types
+
+| Report | Frequency | Content | Delivery |
+|--------|-----------|---------|----------|
+| Daily Digest | Daily (09:00 UTC) | Key metrics, new alerts, resolved alerts | Slack |
+| Weekly Performance Summary | Weekly (Monday 09:00 UTC) | CWV trends, traffic delta, uptime %, top errors | Slack |
+| Monthly Analytics Report | Monthly (1st, 09:00 UTC) | Full analytics overview, MoM comparisons, recommendations | Slack + Email |
+| On-Demand Report | Manual trigger | Any combination of metrics | Slack or Email |
+
+## Daily Digest
+
+### Content
+
+- Site uptime percentage (last 24h)
+- Average response time
+- New alerts triggered (count by severity)
+- Resolved alerts (count)
+- CWV snapshot (LCP, CLS, INP averages)
+- Plugin updates pending
+
+### Slack Block Kit Template
+
+```json
+{
+  "blocks": [
+    {
+      "type": "header",
+      "text": { "type": "plain_text", "text": ":newspaper: Daily Digest — example.com" }
+    },
+    {
+      "type": "section",
+      "fields": [
+        { "type": "mrkdwn", "text": "*Uptime:*\n99.98%" },
+        { "type": "mrkdwn", "text": "*Avg Response:*\n420ms" },
+        { "type": "mrkdwn", "text": "*Alerts (new):*\n2 warning, 0 critical" },
+        { "type": "mrkdwn", "text": "*Alerts (resolved):*\n1" }
+      ]
+    },
+    {
+      "type": "section",
+      "fields": [
+        { "type": "mrkdwn", "text": "*LCP:*\n1.8s :white_check_mark:" },
+        { "type": "mrkdwn", "text": "*CLS:*\n0.05 :white_check_mark:" },
+        { "type": "mrkdwn", "text": "*INP:*\n150ms :white_check_mark:" },
+        { "type": "mrkdwn", "text": "*Updates:*\n3 plugins pending" }
+      ]
+    },
+    {
+      "type": "context",
+      "elements": [
+        { "type": "mrkdwn", "text": "Report period: last 24 hours | Generated by wp-monitoring-agent" }
+      ]
+    }
+  ]
+}
+```
+
+## Weekly Performance Summary
+
+### Content
+
+- CWV trends (7-day averages vs previous week)
+- Traffic summary (sessions, pageviews, bounce rate delta)
+- Uptime percentage and incident count
+- Top 5 errors by frequency
+- Top 5 slowest pages
+- Plugin/theme update status
+
+### Slack Block Kit Template
+
+```json
+{
+  "blocks": [
+    {
+      "type": "header",
+      "text": { "type": "plain_text", "text": ":bar_chart: Weekly Summary — example.com" }
+    },
+    {
+      "type": "section",
+      "text": { "type": "mrkdwn", "text": "*Core Web Vitals (7-day avg):*\nLCP: 1.9s (+0.1s) | CLS: 0.04 (-0.01) | INP: 160ms (+10ms)" }
+    },
+    {
+      "type": "section",
+      "text": { "type": "mrkdwn", "text": "*Traffic:*\nSessions: 12,450 (+8%) | Pageviews: 34,200 (+5%) | Bounce: 42% (-2%)" }
+    },
+    {
+      "type": "section",
+      "text": { "type": "mrkdwn", "text": "*Uptime:*\n99.95% | Incidents: 1 (resolved in 3 min)" }
+    },
+    {
+      "type": "context",
+      "elements": [
+        { "type": "mrkdwn", "text": "Report period: last 7 days | Generated by wp-monitoring-agent" }
+      ]
+    }
+  ]
+}
+```
+
+## Monthly Analytics Report
+
+### Content
+
+- Complete CWV analysis with month-over-month comparison
+- Traffic analytics (GA4 + Plausible combined)
+- Top content by engagement and conversions
+- SEO performance (Search Console data if available)
+- Error and incident summary
+- Resource usage trends (disk, database)
+- Recommendations based on trends
+
+### Delivery
+
+- **Slack**: Summary Block Kit message with key highlights
+- **Email (SendGrid)**: Full HTML report with charts and tables
+
+## On-Demand Reports
+
+Triggered manually via command. Supports parameters:
+
+- `--period=7d|30d|90d` — report time range
+- `--metrics=cwv,traffic,uptime,errors` — select metric groups
+- `--format=slack|email|both` — delivery channel
+- `--site=site_id` — target site (defaults to all)
+
+## Scheduling Configuration
+
+Reports are scheduled via `WP_SITES_CONFIG`:
+
+```json
+{
+  "report_schedule": {
+    "daily_digest": { "enabled": true, "time": "09:00", "timezone": "UTC", "channel": "#wp-reports" },
+    "weekly_summary": { "enabled": true, "day": "monday", "time": "09:00", "timezone": "UTC" },
+    "monthly_report": { "enabled": true, "day": 1, "time": "09:00", "email_recipients": ["team@example.com"] }
+  }
+}
+```
+
+Disable any report by setting `"enabled": false`. Adjust `time` and `timezone` as needed.

package/skills/wp-alerting/references/slack-integration.md

@@ -0,0 +1,109 @@
+# Slack Integration for WordPress Alerting
+
+## Incoming Webhook Setup
+
+1. Go to [Slack API: Apps](https://api.slack.com/apps) and create a new app (or select existing).
+2. Navigate to **Incoming Webhooks** and activate them.
+3. Click **Add New Webhook to Workspace** and select the target channel.
+4. Copy the webhook URL (format: `https://hooks.slack.com/services/T.../B.../xxx`).
+5. Add to `WP_SITES_CONFIG`:
+   ```json
+   { "slack_webhook_url": "https://hooks.slack.com/services/T.../B.../xxx" }
+   ```
+
+### Webhook Payload Format
+
+```json
+{
+  "text": "Fallback text for notifications",
+  "blocks": [ ... ]
+}
+```
+
+Webhooks support a subset of Block Kit — use `text` for simple alerts, `blocks` for rich formatting.
+
+## Bot Token Setup (Advanced)
+
+1. In your Slack App, go to **OAuth & Permissions**.
+2. Add the following **Bot Token Scopes**:
+   - `chat:write` — send messages to channels
+   - `channels:read` — list public channels for routing
+   - `channels:join` — (optional) auto-join channels
+3. Install the app to workspace and copy the **Bot User OAuth Token** (`xoxb-...`).
+4. Add to `WP_SITES_CONFIG`:
+   ```json
+   {
+     "slack_bot_token": "xoxb-...",
+     "slack_channel": "#wp-alerts"
+   }
+   ```
+
+### Bot Token vs Webhook
+
+| Feature | Webhook | Bot Token |
+|---------|---------|-----------|
+| Setup complexity | Low | Medium |
+| Block Kit support | Partial | Full |
+| Threaded replies | No | Yes |
+| Channel switching | No (fixed) | Yes (dynamic) |
+| Reactions/emoji | No | Yes |
+| Rate limit | 1 req/sec | Tier 2+ |
+
+## Block Kit Formatting for Alerts
+
+### Critical Alert Template
+
+```json
+{
+  "blocks": [
+    {
+      "type": "header",
+      "text": { "type": "plain_text", "text": ":rotating_light: CRITICAL: Site Down", "emoji": true }
+    },
+    {
+      "type": "section",
+      "fields": [
+        { "type": "mrkdwn", "text": "*Site:*\nexample.com" },
+        { "type": "mrkdwn", "text": "*Status:*\n503 Service Unavailable" },
+        { "type": "mrkdwn", "text": "*Detected:*\n2026-03-01 14:30 UTC" },
+        { "type": "mrkdwn", "text": "*Duration:*\n5 minutes" }
+      ]
+    },
+    {
+      "type": "actions",
+      "elements": [
+        { "type": "button", "text": { "type": "plain_text", "text": "Acknowledge" }, "action_id": "ack_alert", "style": "danger" }
+      ]
+    }
+  ]
+}
+```
+
+### Warning Alert Template
+
+```json
+{
+  "blocks": [
+    {
+      "type": "section",
+      "text": { "type": "mrkdwn", "text": ":warning: *LCP exceeded threshold*\nSite: example.com | LCP: 3.2s (threshold: 2.5s)" }
+    }
+  ]
+}
+```
+
+### Info Alert Template
+
+```json
+{
+  "text": ":information_source: Plugin updates available: 3 plugins on example.com"
+}
+```
+
+## Best Practices
+
+- **Channel naming**: Use dedicated channels (`#wp-alerts`, `#wp-critical`) to separate alert noise.
+- **Mention patterns**: Use `<!channel>` for critical, `<@user_id>` for assigned responders.
+- **Rate limiting**: Slack enforces 1 msg/sec for webhooks. Batch low-priority alerts.
+- **Testing**: Always send a test message after setup to verify formatting.
+- **Fallback text**: Always include `text` field — it appears in notifications and search.