wflow

Guaranteed execution of AI tasks in a specified order.

wflow is a wrapper around iFlow CLI for automating AI tasks through declarative workflow files in YAML format. It uses the iFlow SDK to interact with the AI agent and ensures sequential execution of steps with context passing between them.

Built on iFlow CLI SDK

Features

Guaranteed execution order — steps execute strictly sequentially
Context passing — results from previous steps are available in subsequent ones
Interactive mode — convenient workflow selection and parameter input
Flexible settings — confirmation modes, timeouts, error handling
Full access to iFlow CLI tools — all AI agent tools are available in workflows
ACP server auto-detection — automatically finds or starts iFlow server
Pipeline support — exit codes for CI/CD integration

Installation

Requirements

Python 3.10+
iFlow CLI (installed and configured)

Installation Steps

# 1. Clone the repository
git clone <repository-url>
cd workflow-runner

# 2. Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or
.venv\Scripts\activate     # Windows

# 3. Install dependencies
pip install -r requirements.txt

Dependencies

iflow-cli-sdk>=0.1.0
pyyaml>=6.0
python-dotenv>=1.0.0
rich

Quick Start

Run built-in demo workflow

# Interactive mode - select workflow and enter parameters
python wflow.py

# Or with CLI parameters
python wflow.py demo -i user_name=Test -i topic="My topic"

Run with full path

python wflow.py workflows/code-review.yaml -i branch=feature/my-feature -i project_path=/var/www/project

Skip confirmation

python wflow.py demo -i user_name=Test -y

Pipeline mode (CI/CD)

# Check if ACP server is running
python wflow.py --check-acp

# Run with exit codes for CI/CD
python wflow.py demo -i user_name=Test --exit-code
# Exit codes: 0=success, 1=error, 2=ACP not running

Interactive Mode

Run the runner without arguments for interactive selection:

$ python wflow.py

============================================================
wflow - Workflow Runner
============================================================

Configuration:
  PROJECT_ROOT:   /var/www/my-project
  WORKFLOWS_DIR:  /var/www/my-project/.wflow/workflows
  PROMPTS_DIR:    /var/www/my-project/.wflow/prompts
  RUNNER_DIR:     /home/user/workflow-runner

============================================================
Available Workflows
============================================================

  [1] code-review — Code Review
      Analyzes code changes and creates recommendations...

  [2] demo
      Demo Workflow
      Demonstrates workflow with context passing...

Select workflow (number or name): 2

============================================================
Workflow Inputs
============================================================

  user_name: Your name
      Example: Konstantin
    > user_name: Konstantin

  topic: Topic to explore
      Example: Python async programming
    > topic: Python async programming

============================================================
Ready to Execute
============================================================

  Workflow: Demo Workflow
  Steps: 4

  Inputs:
    user_name: Konstantin
    topic: Python async programming

Proceed? [Y/n]: y

Using in Any Project

Project Structure

my-project/
├── .wflow/
│   ├── .env                    # Configuration (optional)
│   ├── workflows/              # Your workflows
│   │   ├── my-task.yaml
│   │   └── code-review.yaml
│   └── prompts/                # Your prompts
│       └── conventions.md
└── src/

Running from Project

# From project root
python /path/to/wflow.py

# Or specify project directory
python /path/to/wflow.py -C /var/www/my-project

Alias for Convenience

# ~/.bashrc or ~/.zshrc
alias wflow='/path/to/workflow-runner/.venv/bin/python /path/to/workflow-runner/wflow.py'

# Usage
cd /var/www/project
wflow
wflow demo -i user_name=Konstantin

Workflow Format

Basic Structure

# Metadata
name: "Workflow Name"
description: "Brief description"

# Global settings
timeout: 600                    # Timeout in seconds
approval_mode: DEFAULT          # Confirmation mode

# Environment variables
env:
  PROJECT_ROOT: /var/www/project

# Input parameters
inputs:
  param_name:
    description: "Parameter description"
    required: true
    default: "value"
    example: "example"

# Steps
steps:
  - name: step_name
    prompt: "Prompt with ${{ inputs.param_name }}"
    depends_on: [ previous_step ]

Workflow Fields

Field	Type	Required	Description
`name`	string	no	Workflow name
`description`	string	no	Description for workflow list
`timeout`	number	no	Timeout in seconds (default: 600)
`approval_mode`	string	no	Confirmation mode (default: DEFAULT)
`env`	object	no	Global variables
`inputs`	object	no	Input parameters
`steps`	array	yes	Array of steps

Input Parameters (inputs)

inputs:
  component_name:
    description: "Component name in snake_case"
    required: true
    example: "hero_banner"

  module:
    description: "Module machine name"
    required: false
    default: "custom"
    example: "my_module"

Field	Type	Description
`description`	string	Parameter description
`required`	boolean	Required (default: true)
`default`	string	Default value
`example`	string	Example for hint

Steps (steps)

