Temporal Durable Execution
Comprehensive assistance for the Temporal durable execution platform: CLI operations, SDK development across Go/TypeScript/Python/Java, workflow design, and architectural decisions.
Triggers
Use this skill when the user mentions: "temporal", "durable execution", "workflow orchestration", "temporal cli", "temporal sdk", "temporal worker", "temporal activity", "temporal workflow", "temporal schedule", "temporal signal", "temporal query".
Quick Start
Local Development Server
# Install CLI
brew install temporal # macOS
curl -sSf https://temporal.download/cli | sh # Linux
# Start local dev server (with Web UI at localhost:8233)
temporal server start-dev
# Start with persistent storage
temporal server start-dev --db-filename temporal.db
First Workflow (TypeScript example)
npm init -y
npm install @temporalio/client @temporalio/worker @temporalio/workflow @temporalio/activity
Common Tasks by Intent
| Developer wants to... | Action |
|---|---|
| Start a workflow | temporal workflow start --type MyWorkflow --task-queue my-queue --input '{"key":"val"}' |
| Check workflow status | temporal workflow describe -w <workflow-id> |
| View event history | temporal workflow show -w <workflow-id> |
| Cancel a workflow | temporal workflow cancel -w <workflow-id> |
| Send a signal | temporal workflow signal -w <workflow-id> --name signal-name --input '{"data":true}' |
| Query workflow state | temporal workflow query -w <workflow-id> --name query-name |
| List running workflows | temporal workflow list |
| Debug stuck workflow | Check history with temporal workflow show, look for pending activities |
| Set up scheduled runs | temporal schedule create --schedule-id my-sched --cron '0 * * * *' ... |
| Test workflows | Use SDK test utilities with time-skipping and activity mocking |
When to Use Temporal
Good fit:
- Multi-step processes that must complete reliably (order processing, onboarding)
- Saga patterns across microservices (distributed transactions)
- Long-running workflows (days, weeks, months)
- Scheduled/cron jobs with complex logic
- Human-in-the-loop approval workflows
Not a good fit:
- Simple request/response APIs (use plain HTTP)
- Sub-millisecond latency requirements (Temporal adds overhead)
- Trivial fire-and-forget background jobs (use a simple queue)
- Pure data streaming (use Kafka/Flink)
Reference Documents
For deep dives, consult these references:
| Reference | Content |
|---|---|
| CLI.md | Complete CLI command reference: installation, server, workflows, schedules, operators |
| SDK-PATTERNS.md | Cross-language SDK patterns: Go, TypeScript, Python, Java side-by-side |
| CONCEPTS.md | Architecture, core concepts, design patterns, deployment, comparisons |
Troubleshooting
Determinism Violations
Workflows must be deterministic. Common violations:
- Using
Date.now(),Math.random(), or system time directly — useworkflow.now()or side effects - Making network calls from workflow code — move to activities
- Using non-deterministic data structures (e.g., iterating over unordered maps)
- Changing workflow logic without proper versioning
Stuck Workflows
- Check event history:
temporal workflow show -w <id> - Look for
ActivityTaskScheduledwithout correspondingActivityTaskCompleted - Verify workers are running and polling the correct task queue
- Check activity timeouts — may need
HeartbeatTimeoutfor long activities - Check for deadlocked signals/queries
Timeout Issues
Temporal has four timeout types:
- WorkflowExecutionTimeout: Max time for entire workflow (including retries)
- WorkflowRunTimeout: Max time for a single workflow run
- ScheduleToCloseTimeout: Max time from activity scheduled to completed
- StartToCloseTimeout: Max time from activity started to completed
If activities time out unexpectedly, ensure StartToCloseTimeout is generous enough and add heartbeating for long-running activities.
Worker Not Picking Up Tasks
- Verify task queue name matches between workflow starter and worker
- Check that the worker is registered with the correct workflow/activity types
- Ensure the Temporal server address is correct (
TEMPORAL_ADDRESS) - Look at worker logs for connection errors
Workflow
When helping with Temporal:
- Identify the task: CLI operation, SDK code, architecture decision, or debugging
- Check the language: For SDK questions, determine Go/TypeScript/Python/Java
- Consult references: Use the reference docs for detailed patterns and commands
- Verify determinism: For workflow code, ensure deterministic execution rules are followed
- Test guidance: Recommend SDK test utilities, replay testing, and local dev server