mastra-vertical-organization

ffMathy's avatarfrom ffMathy

Guide for organizing code by business verticals in the Mastra project. Use this when creating new features or reorganizing code structure.

⭐2stars🔀0forks📁View on GitHub🕐Updated Jan 10, 2026

When & Why to Use This Skill

This Claude skill provides a comprehensive framework for implementing vertical organization within Mastra projects. It guides developers in structuring code by business domain rather than technical layers, ensuring high cohesion, clear ownership, and scalable directory management for AI agents, tools, and workflows.

Use Cases

  • Architecting new Mastra projects from scratch using domain-driven directory structures to ensure long-term maintainability.
  • Refactoring monolithic or disorganized codebases into modular business verticals to improve team collaboration and code navigation.
  • Standardizing naming conventions and export patterns for agents and tools across large-scale development teams.
  • Determining the optimal time to split complex features into sub-verticals as business logic grows in complexity.
namemastra-vertical-organization
descriptionGuide for organizing code by business verticals in the Mastra project. Use this when creating new features or reorganizing code structure.

Mastra Vertical Organization

This project uses vertical organization where code is grouped by business domain, not technical layer.

Core Principle

Group related agents, tools, and workflows together by business vertical (weather, shopping, cooking) rather than by type (all agents in one folder, all tools in another).

Directory Structure Rules

Simple Vertical

For straightforward features with 1-2 agents:

mastra/verticals/[vertical-name]/
├── agent.ts          # Single general-purpose agent
├── tools.ts          # All tools for this vertical
├── workflows.ts      # All workflows
└── index.ts          # Export everything

Example: weather/ (1 agent, 4 tools, 1 workflow)

Moderate Vertical

For features with 2-3 specialized agents:

mastra/verticals/[vertical-name]/
├── agents.ts         # Multiple agents (note plural)
├── tools.ts          # Shared tools
├── workflows.ts      # Workflows
└── index.ts          # Exports

Example: shopping/ (2 agents, multiple tools)

Complex Vertical with Sub-Verticals

For features with 4+ agents or multiple specialized flows:

mastra/verticals/[vertical-name]/
├── agent.ts                    # General vertical agent
├── tools.ts                    # Shared tools
├── [sub-vertical-name]/        # Specialized sub-vertical
│   ├── agents.ts              # Specialized agents
│   ├── workflows.ts           # Specialized workflows
│   └── index.ts               # Sub-vertical exports
└── index.ts                   # Main vertical exports

Example: cooking/meal-planning/ (3 specialized agents)

Naming Conventions

Files

  • Single agent: agent.ts
  • Multiple agents: agents.ts
  • Tools: Always tools.ts
  • Workflows: Always workflows.ts
  • Exports: Always index.ts

Agents

  • General: [vertical]Agent (e.g., weatherAgent)
  • Specialized: [vertical][Purpose]Agent (e.g., mealPlanSelectorAgent)

Tools

  • Tool IDs: camelCase matching variable name (e.g., getCurrentWeather)
  • Tool exports: Use variable name directly as shorthand
  • Collection: [vertical]Tools (e.g., weatherTools)

Workflows

  • Workflow IDs: camelCase (e.g., weatherMonitoringWorkflow)

Export Pattern

Each vertical's index.ts:

// [Vertical] vertical exports
export { myAgent } from './agent';
export { myTools } from './tools';
export { myWorkflow } from './workflows';

Main verticals/index.ts:

export * from './weather';
export * from './shopping';
export * from './cooking';

When to Split

Create sub-verticals when:

  • More than 4 specialized agents in one vertical
  • Multiple distinct workflows sharing some tools
  • Complex business processes with sub-processes
  • Clear logical separation within the vertical

Tool Organization

  1. Vertical Ownership: Tools belong to exactly one vertical
  2. No Cross-Vertical: Don't share tools across verticals
  3. Shared Tools: If truly shared, create a shared/ vertical

Benefits

  • High Cohesion: Related code stays together
  • Business Alignment: Matches actual domain
  • Clear Ownership: Each vertical has focused scope
  • Easy Navigation: Find all code for a feature in one place