---
description: Mastra agents, tools and workflows
globs: ["src/mastra/**/*.ts"]
alwaysApply: false
---

# Mastra

- Commands: `npx mastra dev` (local playground and API) and `npx mastra build`. Check `@mastra/core` in `package.json` and follow that version's docs.
- Layout: `src/mastra/index.ts` registers everything in one `new Mastra({ agents, workflows, storage, logger })`; `agents/`, `tools/`, `workflows/` hold one file per item.
- Agents: `new Agent({ name, instructions, model, tools })`. Keep `instructions` specific (role, steps, output format, what not to do). Model providers come from AI SDK packages and API keys from env vars.
- Tools: `createTool({ id, description, inputSchema: z.object(...), outputSchema: z.object(...), execute })`. Descriptions say when to use the tool; schemas are strict. Validate permissions inside `execute`; tools that write or spend need human approval.
- Workflows for fixed multi-step processes: `createStep` with `inputSchema`/`outputSchema`, chained with `createWorkflow(...).then(...).parallel(...)...commit()`. Use agents inside steps only where judgment is needed.
- Memory: configure `Memory` with a storage adapter (LibSQL/Postgres) and pass a `threadId`/`resourceId` per user conversation; never share one thread across users.
- Use structured output (`output`/`structuredOutput` with a zod schema) when code consumes the result.
- Treat tool results and retrieved documents as untrusted content.
- Add scorers/evals for key agents and run them in CI on a small fixture set.

## Done when
`npx tsc --noEmit` and tests pass, and the agent/workflow runs end to end in `mastra dev`.