Skip to content

AGENTS.md

Latest commit

 

History

History
60 lines (48 loc) · 3.01 KB

AGENTS.md

File metadata and controls

60 lines (48 loc) · 3.01 KB
Raw

Agent Map

This file is a short map for coding agents. Keep detailed guidance in docs/ and keep this file small enough to fit into every task context.

First Reads

  • DEVELOPMENT.md - project commands, coding rules, test rules, and PR shape.
  • ARCHITECTURE.md - package boundaries, data ownership, and runtime flow.
  • docs/harness/README.md - how this repository is prepared for agent work.
  • docs/harness/validation.md - which checks to run for each change type.
  • docs/harness/worktree-runbook.md - isolated local dev and test setup.
  • docs/harness/pr-review.md - self-review checklist before pushing.
  • docs/harness/server-module-boundaries.md - target backend modules, ownership, and dependency rules.
  • docs/harness/jev-integrations.md - required switches, frontend configuration and registration for JEV consumers.
  • docs/harness/frontend-ui.md - required theme surfaces, UI exceptions and automatic checks.

Common Commands

npm ci --ignore-scripts
npm run harness:check
npm run test
npm run test:e2e
npm run build

Use the smallest relevant check while iterating. Before a broad PR, run npm run harness:check, npm run test:coverage, npm run test:e2e, and npm run build.

Code Ownership Map

  • packages/client/src - Vue 3 client, stores, routes, i18n, API helpers.
  • packages/server/src - Koa API, Socket.IO, persistence, Hermes integration.
  • packages/ekko-agent - canonical Ekko runtime, profiles, providers, tools, memory, skills, and package docs.
  • packages/desktop - Electron wrapper, bundled Python/Hermes runtime, release artifacts.
  • packages/mcu - ESP32-C3 and ESP32-S3 firmware, board projects, and release images.
  • tests/client, tests/server, tests/shared - Vitest coverage.
  • tests/e2e - Playwright browser coverage with mocked backend services.
  • .github/workflows - CI, release, Docker, and desktop packaging automation.

Hard Rules

  • Keep routes thin: put request handling in controllers and reusable behavior in services.
  • Put new server code under modules/studio, modules/hermes, modules/ekko, or modules/coding-agents; compose modules only from bootstrap.
  • Keep Web UI state under HERMES_WEB_UI_HOME or HERMES_WEBUI_STATE_DIR.
  • Keep Hermes Agent state separate from Web UI state.
  • Register local API routes before proxy catch-all routes.
  • Use structured APIs and argument arrays instead of shell string construction.
  • Add user-facing strings to every locale file.
  • Register every JEV business integration with its own switch and frontend configuration entry; explicitly register any enabled Studio default, keep standalone defaults off, and run npm run harness:check.
  • Do not mix unrelated refactors into a bug fix.
  • New UI must follow the theme surface contract in docs/harness/frontend-ui.md; do not expand the legacy style baseline to bypass checks.

When The Agent Gets Stuck

Improve the harness instead of repeating the same prompt. Add missing docs, tests, logs, scripts, or CI checks so the next agent can see and verify the constraint directly.