workflow-creation

name	workflow-creation
description	Create executable agent workflows in .agent/workflows/. Use when the user wants to define, scaffold, validate, or edit a multi-step workflow pipeline that uses tools, delegate steps, approval gates, or parallel branches.

Workflow Creation

Create and edit agent workflow definitions in .agent/workflows/*.yaml.

Workflow

Step 1: Gather Requirements

Extract or confirm:

• Goal: what outcome the workflow should produce
• Trigger: manual, scheduled, event-driven, or approval-driven
• Inputs: names, required fields, and sensible defaults
• Step types: tool, delegate, approval, or parallel
• Failure policy: fail, skip, or retry, plus retry counts where needed
• Agents and tools involved: exact tool names or agent names if known

Ask only for gaps that materially block a correct workflow definition.

Step 2: Pick the Shape

Read workflow-patterns.md and map the user’s request to the workflow engine’s supported step shapes:

• tool: deterministic tool call with tool and args
• delegate: hand work to another agent with agent and task
• approval: pause until a human resumes the run
• parallel: run multiple branches concurrently

Prefer the simplest shape that fits. Most workflows are mostly sequential with a few retries, approvals, or parallel branches.

Step 3: Scaffold

Use the init script to create a starter YAML file:

python3 {baseDir}/scripts/init_workflow.py <workflow-name>

Optional flags:

python3 {baseDir}/scripts/init_workflow.py <workflow-name> --path .agent/workflows --description "..."

This creates .agent/workflows/<workflow-name>.yaml by default.

Step 4: Fill the Workflow

Use the template at workflow-template.yaml and follow these rules:

• name must match the filename without .yaml
• steps must be a YAML list
• every step needs a unique id
• step type may be explicit via type, or inferred from tool, agent, approval, or parallel
• onError may be fail, skip, or retry
• retryCount only makes sense with onError: retry
• parallel steps contain branch objects, each with its own steps list

Keep task strings and approval.message fields explicit. Avoid vague prompts like “handle it”.

Step 5: Validate

Run:

python3 {baseDir}/scripts/validate_workflow.py .agent/workflows/<workflow-name>.yaml

The validator checks:

• top-level name and steps
• filename matches name
• unique step ids
• valid step types
• required fields for each step shape
• valid onError and retryCount combinations

Fix all reported errors before finalizing.

Step 6: Review for Execution

Walk the workflow end to end:

• Do required inputs cover every placeholder the workflow needs?
• Are tool names and agent names real for this repo?
• Do parallel branches avoid conflicting writes?
• Is any approval step acceptable for the intended trigger?
• Would retries be safe and idempotent?

If the workflow is meant for unattended use later, avoid approval steps or clearly note that a cron runner would need to handle them specially.

Output Format

Always produce the final workflow as a YAML file in .agent/workflows/, not a markdown runbook.

Tips

• Prefer small steps with stable ids like fetch-pr, review, notify
• Use delegate for open-ended reasoning and tool for deterministic actions
• Keep branch counts modest in parallel steps
• Put defaults in inputs when they reduce operator friction
• Add short descriptions so run_workflow list is useful