steps:
  - name: analyze
    description: "Analyzes the task"
    prompt: |
      Analyze: ${{ inputs.task }}
    output_format: json

  - name: implement
    description: "Implements code"
    prompt: |
      Implement based on analysis:
      ${{ steps.analyze }}
    depends_on:
      - analyze
    approval: auto
    interactive: false
    on_failure:
      retry: 2
      notify: true

Field	Type	Description
`name`	string	Required. Step identifier
`description`	string	Step description
`prompt`	string	Prompt text (one of: prompt or prompt_file)
`prompt_file`	string	Path to prompt file
`depends_on`	array	List of dependencies
`context`	array	Variables for context
`output_format`	string	`text` or `json`
`interactive`	boolean	Request confirmation before step
`approval`	string	Confirmation mode for step
`on_failure`	object	Error handling

Variables in Prompts

# Full format (recommended)
${{ inputs.param_name }}      # Input parameter
${{ env.VAR_NAME }}           # Environment variable
${{ steps.step_name }}        # Step execution result
${{ steps.step_name.outputs.field }}  # Field from JSON result

# Short format
${param_name}
${PROJECT_ROOT}

Approval Modes (approval_mode)

Mode	Description
`DEFAULT`	Request for every action (safe mode)
`AUTO_EDIT`	Automatic file editing
`YOLO`	Full auto mode (for trusted workflows)
`PLAN`	Read-only, no changes

# Global mode
approval_mode: YOLO

steps:
  - name: safe_step
    # Inherits global mode

  - name: dangerous_step
    approval: ask      # Request confirmation

  - name: code_gen
    approval: auto     # Auto-editing

Error Handling

steps:
  - name: validate
    prompt: "Check the code"
    on_failure:
      retry: 2       # Number of retry attempts
      notify: true   # Show notification on error

CLI Commands

# Interactive mode (select workflow and enter parameters)
python wflow.py

# Run workflow by name
python wflow.py demo -i user_name=Test

# Run with full path
python wflow.py workflows/code-review.yaml -i branch=feature/my-feature

# Show configuration
python wflow.py --info

# Validation without running
python wflow.py demo --dry-run

# Verbose output (shows prompts)
python wflow.py demo --verbose

# Debug mode (thinking, tools, subagents, planning)
python wflow.py demo --debug

# Skip confirmation
python wflow.py demo -i user_name=Test -y

# Run from different directory
python wflow.py -C /path/to/project

# Check ACP server status
python wflow.py --check-acp

# Pipeline mode (exit codes for CI/CD)
python wflow.py demo -i user_name=Test --exit-code

CLI Arguments

Argument	Description
`workflow`	Path or name of workflow YAML file
`-i, --input KEY=VALUE`	Input parameter (can use multiple)
`-v, --verbose`	Verbose output (shows prompts)
`-d, --debug`	Debug mode (thinking, tools, subagents)
`--dry-run`	Validate without execution
`--info`	Show configuration
`-C, --directory`	Project working directory
`-y, --yes`	Skip confirmation
`--check-acp`	Check if ACP server is running
`--exit-code`	Output only exit code (for CI/CD pipelines)

Exit Codes (for CI/CD)

Code	Description
0	Success
1	Workflow error
2	ACP server not running

Environment Variables

Variable	Description	Default
`WFLOW_PROJECT_ROOT`	Project root directory	`cwd`
`WFLOW_WORKFLOWS_DIR`	Directory with workflows	`.wflow/workflows`
`WFLOW_PROMPTS_DIR`	Directory with prompts	`.wflow/prompts`
`WFLOW_ACP_HOST`	ACP server host	`localhost`
`WFLOW_ACP_PORT`	ACP server port	`8090`
`WFLOW_ACP_AUTO_START`	Auto-start iFlow if not running	`true`

.env File

Create a .env file in the project for configuration:

# .wflow/.env
WFLOW_PROJECT_ROOT=/var/www/my-project
WFLOW_WORKFLOWS_DIR=.wflow/workflows
WFLOW_PROMPTS_DIR=.wflow/prompts
WFLOW_ACP_HOST=localhost
WFLOW_ACP_PORT=8090
WFLOW_ACP_AUTO_START=true

The project's .env file takes priority over the runner directory's .env file.

Workflow Examples

Minimal Workflow

name: "Simple Task"
description: "Simple single-step workflow"

inputs:
  task:
    description: "What to do"

steps:
  - name: execute
    prompt: "Execute: ${{ inputs.task }}"

Demo Workflow (step chain)

name: "Demo Workflow"
description: "Demonstrates context passing between steps"

inputs:
  user_name:
    description: "Your name"
    required: true
    example: "Konstantin"

  topic:
    description: "Topic to explore"
    required: true
    example: "Python async programming"

timeout: 120
approval_mode: YOLO

