From 6039f21320c1123a0ddf7e9c016e97f65bbbd802 Mon Sep 17 00:00:00 2001
From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com>
Date: Mon, 20 Jul 2026 15:55:10 +0800
Subject: [PATCH] docs(agents): clarify agent guide and share it across AI
 assistants (#1035) (#1036)

* ci: disable header-max-length commit rule



* docs(agents): clarify agent guide and share it across AI assistants

- Symlink CLAUDE.md and GEMINI.md to AGENTS.md so Claude Code, Copilot
  and Gemini read the same guidance
- Use the full conventional-commit format with scope in the guide
- Clarify Vue SFC block order and the feature-flag development steps
- Bump the documented Node.js requirement to v24



---------


(cherry picked from commit 3d39626b9317bfeb500bb2c315ca00ea6404e270)

Signed-off-by: Andy Lee <andy.lee@suse.com>
Co-authored-by: Andy Lee <andy.lee@suse.com>
---
 AGENTS.md                                     | 36 +++++++++----------
 CLAUDE.md                                     |  1 +
 GEMINI.md                                     |  1 +
 README.md                                     |  2 +-
 commitlint.config.js                          |  1 +
 docs/agents.md/agents/boundaries.md           |  4 +--
 docs/agents.md/contributors/1_contributors.md | 32 +++++++++--------
 docs/agents.md/template_agents.md             |  2 +-
 8 files changed, 41 insertions(+), 38 deletions(-)
 create mode 120000 CLAUDE.md
 create mode 120000 GEMINI.md

diff --git a/AGENTS.md b/AGENTS.md
index c1f3feea..8195284e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -28,9 +28,7 @@ You are an expert Senior Software Engineer specializing in Vue.js and TypeScript
   - Run `yarn lint:fix` before commits.
     - Use conventional commit format: 
     ```
-    <type>:
-
-    <description>
+    <type>(<scope>): <description>
     ```
   - Follow existing naming conventions (PascalCase for components, camelCase for functions).
   - After changing a Vue, JS, or TS file, make sure it's automatically formatted with ESLint.
@@ -130,8 +128,8 @@ To get started, follow the `Development Setup` section.
   - `Vue.js`:
     - Composition API components are preferred over Options API.
     - Large pages with lots of code and styles should be avoided by breaking the page up into smaller Vue components.
-    - Place source tag above template above style.
-    - style tag should contain `lang='scss' scoped`.
+    - Order the Single File Component blocks as `<script>`, then `<template>`, then `<style>`.
+    - The `<style>` tag should include `lang="scss" scoped`.
   - `Linting`: Follow the ESLint configuration in the root.
 
 - **File Structure:**
@@ -163,24 +161,26 @@ To get started, follow the `Development Setup` section.
 
 ## Harvester UI Extension Development Guide
 
-1. Backward Compatibility
-The Harvester UI Extension supports earlier cluster versions (e.g., UI Ext v1.8.0 works with clusters v1.7.0 and v1.6.0). It uses Feature Flags defined in pkg/config/feature-flags to ensure the UI matches the cluster's specific version.
+### Backward Compatibility
+
+The Harvester UI Extension supports earlier cluster versions (e.g., UI Ext v1.8.0 works with clusters v1.7.0 and v1.6.0). It uses Feature Flags defined in `pkg/harvester/config/` to ensure the UI matches the cluster's specific version.
+
+### Implementation Steps for New Features
 
-2. Implementation Steps for New Features
 To add a feature in a new release, follow these steps:
 
-    Register: Add a unique [Feature Name] to the corresponding release array in the configuration.
+1. **Register**: Add a unique `[Feature Name]` to the corresponding release array in the configuration.
+2. **Check**: Use the following getter to verify if the feature is enabled for the current version:
 
-    Check: Use the following getter to verify if the feature is enabled for the current version:
+   ```js
+   computed: {
+     newFeatureEnabled() {
+       return this.$store.getters['harvester-common/getFeatureEnabled']('[Feature Name]');
+     },
+   },
+   ```
 
-    ```
-    computed: {
-      newFeatureEnabled() {
-        return this.$store.getters['harvester-common/getFeatureEnabled']('[Feature Name]');
-      },
-    },
-    ```
-    Render: Use the result of the check to conditionally render the UI components.
+3. **Render**: Use the result of the check to conditionally render the UI components.
 
 
 ## E2E Tests (Cypress)
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 00000000..55bf822d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+./AGENTS.md
\ No newline at end of file
diff --git a/GEMINI.md b/GEMINI.md
new file mode 120000
index 00000000..55bf822d
--- /dev/null
+++ b/GEMINI.md
@@ -0,0 +1 @@
+./AGENTS.md
\ No newline at end of file
diff --git a/README.md b/README.md
index 38a682df..d0f2c87c 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,7 @@ For Harvester UI extension installation instructions, please refer to the page *
 
 ## Development Setup
 
-Ensure **Node.js v20 or later** is installed for development and debugging.
+Ensure **Node.js v24 or later** is installed for development and debugging.
 
 ### Standalone Mode
 
diff --git a/commitlint.config.js b/commitlint.config.js
index 4960a2d9..5847239a 100644
--- a/commitlint.config.js
+++ b/commitlint.config.js
@@ -32,6 +32,7 @@ module.exports = {
     'subject-empty':          [2, 'never'],
     'subject-full-stop':      [2, 'never', '.'],
     'subject-max-length':     [0, 'never'],
+    'header-max-length':      [0, 'always', 100],
     'body-leading-blank':     [2, 'always'],
     'body-max-line-length':   [0, 'always', 100],
     'footer-leading-blank':   [2, 'always'],
diff --git a/docs/agents.md/agents/boundaries.md b/docs/agents.md/agents/boundaries.md
index e6cc500c..8aa6cb64 100644
--- a/docs/agents.md/agents/boundaries.md
+++ b/docs/agents.md/agents/boundaries.md
@@ -6,9 +6,7 @@
   - Run `yarn lint:fix` before commits.
     - Use conventional commit format: 
     ```
-    <type>:
-
-    <description>
+    <type>(<scope>): <description>
     ```
   - Follow existing naming conventions (PascalCase for components, camelCase for functions).
   - After changing a Vue, JS, or TS file, make sure it's automatically formatted with ESLint.
diff --git a/docs/agents.md/contributors/1_contributors.md b/docs/agents.md/contributors/1_contributors.md
index e28bea02..560b837b 100644
--- a/docs/agents.md/contributors/1_contributors.md
+++ b/docs/agents.md/contributors/1_contributors.md
@@ -16,8 +16,8 @@ To get started, follow the `Development Setup` section.
   - `Vue.js`:
     - Composition API components are preferred over Options API.
     - Large pages with lots of code and styles should be avoided by breaking the page up into smaller Vue components.
-    - Place source tag above template above style.
-    - style tag should contain `lang='scss' scoped`.
+    - Order the Single File Component blocks as `<script>`, then `<template>`, then `<style>`.
+    - The `<style>` tag should include `lang="scss" scoped`.
   - `Linting`: Follow the ESLint configuration in the root.
 
 - **File Structure:**
@@ -49,22 +49,24 @@ To get started, follow the `Development Setup` section.
 
 ## Harvester UI Extension Development Guide
 
-1. Backward Compatibility
-The Harvester UI Extension supports earlier cluster versions (e.g., UI Ext v1.8.0 works with clusters v1.7.0 and v1.6.0). It uses Feature Flags defined in pkg/config/feature-flags to ensure the UI matches the cluster's specific version.
+### Backward Compatibility
+
+The Harvester UI Extension supports earlier cluster versions (e.g., UI Ext v1.8.0 works with clusters v1.7.0 and v1.6.0). It uses Feature Flags defined in `pkg/harvester/config/` to ensure the UI matches the cluster's specific version.
+
+### Implementation Steps for New Features
 
-2. Implementation Steps for New Features
 To add a feature in a new release, follow these steps:
 
-    Register: Add a unique [Feature Name] to the corresponding release array in the configuration.
+1. **Register**: Add a unique `[Feature Name]` to the corresponding release array in the configuration.
+2. **Check**: Use the following getter to verify if the feature is enabled for the current version:
 
-    Check: Use the following getter to verify if the feature is enabled for the current version:
+   ```js
+   computed: {
+     newFeatureEnabled() {
+       return this.$store.getters['harvester-common/getFeatureEnabled']('[Feature Name]');
+     },
+   },
+   ```
 
-    ```
-    computed: {
-      newFeatureEnabled() {
-        return this.$store.getters['harvester-common/getFeatureEnabled']('[Feature Name]');
-      },
-    },
-    ```
-    Render: Use the result of the check to conditionally render the UI components.
+3. **Render**: Use the result of the check to conditionally render the UI components.
 
diff --git a/docs/agents.md/template_agents.md b/docs/agents.md/template_agents.md
index 1f779543..06fb2a41 100644
--- a/docs/agents.md/template_agents.md
+++ b/docs/agents.md/template_agents.md
@@ -1,4 +1,4 @@
-> This `./AGENTS.md` file is generated by running `yarn agents:generate`.
+> This `./AGENTS.md` file is generated by running `yarn agents:generate`. `CLAUDE.md` and `GEMINI.md` are symlinks to this file so Claude Code, GitHub Copilot and Gemini all read the same content.
 
 
 # Project Overview