Improving AGENTS.md (#329)

Author: jabrena

AGENTS.md

@@ -6,39 +6,191 @@ A collection of `System prompts` for Java Enterprise development.
 
 ### Repository Layout
 
-- `.cursor/rules`: a collection of `System prompts` for Java Enterprise development. The main outcome of this project.
-- `system-prompts-generator`: a Java project designed to build the System prompts based on XML documents.
-- `examples`: a collection of Java examples designed to test with the different System prompts.
-- `site-generator`: JBake project designed to autogenerate public site in `docs` folder
-- `documentation`: Diverse documentation about the project
+```
+java-cursor-rules/
+├── .cursor/rules/                    # 🎯 25 System prompts for Java Enterprise development (main output)
+├── system-prompts-generator/         # 🏗️ Java transformation engine (XML → Markdown cursor rules)
+│   ├── src/main/resources/          # XML rule definitions + XSLT stylesheets
+│   └── src/test/java/              # Automated testing for rule generation
+├── examples/                        # 🧪 9 comprehensive demo projects
+│   ├── spring-boot-demo/           # Complete agile workflow with requirements
+│   ├── spring-boot-*-demo/         # Performance, memory leak, JMeter demos
+│   ├── quarkus-demo/               # Supersonic Subatomic Java framework
+│   ├── aws-lambda-hello-world/     # Serverless Java on AWS
+│   ├── azure-function-hello-world/ # Serverless Java on Azure
+│   └── maven-demo*/                # Testing scenarios (working + broken)
+├── site-generator/                  # 📚 JBake-powered educational website generator
+│   ├── content/                    # Blog posts, courses, documentation
+│   ├── templates/                  # 18 FreeMarker templates for different content types
+│   └── assets/                     # CSS, JS, images for website
+├── documentation/                   # 📖 Comprehensive documentation ecosystem
+│   ├── adr/                        # Architectural Decision Records (3 ADRs)
+│   ├── reviews/                    # AI tool compatibility matrices & evaluations
+│   ├── jeps/                       # Java Enhancement Proposals tracking
+│   ├── dvbe25/                     # 🎤 Conference presentation (Reveal.js)
+│   └── excalidraw/                 # System diagrams and visual documentation
+└── docs/                           # 🌐 Generated static website (GitHub Pages)
+    ├── courses/java-generics/      # 5-module structured learning course
+    ├── blog/                       # Technical articles and release notes
+    └── tags/                       # 23 topic-based content organization
+```
 
-## Build and test commands
+## Modules
 
-- Improve current tests to generate better System prompts encoded in Markdown format
-- Develop or Refactor current System prompts with new Examples
+### 🎯 .cursor/rules/
+The main output of the project - a collection of 25 system prompts for Java Enterprise development. These Markdown files are automatically generated from XML sources and provide AI coding assistance across build systems, design patterns, testing, profiling, and documentation.
 
-When you add new code, format the code before testing:
+### 🏗️ system-prompts-generator/
+Java transformation engine that converts XML rule definitions into Markdown cursor rules using XSLT. Features a 4-stage functional pipeline with XInclude support for modularity, automated testing, and Maven integration for deployment to `.cursor/rules/`.
 
-```bash
-./mvnw clean spotless:apply
-```
+### 🧪 examples/
+Nine comprehensive demo projects showcasing different Java frameworks and scenarios:
+- **Spring Boot demos**: Complete agile workflows, performance testing, memory leak analysis, JMeter integration
+- **Quarkus demo**: Supersonic Subatomic Java framework demonstration
+- **Cloud demos**: AWS Lambda and Azure Functions serverless examples
+- **Maven demos**: Both working and intentionally broken projects for testing cursor rules
+
+### 📚 site-generator/
+JBake-powered static site generator that transforms Markdown content into a professional documentation website. Features 18 specialized FreeMarker templates, structured learning courses (like the 5-module Java Generics course), blog system with tagging, and automated deployment to GitHub Pages.
+
+### 📖 documentation/
+Comprehensive documentation ecosystem including:
+- **ADRs**: 3 Architectural Decision Records documenting technical choices
+- **Reviews**: AI tool compatibility matrices and evaluations
+- **JEPs**: Java Enhancement Proposals tracking for language evolution
+- **Conference Materials**: Reveal.js presentation for conferences and meetups
+- **Visual Documentation**: Excalidraw diagrams and system visualizations
+
+### 🌐 docs/
+Generated static website deployed to GitHub Pages, containing structured courses, technical blog posts, and topic-based navigation with 23 different tags for content organization.
+
+## Development Guidelines
+
+- **Rule Editing**: Don't update files in `.cursor/rules` directly - find the XML source files in `system-prompts-generator/src/main/resources/`
+- **Java Version**: The project is based on Java 24
+- **Build Workflow**: Use the XML-to-Markdown transformation pipeline to generate cursor rules from XML sources
+- **Testing**: Always run tests before promoting changes to ensure rule generation works correctly
+
+## The Comprehensive Documentation Ecosystem
+
+The repository includes a sophisticated documentation framework with multiple specialized components:
+
+### 1. Architectural Decision Records (ADRs)
+- **Location**: `documentation/adr/`
+- **Purpose**: Formal documentation of technical decisions with rationale and consequences
+- **Content**: 3 ADRs covering major architectural choices:
+  - XML-based rule generation approach
+  - Manual scope configuration
+  - Website generation strategy
+
+### 2. Tool Compatibility & Review System
+- **Location**: `documentation/reviews/`
+- **Purpose**: Systematic evaluation of AI coding assistants
+- **Content**: Detailed comparison matrices of 6+ AI tools (Cursor, JetBrains, GitHub Copilot, etc.)
+- **Metrics**: Usability, response speed, reasoning, model support, context windows
+
+### 3. Java Enhancement Proposals (JEPs) Tracking
+- **Location**: `documentation/jeps/`
+- **Purpose**: Continuous monitoring of Java language evolution from Java 8 to Java 25
+- **Integration**: Analysis of how new JEPs could improve existing cursor rules
+- **Value**: Keeps the project current with Java language developments
+
+## System Architecture
 
-Run the tests:
+### The Transformation Pipeline
 
+The repository implements a sophisticated XML-to-Markdown transformation system that powers the entire cursor rules generation process through a multi-stage pipeline:
+
+#### Core Architecture
+- **XML Schema-Based Rule Definitions**: 25+ structured XML files defining complete cursor rules following a common vocabulary defined by [pml.xsd](https://jabrena.github.io/pml/schemas/0.1.0-SNAPSHOT/pml.xsd) (see [system-prompts-generator/src/main/resources/](system-prompts-generator/src/main/resources/))
+- **XSLT Transformation Engine**: Single unified stylesheet (`cursor-rules.xsl`) converting XML to Markdown
+- **Java Processing Pipeline**: 4-stage functional pipeline with XInclude support for modularity
+- **Modular Fragment System**: 13 reusable templates and automation scripts
+
+#### Transformation Flow
+```
+XML Rule Definitions → XInclude Processing → XSLT Transformation → Markdown Cursor Rules
+```
+
+#### Key Benefits
+- **Consistency at Scale**: All 25+ cursor rules follow identical structure and formatting
+- **Domain-Specific Language**: Structured approach to prompt engineering with reusable components
+- **Enterprise Maintainability**: Single source of truth with automated testing and deployment
+- **Build Integration**: Maven-driven automation with automatic deployment to `.cursor/rules/`
+
+This pipeline essentially functions as a **compiler for cursor rules**, transforming high-level XML specifications into deployable Markdown files while ensuring consistency, maintainability, and scalability across the entire rule set.
+
+### Site Generation & Public Documentation System
+
+The repository includes a comprehensive **JBake-powered static site generator** that transforms Markdown content into a professional documentation website deployed at `https://jabrena.github.io/cursor-rules-java/`.
+
+#### Architecture & Integration
+- **Technology Stack**: JBake 2.7.0-rc.7 with FreeMarker templates and Maven integration
+- **Build Integration**: Dedicated Maven module (`site-generator`) with specialized profile (`site-update`)
+- **Output Location**: Generates static HTML/CSS/JS files in the `docs/` directory for GitHub Pages deployment
+- **Content Pipeline**: Markdown → JBake → Static HTML → GitHub Pages
+
+#### Content Organization
+- **Blog System**: Technical articles with date-based organization and tagging
+  - Release announcements and changelogs
+  - Technical deep-dives (e.g., "The Three-Node Quality Framework for AI Prompts")
+  - Feature explanations and tutorials
+- **Course Generation**: Structured learning modules with progressive complexity
+  - **Java Generics Course**: 5-module comprehensive course with assessments
+  - **Module Structure**: Foundations → Wildcards → Advanced → Real-world → Assessment
+  - **Interactive Elements**: FAQ sections, code examples, and practical exercises
+- **Tag-Based Navigation**: Semantic organization by topics (generics, type-safety, performance, etc.)
+
+#### Template System
+- **18 Specialized Templates**: Custom FreeMarker templates for different content types
+- **Responsive Design**: Bootstrap-based responsive layout with custom styling
+- **Content Types**: Posts, courses, pages, archives, tag listings, and RSS feeds
+- **Dynamic CSS Generation**: Template-driven CSS compilation for consistent theming
+
+#### Build Commands
 ```bash
-./mvnw clean verify -pl system-prompts-generator
+# Generate and deploy the website
+./mvnw clean generate-resources -pl site-generator -P site-update
+
+# Local development server
+jwebserver -p 8000 -d "$(pwd)/docs"
 ```
 
-If the tests passes, you could promote the changes to `.cursor/rules`:
+#### Key Features
+- **Automated Course Generation**: Transforms cursor rule content into structured learning paths
+- **SEO Optimization**: Proper meta tags, sitemaps, and RSS feeds
+- **Analytics Integration**: Google Analytics and social media integration
+- **Asset Management**: Optimized handling of images, CSS, and JavaScript resources
+
+#### Content Strategy
+The site serves multiple purposes:
+1. **Public Documentation**: User-facing guides and tutorials
+2. **Educational Content**: Structured courses for learning Java concepts
+3. **Project Updates**: Release notes and development progress
+4. **Community Engagement**: Blog posts and technical articles
+
+This system transforms the repository from a simple rule collection into a **comprehensive educational platform** that supports both immediate cursor rule usage and long-term Java learning objectives.
+
+## Build/Test Commands
+
+- Java 24 required
 
 ```bash
+./mvnw clean verify
+./mvnw clean verify -pl system-prompts-generator
 ./mvnw clean install -pl system-prompts-generator
+./mvnw clean generate-resources -pl site-generator -P site-update
 ```
 
-## General Guidance
+## Common Tasks
 
-- Don´t update any file from the path `.cursor/rules`, find the XML file in the path `generator/src/main/resources`.
-- The project is based on Java 24.
+- Adding new cursor rule: Edit XML in system-prompts-generator/src/main/resources/
+- Updating website: Modify content in site-generator/content/
+- Running examples: Each example has its own README-DEV.md
+
+## File Editing Guidelines
+- Don't edit .cursor/rules/ directly - edit XML sources in system-prompts-generator/src/main/resources/
+- Always run tests before promoting changes
 
 ## Commit Messages and Pull Requests
 
@@ -49,3 +201,7 @@ If the tests passes, you could promote the changes to `.cursor/rules`:
   - **Why?**
   - **Breaking changes?**
 - Comments should be complete sentences and end with a period.
+
+## References
+
+- https://agents.md/

README.md

@@ -20,7 +20,7 @@ The repository was designed to offer support for Cursor, but other tools have ev
 
 A system prompt is a set of instructions given to an AI model that defines how it should behave, what role it should take on, and what guidelines it should follow when responding to users. Think of it as the "operating manual" that shapes the AI's personality, capabilities, and boundaries.
 
-![](./documentation/prompts.png)
+![](./documentation/images/prompts.png)
 
 ### Types of System prompts
 
@@ -38,25 +38,25 @@ The repository provides System prompts that can behave interactively or non-inte
 
 Adding AI tools to the Java development workflow can increase the possibilities of implementing software specifications on time and with quality.
 
-![](./documentation/workflow.png)
+![](./documentation/images/workflow.png)
 
 **Note:** Remember that if you use models and ask questions about recent topics like *Java 25*, it is probable that models will not provide accurate answers.
 
 ## Getting started
 
-New to this repository? Start with our [comprehensive guide](./GETTING-STARTED.md) for a quick introduction to setting up and using the Cursor rules.
+New to this repository? Start with our [comprehensive guide](./documentation/GETTING-STARTED.md) for a quick introduction to setting up and using the Cursor rules.
 
 ## How to use a System prompt in your development?
 
-Learn [how to integrate System prompts](./HOW-TO-USE.md) into your development workflow and maximize their effectiveness in your daily coding tasks.
+Learn [how to integrate System prompts](./documentation/HOW-TO-USE.md) into your development workflow and maximize their effectiveness in your daily coding tasks.
 
 ## How many System prompts include this repository?
 
 Explore the [complete catalog of available System prompts](./CURSOR-RULES-JAVA.md) to discover the full range of capabilities and find the perfect rules for your specific use cases.
 
 ## Constraints, Output format & Safety guards
 
-The cursor rules in this repository follow [The Three-Node Quality Framework for AI Prompts](./docs/articles/prompt-quality-framework.md), which ensures both comprehensive responses and safe execution. This framework consists of three distinct pillars: **constraints**, **output-format** and **safeguards**. Each node operates at different phases of the AI interaction timeline, creating a defense-in-depth strategy.
+The cursor rules in this repository follow [The Three-Node Quality Framework for AI Prompts](https://jabrena.github.io/cursor-rules-java/blog/2025/prompt-quality-framework.html), which ensures both comprehensive responses and safe execution. This framework consists of three distinct pillars: **constraints**, **output-format** and **safeguards**. Each node operates at different phases of the AI interaction timeline, creating a defense-in-depth strategy.
 
 The **constraints** act as gate-keeping mechanisms that define hard requirements and blocking conditions before any work begins - essentially asking "Can I start?" The **output-format** provides prescriptive guidance during execution, ensuring comprehensive coverage and organized responses by defining "What should I deliver?" Finally, **safeguards** implement protective measures throughout and after execution, continuously asking "Did it work safely?" This temporal flow from pre-execution validation to structured execution to continuous monitoring ensures quality at every stage.
 

GETTING-STARTED.md documentation/GETTING-STARTED.mdGETTING-STARTED.md renamed to documentation/GETTING-STARTED.md

@@ -8,7 +8,7 @@ If you are interested in getting the benefits of these cursor rules for Java, yo
 
 This view has a big green button with the text: `<> Code`. If you click on it, you will see the tab `Local` and you will see the link for: `Download Zip`.
 
-![](./documentation/getting-started-github.png)
+![](./images/getting-started-github.png)
 
 Once you have downloaded it, go to the `Downloads` folder in your system and you should see the zip file: `cursor-rules-java-main.zip`. Unzip it and copy the folder `.cursor` into the Java repository where you want to use these Cursor rules.
 
@@ -40,7 +40,7 @@ jbang --fresh setup@jabrena init --cursor https://github.com/jabrena/cursor-rule
 
 Once you have installed the cursor rules in the path `.cursor/rules`, type the following prompt in the cursor chat:
 
-![](./documentation/getting-started-prompt.png)
+![](./images/getting-started-prompt.png)
 
 ```bash
 Create a document with all cursor rules for Java using the cursor rule @100-java-cursor-rules-list

HOW-TO-USE.md documentation/HOW-TO-USE.mdHOW-TO-USE.md renamed to documentation/HOW-TO-USE.md

@@ -1,11 +1,11 @@
 # How to use a system prompt in your development
 
 
-![](./documentation/prompts.png)
+![](./images/prompts.png)
 
 Using a system prompt in your development is straightforward. If you are using a modern IDE that includes AI features, such as Cursor, open the chat:
 
-![](./documentation/cursor-chat1.png)
+![](./images/cursor-chat1.png)
 
 and type your own **user prompt**, such as the following example:
 
@@ -17,24 +17,24 @@ and drag and drop the system prompt that you need into the chat along with the p
 
 The result should be:
 
-![](./documentation/cursor-chat2.png)
+![](./images/cursor-chat2.png)
 
 ---
 
 Another way to interact with models has recently emerged: using CLI tools. The approach is exactly the same.
 
 Starting from a clean session in [Cursor CLI](https://cursor.com/cli):
 
-![](./documentation/cursor-cli1.png)
+![](./images/cursor-cli1.png)
 
 Type your user prompt in the text area:
 
 ```
 Improve the pom.xml using the cursor rule @112-java-maven-plugins
 ```
 
-![](./documentation/cursor-cli2.png)
+![](./images/cursor-cli2.png)
 
 and finally select the file to which you want to apply the process:
 
-![](./documentation/cursor-cli3.png)
+![](./images/cursor-cli3.png)