Temporal Workflows skill for Claude Code

Done well means: workflow code is deterministic and only orchestrates, every side effect is an idempotent activity with an explicit timeout, every change to workflow logic ships behind a patch or a pinned Worker Deployment Version, and a replay test against real production histories passes before deploy.

Fit check

Situation	Temporal?
Multi-step process with retries, waits of minutes to months, human approval, compensation	Yes
Order fulfilment, payments orchestration, provisioning, onboarding, data pipelines with checkpoints	Yes
Fire-and-forget job that runs in seconds and can simply retry	No; a job queue is simpler (background-jobs)
Sub-millisecond request path	No; workflow start adds a round trip to the cluster
Pure event fan-out between services	No; use a broker

Workflow

- [ ] 1. Inventory SDK, server or Cloud, task queues, existing versioning approach
- [ ] 2. Draw the process: steps, waits, external messages, compensations
- [ ] 3. Write activities first: idempotent, with timeouts and non-retryable errors
- [ ] 4. Write the workflow: deterministic orchestration only
- [ ] 5. Add signals, queries, or updates for external interaction
- [ ] 6. Test with the time-skipping environment; add replay tests
- [ ] 7. Plan the deploy: patch or Worker Versioning; confirm with replay

1. Inventory

npm ls @temporalio/workflow @temporalio/worker 2>/dev/null; pip show temporalio 2>/dev/null | head -2
grep -rn "patched\|GetVersion\|deprecatePatch\|deprecate_patch" src/ | head
temporal workflow list --query 'ExecutionStatus="Running"' --limit 20

Long-running workflows already in flight constrain every change you make; count them per workflow type before editing that type.

2. Determinism rules

Workflow code is replayed from event history on any worker at any time. It must produce the same commands in the same order on every replay.

Forbidden in workflow code	Use instead
Network, database, file IO, logging to external sinks	An activity
Date.now(), time.time(), time.Now()	Workflow time (TS sandbox makes Date deterministic; Python workflow.now(); Go workflow.Now(ctx))
Random numbers, uuid4() from the stdlib	SDK deterministic helpers (TS uuid4() from @temporalio/workflow, Python workflow.uuid4() / workflow.random(), Go workflow.SideEffect)
Threads, goroutines, native select, asyncio.create_task on other loops	workflow.Go, workflow.NewSelector, Promise.all, Python asyncio.gather inside the workflow
setTimeout / sleep from the language	sleep() / workflow.sleep() / workflow.Sleep() (durable timers)
Iterating Go maps, reading env vars or global mutable state	Sorted keys; pass config as workflow input
Changing the order or type of activity calls in a running workflow	A patch or a new Worker Deployment Version

3. Activities

// activities.ts — normal Node code; may do IO
import { Context, ApplicationFailure } from "@temporalio/activity";

export async function chargeCard(input: { orderId: string; amountCents: number }) {
  const idempotencyKey = `charge-${input.orderId}`;           // stable across retries
  const res = await payments.charge({ ...input, idempotencyKey });
  if (res.declined) {
    throw ApplicationFailure.nonRetryable("card declined", "CardDeclined");
  }
  return { chargeId: res.id };
}

export async function exportRows(input: { jobId: string; fromOffset: number }) {
  const ctx = Context.current();
  let offset = ctx.info.heartbeatDetails?.offset ?? input.fromOffset;  // resume after retry
  while (offset < total) {
    await writeBatch(offset);
    offset += 1000;
    ctx.heartbeat({ offset });                                  // also delivers cancellation
  }
}

• Activities are at-least-once. Derive idempotency keys from workflow ID plus a step name and pass them to downstream APIs.
• Always set startToCloseTimeout (max time for one attempt). Add heartbeatTimeout for anything longer than about a minute and heartbeat well inside it.
• The default retry policy retries forever with exponential backoff (1 s initial, coefficient 2, capped at 100 x initial). Cap maximumAttempts or set a scheduleToCloseTimeout for calls where unbounded retry makes no sense, and list business errors in nonRetryableErrorTypes.
• Keep payloads small (each payload is limited to about 2 MB). Pass IDs or object-store keys, not files.

4. Workflow

// workflows.ts — deterministic orchestration only
import { proxyActivities, defineSignal, defineQuery, defineUpdate, setHandler, condition, sleep, log } from "@temporalio/workflow";
import type * as acts from "./activities";

const { reserveStock, releaseStock, chargeCard, refundCharge, shipOrder } = proxyActivities<typeof acts>({
  startToCloseTimeout: "30 seconds",
  retry: { maximumAttempts: 10, nonRetryableErrorTypes: ["CardDeclined", "OutOfStock"] },
});

export const cancelSignal = defineSignal("cancel");
export const statusQuery = defineQuery<string>("status");
export const addressUpdate = defineUpdate<string, [string]>("changeAddress");

