docs: add AGENTS.md for AI agent guidance (#837)

* feat: add AGENNTS.md Signed-off-by: Andy Lee <andy.lee@suse.com> * refactor: update based on copilot feedback Signed-off-by: Andy Lee <andy.lee@suse.com> * refactor: update AGENTS.md Signed-off-by: Andy Lee <andy.lee@suse.com> * refactor: update based on AI suggestion Signed-off-by: Andy Lee <andy.lee@suse.com> * refactor: based on comments Signed-off-by: Andy Lee <andy.lee@suse.com> * refactor: some files Signed-off-by: Andy Lee <andy.lee@suse.com> * refactor: boundaries.md Signed-off-by: Andy Lee <andy.lee@suse.com> --------- Signed-off-by: Andy Lee <andy.lee@suse.com>
2026-05-14 06:51:46 +00:00 · 2026-04-29 16:05:51 +08:00 · 2026-04-29 16:05:51 +08:00 · 67bb6dfbd5
commit 67bb6dfbd5
parent e74428d951
12 changed files with 628 additions and 1 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@ -0,0 +1,261 @@
+> This `./AGENTS.md` file is generated by running `yarn agents:generate`.
+
+
+# Project Overview
+
+The Harvester UI Extension is a Rancher extension that provides the user interface for Harvester within the Rancher Dashboard.
+
+```
+Note: This extension is available starting from Rancher 2.10.0. Ensure your Rancher version is 2.10.0 or later to access Harvester integration.
+```
+
+# Personas
+
+## Software Developer
+
+You are an expert Senior Software Engineer specializing in Vue.js and TypeScript. You have deep knowledge of Kubernetes and the Rancher ecosystem.
+- **Focus**: Writing clean, maintainable, and performant code.
+- **Priorities**: Adhering to the project's code style, ensuring type safety, and following best practices for component design.
+
+
+# Agents
+
+## Boundaries
+
+- ✅ **Always:**
+  - Write to `.github`, `docs/`,  `pkg/harvester`, `scripts/`.
+  - Make commits in a new branch (for a PR).
+  - Run `yarn lint:fix` before commits.
+    - Use conventional commit format: 
+    ```
+    <type>:
+
+    <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.
+  - After updating files in `docs/agents.md/`, run `yarn agents:generate` to update root `AGENTS.md`.   
+- ⚠️ **Ask first:**
+  - Adding dependencies
+  - Upgrading dependencies
+- 🚫 **Never:**
+  - Commit or log secrets, `.env`, `kubeconfig` or any API keys.
+  - Edit `node_modules/`.
+  - Commit directly to `main` (use PRs).
+  - Skip git hooks with `--no-verify` flag.
+
+## Tools
+
+### Prerequisites
+
+- **Node.js**: `>= 24.0.0` (see `.nvmrc` for the pinned version: `24`)
+- **Package manager**: `yarn` (v1 classic)
+
+### Common Commands
+
+| Command | Description |
+|---------|-------------|
+| `yarn install --frozen-lockfile` | Install dependencies (CI-safe, no lockfile changes) |
+| `RANCHER_ENV=harvester API=https://<harvester-ip> yarn dev` | Start development server at `https://127.0.0.1:8005` |
+| `yarn build-pkg harvester` | Build the Harvester extension package |
+| `yarn serve-pkgs` | Serve the locally built extension for testing |
+| `yarn lint` | Run ESLint (zero warnings allowed) |
+| `yarn lint:fix` | Run ESLint with auto-fix |
+| `yarn clean` | Clean build artifacts |
+| `yarn agents:generate` | Regenerate `AGENTS.md` from `docs/agents.md/` sources |
+
+### Development
+
+- **Start dev server**:
+  ```bash
+  RANCHER_ENV=harvester API=https://your-harvester-ip yarn dev
+  ```
+  - `API` should point to a running Harvester cluster (e.g., `https://x.x.x.x`).
+  - The dashboard will be available at `https://127.0.0.1:8005`.
+
+### Building
+
+- **Build extension package**:
+  ```bash
+  yarn build-pkg harvester
+  ```
+- **Serve locally built extension** (for integration testing with a Rancher instance):
+  ```bash
+  yarn serve-pkgs
+  ```
+
+### Linting
+
+- **Check** (must pass with zero warnings):
+  ```bash
+  yarn lint
+  ```
+- **Auto-fix**:
+  ```bash
+  yarn lint:fix
+  ```
+- ESLint covers `.js`, `.ts`, and `.vue` files.
+- Always run `yarn lint:fix` before committing.
+
+### Commit Conventions
+
+- Commits are validated by [commitlint](https://commitlint.js.org/) via a Husky `commit-msg` hook.
+- Follow [Conventional Commits](https://www.conventionalcommits.org/) format (configured in `commitlint.config.js`).
+
+### Agent Documentation
+
+- Source files live in `docs/agents.md/` (agents, contributors, personas subdirectories).
+- After editing any source file, regenerate the root `AGENTS.md`:
+  ```bash
+  yarn agents:generate
+  ```
+
+# Contributors Guide
+
+## Getting Started
+
+Please see the [Harvester UI Extension README](https://github.com/harvester/harvester-ui-extension).
+
+To get started, follow the `Development Setup` section.
+
+## Project Information
+
+- **Tech Stack:**
+  - `Vue.js`: Framework
+  - `Linting`: ESLint
+  - `CSS`: SCSS should be used
+  - `TypeScript`: Primary language for logic.
+- **Code Style and Standards:**
+  - `Language`: TypeScript is preferred for new code.
+  - `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`.
+  - `Linting`: Follow the ESLint configuration in the root.
+
+- **File Structure:**
+  - `.github/`: CI/CD workflows and Renovate config.
+  - `docs/`: Documentation source for `AGENTS.md` generation.
+  - `scripts/`: Bash scripts for build, CI and doc generation.
+  - `pkg/harvester/`: Main extension source. Files are named after K8s resource types (e.g., `kubevirt.io.virtualmachine`, `harvesterhci.io.volume`).
+     - `index.ts`: Plugin entry point — registers the product and auto-imports models/detail/edit views.
+     - `types.ts`: `HCI` constant mapping 60+ K8s resource types to string identifiers.
+     - `components/`: Reusable Vue components (VNC/serial console, settings panels, upgrade banners, filters).
+     - `config/`: Constants — settings keys, table column definitions, feature flags, type mappings, doc links.
+     - `detail/`: Read-only detail views per resource type. Complex resources use subdirectories with tabs.
+     - `dialog/`: Modal dialogs for operations (VM clone/migrate/restart, backup/restore, device passthrough, etc.).
+     - `edit/`: Create/edit forms. Complex resources (e.g., VM) split into subcomponents (CpuMemory, Network, Volume, CloudConfig, etc.).
+     - `formatters/`: Table cell formatters — state badges, usage bars, resource references.
+     - `l10n/`: Localization (`en-us.yaml`).
+     - `list/`: List (table) views per resource type, mirroring `detail/` and `edit/` naming.
+     - `mixins/`: Shared Vue mixins — VM helpers (`harvester-vm/`) and disk helpers (`harvester-disk.js`).
+     - `models/`: Model classes extending `SteveModel` with computed properties and actions. Base class: `harvester.js`.
+     - `pages/`: Route-level pages — dashboard, support, console, members, brand, alertmanager.
+     - `promptRemove/`: Custom delete-confirmation dialogs (VM, backup).
+     - `routing/`: Vue Router config — all product routes (CRUD, console, support, upgrade, etc.).
+     - `store/`: Vuex modules — `harvester-common.js` for shared state; `harvester-store/` for VM/resource creation actions with Steve integration.
+     - `styles/`: Global SCSS files.
+     - `utils/`: Helpers — VM volume templates, CPU/memory calc, cron parsing, regex validators, feature flags.
+     - `validators/`: Form validation functions per resource type, pushing i18n error messages.
+  
+  
+
+## 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.
+
+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.
+
+    Check: Use the following getter to verify if the feature is enabled for the current version:
+
+    ```
+    computed: {
+      newFeatureEnabled() {
+        return this.$store.getters['harvester-common/getFeatureEnabled']('[Feature Name]');
+      },
+    },
+    ```
+    Render: Use the result of the check to conditionally render the UI components.
+
+
+## E2E Tests (Cypress)
+
+See https://github.com/harvester/harvester-ui-tests
+
+## Node Dependencies
+
+Dependencies are managed via `package.json` and `yarn`
+
+- To install dependencies use `yarn install`. This will fail if dependencies and versions listed in `package.json` are out of step with the `yarn.lock` file
+- To add a dependency use `yarn run add:no-lock ...` instead of `yarn add`
+- To upgrade a dependency use `yarn run upgrade:no-lock ...` instead of `yarn upgrade`
+
+
+Renovate automatically updates dependencies and opens upgrade PRs after 10:00 AM on Sundays (`Asia/Taipei`).
+For the Renovate config, see `.github/renovate.json`.
+
+
+## Milestone guidance
+
+- All issues must first be resolved in the `main` branch
+- If backports are needed they can be made via the backport bot
+  - pull requests
+    - comment `@Mergifyio backport <target branch>` e.g. `@Mergifyio backport release-harvester-v1.8`
+    - All backported pull requests must link to a backported issue
+
+
+## Creating a branch
+
+### To resolve an issue
+- Checkout the branch matching the milestone of the issue `git checkout ${targetMilestoneBranch}`. Replace `${targetMilestoneBranch}` with the target milestone of the issue. For example
+  - `main` for the latest unreleased minor version
+  - `release-harvester-v.X` for release minor versions
+    - `release-harvester-v1.6`
+    - `release-harvester-v1.7`
+    - `release-harvester-v1.8`
+- Ensure you have the latest of that branch `git pull --rebase`
+- Checkout the branch to commit the changes to `git checkout issue-${issueNumber}`. Replace `${issueNumber}` with the issue number.
+
+## Creating a commit
+
+- This project uses commit-lint with [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) to ensure consistent and meaningful commit messages.
+
+### Commit Message Format
+All commit messages must follow the conventional commit format:
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Supported Types
+- feat: New features
+- fix: Bug fixes
+- docs: Documentation changes
+- style: Code style changes (formatting, missing semicolons, etc.)
+- refactor: Code refactoring
+- perf: Performance improvements
+- test: Adding or updating tests
+- build: Build system or external dependencies
+- ci: CI/CD changes
+- chore: Other changes that don't modify src or test files
+- revert: Reverts a previous commit
+- wip: Work in progress
+- deps: Dependency updates
+- security: Security fixes
+
+## Creating a Pull Request
+
+- Pull requests must come from forks
+- Description should always have commit supported type prefix. E.g `fix: XXX`, `feat: OOO`
+- A Pull Request will only be merged once
+  - ALL CI gates have passed
+  - At least one harvester/harvester-ui-extension code owners reviews and approves the PR
+
--- a/docs/agents.md/README
+++ b/docs/agents.md/README
@ -0,0 +1,63 @@
+# Agents.md
+
+This folder contains files used to construct a single root `AGENTS.md`
+
+We do this because
+- The single commonality between almost all AI tools is that they look for a root `AGENTS.md`
+- Having the information in a single place for all AI tools is better than duplicating and maintaining the information in multiple files for each AI tool
+
+## Process
+1. Add files to or update files in `./docs/agents.md/agents`, `./docs/agents.md/personas`, `./docs/agents.md/contributors`.
+2. Each file must
+  - Start markdown headers at the `##` level
+  - End in a new line
+  - Order contents in AGENTS.md by giving an optional number prefix
+3. Run `yarn agents:generate`.
+   - Take the contents of `./docs/agents.md/template_agents.md`
+   - Insert the contents of the agents, personas and contributors files
+   - Output to `./AGENTS.md`
+4. Commit all changes, including root `./AGENTS.md` and any files that link to it
+
+## Guidance
+
+### Examples
+
+When referencing code or configuration it's good to include an example
+
+## Future Tasks
+- Add real world examples when referencing code
+- Create a GH workflow to monitor `agents.md` folder files in a PR, if changed run generate script and add new AGENTS.md to PR
+- Discuss
+  - Three multi AI tool related questions
+    - Questions
+      - how AI specific patterns, like co-pilot instructions, can be expressed in a way to be adopted by or reduce duplication with the root agents.md
+      - how AI tool specific metadata code can be included
+      - multiple agents vs personas approach works
+    - Proposal
+      - Generic information applicable to all AI tools is added to the root `agents.md`
+      - Agent, instruction or other AI specific files or patterns can be used in files specific to that AI tool. They must not contain duplicate information to the root `agents.md`
+      - The root `agents.md` continues to be AI tool agnostic
+  - How can folder specific agents be used
+    - Proposal
+      - `agents.md` are added to folders as long as most LLMs can make use of them and they do not duplicate information in the root `agents.md`
+
+## Test Prompts
+
+To validate LLMs are picking up information consider running the following prompts.
+
+### Information
+
+Can they provide correct information?
+
+- `what's this project about?`
+- `can you tell me the process for fixing a github issue in this repo?`
+- `what makes a good software developer?`
+- `what should never be done in this project?`
+- `what are the folders in this project for?`
+- `what are the env vars i could use when running e2e tests?`
+
+### Actions
+
+Can they use the information in their actions?
+
+Pending
--- a/docs/agents.md/agents/boundaries.md
+++ b/docs/agents.md/agents/boundaries.md
@ -0,0 +1,23 @@
+## Boundaries
+
+- ✅ **Always:**
+  - Write to `.github`, `docs/`,  `pkg/harvester`, `scripts/`.
+  - Make commits in a new branch (for a PR).
+  - Run `yarn lint:fix` before commits.
+    - Use conventional commit format: 
+    ```
+    <type>:
+
+    <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.
+  - After updating files in `docs/agents.md/`, run `yarn agents:generate` to update root `AGENTS.md`.   
+- ⚠️ **Ask first:**
+  - Adding dependencies
+  - Upgrading dependencies
+- 🚫 **Never:**
+  - Commit or log secrets, `.env`, `kubeconfig` or any API keys.
+  - Edit `node_modules/`.
+  - Commit directly to `main` (use PRs).
+  - Skip git hooks with `--no-verify` flag.
--- a/docs/agents.md/agents/tools.md
+++ b/docs/agents.md/agents/tools.md
@ -0,0 +1,65 @@
+## Tools
+
+### Prerequisites
+
+- **Node.js**: `>= 24.0.0` (see `.nvmrc` for the pinned version: `24`)
+- **Package manager**: `yarn` (v1 classic)
+
+### Common Commands
+
+| Command | Description |
+|---------|-------------|
+| `yarn install --frozen-lockfile` | Install dependencies (CI-safe, no lockfile changes) |
+| `RANCHER_ENV=harvester API=https://<harvester-ip> yarn dev` | Start development server at `https://127.0.0.1:8005` |
+| `yarn build-pkg harvester` | Build the Harvester extension package |
+| `yarn serve-pkgs` | Serve the locally built extension for testing |
+| `yarn lint` | Run ESLint (zero warnings allowed) |
+| `yarn lint:fix` | Run ESLint with auto-fix |
+| `yarn clean` | Clean build artifacts |
+| `yarn agents:generate` | Regenerate `AGENTS.md` from `docs/agents.md/` sources |
+
+### Development
+
+- **Start dev server**:
+  ```bash
+  RANCHER_ENV=harvester API=https://your-harvester-ip yarn dev
+  ```
+  - `API` should point to a running Harvester cluster (e.g., `https://x.x.x.x`).
+  - The dashboard will be available at `https://127.0.0.1:8005`.
+
+### Building
+
+- **Build extension package**:
+  ```bash
+  yarn build-pkg harvester
+  ```
+- **Serve locally built extension** (for integration testing with a Rancher instance):
+  ```bash
+  yarn serve-pkgs
+  ```
+
+### Linting
+
+- **Check** (must pass with zero warnings):
+  ```bash
+  yarn lint
+  ```
+- **Auto-fix**:
+  ```bash
+  yarn lint:fix
+  ```
+- ESLint covers `.js`, `.ts`, and `.vue` files.
+- Always run `yarn lint:fix` before committing.
+
+### Commit Conventions
+
+- Commits are validated by [commitlint](https://commitlint.js.org/) via a Husky `commit-msg` hook.
+- Follow [Conventional Commits](https://www.conventionalcommits.org/) format (configured in `commitlint.config.js`).
+
+### Agent Documentation
+
+- Source files live in `docs/agents.md/` (agents, contributors, personas subdirectories).
+- After editing any source file, regenerate the root `AGENTS.md`:
+  ```bash
+  yarn agents:generate
+  ```
--- a/docs/agents.md/contributors/1_contributors.md
+++ b/docs/agents.md/contributors/1_contributors.md
@ -0,0 +1,70 @@
+## Getting Started
+
+Please see the [Harvester UI Extension README](https://github.com/harvester/harvester-ui-extension).
+
+To get started, follow the `Development Setup` section.
+
+## Project Information
+
+- **Tech Stack:**
+  - `Vue.js`: Framework
+  - `Linting`: ESLint
+  - `CSS`: SCSS should be used
+  - `TypeScript`: Primary language for logic.
+- **Code Style and Standards:**
+  - `Language`: TypeScript is preferred for new code.
+  - `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`.
+  - `Linting`: Follow the ESLint configuration in the root.
+
+- **File Structure:**
+  - `.github/`: CI/CD workflows and Renovate config.
+  - `docs/`: Documentation source for `AGENTS.md` generation.
+  - `scripts/`: Bash scripts for build, CI and doc generation.
+  - `pkg/harvester/`: Main extension source. Files are named after K8s resource types (e.g., `kubevirt.io.virtualmachine`, `harvesterhci.io.volume`).
+     - `index.ts`: Plugin entry point — registers the product and auto-imports models/detail/edit views.
+     - `types.ts`: `HCI` constant mapping 60+ K8s resource types to string identifiers.
+     - `components/`: Reusable Vue components (VNC/serial console, settings panels, upgrade banners, filters).
+     - `config/`: Constants — settings keys, table column definitions, feature flags, type mappings, doc links.
+     - `detail/`: Read-only detail views per resource type. Complex resources use subdirectories with tabs.
+     - `dialog/`: Modal dialogs for operations (VM clone/migrate/restart, backup/restore, device passthrough, etc.).
+     - `edit/`: Create/edit forms. Complex resources (e.g., VM) split into subcomponents (CpuMemory, Network, Volume, CloudConfig, etc.).
+     - `formatters/`: Table cell formatters — state badges, usage bars, resource references.
+     - `l10n/`: Localization (`en-us.yaml`).
+     - `list/`: List (table) views per resource type, mirroring `detail/` and `edit/` naming.
+     - `mixins/`: Shared Vue mixins — VM helpers (`harvester-vm/`) and disk helpers (`harvester-disk.js`).
+     - `models/`: Model classes extending `SteveModel` with computed properties and actions. Base class: `harvester.js`.
+     - `pages/`: Route-level pages — dashboard, support, console, members, brand, alertmanager.
+     - `promptRemove/`: Custom delete-confirmation dialogs (VM, backup).
+     - `routing/`: Vue Router config — all product routes (CRUD, console, support, upgrade, etc.).
+     - `store/`: Vuex modules — `harvester-common.js` for shared state; `harvester-store/` for VM/resource creation actions with Steve integration.
+     - `styles/`: Global SCSS files.
+     - `utils/`: Helpers — VM volume templates, CPU/memory calc, cron parsing, regex validators, feature flags.
+     - `validators/`: Form validation functions per resource type, pushing i18n error messages.
+  
+  
+
+## 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.
+
+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.
+
+    Check: Use the following getter to verify if the feature is enabled for the current version:
+
+    ```
+    computed: {
+      newFeatureEnabled() {
+        return this.$store.getters['harvester-common/getFeatureEnabled']('[Feature Name]');
+      },
+    },
+    ```
+    Render: Use the result of the check to conditionally render the UI components.
+
--- a/docs/agents.md/contributors/2_e2e-tests.md
+++ b/docs/agents.md/contributors/2_e2e-tests.md
@ -0,0 +1,3 @@
+## E2E Tests (Cypress)
+
+See https://github.com/harvester/harvester-ui-tests
--- a/docs/agents.md/contributors/node-dependencies.md
+++ b/docs/agents.md/contributors/node-dependencies.md
@ -0,0 +1,12 @@
+## Node Dependencies
+
+Dependencies are managed via `package.json` and `yarn`
+
+- To install dependencies use `yarn install`. This will fail if dependencies and versions listed in `package.json` are out of step with the `yarn.lock` file
+- To add a dependency use `yarn run add:no-lock ...` instead of `yarn add`
+- To upgrade a dependency use `yarn run upgrade:no-lock ...` instead of `yarn upgrade`
+
+
+Renovate automatically updates dependencies and opens upgrade PRs after 10:00 AM on Sundays (`Asia/Taipei`).
+For the Renovate config, see `.github/renovate.json`.
+
--- a/docs/agents.md/contributors/resolving_gh_issues.md
+++ b/docs/agents.md/contributors/resolving_gh_issues.md
@ -0,0 +1,58 @@
+## Milestone guidance
+
+- All issues must first be resolved in the `main` branch
+- If backports are needed they can be made via the backport bot
+  - pull requests
+    - comment `@Mergifyio backport <target branch>` e.g. `@Mergifyio backport release-harvester-v1.8`
+    - All backported pull requests must link to a backported issue
+
+
+## Creating a branch
+
+### To resolve an issue
+- Checkout the branch matching the milestone of the issue `git checkout ${targetMilestoneBranch}`. Replace `${targetMilestoneBranch}` with the target milestone of the issue. For example
+  - `main` for the latest unreleased minor version
+  - `release-harvester-v.X` for release minor versions
+    - `release-harvester-v1.6`
+    - `release-harvester-v1.7`
+    - `release-harvester-v1.8`
+- Ensure you have the latest of that branch `git pull --rebase`
+- Checkout the branch to commit the changes to `git checkout issue-${issueNumber}`. Replace `${issueNumber}` with the issue number.
+
+## Creating a commit
+
+- This project uses commit-lint with [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) to ensure consistent and meaningful commit messages.
+
+### Commit Message Format
+All commit messages must follow the conventional commit format:
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Supported Types
+- feat: New features
+- fix: Bug fixes
+- docs: Documentation changes
+- style: Code style changes (formatting, missing semicolons, etc.)
+- refactor: Code refactoring
+- perf: Performance improvements
+- test: Adding or updating tests
+- build: Build system or external dependencies
+- ci: CI/CD changes
+- chore: Other changes that don't modify src or test files
+- revert: Reverts a previous commit
+- wip: Work in progress
+- deps: Dependency updates
+- security: Security fixes
+
+## Creating a Pull Request
+
+- Pull requests must come from forks
+- Description should always have commit supported type prefix. E.g `fix: XXX`, `feat: OOO`
+- A Pull Request will only be merged once
+  - ALL CI gates have passed
+  - At least one harvester/harvester-ui-extension code owners reviews and approves the PR
--- a/docs/agents.md/personas/software_developer.md
+++ b/docs/agents.md/personas/software_developer.md
@ -0,0 +1,5 @@
+## Software Developer
+
+You are an expert Senior Software Engineer specializing in Vue.js and TypeScript. You have deep knowledge of Kubernetes and the Rancher ecosystem.
+- **Focus**: Writing clean, maintainable, and performant code.
+- **Priorities**: Adhering to the project's code style, ensuring type safety, and following best practices for component design.
--- a/docs/agents.md/template_agents.md
+++ b/docs/agents.md/template_agents.md
@ -0,0 +1,22 @@
+> This `./AGENTS.md` file is generated by running `yarn agents:generate`.
+
+
+# Project Overview
+
+The Harvester UI Extension is a Rancher extension that provides the user interface for Harvester within the Rancher Dashboard.
+
+```
+Note: This extension is available starting from Rancher 2.10.0. Ensure your Rancher version is 2.10.0 or later to access Harvester integration.
+```
+
+# Personas
+
+`<personas>`
+
+# Agents
+
+`<agents>`
+
+# Contributors Guide
+
+`<contributors>`
--- a/package.json
+++ b/package.json
@ -49,7 +49,8 @@
    "publish-pkgs": "./node_modules/@rancher/shell/scripts/extension/publish",
    "parse-tag-name": "./node_modules/@rancher/shell/scripts/extension/parse-tag-name",
    "commitlint": "commitlint --edit",
-    "prepare": "husky"
+    "prepare": "husky",
+    "agents:generate": "./scripts/generate-agent-and-persona-mds.sh"
  },
  "devDependencies": {
    "@commitlint/load": "^19.8.1",
--- a/scripts/generate-agent-and-persona-mds.sh
+++ b/scripts/generate-agent-and-persona-mds.sh
@ -0,0 +1,44 @@
+#!/bin/bash
+set -e
+
+# Get the directory of the script
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+# Project root is one level up from scripts/
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+
+# Source files
+TEMPLATE_FILE="${PROJECT_ROOT}/docs/agents.md/template_agents.md"
+AGENTS_DIR="${PROJECT_ROOT}/docs/agents.md/agents"
+CONTRIBUTORS_DIR="${PROJECT_ROOT}/docs/agents.md/contributors"
+PERSONAS_DIR="${PROJECT_ROOT}/docs/agents.md/personas"
+
+# Destination file
+OUTPUT_FILE="${PROJECT_ROOT}/AGENTS.md"
+
+insert_directory_contents() {
+    local dir="$1"
+    if [ -d "$dir" ]; then
+        for file in "$dir"/*; do
+            if [ -f "$file" ]; then
+                cat "$file"
+                echo ""
+            fi
+        done
+    fi
+}
+
+echo "Generating ${OUTPUT_FILE}..."
+
+while IFS= read -r line || [ -n "$line" ]; do
+    if [[ "$line" == *"<agents>"* ]]; then
+        insert_directory_contents "${AGENTS_DIR}"
+    elif [[ "$line" == *"<contributors>"* ]]; then
+        insert_directory_contents "${CONTRIBUTORS_DIR}"
+    elif [[ "$line" == *"<personas>"* ]]; then
+        insert_directory_contents "${PERSONAS_DIR}"
+    else
+        echo "$line"
+    fi
+done < "${TEMPLATE_FILE}" > "${OUTPUT_FILE}"
+
+echo "Done."