jabrena · jabrena · Jun 6, 2026 · Jun 6, 2026 · Jun 6, 2026 · Jun 6, 2026
@@ -48,10 +48,10 @@ This project uses **OpenSpec** for structured change management and planning:
 - `documentation/guides/` – Contributor and user guides, including getting-started docs, inventories, and third-party references (WRITE)
 - `documentation/openspec/` – OpenSpec change management (proposals, specs, tasks) (WRITE)
 - `documentation/adr/` – Architecture Decision Records (WRITE)
-- `site-generator/content/` – Blog posts, courses, documentation (WRITE here to update website)
-- `docs/` – Generated static website for GitHub Pages (READ only)
-- `README.md` – Default project README (WRITE); keep `README_ES.md` and `README_CN.md` in sync when it changes
-- `documentation/guides/GETTING-STARTED-*.md` – Getting-started documentation; English files are the master source, so keep matching `_ES.md` and `_CN.md` versions in sync when localized counterparts exist
+- `site-generator/content/` – Blog posts, courses, documentation (WRITE here to update website; regenerate `docs/` in the same change)
+- `docs/` – Generated static website for GitHub Pages (READ only; update only through the `site-update` Maven profile)
+- `README.md` – Default project README (WRITE); keep `README_ES.md` and `README_ZH.md` in sync when it changes
+- `documentation/guides/GETTING-STARTED-*.md` – Getting-started documentation; English files are the master source, so keep matching `_ES.md` and `_ZH.md` versions in sync when localized counterparts exist
 
 ## Commands
 
