claude-plugin-wordpress-manager 2.4.0 → 2.9.0

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

@@ -0,0 +1,131 @@
+# Content Lifecycle Hooks
+
+## Post Status Transitions
+
+WordPress fires `transition_post_status` on every status change:
+
+| Transition | From → To | Common Use |
+|------------|-----------|------------|
+| Publish | `draft` → `publish` | Notify team of new content |
+| Schedule | `draft` → `future` | Confirm scheduling |
+| Unpublish | `publish` → `draft` | Alert editors |
+| Trash | `publish` → `trash` | Audit log entry |
+| Restore | `trash` → `draft` | Notify original author |
+| Pending review | `draft` → `pending` | Notify reviewers |
+
+### Hook Signatures
+
+```php
+// Generic transition hook
+add_action('transition_post_status', function ($new, $old, $post) {
+    if ($new === 'publish' && $old !== 'publish') {
+        // First-time publish — trigger workflow
+    }
+}, 10, 3);
+
+// Specific transition hooks (preferred for performance)
+add_action('draft_to_publish', function ($post) {
+    // Fires only on draft → publish transition
+});
+
+add_action('pending_to_publish', function ($post) {
+    // Fires on pending → publish (after review approval)
+});
+```
+
+### Trigger Config Example
+
+```json
+{
+  "type": "content_lifecycle",
+  "event": "draft_to_publish",
+  "post_type": "post",
+  "actions": [
+    { "channel": "slack", "message": ":newspaper: New post published: *{{post_title}}* by {{post_author}}" }
+  ]
+}
+```
+
+## Custom Post Type Support
+
+The same transition hooks work for any registered post type:
+
+| Post Type | Slug | Example Trigger |
+|-----------|------|-----------------|
+| WooCommerce Product | `product` | Notify when new product goes live |
+| Portfolio | `portfolio` | Share on social when portfolio item published |
+| Event | `event` | Send reminder email on event publish |
+| Landing Page | `page` | Alert marketing team on page publish |
+
+Filter by post type in trigger config:
+
+```json
+{
+  "event": "draft_to_publish",
+  "post_type": ["post", "product"],
+  "condition": "post_type IN (post, product)"
+}
+```
+
+## Taxonomy and Term Changes
+
+| Hook | Fires When | Parameters |
+|------|------------|------------|
+| `set_object_terms` | Terms assigned to a post | `$object_id`, `$terms`, `$tt_ids`, `$taxonomy` |
+| `created_term` | New term created | `$term_id`, `$tt_id`, `$taxonomy` |
+| `edited_term` | Term updated | `$term_id`, `$tt_id`, `$taxonomy` |
+| `delete_term` | Term deleted | `$term_id`, `$tt_id`, `$taxonomy`, `$deleted_term` |
+
+Example: notify when a post is tagged with "featured":
+
+```json
+{
+  "type": "content_lifecycle",
+  "event": "set_object_terms",
+  "condition": "taxonomy == 'post_tag' AND terms CONTAINS 'featured'",
+  "actions": [
+    { "channel": "slack", "message": "Post tagged as featured: {{post_title}}" }
+  ]
+}
+```
+
+## Media Upload Events
+
+| Hook | Fires When | Parameters |
+|------|------------|------------|
+| `add_attachment` | New media uploaded | `$attachment_id` |
+| `edit_attachment` | Attachment metadata updated | `$attachment_id` |
+| `delete_attachment` | Media file deleted | `$attachment_id` |
+| `wp_handle_upload` | File upload processed | `$upload` array |
+
+Example: log large file uploads:
+
+```json
+{
+  "type": "content_lifecycle",
+  "event": "add_attachment",
+  "condition": "filesize > 5MB",
+  "actions": [
+    { "channel": "webhook", "url": "{{audit_webhook_url}}", "payload": { "event": "large_upload", "file": "{{filename}}", "size": "{{filesize}}" } }
+  ]
+}
+```
+
+## Example: Notify Slack When Blog Post Published
+
+```json
+{
+  "name": "Blog Post Published Notification",
+  "type": "content_lifecycle",
+  "event": "draft_to_publish",
+  "post_type": "post",
+  "actions": [
+    {
+      "channel": "slack",
+      "message": ":mega: *New blog post published!*\n*Title:* {{post_title}}\n*Author:* {{post_author}}\n*URL:* {{post_url}}",
+      "channel_override": "#content-updates"
+    }
+  ],
+  "status": "active"
+}
+```

package/skills/wp-content-workflows/references/multi-channel-actions.md

