Skip to main content
workflow-orchestration-patterns 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.
npx skills add wshobson/agents --skill workflow-orchestration-patterns agents claude claude-code subagents anthropic automation
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/databasesDistributed transactions requiring all-or-nothing semanticsLong-running workflows (hours to years) with automatic state persistenceFailure recovery that must resume from last successful stepBusiness processes : bookings, orders, campaigns, approvalsEntity lifecycle management : inventory tracking, account management, cart workflowsInfrastructure automation : CI/CD pipelines, provisioning, deploymentsHuman-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
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 retryShort-lived - Seconds to minutes, not hoursTimeout configuration - Always set timeoutsHeartbeat for long tasks - Report progressError handling - Distinguish retryable vs non-retryable
Common Pitfalls
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
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
Workflow execution duration
Activity failure rates
Retry attempts and backoff
Pending workflow counts
Horizontal scaling with workers
Task queue partitioning
Child workflow decomposition
Activity batching when appropriate
Additional Resources
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
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
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
