Skip to main content

​
How to Create Custom Workflows in ZenFlow

This guide shows you how to design and implement custom workflows in ZenFlow to automate specialized tasks and maintain consistency across your development process.

​
When to Use This Guide

If the built-in workflows (Quick Change, Fix Bug, Spec and Build, Full SDD) don’t quite fit your team’s specific process—such as requiring a security audit step, a specific documentation format, or a custom testing phase—follow this guide to build your own.

​
Prerequisites

Before starting, ensure you have:
  • The ZenFlow desktop application running and connected to your repository.
  • A basic understanding of how ZenFlow uses tasks and worktrees.
  • Access to your repository’s root directory to create configuration files.

​
Setup Steps

​
1. Create the Workflows Directory

ZenFlow looks for custom workflow definitions in a specific directory within your repository. Navigate to your repository root and create the .zenflow/workflows/ directory if it doesn’t already exist: 
mkdir -p .zenflow/workflows/

​
2. Create a Workflow Definition File

Each custom workflow is defined by a single Markdown file. The filename (without the .md extension) will be used to identify the workflow in ZenFlow. Create a new file, for example security-patch.md, inside .zenflow/workflows/.

​
3. Define the Workflow Title and Configuration

Start your file with a top-level heading for the title and a Configuration section. The configuration section tells ZenFlow where to store task-specific files. 
# Security Patch Workflow

## Configuration
- **Artifacts Path**: {@artifacts_path} → `.zenflow/tasks/{task_id}`

​
4. Design Your Workflow Steps

Add a Workflow Steps section. Each step must start with a level-3 heading and a checkbox (### [ ] Step: Name). These steps will appear in the ZenFlow UI as milestones for the agent. 
## Workflow Steps

### [ ] Step: Vulnerability Investigation
Describe the security issue and identify the affected components. 
Reference `{@artifacts_path}/investigation.md` for findings.

### [ ] Step: Remediation Design
Outline the fix and its impact on system security. 
The agent should output the design to `{@artifacts_path}/spec.md`.

### [ ] Step: Implementation & Hardening
Apply the fix and add regression tests. 
Deliverables should be recorded in `{@artifacts_path}/report.md`.

### [ ] Step: Security Review
Perform a final check for side effects and verify the fix against the vulnerability.

​
5. Save and Refresh ZenFlow

Save the file. ZenFlow automatically detects changes in the .zenflow/workflows/ directory.
  1. Open the ZenFlow desktop application.
  2. Click Create Task.
  3. In the workflow selection (Task Type), you should now see your new workflow (e.g., “Security Patch”) alongside the default options.

​
Verification

Your custom workflow is correctly set up when:
  • The new workflow name appears in the Task Type selection when creating a task.
  • Creating a task with this workflow populates the Steps column with the checkboxes and instructions you defined.
  • The {@artifacts_path} placeholder correctly resolves to the task’s worktree directory (e.g., .zenflow/tasks/TASK_ID).

​
Troubleshooting

Workflow not appearing:
  • Ensure the file is in .zenflow/workflows/ (note the leading dot).
  • Verify the file extension is .md.
  • Restart ZenFlow if it doesn’t pick up the change immediately.
Placeholders not resolving:
  • Double-check the syntax {@artifacts_path}.
  • Ensure the Configuration section is present and correctly formatted with a bullet point.
Steps not showing checkboxes:
  • Ensure steps use the exact format ### [ ] Step: Name.
  • Check for trailing spaces or hidden characters in the headers.

​
Next Steps

Now that you’ve created a custom workflow, you can:
  • Add Approval Gates: Insert “Review” steps to pause the agent until you provide feedback.
  • Reference Custom Artifacts: Define your own document templates (e.g., audit_log.md) and instruct the agent to use them.
  • Share with Team: Commit the .zenflow/workflows/ directory to your Git repository so your entire team can use the same standardized processes.