---

name: temporal-python description: "Start, stop, debug, and troubleshoot Temporal workflows for Python projects. Use when: starting workers, executing workflows, workflow is stalled/failed, non-determinism errors, checking workflow status, or managing temporal server start-dev lifecycle." version: 1.1.0 allowed-tools: "Bash(.claude/skills/temporal/scripts/:), Read"

Temporal Skill

Manage Temporal workflows using local development server (Python SDK, temporal server start-dev).

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | CLAUDE_TEMPORAL_LOG_DIR | /tmp/claude-temporal-logs | Worker log directory | | CLAUDE_TEMPORAL_PID_DIR | /tmp/claude-temporal-pids | Worker PID directory | | TEMPORAL_ADDRESS | localhost:7233 | Temporal server gRPC address | | TEMPORAL_WORKER_CMD | uv run worker | Command to start worker |

---

Quick Start

# 1. Start server
./scripts/ensure-server.sh

# 2. Start worker (kills old workers, starts fresh)
./scripts/ensure-worker.sh

# 3. Execute workflow
uv run starter  # Capture workflow_id from output

# 4. Wait for completion
./scripts/wait-for-workflow-status.sh --workflow-id <id> --status COMPLETED

# 5. Get result (verify it's correct, not an error message)
./scripts/get-workflow-result.sh --workflow-id <id>

# 6. CLEANUP: Kill workers when done
./scripts/kill-worker.sh

---

Common Recipes

Clean Start

./scripts/kill-all-workers.sh
./scripts/ensure-server.sh
./scripts/ensure-worker.sh
uv run starter

Debug Stalled Workflow

./scripts/find-stalled-workflows.sh
./scripts/analyze-workflow-error.sh --workflow-id <id>
tail -100 $CLAUDE_TEMPORAL_LOG_DIR/worker-$(basename "$(pwd)").log
# See references/troubleshooting.md for decision tree

Clear Stalled Environment

./scripts/find-stalled-workflows.sh
./scripts/bulk-cancel-workflows.sh
./scripts/kill-worker.sh
./scripts/ensure-worker.sh

Check Recent Results

./scripts/list-recent-workflows.sh --minutes 30
./scripts/get-workflow-result.sh --workflow-id <id>

---

Key Scripts

| Script | Purpose | |--------|---------| | ensure-server.sh | Start dev server if not running | | ensure-worker.sh | Kill old workers, start fresh one | | kill-worker.sh | Kill current project's worker | | kill-all-workers.sh | Kill all workers (--include-server option) | | find-stalled-workflows.sh | Detect stalled workflows | | analyze-workflow-error.sh | Extract errors from history | | wait-for-workflow-status.sh | Block until status reached | | get-workflow-result.sh | Get workflow output |

See references/tool-reference.md for full details.

---

References (Load When Needed)

| Reference | When to Read | |-----------|--------------| | references/concepts.md | Understanding workflow vs activity tasks, component architecture | | references/troubleshooting.md | Workflow stalled, failed, or misbehaving - decision tree and fixes | | references/error-reference.md | Looking up specific error types and recovery steps | | references/tool-reference.md | Script options and worker management details | | references/interactive-workflows.md | Signals, updates, queries for human-in-the-loop workflows | | references/logs.md | Log file locations and search commands |

---

Critical Rules

1. Always kill workers when done - Don't leave stale workers running
2. One worker instance only - Multiple workers cause non-determinism
3. Capture workflow_id - You need it for all monitoring/troubleshooting
4. Verify results - COMPLETED status doesn't mean correct result; check payload
5. Non-determinism: analyze first - Use analyze-workflow-error.sh to understand the mismatch. If accidental: fix code to match history. If intentional v2 change: terminate and start fresh. See references/troubleshooting.md