overlay.yaml
GitHubname: workflow
description: Vercel Workflow DevKit (WDK) expert guidance. Use when building durable workflows, long-running tasks, API routes or agents that need pause/resume, retries, step-based execution, or crash-safe orchestration with Vercel Workflow.
metadata:
priority: 9
docs:
- "https://vercel.com/docs/workflow"
- "https://useworkflow.dev"
sitemap: "https://vercel.com/sitemap/docs.xml"
pathPatterns:
- 'lib/workflow/**'
- 'src/lib/workflow/**'
- 'lib/workflow.*'
- 'src/lib/workflow.*'
- 'workflow.*'
- '*workflow*'
importPatterns:
- '@vercel/workflow'
- 'workflow'
- '@workflow/*'
- '*workflow*'
bashPatterns:
- '\bnpm\s+(install|i|add)\s+[^\n]*@vercel/workflow\b'
- '\bpnpm\s+(install|i|add)\s+[^\n]*@vercel/workflow\b'
- '\bbun\s+(install|i|add)\s+[^\n]*@vercel/workflow\b'
- '\byarn\s+add\s+[^\n]*@vercel/workflow\b'
- '\bnpm\s+(install|i|add)\s+[^\n]*\bworkflow\b'
- '\bpnpm\s+(install|i|add)\s+[^\n]*\bworkflow\b'
- '\bbun\s+(install|i|add)\s+[^\n]*\bworkflow\b'
- '\byarn\s+add\s+[^\n]*\bworkflow\b'
- '\bnpm\s+(install|i|add)\s+[^\n]*@workflow/'
- '\bpnpm\s+(install|i|add)\s+[^\n]*@workflow/'
- '\bbun\s+(install|i|add)\s+[^\n]*@workflow/'
- '\byarn\s+add\s+[^\n]*@workflow/'
- '\bnpx\s+workflow(?:@latest)?\b'
- '\bbunx\s+workflow(?:@latest)?\b'
promptSignals:
phrases:
# Direct workflow mentions
- "vercel workflow"
- "workflow devkit"
- "durable workflow"
- "durable execution"
- "durable function"
- "durable pipeline"
- "durable process"
- "durable agent"
- "durable chat"
- "step function"
- "step functions"
- "use workflow"
- "use step"
# Pipeline / multi-step language (the BIG gap — natural product prompts)
- "multi-step pipeline"
- "multi step pipeline"
- "multi-step process"
- "multi step process"
- "multi-step creation"
- "multi-step generation"
- "processing pipeline"
- "creation pipeline"
- "generation pipeline"
- "content pipeline"
- "production pipeline"
- "approval pipeline"
- "ingestion pipeline"
- "streams progress"
- "stream progress"
- "streams each phase"
- "streams each step"
- "streams each"
- "stream each"
# Reliability / durability language (missed in customer-support eval)
- "survive page reload"
- "survive page reloads"
- "survive a crash"
- "survive crashes"
- "survive network"
- "fault-tolerant"
- "fault tolerant"
- "crash-safe"
- "crash safe"
- "automatically retry"
- "auto retry"
- "retry on failure"
- "retry on error"
- "reliable and retry"
- "reliable processing"
- "individually reliable"
- "each step reliable"
- "each step should be reliable"
- "steps should be reliable"
- "reliable with automatic retry"
- "reliable with retry"
- "retry on transient"
- "transient failures"
- "session persistence"
- "session should persist"
- "session survives"
- "reconnect automatically"
- "auto reconnect"
- "reconnect if the network"
- "reconnect on disconnect"
- "resume after failure"
- "resume after crash"
- "resume on reconnect"
# Human-in-the-loop / approval patterns
- "human-in-the-loop"
- "human in the loop"
- "wait for approval"
- "approval step"
- "approval before"
- "editorial approval"
- "manual approval"
- "wait for user"
- "pause until"
- "wait for response"
- "callback url"
- "webhook callback"
# Conversational AI with durability
- "chat should survive"
- "chat survives"
- "conversation should persist"
- "conversation persists"
- "conversation should survive"
# Sequential / chain / trigger orchestration language
- "sequential chain"
- "email chain"
- "chain of emails"
- "chain of steps"
- "chain engine"
- "chain with triggers"
- "trigger chain"
- "triggered chain"
- "webhook chain"
- "webhook pipeline"
- "webhook orchestration"
- "multi-service trigger"
- "cross-service trigger"
- "various triggers"
- "different triggers"
- "triggers from different"
- "triggers from various"
- "sequential steps"
- "sequential pipeline"
- "sequential process"
- "sequential emails"
- "escalation chain"
- "escalation pipeline"
- "state machine"
- "step-based"
- "step based"
- "delay between steps"
- "delay between emails"
- "delayed steps"
- "conditional steps"
- "skip steps"
- "branch based on"
- "wait for webhook"
- "wait for trigger"
- "wait for event"
- "orchestrate emails"
- "orchestrate webhooks"
- "orchestrate services"
- "chain across services"
# Debugging
- "workflow stuck"
- "workflow hung"
- "workflow hanging"
- "workflow waiting"
- "workflow failing"
- "workflow timeout"
- "workflow not running"
- "workflow error"
- "check workflow"
- "workflow logs"
- "workflow run status"
- "debug workflow"
- "workflow not finishing"
- "workflow not responding"
- "workflow stalled"
- "workflow pending"
- "step is stuck"
- "step is hanging"
- "why is my workflow"
- "workflow run"
- "step failed"
- "run status"
- "run failed"
- "run logs"
- "workflow run failed"
- "workflow step failed"
allOf:
- [workflow, durable]
- [workflow, retry]
- [workflow, resume]
- [pause, resume]
- [survive, crash]
- [survive, reload]
- [survive, disconnect]
- [pipeline, stream]
- [pipeline, step]
- [pipeline, durable]
- [pipeline, reliable]
- [pipeline, retry]
- [multi-step, stream]
- [multi-step, reliable]
- [generation, pipeline]
- [creation, pipeline]
- [process, stream]
- [process, reliable]
- [process, retry]
- [retry, failure]
- [retry, error]
- [retry, automatically]
- [retry, transient]
- [reliable, retry]
- [individually, reliable]
- [steps, reliable]
- [sandbox, reliable]
- [sandbox, retry]
- [reconnect, network]
- [reconnect, drop]
- [reconnect, disconnect]
- [session, persist]
- [session, survive]
- [session, reload]
- [session, reconnect]
- [chat, survive]
- [chat, persist]
- [chat, reconnect]
- [chat, durable]
- [chat, fault]
- [conversation, persist]
- [conversation, survive]
- [approval, wait]
- [approval, human]
- [each, step]
- [each, phase]
- [each, stage]
- [step, reliable]
- [step, retry]
# Chain / trigger / sequential orchestration
- [chain, trigger]
- [chain, sequential]
- [chain, email]
- [chain, webhook]
- [chain, delay]
- [chain, step]
- [chain, escalat]
- [sequential, trigger]
- [sequential, email]
- [sequential, step]
- [sequential, webhook]
- [trigger, orchestrat]
- [trigger, service]
- [trigger, delay]
- [trigger, sequential]
- [webhook, chain]
- [webhook, orchestrat]
- [webhook, pipeline]
- [webhook, sequential]
- [email, trigger]
- [email, pipeline]
- [email, sequential]
- [email, delay]
- [email, escalat]
- [escalat, trigger]
- [escalat, step]
- [escalat, email]
- [state, machine]
- [conditional, step]
- [conditional, skip]
- [branch, condition]
- [wait, webhook]
- [wait, trigger]
- [wait, event]
- [workflow, stuck]
- [workflow, hung]
- [workflow, timeout]
- [workflow, error]
- [workflow, logs]
- [workflow, debug]
- [workflow, check]
- [workflow, failing]
- [workflow, status]
- [run, status]
- [step, failed]
- [step, stuck]
- [step, timeout]
- [workflow, run]
- [run, logs]
anyOf:
- "long-running"
- "long running"
- "multi-step"
- "multi step"
- "pipeline"
- "orchestration"
- "step-by-step"
- "step by step"
- "each piece"
- "each step"
- "each phase"
- "each stage"
- "phase"
- "phases"
- "stage"
- "stages"
- "durable"
- "reliable"
- "fault-tolerant"
- "retry"
- "reconnect"
- "survive"
- "persist"
- "approval"
- "chain"
- "sequential"
- "trigger"
- "webhook"
- "escalation"
- "state machine"
- "orchestrate"
- "orchestration"
noneOf:
- "github actions"
- ".github/workflows"
- "ci workflow"
- "aws step functions"
minScore: 4
validate:
-
pattern: experimental_createWorkflow
message: 'experimental_createWorkflow is now stable — use createWorkflow from @vercel/workflow. Run npx @ai-sdk/codemod v6 for automated migration.'
severity: error
upgradeToSkill: workflow
upgradeWhy: 'Guides migration from experimental_createWorkflow to the stable createWorkflow API and then to the "use workflow" directive.'
-
pattern: from\s+['"]@vercel/workflow['"]
message: 'Workflow DevKit requires AI Gateway OIDC setup — ensure vercel link + vercel env pull for VERCEL_OIDC_TOKEN'
severity: recommended
-
pattern: setTimeout|setInterval
message: 'setTimeout/setInterval are not available in workflow sandbox scope — use sleep() from "workflow" for delays'
severity: error
skipIfFileContains: "use step"
-
pattern: context\.run\s*\(
message: 'context.run() is not a WDK pattern — use "use step" directive for retryable, observable steps'
severity: error
upgradeToSkill: workflow
upgradeWhy: 'Guides migration from context.run() to the "use step" directive for durable, retryable workflow steps.'
-
pattern: \brequire\s*\(
message: 'require() is not available in workflow sandbox scope — use ESM imports and move Node.js logic into "use step" functions'
severity: error
skipIfFileContains: "use step"
-
pattern: getWritable\(\)
message: 'getWritable() must only be called inside "use step" functions — workflow sandbox scope does not support it'
severity: recommended
skipIfFileContains: "use step"
-
pattern: createWorkflow\s*\(
message: 'createWorkflow() is the legacy API — use the "use workflow" directive on an async function instead'
severity: error
upgradeToSkill: workflow
upgradeWhy: 'Guides migration from createWorkflow() function API to the "use workflow" directive pattern.'
skipIfFileContains: experimental_createWorkflow
-
pattern: streamObject\s*\(
message: 'streamObject() was removed in AI SDK v6 — use streamText() with output: Output.object() instead'
severity: error
upgradeToSkill: ai-sdk
upgradeWhy: 'Guides migration from streamObject to streamText + Output.object() with correct v6 streaming patterns.'
-
pattern: await\s+\w+Workflow\s*\(
message: 'Do not call workflow functions directly — use start() from "workflow/api" to register the run and get a runId'
severity: recommended
skipIfFileContains: "use workflow"
-
pattern: \bfetch\s*\(
message: 'Native fetch() is not available in workflow sandbox scope — import fetch from "workflow" or move the call into a "use step" function'
severity: recommended
skipIfFileContains: "use step"
-
pattern: '"use step"'
message: "Workflow steps should include console.log or structured logging for observability — add logging at step entry/exit to debug hangs"
severity: warn
skipIfFileContains: "console\\.(log|warn|error|info)"
-
pattern: '"use workflow"'
message: "Workflow files should import and use logging — add console.log or a logger at key execution points for debugging"
severity: warn
skipIfFileContains: "console\\.(log|warn|error|info)"
chainTo:
-
pattern: 'DurableAgent|@workflow/ai'
targetSkill: ai-sdk
message: 'DurableAgent detected without AI SDK context — loading AI SDK guidance for tool calling, Agent class, and model configuration.'
skipIfFileContains: 'from\s+[''"]ai[''"]|@ai-sdk/|streamText|generateText'
-
pattern: 'process\.env\.(OPENAI_API_KEY|ANTHROPIC_API_KEY)|from\s+[''"]@ai-sdk/(anthropic|openai)[''""]'
targetSkill: ai-gateway
message: 'Direct provider API key in workflow — loading AI Gateway guidance for OIDC auth (required for WDK AI steps).'
skipIfFileContains: 'gateway\(|@ai-sdk/gateway|VERCEL_OIDC'
-
pattern: 'setTimeout\s*\(|setInterval\s*\('
targetSkill: vercel-functions
message: 'Timer-based delay in workflow code — use sleep() from "workflow" instead of setTimeout/setInterval. Loading Vercel Functions guidance.'
skipIfFileContains: 'from\s+[''"]workflow[''"].*sleep|sleep\s*\('
retrieval:
aliases:
- durable workflow
- long running task
- step function
- orchestration
intents:
- build workflow
- add retry logic
- create durable task
- implement step function
entities:
- Workflow DevKit
- WDK
- step
- pause/resume
- durable