Building a dev assistant

In this tutorial, you'll build a complete development assistant that combines all workspace features:

Filesystem for file management
Sandbox for code execution
Skills for coding standards
Search for finding examples

You'll set up a workspace with a sample project and add coding standards as a skill. Then you'll create an agent that writes code following TDD practices. By the end, the agent can read existing code and write new implementations, then run tests in a sandbox and iterate based on the results.

Prerequisites

Node.js v22.13.0 or later installed
An API key from a supported Model Provider
An existing Mastra project (Follow the installation guide to set up a new project)

Install vitest

The dev assistant will use Vitest to run tests inside the workspace sandbox. Install it as a dev dependency in your project:

npm install -D vitest

Set up the workspace

The workspace uses a local filesystem to manage documentation files. The agent reads and writes files within the workspace directory. In your src/mastra/index.ts file, import the Workspace, LocalFilesystem, and LocalSandbox classes.

Additionally, enable BM25 search indexing and load skills from the skills directory.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { resolve } from 'node:path'
import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: resolve(import.meta.dirname, '../../workspace') }),
  sandbox: new LocalSandbox({ workingDirectory: resolve(import.meta.dirname, '../../workspace') }),
  skills: ['skills'],
  bm25: true,
  autoIndexPaths: ['docs', 'src'],
})
export const mastra = new Mastra({
  workspace,
})

At the root of your project, create a new folder called workspace. This is where all files will be stored and managed by the agent.

Add sample project files

The workspace uses the following folder structure:

workspace/src/: Source code for the sample project
workspace/tests/: Test files
workspace/docs/: Project documentation
workspace/skills/: Coding standards and guidelines as Agent Skills

Get started by creating a workspace/src/utils/string-helpers.ts file with some utility functions, and a corresponding test file in workspace/tests/string-helpers.test.ts.

workspace/src/utils/string-helpers.ts

export function capitalize(str: string): string {
  if (!str) return str
  return str.charAt(0).toUpperCase() + str.slice(1)
}
 
export function slugify(str: string): string {
  return str
    .toLowerCase()
    .replace(/[^\w\s-]/g, '')
    .replace(/\s+/g, '-')
}

workspace/tests/string-helpers.test.ts

import { describe, it, expect } from 'vitest'
import { capitalize, slugify } from '../src/utils/string-helpers'
 
describe('String Helpers', () => {
  describe('capitalize', () => {
    it('capitalizes first letter', () => {
      expect(capitalize('hello')).toBe('Hello')
    })
  })
 
  describe('slugify', () => {
    it('converts to lowercase and replaces spaces', () => {
      expect(slugify('Hello World')).toBe('hello-world')
    })
  })
})

Create a skill definition at workspace/skills/coding-standards/SKILL.md. This tells the agent how to write and test code:

workspace/skills/coding-standards/SKILL.md

---
name: coding-standards
description: Project coding standards and testing guidelines
---
 
# Coding Standards
 
## Code quality
 
- Functions under 50 lines
- Use descriptive variable names
- Always add TypeScript types
 
## Testing
 
- Test all exported functions
- Use AAA pattern: Arrange, Act, Assert
- Cover happy paths and edge cases
 
## Before committing
 
1. Write implementation
2. Write comprehensive tests
3. Run tests: `npm test`
4. All tests must pass

Create a reference file at workspace/skills/coding-standards/references/testing-guide.md with detailed testing patterns:

workspace/skills/coding-standards/references/testing-guide.md

# Testing Guide
 
## AAA pattern
 
```typescript
it('descriptive test name', () => {
  // Arrange: Set up test data
  const input = 'test'
 
  // Act: Execute the function
  const result = doSomething(input)
 
  // Assert: Verify the result
  expect(result).toBe('expected')
})
```
 
## What to test
 
- Happy paths (normal inputs)
- Edge cases (empty, null, boundary values)
- Error cases (invalid inputs, exceptions)

Create the dev assistant

With the workspace set up, it's time to create the development assistant agent. This agent will have instructions for adding new features using test-driven development (TDD).

Create a new file src/mastra/agents/dev-assistant.ts and define the agent:

src/mastra/agents/dev-assistant.ts

import { Agent } from '@mastra/core/agent'
 
export const devAssistant = new Agent({
  id: 'dev-assistant',
  name: 'Dev Assistant',
  instructions: `You are a development assistant.
 
When adding features:
1. Activate 'coding-standards' skill
2. Search workspace for similar code examples
3. Write the implementation following standards
4. Write comprehensive tests. Leave existing tests in place, only add your new tests
5. Execute the command \`npx vitest run\` to validate that all tests pass
6. Update documentation if needed
 
For every new feature: Write code → Write tests → Run tests → Update docs
 
Always explain your reasoning and steps.`,
  model: 'openai/gpt-5.6-sol',
})

Define the agent by importing it inside src/mastra/index.ts and registering it with the Mastra instance:

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { resolve } from 'node:path'
import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
import { devAssistant } from './agents/dev-assistant'
 
const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: resolve(import.meta.dirname, '../../workspace') }),
  sandbox: new LocalSandbox({ workingDirectory: resolve(import.meta.dirname, '../../workspace') }),
  skills: ['skills'],
  bm25: true,
  autoIndexPaths: ['docs', 'src'],
})
 
export const mastra = new Mastra({
  workspace,
  agents: { devAssistant },
})

Test the assistant

Start Studio and interact with the agent to see it in action.

npm run dev

Open localhost:4111 and navigate to the dev assistant.

Try asking the agent to add a new function using TDD:

Add a 'truncate' function to string-helpers.ts that shortens strings to a max length. Add '...' if truncated.
 
Follow TDD: write tests first, then implementation.

Since agent responses are non-deterministic, the exact output will vary. However, you should see the agent follow a process similar to this:

Activate the coding-standards skill
Search the workspace for similar code patterns

Write tests first, for example:

describe('truncate', () => {
  it('truncates long strings', () => {
    expect(truncate('Hello World', 5)).toBe('He...')
  })
 
  it('keeps short strings unchanged', () => {
    expect(truncate('Hi', 10)).toBe('Hi')
  })
 
  it('handles edge cases', () => {
    expect(truncate('', 5)).toBe('')
  })
})

Write the implementation, for example:

export function truncate(str: string, maxLength: number): string {
  if (!str || maxLength < 0) return str
  if (str.length <= maxLength) return str
  if (maxLength === 0) return '...'
  return str.slice(0, maxLength - 3) + '...'
}

Run tests and verify they pass

Next steps

You can extend this assistant to:

Add more skills for different languages or frameworks
Create specialized agents for backend, frontend, or DevOps
Integrate with GitHub for automated PR reviews
Build CI/CD automation
Add multi-agent workflows