cron-jobs

name	cron-jobs
description	Create and edit cron job definitions in .agent/crons/. Use when the user wants to schedule recurring workflow or prompt runs, adjust cron schedules, or validate cron YAML.

Cron Jobs

Create and edit cron job definitions in .agent/crons/*.yaml.

Cron Definition Schema

name: my-cron
description: What it does
schedule: "0 9 * * 1-5"
timezone: America/Los_Angeles
enabled: true

type: workflow

# For type: workflow
workflow: my-workflow
inputs:
  key: value

# For type: prompt
prompt: "Do the thing"
agent: main

# Optional delivery routing
slack_channel: "#channel"

Creating a Cron Job

1. Run python3 {baseDir}/scripts/init_cron.py <name> to scaffold a new YAML file in .agent/crons/.
2. Edit the generated file to set schedule, type, and its target configuration.
3. Run python3 {baseDir}/scripts/validate_cron.py <name-or-path> to validate the definition.

For guidance on choosing between workflow and prompt jobs, read cron-types.md.

Cron Expression Reference

┌───────── minute (0-59)
│ ┌─────── hour (0-23)
│ │ ┌───── day of month (1-31)
│ │ │ ┌─── month (1-12)
│ │ │ │ ┌─ day of week (0-6, Sun=0)
│ │ │ │ │
* * * * *

Common patterns:

• 0 9 * * 1-5 for weekdays at 9am
• */30 * * * * for every 30 minutes
• 0 0 * * * for daily at midnight
• 0 9 * * 1 for every Monday at 9am
• 0 */6 * * * for every 6 hours

Editing a Cron Job

Edit the YAML file directly at .agent/crons/<name>.yaml. After editing, run the validator again.

Slack Notifications

Always Notify

Use slack_channel when every run should post a summary.

slack_channel: "#team-updates"

Conditional Notify

For polling or monitoring jobs that often have nothing to report, omit slack_channel and have the prompt post to Slack only when there is something worth sending.

type: prompt
prompt: |
  Check for new items and process them.

  If you handled something, post a short summary to Slack.
  If there is nothing new, finish silently.

Key Rules

• file must live in .agent/crons/ and use .yaml
• name must match the filename
• type: workflow requires workflow
• type: prompt requires prompt
• use enabled: false to disable a cron without deleting it
• if the cron targets a workflow, make sure that workflow exists in .agent/workflows/