72 lines
5.0 KiB
Markdown
72 lines
5.0 KiB
Markdown
# EVOLV Agent Guide (AGENTS.md)
|
|
|
|
## Project Summary
|
|
EVOLV is a modular Node-RED package bundling multiple custom control/automation nodes (primarily under `nodes/`) for wastewater/process applications.
|
|
|
|
## Repository Layout
|
|
- `package.json`: Root package metadata + `node-red.nodes` map that tells Node-RED which node entrypoints to load.
|
|
- `nodes/<nodeName>/`: A Node-RED node module (often a git submodule).
|
|
- `<nodeName>.js`: Node-RED runtime entry (registers the node and exposes admin endpoints).
|
|
- `<nodeName>.html`: Node-RED editor UI definition for the node.
|
|
- `src/`: Node implementation classes and logic.
|
|
- `nodes/generalFunctions/`: Shared utilities used by most nodes (logger/config/menu helpers, etc).
|
|
- `node_modules/`: Local install output; do not edit.
|
|
|
|
## Agent Knowledge Base
|
|
- `.agents/`: Root directory for repository-specific agent definitions and knowledge base content (non-runtime/support assets, not Node-RED production code).
|
|
- `.agents/skills/`: EVOLV specialist skills (domain instructions, workflows, and orchestrator logic).
|
|
- When tasks involve domain reasoning or specialist routing, prefer `.agents/skills/*/SKILL.md` as the primary in-repo source of guidance.
|
|
|
|
## Agent Invocation Policy
|
|
- Default: always invoke orchestrator first via `.agents/skills/evolv-orchestrator/SKILL.md`.
|
|
- Orchestrator decides specialist selection, task decomposition, execution order, and integration checks.
|
|
- Direct specialist invocation is allowed only when all are true:
|
|
- task is clearly single-domain
|
|
- expected impact is local (single node/module concern)
|
|
- no cross-node contract/topic/schema/security implications
|
|
- If uncertainty exists, fall back to orchestrator.
|
|
|
|
## Agent Routing Table
|
|
Use this table after orchestrator triage, or for approved single-domain direct calls.
|
|
|
|
| Task Pattern | Primary Skill | Path |
|
|
|---|---|---|
|
|
| Multi-domain feature, ambiguous ownership, or cross-node integration planning | Orchestrator | `.agents/skills/evolv-orchestrator/SKILL.md` |
|
|
| Node-RED editor HTML, form defaults, menu/config endpoints, UI/runtime config parity | Frontend + Node-RED expert | `.agents/skills/evolv-frontend-node-red/SKILL.md` |
|
|
| Rotating machine behavior, pump curves, operating envelopes, mechanical plausibility | Mechanical rotating equipment engineer | `.agents/skills/evolv-mechanical-rotating-equipment/SKILL.md` |
|
|
| Sensor/measurement semantics, units, validation, quality flags, measurement assets | Instrumentation engineer | `.agents/skills/evolv-instrumentation-assets/SKILL.md` |
|
|
| System-wide control architecture, sequencing, mode transitions, parent-child topic contracts | System/process control engineer | `.agents/skills/evolv-process-systems-control/SKILL.md` |
|
|
| InfluxDB telemetry model, tags/fields, retention, Grafana query compatibility | Database/Influx architect | `.agents/skills/evolv-database-influx-architecture/SKILL.md` |
|
|
| OT/IT threat review, secure defaults, endpoint hardening, control-message safety | OT/IT security engineer | `.agents/skills/evolv-ot-it-security/SKILL.md` |
|
|
| Code quality review, regression risk, test gaps, technical debt prioritization | Quality/debt engineer | `.agents/skills/evolv-quality-technical-debt/SKILL.md` |
|
|
|
|
## Shared Engineering Baseline
|
|
- Dependencies: prefer `npm ci` at repo root (uses `package-lock.json`). Avoid changing `package.json` without updating the lockfile.
|
|
- Node-RED integration (local dev):
|
|
- Ensure Node-RED can see this repo as a nodes directory (e.g., `settings.js` with `nodesDir: './nodes'`) or copy/link the repo into `~/.node-red/nodes/`.
|
|
- Restart Node-RED after changes so nodes reload.
|
|
|
|
## Submodules
|
|
Many `nodes/*` directories are git submodules.
|
|
- Prefer making changes in the appropriate submodule directory and keep edits scoped to that node.
|
|
- Avoid editing `nodes/*/.git` files directly.
|
|
- If the task is “update a node submodule”, update the submodule pointer in this repo rather than copying code across nodes.
|
|
|
|
## Safety / Hygiene
|
|
- Do not modify generated or vendored content unless explicitly requested:
|
|
- `node_modules/`
|
|
- `EVOLV-*.tgz`
|
|
- Exclude `node_modules/` when searching or refactoring (`rg --glob '!**/node_modules/**'`).
|
|
- Network access may be restricted in automated runs; avoid installing from git/NPM without approval.
|
|
|
|
## Validation
|
|
No centralized test runner is configured at the root.
|
|
- Prefer targeted smoke checks: Node-RED starts, nodes load, node editor renders, and admin endpoints respond.
|
|
- If a node has its own `package.json` scripts, run them from that node directory only when they actually execute in your environment.
|
|
|
|
## Skill Ownership Of Detailed Standards
|
|
- Node-RED structure, file responsibilities, admin endpoints, and new-node checklist: `.agents/skills/evolv-frontend-node-red/SKILL.md`
|
|
- Message/port conventions and topic contract behavior: `.agents/skills/evolv-process-systems-control/SKILL.md`
|
|
- Test policy depth and quality gates: `.agents/skills/evolv-quality-technical-debt/SKILL.md`
|
|
- Multi-skill decomposition/integration and interview protocol: `.agents/skills/evolv-orchestrator/SKILL.md`
|