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 — use workflow.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
ActivityTaskScheduled without corresponding ActivityTaskCompleted
- Verify workers are running and polling the correct task queue
- Check activity timeouts — may need
HeartbeatTimeout for 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
1---2name: temporal3description: Help developers use Temporal for durable execution workflows. Covers CLI commands, SDK patterns (Go, TypeScript, Python, Java), workflow orchestration, and architectural decisions.4---56# Temporal Durable Execution78Comprehensive assistance for the Temporal durable execution platform: CLI operations, SDK development across Go/TypeScript/Python/Java, workflow design, and architectural decisions.910## Triggers1112Use 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".1314## Quick Start1516### Local Development Server1718```bash19# Install CLI20brew install temporal # macOS21curl -sSf https://temporal.download/cli | sh # Linux2223# Start local dev server (with Web UI at localhost:8233)24temporal server start-dev2526# Start with persistent storage27temporal server start-dev --db-filename temporal.db28```2930### First Workflow (TypeScript example)3132```bash33npm init -y34npm install @temporalio/client @temporalio/worker @temporalio/workflow @temporalio/activity35```3637## Common Tasks by Intent3839| Developer wants to... | Action |40|-----------------------|--------|41| Start a workflow | `temporal workflow start --type MyWorkflow --task-queue my-queue --input '{"key":"val"}'` |42| Check workflow status | `temporal workflow describe -w <workflow-id>` |43| View event history | `temporal workflow show -w <workflow-id>` |44| Cancel a workflow | `temporal workflow cancel -w <workflow-id>` |45| Send a signal | `temporal workflow signal -w <workflow-id> --name signal-name --input '{"data":true}'` |46| Query workflow state | `temporal workflow query -w <workflow-id> --name query-name` |47| List running workflows | `temporal workflow list` |48| Debug stuck workflow | Check history with `temporal workflow show`, look for pending activities |49| Set up scheduled runs | `temporal schedule create --schedule-id my-sched --cron '0 * * * *' ...` |50| Test workflows | Use SDK test utilities with time-skipping and activity mocking |5152## When to Use Temporal5354**Good fit:**55- Multi-step processes that must complete reliably (order processing, onboarding)56- Saga patterns across microservices (distributed transactions)57- Long-running workflows (days, weeks, months)58- Scheduled/cron jobs with complex logic59- Human-in-the-loop approval workflows6061**Not a good fit:**62- Simple request/response APIs (use plain HTTP)63- Sub-millisecond latency requirements (Temporal adds overhead)64- Trivial fire-and-forget background jobs (use a simple queue)65- Pure data streaming (use Kafka/Flink)6667## Reference Documents6869For deep dives, consult these references:7071| Reference | Content |72|-----------|---------|73| [CLI.md](references/CLI.md) | Complete CLI command reference: installation, server, workflows, schedules, operators |74| [SDK-PATTERNS.md](references/SDK-PATTERNS.md) | Cross-language SDK patterns: Go, TypeScript, Python, Java side-by-side |75| [CONCEPTS.md](references/CONCEPTS.md) | Architecture, core concepts, design patterns, deployment, comparisons |7677## Troubleshooting7879### Determinism Violations8081Workflows must be deterministic. Common violations:82- Using `Date.now()`, `Math.random()`, or system time directly — use `workflow.now()` or side effects83- Making network calls from workflow code — move to activities84- Using non-deterministic data structures (e.g., iterating over unordered maps)85- Changing workflow logic without proper versioning8687### Stuck Workflows88891. Check event history: `temporal workflow show -w <id>`902. Look for `ActivityTaskScheduled` without corresponding `ActivityTaskCompleted`913. Verify workers are running and polling the correct task queue924. Check activity timeouts — may need `HeartbeatTimeout` for long activities935. Check for deadlocked signals/queries9495### Timeout Issues9697Temporal has four timeout types:98- **WorkflowExecutionTimeout**: Max time for entire workflow (including retries)99- **WorkflowRunTimeout**: Max time for a single workflow run100- **ScheduleToCloseTimeout**: Max time from activity scheduled to completed101- **StartToCloseTimeout**: Max time from activity started to completed102103If activities time out unexpectedly, ensure `StartToCloseTimeout` is generous enough and add heartbeating for long-running activities.104105### Worker Not Picking Up Tasks106107- Verify task queue name matches between workflow starter and worker108- Check that the worker is registered with the correct workflow/activity types109- Ensure the Temporal server address is correct (`TEMPORAL_ADDRESS`)110- Look at worker logs for connection errors111112## Workflow113114When helping with Temporal:1151161. **Identify the task**: CLI operation, SDK code, architecture decision, or debugging1172. **Check the language**: For SDK questions, determine Go/TypeScript/Python/Java1183. **Consult references**: Use the reference docs for detailed patterns and commands1194. **Verify determinism**: For workflow code, ensure deterministic execution rules are followed1205. **Test guidance**: Recommend SDK test utilities, replay testing, and local dev server
rube-de