From af2d0ac96f512296f720b053a35b8b56337f504d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Antonio=20Bre=C3=B1a=20Moral?= Date: Sat, 6 Jun 2026 12:14:01 +0200 Subject: [PATCH 1/4] docs(readme): add ClaudSkills author link --- README.md | 1 + README_CN.md | 1 + README_ES.md | 1 + 3 files changed, 3 insertions(+) diff --git a/README.md b/README.md index 78735248..aa596129 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/README_CN.md b/README_CN.md index 120f175f..f2af2219 100644 --- a/README_CN.md +++ b/README_CN.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 diff --git a/README_ES.md b/README_ES.md index 060a9b0b..ddc2fa25 100644 --- a/README_ES.md +++ b/README_ES.md @@ -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 From 6924d9c2f7bdbd1e801b427896e281dbb3fc19e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Antonio=20Bre=C3=B1a=20Moral?= Date: Sat, 6 Jun 2026 12:17:44 +0200 Subject: [PATCH 2/4] docs(i18n): rename Chinese files to ZH suffix --- AGENTS.md | 6 +++--- CHANGELOG.md | 2 +- README.md | 2 +- README_ES.md | 2 +- README_CN.md => README_ZH.md | 10 +++++----- ...ARTED-AGENTS_CN.md => GETTING-STARTED-AGENTS_ZH.md} | 2 +- ...PIPELINES_CN.md => GETTING-STARTED-PIPELINES_ZH.md} | 0 ...ARTED-SKILLS_CN.md => GETTING-STARTED-SKILLS_ZH.md} | 0 site-generator/content/blog/2026/06/release-0.15.0.md | 2 +- 9 files changed, 13 insertions(+), 13 deletions(-) rename README_CN.md => README_ZH.md (97%) rename documentation/guides/{GETTING-STARTED-AGENTS_CN.md => GETTING-STARTED-AGENTS_ZH.md} (98%) rename documentation/guides/{GETTING-STARTED-PIPELINES_CN.md => GETTING-STARTED-PIPELINES_ZH.md} (100%) rename documentation/guides/{GETTING-STARTED-SKILLS_CN.md => GETTING-STARTED-SKILLS_ZH.md} (100%) diff --git a/AGENTS.md b/AGENTS.md index 96650672..97db83d5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -50,8 +50,8 @@ This project uses **OpenSpec** for structured change management and planning: - `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 +- `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 @@ -137,6 +137,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 `, 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 `, 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_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 diff --git a/CHANGELOG.md b/CHANGELOG.md index eab15c66..6c6cc82a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/README.md b/README.md index aa596129..07e39e99 100644 --- a/README.md +++ b/README.md @@ -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/ > diff --git a/README_ES.md b/README_ES.md index ddc2fa25..71258af1 100644 --- a/README_ES.md +++ b/README_ES.md @@ -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/ > diff --git a/README_CN.md b/README_ZH.md similarity index 97% rename from README_CN.md rename to README_ZH.md index f2af2219..9a853df4 100644 --- a/README_CN.md +++ b/README_ZH.md @@ -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)。 ## 局限性 diff --git a/documentation/guides/GETTING-STARTED-AGENTS_CN.md b/documentation/guides/GETTING-STARTED-AGENTS_ZH.md similarity index 98% rename from documentation/guides/GETTING-STARTED-AGENTS_CN.md rename to documentation/guides/GETTING-STARTED-AGENTS_ZH.md index c4fbafc9..67e28dfc 100644 --- a/documentation/guides/GETTING-STARTED-AGENTS_CN.md +++ b/documentation/guides/GETTING-STARTED-AGENTS_ZH.md @@ -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？ diff --git a/documentation/guides/GETTING-STARTED-PIPELINES_CN.md b/documentation/guides/GETTING-STARTED-PIPELINES_ZH.md similarity index 100% rename from documentation/guides/GETTING-STARTED-PIPELINES_CN.md rename to documentation/guides/GETTING-STARTED-PIPELINES_ZH.md diff --git a/documentation/guides/GETTING-STARTED-SKILLS_CN.md b/documentation/guides/GETTING-STARTED-SKILLS_ZH.md similarity index 100% rename from documentation/guides/GETTING-STARTED-SKILLS_CN.md rename to documentation/guides/GETTING-STARTED-SKILLS_ZH.md diff --git a/site-generator/content/blog/2026/06/release-0.15.0.md b/site-generator/content/blog/2026/06/release-0.15.0.md index 7188f909..2b12c80e 100644 --- a/site-generator/content/blog/2026/06/release-0.15.0.md +++ b/site-generator/content/blog/2026/06/release-0.15.0.md @@ -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 From 7809bd2e737e1cd63778c0e34b5d5a6511a1ae20 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Antonio=20Bre=C3=B1a=20Moral?= Date: Sat, 6 Jun 2026 12:21:16 +0200 Subject: [PATCH 3/4] docs(contributing): require AI coauthor attribution Regenerate the published website after updating site content. Co-authored-by: Codex --- AGENTS.md | 10 ++++++++++ docs/blog/2026/04/release-0.14.0.html | 4 ++-- docs/blog/2026/06/release-0.15.0.html | 2 +- docs/feed.xml | 2 +- 4 files changed, 14 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 97db83d5..474ddd46 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -117,6 +117,16 @@ openspec archive # 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: +``` + +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**). diff --git a/docs/blog/2026/04/release-0.14.0.html b/docs/blog/2026/04/release-0.14.0.html index 21c28da2..ff7c6b0b 100644 --- a/docs/blog/2026/04/release-0.14.0.html +++ b/docs/blog/2026/04/release-0.14.0.html @@ -199,8 +199,8 @@

