From 10fddc9694fc3da1a02a5cdcd72a217961c5554a Mon Sep 17 00:00:00 2001
From: Alexander Brown <drjkl@comfy.org>
Date: Fri, 5 Dec 2025 15:03:31 -0800
Subject: [PATCH] =?UTF-8?q?=F0=9F=A4=96=20AGENTS.md=20consolidation=20and?=
 =?UTF-8?q?=20updates=20(#7194)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

Unify some of the different documentation intended for LLM consumption.

┆Issue is synchronized with this [Notion
page](https://www.notion.so/PR-7194-AGENTS-md-consolidation-and-updates-2c06d73d36508123b10ed75f03d41e75)
by [Unito](https://www.unito.io)

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
---
 .cursorrules |  61 -------------
 AGENTS.md    | 250 ++++++++++++++++++++++++++++++++++++++++++++++-----
 CLAUDE.md    | 120 ++-----------------------
 3 files changed, 234 insertions(+), 197 deletions(-)
 delete mode 100644 .cursorrules

diff --git a/.cursorrules b/.cursorrules
deleted file mode 100644
index 6f43623a3..000000000
--- a/.cursorrules
+++ /dev/null
@@ -1,61 +0,0 @@
-# Vue 3 Composition API Project Rules
-
-## Vue 3 Composition API Best Practices
-- Use setup() function for component logic
-- Utilize ref and reactive for reactive state
-- Implement computed properties with computed()
-- Use watch and watchEffect for side effects
-- Implement lifecycle hooks with onMounted, onUpdated, etc.
-- Utilize provide/inject for dependency injection
-- Use vue 3.5 style of default prop declaration. Example:
-
-```typescript
-const { nodes, showTotal = true } = defineProps<{
-  nodes: ApiNodeCost[]
-  showTotal?: boolean
-}>()
-```
-
-- Organize vue component in <template> <script> <style> order
-
-## Project Structure
-```
-src/
-  components/
-  constants/
-  composables/
-  views/
-  stores/
-  services/
-  App.vue
-  main.ts
-```
-
-## Styling Guidelines
-- Use Tailwind CSS for styling
-- Implement responsive design with Tailwind CSS
-
-## PrimeVue Component Guidelines
-DO NOT use deprecated PrimeVue components. Use these replacements instead:
-- Dropdown → Use Select (import from 'primevue/select')
-- OverlayPanel → Use Popover (import from 'primevue/popover')
-- Calendar → Use DatePicker (import from 'primevue/datepicker')
-- InputSwitch → Use ToggleSwitch (import from 'primevue/toggleswitch')
-- Sidebar → Use Drawer (import from 'primevue/drawer')
-- Chips → Use AutoComplete with multiple enabled and typeahead disabled
-- TabMenu → Use Tabs without panels
-- Steps → Use Stepper without panels
-- InlineMessage → Use Message component
-
-## Development Guidelines
-1. Leverage VueUse functions for performance-enhancing styles
-2. Use es-toolkit for utility functions
-3. Use TypeScript for type safety
-4. Implement proper props and emits definitions
-5. Utilize Vue 3's Teleport component when needed
-6. Use Suspense for async components
-7. Implement proper error handling
-8. Follow Vue 3 style guide and naming conventions
-9. Use Vite for fast development and building
-10. Use vue-i18n in composition API for any string literals. Place new translation entries in src/locales/en/main.json
-11. Never use deprecated PrimeVue components listed above
diff --git a/AGENTS.md b/AGENTS.md
index 0d060af1f..986a3e27e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,38 +1,242 @@
 # Repository Guidelines
 
 ## Project Structure & Module Organization
-- Source: `src/` (Vue 3 + TypeScript). Key areas: `components/`, `views/`, `stores/` (Pinia), `composables/`, `services/`, `utils/`, `assets/`, `locales/`.
-- Routing/i18n/entry: `src/router.ts`, `src/i18n.ts`, `src/main.ts`.
-- Tests: unit/component in `tests-ui/` and `src/components/**/*.{test,spec}.ts`; E2E in `browser_tests/`.
-- Public assets: `public/`. Build output: `dist/`.
-- Config: `vite.config.mts`, `vitest.config.ts`, `playwright.config.ts`, `eslint.config.ts`, `.prettierrc`.
+
+- Source: `src/`
+  - Vue 3.5+
+  - TypeScript
+  - Tailwind 4
+  - Key areas:
+    - `components/`
+    - `views/`
+    - `stores/` (Pinia)
+    - `composables/`
+    - `services/`
+    - `utils/`
+    - `assets/`
+    - `locales/`
+- Routing: `src/router.ts`,
+- i18n: `src/i18n.ts`,
+- Entry Point: `src/main.ts`.
+- Tests:
+  - unit/component in `tests-ui/` and `src/**/*.test.ts`
+  - E2E (Playwright) in `browser_tests/**/*.spec.ts`
+- Public assets: `public/`
+- Build output: `dist/`
+- Configs
+  - `vite.config.mts`
+  - `vitest.config.ts`
+  - `playwright.config.ts`
+  - `eslint.config.ts`
+  - `.prettierrc`
+  - etc.
+
+## Monorepo Architecture
+
+The project now uses **Nx** for build orchestration and task management:
+
+- **Task Orchestration**: Commands like `dev`, `build`, `lint`, and `test:browser` run via Nx
+- **Caching**: Nx provides intelligent caching for faster rebuilds
+- **Configuration**: Managed through `nx.json` with plugins for ESLint, Storybook, Vite, and Playwright
+- **Dependencies**: Nx handles dependency graph analysis and parallel execution
+
+Key Nx features:
+
+- Build target caching and incremental builds
+- Parallel task execution across the monorepo
+- Plugin-based architecture for different tools
 
 ## Build, Test, and Development Commands
+
 - `pnpm dev`: Start Vite dev server.
-- `pnpm dev:electron`: Dev server with Electron API mocks.
-- `pnpm build`: Type-check then production build to `dist/`.
-- `pnpm preview`: Preview the production build locally.
-- `pnpm test:unit`: Run Vitest unit tests.
-- `pnpm test:browser`: Run Playwright E2E tests (`browser_tests/`).
-- `pnpm lint` / `pnpm lint:fix`: Lint (ESLint). `pnpm format` / `format:check`: Prettier.
-- `pnpm typecheck`: Vue TSC type checking.
+- `pnpm dev:electron`: Dev server with Electron API mocks
+- `pnpm build`: Type-check then production build to `dist/`
+- `pnpm preview`: Preview the production build locally
+- `pnpm test:unit`: Run Vitest unit tests
+- `pnpm test:browser`: Run Playwright E2E tests (`browser_tests/`)
+- `pnpm lint` / `pnpm lint:fix`: Lint (ESLint)
+- `pnpm format` / `pnpm format:check`: Prettier
+- `pnpm typecheck`: Vue TSC type checking
 
 ## Coding Style & Naming Conventions
-- Language: TypeScript, Vue SFCs (`.vue`). Indent 2 spaces; single quotes; no semicolons; width 80 (see `.prettierrc`).
-- Imports: sorted/grouped by plugin; run `pnpm format` before committing.
-- ESLint: Vue + TS rules; no floating promises; unused imports disallowed; i18n raw text restrictions in templates.
-- Naming: Vue components in PascalCase (e.g., `MenuHamburger.vue`); composables `useXyz.ts`; Pinia stores `*Store.ts`.
+
+- Language:
+  - TypeScript (exclusive, no new JavaScript)
+  - Vue 3 SFCs (`.vue`)
+    - Composition API only
+  - Tailwind 4 styling
+    - Avoid `<style>` blocks
+- Style: (see `.prettierrc`)
+  - Indent 2 spaces
+  - single quotes
+  - no trailing semicolons
+  - width 80
+- Imports:
+  - sorted/grouped by plugin
+  - run `pnpm format` before committing
+- ESLint:
+  - Vue + TS rules
+  - no floating promises
+  - unused imports disallowed
+  - i18n raw text restrictions in templates
+- Naming:
+  - Vue components in PascalCase (e.g., `MenuHamburger.vue`)
+  - composables `useXyz.ts`
+  - Pinia stores `*Store.ts`
 
 ## Testing Guidelines
-- Frameworks: Vitest (unit/component, happy-dom) and Playwright (E2E).
-- Test files: `**/*.{test,spec}.{ts,tsx,js}` under `tests-ui/`, `src/components/`, and `src/lib/litegraph/test/`.
-- Coverage: text/json/html reporters enabled; aim to cover critical logic and new features.
-- Playwright: place tests in `browser_tests/`; optional tags like `@mobile`, `@2x` are respected by config.
+
+- Frameworks:
+  - Vitest (unit/component, happy-dom)
+  - Playwright (E2E)
+- Test files:
+  - Unit/Component: `**/*.test.ts`
+  - E2E: `browser_tests/**/*.spec.ts`
+  - Litegraph Specific: `src/lib/litegraph/test/`
+- Coverage: text/json/html reporters enabled
+  - aim to cover critical logic and new features
+- Playwright:
+  - optional tags like `@mobile`, `@2x` are respected by config
 
 ## Commit & Pull Request Guidelines
-- Commits: Use `[skip ci]` for locale-only updates when appropriate.
-- PRs: Include clear description, linked issues (`- Fixes #123`), and screenshots/GIFs for UI changes.
-- Quality gates: `pnpm lint`, `pnpm typecheck`, and relevant tests must pass. Keep PRs focused and small.
+
+- Commits: Use `[skip ci]` for locale-only updates when appropriate
+- PRs: Include clear description, linked issues (`- Fixes #123`), and screenshots/GIFs for UI changes
+- Quality gates: `pnpm lint`, `pnpm typecheck`, and relevant tests must pass
+- Keep PRs focused and small
 
 ## Security & Configuration Tips
+
 - Secrets: Use `.env` (see `.env_example`); do not commit secrets.
+
+## Vue 3 Composition API Best Practices
+
+- Use `<script setup lang="ts">` for component logic
+- Utilize `ref` for reactive state
+- Implement computed properties with computed()
+- Use watch and watchEffect for side effects
+  - Avoid using a `ref` and a `watch` if a `computed` would work instead
+- Implement lifecycle hooks with onMounted, onUpdated, etc.
+- Utilize provide/inject for dependency injection
+  - Do not use dependency injection if a Store or a shared composable would be simpler
+- Use Vue 3.5 TypeScript style of default prop declaration
+  - Example:
+
+    ```typescript
+    const { nodes, showTotal = true } = defineProps<{
+    nodes: ApiNodeCost[]
+    showTotal?: boolean
+    }>()
+    ```
+
+  - Do not use `withDefaults` or runtime props declaration
+  - Do not import Vue macros unnecessarily
+  - Prefer `useModel` to separately defining a prop and emit
+  - Be judicious with addition of new refs or other state
+    - If it's possible to accomplish the design goals with just a prop, don't add a `ref`
+    - If it's possible to use the `ref` or prop directly, don't add a `computed`
+    - If it's possible to use a `computed` to name and reuse a derived value, don't use a `watch`
+
+## Development Guidelines
+
+1. Leverage VueUse functions for performance-enhancing styles
+2. Use es-toolkit for utility functions
+3. Use TypeScript for type safety
+4. Implement proper props and emits definitions
+5. Utilize Vue 3's Teleport component when needed
+6. Use Suspense for async components
+7. Implement proper error handling
+8. Follow Vue 3 style guide and naming conventions
+9. Use Vite for fast development and building
+10. Use vue-i18n in composition API for any string literals. Place new translation entries in src/locales/en/main.json
+11. Avoid new usage of PrimeVue components
+
+## External Resources
+
+- Vue: <https://vuejs.org/api/>
+- Tailwind: <https://tailwindcss.com/docs/styling-with-utility-classes>
+- shadcn/vue: <https://www.shadcn-vue.com/>
+- Reka UI: <https://reka-ui.com/>
+- PrimeVue: <https://primevue.org>
+- ComfyUI: <https://docs.comfy.org>
+- Electron: <https://www.electronjs.org/docs/latest/>
+- Wiki: <https://deepwiki.com/Comfy-Org/ComfyUI_frontend/1-overview>
+
+## Project Philosophy
+
+- Follow good software engineering principles
+  - YAGNI
+  - AHA
+  - DRY
+  - SOLID
+- Clean, stable public APIs
+- Domain-driven design
+- Thousands of users and extensions
+- Prioritize clean interfaces that restrict extension access
+
+## Repository Navigation
+
+- Check README files in key folders (tests-ui, browser_tests, composables, etc.)
+- Prefer running single tests for performance
+- Use --help for unfamiliar CLI tools
+
+## GitHub Integration
+
+When referencing Comfy-Org repos:
+
+1. Check for local copy
+2. Use GitHub API for branches/PRs/metadata
+3. Curl GitHub website if needed
+
+## Settings and Feature Flags Quick Reference
+
+### Settings Usage
+
+```typescript
+const settingStore = useSettingStore()
+const value = settingStore.get('Comfy.SomeSetting')     // Get setting
+await settingStore.set('Comfy.SomeSetting', newValue)   // Update setting
+```
+
+### Dynamic Defaults
+
+```typescript
+{
+  id: 'Comfy.Example.Setting',
+  defaultValue: () => window.innerWidth < 1024 ? 'small' : 'large'  // Runtime context
+}
+```
+
+### Version-Based Defaults
+
+```typescript
+{
+  id: 'Comfy.Example.Feature',
+  defaultValue: 'legacy',
+  defaultsByInstallVersion: { '1.25.0': 'enhanced' }  // Gradual rollout
+}
+```
+
+### Feature Flags
+
+```typescript
+if (api.serverSupportsFeature('feature_name')) {  // Check capability
+  // Use enhanced feature
+}
+const value = api.getServerFeature('config_name', defaultValue)  // Get config
+```
+
+**Documentation:**
+
+- Settings system: `docs/SETTINGS.md`
+- Feature flags system: `docs/FEATURE_FLAGS.md`
+
+## Common Pitfalls
+
+- NEVER use `any` type - use proper TypeScript types
+- NEVER use `as any` type assertions - fix the underlying type issue
+- NEVER use `--no-verify` flag when committing
+- NEVER delete or disable tests to make them pass
+- NEVER circumvent quality checks
+- NEVER use `dark:` or `dark-theme:` tailwind variants. Instead use a semantic value from the `style.css` theme, e.g. `bg-node-component-surface`
+- NEVER use `:class="[]"` to merge class names - always use `import { cn } from '@/utils/tailwindUtil'`, for example: `<div :class="cn('text-node-component-header-icon', hasError && 'text-danger')" />`
diff --git a/CLAUDE.md b/CLAUDE.md
index 7a456b1fa..85df32685 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,44 +1,19 @@
-# ComfyUI Frontend Project Guidelines
+# Claude Code specific instructions
+
+@Agents.md
 
 ## Repository Setup
 
 For first-time setup, use the Claude command:
-```
+
+```sh
 /setup_repo
 ```
+
 This bootstraps the monorepo with dependencies, builds, tests, and dev server verification.
 
 **Prerequisites:** Node.js >= 24, Git repository, available ports (5173, 6006)
 
-## Quick Commands
-
-- `pnpm`: See all available commands
-- `pnpm dev`: Start development server (port 5173, via nx)
-- `pnpm typecheck`: Type checking
-- `pnpm build`: Build for production (via nx)
-- `pnpm lint`: Linting (via nx)
-- `pnpm oxlint`: Fast Rust-based linting with Oxc
-- `pnpm format`: Prettier formatting
-- `pnpm test:unit`: Run all unit tests
-- `pnpm test:browser`: Run E2E tests via Playwright
-- `pnpm test:unit -- tests-ui/tests/example.test.ts`: Run single test file
-- `pnpm storybook`: Start Storybook development server (port 6006)
-- `pnpm knip`: Detect unused code and dependencies
-
-## Monorepo Architecture
-
-The project now uses **Nx** for build orchestration and task management:
-
-- **Task Orchestration**: Commands like `dev`, `build`, `lint`, and `test:browser` run via Nx
-- **Caching**: Nx provides intelligent caching for faster rebuilds
-- **Configuration**: Managed through `nx.json` with plugins for ESLint, Storybook, Vite, and Playwright
-- **Dependencies**: Nx handles dependency graph analysis and parallel execution
-
-Key Nx features:
-- Build target caching and incremental builds
-- Parallel task execution across the monorepo
-- Plugin-based architecture for different tools
-
 ## Development Workflow
 
 1. **First-time setup**: Run `/setup_repo` Claude command
@@ -50,87 +25,6 @@ Key Nx features:
 
 ## Git Conventions
 
-- Use [prefix] format: [feat], [bugfix], [docs]
+- Use `prefix:` format: `feat:`, `fix:`, `test:`
 - Add "Fixes #n" to PR descriptions
 - Never mention Claude/AI in commits
-
-## External Resources
-
-- PrimeVue docs: <https://primevue.org>
-- ComfyUI docs: <https://docs.comfy.org>
-- Electron: <https://www.electronjs.org/docs/latest/>
-- Wiki: <https://deepwiki.com/Comfy-Org/ComfyUI_frontend/1-overview>
-
-## Project Philosophy
-
-- Follow good software engineering principles
-  - YAGNI
-  - AHA
-  - DRY
-  - SOLID
-- Clean, stable public APIs
-- Domain-driven design
-- Thousands of users and extensions
-- Prioritize clean interfaces that restrict extension access
-
-## Repository Navigation
-
-- Check README files in key folders (tests-ui, browser_tests, composables, etc.)
-- Prefer running single tests for performance
-- Use --help for unfamiliar CLI tools
-
-## GitHub Integration
-
-When referencing Comfy-Org repos:
-
-1. Check for local copy
-2. Use GitHub API for branches/PRs/metadata
-3. Curl GitHub website if needed
-
-## Settings and Feature Flags Quick Reference
-
-### Settings Usage
-```typescript
-const settingStore = useSettingStore()
-const value = settingStore.get('Comfy.SomeSetting')     // Get setting
-await settingStore.set('Comfy.SomeSetting', newValue)   // Update setting
-```
-
-### Dynamic Defaults
-```typescript
-{
-  id: 'Comfy.Example.Setting',
-  defaultValue: () => window.innerWidth < 1024 ? 'small' : 'large'  // Runtime context
-}
-```
-
-### Version-Based Defaults
-```typescript
-{
-  id: 'Comfy.Example.Feature',
-  defaultValue: 'legacy',
-  defaultsByInstallVersion: { '1.25.0': 'enhanced' }  // Gradual rollout
-}
-```
-
-### Feature Flags
-```typescript
-if (api.serverSupportsFeature('feature_name')) {  // Check capability
-  // Use enhanced feature
-}
-const value = api.getServerFeature('config_name', defaultValue)  // Get config
-```
-
-**Documentation:**
-- Settings system: `docs/SETTINGS.md`
-- Feature flags system: `docs/FEATURE_FLAGS.md`
-
-## Common Pitfalls
-
-- NEVER use `any` type - use proper TypeScript types
-- NEVER use `as any` type assertions - fix the underlying type issue
-- NEVER use `--no-verify` flag when committing
-- NEVER delete or disable tests to make them pass
-- NEVER circumvent quality checks
-- NEVER use `dark:` or `dark-theme:` tailwind variants. Instead use a semantic value from the `style.css` theme, e.g. `bg-node-component-surface`
-- NEVER use `:class="[]"` to merge class names - always use `import { cn } from '@/utils/tailwindUtil'`, for example: `<div :class="cn('text-node-component-header-icon', hasError && 'text-danger')" />`