48f790d123
Some checks failed
CI / lint-and-test (push) Has been cancelled
Move content to correct locations: - AGENTS.md → .agents/AGENTS.md (with orchestrator reference update) - third_party/docs/ (8 reference docs) → wiki/concepts/ - manuals/ (12 Node-RED docs) → wiki/manuals/ Delete 23 unreferenced one-off scripts from scripts/ (keeping 5 active). Delete stale Dockerfile.e2e, docker-compose.e2e.yml, test/e2e/. Remove empty third_party/ directory. Root is now: README, CLAUDE.md, LICENSE, package.json, Makefile, Dockerfile, docker-compose.yml, docker/, scripts/ (5), nodes/, wiki/, plus dotfiles (.agents, .claude, .gitea). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
168 lines
12 KiB
Markdown
168 lines
12 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.
|
|
- `test/`: Node-level tests (`basic/`, `integration/`, `edge/`, optional `helpers/`).
|
|
- `examples/`: Import-ready Node-RED example flows (`basic.flow.json`, `integration.flow.json`, `edge.flow.json`) and `examples/README.md`.
|
|
- `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.
|
|
- `team` keyword policy:
|
|
- When the user says `team`, treat the request as orchestrator-led multi-specialist work.
|
|
- The orchestrator must choose the best-fit specialists for the task (minimum set that covers all required domains).
|
|
- Specialists must perform an internal alignment pass before any user-facing conclusion:
|
|
- share assumptions
|
|
- reconcile conflicts/tradeoffs
|
|
- agree on a single integrated recommendation (or document explicit dissent)
|
|
- Return one consolidated conclusion with:
|
|
- recommended plan
|
|
- risks and tradeoffs
|
|
- unresolved disagreements (if any)
|
|
- For any change inside `nodes/*` that affects Node-RED runtime/editor behavior, always load `.agents/skills/evolv-frontend-node-red/SKILL.md` before editing.
|
|
- For dashboard graphics/charts work, also load `manuals/node-red/flowfuse-ui-chart-manual.md` and `manuals/node-red/flowfuse-dashboard-layout-manual.md`.
|
|
- FlowFuse `ui-chart` baseline for EVOLV: use series by `msg.topic` (`category: "topic"`, `categoryType: "msg"`). Avoid leaving `category` blank.
|
|
- 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.
|
|
|
|
## Harness Engineering Adaptation (EVOLV)
|
|
Treat the repository as the operating map. Avoid broad static instructions that are not anchored to concrete files, interfaces, or tests.
|
|
|
|
Execution loop for agent work:
|
|
1. Build an impact map from the current repo state (files, contracts, tests, and runtime touchpoints).
|
|
2. Define non-negotiable invariants before editing (topic contracts, safety limits, schema/API compatibility, security posture).
|
|
3. Implement minimum-scoped changes with explicit acceptance criteria.
|
|
4. Verify with local evidence (tests, smoke checks, static checks, or endpoint/output validation).
|
|
5. Capture durable learnings by updating the relevant `SKILL.md` and decision logs.
|
|
|
|
Progressive disclosure policy:
|
|
- Load only the primary skill file first.
|
|
- Open referenced files/manuals only when needed by the active task.
|
|
- Prefer small, auditable diffs over large speculative rewrites.
|
|
|
|
Decision interview policy (owner-controlled gates):
|
|
- Interview the user before finalizing changes that alter any of:
|
|
- Released `msg.topic` contracts or payload schemas
|
|
- Safety/availability envelopes or fail-safe behavior
|
|
- Security defaults, endpoint exposure, or trust boundaries
|
|
- Influx retention/backfill semantics or dashboard query contracts
|
|
- Dependency strategy with operational rollout risk
|
|
- Ask at most 3 questions per batch and proceed immediately after answers.
|
|
|
|
Current owner-approved defaults (February 16, 2026):
|
|
- Compatibility posture: `controlled`
|
|
- Breaking `msg.topic`/payload changes are allowed only with explicit migration/deprecation notes.
|
|
- Safety posture: `availability-first`
|
|
- Prefer continuity of operation with bounded safeguards over early protective trips.
|
|
- Decision logging: `required for all decision-gate changes`
|
|
- Every decision-gate outcome must be recorded in `.agents/decisions/`.
|
|
|
|
Decision log:
|
|
- Record important decisions in `.agents/decisions/DECISION-YYYYMMDD-<slug>.md`.
|
|
- Include context, options, decision, consequences, and rollback/migration notes.
|
|
|
|
Functional/architectural improvements backlog:
|
|
- Track deferred functional/runtime/architecture improvements in `.agents/improvements/IMPROVEMENTS_BACKLOG.md`.
|
|
- If an improvement is discovered during non-functional work, add it to this backlog before closing the task.
|
|
- Keep the top priority review list in `.agents/improvements/TOP10_PRODUCTION_PRIORITIES_YYYY-MM-DD.md` when requested.
|
|
- When an item is implemented after review, remove it from `.agents/improvements/IMPROVEMENTS_BACKLOG.md` and note the fix in session notes/PR context.
|
|
|
|
## 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` |
|
|
| Biological process modeling, ASM kinetics, oxygen demand, sludge/retention assumptions | Biological process engineer | `.agents/skills/evolv-biological-process-engineering/SKILL.md` |
|
|
| InfluxDB telemetry model, tags/fields, retention, Grafana query compatibility | Database/Influx architect | `.agents/skills/evolv-database-influx-architecture/SKILL.md` |
|
|
| Sensor/analyzer product behavior, warmup/drift/fouling, device quality semantics | Measurement product specialist | `.agents/skills/evolv-measurement-product-specialist/SKILL.md` |
|
|
| OT edge protocol integration (OPC UA/PLC/fieldbus mapping), reconnect and handshake behavior | OT edge PLC integration specialist | `.agents/skills/evolv-ot-edge-plc-integration/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` |
|
|
| Alarm strategy, interlocks, permissives, trip/reset behavior | Alarms/interlocks engineer | `.agents/skills/evolv-alarms-interlocks-permissives/SKILL.md` |
|
|
| Hydraulics and cross-node mass/volume balance plausibility | Process hydraulics engineer | `.agents/skills/evolv-process-hydraulics-mass-balance/SKILL.md` |
|
|
| Telemetry KPI contract design, dashboard/query compatibility, operator diagnostics | Telemetry/analytics specialist | `.agents/skills/evolv-telemetry-analytics-dashboards/SKILL.md` |
|
|
| Wastewater compliance/reporting impact and auditability | Regulatory compliance specialist | `.agents/skills/evolv-regulatory-compliance-wastewater/SKILL.md` |
|
|
| FAT/SAT planning, commissioning evidence, rollout readiness gates | Commissioning and validation specialist | `.agents/skills/evolv-commissioning-validation/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.
|
|
- Node-RED Function node scripts: avoid declaring local variables named `flow`, `global`, `context`, `env`, `RED`, or `node` (these are runtime-provided objects and can trigger redeclare/runtime errors).
|
|
- Use explicit alternatives like `flowValue`, `flowRate`, or `flowMetric` for process data variables.
|
|
|
|
## 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.
|
|
|
|
## Node Artifact Standard (Required For All Nodes)
|
|
Each node under `nodes/<nodeName>/` must include:
|
|
- Runtime/editor implementation:
|
|
- `<nodeName>.js`
|
|
- `<nodeName>.html`
|
|
- `src/`
|
|
- Test structure:
|
|
- `test/basic/*.test.js`
|
|
- `test/integration/*.test.js`
|
|
- `test/edge/*.test.js`
|
|
- Example flow package:
|
|
- `examples/README.md`
|
|
- `examples/basic.flow.json`
|
|
- `examples/integration.flow.json`
|
|
- `examples/edge.flow.json`
|
|
|
|
Enforcement:
|
|
- Do not close node-level work items without maintaining both test and examples structure.
|
|
- If legacy nodes are missing these artifacts, treat as technical debt and bring to parity during related work.
|
|
|
|
## 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`
|
|
- Biological/kinetic modeling assumptions and plausibility constraints: `.agents/skills/evolv-biological-process-engineering/SKILL.md`
|
|
- Sensor/analyzer product behavior and quality-state semantics: `.agents/skills/evolv-measurement-product-specialist/SKILL.md`
|
|
- PLC/OPC UA edge protocol mapping and reconnect semantics: `.agents/skills/evolv-ot-edge-plc-integration/SKILL.md`
|
|
- Alarm/interlock/permissive design standards: `.agents/skills/evolv-alarms-interlocks-permissives/SKILL.md`
|
|
- Hydraulics and mass-balance consistency rules: `.agents/skills/evolv-process-hydraulics-mass-balance/SKILL.md`
|
|
- Telemetry KPI and dashboard/query contract standards: `.agents/skills/evolv-telemetry-analytics-dashboards/SKILL.md`
|
|
- Wastewater compliance and auditability constraints: `.agents/skills/evolv-regulatory-compliance-wastewater/SKILL.md`
|
|
- Commissioning/FAT/SAT validation standards: `.agents/skills/evolv-commissioning-validation/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`
|