lvndry/create-workflow

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:

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

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

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:

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

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