claude-plugin-wordpress-manager 2.6.0 → 2.9.0

package/skills/wp-content-workflows/references/schedule-triggers.md

@@ -0,0 +1,118 @@
+# Schedule-Based Triggers
+
+## WP-Cron Built-in Intervals
+
+| Interval | Hook Name | Frequency |
+|----------|-----------|-----------|
+| `hourly` | `wp_scheduled_event` | Every hour |
+| `twicedaily` | `wp_scheduled_event` | Every 12 hours |
+| `daily` | `wp_scheduled_event` | Every 24 hours |
+| `weekly` | `wp_scheduled_event` | Every 7 days |
+
+## Custom Cron Intervals
+
+Register custom intervals via `cron_schedules` filter:
+
+```php
+add_filter('cron_schedules', function ($schedules) {
+    $schedules['every_15_minutes'] = [
+        'interval' => 900,
+        'display'  => 'Every 15 Minutes',
+    ];
+    $schedules['every_monday_9am'] = [
+        'interval' => 604800, // weekly
+        'display'  => 'Weekly (Monday 9am)',
+    ];
+    return $schedules;
+});
+```
+
+Schedule a recurring event:
+
+```php
+if (!wp_next_scheduled('wpm_weekly_report')) {
+    wp_schedule_event(
+        strtotime('next Monday 09:00'),
+        'weekly',
+        'wpm_weekly_report'
+    );
+}
+add_action('wpm_weekly_report', 'generate_weekly_performance_report');
+```
+
+## Scheduled Content Publishing
+
+WordPress natively supports future-dated posts via `publish_future_post` hook:
+
+- Set post status to `future` with a future `post_date`
+- WP-Cron fires `publish_future_post` at the scheduled time
+- Trigger workflow actions on publish (e.g., notify Slack)
+
+Trigger config example:
+
+```json
+{
+  "type": "schedule",
+  "event": "publish_future_post",
+  "actions": [
+    { "channel": "slack", "message": "New post published: {{post_title}}" }
+  ]
+}
+```
+
+## Recurring Health Check Triggers
+
+Common scheduled workflow patterns:
+
+| Trigger | Interval | Purpose |
+|---------|----------|---------|
+| Performance report | Weekly | CWV scores, uptime stats |
+| Plugin update check | Daily | Security and compatibility |
+| Content freshness | Weekly | Stale draft detection |
+| Backup verification | Daily | Confirm last backup age |
+| SSL expiry check | Daily | Certificate renewal reminder |
+
+## External Cron Setup (Server Cron)
+
+When `DISABLE_WP_CRON` is `true`, use server-side cron:
+
+```bash
+# crontab entry — fire WP-Cron every 5 minutes
+*/5 * * * * wget -qO- https://example.com/wp-cron.php > /dev/null 2>&1
+
+# Alternative with curl
+*/5 * * * * curl -s https://example.com/wp-cron.php > /dev/null 2>&1
+
+# WP-CLI approach (recommended for reliability)
+*/5 * * * * cd /var/www/html && wp cron event run --due-now > /dev/null 2>&1
+```
+
+**When to use external cron:**
+- High-traffic sites (WP-Cron adds latency to page loads)
+- Sites behind caching layers that block `wp-cron.php`
+- When precise timing is required (WP-Cron is visitor-triggered)
+
+## Example: Weekly Performance Report Every Monday 9am
+
+```json
+{
+  "name": "Weekly Performance Report",
+  "type": "schedule",
+  "schedule": "weekly",
+  "first_run": "2026-03-02T09:00:00Z",
+  "actions": [
+    {
+      "channel": "slack",
+      "template": "weekly_report",
+      "variables": { "site": "{{site_url}}", "period": "last_7_days" }
+    },
+    {
+      "channel": "email",
+      "to": "team@example.com",
+      "subject": "Weekly WP Report — {{site_url}}",
+      "template": "weekly_report_email"
+    }
+  ],
+  "status": "active"
+}
+```

package/skills/wp-content-workflows/references/trigger-management.md

