From 014b682374048f049d60ebad147c253861e048f0 Mon Sep 17 00:00:00 2001
From: Rahman <rahmanunver@gmail.com>
Date: Fri, 3 Apr 2026 16:40:29 +0200
Subject: [PATCH] chore: consolidate AGENTS.md and CLAUDE.md to eliminate
 duplication

Make AGENTS.md the single source of truth for all AI agents. CLAUDE.md
becomes a thin wrapper that imports AGENTS.md and adds Claude Code-specific
hooks and auto-loaded documentation.
---
 AGENTS.md | 75 +++++++++++++++++++++++++++++++++++++++----------------
 CLAUDE.md | 63 ++++++----------------------------------------
 2 files changed, 61 insertions(+), 77 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 53fb367c83..b60593f0a6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,35 +1,66 @@
-# Mendix Web Widgets Repository
+# Mendix Web Widgets
 
 Monorepo of official Mendix pluggable web widgets. pnpm workspaces + Turbo.
 
-## Structure
+## Commands
 
-- `packages/pluggableWidgets/*-web` — Widget packages (React, TypeScript, SCSS)
-- `packages/modules/*` — Mendix module packages
-- `packages/shared/*` — Shared configs and utilities
-- `automation/` — Build and release automation
-- `docs/requirements/` — Detailed technical requirements
+- Install: `pnpm install`
+- Build all: `pnpm build`
+- Build one: `pnpm --filter @mendix/<name> run build`
+- Test one: cd into package dir, run `pnpm run test` (NOT from repo root)
+- Lint one: cd into package dir, run `pnpm run lint`
+- Changelog: `pnpm -w changelog`
 
-## Commands
+## Structure
 
-| Command | Description |
-|---------|-------------|
-| `pnpm install` | Install dependencies |
-| `pnpm build` | Build all packages |
-| `pnpm lint` | Lint all packages |
-| `pnpm test` | Test all packages |
-| `pnpm --filter @mendix/<name> run <script>` | Run script in one package |
+```
+packages/pluggableWidgets/*-web/  -> Widget packages (React + TS + SCSS)
+packages/modules/                 -> Mendix module packages
+packages/shared/                  -> Shared configs, plugins, utilities
+automation/                       -> Build/release automation
+docs/requirements/                -> Detailed technical requirements
+```
 
 ## Conventions
 
