/scheduling

name: scheduling
description: Set up recurring or scheduled work — anything the user wants run on a schedule, repeatedly, or at a future time ("every morning", "each weekday at 9am", "daily digest", "weekly report", "remind me", "run this on a cron"). Teaches how to author a durable Vexa Scheduler routine that survives restarts. Use this instead of any OS cron job, system timer, or session-only reminder.

scheduling — durable recurring work

When the user asks for ANYTHING that should run on a schedule or repeat over time (a daily digest, a weekly report, a periodic check, a future reminder), you create a **routine file** in this workspace. The agent-api reconciler compiles it into a **durable Vexa Scheduler job** that survives restarts and process death — it is the only correct mechanism for scheduled work here.

**NEVER** do any of these for scheduled work:

• create an OS cron job (`crontab`, `/etc/cron.*`)
• create a systemd timer or any other system timer
• start a shell background loop / `sleep` loop
• leave a "session-only" reminder (your turn ends and it is gone)

All of those die on restart or when your turn ends. Only a routine file is durable.

How to create a routine

Write one file at **`routines/<name>.md`** (`<name>` is a short slug; the filename stem becomes the routine name). It is a normal governed workspace file — just write it; you do not run git.

The file is **YAML frontmatter** plus an **optional markdown body**:

| field | required | meaning | |-----------|-----------------|----------------------------------------------------------------| | `enabled` | no (default `true`) | `false` cancels the job but keeps the file for later re-enable | | `cron` | yes (when enabled) | a standard **5-field** cron expression (min hour dom mon dow) | | `prompt` | yes (when enabled) | the instruction sent to the agent on each run (non-empty) |

The optional markdown body below the second `---` is appended to `prompt` as extra context for each run.

cron format

Five fields, space-separated: `minute hour day-of-month month day-of-week`. Day-of-week is `0`–`7` (0 and 7 are both Sunday); `mon`/`tue`/… and `jan`/`feb`/… names are accepted, as are ranges (`mon-fri`), lists (`1,15`), and steps (`*/15`).

Examples:

• `0 8 * * *` — every day at 08:00
• `30 9 * * mon-fri` — 09:30 on weekdays
• `0 17 * * fri` — 17:00 every Friday
• `0 * * * *` — top of every hour

Worked example

For "every weekday at 9am, give me a digest of yesterday's meetings", create `routines/morning-digest.md`:

---
enabled: true
cron: "30 9 * * mon-fri"
prompt: "Compile a short digest of yesterday's meetings and open tasks from kg/entities/, and summarize what needs attention today."
---

Keep it under ~10 bullet points. Group by person/company. Link entities with [[wikilinks]].

That's it. The reconciler (running in agent-api, scanning every workspace on an interval) picks the file up, validates the cron + prompt, and schedules a durable Vexa Scheduler job. Editing the file updates the job; setting `enabled: false` (or deleting the file) cancels it.

Validation notes

• An **enabled** routine MUST have a valid 5-field `cron` and a non-empty `prompt`,

or the reconciler logs a warning and skips it (no job is created). Double-check the cron has exactly five fields.

• A **disabled** routine (`enabled: false`) needs no cron/prompt — it just cancels

any existing job for that name.

• Confirm to the user what you scheduled (name + cron + what it does).