cron-jobs

name	cron-jobs
description	Create and edit pi cron jobs in .vera/crons/. Use when the user wants to schedule tasks, create cron jobs, edit cron schedules, or automate recurring workflows and prompts.

Cron Jobs

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

Cron Definition Schema

name: my-cron              # required, unique identifier
description: What it does   # optional
schedule: "0 9 * * 1-5"    # required, cron expression (croner-compatible)
timezone: America/New_York  # optional, IANA timezone
enabled: true               # optional, default true

type: workflow              # required: "workflow" or "prompt"

# For type: workflow
workflow: my-workflow       # references .vera/workflows/*.yaml by name
inputs:                     # optional inputs passed to workflow
  key: value

# For type: prompt
prompt: "Do the thing"      # task prompt for agent
agent: my-agent             # optional, references src/agents/*.md

# Output routing
slack_channel: "#channel"   # optional, posts result summary to Slack

Creating a Cron Job

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

For guidance on choosing between workflow and prompt types, see {baseDir}/references/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 — weekdays at 9am
• */30 * * * * — every 30 minutes
• 0 0 * * * — daily at midnight
• 0 9 * * 1 — every Monday at 9am
• 0 */6 * * * — every 6 hours

Editing a Cron Job

Edit the YAML file directly at .vera/crons/<name>.yaml. After editing, run python3 {baseDir}/scripts/validate_cron.py <name> to check correctness.

Slack Notifications

Always-notify (slack_channel)

Use slack_channel when every run should post to Slack — e.g. daily reports, scheduled summaries.

slack_channel: "#team-updates"   # or "dm" for DM to the user

The first 500 chars of the agent's output are posted automatically after every run.

Conditional notify (agent-driven)

Use this pattern when a cron may have nothing to report — e.g. inbox polling, queue draining, error monitoring. Instead of slack_channel, omit it entirely and instruct the agent to post to Slack directly via curl only when there's something worth reporting:

# Do NOT set slack_channel — the agent decides whether to notify
type: prompt
prompt: |
  Check for new items and process them.

  If you handled something, notify via Slack:
  curl -s -X POST https://slack.com/api/chat.postMessage \
    -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"channel":"#channel-or-DM-id","text":"<brief summary>"}'

  If there's nothing new, finish silently — do NOT send any Slack message.

When to use which:

Pattern	Use when
slack_channel	Every run produces useful output (reports, summaries)
Agent-driven curl	Runs are often no-ops (polling, monitoring, queue checks)

Key Rules

• File must be in .vera/crons/ with .yaml extension
• name field must match the filename (without extension)
• type: workflow requires workflow field pointing to an existing workflow
• type: prompt requires prompt field
• Set enabled: false to disable without deleting
• Approval steps in workflows are automatically stripped for cron runs (unattended)
• Run results are saved to .vera/crons/runs/<name>/