diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000000..1cff7a13c7a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,178 @@
+# OpenProject AI Coding Agent Instructions
+
+## Repository Overview
+
+**OpenProject** is a web-based, open-source project management software written in Ruby on Rails with PostgreSQL for data persistence.
+
+- **Size**: Large monorepo (~840MB, ~1M+ lines of code)
+- **Backend**: Ruby 3.4.5, Rails ~8.0.3
+- **Frontend**: Node.js 22.21.0, npm 10.1.0+, TypeScript
+- **Database**: PostgreSQL (required)
+- **Architecture**: Server-rendered HTML with Hotwire (Turbo + Stimulus). Legacy Angular components exist and are being migrated to custom elements. Uses GitHub's Primer Design System via ViewComponent.
+- **Editions**: Community, Enterprise (SSO, LDAP, SCIM), and BIM (construction industry, code in `modules/bim/`)
+
+## Critical Setup Requirements
+
+**ALWAYS verify versions before building:**
+- Ruby: `3.4.5` (see `.ruby-version`)
+- Node: `^22.21.0` (see `package.json` engines)
+- Bundler: Latest 2.x
+
+**Local Development Setup:**
+```bash
+bundle install                    # Install Ruby gems
+cd frontend && npm ci && cd ..   # Install Node packages
+bundle exec rake db:migrate      # Setup database
+bin/dev                          # Start all services (Rails, frontend, Good Job worker)
+# Access at http://localhost:3000
+```
+
+**Docker Setup:** See `docker-compose.yml` and run `bin/compose setup`. Note: `config/database.yml` must NOT exist when using Docker.
+
+## Project Structure
+
+### Key Directories
+- `app/` - Rails application code
+  - `app/components/` - ViewComponent-based UI components (Ruby + ERB)
+  - `app/contracts/` - Validation and authorization contracts
+  - `app/controllers/` - Rails controllers
+  - `app/models/` - ActiveRecord models
+  - `app/services/` - Service objects (business logic)
+  - `app/workers/` - Background job workers
+- `config/` - Rails configuration, routes, locales
+- `db/` - Database migrations and seeds
+- `frontend/src/` - Frontend code
+  - `frontend/src/app/` - Legacy Angular modules/components
+  - `frontend/src/stimulus/` - Stimulus controllers
+  - `frontend/src/turbo/` - Turbo integration
+- `lib/` - Ruby libraries and extensions
+- `lookbook/` - ViewComponent previews (https://qa.openproject-edge.com/lookbook/)
+- `modules/` - OpenProject plugin modules
+- `spec/` - RSpec test suite
+  - `spec/features/` - System/feature tests (Capybara)
+  - `spec/models/` - Model unit tests
+  - `spec/requests/` - API/integration tests
+  - `spec/services/` - Service tests
+
+### Configuration Files
+- `.ruby-version` - Ruby version
+- `.rubocop.yml` - Ruby linting rules
+- `.erb_lint.yml` - ERB template linting
+- `frontend/eslint.config.mjs` - JavaScript/TypeScript linting
+- `Gemfile` - Ruby dependencies
+- `package.json` / `frontend/package.json` - Node.js dependencies
+- `lefthook.yml` - Git hooks configuration
+
+## Building and Testing
+
+### Linting (Run Before Committing)
+
+```bash
+# Ruby
+bundle exec rubocop                              # Check all files
+bin/dirty-rubocop --uncommitted                  # Check only uncommitted changes
+
+# JavaScript/TypeScript
+cd frontend && npx eslint src/ && cd ..
+
+# ERB Templates
+erb_lint {files}
+
+# Install Git Hooks (recommended)
+bundle exec lefthook install
+```
+
+### Running Tests
+
+```bash
+# Backend (RSpec) - prefer specific tests over running all
+bundle exec rspec spec/models/user_spec.rb              # Single file
+bundle exec rspec spec/models/user_spec.rb:42           # Single line
+bundle exec rspec spec/features                         # Directory
+bundle exec rake parallel:spec                          # Parallel execution
+
+# Frontend (Jasmine/Karma)
+cd frontend && npm test && cd ..
+```
+
+### Debugging CI Failures
+```bash
+./script/github_pr_errors | xargs bundle exec rspec    # Run failed tests from CI
+./script/bulk_run_rspec spec/path/to/flaky_spec.rb     # Run tests multiple times
+```
+
+## Code Style Guidelines
+
+### Ruby
+- Follow [Ruby community style guide](https://github.com/bbatsov/ruby-style-guide)
+- Use service objects for complex business logic (return `ServiceResult`)
+- Use contracts for validation and authorization
+- Keep controllers thin, models focused
+- Document with [YARD](https://yardoc.org/)
+- Write RSpec tests for all new features
+
+### JavaScript/TypeScript
+- **New development**: Use Hotwire (Turbo + Stimulus) with server-rendered HTML
+- **Legacy code**: Follow ESLint rules
+- Prefer TypeScript over JavaScript
+- Use [Primer Design System](https://primer.style/product/) via ViewComponent
+
+### Templates
+- Use ERB for server-rendered views
+- Use ViewComponents for reusable UI (with Lookbook previews)
+- Lint with erb_lint before committing
+
+### Database Migrations
+- Follow Rails migration conventions
+- Migrations are "squashed" between major releases (see `docs/development/migrations/`)
+
+### Translations
+- UI strings must use translation keys (never hard-coded)
+- Source translations in `**/config/locales/en.yml` can be modified directly
+- Other translations managed via Crowdin
+
+### Commit Messages
+- First line: < 72 characters, then blank line, then detailed description
+- Reference work packages when applicable
+- Merge strategy: "Merge pull request" (not squash), except single-commit PRs can use "Rebase and merge"
+
+## Important Commands Reference
+
+```bash
+# Setup
+bin/setup              # Initial Rails setup
+bin/setup_dev          # Full dev environment setup
+
+# Database
+bundle exec rake db:migrate              # Run migrations
+bundle exec rake db:rollback             # Rollback last migration
+bundle exec rake db:seed                 # Seed sample data
+
+# Development
+bin/dev                                  # Start all services
+bundle exec rails console                # Rails console
+bundle exec rails routes                 # List routes
+
+# Testing
+bundle exec rspec                        # Run RSpec tests
+bundle exec rake parallel:spec           # Parallel tests
+cd frontend && npm test                  # Frontend tests
+
+# Linting
+bundle exec rubocop                      # Ruby linting
+cd frontend && npx eslint src/           # JS/TS linting
+erb_lint {files}                         # ERB linting
+
+# Docker
+bin/compose setup                        # Setup Docker environment
+bin/compose start                        # Start services
+bin/compose rspec {test_file}            # Run tests in Docker
+```
+
+## Additional Documentation
+
+- `docs/development/` - Development documentation
+- `docs/development/running-tests/` - Testing guide
+- `docs/development/code-review-guidelines/` - Code review standards
+- `CONTRIBUTING.md` - Contribution workflow
+- `.github/copilot-instructions.md` - Extended agent instructions with troubleshooting