migrating-to-workflow-sdk

Migrating to the Workflow SDK

Use this skill when converting an existing orchestration system to the Workflow SDK.

Intake

1. Identify the source system:
   • Temporal
   • Inngest
   • Trigger.dev
   • AWS Step Functions
2. Identify the target runtime:
   • Managed hosting -> keep examples focused on start(), getRun(), hooks/webhooks, and route handlers.
   • Self-hosted -> also read references/runtime-targets.md and explicitly say the workflow/step code can stay the same, but deployment still needs a World implementation and startup bootstrap.
3. Extract the source constructs:
   • entrypoint
   • waits / timers
   • external callbacks / approvals
   • retries / failure handling
   • child workflows / fan-out
   • progress streaming
   • external side effects

Default migration rules

• Put orchestration in "use workflow" functions.
• Put side effects, SDK calls, DB calls, HTTP calls, and stream I/O in "use step" functions.
• Use sleep() only in workflow context.
• For Signals, step.waitForEvent(), and .waitForTaskToken, choose exactly one resume surface:
  • resume/internal -> createHook() + resumeHook() when the app resumes from server-side code with a deterministic business token.
  • resume/url/default -> createWebhook() when the external system needs a generated callback URL and the default 202 Accepted response is fine.
  • resume/url/manual -> createWebhook({ respondWith: 'manual' }) only when the prompt explicitly requires a custom response body, status, or headers.
  • If a callback-URL prompt does not specify response semantics, default to resume/url/default and make the assumption explicit in ## Open Questions.
• Never pair createWebhook() with resumeHook(), and never pass token: to createWebhook().
• Wrap start() and getRun() inside "use step" functions for child runs.
• Use getStepMetadata().stepId as the idempotency key for external writes.
• Use getWritable() in workflow context to obtain the stream, but interact with it (write, close) only inside "use step" functions.
• Prefer rollback stacks for multi-step compensation.
• Choose app-boundary syntax in this order:
  1. If the prompt explicitly asks for framework-agnostic app-boundary code, use plain Request / Response even when a framework like Hono is named.
  2. Otherwise, if the target framework is named, shape app-boundary examples to that framework.
  3. Otherwise, keep examples framework-agnostic with Request / Response. Do not default to Next.js-only route signatures unless Next.js is explicitly named.