Create Workflow

Generate workflow automation files that schedule jazz agents to run recurring tasks.

When to Use

User wants to automate a recurring task using a Jazz Agent
User asks to "create a workflow" or "schedule an agent"
User says "I want to check X every Y" (e.g., "check emails every hour")
User wants unattended agent execution

Note: If the user wants to schedule a simple shell script or system command without using a Jazz Agent, use the create-system-routine skill instead.

Gathering Information (Questionnaire)

Do not create the workflow file until you have enough information. If the user's prompt is vague (e.g. "create a workflow", "I want to automate emails") or missing any of the items below, guide them through a short questionnaire instead of guessing.

You have enough info when you know:

Task: What should the agent do? (Concrete, not vague.)
Schedule: When should it run? (So you can convert to cron.)
Catch-up: Should missed runs execute on startup? (If not specified, ask or choose a sensible default.)
Auto-approve: What risk level? (read-only / low-risk / high-risk / false—default to conservative.)
Skills: Which skills does the agent need? (e.g. email, calendar, deep-research.)
Instructions: Clear, safety-first prompt with explicit criteria and "when in doubt" rules.
Location: Where to save? (Local ./workflows/<name>/ or global ~/.jazz/workflows/<name>/.)

How to run the questionnaire:

Ask one or a few questions at a time; don't dump a long list.
Use the user's words to refine (e.g. "You said 'clean my inbox'—should that be archive only, or also delete? How old is 'old'?").
After each answer, confirm what you have and ask only what's still missing.
Once you have all seven items above, proceed to create the WORKFLOW.md.

Workflow

Understand the task: What should the agent do? When should it run? If unclear, ask.
Determine schedule: Convert user intent to cron format; if not stated, ask when they want it to run.
Decide catch-up behavior: Should missed runs execute on startup? Ask if not specified.
Choose auto-approve policy: Based on risk level of operations; default to conservative.
Identify required skills: What skills will the agent need?
Write clear instructions: Safety-first prompt with explicit guidelines.
Create WORKFLOW.md: Place in appropriate directory only after you have enough info from above.

Workflow File Structure

---
name: workflow-name
description: Brief one-line summary
schedule: "0 8 * * *"
autoApprove: read-only
catchUpOnStartup: true
maxCatchUpAge: 43200
agent: default
skills:
  - skill-name
---

# Workflow Title

[Clear instructions for the agent, including safety guidelines]

Frontmatter Fields

| Field | Required | Description | Example | | ------------------ | -------- | ----------------------------------------------- | ----------------------------------------------------- | | name | ✓ | Kebab-case identifier | email-cleanup | | description | ✓ | One-line summary | Clean up old newsletters | | schedule | | Cron expression | 0 * * * * (hourly) | | agent | | Agent to use (optional, will prompt if omitted) | research-agent | | autoApprove | | Auto-approval policy | read-only, low-risk, high-risk, true, false | | skills | | Skills to load | ["email", "calendar"] | | catchUpOnStartup | | Run missed workflows on startup | true | | maxCatchUpAge | | Max age (seconds) for catch-up runs | 43200 (12 hours) |

Cron Schedule Guide

Ask user when they want it to run, then convert to cron:

| User Intent | Cron Expression | Description | | -------------------- | --------------- | ------------------------- | | Every hour | 0 * * * * | At minute 0 of every hour | | Every morning at 8am | 0 8 * * * | Daily at 8:00 AM | | Every 15 minutes | */15 * * * * | Every 15 minutes | | Weekdays at 9am | 0 9 * * 1-5 | Mon-Fri at 9:00 AM | | Every Monday at 9am | 0 9 * * 1 | Weekly on Monday | | First of month | 0 0 1 * * | Monthly at midnight |

Cron format: minute hour day-of-month month day-of-week

Auto-Approve Policy

Choose based on what tools the workflow will use:

| Policy | When to Use | Example Workflows | | ----------- | ------------------------------------- | ------------------------------------------------ | | read-only | Only reads/searches, no modifications | Weather check, news digest, monitoring | | low-risk | Modifies data but reversible | Email archiving, labeling, calendar events | | high-risk | Deletes, sends, executes commands | Email cleanup with deletion, automated responses | | false | Always ask for approval | Testing, development |

Default to the most restrictive policy that allows the workflow to function.

Safety Guidelines

Always include safety rules in the workflow prompt:

**Safety Rules:**
- When in doubt, DO NOTHING
- Only perform actions you're 100% confident about
- Leave uncertain items for manual review
- [Add task-specific safety rules]

For workflows that modify or delete:

Emphasize conservative behavior
Specify exact criteria (e.g., "only archive newsletters older than 2 weeks")
Add "if unsure, skip it" instructions

File Location

Ask user where they want the workflow (or choose based on context):

