Adds package-local agent instructions for Mastra Code and tightens the
root build guidance so agents avoid slow repo-wide builds.
The main intent is to make the preferred path clearer:
```sh
pnpm build:mastracode
pnpm --filter ./mastracode exec vitest run <test-file> --reporter=dot --bail 1
MC_E2E_VITEST_SCENARIOS=<scenario> pnpm --filter ./mastracode exec vitest run --config e2e/vitest.config.ts --reporter=dot
```
Also calls out the common workspace dependency issue: if tests cannot
resolve workspace package artifacts, build the relevant package graph
instead of changing tests to tolerate an unbuilt repo.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR updates the docs so AI coding agents know the fastest, safest
commands to build and test just the `mastracode` package (not the whole
monorepo). It also explains what to do when tests can’t find
workspace-built artifacts: build the needed package dependency graph
first.
## Summary
- Added package-local agent instructions in `mastracode/AGENTS.md`,
including:
- Root commands: `pnpm build:mastracode`, `pnpm test:mastracode`, `pnpm
--filter ./mastracode check`, `pnpm --filter ./mastracode lint`
- Build-before-audits guidance: run `pnpm build:mastracode` before
broader Mastra Code test audits so workspace dist artifacts exist
- Focused Vitest guidance: prefer `pnpm --filter ./mastracode exec
vitest run <test-file> --reporter=dot --bail 1` before the full suite
- E2E/TUI scenario guidance and example commands, including
`MC_E2E_VITEST_SCENARIOS=<scenario> pnpm --filter ./mastracode exec
vitest run --config e2e/vitest.config.ts --reporter=dot`
- Where unit vs TUI/e2e tests and fixtures live, plus fixture handling
and “keep edits surgical” conventions
- Tightened root `AGENTS.md` to discourage slow whole-repo builds by
emphasizing:
- “Prefer narrowest package build/test/lint/typecheck; start with
unit/integration before E2E”
- Targeted dependency-graph builds via package-specific root scripts and
`pnpm --filter ./packages/<name> ...` / `pnpm turbo build --filter
./packages/<name>`
- Fresh-clone workflow: `pnpm install`, then build relevant packages
- Troubleshooting rule: “Unresolvable internal/workspace imports means
deps aren’t built” (and notes about some integration tests needing `pnpm
i --ignore-workspace`)
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Mastra Code (openai/gpt-5.5) <noreply@mastra.ai>
Replaces the `tailwind-best-practices` skill with two consolidated,
single-file skills. The previous structure spread 8 rules across 10
files and 3 levels of indirection (SKILL.md → catalog → rule files),
with the same guidance repeated in up to 3 places (`bg-(--var)` was
explained in 3 files, the transform/transition gotcha in 3). The catalog
pattern is borrowed from `react-best-practices`, where ~17 rules justify
an index; at 8 rules it was pure overhead.
**`.claude/skills/tailwind-v4`** — generic Tailwind v4 guidance for any
Tailwind code in the repo:
- Version and sources: check the pinned `tailwindcss` version (4.2.2
today) before using recent utilities, with links to the official docs,
upgrade guide, and release posts so guidance stays accurate when the pin
moves.
- CSS-first configuration table: `@theme` / `@theme inline`, `@utility`,
`@custom-variant`, `@variant`, `@source`, `@reference` vs their v3-era
equivalents.
- v3 → v4 rename table: shadow/blur/rounded scale shifts,
`outline-hidden`, `ring-3`, opacity modifiers, `bg-linear-*`, important
suffix, `bg-(--var)` shorthand.
- Prefer generated utilities over arbitrary values: infinite spacing
scale (`min-w-100` over `min-w-[400px]`), `grid-cols-N`,
`data-current:`, custom-property shorthand with type hints.
- "Don't hand-write CSS or JS for what a variant covers" table:
`active:`, `aria-*`, `data-*`, `group`/`peer`, `has-*`, `mask-*`,
`pointer-coarse:`, `nth-*`, `*:`/`**:`.
- New v4 capabilities that replace hacks: `field-sizing-content`,
`wrap-anywhere` (no more `min-w-0`), safe alignment, `user-valid:`,
`starting:`.
- Behavior changes (individual transform properties, hover-capable-only
`hover:`, `currentColor` defaults, left-to-right variant stacking, `gap`
over `space-*`) and motion guidance.
**`.claude/skills/mastra-frontend`** — how to build any Mastra app UI
with the `@mastra/playground-ui` design system (in this repo or
externally; the docs site keeps its own styling). Aimed at agents and
contributors who don't know frontend: composition first, the design
system provides the look. Changing the design system itself stays a
separate, explicitly-approved task.
- The look vs layout boundary: layout `className` (positioning, gap,
margins, size constraints) is legitimate on DS components; look
overrides (colors, typography, radius, shadows, padding) never are — use
variants or escalate.
- Discovery over enumeration: browse `ds/components/` exports and read
the `@theme` block in `theme.css` (namespace → generated utility)
instead of trusting remembered names.
- 5-rung decision ladder: DS component → `theme.css` utility → dynamic
v4 utility → local CSS custom property → justified arbitrary value.
- Wiring: `index.css` imports, the dark-mode model (`:root` is the dark
default, `html.light` flips the semantic variables — never `dark:` color
overrides on semantic tokens), and `cn()` backed by the DS-extended
`twMerge` config.
- Theme contract (`theme.css` is API, approval required to change) and
review smells for all of the above.
Skill references updated in `AGENTS.md`,
`packages/playground/CLAUDE.md`, and `packages/playground-ui/CLAUDE.md`.
Net: 775 → 164 lines, 10 → 2 files, while covering more than before —
opacity modifiers, `bg-linear-*`, container queries, `has-*`/`aria-*`
variants, the `cn()`/`twMerge` merge behavior, and the dark-mode model
were all absent from the previous version.
Validation:
- `pnpm exec prettier --check` on both SKILL.md files, `git diff
--check`, commit hook / `lint-staged`
- Token examples verified against `packages/playground-ui/theme.css`;
`cn()`/`twMerge` claims verified against `src/lib/tw-merge-config.ts`
- Tailwind claims cross-checked against the v4.0/v4.1/v4.3 release
posts, the upgrade guide, and the theme/functions-and-directives docs
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR splits one big set of Tailwind instructions into two smaller
guides: one for general Tailwind v4 usage and one for building Mastra
app screens with the shared design system. It also updates the places
that point to those guides so people and tools use the right advice.
### What changed
- Added `.claude/skills/tailwind-v4` with repo-specific Tailwind v4
guidance:
- CSS-first config model
- v3→v4 rename/behavior changes
- preference for generated utilities over arbitrary values
- new v4 features like container queries and variant behavior
- motion-safe / motion-reduce guidance
- Added `.claude/skills/mastra-frontend` with guidance for Mastra UI
work:
- layout vs. look responsibilities
- finding existing tokens/components first
- styling decision order
- `cn()` / `twMerge` usage
- dark-mode and theme contract details
- Updated skill references in:
- `AGENTS.md`
- `packages/playground/CLAUDE.md`
- `packages/playground-ui/CLAUDE.md`
- Removed the old multi-file `tailwind-best-practices` skill structure
and its reference docs.
### Notes
- The new guidance fills prior gaps around opacity modifiers,
`bg-linear-*`, `has-*` / `aria-*` variants, container queries, and
dark-mode behavior.
- Validation included formatting checks, diff checks, hooks/lint-staged,
and spot-checks against Tailwind docs and repo sources.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## What
Fixes the failing **Lint / Format** CI check on the changeset release PR
(#18189), and adds contributor guidance to prevent recurrence.
## Why
The Prettier `--check` step was failing on two files introduced in
#17794:
- `packages/core/src/agent/durable/preparation.ts`
-
`packages/core/src/agent/durable/__tests__/durable-agent-default-options.test.ts`
These were merged to `main` without Prettier formatting, so every PR
branching from `main` (including the auto-generated changeset release PR
#18189) inherits the failing lint check.
## How
1. Ran `pnpm prettier:format` on the two affected files. Changes are
purely cosmetic (line-length wrapping). No behavioral changes.
2. Updated `AGENTS.md` to explicitly instruct contributors to run
lint/format before opening a PR, referencing the real scripts (`pnpm
prettier:format`, `pnpm prettier:changed`, `pnpm prettier:format:check`,
`pnpm lint`).
## Verification
```
pnpm prettier --check packages/core/src/agent/durable/preparation.ts \
packages/core/src/agent/durable/__tests__/durable-agent-default-options.test.ts AGENTS.md
# All matched files use Prettier code style!
```
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR just “cleans up” code formatting in a couple of files so the
project’s automatic formatting check (Prettier) stops failing. It
doesn’t change what the code does—only how it’s wrapped and laid out.
## Changes
Prettier formatting was corrected in durable agent code to fix failing
**Lint / Format** CI checks:
-
`packages/core/src/agent/durable/__tests__/durable-agent-default-options.test.ts`
- Reformatted `createRepeatedToolThenTextModel` function signature to
multi-line parameters
- Reformatted the streamed `finish` event object in the mocked
`doStream` implementation
- Lines changed: +11/-2
- `packages/core/src/agent/durable/preparation.ts`
- Reformatted `DurablePreparationAgent`’s `getDefaultOptions` `opts`
parameter type (inline wrapping)
- Lines changed: +1/-3
- `AGENTS.md`
- Added contributor guidance to run lint/format checks (using `pnpm`
scripts) before opening PRs to prevent recurrence
All changes are purely cosmetic (line-length wrapping/formatting). No
functional or behavioral logic was modified.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
First slice of the Agent Builder UI being carved out of the larger
`yj/magnificent-marquess` branch into smaller, reviewable stacked PRs.
This PR ships **only** the create-flow building blocks for the Agent
Builder in `packages/playground`. The route is intentionally **not
registered** in `App.tsx`, so the new pages are dead code at runtime
until a follow-up PR wires them into the router.
## What's included
- `AgentBuilderStarter` component (textarea, submit, suggestion chips,
in-flight spinner) and its unit test
- `/agent-builder/agents/create` route file that gates on write access
and warms `tools`/`agents`/`workflows`/`stored-skills` caches
- Redirect-only `AgentBuilderRoot` index page that sends users to either
`/agent-builder/agents` or `/agent-builder/agents/create`
- Tiny `domains/agent-builder/index.ts` barrel re-exporting
`useBuilderAgentAccess` / `useBuilderAgentFeatures` /
`useCanCreateAgent`
- Optional `{ enabled }` on `useTools`, `useAgents`, `useWorkflows`,
`useStoredSkills` (additive, non-breaking) so the create page can defer
warm-ups until the user has access
- Starter-only CSS (aurora, drift, enter, chips) plus a
`prefers-reduced-motion` fallback
- Test infrastructure: `src/test/msw-server.ts` with a default empty
stored-skills handler, matching `vitest.setup.ts` wiring, and a
`scrollTo` polyfill
- `nanoid` dependency used by the starter for client-side ids
## What's explicitly NOT included
- No `App.tsx` change — route registration ships in a follow-up PR
- No `packages/client-js` changes — the existing `createStoredAgent` is
sufficient
- No `packages/playground-ui` changes — every primitive (`Textarea`,
`Button`, `Spinner`, `testId`, `tooltip`) already exists on `main`
## Test plan
- `pnpm --filter ./packages/playground typecheck` → ✅ passes
- `npx vitest run` (in `packages/playground`) → ✅ 374/374 tests pass
across 37 files, including the new `agent-builder-starter.test.tsx` (6
cases: disabled submit, eager create + navigate with `userMessage`,
20-char ellipsis truncation, spinner state, no navigate on failure, no
"create manually" affordance)
- `pnpm --filter ./packages/playground lint` → ✅ 0 errors (warnings are
all pre-existing)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR adds the first, standalone piece of an Agent Builder: a page
where someone can type a prompt and start creating a new AI agent. It
includes the create UI, background cache warm-ups, styling, tests, and
helpers — the route is intentionally not yet wired into the app so the
code is inert until a follow-up PR registers it.
## Overview
Extracts the initial Agent Builder create flow into packages/playground
and provides the building blocks for creating agents. The new pages are
left unregistered in App.tsx (dead code until a follow-up PR wires
routing). Key additions: starter UI component, create page with
permission gating and cache warm-ups, domain re-exports, optional defer
flags for several hooks, starter-only CSS with reduced-motion support,
MSW-backed test infra, fixtures, utilities, and a small runtime
dependency for client-side ids.
## New Exports
Domain barrel re-exports:
- useBuilderAgentAccess (hook) and related types
- useBuilderAgentFeatures (hook)
- useCanCreateAgent (hook) and related types
## Components & Pages
AgentBuilderStarter component
- Prompt textarea with Enter-to-submit (respects Shift+Enter and IME
composition).
- Example suggestion chips to populate the textarea.
- Creates a stored agent using nanoid() id, truncated name (20 chars +
ellipsis), default visibility, resolved starter model (falls back to a
Gemini-like model), and empty starter fields.
- Disables input and shows a Spinner while create mutation is pending;
shows a toast on error; navigates to /agent-builder/agents/{id}/edit on
success (navigation state includes userMessage and viewTransition).
- Unit tests cover enabling/disabling, successful create + navigation,
truncation, in-flight behavior, and failure handling.
Pages
- /agent-builder/agents/create — gates on write permission, warms caches
(tools, agents, workflows, stored-skills) via their hooks when allowed,
renders back button + AgentBuilderStarter, redirects users without write
permission to the agents list.
- /agent-builder/index (AgentBuilderRoot) —
useAgentBuilderInternalRedirect-driven index that renders a Spinner
while loading and Navigate to /agent-builder/agents or
/agent-builder/agents/create depending on whether stored agents exist.
## Hook Signature Updates (defer cache warm-ups)
Several hooks now accept an optional options object to control React
Query enabled:
- useTools(options?: { enabled?: boolean }) — query key updated to
include requestContext
- useAgents(options?: { enabled?: boolean })
- useWorkflows(options?: { enabled?: boolean })
- useStoredSkills(options?: { enabled?: boolean })
This enables the create page to selectively warm caches only when
appropriate.
## Styling
- Adds starter-only CSS in src/index.css: .starter-aurora background,
starter-drift animation, starter-enter animations for
heading/prompt/chips, and a prefers-reduced-motion fallback.
## Test Infrastructure
- packages/playground/src/test/msw-server.ts — MSW server with a default
GET */api/stored/skills handler (empty paginated payload) and exported
server/handlers.
- vitest.setup.ts — wires MSW lifecycle (beforeAll/afterEach/afterAll)
with onUnhandledRequest: 'error', polyfills scrollTo and matchMedia for
jsdom.
- New/updated tests: AgentBuilderStarter,
useAgentBuilderInternalRedirect, AgentBuilderRoot, AgentBuilderCreate
and related fixtures; tests exercise real `@mastra/client-js` + React
Query while mocking only the network via MSW.
## Fixtures & Utilities
- Starter constants (FALLBACK_MODEL, EXAMPLES), ExampleList component,
resolveStarterModel and truncateName utilities.
- useAgentBuilderInternalRedirect hook aggregates draft/published agent
queries and returns { isLoading, hasAgents }.
- Typed stored-agent and builder fixtures for tests.
## Dependency
- Adds nanoid@^5.1.7 to packages/playground/package.json for client-side
id generation.
## Test & Quality
- Typecheck: pnpm --filter ./packages/playground typecheck — passes.
- Tests: npx vitest run in packages/playground — 374/374 tests pass
(includes new tests).
- Lint: pnpm --filter ./packages/playground lint — 0 errors.
## Not Included
- No App.tsx route registration for the new pages (planned in a
follow-up PR).
- No changes to packages/client-js or packages/playground-ui.
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/mastra-ai/mastra/pull/17056?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)
<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Mastra Code (anthropic/claude-opus-4-7) <noreply@mastra.ai>
Adds a short line to `AGENTS.md` clarifying that agents should run the
narrowest relevant local checks before pushing commits or opening PRs,
and run a local CodeRabbit review when the CLI is installed and
configured.
This keeps the existing package-local verification guidance intact and
makes the CodeRabbit step conditional for environments where the CLI is
not available.
Fixes#16533.
Tested with:
```bash
git diff --check
coderabbit review --type uncommitted --plain
```
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Chores**
* Updated development guidelines to recommend running local checks
before pushing commits or opening pull requests.
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/mastra-ai/mastra/pull/16534)
<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Adds a CI check that fails when any AGENTS.md file goes over the 500
token limit, then trims the existing AGENTS files so the repo passes the
new rule.
Before:
```md
# AGENTS.md
## Scope
This file applies to work in `packages/auth/`.
- Build from root: `pnpm build:auth`
```
After:
```md
Build from root: pnpm build:auth
Test from root: pnpm --filter ./packages/auth test
For broader auth coverage use pnpm test:auth
```
For codemod, the short AGENTS file now keeps the high-signal
instructions and points to a package-local skill for the longer workflow
and pattern reference.
codemod file went from ~5k tokens to 250, root AGENTS.md went from 1.8k
to 375
<img width="634" height="440" alt="Screenshot 2026-04-16 at 5 02 38 PM"
src="https://github.com/user-attachments/assets/307b6516-736b-47eb-98f4-48310d2d7d96"
/>
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR adds an automatic check that makes sure every AGENTS.md file
stays short (under 500 tokens) and shortens the existing AGENTS.md files
so they all pass that check.
## Overview
Enforces a 500-token limit for AGENTS.md files via CI, adds a validation
script to count tokens, and trims many AGENTS.md documents to keep only
high-signal guidance while moving large, detailed reference content into
a separate skill file.
## Changes
### CI & Validation
- Added `.github/scripts/validate-agents-md.mjs`: Node script that finds
AGENTS.md files, counts tokens using `tokenx`, and exits non‑zero if any
file exceeds the 500-token limit.
- Updated `.github/workflows/lint.yml`: new `agents-md-check` job runs
the validation script in CI for the mastra-ai/mastra repository.
### Dependencies
- Added `tokenx` (^1.3.0) to root `package.json` for token counting.
### AGENTS.md Consolidation
Multiple AGENTS.md files were condensed by removing multi-section
structure and extraneous formatting, preserving core commands and
high-signal instructions so each file stays ≤ 500 tokens:
- Root AGENTS.md: ~1.8k → 375 tokens (condensed conventions, removed
detailed examples and lengthy rules)
- docs/AGENTS.md: condensed docs and E2E guidance (removed fenced code
blocks and verbose explanations)
- packages/auth/AGENTS.md: simplified to core build/test guidance (62
tokens)
- packages/cli/AGENTS.md: collapsed into concise command lines (53
tokens)
- packages/codemod/AGENTS.md: main codemod guidance trimmed and
redirected to new skill file (result much smaller; AGENTS.md reduced
significantly)
- packages/core/AGENTS.md: flattened while keeping build/test/Zod-compat
notes (147 tokens)
- packages/mcp/AGENTS.md: consolidated client/server/integration test
guidance (107 tokens)
- packages/memory/AGENTS.md: reorganized integration workflow into a
concise section (283 tokens)
- packages/playground-ui/AGENTS.md: reduced to operational commands and
a brief design-system note (74 tokens)
- packages/playground/AGENTS.md: simplified build/test instructions and
coordination note (99 tokens)
- packages/rag/AGENTS.md: collapsed into brief build/test/lint guidance
(81 tokens)
- packages/server/AGENTS.md: condensed to three sentences covering
build/test/permissions (85 tokens)
### Knowledge Base Enhancement
- Added `packages/codemod/.claude/skills/codemod-patterns/SKILL.md`: a
607-line detailed codemod patterns and workflow guide moved out of
AGENTS.md to keep AGENTS.md concise.
## Validation
A terminal validation run (included in the PR) shows all AGENTS.md files
pass the 500-token rule, with token counts ranging from 53 to 403 and a
final message: "All AGENTS.md files are within the 500-token limit."
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Mastra Code (openai/gpt-5.4) <noreply@mastra.ai>
Co-authored-by: Abhi Aiyer <abhiaiyer91@gmail.com>
## Description
Adds Commands and Skills sections to AGENTS.md so that non-Claude agents
(e.g. OpenAI Codex) can discover and use the same reusable command
prompts and domain-specific skill files that Claude agents access via
`.claude/commands/` and `.claude/skills/`. This gives all coding agents
parity regardless of which provider they come from.
## Related Issue(s)
N/A
## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update
## Checklist
- [x] I have made corresponding changes to the documentation (if
applicable)
- [ ] I have added tests that prove my fix is effective or that my
feature works
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR adds a helpful instruction guide to AGENTS.md that lists all the
reusable command templates and skill guides that AI agents can use when
working on the project. Think of it like adding a table of contents or a
menu that shows agents what tools and best practices they can follow,
whether they're Claude or another AI provider.
## Overview
Updates the root `AGENTS.md` file to expose Commands and Skills
sections, enabling agents of any provider to discover and reference
reusable command prompts and domain-specific skill documentation for
cross-agent parity.
## Changes
Adds two new sections to `AGENTS.md`:
**Commands** — Lists 13 reusable command prompts available in
`.claude/commands/` including:
- Changeset creation, conventional commits, and PR workflows
- GitHub issue debugging and CI/lint fixes
- Documentation generation
- Bulk issue solving and planning
**Skills** — Documents 7 domain-specific guidance files in
`.claude/skills/` covering:
- E2E testing for Studio (required for `packages/playground-ui` and
`packages/playground` changes)
- Documentation, React, and Tailwind best practices
- Smoke testing procedures and Ralph planning
## Impact
Documentation-only update (+29 lines). No code changes or exported
entities modified. Enables non-Claude agents to access the same reusable
prompts and skill documentation that were previously only documented for
Claude-specific workflows.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Adds dynamic AGENTS.md loading to MastraCode so instruction files
discovered during tool use show up in the chat and continue to work
after reload.
After:
```text
Loaded AGENTS.md
src/agents/nested/AGENTS.md
```
The reminder is injected from completed tool usage, streamed inline
while the run is active, persisted for history/reload, and rendered with
the same expand/collapse behavior as the rest of the TUI.
This is an example of how we could internally support injecting system
notices about external events into harness. Later we could add something
like `harness.injectSystemReminder()` or similar
<img width="714" height="1037" alt="Screenshot 2026-03-24 at 9 50 02 AM"
src="https://github.com/user-attachments/assets/8aaea44b-7ad1-4424-a1c8-f3d7602be30f"
/>
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* System reminders now render as bordered notices in the TUI,
auto-collapse long content (10-line default) and can be expanded via
keyboard or controls; streaming and deduplication of reminders improved.
* Agents MD reminders can be injected when tools reference instruction
files, with transient streaming updates and persisted reminder messages.
* **Documentation**
* Added and consolidated package-scoped AGENTS.md guidance and
simplified main repository guidance.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Mastra Code (minimax/MiniMax-M2.7-highspeed) <noreply@mastra.ai>
## Summary
Move all slash command files to `.mastracode/commands/` and replace the
files in `.claude/commands/`, `.cursor/commands/`, and
`.opencode/command/` with symlinks pointing back to
`.mastracode/commands/`.
This means edits to any command file only need to happen in one place.
## Changes
- Created `.mastracode/commands/` with all 12 command files (canonical
copies)
- Replaced all files in `.claude/commands/`, `.cursor/commands/`,
`.opencode/command/` with symlinks
- Updated `AGENTS.md` to reference `.mastracode/commands/changeset.md`
## Test Plan
- Verified all symlinks resolve correctly (`cat` through each directory
returns identical content)
- No code changes — only config/docs files affected
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added comprehensive command documentation and workflow guidance for
managing GitHub issues, pull requests, changesets, and CI/CD processes.
* Introduced structured command specifications for bulk issue
resolution, debugging workflows, and collaborative code review
processes.
* **Documentation**
* Added detailed instructions for conventional commits, PR creation,
linting fixes, and changelog management.
* Centralized command definitions across development tools.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Co-authored-by: Mastra Code (anthropic/claude-opus-4-6) <noreply@mastra.ai>
## Summary
PR 1 of 3 from the `auth-rbac-cms` branch split. This PR adds all
backend plumbing for auth/RBAC. PRs 2 (auth providers) and 3 (playground
UI) depend on this and can land in parallel once this merges.
- **New `@mastra/core/auth` export** — interfaces for RBAC, sessions,
SSO, credentials, ACL, and user management, plus default implementations
(static RBAC provider, cookie/memory session providers, built-in roles)
- **Server auth handlers** — login, signup, logout, session management,
and SSO flows with Zod-validated schemas
- **Route-level permission enforcement** — `requiresPermission` on route
configs with convention-based derivation from path/method (e.g. `GET
/agents/:id` → `agents:read`)
- **Server adapter RBAC middleware** (Hono, Express, Fastify, Koa) —
resolves user permissions via RBAC provider, cookie auth fallthrough for
session-based auth
- **Authorization policy fix** — `isProtectedPath` now uses
`isProtectedCustomRoute` instead of `!isCustomRoutePublic`, fixing a bug
where studio UI couldn't load in production
- **Deployer updates** — `MASTRA_PACKAGES_FILE` env var injection,
dynamic CORS origin when auth configured
- **Client SDK** — `getFullUrl` helper, `AuthCapabilities` type export
### Key behavioral changes
| Change | Risk | Mitigation |
|---|---|---|
| `SimpleAuth<TUser>` → `SimpleAuth<TUser extends EEUser>` | Medium —
requires `id` + `email` fields | Intentional; compile-time catch |
| `isProtectedPath` logic change | Medium — authorization policy | New
tests cover this; required for studio login in prod |
| Cookie fallthrough in Hono auth middleware | Low | Falls back to 401
if no user found |
| No RBAC → authenticated users get full access | Low — intentional |
Auth-only mode preserved |
| CORS dynamic origin when auth configured | Low | Only activates with
auth config; user can override |
### Deviation from plan
`deployers/cloud/package.json` — the plan called for adding
`@mastra/auth-cloud` dependency, but that package is created in PR 2.
Omitted here to avoid workspace resolution failure; PR 2 will add it.
### Fixed pre-existing test bug
All 4 adapter RBAC tests had a failing test ("should derive permissions
from route path/method when not explicitly set") that registered an API
handler at `/agents/test` with no prefix. That's a frontend/SPA path —
real API handlers are always under `/api/*`. Fixed the test to use
`prefix: '/api'` so the route is at `/api/agents/test`, matching how
routes are actually registered. Verified the bug exists on
`auth-rbac-cms` with clean install + build.
## Test plan
- [x] `pnpm build:packages` — 35/35 tasks pass
- [x] Core auth tests (cookie.test.ts) — 16/16 pass
- [x] Server tests (permissions, helpers, system) — 177/177 pass
- [x] Hono RBAC tests — 21/21 pass
- [x] Express RBAC tests — 15/15 pass
- [x] Fastify RBAC tests — 15/15 pass
- [x] Koa RBAC tests — 15/15 pass
- [x] Client SDK tests (base.test.ts) — 5/5 pass
- [ ] Verify no auth configured → all existing behavior identical (no
403s, no auth prompts)
- [ ] Verify pre-commit hooks pass (eslint + prettier)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Enterprise auth: SSO and credentials sign-in/sign-up, login/logout,
cookie and in-memory sessions, auth capabilities and current-user
endpoints.
* RBAC: default roles, static RBAC provider, route-level permission
enforcement and middleware across adapters.
* Client: full-URL helper; system responses include isDev.
* Deploy/build: bundling emits package metadata; deployers set runtime
packages file and adjust CORS when auth is enabled.
* **Bug Fixes**
* Studio UI loads correctly in production.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Shane Thomas <shane@codekarate.com>
Co-authored-by: Mastra Code (anthropic/claude-opus-4-6) <noreply@mastra.ai>
Co-authored-by: Abhi Aiyer <abhiaiyer91@gmail.com>
## Description
- Add docs styleguides
- Add AGENTS.md files and point CLAUDE.md file to it
- Add mastra-docs claude skill
- Improve prompts on writing docs
## Related Issue(s)
Fixes DEVED-110
## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [X] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update
## Checklist
- [ ] I have made corresponding changes to the documentation (if
applicable)
- [ ] I have added tests that prove my fix is effective or that my
feature works
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added comprehensive docs and styleguides (DOC, STYLEGUIDE, GUIDE_* ,
REFERENCE) and new AGENTS.md; reorganized docs content and contributor
workflow.
* Replaced extensive CLAUDE.md content with pointer to AGENTS.md;
cleared docs changelog and removed some legacy guideline files.
* Updated CLI/pr/changeset prompts and guidance to require multiple
changesets for multi-package changes and warn against very long
changesets.
* **Community**
* Updated Code of Conduct with expanded scope and clearer enforcement
guidance.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>