output-dev-step-function

Creating Step Functions

Overview

This skill documents how to create step functions in steps.ts for Output SDK workflows. Steps are where all I/O operations happen - HTTP requests, LLM calls, database operations, file system access, etc.

When to Use This Skill

• Implementing I/O operations for a workflow
• Adding HTTP client integrations
• Implementing LLM-powered steps
• Handling errors with FatalError and ValidationError
• Creating reusable step components

File Organization

Option 1: Flat File (Default)

For smaller workflows, use a single steps.ts file:

src/workflows/{workflow-name}/
├── workflow.ts
├── steps.ts         # All steps in one file
├── types.ts
└── ...

Option 2: Folder-Based (Large workflows)

For larger workflows with many steps, use a steps/ folder:

src/workflows/{workflow-name}/
├── workflow.ts
├── steps/           # Steps split into individual files
│   ├── fetch_data.ts
│   ├── process.ts
│   └── validate.ts
├── types.ts
└── ...

Component Location Rules

Important: step() calls MUST be in files containing 'steps' in the path:

• src/workflows/my_workflow/steps.ts ✓
• src/workflows/my_workflow/steps/fetch_data.ts ✓
• src/shared/steps/common_steps.ts ✓
• src/workflows/my_workflow/helpers.ts ✗ (cannot contain step() calls)

Activity Isolation Constraints

Steps are Temporal activities with strict import rules to ensure deterministic replay.

Steps CAN import from:

• Local workflow files: ./utils.js, ./types.js, ./helpers.js
• Local subdirectories: ./clients/pokeapi.js, ./lib/helpers.js
• Shared utilities: ../../shared/utils/*.js
• Shared clients: ../../shared/clients/*.js
• Shared services: ../../shared/services/*.js

Steps CANNOT import:

• Other step files (even shared steps - workflows import those)
• Evaluator files
• Workflow files

Example of WRONG imports:

// WRONG - steps cannot import other steps
import { otherStep } from '../../shared/steps/other.js'; // ✗
import { anotherStep } from './other_steps.js'; // ✗