flow-validation-checklist

name	flow-validation-checklist
description	Complete migration validation checklist for Flow to Output SDK. Use after migration to verify completeness and correctness.
allowed-tools	["Bash","Read","Grep","Glob"]

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 @outputai/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 @outputai/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 ([e-mail])

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 @outputai/core
• step() and workflow() imported from @outputai/core
• LLM calls use generateText() from @outputai/llm (with Output.object() for structured output)
• ValidationError/FatalError imported from @outputai/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 "@outputai/core" src/workflows/my_workflow/
grep -r "@outputai/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 [e-mail]
• 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