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

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:

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

1. Understand the task: What should the agent do? When should it run? If unclear, ask.
2. Determine schedule: Convert user intent to cron format; if not stated, ask when they want it to run.
3. Decide catch-up behavior: Should missed runs execute on startup? Ask if not specified.
4. Choose auto-approve policy: Based on risk level of operations; default to conservative.
5. Identify required skills: What skills will the agent need?
6. Write clear instructions: Safety-first prompt with explicit guidelines.
7. 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

name

email-cleanup

description

Clean up old newsletters

schedule

0 * * * *

agent

research-agent

autoApprove

read-only

low-risk

high-risk

true

false

skills

["email", "calendar"]

catchUpOnStartup

true

maxCatchUpAge

43200

Cron Schedule Guide

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

0 * * * *

0 8 * * *

*/15 * * * *

0 9 * * 1-5

0 9 * * 1

0 0 1 * *

Cron format:

minute hour day-of-month month day-of-week

Auto-Approve Policy

Choose based on what tools the workflow will use:

read-only

low-risk

high-risk

false

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

./workflows/<name>/WORKFLOW.md

~/.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:

1. ✓ What counts as "old"? (2 weeks)
2. ✓ Should it only archive or also delete? (archive only)
3. ✓ Any specific senders to target? (newsletters, promotional)
4. ✓ 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:

email

calendar

deep-research

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:

1. Manual run first:

   jazz workflow run <name>

   to verify logic
2. Check with

   --auto-approve

   : Test the auto-approval behavior
3. Monitor initial runs: Watch logs for first few scheduled executions
4. 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