-- TypeScript + React functional components + SCSS
-- Mendix Pluggable Widgets API (EditableValue, ActionValue, ListValue)
-- Atlas UI design system for styling
-- Conventional commits (commitlint enforced)
-- Semver versioning + CHANGELOG.md per package
+- TypeScript strict, React functional components + hooks
+- Mendix Pluggable Widgets API: EditableValue, ActionValue, ListValue, DynamicValue
+- Check ActionValue.canExecute before execute()
+- Render loading/empty states until values are ready
+- SCSS for styling, prefer Atlas UI classes, BEM-like naming with widget prefix
+- Conventional commits enforced: `type(scope): description`
+- Semver + CHANGELOG.md per package for runtime/XML/behavior changes
+- Jest + RTL for unit tests (src/**/__tests__/*.spec.ts)
+- Playwright for E2E (e2e/*.spec.js)
+
+## Development Setup
+
+- Node >=22, pnpm 10.x
+- Set MX_PROJECT_PATH to Mendix project dir for live reload
+- Run `pnpm start` inside widget package for dev build
+
+## Constraints
+
+- Never modify dist/, generated files, or lockfiles
+- XML property keys: lowerCamelCase, must match TypeScript props exactly
+- Don't override core Atlas UI classes
+- Prefer tree-shakable imports for new dependencies
+
+## Documentation
+
+Essential reading (consult for any widget work):
+- docs/requirements/tech-stack.md — Full technology stack
+- docs/requirements/frontend-guidelines.md — CSS/SCSS/Atlas UI guidelines
+- docs/requirements/app-flow.md — Widget lifecycle and Studio Pro integration
+- docs/requirements/backend-structure.md — Data flow and Mendix runtime
+- docs/requirements/project-requirements-document.md — Goals and scope
+
+Reference (consult on demand for specific tasks):
+- docs/requirements/implementation-plan.md — New widget guide + PR template
+- docs/requirements/widget-to-module.md — Widget-to-module conversion guide
 
 ## Agent-Specific Instructions
 
-- **Claude Code** — See `CLAUDE.md` for hooks, commands, and detailed instructions
+- **Claude Code** — See `CLAUDE.md` for hooks and auto-imported documentation
 - **GitHub Copilot** — See `.github/copilot-instructions.md` for PR review guidelines
-- **Cursor / Windsurf** — See `docs/requirements/` for rule files (YAML frontmatter compatible)
+- **Cursor / Windsurf** — Use docs/requirements/ files as rule sources (YAML frontmatter compatible)
diff --git a/CLAUDE.md b/CLAUDE.md
index 75bea1d4d5..8d6a7d892d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,25 +1,6 @@
-# Mendix Web Widgets
+@AGENTS.md
 
-Monorepo of official Mendix pluggable web widgets. pnpm workspaces + Turbo.
-
-## Commands
-
-- Install: `pnpm install`
-- Build all: `pnpm build`
-- Build one: `pnpm --filter @mendix/<name> run build`
-- Test one: cd into package dir, run `pnpm run test` (NOT from repo root)
-- Lint one: cd into package dir, run `pnpm run lint`
-- Changelog: `pnpm -w changelog`
-
-## Structure
-
-```
-packages/pluggableWidgets/*-web/  -> Widget packages (React + TS + SCSS)
-packages/modules/                 -> Mendix module packages
-packages/shared/                  -> Shared configs, plugins, utilities
-automation/                       -> Build/release automation
-docs/requirements/                -> Detailed technical requirements
-```
+# Claude Code
 
 ## Hooks (auto-applied)
 
@@ -28,38 +9,10 @@ docs/requirements/                -> Detailed technical requirements
 - **Auto-lint**: After each edit, eslint runs via `pnpm run lint` in the file's package.
   Lint errors are fed back automatically — fix them in the next edit, do NOT run lint commands manually.
 
-## Conventions
-
-- TypeScript strict, React functional components + hooks
-- Mendix Pluggable Widgets API: EditableValue, ActionValue, ListValue, DynamicValue
-- Check ActionValue.canExecute before execute()
-- Render loading/empty states until values are ready
-- SCSS for styling, prefer Atlas UI classes, BEM-like naming with widget prefix
-- Conventional commits enforced: `type(scope): description`
-- Semver + CHANGELOG.md per package for runtime/XML/behavior changes
-- Jest + RTL for unit tests (src/**tests**/\*.spec.ts)
-- Playwright for E2E (e2e/\*.spec.js)
-
-## Development Setup
-
-- Node >=22, pnpm 10.x
-- Set MX_PROJECT_PATH to Mendix project dir for live reload
-- Run `pnpm start` inside widget package for dev build
-
-## Detailed Reference
-
-For deeper context, see:
-
-- @docs/requirements/tech-stack.md — Full technology stack
-- @docs/requirements/frontend-guidelines.md — CSS/SCSS/Atlas UI guidelines
-- @docs/requirements/app-flow.md — Widget lifecycle and Studio Pro integration
-- @docs/requirements/backend-structure.md — Data flow and Mendix runtime
-- @docs/requirements/implementation-plan.md — New widget guide + PR template
-- @docs/requirements/project-requirements-document.md — Goals and scope
-
-## Constraints
+## Auto-loaded Documentation
 
-- Never modify dist/, generated files, or lockfiles
-- XML property keys: lowerCamelCase, must match TypeScript props exactly
-- Don't override core Atlas UI classes
-- Prefer tree-shakable imports for new dependencies
+@docs/requirements/tech-stack.md
+@docs/requirements/frontend-guidelines.md
+@docs/requirements/app-flow.md
+@docs/requirements/backend-structure.md
+@docs/requirements/project-requirements-document.md