EndavaEndava/BEEQ/AGENTS.md

BEEQ

AGENTS.md162 starsChanged 11 days agoApache-2.0View on GitHub

BEEQ is a StencilJS web component library and design system, in an Nx monorepo. Components and design tokens live in packages/beeq (tokens in src/global/styles/foundations), the standalone Tailwind preset generated from those tokens in packages/beeq-tailwindcss, framework wrappers in packages/beeq-{angular,react,vue}, consumer agent skills in packages/beeq-skills, and the Mintlify docs in apps/beeq-docs. Use pnpm (not npm). Nx projects are tagged core, publishable, wrapper, preset, skills; the filters below select by tag. pnpm build:beeq:fast and pnpm test:e2e:fast skip icon generation; read build performance before…

Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,774 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository10 other files it gives its agents.
- create-componentSkill
- doc-componentSkill
- fix-accessibilitySkill
- pr-checklistSkill
- review-componentSkill
- review-docSkill
- write-e2e-testsSkill
- write-storiesSkill
- write-unit-testsSkill
- beeqSkill

The file

We split this AGENTS.md into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Use pnpm (not npm). Nx projects are tagged core, publishable, wrapper, preset, skills.
line 7
Very specific:
Write commits as Conventional Commits (commitlint enforces them) and end docs-only commits with [ci skip].
line 23
Distinctive:
Keep changes scoped to the task.
line 26

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

AGENTS.md

BEEQ is a StencilJS web component library and design system, in an Nx monorepo. Components and design tokens live in packages/beeq (tokens in src/global/styles/foundations), the standalone Tailwind preset generated from those tokens in packages/beeq-tailwindcss, framework wrappers in packages/beeq-{angular,react,vue}, consumer agent skills in packages/beeq-skills, and the Mintlify docs in apps/beeq-docs.

Package manager and commands

Use pnpm (not npm). Nx projects are tagged core, publishable, wrapper, preset, skills; the filters below select by tag.

pnpm exec nx affected -t check --exclude='*,!tag:core' --parallel=3      # lint + typecheck
pnpm exec nx affected -t test --exclude='*,!tag:core' --parallel=3       # unit tests
pnpm exec nx affected -t e2e --exclude='*,!tag:core' --parallel=3        # e2e tests
pnpm exec nx affected -t build --exclude='*,!tag:publishable' --parallel=3
pnpm g                           # scaffold a component (Plop)
pnpm skills:sync                 # regenerate skills/ from beeq-skills/src

pnpm build:beeq:fast and pnpm test:e2e:fast skip icon generation; read build performance before using them.

Rules for every task

Format and lint with Biome.
Write commits as Conventional Commits (commitlint enforces them) and end docs-only commits with [ci skip]. Details: git workflow.
CHANGELOG.md is generated by Nx release; never edit it.
Edit packages/beeq-skills/src; skills/ is generated by pnpm skills:sync.
Keep changes scoped to the task. Report refactors that would clearly improve performance, scalability, efficiency or readability as a final list: file, benefit, rough effort.

Guidelines by task

Open the files for your task before editing. applyTo frontmatter in them is a hint for tools that support it; rely on these links. Package folders have their own AGENTS.md with local notes.

Editing a component (.tsx, .scss)
- Components: structure, naming, JSDoc
- Styles: required for any .scss change
- Accessibility: ARIA, keyboard, contrast, WCAG 2.1 AA
Writing tests
- Testing: e2e for components, unit for shared/
Writing or editing docs in apps/beeq-docs
- Documentation: tone, frontmatter, non-component pages
- Component docs: component page structure
- Code examples: CodeLivePreview, CSS tab, framework tabs
Committing, branching, opening a PR
- Git workflow: branches, commits, PRs, breaking changes
Building or running e2e locally
- Build performance: BEEQ_SKIP_ICONS and :fast scripts

Skills

Skills live in .agents/skills/.

Task	Skill
Scaffold a new `bq-*` component	`create-component`
Write E2E tests (`@stencil/vitest`)	`write-e2e-tests`
Write Vitest unit tests for shared utils	`write-unit-tests`
Write Storybook stories and MDX docs	`write-stories`
Review a component against guidelines	`review-component`
Audit and fix WCAG 2.1 AA issues	`fix-accessibility`
Write or complete a Mintlify MDX doc page	`doc-component`
Audit an existing MDX doc page	`review-doc`
Run the PR merge checklist before review	`pr-checklist`

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free