Skip to main content

​
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

ElementDescription
# TitleTop-level heading becomes the workflow name
## ConfigurationSet shared variables like Artifacts Path
### [ ] Step: NameEach step appears in the Steps column with a checkbox

​
Optional Elements

ElementDescription
<!-- agent: preset-name -->Assign a specific agent preset to a step
{@artifacts_path}Resolves to .zenflow/worktrees/{task_id} at runtime
Step instructionsMarkdown 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

## 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

## 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

## 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