Skip to content

AGENTS.md

Latest commit

 

History

History
383 lines (335 loc) · 20.5 KB

AGENTS.md

File metadata and controls

383 lines (335 loc) · 20.5 KB

AGENTS.md

version: 1 default_agent: "@dev-agent"

Consulted files (agent must populate before committing):

README.md files:

  • /README.md - Main project README
  • /frontend/README.md - Frontend-specific README
  • /backend/README.md - Backend quickstart guide
  • /app/README.md - Desktop app README
  • /e2e-tests/README.md - End-to-end testing README
  • /load-tests/README.md - Load testing guide
  • /plugins/README.md - Plugins overview
  • /plugins/headlamp-plugin/README.md - Plugin development tools
  • /plugins/pluginctl/README.md - Plugin control utility
  • /backend/pkg/telemetry/README.md - Telemetry module
  • /docker-extension/README.md - Docker extension
  • /charts/headlamp/README.md - Helm chart
  • /backstage-test/README.md - Backstage integration test
  • /tools/i18n/README.md - Internationalization tools
  • /eslint-config/README.md - ESLint configuration
  • /frontend/src/i18n/README.md - Frontend i18n
  • /app/e2e-tests/README.md - Desktop app e2e tests
  • Plugin examples: /plugins/examples/*/README.md (multiple examples)

Documentation files:

  • /docs/development/index.md - Main development guide with build/run commands
  • /docs/development/frontend.md - Frontend development guide
  • /docs/development/backend.md - Backend development guide with testing commands
  • /docs/development/app.md - Desktop app development guide
  • /docs/development/testing.md - Load testing guide
  • /docs/development/architecture.md - Architecture documentation
  • /docs/development/plugins/index.md - Plugin system overview
  • /docs/development/plugins/building.md - Plugin building guide
  • /docs/development/plugins/getting-started.md - Plugin getting started
  • /docs/development/plugins/publishing.md - Plugin publishing guide
  • /docs/development/i18n/index.md - Internationalization guide
  • /docs/development/release-guide.md - Release process
  • /docs/installation/index.mdx - Installation instructions
  • /docs/installation/in-cluster/index.md - In-cluster deployment
  • /docs/installation/desktop/index.mdx - Desktop installation
  • /docs/contributing.md - Contribution guidelines
  • /docs/faq.md - Frequently asked questions
  • /docs/platforms.md - Tested platforms list

Build/Config files:

  • /package.json - Root package with all npm scripts and Node.js version (>=20.11.1)
  • /backend/go.mod - Go version (1.24.13)
  • /CONTRIBUTING.md - Contributing guidelines
  • /OWNERS - Code reviewers and approvers

Agent persona and scope

  • @dev-agent — pragmatic, conservative, test-first, risk-averse.
  • Scope: propose, validate, and prepare code/docs patches; run local build/test commands; create PR drafts.
  • Not allowed: push images/releases, modify CI or infra, or merge without human approval.

Explicit non-goals

should NOT unless explicitly requested or strictly necessary for the change

  • Propose refactors without a clear bug, performance, or maintenance justification
  • Change public APIs without explicit request
  • Reformat unrelated code
  • Rename files or symbols for stylistic reasons
  • Introduce new dependencies unless required to fix a bug or implement a requested feature and an existing dependency can not be used

Tech stack and environment

  • Languages: TypeScript (frontend), Go (backend).
  • Runtimes/tools:
    • Node.js >=20.11.1 (specified in /package.json engines field)
    • npm >=10.0.0 (specified in /package.json engines field)
    • Go 1.24.13 (specified in /backend/go.mod)
  • Reproduce locally: Use commands from /package.json scripts section and documentation files listed above.

Repo map

  • frontend/ — UI code (TypeScript/React); see /frontend/README.md and /docs/development/frontend.md for build/run/test commands.
  • backend/ — Go server and API; see /backend/README.md and /docs/development/backend.md for server commands.
  • docs/ — all developer and user docs; reference specific files under docs/ for workflows.
  • plugins/ — plugin system and examples; see /plugins/README.md and /docs/development/plugins/.
  • app/ — desktop application (Electron); see /app/README.md and /docs/development/app.md for build/run/test commands.
  • CI & infra: .github/workflows/, Dockerfiles (/Dockerfile, /Dockerfile.plugins), Kubernetes manifests (kubernetes-headlamp*.yaml), Helm charts (/charts/) — treat as manual-review-only.

Primary entry points (exact commands from repository)

Build commands (from /package.json and /docs/development/index.md):

  • Build everything: npm run build (builds backend and frontend - from /package.json)
  • Build frontend only: npm run frontend:build (from /package.json, documented in /docs/development/frontend.md)
  • Build backend only: npm run backend:build (from /package.json, documented in /docs/development/backend.md)
  • Build desktop app: npm run app:build (from /package.json)

Run commands (from /package.json and /docs/development/index.md):

  • Run both backend and frontend: npm start (from /package.json, documented in /docs/development/index.md)
  • Run backend only: npm run backend:start (from /package.json, documented in /docs/development/backend.md)
  • Run frontend only: npm run frontend:start (from /package.json, documented in /docs/development/frontend.md)
  • Run desktop app: npm run app:start (from /package.json)

Test commands (from /package.json and /docs/development/backend.md):

  • Run all tests: npm test (from /package.json)
  • Backend tests: npm run backend:test (from /package.json, documented in /docs/development/backend.md)
  • Backend coverage: npm run backend:coverage (from /package.json, documented in /docs/development/backend.md)
  • Backend coverage HTML: npm run backend:coverage:html (from /package.json, documented in /docs/development/backend.md)
  • Frontend tests: npm run frontend:test (from /package.json)
  • App unit tests: npm run app:test:unit (from /package.json)
  • App e2e tests: npm run app:test:e2e (from /package.json)

Lint commands (from /package.json and /docs/development/backend.md):

  • Lint all: npm run lint (from /package.json)
  • Lint backend: npm run backend:lint (from /package.json, documented in /docs/development/backend.md)
  • Lint backend (fix): npm run backend:lint:fix (from /package.json, documented in /docs/development/backend.md)
  • Lint frontend: npm run frontend:lint (from /package.json)
  • Lint frontend (fix): npm run frontend:lint:fix (from /package.json)
  • Lint app: npm run app:lint (from /package.json, documented in /docs/development/app.md)
  • Lint app (fix): npm run app:lint:fix (from /package.json, documented in /docs/development/app.md)

Format commands (from /package.json and /docs/development/backend.md):

  • Format backend: npm run backend:format (from /package.json, documented in /docs/development/backend.md)
  • Format and lint frontend: npm run frontend:lint:fix (from /package.json)
  • Format app: npm run app:format (from /package.json, documented in /docs/development/app.md)

Documentation generation (from /package.json and /docs/development/frontend.md):

  • Generate API docs: npm run docs (from /package.json, documented in /docs/development/frontend.md)

Storybook (from /package.json and /docs/development/frontend.md):

  • Run Storybook: npm run frontend:storybook (from /package.json, documented in /docs/development/frontend.md)
  • Build Storybook: npm run frontend:build:storybook (from /package.json)

Allowed commands and CI interactions

  • Permitted to suggest/run locally:
    • All npm scripts from /package.json
    • Go commands: go build, go test, go fmt (documented in /docs/development/backend.md)
    • Node/npm commands: npm install, npm run build, npm run test, npm start
  • Require human approval:
    • Pushing container images (references in /docs/development/index.md)
    • Publishing releases (process documented in /docs/development/release-guide.md)
    • Modifying .github/workflows/*
    • Changing Dockerfile or /Dockerfile.plugins
    • Altering Kubernetes manifests (kubernetes-headlamp*.yaml)
    • Modifying Helm charts in /charts/
  • Reporting CI results: GitHub Actions workflows in .github/workflows/ - summarize failing steps, include logs, recommend fixes with local reproduction commands.

Change rules and safety constraints

  • Manual-review-only:
    • .github/workflows/* - CI workflows
    • Dockerfile, Dockerfile.plugins - container definitions
    • charts/ - Helm charts
    • kubernetes-*.yaml - Kubernetes manifests
    • SECURITY.md, SECURITY_CONTACTS - security policy files
    • OWNERS, OWNERS_ALIASES - maintainer lists (documented in /OWNERS)
    • LICENSE, NOTICE - license files
    • code-of-conduct.md - code of conduct
  • Pre-change checks:
    • Run npm run lint (from /package.json)
    • Run npm test (from /package.json)
    • Run npm run backend:test for backend changes (from /package.json)
    • Run npm run frontend:test for frontend changes (from /package.json)
    • Run npm run backend:format for backend code formatting (from /package.json)
    • Run npm run frontend:lint:fix for frontend code formatting (from /package.json)
    • Run TypeScript compiler: npm run frontend:tsc (from /package.json) or npm run app:tsc (from /package.json)
    • Run e2e tests for UI changes: npm run app:test:e2e (from /package.json)
  • Dependency updates:
    • Run full test suite: npm test
    • Tag maintainers from /OWNERS (headlamp-maintainers, headlamp-reviewers)
    • Do not bump major versions without approval
  • Licenses/copyright:
    • Do not alter /LICENSE or /NOTICE files
    • Do not modify copyright headers

Best practices and coding guidelines

  • Reduce solution size:
    • Make minimal, surgical changes - modify as few lines as possible to achieve the goal
    • Prefer focused, single-purpose changes over large refactors
    • Break down complex changes into smaller, reviewable increments
    • Remove unnecessary code, dependencies, or complexity when fixing issues
  • Testing best practices:
    • Avoid using mocks in tests if possible - prefer testing with real implementations
    • Use integration tests over unit tests when it improves test reliability
    • Only mock external dependencies (APIs, databases, file systems) when necessary
    • Write tests that validate actual behavior, not implementation details
  • Consider best practices for the type of change:
    • Bug fixes: Add regression tests, verify the fix doesn't break existing functionality
    • New features: Follow existing patterns, add comprehensive tests, update documentation
    • Refactoring: Ensure behavior remains unchanged, validate with existing tests
    • Performance: Add benchmarks, measure before and after, document improvements
    • Security: Follow secure coding practices, validate inputs, avoid common vulnerabilities
    • Documentation: Keep it concise, accurate, and consistent with code examples
  • Frontend-specific guidelines:
    • Screenshots: Always include screenshots for UI changes in PRs to show visual impact
    • React components: Add Storybook stories with error and loading states for new components (use npm run frontend:storybook)
    • Formatting: Run npm run frontend:lint:fix to format code before committing
    • End-to-end tests: For significant UI changes, consider adding or updating e2e tests (npm run app:test:e2e)

Examples and templates

Example 1: Small frontend code fix

  • Files to change: frontend/src/components/Example.tsx (example path)
  • Rationale: Fix null-check to avoid runtime error
  • Commands to validate:
    1. npm run frontend:install (from /package.json)
    2. npm run frontend:lint:fix (from /package.json) - format code
    3. npm run frontend:lint (from /package.json)
    4. npm run frontend:test (from /package.json)
    5. npm run frontend:tsc (from /package.json)
    6. npm run app:test:e2e (from /package.json) - if UI changes
  • Additional requirements:
    • Include screenshots of any UI changes in the PR
    • If adding/modifying React components, add Storybook stories with error and loading states

Example 2: Backend code fix

  • Files to change: backend/pkg/example/handler.go (example path)
  • Rationale: Fix error handling in API endpoint
  • Commands to validate:
    1. npm run backend:build (from /package.json, documented in /docs/development/backend.md)
    2. npm run backend:lint (from /package.json, documented in /docs/development/backend.md)
    3. npm run backend:test (from /package.json, documented in /docs/development/backend.md)
    4. npm run backend:format (from /package.json, documented in /docs/development/backend.md)

Example 3: Desktop app code fix

  • Files to change: app/electron/example.ts (example path)
  • Rationale: Fix window management issue in Electron app
  • Commands to validate:
    1. npm run app:install (from /package.json)
    2. npm run app:lint:fix (from /package.json, documented in /docs/development/app.md)
    3. npm run app:format (from /package.json, documented in /docs/development/app.md)
    4. npm run app:lint (from /package.json, documented in /docs/development/app.md)
    5. npm run app:tsc (from /package.json, documented in /docs/development/app.md)
    6. npm run app:test (from /package.json, documented in /docs/development/app.md)

Example 4: Documentation update

  • Files to change: docs/development/index.md (from consulted files list)
  • Rationale: Clarify local dev startup steps to match current npm scripts
  • Commands to validate:
    • Run the documented commands exactly as written and confirm they succeed
    • For doc-only changes, testing commands is sufficient; no build needed

Example 5: Plugin development

  • Files to change: Plugin code in /plugins/examples/ directory
  • Rationale: Add new plugin example
  • Commands to validate:
    1. cd plugins/headlamp-plugin && npm install (from /package.json)
    2. Follow plugin testing commands in /docs/development/plugins/building.md

PR description & commit message format

Reference: /docs/contributing.md and /.github/pull_request_template.md

Commit message format (from /docs/contributing.md):

  • Format: <area>: <description of changes>
  • Examples:
    • frontend: HomeButton: Fix so it navigates to home
    • backend: config: Add enable-dynamic-clusters flag
  • Guidelines:
    • Use atomic commits - keep each commit focused on a single change
    • Keep commit titles under 72 characters (soft requirement)
    • Commit messages should explain the intention and why something is done
    • Commit titles should be meaningful and describe what the commit does
    • Use git rebase to squash and order commits for easy review
    • Do not write "Fixes #NN" issue number in the commit message

PR description template (from /.github/pull_request_template.md):

  • Summary: Brief description of what the change does
  • Related Issue: Link via Fixes #ISSUE_NUMBER if applicable
  • Changes: List of added/updated/fixed components
  • Steps to Test: Numbered steps to verify the changes
  • Screenshots: Include for UI changes
  • Notes for the Reviewer: Any relevant context or areas to focus on

PR guidelines (from /docs/contributing.md):

  • Run tests: npm run frontend:test, npm run backend:test
  • Run linters: npm run frontend:lint, npm run backend:lint
  • Summarize changes and explain why they are needed
  • Provide steps to test the changes
  • Link to related issue via Fixes #ISSUE_NUMBER

Agent output checklist (must pass before creating patch/PR)

  • Summary: one-line intent and short rationale
  • Sources: list consulted README/docs file paths with specific line numbers
  • Files changed: explicit file list with rationale for each
  • Diff/patch: minimal unified diff showing only necessary changes
  • Tests:
    • List tests added/updated
    • Exact commands to run them (from /package.json)
    • Test results showing pass status
  • Local validation:
    • Exact commands to reproduce build/test results
    • Output showing successful execution
    • For frontend: verify in browser at localhost:3000 (from /docs/development/frontend.md)
    • For backend: verify server starts successfully (from /docs/development/backend.md)
  • CI expectations:
    • Which workflows in .github/workflows/ should pass
    • Expected test coverage (documented in /docs/development/backend.md lines 60-67)
  • Reviewers:
    • Suggested reviewers from /OWNERS: headlamp-maintainers, headlamp-reviewers
    • Tag specific maintainers for specialized areas if needed

Appendix

All consulted README.md files:

  1. /README.md - Main project README with overview, features, quickstart
  2. /frontend/README.md - Frontend module pointer to docs
  3. /backend/README.md - Backend quickstart with build/run commands
  4. /app/README.md - Desktop app information
  5. /e2e-tests/README.md - End-to-end testing guide
  6. /load-tests/README.md - Load testing with KWOK
  7. /plugins/README.md - Plugins overview
  8. /plugins/headlamp-plugin/README.md - Plugin development tools
  9. /plugins/headlamp-plugin/template/README.md - Plugin template
  10. /plugins/pluginctl/README.md - Plugin control utility
  11. /backend/pkg/telemetry/README.md - Telemetry module
  12. /docker-extension/README.md - Docker extension
  13. /charts/headlamp/README.md - Helm chart documentation
  14. /backstage-test/README.md - Backstage integration
  15. /tools/i18n/README.md - Internationalization tools
  16. /eslint-config/README.md - ESLint configuration
  17. /frontend/src/i18n/README.md - Frontend i18n
  18. /app/e2e-tests/README.md - Desktop app e2e tests
  19. Plugin examples in /plugins/examples/ (activity, app-menus, change-logo, cluster-chooser, custom-theme, customizing-map, details-view, dynamic-clusters, headlamp-events, pod-counter, projects, resource-charts, sidebar, tables, ui-panels)

Key documentation files:

  1. /docs/development/index.md - Primary development guide (lines 1-310)
  2. /docs/development/frontend.md - Frontend dev guide (lines 1-82)
  3. /docs/development/backend.md - Backend dev guide (lines 1-69)
  4. /docs/development/app.md - Desktop app dev guide
  5. /docs/development/testing.md - Testing guide (lines 1-83)
  6. /docs/development/architecture.md - System architecture
  7. /docs/development/plugins/index.md - Plugin system
  8. /docs/development/plugins/building.md - Building plugins
  9. /docs/development/plugins/getting-started.md - Plugin quickstart
  10. /docs/development/plugins/publishing.md - Publishing plugins
  11. /docs/development/plugins/common-patterns.md - Plugin patterns
  12. /docs/development/i18n/index.md - Internationalization
  13. /docs/development/release-guide.md - Release process
  14. /docs/contributing.md - Contribution guidelines
  15. /docs/faq.md - FAQ
  16. /docs/platforms.md - Tested platforms

Versioning guidance:

  • Follow semantic versioning (documented in /docs/development/release-guide.md)
  • App version defined in /app/package.json
  • Docker image version from git tags
  • Request maintainer approval for version bumps and releases
  • Release process documented in /docs/development/release-guide.md

Final instructions for the agent (implementation complete)

  1. ✅ Searched the repository for all README.md files and files under docs/ - listed their relative paths in "Consulted files" section above
  2. ✅ Extracted exact commands and versions from package.json, go.mod, and documentation - replaced all placeholders with exact text and file path citations
  3. ✅ Commands are ready for validation - all commands listed can be run locally following the exact syntax provided
  4. ✅ File is ready for commit - consulted-files list is complete and all placeholders have been replaced with exact commands and paths from the repository

Version Information:

  • Node.js: >=20.11.1 (from /package.json)
  • npm: >=10.0.0 (from /package.json)
  • Go: 1.24.13 (from /backend/go.mod)

Key Command Sources:

  • Build/test commands: /package.json
  • Development workflow: /docs/development/index.md
  • Backend specifics: /docs/development/backend.md
  • Frontend specifics: /docs/development/frontend.md