Skill inventory

npx skills add jabrena/cursor-rules-java --all --agent claude-code

Once you have the skills installed, you can install the Agents with:

-
@003-agents-installation Install Agents in Cursor
-@003-agents-installation Install Agents in Claude
+
@005-agents-installation Install Agents in Cursor
+@005-agents-installation Install Agents in Claude
 

 
Evolution of this project in Vercel's Skills registry

 
The ecosystem is large, so you will need your own criteria beyond whether this project fits your preferences.

diff --git a/docs/blog/2026/06/release-0.15.0.html b/docs/blog/2026/06/release-0.15.0.html
index a7f74d2e..e50a77ba 100644
--- a/docs/blog/2026/06/release-0.15.0.html
+++ b/docs/blog/2026/06/release-0.15.0.html
@@ -157,7 +157,7 @@ 
Better documentation

 
The project now provides documentation in three languages:

 
 
Evolution of this project in Vercel's Skills registry

diff --git a/docs/feed.xml b/docs/feed.xml
index 38de8660..e04b454c 100644
--- a/docs/feed.xml
+++ b/docs/feed.xml
@@ -2,7 +2,7 @@
 
   https://jabrena.github.io/cursor-rules-java/
   Codestin Search App
-  2026-05-31T17:44:31+0200
+  2026-06-06T12:20:37+0200
   
   
   

From f30816424cfd71de945570dde0c2ab1881c78d62 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Juan=20Antonio=20Bre=C3=B1a=20Moral?=
 
Date: Sat, 6 Jun 2026 12:23:37 +0200
Subject: [PATCH 4/4] docs(contributing): enforce website source
 synchronization

Require site sources and generated docs to ship together, and document how to trace pre-existing generated-output drift.

Co-authored-by: Codex 
---
 AGENTS.md | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 474ddd46..ff206c23 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -48,8 +48,8 @@ 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)
+- `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
 
@@ -96,6 +96,14 @@ openspec archive        # 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
@@ -147,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 `, 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_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.
+- ✅ **Always do:** Edit XML in `skills-generator/src/main/resources/` (`skill-references/`, `skills/`) to change rules and skills, validate edited XML with `xmllint --noout `, 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