workflow-creator

name	workflow-creator
description	Create structured, step-by-step workflows that chain multiple tasks into automated or semi-automated processes. Use when the user wants to define, document, or build a workflow, pipeline, runbook, or multi-step process — including CI/CD pipelines, deployment procedures, data processing flows, or operational runbooks.

Workflow Creator

Help users design and document structured workflows — repeatable processes that chain multiple tasks with clear inputs, outputs, error handling, and decision points.

Workflow

Step 1: Gather Requirements

Ask the user:

• Goal — What end result does this workflow produce?
• Trigger — What starts it? (manual, scheduled, event-driven, webhook)
• Scope — How many steps? What systems/tools are involved?
• Actors — Who or what executes each step? (human, script, API, agent)
• Error tolerance — Must it be atomic? Can steps be retried? Is rollback needed?
• Environment — What prerequisites, credentials, or dependencies exist?

If the user has a rough description, extract these from it. Only ask about gaps.

Step 1b: Scaffold the Workflow

Run the init script to create a pre-filled workflow document:

python3 {baseDir}/scripts/init_workflow.py <workflow-name> --path <output-dir> [--pattern <pattern>]

Valid patterns: sequential, parallel, conditional, retry, approval-gate, loop, fan-out-fan-in.

This creates <output-dir>/<workflow-name>.md from the standard template with the name, title, date, and pattern pre-filled. Edit the generated file to fill in the remaining sections.

Step 2: Identify the Pattern

Read workflow-patterns.md and match the user's needs to one or more patterns:

Pattern	Use When
Sequential	Steps must run in strict order
Parallel	Independent steps can run concurrently
Conditional	Different paths based on runtime data
Retry/Error	Steps may fail transiently
Approval Gate	Human review required before continuing
Loop	Repeat over a collection or until a condition
Fan-out/Fan-in	Process items in parallel, then aggregate

Most real workflows combine patterns. Identify the primary flow and note where secondary patterns apply.

Step 3: Define Steps

For each step, capture:

1. Name — Short verb phrase (e.g., "Validate input", "Deploy to staging")
2. Actor — Who/what executes it
3. Input — What data or artifacts it needs
4. Action — Concrete command, API call, or instruction
5. Output — What it produces
6. Error handling — What happens on failure (retry, abort, fallback, notify)
7. Timeout — Maximum duration, if applicable

Order steps logically. Mark parallel groups and decision branches explicitly.

Step 4: Define Error Handling & Rollback

For every workflow, determine:

• Per-step failures — Retry count, backoff, fallback action
• Workflow-level failure — At what point is the whole workflow considered failed?
• Rollback plan — Steps to undo partial progress (reverse order of completed steps)
• Notification — Who gets alerted on failure and how

Step 5: Write the Workflow Document

Use the template at workflow-template.md. Copy it and fill in all sections. Follow these rules:

• Use numbered steps with clear imperative verbs
• Mark optional steps with (optional)
• Mark conditional branches with if/else blocks
• Mark parallel steps with a [parallel] tag
• Include concrete commands, scripts, or API calls — not vague descriptions
• Define success criteria as observable, verifiable conditions

Step 6: Validate

Run the validation script to check the workflow document for structural issues:

python3 {baseDir}/scripts/validate_workflow.py <path/to/workflow.md>

This checks:

• Top-level # Workflow: ... heading exists
• Required sections present: Description, Trigger, Prerequisites, Steps, Success Criteria
• Each step has Action, Output, and Error handling fields
• Warns (without failing) if Rollback Plan, Notifications, or Metadata are missing

Fix all errors before finalizing. Address warnings where applicable.

Step 7: Review & Refine

Walk through the workflow mentally (or with the user) end-to-end:

• Can every step actually execute given the outputs of previous steps?
• Are error cases handled? What if step 3 fails after step 2 succeeded?
• Are there race conditions in parallel sections?
• Is the rollback plan complete and tested?
• Are timeouts reasonable?

Adjust until the workflow is sound.

Output Format

Always produce the final workflow as a single markdown document following the template structure. Place it where the user specifies, or default to docs/workflows/<workflow-name>.md.

Tips

• Prefer small, composable steps over monolithic ones
• Every step should be independently testable
• Idempotent steps simplify retries and rollback
• Log entry/exit of each step for observability
• Version your workflows — they evolve with the system