0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/packages/cli/AGENTS.md
Tyler Barnes 5172c80fad
chore: enforce AGENTS.md token limits (#15464)
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>
2026-04-18 19:12:37 -07:00

225 B

Build from root: pnpm build:cli Test from root: pnpm test:cli Typecheck from root: pnpm --filter ./packages/cli typecheck

Most validation is package-scoped tests plus CLI typecheck/build checks

Preserve stable CLI behavior