export async function orderWorkflow(order: Order): Promise<string> {
  let status = "started";
  let cancelled = false;
  let address = order.address;
  setHandler(cancelSignal, () => { cancelled = true; });
  setHandler(statusQuery, () => status);
  setHandler(addressUpdate, (a) => { address = a; return address; }, {
    validator: (a) => { if (status === "shipped") throw new Error("already shipped"); },
  });

  const compensations: Array<() => Promise<unknown>> = [];
  try {
    await reserveStock(order.id, order.items);
    compensations.unshift(() => releaseStock(order.id));

    const { chargeId } = await chargeCard({ orderId: order.id, amountCents: order.total });
    compensations.unshift(() => refundCharge(chargeId));
    status = "paid";

    // wait up to 1 hour for a cancel before shipping (durable timer)
    if (await condition(() => cancelled, "1 hour")) throw new Error("cancelled by customer");

    await shipOrder(order.id, address);
    status = "shipped";
    return status;
  } catch (err) {
    log.warn("compensating", { orderId: order.id });
    for (const undo of compensations) await undo();   // compensations are activities too
    status = "compensated";
    throw err;
  }
}

Start it with a business ID so duplicates are rejected:

await client.workflow.start(orderWorkflow, {
  taskQueue: "orders",
  workflowId: `order-${order.id}`,          // dedupe: one workflow per order
  args: [order],
});

Message types:

Need	Use	Notes
Fire-and-forget input that changes state	Signal	Async, durable, no return value
Read current state	Query	Must not mutate state or call activities
Request with validation and a result	Update	Validator rejects before history is written
Start if absent, then send	Signal-with-start / update-with-start	Removes the start/send race

5. Long-running workflows

• Event history has hard limits (51,200 events or 50 MB); the server warns from about 10,240 events. Loops that run forever (subscriptions, polling, entity workflows) call continue-as-new when the SDK reports it is suggested (TS workflowInfo().continueAsNewSuggested, Python workflow.info().is_continue_as_new_suggested()), carrying state as input.
• Drain signal handlers before continuing as new, or messages received in that task are lost; wait with condition(allHandlersFinished) in TS or the equivalent.
• Child workflows partition very large fan-outs (for example 1,000 children of 1,000 activities each) and give each part its own history.

6. Changing workflow code safely

A change that alters which commands a workflow emits breaks replay of running executions (NondeterminismError / “nondeterministic workflow”). Pick one:

Option	Use when
No versioning needed	Change only affects activity implementations, or no executions of this type are running
Patching (patched("id"), workflow.patched, workflow.GetVersion)	Small logic changes; old and new paths coexist in code until old executions finish, then deprecatePatch, then remove
Worker Versioning (GA; Pinned or Auto-Upgrade per workflow type)	Frequent deploys; Pinned workflows finish on the build they started on, so no patches needed for short workflows; requires running old and new worker versions side by side (rainbow deploys)
New workflow type name	Large rewrites; route new starts to the new type and let the old drain

import { patched, deprecatePatch } from "@temporalio/workflow";
if (patched("fraud-check-before-charge")) {
  await fraudCheck(order.id);
}
// later, once no pre-patch executions remain: deprecatePatch("fraud-check-before-charge")

Auto-Upgrade workflows still need patching for incompatible changes.

7. Tests

import { TestWorkflowEnvironment } from "@temporalio/testing";
import { Worker } from "@temporalio/worker";
import { ApplicationFailure } from "@temporalio/common";

const env = await TestWorkflowEnvironment.createTimeSkipping();
const worker = await Worker.create({
  connection: env.nativeConnection,
  taskQueue: "test",
  workflowsPath: require.resolve("./workflows"),
  activities: { ...fakeActivities, chargeCard: async () => { throw ApplicationFailure.nonRetryable("x", "CardDeclined"); } },
});
await worker.runUntil(async () => {
  await expect(env.client.workflow.execute(orderWorkflow, { taskQueue: "test", workflowId: "t1", args: [order] }))
    .rejects.toThrow();
  // assert releaseStock fake was called
});
await env.teardown();

Replay tests catch non-determinism before deploy:

temporal workflow show --workflow-id order-123 --output json > histories/order-123.json

await Worker.runReplayHistory({ workflowsPath: require.resolve("./workflows") }, history);

Keep a few histories per workflow type (happy path, compensation, long wait) in the repo and replay them in CI on every workflow change.

For Python and Go equivalents of every snippet above (activities, timers, signals, updates, patching, continue-as-new, test environments, replayers), read references/sdk-cheatsheet.md when the project is not TypeScript.

Gotchas

• Importing activity implementations (not just types) into workflow files pulls Node modules into the workflow sandbox and fails the bundle.
• Python workflow files run in a sandbox; import third-party modules through workflow.unsafe.imports_passed_through().
• A workflow that catches every error and retries in a loop builds history fast; let the activity retry policy do retries.
• temporal workflow reset and terminate change running business processes; run them only with explicit user confirmation and a reason recorded.
• Sensitive data lands in event history in plain text unless a payload codec encrypts it.

Verification

1. Unit and time-skipping tests pass, including the compensation path.
2. Replay tests against stored production histories pass with the new code.
3. temporal workflow describe --workflow-id <id> on a staging run shows expected pending activities and no task failures.
4. After deploy, watch for workflow task failures with non-determinism errors; on the first one, roll back the worker and add a patch.