workflow-orchestration-patterns

wshobson/agents

Reference guide for designing reliable, deterministic Temporal workflows and idempotent activities.

What is workflow-orchestration-patterns?

This skill provides reference guidance and best practices for designing durable workflows with Temporal, covering when to use workflow orchestration, the separation between workflows and activities, determinism constraints, saga patterns for distributed transactions, and operational concerns like monitoring and scalability. Use it when architecting long-running processes, distributed transactions, or microservice orchestration systems.

Defines when workflow orchestration is appropriate vs when to use simpler alternatives like direct APIs or batch tools
Explains the separation of concerns between workflows (deterministic orchestration) and activities (idempotent external calls)
Documents determinism constraints and common workflow violations to avoid
Covers saga pattern usage for distributed transactions
Lists best practices for workflow design, activity design, and operational monitoring/scalability
Points to a references/details.md file with detailed patterns and worked examples

How to install workflow-orchestration-patterns

npx skills add https://github.com/wshobson/agents --skill workflow-orchestration-patterns

Prerequisites

Familiarity with Temporal (or similar durable workflow execution engines) concepts such as workflows, activities, and workers
A distributed system or microservice architecture where long-running or multi-step processes need reliable orchestration

Claude Code

Cursor

Windsurf

Cline

How to use workflow-orchestration-patterns

1.Identify whether your use case fits ideal scenarios (multi-step distributed processes, long-running workflows, distributed transactions, human-in-the-loop approvals) rather than simple CRUD or stateless APIs.
2.Separate your system design into workflows (deterministic orchestration logic) and activities (idempotent external calls), per the workflow vs activity boundary guidance.
3.Apply the workflow design best practices: keep workflows single-responsibility, use child workflows for scalability, and test locally with a time-skipping test environment.
4.Apply activity design best practices: make operations idempotent, keep them short-lived, configure timeouts, use heartbeats for long tasks, and classify retryable vs non-retryable errors.
5.Consult references/details.md for detailed patterns and worked examples (e.g., saga pattern) when the top-level guidance isn't enough.
6.Set up monitoring for workflow execution duration, activity failure rates, retry attempts, and pending workflow counts, and plan scalability via worker scaling, task queue partitioning, and child workflow decomposition.

Use cases

Good for

Architecting a multi-step order fulfillment or booking process spanning multiple services with automatic state persistence
Implementing distributed transactions with all-or-nothing semantics using the saga pattern
Building long-running business processes (hours to years) such as campaign management or approval workflows
Designing human-in-the-loop systems that require timeouts and escalations
Automating infrastructure pipelines like CI/CD, provisioning, or deployments with reliable failure recovery

Who it's for

Backend/distributed systems engineers building microservice orchestration
Engineers adopting Temporal for long-running or fault-tolerant workflows
Architects designing distributed transaction handling (saga pattern) across services
Teams implementing CI/CD or infrastructure automation pipelines requiring durable execution

workflow-orchestration-patterns FAQ

What is the core principle to remember when splitting logic?

Workflows handle orchestration logic and must be deterministic; activities perform external calls (API requests, DB writes) and must be idempotent since they can be retried.

When should I NOT use Temporal-style workflow orchestration?

Avoid it for simple CRUD operations, pure data processing pipelines (use Airflow/batch tools instead), stateless request/response APIs, or real-time streaming (use Kafka or event processors).

What are common workflow code mistakes this skill helps avoid?

Using datetime.now() instead of workflow.now(), introducing threading/async in workflow code, calling external APIs directly from a workflow, and other non-deterministic logic.

What is the saga pattern reference for?

It's referenced for implementing distributed transactions requiring all-or-nothing semantics across multiple services, with a pointer to Temporal's official saga pattern blog post.

Does this skill include hands-on code samples?

The top-level SKILL.md provides navigation and best practices; detailed patterns and worked examples are in a separate references/details.md file included with the skill.

Full instructions (SKILL.md)

Source of truth, from wshobson/agents.

name: workflow-orchestration-patterns description: 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.

Workflow Orchestration Patterns

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