chore(agents): add CLAUDE.md, refine AGENTS.md

Author: rahmanunver

AGENTS.md

@@ -1,94 +1,35 @@
-# Mendix Web Widgets Repository - AI Agent Overview
+# Mendix Web Widgets Repository
 
-This document provides a comprehensive overview of the Mendix Web Widgets repository structure and conventions for AI development assistants. This repository contains the official collection of pluggable web widgets for the Mendix low-code platform.
+Monorepo of official Mendix pluggable web widgets. pnpm workspaces + Turbo.
 
-## Repository Overview
+## Structure
 
-The **Mendix Web Widgets** repository is the official home of all Mendix platform-supported pluggable web widgets and related modules. These are reusable UI components built with modern web technologies (React, TypeScript, SCSS) that integrate seamlessly into Mendix Studio Pro applications.
+- `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
 
-### Key Characteristics
-- **Monorepo structure** using pnpm workspaces and Turbo for build orchestration
-- **Modern web stack**: TypeScript, React, SCSS, Jest, ESLint, Prettier
-- **Mendix integration**: Built using Mendix Pluggable Widgets API
-- **Atlas UI alignment**: Consistent with Mendix's design system
-- **Comprehensive testing**: Unit tests (Jest/RTL), E2E tests (Playwright)
+## Commands
 
-## Repository 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/     # Main widget packages (*-web folders)
-│   ├── modules/              # Mendix modules
-│   ├── customWidgets/        # Custom widget implementations  
-│   └── shared/               # Shared configurations and utilities
-├── docs/
-│   └── requirements/         # Detailed technical requirements (see below)
-├── automation/               # Build and release automation
-└── .github/                  # GitHub workflows and Copilot instructions
-```
+## Conventions
 
-## Detailed Requirements Documentation
+- 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
 
-The `/docs/requirements/` folder contains comprehensive technical documentation for understanding and contributing to this repository. Each document covers specific aspects of the development process:
+## Agent-Specific Instructions
 
-### Core Requirements and Guidelines
-
-- **[Project Requirements Document](docs/requirements/project-requirements-document.md)** - High-level overview of repository purpose, goals, target users, and design system alignment
-- **[Technology Stack and Project Structure](docs/requirements/tech-stack.md)** - Core technologies, monorepo structure, configuration standards, and development tools
-- **[Frontend Guidelines](docs/requirements/frontend-guidelines.md)** - CSS/SCSS styling guidelines, naming conventions, component best practices, and Atlas UI integration
-
-### Development Workflow and Integration
-
-- **[Application Flow and Widget Lifecycle](docs/requirements/app-flow.md)** - Complete widget development lifecycle from scaffolding to Studio Pro integration
-- **[Backend Structure and Data Flow](docs/requirements/backend-structure.md)** - Widget-to-Mendix runtime integration, data handling, and event management
-- **[Implementation Plan](docs/requirements/implementation-plan.md)** - Step-by-step guide for creating new widgets, including PR templates and testing requirements
-
-### Module Development
-
-- **[Widget to Module Conversion](docs/requirements/widget-to-module.md)** - Guidelines for converting widgets to Mendix modules when appropriate
-
-## Development Commands
-
-Key commands for working with this repository:
-
-- **`pnpm lint`** - Run linting across all packages
-- **`pnpm test`** - Run unit tests across all packages  
-- **`pnpm build`** - Build all packages
-- **`pnpm -w changelog`** - Update changelogs
-- **`pnpm -w version`** - Bump versions across packages
-
-## AI Development Assistant Context
-
-### For Code Reviews and PR Analysis
-See [.github/copilot-instructions.md](.github/copilot-instructions.md) for detailed PR review guidelines, including:
-- Mendix-specific conventions and API usage
-- React best practices and performance considerations
-- Testing requirements (unit, component, E2E)
-- Styling guidelines and Atlas UI integration
-- Version management and changelog requirements
-
-### For Code Development
-When working on this repository, prioritize:
-
-1. **Minimal changes** - Make surgical, precise modifications
-2. **Mendix conventions** - Follow established patterns for XML configuration, TypeScript props, and data handling
-3. **Testing coverage** - Ensure unit tests, component tests, and E2E tests as appropriate
-4. **Atlas UI consistency** - Use Atlas classes and design tokens
-5. **Performance** - Consider React render optimization and Mendix data efficiency
-
-### Common Development Patterns
-
-- **Widget Structure**: Each widget has XML configuration, TypeScript component, SCSS styling, and test files
-- **Data Integration**: Use Mendix API objects (EditableValue, ActionValue, ListValue) correctly
-- **Styling**: Prefer Atlas UI classes over custom styles; use SCSS for widget-specific styling
-- **Testing**: Follow Jest + RTL for unit tests, Playwright for E2E testing
-
-## Getting Started
-
-1. **Prerequisites**: Node.js ≥22, pnpm 10.15.0
-2. **Installation**: `pnpm install`
-3. **Development**: Set `MX_PROJECT_PATH` environment variable to your Mendix project
-4. **Building**: Use `pnpm build` or `pnpm start` for development builds
-5. **Testing**: Use `pnpm test` for unit tests, `pnpm e2e` for E2E tests
-
-For detailed implementation guidance, refer to the specific requirement documents linked above.
+- **Claude Code** — See `CLAUDE.md` for hooks, commands, and detailed instructions
+- **GitHub Copilot** — See `.github/copilot-instructions.md` for PR review guidelines
+- **Cursor / Windsurf** — See `docs/requirements/` for rule files (YAML frontmatter compatible)

CLAUDE.md

@@ -0,0 +1,66 @@
+# Mendix Web Widgets
+
+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 `npm run test` (NOT from repo root)
+- Lint one: cd into package dir, run `npm 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
+```
+
+## Hooks (auto-applied)
+
+- **Auto-format**: Every file edit is auto-formatted by prettier via PostToolUse hook.
+  Do NOT manually run `prettier --write` — it wastes tokens, the hook handles it.
+- **Auto-lint**: After each edit, eslint runs via `npm 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()
+- Use EditableValue.setValue() for two-way binding
+- 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
+
+- 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