Temporal Workflows skill for Codex

Done well means: workflow code is pure orchestration and replays identically, every side effect lives in an idempotent activity with explicit timeouts and a bounded retry policy, business failures are modelled as non-retryable errors with compensation, histories stay small through continue-as-new, and every change to workflow logic passes replay tests against real histories before it ships.

Before changing anything

1. Read AGENTS.md, the SDK and version (@temporalio/*, temporalio for Python, go.temporal.io/sdk), worker setup, task queue names and namespace configuration.
2. Ask whether executions of the workflow are currently running in production. If yes, any change to command order needs versioning: read references/determinism.md before editing.
3. Start a local server for development: temporal server start-dev (gRPC on 7233, Web UI on 8233). Installing the CLI needs network.
4. Never cancel, terminate, reset or signal production executions without explicit user confirmation; these change real business processes.

What goes where

Code	Lives in	Rules
Sequencing, branching, waiting, timers, state	Workflow	Deterministic; no I/O, no clocks, no randomness outside SDK APIs
HTTP calls, DB writes, email, payments, file I/O	Activity	Idempotent; may run more than once
Input to start	Workflow ID + args	Workflow ID = business key (order-<id>) so duplicate starts are rejected
Large blobs	Object storage; pass a reference	Payloads are capped (about 2 MB each by default) and bloat history

Workflow and activities (TypeScript)

// activities.ts — normal Node code
export async function chargeCard(input: { orderId: string; amountCents: number }): Promise<string> {
  // Pass the idempotency key to the provider so a retried activity does not double charge.
  return payments.charge({ ...input, idempotencyKey: `charge-${input.orderId}` });
}
export async function refundCard(chargeId: string): Promise<void> { await payments.refund(chargeId); }
export async function reserveStock(orderId: string): Promise<void> { /* ... */ }
export async function releaseStock(orderId: string): Promise<void> { /* ... */ }

// workflows.ts — bundled into the workflow sandbox; import activity TYPES only
import { proxyActivities, defineSignal, defineQuery, setHandler, condition, ApplicationFailure } from '@temporalio/workflow';
import type * as activities from './activities';

const { chargeCard, refundCard, reserveStock, releaseStock } = proxyActivities<typeof activities>({
  startToCloseTimeout: '30 seconds',
  retry: {
    initialInterval: '1 second',
    backoffCoefficient: 2,
    maximumInterval: '1 minute',
    maximumAttempts: 10,
    nonRetryableErrorTypes: ['CardDeclined', 'InvalidOrder'],
  },
});

export const approveSignal = defineSignal<[boolean]>('approve');
export const statusQuery = defineQuery<string>('status');

export async function orderWorkflow(order: { id: string; amountCents: number }): Promise<string> {
  let status = 'reserving';
  let approved: boolean | undefined;
  setHandler(approveSignal, (ok) => { approved = ok; });
  setHandler(statusQuery, () => status);

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

    status = 'awaiting-approval';
    if (!(await condition(() => approved !== undefined, '24 hours')) || !approved) {
      throw ApplicationFailure.nonRetryable('Order not approved', 'NotApproved');
    }

    status = 'charging';
    const chargeId = await chargeCard({ orderId: order.id, amountCents: order.amountCents });
    compensations.unshift(() => refundCard(chargeId));

    status = 'done';
    return chargeId;
  } catch (err) {
    status = 'compensating';
    for (const undo of compensations) await undo();
    throw err;
  }
}

If the workflow can be cancelled, run compensations inside CancellationScope.nonCancellable(...) so they still execute after cancellation.

Worker and client:

const worker = await Worker.create({
  connection: await NativeConnection.connect({ address: 'localhost:7233' }),
  taskQueue: 'orders',
  workflowsPath: require.resolve('./workflows'),
  activities,
});
await worker.run();

await client.workflow.start(orderWorkflow, {
  taskQueue: 'orders',
  workflowId: `order-${order.id}`,     // business key: duplicates fail with WorkflowExecutionAlreadyStarted
  args: [order],
});

