utun2/.opencode/context/development/ai/mastra-ai/guides/workflow-step-structure.md

Guide: Workflow Step Structure

Purpose: Standardized pattern for defining maintainable and testable workflow steps.

Last Updated: 2026-01-09

---

Core Idea

Workflow steps should be self-contained units that encapsulate their input/output schemas and execution logic. For complex workflows, steps should be moved to a dedicated steps/ directory and grouped by phase.

Key Points

• Directory Structure: Group steps by phase (e.g., steps/phase1-load.ts, steps/phase2-process.ts).
• Schema Centralization: Define shared schemas (like workflowStateSchema) in a schemas.ts file within the steps directory.
• Explicit State: Use stateSchema in createStep to ensure type safety when accessing the global workflow state.
• Tool Delegation: Steps should primarily act as orchestrators, delegating heavy lifting to Tools.
• Logging: Include clear console logs at the start and end of each step for easier debugging.

Quick Example

// src/mastra/workflows/v3/steps/phase1.ts
export const myStep = createStep({
  id: 'my-step-id',
  inputSchema: z.object({ ... }),
  outputSchema: z.object({ ... }),
  stateSchema: workflowStateSchema,
  execute: async ({ inputData, state, mastra }) => {
    console.log('🚀 Starting myStep...');
    const result = await myTool.execute(inputData, { mastra });
    return result;
  },
});

Reference: src/mastra/workflows/v3/steps/ Related:

• concepts/workflows.md
• guides/modular-building.md