Add AGENTS.md and AI coding assistant support #15340
Open
+1,960
−0
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
jdaugherty
reviewed
Jan 25, 2026
Contributor
jdaugherty
left a comment
jdaugherty
left a comment
There was a problem hiding this comment.
There is a lot of information missing from this file. Some of it:
- We need to inform LLMs of our project structure (it's not that it's multiproject, but the composite build is important to mention). This includes directory discussions.
- Build instructions need run - rat & codestyle need explicitly mentioned
- We need rules on restructuring the project
- We need rules on dependency includes and when to include, where
The purpose of this file is to make it easier for the LLM to understand how to run tests, how to make changes, etc. While this is a good starting point, we need to be much more thorough.
Contributor
|
AGENTS.md - some items we might want to include |
Contributor
|
@sanjana2505006 I am going to push some additional changes to this PR based on https://github.com/apache/superset/ and the conversation in our weekly Grails planning meeting. |
Replaces the previous ASF license header notes with a comprehensive guide for automated coding agents and developers. Adds detailed instructions on environment setup, build/test commands, code style, Spock/Groovy conventions, commit/PR guidelines, parallel test isolation, and documentation processes for the grails-core repository.
Add three specialized skills in .agents/skills/ for AI agent guidance: - grails-developer: Grails 7 development with GORM, controllers, services, views, plugins, and Spock/Geb testing - groovy-developer: Groovy 4 syntax, closures, DSLs, metaprogramming, static compilation, and testing patterns - java-developer: Java 17 features including records, sealed classes, pattern matching, and Groovy interoperability Skills follow the open AGENTS.md standard format with compatibility for Claude, Copilot, Cursor, Gemini, Windsurf, Cline, and others.
Add instruction files that reference AGENTS.md for various AI tools: - CLAUDE.md: Claude Code - GEMINI.md: Google Gemini CLI - .github/copilot-instructions.md: GitHub Copilot - .cursorrules: Cursor - .windsurfrules: Windsurf - .clinerules: Cline Update AGENTS.md with optimized agent-friendly format: - Quick reference section with common commands - Critical rules highlighted (jakarta.*, @GrailsCompileStatic, etc.) - Concise tables for technology stack, modules, and artefacts - Code patterns for Spock tests, mocking, and framework access - Test isolation warnings for parallel execution - Troubleshooting table for common issues All files include Apache License headers and reference the skills in .agents/skills/ for detailed guidance.
jamesfredley
changed the title
Contributor
|
We will likely want to copy this over to grails-spring-security, grails-cache and grails-quartz. |
Eliminates duplication by making all AI assistant config files symlinks to the canonical AGENTS.md, ensuring content loads automatically.
Updated AGENTS.md to require AI agents to read relevant skill files before writing or modifying Groovy, Grails, or Java code. This ensures agents follow best practices and guidelines specific to each language or framework.
Creates .claude/skills/ directory with symlinks to the canonical skill files in .agents/skills/, enabling Claude Code slash commands.
jdaugherty
approved these changes
Jan 28, 2026
Contributor
jdaugherty
left a comment
jdaugherty
left a comment
There was a problem hiding this comment.
I think this is a good start
Contributor
|
@sanjana2505006 Let's let @jamesfredley implement the feedback in this PR and we'll merge once @matrei also reviews. |
Deleted the .github/copilot-instructions.md symlink that pointed to ../AGENTS.md. This cleans up unused or obsolete configuration.
Added a new section detailing the repository's multi-project Gradle structure and build commands. Introduced pull request guidelines and review process table. Updated security reporting instructions to reference the ASF Security Team.
jdaugherty
approved these changes
Jan 29, 2026
- Clarify @GrailsCompileStatic usage for artefact classes only - Fix test isolation warning about static state cleanup - Replace @ResourceLock with @shared (no Spock parallel execution) - Update documentation URLs to grails.apache.org - Fix grails-developer skill: logback-spring.xml, spring/resources.groovy - Add integration-test/groovy directory to project structure - Update to ContainerGebSpec for Geb tests - Update plugin coordinates to org.apache.grails.plugins - Change codeStyle to check task (more general) - Use single quotes for simple strings in Groovy examples
- Rename 'double' to 'twice' (double is reserved word) - Remove (Incubating) from Records section (stable in Groovy 4) - Update @GrailsCompileStatic example to use dynamic finder - Fix imports: groovy.lang.Delegate and groovy.lang.Singleton - Add parentheses guidance to code style - Clarify @GrailsCompileStatic usage with 'if needed' - Update GString map key example with toString() - Clarify == vs is comparison (same as Java) - Update static imports guidance - Update GORM URL to grails.apache.org
Contributor
|
@matrei I pushed a couple commits with requested changes. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Add comprehensive support for AI coding assistants working with the Grails codebase:
.agents/skills/for Grails 7, Groovy 4, and Java 17.claude/skills/enabling slash commands for developer skillsArchitecture
All agent instruction files are symlinks to AGENTS.md, ensuring:
Files Added
AGENTS.md.agents/skills/grails-developer/SKILL.md.agents/skills/groovy-developer/SKILL.md.agents/skills/java-developer/SKILL.mdCLAUDE.mdGEMINI.md.github/copilot-instructions.md.cursorrules.windsurfrules.clinerules.claude/skills/*/SKILL.mdAGENTS.md Highlights
Skills Coverage
Test Plan
ls -laandcat)