plungeai-scheduling

Cron-schedule PlungeAI workflows, agent queries, pre-built agent cards, and condition-watching heartbeats via plungeai_schedule, with full run history and retries. Use when the user wants something to run daily/hourly/on a cron, a recurring report, a standing watchdog, or asks about job status, retries, or why a scheduled run didn't fire. For the workflow or mission being scheduled use plungeai-workflows / plungeai-missions; for a list-to-completion campaign's own cadence use plungeai-campaigns.

Download zip (opens in a new tab) · View raw SKILL.md (opens in a new tab)

The scheduler runs platform work unattended on cron expressions: a saved workflow every morning, an agent query hourly, a pre-built agent card nightly, or a condition-watching heartbeat. Every job has first-class run history — nothing here is fire-and-forget.

Prerequisites

• A self-service ozk_ API key from Dashboard → One API → Keys (https://dashboard.plungeai.com (opens in a new tab)), or an MCP client connected to https://mcp.plungeai.com/v1.
• The thing being scheduled must already exist and be discoverable: plungeai_list_workflows for a saved workflow, plungeai_list_agents {search: "…"} for an agent/check_agent id — never guess an id, it is fence-checked at create time.

Creating a job — plungeai_schedule

Action-routed, one tool:

plungeai_schedule {action: "create", name: "Daily market brief",
  job_type: "workflow",            # agent | query | workflow | heartbeat
  target: "<workflow id>", schedule: "0 7 * * *"}                # 07:00 UTC daily

plungeai_schedule {action: "list"}
plungeai_schedule {action: "run_now", job_id: "…"}   # always do this right after create
plungeai_schedule {action: "runs", job_id: "…"}      # Execution ID column → plungeai_get_result
plungeai_schedule {action: "stats"}

Four create shapes — workflow (target = a workflow id you own), agent (target = an agent id + parameters: {prompt}), query (target = {agent, query} JSON), and heartbeat (check_agent + condition_prompt, ticks and only acts when the condition is met — of the five notify_channel values, telegram/discord/slack/email all deliver through the normal per-channel adapters; whatsapp is a known gap, prefer trigger_workflow or another channel for it). mission_ref on create schedules a pre-built agent card directly, resolved live at fire time.

Standard 5-field cron, UTC, 1-minute minimum granularity, ±5s accuracy. Use the rolling date tokens ({yesterday}, {week_start}, {last_week_end}, …) instead of baking concrete dates into scheduled YAML — full table in references/scheduling.md.

Verify every job you create

run_now fires immediately and reports the REAL outcome plus a resolvable execution id — always call it right after create to prove the job works end-to-end, rather than waiting for the first natural fire.

Gotchas

• Workflow jobs run by reference — edit the workflow in Studio and the next scheduled run uses the latest saved version automatically; there is no "update the schedule to change the logic".
• Delete is soft — history stays readable, but a deleted job refuses run_now/update/pause/resume; there is no undelete.
• Failed runs auto-retry (3 attempts, 5 minutes apart) and re-fire the FULL job — schedule only idempotent work, or make the workflow itself idempotent.
• A scheduler run id (exec_..., underscore) is not resolvable by plungeai_get_workflow_status / plungeai_get_result directly — go through action: "runs" and take its Execution ID column first.
• Scheduled user workflows keep the full per-user memory lifecycle (recall + write) — only system jobs and heartbeat checks are memory-free.
• @once fires once then soft-deletes; runAgain (a workflow's own last step) self-schedules the next @once run without any cron expression at all — the mechanism behind a campaign that "just keeps going."

Related skills

• plungeai-workflows — author the workflow a job runs.
• plungeai-missions — author the mission a mission_ref job runs.
• plungeai-campaigns — a list-to-completion ledger driven by cron or runAgain.
• plungeai-memory — the recall/write lifecycle of a scheduled run.
• plungeai-results-traces — read a job run's status, output, and trace once you have its Execution ID.

Reference

• references/scheduling.md — full action table, cron/date-token reference, heartbeat semantics, retries/history, troubleshooting, and the plungeai_schedule MCP tool contract.

Reference pages