@@ -0,0 +1,159 @@
+# Trigger Management
+
+## Listing and Filtering Triggers
+
+Use `wf_list_triggers` to retrieve all registered triggers:
+
+```json
+// List all triggers
+{ "tool": "wf_list_triggers" }
+
+// Filter by status
+{ "tool": "wf_list_triggers", "status": "active" }
+{ "tool": "wf_list_triggers", "status": "inactive" }
+
+// Filter by type
+{ "tool": "wf_list_triggers", "type": "schedule" }
+{ "tool": "wf_list_triggers", "type": "content_lifecycle" }
+{ "tool": "wf_list_triggers", "type": "action_hook" }
+```
+
+### Trigger List Response Format
+
+| Field | Description |
+|-------|-------------|
+| `id` | Unique trigger identifier |
+| `name` | Human-readable trigger name |
+| `type` | `schedule`, `content_lifecycle`, or `action_hook` |
+| `event` | The WordPress event or cron schedule |
+| `status` | `active` or `inactive` |
+| `actions` | Array of action channel configurations |
+| `last_fired` | Timestamp of last execution (null if never) |
+| `fire_count` | Total number of times fired |
+| `created_at` | Creation timestamp |
+
+## Activate/Deactivate Without Deleting
+
+Toggle triggers on or off without losing configuration:
+
+```json
+// Deactivate a trigger
+{ "tool": "wf_update_trigger", "id": "trg_001", "status": "inactive" }
+
+// Reactivate a trigger
+{ "tool": "wf_update_trigger", "id": "trg_001", "status": "active" }
+```
+
+**Use cases for deactivation:**
+- Temporarily silence during maintenance windows
+- Pause triggers during site migration
+- Debug by isolating triggers one at a time
+- Seasonal triggers (e.g., holiday sale workflows)
+
+## Testing Triggers (Dry-Run Mode)
+
+Test a trigger without executing real actions:
+
+```json
+{
+  "tool": "wf_update_trigger",
+  "id": "trg_001",
+  "dry_run": true
+}
+```
+
+Dry-run behavior:
+- Evaluates conditions against current site state
+- Resolves all template variables with real data
+- Logs the fully rendered action payloads
+- Does NOT send Slack messages, emails, or webhooks
+- Returns the rendered output for review
+
+### Manual Test Fire
+
+Force a trigger to execute once (real actions):
+
+```json
+{
+  "tool": "wf_update_trigger",
+  "id": "trg_001",
+  "test_fire": true
+}
+```
+
+**Warning:** `test_fire` sends real messages. Use `dry_run` first to verify payload format.
+
+## Trigger Audit Log
+
+Every trigger execution is logged:
+
+| Field | Description |
+|-------|-------------|
+| `trigger_id` | ID of the trigger that fired |
+| `timestamp` | When the trigger fired |
+| `event` | WordPress event that caused the fire |
+| `actions_executed` | List of actions taken (channel + status) |
+| `dry_run` | Whether this was a dry-run execution |
+| `error` | Error message if any action failed |
+| `duration_ms` | Total execution time in milliseconds |
+
+Query audit logs via the WordPress admin or REST API for debugging and compliance.
+
+## Bulk Operations
+
+### Enable/Disable All Triggers
+
+```json
+// Disable all triggers (maintenance mode)
+{ "tool": "wf_update_trigger", "bulk": true, "status": "inactive" }
+
+// Re-enable all triggers
+{ "tool": "wf_update_trigger", "bulk": true, "status": "active" }
+```
+
+### Export/Import Triggers
+
+Export all trigger configurations as JSON for backup or migration:
+
+```json
+// Export triggers
+{ "tool": "wf_list_triggers", "format": "export" }
+```
+
+The export includes full trigger config without runtime data (fire_count, last_fired). Import by creating triggers from the exported JSON array.
+
+### Bulk Delete
+
+Remove all inactive or stale triggers:
+
+```json
+// Delete a specific trigger (requires confirmation)
+{ "tool": "wf_delete_trigger", "id": "trg_001" }
+```
+
+The `wf_delete_trigger` tool has a safety hook that requires explicit confirmation before deletion.
+
+## Cleanup: Removing Stale Triggers
+
+A trigger is considered stale if:
+- Status is `inactive` for more than 30 days
+- `last_fired` is null and `created_at` is older than 30 days
+- Referenced hook or event no longer exists (e.g., plugin deactivated)
+
+### Cleanup Workflow
+
+1. List inactive triggers: `wf_list_triggers` with `status: "inactive"`
+2. Review each trigger's `last_fired` and `created_at`
+3. Identify stale triggers based on criteria above
+4. Delete stale triggers with `wf_delete_trigger`
+5. Verify remaining triggers are all active and functional
+
+### Recommended Maintenance Schedule
+
+| Task | Frequency | Tool |
+|------|-----------|------|
+| Review trigger list | Weekly | `wf_list_triggers` |
+| Test critical triggers | Monthly | `wf_update_trigger` (dry_run) |
+| Clean stale triggers | Monthly | `wf_delete_trigger` |
+| Export trigger backup | Before updates | `wf_list_triggers` (export) |
+| Audit log review | Weekly | WordPress admin |

package/skills/wp-content-workflows/references/wp-action-hooks.md

