design-pro-schedule-manager

Manage NV oOS Pro Schedules — create, update, delete, list, dry-run, view run history, and plan schedules from workflows. Covers all 7 Pro Schedule Manager MCP tools with usage patterns, cross-referen

SKILL.md

GitHub

NV oOS Pro Schedule Manager

The Pro Schedule Manager provides a management UI and MCP tool layer for scheduled tasks in the NV oOS ecosystem. It sits above WordPress's native cron and Action Scheduler — it does not replace them, but provides CRUD, history, dry-run testing, and workflow-to-schedule planning on top.

WP-CLI Commands

Key mcp-ai WP-CLI commands for pipeline automation. Run via terminal:

Command Use for
wp mcp-ai cron Inspect scheduled tasks, debug late/duplicate cron events
wp mcp-ai queue View background job queues, retry failed tasks
wp mcp-ai bulk Bulk operations — useful for batch schedule management
wp mcp-ai health Verify system health before enabling new schedules
wp mcp-ai log View execution logs for debugging schedule failures

When to use this skill

Trigger when ANY of the following is true:

  • Creating, updating, or deleting a scheduled task via the Pro Schedule Manager.
  • Listing active schedules to audit what's running.
  • Checking the run history of a specific schedule (success/failure logs).
  • Dry-running a schedule to validate its configuration before activation.
  • Planning schedules from a workflow — converting workflow outputs into timed tasks.
  • Debugging "my schedule didn't fire" or "fired but produced wrong results" issues at the management layer.
  • Deciding whether a task should be a Pro Schedule vs a raw Action Scheduler job.

Mental model — Pro Schedules are managed wrappers

Pro Schedules are managed entities that wrap lower-level scheduling primitives (WP-Cron events or Action Scheduler actions). Think of them as:

Pro Schedule (management record)
  └── schedule config (hook, recurrence, args, timing)
  └── run history (timestamp, status, output/logs)
  └── workflow association (optional link to source workflow)

The underlying execution still happens through WP-Cron or Action Scheduler. The Pro Schedule layer adds:

  • CRUD management — create/update/delete without writing PHP code.
  • Run history — track every execution, status, and output.
  • Dry-run — test without side effects.
  • Workflow integration — plan schedules from workflow outputs.

Available Tools (7)

1. create_pro_schedule

Create a new managed schedule.

{
  "name": "create_pro_schedule",
  "arguments": {
    "title": "Daily Product Sync",
    "hook": "myplugin/daily_product_sync",
    "recurrence": "daily",
    "args": { "batch_size": 50 },
    "first_run": "2026-08-12T04:00:00Z",
    "enabled": true
  }
}

Key parameters:

  • title — human-readable name displayed in the admin UI.
  • hook — the WordPress action hook that fires. Must match a registered callback.
  • recurrence — interval: hourly, twicedaily, daily, weekly, or a custom cron schedule slug.
  • args — optional arguments passed to the hook callback (JSON-serializable).
  • first_run — ISO 8601 timestamp for the first execution.
  • enabled — whether the schedule is active immediately.

