redis · valkirilov · Dec 5, 2025
@@ -1,12 +1,74 @@
 # RedisInsight AI Development Rules
 
-This directory contains the **single source of truth** for AI-assisted development rules and workflows in RedisInsight. These rules are used by multiple AI coding assistants:
+This directory contains the **single source of truth** for AI-assisted development rules and workflows in RedisInsight.
+
+## Overview
+
+This repository uses a centralized approach to AI development rules:
+
+- **`AGENTS.md`** (at repository root) - Entry point for AI agents with essential commands, testing instructions, and quick reference
+- **`.ai/rules/`** - Detailed development standards organized by topic
+- **`.ai/commands/`** - AI workflow commands and templates
+
+These rules are used by multiple AI coding assistants:
 
 - **Cursor** (via symlinks: `.cursor/rules/` and `.cursor/commands/`)
 - **Augment** (via symlink: `.augment/`)
 - **Windsurf** (via symlink: `.windsurfrules`)
 - **GitHub Copilot** (via file: `.github/copilot-instructions.md`)
 
+## Structure
+
+```
+AGENTS.md                              # 🎯 AI agent entry point
+.ai/                                   # Single source of truth
+├── README.md                          # This file (human-readable overview)
+├── rules/                             # Development standards (modular)
+│   ├── code-quality.md                # Linting, TypeScript standards
+│   ├── frontend.md                    # React, Redux, UI patterns
+│   ├── backend.md                     # NestJS, API patterns
+│   ├── testing.md                     # Testing standards
+│   ├── branches.md                    # Branch naming conventions
+│   ├── commits.md                     # Commit message guidelines
+│   └── pull-requests.md               # Pull request process
+└── commands/                          # AI workflow commands
+    ├── pr-plan.md                     # JIRA ticket implementation planning
+    ├── commit-message.md              # Commit message generation
+    └── pull-request-review.md         # PR review workflow
+
+# Symlinks (all AI tools read from .ai/)
+.cursor/
+  ├── rules/ -> ../.ai/rules/          # Cursor AI (rules)
+  └── commands/ -> ../.ai/commands/  # Cursor AI (commands)
+.augment/ -> .ai/                      # Augment AI
+.windsurfrules -> .ai/                 # Windsurf AI
+.github/copilot-instructions.md        # GitHub Copilot
+```
+
+## For AI Agents
+
+**Start here**: Read `AGENTS.md` at the repository root for:
+
+- Setup and build commands
+- Code quality standards
+- Testing instructions
+- Git workflow guidelines
+- Boundaries and best practices
+
+**Then refer to**: `.ai/rules/` for detailed guidelines on specific topics.
+
+## For Human Developers
+
+This directory contains comprehensive development standards that are automatically used by AI coding assistants. The rules are organized into modular files for easy maintenance:
+
+- **Code Quality Standards**: `.ai/rules/code-quality.md` - TypeScript standards, import organization, best practices
+- **Frontend Patterns**: `.ai/rules/frontend.md` - React, Redux, styled-components, UI component usage
+- **Backend Patterns**: `.ai/rules/backend.md` - NestJS, dependency injection, API patterns
+- **Testing Standards**: `.ai/rules/testing.md` - Testing patterns, faker usage, test helpers
+- **Branch Naming**: `.ai/rules/branches.md` - Branch naming conventions
+- **Commit Messages**: `.ai/rules/commits.md` - Commit message guidelines (Conventional Commits)
+- **Pull Request Process**: `.ai/rules/pull-requests.md` - PR creation and review guidelines
+
 ## MCP (Model Context Protocol) Setup
 
 AI tools can access external services (JIRA, Confluence, GitHub) via MCP configuration.
@@ -25,7 +87,7 @@ AI tools can access external services (JIRA, Confluence, GitHub) via MCP configu
    - Create a classic token by pressing the first "Create Token" button
    - Copy the token
 
-3. **Edit `.env.mcp` with your credentials:**
+3. **Edit `.env.mcp` with your credentials**
 
 4. **Verify your setup:**
 
@@ -56,69 +118,13 @@ The `mcp.json` file configures these services:
 - **context-7** - Advanced context management
 - **atlassian** - JIRA (RI-XXX tickets) and Confluence integration
 