steps:
  - name: greeting
    prompt: |
      Hello! Your name is ${{ inputs.user_name }}.
      Today we're exploring: ${{ inputs.topic }}
      Reply in one sentence.

  - name: analyze
    prompt: |
      Topic: ${{ inputs.topic }}
      Previous response: ${{ steps.greeting }}
      Write 3 key aspects of this topic.
    depends_on: [ greeting ]

  - name: summary
    prompt: |
      Summarize:
      Topic: ${{ inputs.topic }}
      Aspects: ${{ steps.analyze }}
    depends_on: [ analyze ]

Code Review Workflow

name: "Code Review"
description: "Analyzes code changes"

inputs:
  project_path:
    description: "Path to project"
    required: true

  branch:
    description: "Branch to analyze"
    required: true

timeout: 300
approval_mode: PLAN  # Read-only

steps:
  - name: analyze_changes
    prompt: |
      Analyze changes in project ${{ inputs.project_path }}.
      Branch: ${{ inputs.branch }}
      Get git diff and determine the type of changes.

  - name: security_check
    prompt: |
      Check for security issues:
      ${{ steps.analyze_changes }}
    depends_on: [ analyze_changes ]

  - name: quality_check
    prompt: |
      Check code quality:
      ${{ steps.analyze_changes }}
    depends_on: [ analyze_changes ]

  - name: report
    prompt: |
      Generate final report:
      Security: ${{ steps.security_check }}
      Quality: ${{ steps.quality_check }}
    depends_on: [ security_check, quality_check ]

iFlow CLI Tools

The iFlow CLI AI agent has access to the following tools:

File Operations

Tool	Description
`read_file`	Read file (text, PDF, DOCX, Excel, images)
`write_file`	Create/overwrite file
`replace`	Exact text replacement in file
`glob`	Find files by pattern (`*/.ts`)
`search_file_content`	Search content (regex)
`list_directory`	List directory
`xml_escape`	Escape XML/HTML

Command Execution

Tool	Description
`run_shell_command`	Execute shell command
`ReadCommandOutput`	Read background command output

Web

Tool	Description
`web_search`	Web search
`web_fetch`	Fetch and process URL

AI and Agents

Tool	Description
`task`	Launch subagent
`image_read`	Analyze images (VL model)
`Skill`	Call specialized skill

Management

Tool	Description
`todo_write`	Create task list
`todo_read`	Read task list
`ask_user_question`	Ask user question
`save_memory`	Save to long-term memory

Specialized Agents

task:
  subagent_type: "general-purpose"   # General tasks
  subagent_type: "plan-agent"        # Planning
  subagent_type: "explore-agent"     # Codebase exploration
  subagent_type: "frontend-tester"   # UI testing
  subagent_type: "ai-engineer"       # LLM applications

Debugging

Show Configuration

python wflow.py --info

Workflow Validation

python wflow.py workflow.yaml --dry-run

Verbose Output

# Shows prompts
python wflow.py workflow.yaml --verbose

Debug Mode

# Shows thinking, tool calls, subagents, planning
python wflow.py workflow.yaml --debug

ACP Server Check

# Check if server is running
python wflow.py --check-acp

# Check and get port for scripts
PORT=$(python wflow.py --check-acp --exit-code)

Project Structure

workflow-runner/
├── wflow.py               # Main script
├── sdk_patches.py         # SDK patches
├── .env.example           # Example configuration
├── requirements.txt       # Dependencies
├── README.md              # Documentation (English)
├── README.ru.md           # Documentation (Russian)
├── workflows/             # Built-in workflows
│   ├── demo.yaml          # Demo
│   ├── code-review.yaml   # Code review
│   └── workflow-generator.yaml
└── prompts/               # Prompts
    └── workflow-spec.md   # Workflow specification

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
prompts		prompts
workflows		workflows
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
README.ru.md		README.ru.md
README.zh.md		README.zh.md
example-workflow.yaml		example-workflow.yaml
requirements.txt		requirements.txt
sdk_patches.py		sdk_patches.py
wflow.py		wflow.py

Folders and files

Latest commit

History

Repository files navigation

wflow

Features

Table of Contents

Installation

Requirements

Installation Steps

Dependencies

Quick Start

Run built-in demo workflow

Run with full path

Skip confirmation

Pipeline mode (CI/CD)

Interactive Mode

Using in Any Project

Project Structure

Running from Project

Alias for Convenience

Workflow Format

Basic Structure

Workflow Fields

Input Parameters (inputs)

Steps (steps)

Variables in Prompts

Approval Modes (approval_mode)

Error Handling

CLI Commands

CLI Arguments

Exit Codes (for CI/CD)

Environment Variables

.env File

Workflow Examples

Minimal Workflow

Demo Workflow (step chain)

Code Review Workflow

iFlow CLI Tools

File Operations

Command Execution

Web

AI and Agents

Management

Specialized Agents

Debugging

Show Configuration

Workflow Validation

Verbose Output

Debug Mode

ACP Server Check

Project Structure

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages