(grails-core) branch 8.0.x_fix_skills updated: codebase memory skill

[bo...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

borinquenkid pushed a commit to branch 8.0.x_fix_skills
in repository https://gitbox.apache.org/repos/asf/grails-core.git


The following commit(s) were added to refs/heads/8.0.x_fix_skills by this push:
     new 20d73c6bad codebase memory skill
20d73c6bad is described below

commit 20d73c6bad6c2d082a548b6b0627d180b46ce7ba
Author: Walter Duque de Estrada <wb...@mac.com>
AuthorDate: Sat Apr 11 21:15:41 2026 -0500

    codebase memory skill
---
 .agents/skills/codebase-memory/SKILL.md | 118 +++++++++++++++
 AGENTS.md                               | 260 +++++++++++++++++++++++++++++++-
 2 files changed, 377 insertions(+), 1 deletion(-)

diff --git a/.agents/skills/codebase-memory/SKILL.md b/.agents/skills/codebase-memory/SKILL.md
new file mode 100644
index 0000000000..ed68dd8eaa
--- /dev/null
+++ b/.agents/skills/codebase-memory/SKILL.md
@@ -0,0 +1,118 @@
+---
+name: codebase-memory-setup
+description: Helps the developer set up codebase-memory-mcp locally
+license: Apache-2.0
+---
+<!-- @formatter:off -->
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements. See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership. The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License. You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied. See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+---
+name: codebase-memory-setup
+description: >
+Verify and set up the codebase-memory MCP server for Grails-Core architectural navigation.
+Use this skill at the start of any Grails-Core session to detect whether the MCP server is
+active, prompt the user to install it if missing, and provide step-by-step configuration
+instructions. Trigger whenever working with grails-core and MCP tool availability is unknown,
+or when the user asks about faster codebase navigation, architectural mode, or MCP setup.
+---
+
+# Codebase Memory MCP: Environment Verification & Setup
+
+This skill governs how to verify, onboard, and configure the `codebase-memory` MCP server when
+working in the Grails-Core repository. It enables "Architectural Mode" — a significantly faster
+mode of codebase navigation using graph-based memory tools.
+
+---
+
+## Step 1: Detect Operating Mode (Mandatory on Load)
+
+Before doing anything else, check your available tool definitions for the presence of any of
+these tools:
+
+- `index_repository`
+- `search_graph`
+- `trace_call_path`
+- `query_graph`
+
+| Condition | Mode |
+|---|---|
+| Tools **present** | **Architectural Mode** — proceed normally |
+| Tools **absent** | **Standard Mode** — proceed to Step 2 |
+
+---
+
+## Step 2: Proactive Onboarding (Standard Mode Only)
+
+If the MCP server is **not** detected, interrupt the current flow (unless addressing a critical
+fix) and present the following message to the user:
+
+> "I've detected that this repository is optimized for **Codebase Memory MCP**, which allows me
+> to navigate the Grails-Core architecture 90% faster. However, the server is not currently
+> running in your environment. Would you like me to help you install it now?"
+
+Wait for the user's response before continuing.
+
+---
+
+## Step 3: Installation (If User Approves)
+
+The package ships as a **static binary** (not npm). Use the appropriate one-liner for the user's
+platform, or run it yourself if you have shell access.
+
+**macOS / Linux (bash):**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
+```
+
+**Windows (PowerShell):**
+
+```powershell
+irm https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/scripts/setup-windows.ps1 | iex
+```
+
+Both scripts download the correct binary for the platform, place it on the PATH, and run
+`codebase-memory-mcp install` to auto-configure all detected agents (Claude Code, Zed, Cursor,
+etc.) in one step.
+
+> **Note:** `npm install -g codebase-memory-mcp` will not work — ignore any documentation
+> suggesting this.
+
+After the script completes, restart the agent environment.
+
+### Index the Repository
+
+Once the server is active, index grails-core by telling the agent:
+
+```
+"Index this project"
+```
+
+The agent will call `index_repository` and build the knowledge graph automatically.
+
+---
+
+## Step 4: Verify Activation
+
+Confirm that `index_repository`, `search_graph`, `trace_call_path`, and `query_graph` are now
+available. If they are, **Architectural Mode** is active — proceed with the original task.
+
+If tools are still missing, ask the user to confirm the install script completed without errors
+and that the agent environment was fully restarted.
\ No newline at end of file
diff --git a/AGENTS.md b/AGENTS.md
index eabfa51cdd..c1e4add3ab 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,3 +1,19 @@
+<!--
+SPDX-License-Identifier: Apache-2.0
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
 # Agent Guide for grails-core
 
 > **IMPORTANT**: This is the Grails Framework source repository (60+ modules), NOT a Grails application.
@@ -20,4 +36,246 @@
 ./gradlew codeStyle
 
 # Out of memory? Set:
-export GRADLE_OPTS="-Xms2G -Xmx5G"
\ No newline at end of file
+export GRADLE_OPTS="-Xms2G -Xmx5G"
+```
+
+## Critical Rules
+
+1. **Use `jakarta.*` NOT `javax.*`** - All packages migrated to Jakarta EE 10
+2. **Use `@GrailsCompileStatic`** - Not plain `@CompileStatic` in Grails artefact classes
+3. **Use `GrailsWebRequest.lookup()`** - For thread-safe request context in tests
+4. **No wildcard imports** - Use explicit imports
+5. **4 spaces, no tabs** - See `.editorconfig`
+6. **Apache license header** - Required on all new source files
+7. **New features require docs** - Any user-facing change must include or update documentation in `grails-doc`; do not merge features without corresponding doc coverage
+8. **No internal APIs in docs** - Only document public APIs; never reference internal or package-private classes and methods in user-facing documentation
+9. **Test via public APIs** - Tests must exercise behavior through the same APIs an end user calls; never invoke internal implementations, package-private methods, or bypass the public surface directly
+10. **Always review and extend tests** - Review existing unit and functional tests before making changes; every code change must include new or enhanced tests that cover the affected behavior
+11. **Every code touch must update all tests for the changed class** - When a class is modified, find and update every test that covers it — unit, integration, and TCK. Do not leave any existing test out of sync with the new code.
+12. **Clean violations before commit** - Before every automated commit, run `./gradlew clean aggregateStyleViolations test aggregateTestFailures --continue` from the root and ensure that `CHECKSTYLE_VIOLATIONS.md`, `CODENARC_VIOLATIONS.md`, `PMD_VIOLATIONS.md`, and `TEST_FAILURES.md` report no issues and are removed.
+13. **Mandatory test coverage** - Any class touched in a commit MUST be covered with tests that verify all behavior. You must run ALL tests in the affected module(s) and ensure they pass before committing.
+
+## Available Skills
+
+> **AI AGENTS - MANDATORY**: Before writing or modifying any code, you **MUST** read the relevant skill file(s) below. Do not write Groovy/Grails code without first loading these instructions:
+> - Writing Grails code → Read `.agents/skills/grails-developer/SKILL.md`
+> - Writing Groovy code → Read `.agents/skills/groovy-developer/SKILL.md`
+> - Writing Java code → Read `.agents/skills/java-developer/SKILL.md`
+> - Writing Hibernate code → Read `.agents/skills/hibernate-developer/SKILL.md`
+> - Styling code → Read `.agents/skills/style-fixer/SKILL.md`
+> - Fixing broken test → Read `.agents/skills/test-fixer/SKILL.md`
+> - Indexing code -> Read `.agents/skills/codebase-memory/SKILL.md`
+>
+> Use your file reading capability to load the skill content before proceeding with any code changes.
+
+| Skill | Path | Use For |
+|-------|------|---------|
+| **grails-developer** | `.agents/skills/grails-developer/SKILL.md` | Grails 7 apps, GORM, controllers, views |
+| **groovy-developer** | `.agents/skills/groovy-developer/SKILL.md` | Groovy 4 syntax, closures, DSLs, Spock |
+| **java-developer** | `.agents/skills/java-developer/SKILL.md` | Java 17 features, Groovy interop |
+| **hibernate-developer** | `.agents/skills/hibernate-developer/SKILL.md` | Hibernate 7 mapping, binders, generators |
+| **style-fixer** | `.agents/skills/style-fixer/SKILL.md` | Fix style violations (CodeNarc, Checkstyle) |
+| **test-fixer** | `.agents/skills/test-fixer/SKILL.md` | Aggregate and fix test failures |
+| **codebase-memory** | `.agents/skills/codebase-memory/SKILL.md` | Setup codebase-memory-mcp locally |
+
+## Technology Stack
+
+| Component | Version |
+|-----------|---------|
+| JDK | 21+ (baseline 21) |
+| Groovy | 4.0.x |
+| Spring Boot | 4.0.x |
+| Spring Framework | 7.0.x |
+| Spock | 2.3-groovy-4.0 |
+| Gradle | 8.14.x |
+| Jakarta EE | 10 |
+
+## Project Structure
+
+This repository contains multiple independent Gradle projects:
+
+| Project | Description | Build Command |
+|---------|-------------|---------------|
+| **grails-core** (root) | Main framework with 60+ modules | `./gradlew build` |
+| **build-logic/** | Gradle convention plugins for the build | `cd build-logic && ../gradlew build` |
+| **grails-gradle/** | Grails Gradle plugins | `cd grails-gradle && ./gradlew build` |
+| **grails-forge/** | Application generator (like Spring Initializr) | `cd grails-forge && ./gradlew build` |
+
+Each project has its own `settings.gradle` and independent build. When working on a specific project, run Gradle commands from that project's directory.
+
+## Key Modules
+
+**Core**: `grails-core`, `grails-bootstrap`, `grails-spring`, `grails-common`
+
+**Web**: `grails-web-core`, `grails-web-mvc`, `grails-controllers`, `grails-url-mappings`, `grails-interceptors`
+
+**GORM**: `grails-datastore-core`, `grails-datamapping-core`, `grails-domain-class`, `grails-validation`, `grails-databinding`
+
+**Views**: `grails-views-core`, `grails-views-gson`, `grails-views-markup`
+
+**Testing**: `grails-testing-support-core`, `grails-testing-support-web`, `grails-geb`
+
+**Other**: `grails-bom` (dependency management), `grails-doc`, `grails-shell-cli`, `grails-forge`
+
+## Artefact Types
+
+| Type | Pattern | Handler |
+|------|---------|---------|
+| Domain | `**/domain/**/*.groovy` | `DomainClassArtefactHandler` |
+| Controller | `**/*Controller.groovy` | `ControllerArtefactHandler` |
+| Service | `**/*Service.groovy` | `ServiceArtefactHandler` |
+| TagLib | `**/*TagLib.groovy` | `TagLibArtefactHandler` |
+| Interceptor | `**/*Interceptor.groovy` | `InterceptorArtefactHandler` |
+
+## Code Patterns
+
+### Spock Test Structure
+```groovy
+class MyServiceSpec extends Specification implements ServiceUnitTest<MyService> {
+    def "feature description"() {
+        given: "preconditions"
+        def input = "test"
+
+        when: "action"
+        def result = service.process(input)
+
+        then: "assertions"
+        result != null
+        result.status == "OK"
+    }
+}
+```
+
+### Mocking
+```groovy
+def repo = Mock(BookRepository)
+1 * repo.save(_) >> savedBook  // expect 1 call, return savedBook
+```
+
+### Data-Driven Tests
+```groovy
+@Unroll
+def "#a + #b == #c"() {
+    expect: a + b == c
+    where:
+    a | b || c
+    1 | 2 || 3
+    4 | 5 || 9
+}
+```
+
+### Framework Access
+```groovy
+// Thread-safe request context
+GrailsWebRequest webRequest = GrailsWebRequest.lookup()
+
+// Artefact registry
+grailsApplication.getArtefacts(DomainClassArtefactHandler.TYPE)
+```
+
+## Groovy Style
+
+```groovy
+// DO: Safe navigation
+book?.author?.name
+
+// DO: Elvis operator
+name ?: 'Unknown'
+
+// DO: GStrings
+"Hello ${user.name}"
+
+// DO: Spread operator
+books*.title
+
+// DO: Static compilation
+@GrailsCompileStatic  // or @CompileStatic for non-artefact classes
+class MyService { }
+
+// DON'T: Wildcard imports
+// import java.util.*  ❌
+
+// DON'T: javax packages
+// import javax.servlet.*  ❌ → use jakarta.servlet.*
+
+// DON'T: Section separator or grouping comments
+// // --- Domain classes ---  ❌
+// // ===== Helpers =====     ❌
+```
+
+## Test Isolation
+
+> **WARNING**: Tests run in parallel (`maxParallelForks > 1`). Static state that is not properly reset in test cleanup can cause flaky tests in subsequent tests within the same fork.
+
+- Use `GrailsWebRequest.lookup()` for thread-local context
+- Clear artefacts: `grailsApplication.artefactInfo.clear()`
+- Use `@Shared` for fields that should be reused by multiple feature methods in a Spec
+
+## Build Commands
+
+| Task | Command |
+|------|---------|
+| Build (no tests) | `./gradlew build -PskipTests` |
+| Build module | `./gradlew :grails-core:build` |
+| Test module | `./gradlew :grails-core:test` |
+| Single test | `./gradlew :module:test --tests "pkg.MySpec"` |
+| Single feature | `./gradlew :module:test --tests "pkg.MySpec.feature name"` |
+| Force rerun | `./gradlew :module:test --rerun-tasks` |
+| Style check | `./gradlew codeStyle` |
+| Build docs | `./gradlew :grails-doc:publishGuide -x aggregateGroovydoc` |
+| Debug | `./gradlew bootRun --debug-jvm` |
+
+## Branch Naming (Auto-Labels PRs)
+
+| Prefix | Label |
+|--------|-------|
+| `fix/` | bug |
+| `feat/`, `feature/` | feature |
+| `docs/` | documentation |
+| `chore/`, `refactor/`, `test/`, `ci/`, `perf/`, `build/` | maintenance |
+| `deps/` | deps |
+
+## Pull Request Guidelines
+
+1. **Fork & branch** from the target release branch (e.g., `7.0.x`)
+2. **Run tests** before submitting: `./gradlew build --rerun-tasks`
+3. **Run code style checks**: `./gradlew codeStyle`
+4. **Clean style violations**: Before committing, run `./gradlew clean aggregateStyleViolations` from the root and ensure that `CHECKSTYLE_VIOLATIONS.md`, `CODENARC_VIOLATIONS.md`, and `PMD_VIOLATIONS.md` have no issues.
+5. **Verify test coverage**: Ensure any touched class is covered by tests verifying all behavior. You must run ALL tests in the affected module(s) and ensure they pass before submission.
+6. **Squash commits** into a single meaningful commit message
+6. **Reference issues** in PR description (e.g., "Fixes #1234")
+
+### Review Process
+
+| Change Type | Review Policy | Reviewers | Wait Period |
+|-------------|---------------|-----------|-------------|
+| Build/CI changes | Commit then Review | - | - |
+| Documentation | Commit then Review (obvious fixes) | 1 minimum | - |
+| Groovy/Spring dependency changes | Review then Commit | 2-3 required | 3 days (weekend) / 1 day (weekday) |
+| All other changes | Review then Commit | 1 required | - |
+
+See `CONTRIBUTING.md` for full details.
+
+## Common Issues
+
+| Problem | Solution |
+|---------|----------|
+| Out of memory | `export GRADLE_OPTS="-Xms2G -Xmx5G"` |
+| Container missing | Use `-PskipTests` or install Docker/Podman |
+| Flaky tests | Check static state pollution, ensure proper cleanup in tests |
+| Cache issues | `./gradlew --rerun-tasks` |
+| Deprecation details | `./gradlew <task> --warning-mode all` |
+
+
+### Reporting Vulnerabilities
+
+Please see the page of the [ASF Security Team](https://www.apache.org/security/) for further information and contact information.
+
+## Resources
+
+- **Grails 7 Guide**: https://grails.apache.org/docs/latest/guide/single.html
+- **Groovy 4 Docs**: https://docs.groovy-lang.org/docs/groovy-4.0.30/html/documentation/
+- **Spock 2.3 Docs**: https://spockframework.org/spock/docs/2.3/all_in_one.html
+- **GORM Docs**: https://grails.apache.org/docs/latest/grails-data/
+- **Issues**: https://github.com/apache/grails-core/issues
+- **Slack**: https://grails.slack.com