v1.1.93 semantics (PR #6856) — cron re-arm discipline:

  • Create: one-shot schedules keep the documented 60-second default first run; recurring schedules start one full interval from creation (a daily schedule fires ~24h later, not ~60s later).
  • Update (metadata-only saves do NOT re-arm): update_schedule() touches the WP cron event only when the timing actually changed (explicit first_run, interval change, or re-enabling). Saving a title/args tweak leaves the existing event and cadence untouched, and a consumed one-shot schedule is never re-armed by a save (pre-1.1.93, every save un-scheduled and re-scheduled the stored — now-past — timestamp, so WP cron fired the overdue event immediately on the next spawn).
  • Re-enable: schedules the next run one interval out; use the Run action for an immediate execution.
  • UI (PR #6855): the edit modal only sends workflow_steps for workflow-type schedules (the document-wide selector previously always matched the hidden create form, so every edit was rejected server-side).

2. update_pro_schedule

Modify an existing schedule. All fields are optional — only provided fields change.

{
  "name": "update_pro_schedule",
  "arguments": {
    "schedule_id": 42,
    "title": "Product Sync (increased batch)",
    "args": { "batch_size": 100 },
    "enabled": true
  }
}

Use this to:

  • Toggle a schedule on/off without deleting it (preserves history).
  • Adjust arguments (e.g., batch size, timeout).
  • Rename for clarity.
  • Change recurrence timing.
  • Edit workflow steps in place — workflow_steps replaces the whole ordered tool chain on workflow-type schedules, so a step's arguments can be corrected without recreating the schedule (rejected with invalid_schedule_type on non-workflow schedules, invalid_workflow_steps when no valid step survives sanitisation):
{
  "name": "update_pro_schedule",
  "arguments": {
    "schedule_id": "abc123…",
    "workflow_steps": [
      {
        "tool_slug": "search_upwork_jobs",
        "arguments": { "query": "wordpress developer", "sort": "recency", "limit": 20 },
        "label": "Search for new matching jobs"
      }
    ]
  }
}

3. delete_pro_schedule

Permanently remove a schedule and its run history.

{
  "name": "delete_pro_schedule",
  "arguments": {
    "schedule_id": 42
  }
}

⚠️ Warning: This deletes the management record AND all run history. If you only want to pause execution, use update_pro_schedule with enabled: false instead.

Before deleting, consider:

  • Export run history if needed for auditing.
  • Verify no workflows depend on this schedule.
  • Check that the underlying cron/Action Scheduler event is also cleaned up.

4. list_pro_schedules

List all managed schedules with optional filtering.

{
  "name": "list_pro_schedules",
  "arguments": {
    "status": "active",
    "search": "sync",
    "per_page": 20,
    "page": 1
  }
}

Filter options:

  • status — active, inactive, or all.
  • search — free-text search across title and hook.
  • per_page / page — pagination.

Use this to:

  • Audit all active schedules across the site.
  • Find schedules by hook name or keyword.
  • Check what's enabled vs disabled.

5. get_schedule_run_history

Retrieve the execution history for a specific schedule.

{
  "name": "get_schedule_run_history",
  "arguments": {
    "schedule_id": 42,
    "per_page": 25,
    "page": 1
  }
}

Returns for each run:

  • Timestamp (scheduled and actual execution time).
  • Status: success, failed, running, timeout.
  • Output/logs from the callback.
  • Duration (execution time in seconds).

Use this to:

  • Debug failures — find the exact error from the callback output.
  • Identify performance issues — runs that take unusually long.
  • Audit execution patterns — is a "daily" schedule actually firing daily?
  • Detect silent failures — callbacks that return without error but produce wrong results.

6. dry_run_pro_schedule

Execute the schedule's callback once, immediately, without persisting side effects (where supported) or recording it as an official run.

{
  "name": "dry_run_pro_schedule",
  "arguments": {
    "schedule_id": 42
  }
}

Use this to:

  • Validate a new schedule before enabling it.
  • Test argument changes without affecting production data.
  • Reproduce a failure from the run history in a controlled way.
  • Verify that recent code changes don't break an existing schedule.

Note: Dry-run behavior depends on the callback implementation. Callbacks that use wp_get_environment_type() or similar checks can gate side effects during dry-runs. The Pro Schedule Manager sets an environment flag that callbacks can inspect.

7. plan_schedules_from_workflow

Convert a workflow's output into one or more scheduled tasks. This is the bridge between the workflow engine and the schedule manager.

{
  "name": "plan_schedules_from_workflow",
  "arguments": {
    "workflow_id": 7,
    "schedule_pattern": "daily",
    "first_run_offset_hours": 2
  }
}

Key parameters:

  • workflow_id — the source workflow to derive schedules from.
  • schedule_pattern — recurrence pattern for generated schedules.
  • first_run_offset_hours — delay before the first run.

Use this when:

  • A content workflow produces tasks that need to run on a schedule.
  • You want to automate schedule creation from workflow templates.
  • A multi-step workflow needs staggered execution timing.

The tool analyzes the workflow structure and produces one or more schedule records, each mapped to a workflow step that benefits from scheduled execution.

Common workflows

Creating a new scheduled task

1. Define the callback hook (register via add_action in your plugin).
2. Use create_pro_schedule to wrap it in a managed schedule.
3. Use dry_run_pro_schedule to validate.
4. Check get_schedule_run_history after the first real run.

Debugging a failed schedule

1. Use list_pro_schedules to find the schedule.
2. Use get_schedule_run_history to see the failure details.
3. Use dry_run_pro_schedule to reproduce the issue.
4. Fix the callback or configuration.
5. Use update_pro_schedule if you need to adjust args/timing.
6. Check run history again after the next execution.

Pausing vs deleting

PAUSE:    update_pro_schedule(schedule_id, enabled: false)
RESUME:   update_pro_schedule(schedule_id, enabled: true)
DELETE:   delete_pro_schedule(schedule_id)
          — also clean up the underlying cron/Action Scheduler event

Always prefer pausing over deleting when:

  • You may need the schedule again.
  • You want to preserve run history.
  • Other workflows or schedules reference this one.

Converting a raw Action Scheduler job to a managed schedule

1. Identify the existing Action Scheduler hook.
2. Use create_pro_schedule with the same hook and args.
3. This adds management UI, run history, and dry-run support.
4. The underlying Action Scheduler event continues to run as before.

Integration with wp-plugin-cron and wp-action-scheduler

The Pro Schedule Manager does NOT replace these. It delegates to them:

Layer What it does
Pro Schedule Manager (this skill) Manage, audit, dry-run, plan schedules.
Action Scheduler (wp-action-scheduler) Queue semantics, status tracking, retries, admin UI. Backend for most Pro Schedules.
WP-Cron (wp-plugin-cron) Simple periodic events without queue overhead. Used for lightweight Pro Schedules.

When creating a Pro Schedule, the manager selects the appropriate backend based on the schedule's characteristics (recurrence, expected load, need for retries).

Cross-reference flow:

  • If the question is about scheduling mechanics (recurrence, cron intervals, multisite, idempotency): → wp-plugin-cron
  • If the question is about queue behavior (status tracking, retries, batch size, WP-CLI debugging): → wp-action-scheduler
  • If the question is about managing schedules (CRUD, history, dry-run, workflow planning): → this skill

Critical rules

  • Prefer pausing (enabled: false) over deleting — preserves history and allows resumption.
  • Always dry-run new or modified schedules before enabling to catch config errors.
  • Check run history after the first real execution — don't assume it worked.
  • Keep args JSON-serializable and small — same constraint as Action Scheduler.
  • The hook must be registered before the schedule fires — otherwise the event is silently ignored.
  • Deleting a Pro Schedule may not clean up the underlying cron/Action Scheduler event — verify and clean up manually if needed.
  • Workflow-planned schedules are derived, not linked — updating the source workflow does not auto-update derived schedules.

Common mistakes

// WRONG — deleting a schedule without checking if others depend on it
{ "name": "delete_pro_schedule", "arguments": { "schedule_id": 7 } }

// RIGHT — pause first, audit dependencies, then delete
{ "name": "update_pro_schedule", "arguments": { "schedule_id": 7, "enabled": false } }
// ... audit ...
{ "name": "delete_pro_schedule", "arguments": { "schedule_id": 7 } }

// WRONG — enabling a schedule without dry-running after argument changes
{ "name": "update_pro_schedule", "arguments": { "schedule_id": 42, "args": { "mode": "aggressive" }, "enabled": true } }

// RIGHT — dry-run first
{ "name": "dry_run_pro_schedule", "arguments": { "schedule_id": 42 } }
// verify output...
{ "name": "update_pro_schedule", "arguments": { "schedule_id": 42, "enabled": true } }

// WRONG — assuming the schedule fired at the exact configured time
// Check get_schedule_run_history for the actual execution timestamp.

// WRONG — creating a schedule with a hook that isn't registered yet
// The event will fire but the callback won't run.
// Register the callback first, then create the schedule.

Cross-references

  • Run wp-plugin-cron for scheduling mechanics: cron intervals, multisite, idempotent callbacks, wp_next_scheduled guards.
  • Run wp-action-scheduler for queue semantics: status tracking, retries, batch processing, WP-CLI commands.
  • Run wp-plugin-lifecycle for activation/deactivation scheduling patterns.
  • Run wp-security-audit on schedule callbacks — they run with no current user, so capability checks don't work.
  • Run design-pro-workflow-builder to design workflows that produce scheduled tasks via plan_schedules_from_workflow.
  • Run design-crm to schedule recurring CRM tasks — pipeline reviews, lead scoring, follow-up reminders.
  • Run design-campaign-orchestration to schedule recurring campaign content publication and monthly reports.

What this skill does NOT cover

  • Writing the actual hook callbacks — that's your plugin code.
  • WP-Cron or Action Scheduler internals — covered by wp-plugin-cron and wp-action-scheduler.
  • Workflow engine design — this skill only covers the plan_schedules_from_workflow bridge.
  • Server-level cron daemon configuration.

References