@@ -0,0 +1,114 @@
+# WordPress Action/Filter Hooks for Workflows
+
+## Core WordPress Action Hooks
+
+### User Actions
+
+| Hook | Fires When | Key Parameters |
+|------|------------|----------------|
+| `user_register` | New user created | `$user_id` |
+| `wp_login` | User logs in | `$user_login`, `$user` |
+| `wp_logout` | User logs out | `$user_id` |
+| `profile_update` | Profile updated | `$user_id`, `$old_user_data` |
+| `delete_user` | User deleted | `$user_id`, `$reassign` |
+| `set_user_role` | Role changed | `$user_id`, `$role`, `$old_roles` |
+
+### Comment Actions
+
+| Hook | Fires When | Key Parameters |
+|------|------------|----------------|
+| `comment_post` | New comment posted | `$comment_id`, `$approved` |
+| `edit_comment` | Comment edited | `$comment_id` |
+| `wp_set_comment_status` | Status changed (approve/spam/trash) | `$comment_id`, `$status` |
+| `delete_comment` | Comment deleted | `$comment_id` |
+
+### Plugin & Theme Actions
+
+| Hook | Fires When | Key Parameters |
+|------|------------|----------------|
+| `activated_plugin` | Plugin activated | `$plugin`, `$network_wide` |
+| `deactivated_plugin` | Plugin deactivated | `$plugin` |
+| `upgrader_process_complete` | Update completed | `$upgrader`, `$options` |
+| `switch_theme` | Theme switched | `$new_name`, `$new_theme` |
+
+### System Actions
+
+| Hook | Fires When | Key Parameters |
+|------|------------|----------------|
+| `wp_mail_failed` | Email delivery failed | `$wp_error` |
+| `recovery_mode_email_sent` | Recovery mode triggered | — |
+| `wp_privacy_personal_data_export_file_created` | GDPR export ready | `$archive_pathname` |
+
+## WooCommerce Action Hooks
+
+| Hook | Fires When | Key Parameters |
+|------|------------|----------------|
+| `woocommerce_new_order` | New order placed | `$order_id` |
+| `woocommerce_order_status_changed` | Order status transition | `$order_id`, `$old_status`, `$new_status` |
+| `woocommerce_payment_complete` | Payment received | `$order_id` |
+| `woocommerce_order_refunded` | Order refunded | `$order_id`, `$refund_id` |
+| `woocommerce_low_stock` | Product low stock | `$product` |
+| `woocommerce_no_stock` | Product out of stock | `$product` |
+| `woocommerce_new_customer_note` | Customer note added | `$args` |
+
+### Trigger Config Example (WooCommerce)
+
+```json
+{
+  "type": "action_hook",
+  "event": "woocommerce_order_status_changed",
+  "condition": "new_status == 'completed'",
+  "actions": [
+    { "channel": "slack", "message": ":package: Order #{{order_id}} completed — {{order_total}}" },
+    { "channel": "email", "to": "fulfillment@example.com", "subject": "Order #{{order_id}} ready for shipping" }
+  ]
+}
+```
+
+## Filter Hooks for Content Transformation
+
+Filters modify data before saving or displaying. Use for content transformation workflows:
+
+| Filter | Purpose | Parameters |
+|--------|---------|------------|
+| `wp_insert_post_data` | Modify post before save | `$data`, `$postarr` |
+| `the_content` | Transform content on display | `$content` |
+| `wp_handle_upload_prefilter` | Validate uploads before processing | `$file` |
+| `comment_text` | Transform comment text on display | `$comment_text` |
+
+**Note:** Filter-based triggers observe data flow but should not block it. Use filters for logging and auditing, not for heavy action dispatch.
+
+## Hook Priority and Execution Order
+
+```php
+// Default priority is 10. Lower = earlier execution.
+add_action('user_register', 'workflow_on_register', 20); // Fires after core handlers
+add_action('user_register', 'audit_log_register', 5);    // Fires before most handlers
+```
+
+- Use priority `20+` for workflow triggers to ensure core WordPress operations complete first
+- Avoid priority `1` unless the trigger must run before all other handlers
+
+## Example: Email Admin on New User Registration
+
+```json
+{
+  "name": "New User Registration Alert",
+  "type": "action_hook",
+  "event": "user_register",
+  "actions": [
+    {
+      "channel": "email",
+      "to": "admin@example.com",
+      "subject": "New user registered: {{user_name}}",
+      "body": "A new user ({{user_email}}) registered on {{site_url}} at {{timestamp}}.",
+      "template": "new_user_alert"
+    },
+    {
+      "channel": "slack",
+      "message": ":bust_in_silhouette: New user: *{{user_name}}* ({{user_email}})"
+    }
+  ],
+  "status": "active"
+}
+```