-## Structure
-
-```
-.ai/                                  # 🎯 Single source of truth
-├── README.md                         # Overview & quick reference
-├── rules/                            # Development standards (modular)
-│   ├── code-quality.md               # Linting, TypeScript standards
-│   ├── frontend.md                   # React, Redux, UI patterns
-│   ├── backend.md                    # NestJS, API patterns
-│   ├── testing.md                    # Testing standards
-│   ├── branches.md                   # Branch naming conventions
-│   ├── commits.md                    # Commit message guidelines
-│   └── pull-requests.md              # Pull request process
-└── commands/                         # AI workflow commands
-    ├── commit-message.md             # Commit message generation
-    └── pull-request-review.md        # PR review workflow
-
-# Symlinks (all AI tools read from .ai/)
-.cursor/
-  ├── rules/ -> ../.ai/rules/         # Cursor AI (rules)
-  └── commands/ -> ../.ai/commands/   # Cursor AI (commands)
-.augment/ -> .ai/                     # Augment AI
-.windsurfrules -> .ai/                # Windsurf AI
-.github/copilot-instructions.md       # GitHub Copilot
-```
-
-## Project Overview
-
-**RedisInsight** is a desktop application for Redis database management built with:
-
-- **Frontend**: React 18, TypeScript, Redux Toolkit, Elastic UI, Monaco Editor, Vite
-- **Backend**: NestJS, TypeScript, Node.js
-- **Desktop**: Electron for cross-platform distribution
-- **Testing**: Jest, Testing Library, Playwright
-
-**Architecture**:
-
-```
-redisinsight/
-├── ui/          # React frontend (Vite + TypeScript)
-├── api/         # NestJS backend (TypeScript)
-├── desktop/     # Electron main process
-└── tests/       # E2E tests (Playwright)
-```
-
-## Detailed Guidelines
-
-All detailed development standards, coding practices, and workflows are maintained in modular files:
-
-- **Code Quality Standards**: See `.ai/rules/code-quality.md`
-- **Frontend Patterns**: See `.ai/rules/frontend.md`
-- **Backend Patterns**: See `.ai/rules/backend.md`
-- **Testing Standards**: See `.ai/rules/testing.md`
-- **Branch Naming**: See `.ai/rules/branches.md`
-- **Commit Messages**: See `.ai/rules/commits.md`
-- **Pull Request Process**: See `.ai/rules/pull-requests.md`
-
 ## Updating These Rules
 
 To update AI rules:
 
 1. **Edit files in `.ai/` only** (never edit symlinked files directly)
-2. Changes automatically propagate to all AI tools
-3. Commit changes to version control
+2. **Update `AGENTS.md`** if you change commands, testing instructions, or boundaries
+3. Changes automatically propagate to all AI tools via symlinks
+4. Commit changes to version control
 
 **Remember**: These rules exist to maintain code quality and consistency. Follow them, but also use good judgment.
@@ -1,17 +1,19 @@
 # GitHub Copilot Instructions for RedisInsight
 
-> **📚 All development rules and guidelines are in the `.ai/` directory**
+> **🎯 Start here: Read `AGENTS.md` at the repository root for essential commands, testing instructions, and quick reference**
 
-This project uses a centralized AI rules structure. All detailed guidelines, standards, and workflows are maintained in the `.ai/` directory as the single source of truth.
+This project uses a centralized AI rules structure:
+
+- **`AGENTS.md`** (repository root) - Entry point with commands, testing, and boundaries
+- **`.ai/rules/`** - Detailed development standards organized by topic
+- **`.ai/commands/`** - AI workflow commands and templates
 
 ## 📂 Rules Structure
 
 ### Core Development Rules
 
 - **Code Quality**: `.ai/rules/code-quality.md`
 
-  - ESLint configuration (Airbnb base)
-  - Prettier formatting standards
   - TypeScript best practices
   - Import organization
   - SonarJS complexity rules
@@ -56,8 +58,9 @@ This project uses a centralized AI rules structure. All detailed guidelines, sta
 
 ### Commands and Workflows
 
-- **Commit Message Generation**: `.ai/commands/commit-message.md`
-- **PR Review**: `.ai/commands/pull-request-review.md`
+- **PR Plan**: `.ai/commands/pr-plan.md` - Analyze JIRA tickets (RI-XXX) and create detailed implementation plans
+- **Commit Message Generation**: `.ai/commands/commit-message.md` - Generate commit messages following Conventional Commits
+- **PR Review**: `.ai/commands/pull-request-review.md` - Review pull requests and provide feedback
 
 ## 🎯 Project Overview
 
@@ -76,8 +79,9 @@ This project uses a centralized AI rules structure. All detailed guidelines, sta
 
 ## 📖 Additional Documentation
 
