Workflow Orchestration Patterns

From the author

Design durable workflows with Temporal for distributed systems. Covers workflow vs activity separation, saga patterns, state management, and determinism constraints. Use when building long-running processes, distributed transactions, or microservice orchestration.

— the description by Seth Hobson

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides architectural guidance for designing durable, fault-tolerant workflows using Temporal. It focuses on the separation of orchestration logic from external interactions, ensuring determinism in workflows and idempotency in activities. The content covers essential design patterns for distributed systems, including the Saga pattern for transactions, entity-based workflows, parallel execution strategies, and asynchronous callbacks.

What it does

Defines the distinction between workflow orchestration and activity execution
Explains the Saga pattern for managing distributed transactions
Provides patterns for long-lived entity management
Outlines strategies for parallel task execution and aggregation
Details requirements for workflow determinism and state preservation
Lists best practices for error handling and activity design

When to use it

When building multi-step processes that span multiple services
When implementing distributed transactions with rollback requirements
When managing long-running business processes that require state persistence
When designing systems that must recover automatically from infrastructure failures
When coordinating human-in-the-loop approvals or external callbacks

Advantages

Ensures system reliability through automatic state persistence
Provides clear separation of concerns between logic and side effects
Enables robust failure recovery and retry mechanisms
Supports complex coordination of distributed services

Usage examples

“How should I structure a payment process that requires a rollback if the order fulfillment fails?”: The agent explains the Saga pattern, detailing how to register compensation activities before executing the primary payment step to ensure consistency.
“What are the rules for writing code inside a Temporal workflow?”: The agent provides guidelines on maintaining determinism, such as avoiding direct external API calls and using workflow-specific time functions.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/wshobson/workflow-orchestration-patterns/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip workflow-orchestration-patterns.zip -d .agents/skills

Documentation by Seth Hobson

Master workflow orchestration architecture with Temporal, covering fundamental design decisions, resilience patterns, and best practices for building reliable distributed systems.

When to Use Workflow Orchestration

Ideal Use Cases (Source: docs.temporal.io)

Multi-step processes spanning machines/services/databases
Distributed transactions requiring all-or-nothing semantics
Long-running workflows (hours to years) with automatic state persistence
Failure recovery that must resume from last successful step
Business processes: bookings, orders, campaigns, approvals
Entity lifecycle management: inventory tracking, account management, cart workflows
Infrastructure automation: CI/CD pipelines, provisioning, deployments
Human-in-the-loop systems requiring timeouts and escalations

When NOT to Use

Simple CRUD operations (use direct API calls)
Pure data processing pipelines (use Airflow, batch processing)
Stateless request/response (use standard APIs)
Real-time streaming (use Kafka, event processors)

Detailed patterns and worked examples

Detailed pattern documentation lives in references/details.md. Read that file when the navigation tier above is insufficient.

Best Practices

Workflow Design

Keep workflows focused - Single responsibility per workflow
Small workflows - Use child workflows for scalability
Clear boundaries - Workflow orchestrates, activities execute
Test locally - Use time-skipping test environment

Activity Design

Idempotent operations - Safe to retry
Short-lived - Seconds to minutes, not hours
Timeout configuration - Always set timeouts
Heartbeat for long tasks - Report progress
Error handling - Distinguish retryable vs non-retryable

Common Pitfalls

Workflow Violations:

Using datetime.now() instead of workflow.now()
Threading or async operations in workflow code
Calling external APIs directly from workflow
Non-deterministic logic in workflows

Activity Mistakes:

Non-idempotent operations (can't handle retries)
Missing timeouts (activities run forever)
No error classification (retry validation errors)
Ignoring payload limits (2MB per argument)

Operational Considerations

Monitoring:

Workflow execution duration
Activity failure rates
Retry attempts and backoff
Pending workflow counts

Scalability:

Horizontal scaling with workers
Task queue partitioning
Child workflow decomposition
Activity batching when appropriate

Additional Resources

Official Documentation:

Temporal Core Concepts: docs.temporal.io/workflows
Workflow Patterns: docs.temporal.io/evaluate/use-cases-design-patterns
Best Practices: docs.temporal.io/develop/best-practices
Saga Pattern: temporal.io/blog/saga-pattern-made-easy

Key Principles:

Workflows = orchestration, Activities = external calls
Determinism is non-negotiable for workflows
Idempotency is critical for activities
State preservation is automatic
Design for failure and recovery

Files

ATTRIBUTION.mdAdded by AutoGineer1.0 KiB
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md3.4 KiB
references/details.md5.8 KiB

SKILL.md