Workflows
YAML templates that materialize as issues, dependencies, and labels — with optional human approval gates.
A workflow template is a YAML graph of steps. Running it creates plain issues
plus dependency edges plus run:<parent> / step:<id> labels — no new
tables.
Two ways to build a graph. This page covers static templates — a fixed
shape with {{var}} substitution. When the shape is computed (a step per
module, conditional fan-out), write a dynamic workflow in
JavaScript and pipe it into clu batch instead.
Template format
Templates live in .clu/templates/*.yaml.
name: release
vars:
version: { required: true, pattern: '^\d+\.\d+\.\d+$' }
steps:
- id: build
title: "Build {{version}}"
- id: test
title: "Test {{version}}"
needs: [build]
- id: approve
type: checkpoint # human gate
title: "Approve {{version}} for prod"
wait: { approval: [alice, bob] }
needs: [test]
- id: deploy
title: "Deploy {{version}}"
needs: [approve]vars declares typed variables that must be supplied at run time. needs is
the dependency graph between steps. {{var}} interpolation happens in titles
and descriptions.
Running
clu run release -v version=1.2.3That single command creates the parent issue, four children, and all dep edges
in one shot. Agents drive the run by claiming ready issues as each step
closes; humans clear checkpoint gates via:
clu approve <id>Checkpoints
A step with type: checkpoint additionally gets:
- a
checkpoint:pendinglabel, and - a
cp:<issue-id>KV entry holding{kind, approvers}JSON.
clu approve records the calling agent as the approver and closes the
checkpoint. The approvers list is informational only — it is not
enforced (single-user model), so any agent can approve. Failing a
checkpoint cascade-cancels the rest of
the run via the same forward-walk that powers clu cancel.
See demo-workflow.sh
in the repo for the full demo.