temporal

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](references/CLI.md) | Complete CLI command reference: installation, server, workflows, schedules, operators | | [SDK-PATTERNS.md](references/SDK-PATTERNS.md) | Cross-language SDK patterns: Go, TypeScript, Python, Java side-by-side | | [CONCEPTS.md](references/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

1. Check event history: temporal workflow show -w <id>
2. Look for ActivityTaskScheduled without corresponding ActivityTaskCompleted
3. Verify workers are running and polling the correct task queue
4. Check activity timeouts — may need HeartbeatTimeout for long activities
5. 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:

1. Identify the task: CLI operation, SDK code, architecture decision, or debugging
2. Check the language: For SDK questions, determine Go/TypeScript/Python/Java
3. Consult references: Use the reference docs for detailed patterns and commands
4. Verify determinism: For workflow code, ensure deterministic execution rules are followed
5. Test guidance: Recommend SDK test utilities, replay testing, and local dev server