temporal

name	temporal
description	Help developers use Temporal for durable execution workflows. Covers CLI commands, SDK patterns (Go, TypeScript, Python, Java), workflow orchestration, and architectural decisions.
allowed-tools	["Read","Grep","Glob","Bash","WebSearch","WebFetch","Write","Edit"]
user-invocable	true
metadata	{"author":"rube-de","version":"1.0.0"}

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

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