Workflows

A workflow saves a job you want to repeat: a prompt, an agent, permissions, and run limits. Use one for reviews, briefings, or checks you want to run by name or on a schedule.

Create a workflow

First create an agent named assistant. From the project directory, create workflows/project-status/ and save this as WORKFLOW.md:

---
name: project-status
description: "Report recent commits and current uncommitted changes."
agent: assistant
schedule: "0 17 * * 5"
autoApprove: read-only
maxIterations: 40
maxCostUSD: 1.00
---

# Project status

Read the project files and inspect git status and git log without modifying anything.
Summarize commits between {schedule.lastRunAt} and {run.startedAt}; if the last-run time
is empty, use the last seven days. List uncommitted changes separately.
This is the {schedule.label} report.

Run it from the project directory:

jazz workflow run project-status --auto-approve

Jazz prints the report. --auto-approve uses the workflow’s read-only policy, so you can check the behavior it will have unattended. When the result is useful, install its Friday 17:00 schedule:

jazz workflow schedule project-status

See Scheduled runs to set up delivery and inspect run history.

What the frontmatter does

Field	Decides
`agent`	Who runs it
`schedule`	Its default frequency, as a cron
`autoApprove`	What it may do with nobody watching
`maxCostUSD` and friends	When to stop

Every field is listed in workflow frontmatter.

Where Jazz looks

Path	Applies to
`~/.jazz/workflows/`	all your projects
`./workflows/`	this repository only

Closest wins. A repository can have its own code-review without touching yours.

Starting points

Jazz ships no workflows of its own. The library offers workflows you can install and edit, from a morning weather briefing to a merged-pull-request recap. Installed copies live in ~/.jazz/workflows/<name>/ and can be edited locally.

Several schedules, one workflow

A workflow is a process definition. A schedule binds it to a cron and an agent, and one workflow can have several. The id of a schedule is <workflow>/<label>; the frontmatter frequency installs as default.

jazz workflow schedule project-status                                  # project-status/default, Fridays
jazz workflow schedule project-status --cron "0 9 1 * *" --as monthly  # project-status/monthly
jazz workflow scheduled project-status                                 # both, with their crons
jazz workflow unschedule project-status/monthly                        # just that one

The prompt can use these schedule placeholders:

Placeholder	Value
`{schedule.label}`	`default`, `monthly`, or `manual` for `jazz workflow run`
`{schedule.cron}`	the cron that fired, empty for a manual run
`{schedule.lastRunAt}`	when this workflow last completed under the same label
`{run.startedAt}`	now

Each label keeps its own last-run marker, so the monthly recap covers the whole month even though the weekly one ran four times in between. Catch-up treats each schedule on its own for the same reason. Two schedules of one workflow may not share a cron.

The library

Browse and install workflows:

jazz workflow browse             # pick one, read the whole file, install it
jazz workflow search             # list what the library offers
jazz workflow add <name>     # straight to ~/.jazz/workflows/<name>/WORKFLOW.md

Installing prints the full WORKFLOW.md and asks for confirmation. Review its prompt and autoApprove tier before accepting. --as <name> installs under a different local name. Contributing one is a pull request: CONTRIBUTING.md.

Workflow, skill, or agent?

A workflow is a job: this prompt, this agent, these limits.

A skill is know-how. The model loads it when a task matches. No prompt of its own, and you cannot schedule it.

An agent is who does the work.

A workflow can list skills in its frontmatter to supply the procedures its agent should follow.

Workflow frontmatter: every field and its default
Scheduled runs: installing and managing schedules
jazz workflow: list, run, schedule, history, catch-up