Zebra Workflow Engine

A workflow engine for AI-assisted development tasks. Zebra enables structured execution of complex, long-running workflows with support for parallel execution, conditional routing, and LLM integration.

Project Structure

zebra/
├── zebra-py/              # Python workflow engine (primary implementation)
├── zebra-tasks/           # Reusable task actions library (Python)
├── zebra-agent/           # Self-improving AI agent framework
├── zebra-agent-web/       # Web UI for Zebra Agent (Django)
└── legacy/                # Legacy Java implementation (archived)

Components

Package	Language	Description
zebra-py	Python	Core workflow engine with MCP server integration
zebra-tasks	Python	Reusable task actions (subtasks, LLM calling)
zebra-agent	Python	Self-improving agent framework built on zebra workflows
zebra-agent-web	Python	Web UI for Zebra Agent with human task forms and Django ORM storage

Quick Start

Python (zebra-py)

cd zebra-py
uv sync
uv run python -c "from zebra import WorkflowEngine; print('Ready!')"

Building

This project uses uv workspaces to manage multiple Python packages.

All Python Packages (Recommended)

# From project root - syncs all packages
uv sync --all-packages

Individual Packages

# zebra-py only
cd zebra-py && uv sync

# zebra-tasks only
cd zebra-tasks && uv sync

Running Tests

Run tests using uv run pytest from the project root.

All Tests

# Run all tests across all packages (866 tests)
uv run pytest

Individual Package Tests

# Core workflow engine (272 tests)
uv run pytest zebra-py/tests/ -v

# Task actions library (406 tests)
uv run pytest zebra-tasks/tests/ -v

# Agent framework (168 tests)
uv run pytest zebra-agent/tests/ -v

# Web UI tests (20 tests)
uv run pytest zebra-agent-web/tests/ -v

Test with Coverage

# All tests with coverage
uv run pytest --cov

# Coverage for specific package
uv run pytest zebra-py/tests/ --cov=zebra

Example Workflow

name: "Code Review"
version: 1

tasks:
  analyze:
    name: "Analyze Code"
    action: llm_call
    properties:
      prompt: "Analyze this code for issues: {{code}}"
      output_key: analysis

  review:
    name: "Review"
    auto: false
    properties:
      schema:
        type: object
        title: "Review Analysis"
        description: "Analysis: {{analysis}}"
        required: [decision]
        properties:
          decision:
            type: string
            title: "Approve?"
            enum: ["approve", "reject"]
          comments:
            type: string
            title: "Comments"
            format: multiline

routings:
  - from: analyze
    to: review

Human tasks (tasks with auto: false) pause the workflow and wait for input. Form fields are defined using JSON Schema in properties.schema and rendered automatically by the web UI. See the zebra-py README for full documentation.

Documentation

• zebra-py README - Full Python engine documentation
• zebra-tasks README - Task actions documentation
• Design Document - Original design specification

License

Apache License 2.0 (see LICENSE.txt)

Credits

Based on the Java Zebra workflow engine originally developed by Anite (2004) and modified by Ben Gidley (2010).