package/skills/wp-content-workflows/scripts/workflow_inspect.mjs

@@ -0,0 +1,202 @@
+/**
+ * workflow_inspect.mjs — Detect workflow automation configuration readiness.
+ *
+ * Checks WP_SITES_CONFIG for Slack/SendGrid/Mailchimp credentials.
+ * Scans for automation plugins, custom REST endpoints, WP-Cron config,
+ * and webhook setup.
+ *
+ * Usage:
+ *   node workflow_inspect.mjs [--cwd=/path/to/project]
+ *
+ * Exit codes:
+ *   0 — workflow configuration found
+ *   1 — no workflow configuration found
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { argv, stdout, exit } from 'node:process';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function readFileSafe(filePath) {
+  try { return readFileSync(filePath, 'utf-8'); } catch { return null; }
+}
+
+function existsSafe(filePath) {
+  try { return existsSync(filePath); } catch { return false; }
+}
+
+function globDir(dirPath) {
+  try { return readdirSync(dirPath); } catch { return []; }
+}
+
+// ---------------------------------------------------------------------------
+// Detectors
+// ---------------------------------------------------------------------------
+
+function detectActionChannelConfig() {
+  const channels = { configured: false, indicators: [], missing: [] };
+  const raw = process.env.WP_SITES_CONFIG;
+  if (!raw) { channels.missing.push('WP_SITES_CONFIG env var not set'); return channels; }
+
+  let sites;
+  try { sites = JSON.parse(raw); } catch { channels.missing.push('WP_SITES_CONFIG is not valid JSON'); return channels; }
+  if (!Array.isArray(sites)) { channels.missing.push('WP_SITES_CONFIG is not an array'); return channels; }
+
+  const keys = ['slack_webhook_url', 'slack_bot_token', 'sendgrid_api_key', 'mailchimp_api_key'];
+
+  for (const site of sites) {
+    const label = site.id || site.url || 'unknown';
+    for (const key of keys) {
+      if (site[key]) {
+        channels.configured = true;
+        channels.indicators.push(`${key} configured for ${label}`);
+      } else {
+        channels.missing.push(`${key} not set for ${label}`);
+      }
+    }
+  }
+  return channels;
+}
+
+function detectAutomationPlugins(cwd) {
+  const result = { found: false, indicators: [], recommendations: [] };
+  const pluginsDir = join(cwd, 'wp-content', 'plugins');
+  const plugins = globDir(pluginsDir);
+
+  const automationPlugins = [
+    'automatewoo',
+    'wp-fusion',
+    'fluent-crm',
+    'suretriggers',
+    'wp-crontrol',
+    'advanced-cron-manager',
+    'advanced-cron-manager-pro',
+  ];
+
+  for (const plugin of automationPlugins) {
+    if (plugins.includes(plugin)) {
+      result.found = true;
+      result.indicators.push(`plugin: ${plugin}`);
+    }
+  }
+
+  if (!result.found) {
+    result.recommendations.push('Install wp-crontrol for cron event management');
+    result.recommendations.push('Consider FluentCRM or AutomateWoo for advanced workflows');
+  }
+  return result;
+}
+
+function detectCustomRestEndpoints(cwd) {
+  const rest = { found: false, indicators: [] };
+
+  // Look for wp-manager workflow namespace in plugin/theme files
+  const muPluginsDir = join(cwd, 'wp-content', 'mu-plugins');
+  const pluginsDir = join(cwd, 'wp-content', 'plugins');
+  const themeDir = join(cwd, 'wp-content', 'themes');
+
+  const searchDirs = [muPluginsDir, pluginsDir, themeDir];
+  const pattern = /register_rest_route\s*\(\s*['"]wp-manager\/v1\/workflows['"]/;
+
+  for (const dir of searchDirs) {
+    const files = globDir(dir);
+    for (const file of files) {
+      const filePath = join(dir, file);
+      if (file.endsWith('.php')) {
+        const content = readFileSafe(filePath);
+        if (content && pattern.test(content)) {
+          rest.found = true;
+          rest.indicators.push(`REST endpoint in ${filePath}`);
+        }
+      }
+    }
+  }
+  return rest;
+}
+
+function detectWpCronConfig(cwd) {
+  const cron = { disabled: false, alternate: false, indicators: [], recommendations: [] };
+
+  const wpConfig = readFileSafe(join(cwd, 'wp-config.php'));
+  if (!wpConfig) {
+    cron.recommendations.push('wp-config.php not found — cannot check cron config');
+    return cron;
+  }
+
+  if (/define\s*\(\s*['"]DISABLE_WP_CRON['"]\s*,\s*true\s*\)/i.test(wpConfig)) {
+    cron.disabled = true;
+    cron.indicators.push('DISABLE_WP_CRON is true — server-side cron expected');
+  }
+  if (/define\s*\(\s*['"]ALTERNATE_WP_CRON['"]\s*,\s*true\s*\)/i.test(wpConfig)) {
+    cron.alternate = true;
+    cron.indicators.push('ALTERNATE_WP_CRON is true — redirect-based cron active');
+  }
+
+  const cronPath = join(cwd, 'wp-cron.php');
+  if (existsSafe(cronPath)) {
+    cron.indicators.push('wp-cron.php found');
+  }
+
+  if (cron.disabled) {
+    cron.recommendations.push('Ensure server cron job calls wp-cron.php for scheduled triggers');
+  }
+  return cron;
+}
+
+function detectWebhookConfig() {
+  const webhooks = { configured: false, indicators: [] };
+  const raw = process.env.WP_SITES_CONFIG;
+  if (!raw) return webhooks;
+
+  let sites;
+  try { sites = JSON.parse(raw); } catch { return webhooks; }
+  if (!Array.isArray(sites)) return webhooks;
+
+  for (const site of sites) {
+    const label = site.id || site.url || 'unknown';
+    if (site.wc_webhook_secret || site.webhook_secret) {
+      webhooks.configured = true;
+      webhooks.indicators.push(`webhook secret configured for ${label}`);
+    }
+    if (site.url) {
+      webhooks.indicators.push(`site URL available for ${label} — wc-webhooks tools can be used`);
+    }
+  }
+  return webhooks;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const cwdArg = argv.find(a => a.startsWith('--cwd='));
+  const cwd = cwdArg ? resolve(cwdArg.split('=')[1]) : process.cwd();
+
+  const channels = detectActionChannelConfig();
+  const plugins = detectAutomationPlugins(cwd);
+  const rest = detectCustomRestEndpoints(cwd);
+  const cron = detectWpCronConfig(cwd);
+  const webhooks = detectWebhookConfig();
+
+  const anyConfigured = channels.configured || plugins.found || rest.found || webhooks.configured || cron.indicators.length > 0;
+
+  const report = {
+    workflow_configured: anyConfigured,
+    action_channels: channels,
+    automation_plugins: plugins,
+    custom_rest_endpoints: rest,
+    wp_cron: cron,
+    webhooks,
+    cwd,
+  };
+
+  stdout.write(JSON.stringify(report, null, 2) + '\n');
+  exit(anyConfigured ? 0 : 1);
+}
+
+main();

package/skills/wp-monitoring/SKILL.md

@@ -130,3 +130,5 @@ See `references/fleet-monitoring.md`
 - **`wp-performance`** — optimization actions based on performance trends
 - **`wp-cicd`** — CI/CD quality gates that complement monitoring (pre-deploy checks)
 - **`wp-search-console`** — add GSC search performance checks to periodic SEO monitoring
+- **`wp-alerting`** — severity-based alert routing (Slack + email) for monitoring findings
+- **`wp-analytics`** — analytics data used in performance dashboards and threshold evaluation

package/skills/wp-search-console/SKILL.md

@@ -119,3 +119,4 @@ Use the **`wp-content-strategist`** agent for SEO feedback loops and content opt
 - **`wp-social-email`** — distribute optimized content across social and email channels
 - **`wp-content`** — create and manage WordPress content informed by search analytics
 - **`wp-content-optimization`** — use GSC data as input for AI-driven content optimization and triage
+- Per correlare keyword GSC con traffico GA4, vedi `wp-analytics`

package/skills/wp-social-email/SKILL.md

@@ -150,3 +150,4 @@ Use the **`wp-distribution-manager`** agent for complex multi-channel distributi
 - **`wp-webhooks`** — trigger distribution on WordPress events (publish, update)
 - **`wp-content`** — create and manage WordPress content for distribution
 - **`wp-content-attribution`** — track content sources and attribution across channels
+- **`wp-content-workflows`** — automate distribution via workflow triggers (schedule, content lifecycle, hooks)

package/skills/wp-webhooks/SKILL.md

@@ -106,3 +106,4 @@ See `references/payload-formats.md`
 - **`wp-woocommerce`** — WooCommerce store operations (webhook source events)
 - **`wp-cicd`** — CI/CD webhooks for deployment triggers
 - **wp-social-email** — direct publishing to social/email (alternative to webhook-based distribution)
+- **`wp-content-workflows`** — workflow triggers that can fire webhook actions on WordPress events