Agent skill

flow-validation-checklist

Complete migration validation checklist for Flow to Output SDK. Use after migration to verify completeness and correctness.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/flow-validation-checklist-growthxai-output-claude-plugin

SKILL.md

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:

bash
# 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
bash
# 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:

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

# Should return nothing
bash
# 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
bash
# 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:

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

# Should return nothing
bash
# 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:

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

# Expected files:
# - workflow.ts
# - steps.ts
# - types.ts
# - *.prompt files
# - scenarios/ directory (optional)
bash
# 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"
bash
# 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:

bash
# Check workflow definition
grep -A10 "export default workflow" src/workflows/my_workflow/workflow.ts
bash
# 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:

bash
# List all steps
grep "export const.*= step" src/workflows/my_workflow/steps.ts
bash
# 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:

bash
# 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:

bash
# 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:

bash
# 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:

bash
#!/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

Didn't find tool you were looking for?

Be as detailed as possible for better results