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).