| Location | Use Case | Path | | ---------- | ----------------------------- | -------------------------------------- | | Local | Project-specific automation | ./workflows/<name>/WORKFLOW.md | | Global | User-wide personal automation | ~/.jazz/workflows/<name>/WORKFLOW.md |

Built-in workflows are shipped with Jazz and shouldn't be modified.

Complete Example

User request: "I want to clean up my email inbox every hour, archiving old newsletters"

Questions to ask:

✓ What counts as "old"? (2 weeks)
✓ Should it only archive or also delete? (archive only)
✓ Any specific senders to target? (newsletters, promotional)
✓ Where to save it? (global: ~/.jazz/workflows/)

Generated workflow:

---
name: email-cleanup
description: Archive old newsletters and promotional emails
schedule: "0 * * * *"
autoApprove: low-risk
skills:
  - email
---

# Email Cleanup

Review my inbox from the last hour and archive emails matching these criteria:

**Criteria for archiving:**
- Newsletters older than 2 weeks
- Promotional emails older than 3 days
- GitHub notifications already read

**Safety Rules:**
- When in doubt, DO NOTHING
- Only archive emails you're 100% confident match the criteria
- If an email might be important, leave it in inbox
- Never delete, only archive

**Output:**
Log count of archived emails to console.

Skills Integration

If the workflow needs specific capabilities, suggest relevant skills:

| Task Type | Skills to Include | | ------------------- | ----------------------------- | | Email management | email | | Calendar tasks | calendar | | Research/analysis | deep-research | | Code/git operations | (none needed, built-in tools) | | Web searches | (none needed, built-in) |

Include skills in frontmatter:

skills:
  - email
  - calendar

And reference in prompt:

Use the `email` skill to access my inbox efficiently.

After Creation

Tell the user what to do next:

# Test the workflow manually first
jazz workflow run <name>

# Once confident, schedule it
jazz workflow schedule <name>

# Monitor logs
tail -f ~/.jazz/logs/<name>.log

# View run history
jazz workflow history <name>

Common Workflow Patterns

Daily Research Digest

---
name: tech-digest
description: Daily AI and tech news digest
schedule: "0 8 * * *"
autoApprove: true
skills:
  - deep-research
---

# Daily Tech Digest

Research the most important AI and tech news from the last 24 hours.

**Sources:** Twitter, Reddit, Hacker News, Hugging Face, TechCrunch

**Output:** Save summary to `~/digests/YYYY/Month/DD.md`

**Format:** Brief bullet points with source links

Morning Briefing

---
name: morning-briefing
description: Weather, calendar, and news brief
schedule: "0 7 * * 1-5"
autoApprove: read-only
---

# Morning Briefing

Provide a concise morning brief:

1. Today's weather and outfit suggestion
2. Calendar events for today
3. Top 3 news headlines

Keep it under 100 words - this is a quick glance.

GitHub Issue Triage

---
name: github-triage
description: Label and prioritize new GitHub issues
schedule: "0 9 * * 1-5"
autoApprove: low-risk
---

# GitHub Issue Triage

Review new GitHub issues from the last 24 hours:

1. Add appropriate labels (bug, feature, documentation)
2. Set priority (P0-P3) based on severity
3. Add to project board if critical

**Safety:** Only add labels and project assignments. Never close issues.

Weekly Standup Report

---
name: weekly-standup
description: Generate weekly progress report
schedule: "0 17 * * 5"
autoApprove: read-only
---

# Weekly Standup Report

Generate a weekly summary:

1. Completed tasks (from GitHub, calendar, notes)
2. In-progress work
3. Blockers or challenges
4. Next week's priorities

**Output:** Save to `~/standups/YYYY-WW.md`

Validation Checklist

Before creating the file, verify:

✓ Name is kebab-case, descriptive
✓ Description is one clear sentence
✓ Schedule is valid cron (5 fields)
✓ Auto-approve matches task risk level
✓ Safety rules are explicit and conservative
✓ Skills are listed if needed
✓ Output location is specified if workflow saves files
✓ Instructions are clear enough for an AI agent

Anti-Patterns

❌ Vague instructions: "clean my inbox" → specify exactly what to clean
❌ Overly aggressive auto-approve: Don't use high-risk unless necessary
❌ Missing safety rules: Always include "when in doubt" guidelines
❌ No schedule: If automating, include a schedule (or explain it's manual-only)
❌ Wrong location: Project-specific workflows shouldn't be global
❌ Too complex: Break into multiple simple workflows instead

Testing Guidance

Always recommend testing before scheduling:

Manual run first: jazz workflow run <name> to verify logic
Check with --auto-approve: Test the auto-approval behavior
Monitor initial runs: Watch logs for first few scheduled executions
Iterate: Adjust safety rules and criteria based on actual behavior

Documentation

After creating the workflow, optionally create a README in the workflow directory explaining:

What it does
When it runs
What to expect
How to customize

Example: workflows/email-cleanup/README.md