| 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:
- Name — Short verb phrase (e.g., "Validate input", "Deploy to staging")
- Actor — Who/what executes it
- Input — What data or artifacts it needs
- Action — Concrete command, API call, or instruction
- Output — What it produces
- Error handling — What happens on failure (retry, abort, fallback, notify)
- 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
