Custom Workflows

Overview

Custom workflows let you define your own task templates beyond the built-in options. Write a Markdown file describing the workflow steps, drop it in .zenflow/workflows/ in your repo, and Zenflow surfaces it alongside the standard workflows when creating a task.

Credit Efficiency: Custom workflows have varying credit costs depending on the number of steps and the models configured. Learn more in the Workflow Credit Efficiency reference guide.

When to Use

Recurring team processes (release prep, security audits, migrations)
Compliance-driven workflows requiring specific documentation stages
Domain-specific flows (ML training pipelines, data processing)
When built-in workflows don’t match your team’s process

Creating a Custom Workflow

1. Create the workflow file

Add a .md file to .zenflow/workflows/ in your repository root:

your-repo/
├── .zenflow/
│   └── workflows/
│       └── security-review.md

2. Write the workflow definition

# Security Review Workflow

## Configuration
- **Artifacts Path**: {@artifacts_path}

---

## Workflow Steps

### [ ] Step: Threat Model
<!-- agent: opus-planner -->
Analyze the codebase for security-sensitive areas. Document potential
threats and attack surfaces in {@artifacts_path}/threat-model.md.

### [ ] Step: Implementation
<!-- agent: sonnet-builder -->
Implement security fixes and hardening measures identified in the
threat model. Update {@artifacts_path}/report.md with changes made.

### [ ] Step: Security Verification
<!-- agent: opus-reviewer -->
Review all changes against the threat model. Run security-focused
tests and static analysis. Document findings in {@artifacts_path}/review.md.

3. Use the workflow

When creating a new task, your custom workflow appears in the workflow picker alongside Auto, Fix a Bug, and others.

Workflow File Structure

Required Elements

Element	Description
`# Title`	Top-level heading becomes the workflow name
`## Configuration`	Set shared variables like `Artifacts Path`
`### [ ] Step: Name`	Each step appears in the Steps column with a checkbox

Optional Elements

Element	Description
`<!-- agent: preset-name -->`	Assign a specific agent preset to a step
`{@artifacts_path}`	Resolves to `.zenflow/worktrees/{task_id}` at runtime
Step instructions	Markdown below each step heading — objectives, acceptance criteria, deliverables

Agent Assignment

Assign different agent presets to different steps using HTML comments:

### [ ] Step: Planning
<!-- agent: opus-planner -->
Create the technical specification...

### [ ] Step: Implementation
<!-- agent: flash-builder -->
Implement the changes...

### [ ] Step: Review
<!-- agent: sonnet-reviewer -->
Review all changes...

Agent presets are configured in Settings → Default agents. Each preset defines a CLI, model, and execution configuration.

Examples

Release Preparation

# Release Preparation

## Configuration
- **Artifacts Path**: {@artifacts_path}

---

## Workflow Steps

### [ ] Step: Changelog Generation
Review all commits since the last release tag. Generate a changelog
grouped by category (features, fixes, breaking changes) in
{@artifacts_path}/changelog.md.

### [ ] Step: Version Bump
Update version numbers in package.json, pyproject.toml, or equivalent.
Ensure all references are consistent.

### [ ] Step: Pre-Release Verification
Run the full test suite, check for deprecation warnings, verify
documentation links. Document results in {@artifacts_path}/verification.md.

Database Migration

# Database Migration

## Configuration
- **Artifacts Path**: {@artifacts_path}

---

## Workflow Steps

### [ ] Step: Schema Analysis
<!-- agent: opus-planner -->
Analyze current schema and proposed changes. Document migration
strategy, rollback plan, and data preservation approach in
{@artifacts_path}/migration-plan.md.

### [ ] Step: Migration Implementation
Generate migration files following the project's ORM conventions.
Include both up and down migrations. Add data backfill scripts
where needed.

### [ ] Step: Migration Testing
Run migrations against a test database. Verify data integrity,
check rollback works, and validate performance impact.
Document results in {@artifacts_path}/test-results.md.

API Design Review

# API Design Review

## Configuration
- **Artifacts Path**: {@artifacts_path}

---

## Workflow Steps

### [ ] Step: API Specification
<!-- agent: opus-planner -->
Create an OpenAPI specification for the proposed endpoints.
Document request/response schemas, error codes, and rate limits
in {@artifacts_path}/api-spec.md.

### [ ] Step: Implementation
<!-- agent: flash-builder -->
Implement the API endpoints following the specification.
Include input validation, error handling, and integration tests.

### [ ] Step: Contract Testing
Verify the implementation matches the OpenAPI spec exactly.
Run contract tests and document any deviations in
{@artifacts_path}/contract-report.md.

Best Practices

Scope steps as coherent milestones — each step should produce a clear deliverable
Use artifact placeholders — {@artifacts_path}/filename.md resolves paths automatically per task
Write imperative instructions — tell the agent what to produce, not just what to think about
Assign agents per step — use reasoning models for planning and fast models for implementation
Version control workflows — keep .zenflow/workflows/ in your repo so the team shares the same processes

All Workflows

Compare all available workflows

Multi-Agent Orchestration

Agent presets and subagent configuration

Subagents

Spawn isolated sub-processes within workflow steps

Get Started

Zenflow

Agents

Workflows

Customizing

Models

Integrations & MCP

IDE Plugin

CLIs

Admin

Resources

Overview

When to Use

Creating a Custom Workflow

1. Create the workflow file

2. Write the workflow definition

3. Use the workflow

Workflow File Structure

Required Elements

Optional Elements

Agent Assignment

Examples

Best Practices

All Workflows

Multi-Agent Orchestration

Subagents

​Overview

​When to Use

​Creating a Custom Workflow

​1. Create the workflow file

​2. Write the workflow definition

​3. Use the workflow

​Workflow File Structure

​Required Elements

​Optional Elements

​Agent Assignment

​Examples

​Best Practices

​Related

All Workflows

Multi-Agent Orchestration

Subagents

Overview

When to Use

Creating a Custom Workflow

1. Create the workflow file

2. Write the workflow definition

3. Use the workflow

Workflow File Structure

Required Elements

Optional Elements

Agent Assignment

Examples

Best Practices

Related