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

• NV oOS Pro Schedule Manager admin page: /wp-admin/admin.php?page=nvoos-pro-schedule-manager
• WordPress Cron Handbook: developer.wordpress.org/plugins/cron/
• Action Scheduler: actionscheduler.org