@@ -96,6 +96,14 @@ openspec archive <change-name>       # Archive a completed change
 
 ```
 
+## Website generation workflow
+
+1. Edit website sources under `site-generator/content/`, `site-generator/templates/`, or `site-generator/assets/`; never edit `docs/` directly.
+2. Run `./mvnw clean generate-resources -pl site-generator -P site-update` in the same change whenever website sources change.
+3. Review every generated `docs/` diff and verify it corresponds to a current source, template, or asset change.
+4. If regeneration reveals output drift from a source change committed earlier, trace it with `git log` or `git blame`, retain the generated correction, and explain that provenance in the commit or pull request.
+5. Commit the website source and generated `docs/` output together so GitHub Pages never lags behind its source.
+
 ## Git workflow
 
 - **Conventional Commits**: Use conventional commit format for all commit messages
@@ -117,6 +125,16 @@ openspec archive <change-name>       # Archive a completed change
 
 The [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) spec allows other types if your team agrees. **This repository’s commit-msg hook** accepts the types in the table above and requires a **scope** (see [`.pre-commit-config.yaml`](.pre-commit-config.yaml)).
 
+### AI-assisted commits
+
+When Cursor, Claude, Codex, or another AI tool authors or materially contributes to a commit, include a `Co-authored-by` trailer using the tool's documented Git identity:
+
+```text
+Co-authored-by: <tool-name> <tool-email>
+```
+
+Place the trailer after a blank line at the end of the commit message. Do not add an AI co-author when the tool only provided incidental assistance and did not contribute to the committed change.
+
 ### Pre-commit hooks (recommended)
 
 This repository includes [pre-commit](https://pre-commit.com/) configuration at [`.pre-commit-config.yaml`](.pre-commit-config.yaml): YAML checks and a **commit-msg** hook that enforces the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) rules above (including a required **scope**).
@@ -137,6 +155,6 @@ pre-commit run conventional-pre-commit --hook-stage commit-msg --commit-msg-file
 
 ## Boundaries
 
-- ✅ **Always do:** Edit XML in `skills-generator/src/main/resources/` (`skill-references/`, `skills/`) to change rules and skills, validate edited XML with `xmllint --noout <path-to-edited-file.xml>`, and run `./mvnw clean verify` before promoting changes. For local skill regeneration, use `./mvnw clean install -pl skills-generator` and test the generated output from `.agents/skills`; do not refresh `skills/` unless preparing an intentional release. For release skill changes, run `./mvnw clean install -pl skills-generator -P release`, then validate `skills/` with `npx skill-check@latest skills --no-security-scan --format github` and `skill-scanner scan-all ./skills --recursive --use-behavioral --policy strict --fail-on-severity high` when the scanner is available. When editing XML, follow PML Schema: [https://jabrena.github.io/pml/schemas/0.7.0/pml.xsd](https://jabrena.github.io/pml/schemas/0.7.0/pml.xsd). For complex changes, create OpenSpec proposals first. When you change `README.md`, update the translated READMEs (`README_ES.md`, `README_CN.md`) in the same change. When you change an English `documentation/guides/GETTING-STARTED-*.md` file, update the matching `_ES.md` and `_CN.md` files in the same change when they exist.
+- ✅ **Always do:** Edit XML in `skills-generator/src/main/resources/` (`skill-references/`, `skills/`) to change rules and skills, validate edited XML with `xmllint --noout <path-to-edited-file.xml>`, and run `./mvnw clean verify` before promoting changes. For local skill regeneration, use `./mvnw clean install -pl skills-generator` and test the generated output from `.agents/skills`; do not refresh `skills/` unless preparing an intentional release. For release skill changes, run `./mvnw clean install -pl skills-generator -P release`, then validate `skills/` with `npx skill-check@latest skills --no-security-scan --format github` and `skill-scanner scan-all ./skills --recursive --use-behavioral --policy strict --fail-on-severity high` when the scanner is available. When editing XML, follow PML Schema: [https://jabrena.github.io/pml/schemas/0.7.0/pml.xsd](https://jabrena.github.io/pml/schemas/0.7.0/pml.xsd). For complex changes, create OpenSpec proposals first. When website sources change, regenerate and review `docs/`, then commit source and output together. When you change `README.md`, update the translated READMEs (`README_ES.md`, `README_ZH.md`) in the same change. When you change an English `documentation/guides/GETTING-STARTED-*.md` file, update the matching `_ES.md` and `_ZH.md` files in the same change when they exist.
 - ⚠️ **Ask first:** Adding new XML rule files, modifying the XSLT stylesheet, changing site templates, architectural changes (use OpenSpec for planning)
 - 🚫 **Never do:** Edit `.cursor/rules/` or `docs/` directly, commit secrets, skip tests before promoting, bypass OpenSpec for major changes
@@ -36,7 +36,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Documentation:**
   - Improved project usage guidance in `README.md` and skills documentation (#732, #733)
-  - Added localized README translations (`README_ES.md`, `README_CN.md`) with a language switcher in `README.md`, refreshed the Goal statement, and documented sync requirements in `AGENTS.md`
+  - Added localized README translations (`README_ES.md`, `README_ZH.md`) with a language switcher in `README.md`, refreshed the Goal statement, and documented sync requirements in `AGENTS.md`
   - Third-party tools and links documented in `documentation/THIRD-PARTIES.md` (#734)
 
 ## [0.14.0] 2026-04-12

@@ -6,7 +6,7 @@
 
 [![CI Builds](https://github.com/jabrena/cursor-rules-java/actions/workflows/maven.yaml/badge.svg)](https://github.com/jabrena/cursor-rules-java/actions/workflows/maven.yaml)
 
-> **Languages:** [Español](./README_ES.md) · [中文](./README_CN.md)
+> **Languages:** [Español](./README_ES.md) · [中文](./README_ZH.md)
 >
 > **Website:** https://jabrena.github.io/cursor-rules-java/
 >
@@ -159,6 +159,7 @@ Java uses JEPs (JDK Enhancement Proposals) to describe new language and platform
 - [https://openspec.dev/](https://openspec.dev/)
 - [https://skills.sh/jabrena/cursor-rules-java](https://skills.sh/jabrena/cursor-rules-java)
 - [https://tessl.io/registry/skills/github/jabrena/cursor-rules-java](https://tessl.io/registry/skills/github/jabrena/cursor-rules-java)
+- https://claudskills.com/author/jabrena/
 - https://agent-skills.cc/zh/skills/jabrena-cursor-rules-java
 - https://shyft.ai/skills/cursor-rules-java
 - https://lobehub.com/skills?q=cursor-rules-java

@@ -6,7 +6,7 @@
 
 [![CI Builds](https://github.com/jabrena/cursor-rules-java/actions/workflows/maven.yaml/badge.svg)](https://github.com/jabrena/cursor-rules-java/actions/workflows/maven.yaml)
 
-> **Idiomas:** [English](./README.md) · [中文](./README_CN.md)
+> **Idiomas:** [English](./README.md) · [中文](./README_ZH.md)
 >
 > **Website:** https://jabrena.github.io/cursor-rules-java/
 >
@@ -159,6 +159,7 @@ Java usa JEPs (JDK Enhancement Proposals) para describir nuevas características
 - [https://openspec.dev/](https://openspec.dev/)
 - [https://skills.sh/jabrena/cursor-rules-java](https://skills.sh/jabrena/cursor-rules-java)
 - [https://tessl.io/registry/skills/github/jabrena/cursor-rules-java](https://tessl.io/registry/skills/github/jabrena/cursor-rules-java)
+- https://claudskills.com/author/jabrena/
 - https://agent-skills.cc/zh/skills/jabrena-cursor-rules-java
 - https://shyft.ai/skills/cursor-rules-java
 - https://lobehub.com/skills?q=cursor-rules-java

@@ -30,8 +30,8 @@
 |               | 分析 / 设计 | 实现 | 运维 |
 | ------------- | ----------------- | -------------- | --------- |
 | Commands      | [`/update-issue-description`](./.cursor/commands/update-issue-description.md) | [`/create-feature-branch`](./.cursor/commands/create-feature-branch.md) · [`/implement`](./.cursor/commands/implement.md) | [`/verify`](./.cursor/commands/verify.md) · [`/kill-port`](./.cursor/commands/kill-port.md) |
-| [Agents](./documentation/guides/GETTING-STARTED-AGENTS_CN.md)        | `@robot-business-analyst` | `@robot-coordinator` · `@robot-java-coder` · `@robot-spring-boot-coder` · `@robot-quarkus-coder` · `@robot-micronaut-coder` |  |
-| [Skills](./documentation/guides/GETTING-STARTED-SKILLS_CN.md)        | [014-agile-user-story](https://www.skills.sh/jabrena/cursor-rules-java/014-agile-user-story) · [030-architecture-adr-general](https://www.skills.sh/jabrena/cursor-rules-java/030-architecture-adr-general) · [031-architecture-adr-functional-requirements](https://www.skills.sh/jabrena/cursor-rules-java/031-architecture-adr-functional-requirements) · [033-architecture-diagrams](https://www.skills.sh/jabrena/cursor-rules-java/033-architecture-diagrams) · [041-planning-plan-mode](https://www.skills.sh/jabrena/cursor-rules-java/041-planning-plan-mode) | [110-java-maven-best-practices](https://www.skills.sh/jabrena/cursor-rules-java/110-java-maven-best-practices) · [121-java-object-oriented-design](https://www.skills.sh/jabrena/cursor-rules-java/121-java-object-oriented-design) · [124-java-secure-coding](https://www.skills.sh/jabrena/cursor-rules-java/124-java-secure-coding) · [111-java-maven-dependencies](https://www.skills.sh/jabrena/cursor-rules-java/111-java-maven-dependencies) · [143-java-functional-exception-handling](https://www.skills.sh/jabrena/cursor-rules-java/143-java-functional-exception-handling) | [151-java-performance-jmeter](https://www.skills.sh/jabrena/cursor-rules-java/151-java-performance-jmeter) · [162-java-profiling-analyze](https://www.skills.sh/jabrena/cursor-rules-java/162-java-profiling-analyze) · [161-java-profiling-detect](https://www.skills.sh/jabrena/cursor-rules-java/161-java-profiling-detect) · [163-java-profiling-refactor](https://www.skills.sh/jabrena/cursor-rules-java/163-java-profiling-refactor) · [164-java-profiling-verify](https://www.skills.sh/jabrena/cursor-rules-java/164-java-profiling-verify) |
+| [Agents](./documentation/guides/GETTING-STARTED-AGENTS_ZH.md)        | `@robot-business-analyst` | `@robot-coordinator` · `@robot-java-coder` · `@robot-spring-boot-coder` · `@robot-quarkus-coder` · `@robot-micronaut-coder` |  |
+| [Skills](./documentation/guides/GETTING-STARTED-SKILLS_ZH.md)        | [014-agile-user-story](https://www.skills.sh/jabrena/cursor-rules-java/014-agile-user-story) · [030-architecture-adr-general](https://www.skills.sh/jabrena/cursor-rules-java/030-architecture-adr-general) · [031-architecture-adr-functional-requirements](https://www.skills.sh/jabrena/cursor-rules-java/031-architecture-adr-functional-requirements) · [033-architecture-diagrams](https://www.skills.sh/jabrena/cursor-rules-java/033-architecture-diagrams) · [041-planning-plan-mode](https://www.skills.sh/jabrena/cursor-rules-java/041-planning-plan-mode) | [110-java-maven-best-practices](https://www.skills.sh/jabrena/cursor-rules-java/110-java-maven-best-practices) · [121-java-object-oriented-design](https://www.skills.sh/jabrena/cursor-rules-java/121-java-object-oriented-design) · [124-java-secure-coding](https://www.skills.sh/jabrena/cursor-rules-java/124-java-secure-coding) · [111-java-maven-dependencies](https://www.skills.sh/jabrena/cursor-rules-java/111-java-maven-dependencies) · [143-java-functional-exception-handling](https://www.skills.sh/jabrena/cursor-rules-java/143-java-functional-exception-handling) | [151-java-performance-jmeter](https://www.skills.sh/jabrena/cursor-rules-java/151-java-performance-jmeter) · [162-java-profiling-analyze](https://www.skills.sh/jabrena/cursor-rules-java/162-java-profiling-analyze) · [161-java-profiling-detect](https://www.skills.sh/jabrena/cursor-rules-java/161-java-profiling-detect) · [163-java-profiling-refactor](https://www.skills.sh/jabrena/cursor-rules-java/163-java-profiling-refactor) · [164-java-profiling-verify](https://www.skills.sh/jabrena/cursor-rules-java/164-java-profiling-verify) |
 | [MCP Servers](./documentation/guides/THIRD-PARTIES.md)   | [JDBC](https://github.com/quarkiverse/quarkus-mcp-servers/blob/main/jdbc/README.md) | [JavaDocs](https://www.javadocs.dev/mcp) · [Serena](https://oraios.github.io/serena/01-about/000_intro.html) | [Graphana](https://grafana.com/docs/grafana/latest/developer-resources/mcp/) |
 
 ## 交付物
@@ -41,8 +41,8 @@
 | 清单     | 安装                                                                                    | 快速入门                                                                           |
 | --------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
 | 1. [Commands](./documentation/guides/INVENTORY-COMMANDS-JAVA.md) | `@004-commands-installation` 在项目中安装 Commands | [`Commands`](./documentation/guides/COMMANDS.md) |
-| 2. [Agents](./documentation/guides/INVENTORY-AGENTS-JAVA.md) | `@005-agents-installation` 在 Cursor/Claude 中安装 Agents | [`Agents`](./documentation/guides/GETTING-STARTED-AGENTS_CN.md)     |
-| 3. [Skills](./documentation/guides/INVENTORY-SKILLS-JAVA.md) | `npx skills add jabrena/cursor-rules-java --all --agent cursor` | [`Skills`](./documentation/guides/GETTING-STARTED-SKILLS_CN.md)     |
+| 2. [Agents](./documentation/guides/INVENTORY-AGENTS-JAVA.md) | `@005-agents-installation` 在 Cursor/Claude 中安装 Agents | [`Agents`](./documentation/guides/GETTING-STARTED-AGENTS_ZH.md)     |
+| 3. [Skills](./documentation/guides/INVENTORY-SKILLS-JAVA.md) | `npx skills add jabrena/cursor-rules-java --all --agent cursor` | [`Skills`](./documentation/guides/GETTING-STARTED-SKILLS_ZH.md)     |
 
 **⚠️ 注意：** 若你仍在使用本项目的 System prompts/rules，请阅读[相关文章](https://jabrena.github.io/cursor-rules-java/blog/2026/04/release-0.14.0.html)。当前的 `System prompts/rules` 将在下一版本（v0.16.0）中移除。
 
@@ -72,7 +72,7 @@
 
 ![](./documentation/images/workflow-pipelines.png)
 
-更多信息见[此处](./documentation/guides/GETTING-STARTED-PIPELINES_CN.md)。
+更多信息见[此处](./documentation/guides/GETTING-STARTED-PIPELINES_ZH.md)。
 
 ## 局限性
 
@@ -159,6 +159,7 @@ Java 使用 JEP（JDK Enhancement Proposals）描述新的语言与平台特性
 - [https://openspec.dev/](https://openspec.dev/)
 - [https://skills.sh/jabrena/cursor-rules-java](https://skills.sh/jabrena/cursor-rules-java)
 - [https://tessl.io/registry/skills/github/jabrena/cursor-rules-java](https://tessl.io/registry/skills/github/jabrena/cursor-rules-java)
+- https://claudskills.com/author/jabrena/
 - https://agent-skills.cc/zh/skills/jabrena-cursor-rules-java
 - https://shyft.ai/skills/cursor-rules-java
 - https://lobehub.com/skills?q=cursor-rules-java

@@ -199,8 +199,8 @@ <h3>Skill inventory</h3>
 npx skills add jabrena/cursor-rules-java --all --agent claude-code
 </code></pre>
 <p>Once you have the skills installed, you can install the <code>Agents</code> with:</p>
-<pre><code>@003-agents-installation Install Agents in Cursor
-@003-agents-installation Install Agents in Claude
+<pre><code>@005-agents-installation Install Agents in Cursor
+@005-agents-installation Install Agents in Claude
 </code></pre>
 <h2>Evolution of this project in Vercel's Skills registry</h2>
 <p>The ecosystem is large, so you will need your own criteria beyond whether this project fits your preferences.</p>

@@ -157,7 +157,7 @@ <h3>Better documentation</h3>
 <p>The project now provides documentation in three languages:</p>
 <ul>
 <li><a href="https://github.com/jabrena/cursor-rules-java/blob/main/README.md"><code>English</code></a></li>
-<li><a href="https://github.com/jabrena/cursor-rules-java/blob/main/README_CN.md"><code>Chinese</code></a></li>
+<li><a href="https://github.com/jabrena/cursor-rules-java/blob/main/README_ZH.md"><code>Chinese</code></a></li>
 <li><a href="https://github.com/jabrena/cursor-rules-java/blob/main/README_ES.md"><code>Spanish</code></a></li>
 </ul>
 <h2>Evolution of this project in Vercel's Skills registry</h2>

@@ -2,7 +2,7 @@
 <feed xmlns='http://www.w3.org/2005/Atom' xml:lang='en'>
   <id>https://jabrena.github.io/cursor-rules-java/</id>
   <title>Skills & Agents for Java</title>
-  <updated>2026-05-31T17:44:31+0200</updated>
+  <updated>2026-06-06T12:20:37+0200</updated>
   <link rel="alternate" type="text/html" href="https://jabrena.github.io/cursor-rules-java/" />
   <link rel='self' type='application/atom+xml' href='https://jabrena.github.io/cursor-rules-java//feed.xml' />
   <entry>

@@ -18,7 +18,7 @@
 
 ### 对 Skills 和 System prompts 的依赖
 
-这些智能体假设你可以附加 **Skills**（见 [Java Skills 快速入门](GETTING-STARTED-SKILLS_CN.md)）和/或 **Cursor rules**（见 [Getting started for System prompts for Java](GETTING-STARTED-SYSTEM-PROMPTS.md)），这样聊天中的 `@...` 引用才能解析。实现智能体会明确命名具体的 skill 前缀（例如 `@322-frameworks-spring-boot-testing-integration-tests`）。
+这些智能体假设你可以附加 **Skills**（见 [Java Skills 快速入门](GETTING-STARTED-SKILLS_ZH.md)）和/或 **Cursor rules**（见 [Getting started for System prompts for Java](GETTING-STARTED-SYSTEM-PROMPTS.md)），这样聊天中的 `@...` 引用才能解析。实现智能体会明确命名具体的 skill 前缀（例如 `@322-frameworks-spring-boot-testing-integration-tests`）。
 
 ## 如何安装 Agents？
 

@@ -86,7 +86,7 @@ https://github.com/Endava/cats
 The project now provides documentation in three languages:
 
 - [`English`](https://github.com/jabrena/cursor-rules-java/blob/main/README.md)
-- [`Chinese`](https://github.com/jabrena/cursor-rules-java/blob/main/README_CN.md)
+- [`Chinese`](https://github.com/jabrena/cursor-rules-java/blob/main/README_ZH.md)
 - [`Spanish`](https://github.com/jabrena/cursor-rules-java/blob/main/README_ES.md)
 
 ## Evolution of this project in Vercel's Skills registry