Python and Go equivalents

@workflow.defn
class OrderWorkflow:
    @workflow.run
    async def run(self, order: Order) -> str:
        await workflow.execute_activity(
            reserve_stock, order.id,
            start_to_close_timeout=timedelta(seconds=30),
            retry_policy=RetryPolicy(maximum_attempts=10, non_retryable_error_types=["InvalidOrder"]),
        )
        ...

ctx = workflow.WithActivityOptions(ctx, workflow.ActivityOptions{
    StartToCloseTimeout: 30 * time.Second,
    RetryPolicy: &temporal.RetryPolicy{MaximumAttempts: 10, NonRetryableErrorTypes: []string{"InvalidOrder"}},
})
if err := workflow.ExecuteActivity(ctx, ReserveStock, order.ID).Get(ctx, nil); err != nil {
    return "", err
}

Python workflows run in a sandbox: import activities and libraries inside with workflow.unsafe.imports_passed_through():. Go workflows must use workflow.Go, workflow.Channel and workflow.Selector, never native goroutines or select.

Timeouts and retries

Setting	Set it to	Notes
startToCloseTimeout	Max time one attempt can take, with margin	Required (or scheduleToClose); detects crashed workers
scheduleToCloseTimeout	Total budget across all retries	Use when the business has a deadline
heartbeatTimeout	A few heartbeat intervals	Long activities (over ~1 min) heartbeat with progress details
maximumAttempts	Bounded (5-20) or a schedule-to-close budget	The default retry policy retries forever
nonRetryableErrorTypes	Business failures (declined, invalid)	Retrying a declined card is pointless

Activities are at-least-once: a worker can crash after the side effect but before reporting success. Use provider idempotency keys, upserts, or check-then-act on a unique business key.

Signals, queries, updates

Need	Use
Fire-and-forget input (approval, cancel request)	Signal
Read current state, no side effects	Query (must not mutate state or call activities)
Input that needs a validated result returned to the caller	Update (with an optional validator to reject early)

Register handlers at the start of the workflow function so early signals are not lost.

Long-running workflows

• Event histories have hard limits (about 50k events or 50 MB); performance degrades well before that. Loops that run indefinitely (subscriptions, polling, entity workflows) call continueAsNew with compact state, for example when workflowInfo().continueAsNewSuggested is true or every N iterations.
• Drain signal handlers and wait for in-flight updates before continuing as new.
• Use child workflows to partition large fan-outs (thousands of activities) rather than one huge history.

Testing

• Unit-test activities as plain functions.
• Workflow tests use the time-skipping environment so sleep('24 hours') takes milliseconds: TypeScript TestWorkflowEnvironment.createTimeSkipping(), Python WorkflowEnvironment.start_time_skipping(), Go testsuite.WorkflowTestSuite with mocked activities.
• Test the unhappy paths: declined charge triggers compensation, approval timeout, worker restart mid-workflow (replay).
• Replay tests against downloaded production histories run in CI on every change to workflow code; see references/determinism.md.

Checklist

• Workflow code free of I/O, clocks, randomness and native concurrency
• Every activity idempotent with start-to-close timeout and bounded retries
• Business errors non-retryable; compensations registered after each step succeeds
• Workflow ID is a business key; payloads small
• Changes to running workflows patched; replay tests pass
• Time-skipping tests cover success, failure with compensation, and timeouts

Gotchas

• Importing an activity implementation (not just its type) into a TypeScript workflow file pulls Node modules into the sandbox bundle and fails the worker at startup.
• Changing an activity’s function name renames its activity type and breaks running executions.
• Catching all errors in a workflow and swallowing them hides cancellation; rethrow CancelledFailure (or check isCancellation).
• A workflow task timeout loop usually means blocking code or a deadlock in workflow code, not a slow activity; check the worker logs for the stack.