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-10-04 21:26:08 +08:00 · 2026-04-29 16:05:51 +08:00
parent e74428d951
commit 67bb6dfbd5
12 changed files with 628 additions and 1 deletions
@@ -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.
@@ -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
+  ```