@@ -0,0 +1,151 @@
+# Multi-Channel Action Configuration
+
+## Action Channel Types
+
+| Channel | Identifier | Required Config | Tool |
+|---------|-----------|-----------------|------|
+| Slack (Webhook) | `slack` | `slack_webhook_url` in WP_SITES_CONFIG | `slack_send_webhook` |
+| Slack (Bot) | `slack_bot` | `slack_bot_token` + `slack_channel` | `slack_send_message` |
+| Email (SendGrid) | `email` | `sendgrid_api_key` in WP_SITES_CONFIG | `sg_send_email` |
+| Webhook (HTTP) | `webhook` | Target URL in action config | Custom HTTP POST |
+| Mailchimp | `mailchimp` | `mailchimp_api_key` in WP_SITES_CONFIG | Mailchimp API |
+
+## Template Variables
+
+Common variables available in all action templates:
+
+| Variable | Description | Example Value |
+|----------|-------------|---------------|
+| `{{site_url}}` | WordPress site URL | `https://example.com` |
+| `{{site_name}}` | Site title | `My WordPress Site` |
+| `{{timestamp}}` | Event timestamp (ISO 8601) | `2026-03-01T14:30:00Z` |
+| `{{trigger_name}}` | Name of the firing trigger | `Blog Post Published` |
+| `{{post_title}}` | Post title (content events) | `Hello World` |
+| `{{post_url}}` | Post permalink | `https://example.com/hello-world` |
+| `{{post_author}}` | Post author display name | `John Doe` |
+| `{{post_type}}` | Post type slug | `post` |
+| `{{user_name}}` | User display name | `Jane Smith` |
+| `{{user_email}}` | User email address | `jane@example.com` |
+| `{{order_id}}` | WooCommerce order ID | `1234` |
+| `{{order_total}}` | Order total with currency | `$99.00` |
+| `{{order_status}}` | Current order status | `completed` |
+
+## Channel-Specific Formatting
+
+### Slack (Block Kit)
+
+```json
+{
+  "channel": "slack",
+  "format": "block_kit",
+  "blocks": [
+    {
+      "type": "header",
+      "text": { "type": "plain_text", "text": "{{trigger_name}}", "emoji": true }
+    },
+    {
+      "type": "section",
+      "fields": [
+        { "type": "mrkdwn", "text": "*Post:*\n{{post_title}}" },
+        { "type": "mrkdwn", "text": "*Author:*\n{{post_author}}" }
+      ]
+    }
+  ],
+  "fallback_text": "{{trigger_name}}: {{post_title}} by {{post_author}}"
+}
+```
+
+### Email (HTML)
+
+```json
+{
+  "channel": "email",
+  "to": "team@example.com",
+  "subject": "[{{site_name}}] {{trigger_name}}",
+  "format": "html",
+  "body": "<h2>{{trigger_name}}</h2><p><strong>{{post_title}}</strong> by {{post_author}}</p><p><a href='{{post_url}}'>View Post</a></p>"
+}
+```
+
+### Webhook (JSON)
+
+```json
+{
+  "channel": "webhook",
+  "url": "https://api.example.com/events",
+  "method": "POST",
+  "headers": { "Content-Type": "application/json", "X-Webhook-Secret": "{{webhook_secret}}" },
+  "payload": {
+    "event": "{{trigger_name}}",
+    "post": { "title": "{{post_title}}", "url": "{{post_url}}", "author": "{{post_author}}" },
+    "timestamp": "{{timestamp}}"
+  }
+}
+```
+
+## Rate Limiting Per Channel
+
+| Channel | Default Limit | Burst | Cooldown |
+|---------|---------------|-------|----------|
+| Slack (Webhook) | 1 msg/sec | 5 msg burst | 1 second |
+| Slack (Bot) | 1 msg/sec per channel | Tier 2 | Varies |
+| Email (SendGrid) | 100 msg/sec (plan-dependent) | — | None |
+| Webhook | 10 req/sec | 20 burst | 100ms |
+
+**Rate limit strategy:**
+- Queue actions when rate exceeded
+- Batch low-priority events into digest messages
+- Critical events bypass rate limits (sent immediately)
+- Log rate limit hits for trigger tuning
+
+## Multi-Channel Action Mapping
+
+A single trigger can fire multiple actions across channels:
+
+```json
+{
+  "actions": [
+    { "channel": "slack", "priority": "high" },
+    { "channel": "email", "priority": "high" },
+    { "channel": "webhook", "priority": "normal" }
+  ]
+}
+```
+
+**Priority levels:**
+- `critical` — all channels fire immediately, bypass rate limits
+- `high` — all channels fire immediately, respect rate limits
+- `normal` — queued, batched if necessary
+- `low` — batched into digest (hourly or daily)
+
+## Example: Critical Order — Slack + Email + Webhook
+
+```json
+{
+  "name": "Critical Order Alert",
+  "type": "action_hook",
+  "event": "woocommerce_payment_complete",
+  "condition": "order_total > 500",
+  "actions": [
+    {
+      "channel": "slack",
+      "priority": "critical",
+      "message": ":moneybag: *High-value order!* #{{order_id}} — {{order_total}}"
+    },
+    {
+      "channel": "email",
+      "priority": "critical",
+      "to": "sales@example.com",
+      "subject": "High-value order #{{order_id}} — {{order_total}}",
+      "template": "high_value_order"
+    },
+    {
+      "channel": "webhook",
+      "priority": "critical",
+      "url": "https://crm.example.com/api/orders",
+      "payload": { "order_id": "{{order_id}}", "total": "{{order_total}}", "event": "high_value" }
+    }
+  ],
+  "status": "active"
+}
+```

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"
+}
+```