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.agents/skills/design-pro-schedule-manager/SKILL.md
GitHubNV 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 (explicitfirst_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_stepsforworkflow-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_stepsreplaces the whole ordered tool chain onworkflow-type schedules, so a step's arguments can be corrected without recreating the schedule (rejected withinvalid_schedule_typeon non-workflow schedules,invalid_workflow_stepswhen 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, orall.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-cronfor scheduling mechanics: cron intervals, multisite, idempotent callbacks,wp_next_scheduledguards. - Run
wp-action-schedulerfor queue semantics: status tracking, retries, batch processing, WP-CLI commands. - Run
wp-plugin-lifecyclefor activation/deactivation scheduling patterns. - Run
wp-security-auditon schedule callbacks — they run with no current user, so capability checks don't work. - Run
design-pro-workflow-builderto design workflows that produce scheduled tasks viaplan_schedules_from_workflow. - Run
design-crmto schedule recurring CRM tasks — pipeline reviews, lead scoring, follow-up reminders. - Run
design-campaign-orchestrationto 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-cronandwp-action-scheduler. - Workflow engine design — this skill only covers the
plan_schedules_from_workflowbridge. - 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