-For a comprehensive introduction and quick reference, see: `.ai/README.md`
+- **For AI agents**: Start with `AGENTS.md` at repository root
+- **For human developers**: See `.ai/README.md` for setup and overview
 
 ---
 
-**Note**: This is a minimal reference file. GitHub Copilot cannot read the referenced files directly, but developers can access the full guidelines in the `.ai/` directory. Other AI tools (Cursor, Augment, Windsurf) access these rules via symlinks.
+**Note**: This is a minimal reference file. GitHub Copilot cannot read the referenced files directly, but developers can access the full guidelines. Other AI tools (Cursor, Augment, Windsurf) access these rules via symlinks and can read `AGENTS.md` directly.
@@ -0,0 +1,120 @@
+# RedisInsight AI Agent Instructions
+
+This file provides essential context and instructions for AI coding agents working on RedisInsight.
+
+## Project Overview
+
+**RedisInsight** is a desktop application for Redis database management built with:
+
+- **Frontend**: React 18, TypeScript, Redux Toolkit, styled-components, Monaco Editor, Vite
+- **Backend**: NestJS, TypeScript, Node.js
+- **Desktop**: Electron for cross-platform distribution
+- **Testing**: Jest, Testing Library, Playwright
+
+**Architecture**:
+
+```
+redisinsight/
+├── ui/          # React frontend (Vite + TypeScript)
+├── api/         # NestJS backend (TypeScript)
+├── desktop/     # Electron main process
+└── tests/       # E2E tests (Playwright)
+```
+
+## Setup Commands
+
+### Development
+
+```bash
+# Frontend development (web)
+yarn dev:ui
+
+# Backend development
+yarn dev:api
+
+# Desktop app development (runs all: API + UI + Electron)
+yarn dev:desktop
+
+# Frontend with coverage
+yarn dev:ui:coverage
+```
+
+## Testing Instructions
+
+### Run Tests
+
+```bash
+# Frontend tests
+yarn test              # Run all UI tests
+
+# Backend tests
+yarn test:api          # Run all API tests
+
+# E2E tests
+yarn --cwd tests/e2e test
+```
+
+### Before Committing
+
+**ALWAYS run these before committing:**
+
+```bash
+# Lint check
+yarn lint              # All code
+yarn lint:ui           # Frontend only
+yarn lint:api          # Backend only
+
+# Type checking
+yarn type-check:ui     # Frontend TypeScript
+
+# Tests
+yarn test              # Frontend tests
+yarn test:api          # Backend tests
+```
+
+**Fix any linting errors, type errors, or test failures before committing.**
+
+All detailed development standards are maintained in `.ai/rules/`:
+
+- **Code Quality**: `.ai/rules/code-quality.md` - Linting, TypeScript standards
+- **Frontend**: `.ai/rules/frontend.md` - React, Redux, UI patterns, styled-components
+- **Backend**: `.ai/rules/backend.md` - NestJS, API patterns, dependency injection
+- **Testing**: `.ai/rules/testing.md` - Testing standards, faker usage, test patterns
+- **Branches**: `.ai/rules/branches.md` - Branch naming conventions
+- **Commits**: `.ai/rules/commits.md` - Commit message guidelines
+- **Pull Requests**: `.ai/rules/pull-requests.md` - PR process and review guidelines
+
+**Refer to these files for comprehensive guidelines on each topic.**
+
+## Boundaries
+
+### ✅ Always Do
+
+- Write to `src/` and `tests/` directories
+- Run `yarn lint` and `yarn test` before commits
+- Follow naming conventions (camelCase, PascalCase, UPPER_SNAKE_CASE)
+- Use faker library for test data generation
+- Use `renderComponent` helper in component tests
+- Extract duplicate strings to constants
+- Use semantic colors from theme (not CSS variables)
+- Use layout components (Row/Col/FlexGroup) instead of div
+- Pass layout props as component props (not hardcoded in styles)
+
+### ⚠️ Ask First
+
+- Database schema changes
+- Adding new dependencies
+- Modifying CI/CD configuration (`.github/workflows/`)
+- Changes to build configuration
+- Breaking changes to APIs
+
+### 🚫 Never Do
+
+- Commit secrets or API keys
+- Edit `node_modules/` or `vendor/` directories
+- Use fixed time waits in tests (use `waitFor` instead)
+- Use `!important` in styled-components
+- Import directly from `@redis-ui/*` (use internal wrappers from `uiSrc/components/ui`)
+- Use Elastic UI for new code (migrating to Redis UI)
+- Use hardcoded pixel values (use theme spacing)
+- Use `any` type without reason