Migration Validation Checklist

Overview

This skill provides a comprehensive checklist to validate a completed Flow to Output SDK migration. Use this after migration to ensure nothing was missed.

When to Use This Skill

After Migration:

• Verifying migration completeness
• Before marking migration as done
• During code review of migrated workflow

Complete Validation Checklist

1. Type Safety

• [ ] All step Input/Output interfaces defined in types.ts
• [ ] Workflow input/output schemas defined with Zod
• [ ] Steps use typed input parameters
• [ ] Zod schemas match original type definitions
• [ ] All z imports from @output.ai/core (not zod)

Validation Commands:

# Check for wrong zod imports
grep -r "from 'zod'" src/workflows/my_workflow/
grep -r 'from "zod"' src/workflows/my_workflow/

# Should return nothing - all zod should be from @output.ai/core

# Verify types.ts has Zod schemas
grep -c "z.object" src/workflows/my_workflow/types.ts

2. Template & Prompt Conversion

• [ ] All prompts extracted to .prompt files
• [ ] YAML frontmatter includes provider and model
• [ ] Template conditionals use Liquid.js ({% if %} not {{#if}})
• [ ] Variable spacing correct ({{ var }} not {{var}})
• [ ] Boolean template variables handled as strings
• [ ] Prompt files follow naming convention (name@version.prompt)

Validation Commands:

# Check for remaining Handlebars syntax
grep -r "{{#if" src/workflows/my_workflow/
grep -r "{{/if}}" src/workflows/my_workflow/

# Should return nothing

# Check for variables without spaces
grep -r "{{[^{]" src/workflows/my_workflow/*.prompt 2>/dev/null | grep -v "{{ "

# Should return nothing - all variables should have spaces

# List all prompt files
ls src/workflows/my_workflow/*.prompt

# Verify frontmatter in each
head -10 src/workflows/my_workflow/*.prompt

3. API & Imports

• [ ] All files import z from @output.ai/core
• [ ] step() and workflow() imported from @output.ai/core
• [ ] LLM calls use generateText() or generateObject() from @output.ai/llm
• [ ] ValidationError/FatalError imported from @output.ai/core
• [ ] No leftover Flow SDK imports

Validation Commands:

# Check for Flow SDK imports
grep -r "@flow/sdk" src/workflows/my_workflow/
grep -r "WorkflowScope" src/workflows/my_workflow/

# Should return nothing

# Verify correct imports
grep -r "@output.ai/core" src/workflows/my_workflow/
grep -r "@output.ai/llm" src/workflows/my_workflow/

4. File Structure

• [ ] workflow.ts contains workflow definition with export default
• [ ] steps.ts contains all step definitions
• [ ] types.ts contains Input/Output interfaces and Zod schemas
• [ ] Prompt files named name@version.prompt
• [ ] No leftover activities.ts (renamed to steps.ts)
• [ ] No leftover prompts.ts or prompts.xml
• [ ] File imports have .js extension

Validation Commands:

# Check file structure
ls -la src/workflows/my_workflow/

# Expected files:
# - workflow.ts
# - steps.ts
# - types.ts
# - *.prompt files
# - scenarios/ directory (optional)

# Check for leftover files
ls src/workflows/my_workflow/activities.ts 2>/dev/null
ls src/workflows/my_workflow/prompts.ts 2>/dev/null
ls src/workflows/my_workflow/prompts.xml 2>/dev/null

# Should all return "No such file"

# Check import extensions
grep -r "from './" src/workflows/my_workflow/*.ts | grep -v ".js'"

# Should return nothing - all local imports should end with .js

5. Workflow Definition

• [ ] Workflow uses workflow() function (not class)
• [ ] Workflow has name property
• [ ] Workflow has description property
• [ ] Workflow uses export default
• [ ] Workflow name matches legacy name (if required)

Validation Commands:

# Check workflow definition
grep -A10 "export default workflow" src/workflows/my_workflow/workflow.ts

# Verify no class-based workflow
grep "class.*Workflow" src/workflows/my_workflow/workflow.ts

# Should return nothing

6. Step Definitions

• [ ] All activities converted to steps
• [ ] Steps use step() function
• [ ] Steps have inputSchema defined
• [ ] Steps use object parameters (not direct parameters)
• [ ] Step names are descriptive

Validation Commands:

# List all steps
grep "export const.*= step" src/workflows/my_workflow/steps.ts

# Verify inputSchema for each step
grep -c "inputSchema:" src/workflows/my_workflow/steps.ts

7. Error Handling

• [ ] No try-catch blocks wrapping step calls in workflow
• [ ] ValidationError used for validation failures
• [ ] FatalError used for unrecoverable errors
• [ ] Errors propagate naturally (not re-wrapped)

Validation Commands:

# Check for try-catch in workflow
grep -A20 "fn: async" src/workflows/my_workflow/workflow.ts | grep "try {"

# Should return nothing or minimal results

8. Business Logic

• [ ] Original workflow logic preserved
• [ ] All activities converted to steps
• [ ] Parameter passing maintains data flow
• [ ] Conditional logic intact
• [ ] Loop logic intact
• [ ] External API calls preserved

Manual Review:

• Compare step-by-step execution flow
• Verify data transformations
• Check edge case handling

9. ESLint Compliance

• [ ] npm run lint passes
• [ ] Single quotes used
• [ ] Spaces in brackets and parentheses
• [ ] No trailing commas
• [ ] Proper line length

Validation Commands:

# Run lint
npm run lint -- src/workflows/my_workflow/

# Should pass with no errors

10. Runtime Validation

• [ ] Workflow builds successfully
• [ ] Workflow runs with test input
• [ ] Output matches expected format
• [ ] No runtime errors

Validation Commands:

# Build
npm run output:workflow:build

# Run with test input
npx output workflow run my_workflow --input '{"testKey": "testValue"}'

Quick Validation Script

Run this to check common issues:

#!/bin/bash
WORKFLOW_PATH="src/workflows/my_workflow"

echo "=== Migration Validation ==="

echo -e "\n1. Checking for wrong zod imports..."
grep -r "from 'zod'" $WORKFLOW_PATH && echo "FAIL: Found direct zod imports" || echo "PASS"

echo -e "\n2. Checking for Handlebars syntax..."
grep -r "{{#if" $WORKFLOW_PATH && echo "FAIL: Found Handlebars syntax" || echo "PASS"

echo -e "\n3. Checking for Flow SDK imports..."
grep -r "@flow/sdk" $WORKFLOW_PATH && echo "FAIL: Found Flow SDK imports" || echo "PASS"

echo -e "\n4. Checking for class-based workflow..."
grep "class.*Workflow" $WORKFLOW_PATH/workflow.ts && echo "FAIL: Found class-based workflow" || echo "PASS"

echo -e "\n5. Checking for try-catch in workflow..."
grep -A20 "fn: async" $WORKFLOW_PATH/workflow.ts | grep "try {" && echo "WARN: Found try-catch" || echo "PASS"

echo -e "\n6. Checking import extensions..."
grep "from './" $WORKFLOW_PATH/*.ts | grep -v ".js'" && echo "FAIL: Missing .js extension" || echo "PASS"

echo -e "\n7. Verifying file structure..."
[ -f "$WORKFLOW_PATH/workflow.ts" ] && echo "PASS: workflow.ts exists" || echo "FAIL: workflow.ts missing"
[ -f "$WORKFLOW_PATH/steps.ts" ] && echo "PASS: steps.ts exists" || echo "FAIL: steps.ts missing"
[ -f "$WORKFLOW_PATH/types.ts" ] && echo "PASS: types.ts exists" || echo "FAIL: types.ts missing"

echo -e "\n=== Validation Complete ==="

Related Skills

• flow-error-zod-import - Fix zod import issues
• flow-error-try-catch-removal - Remove try-catch antipattern
• flow-error-eslint-compliance - Fix ESLint issues
• flow-conventions-folder-structure - Folder structure reference