Migrate to new Gitea instance (gitea.wbd-rd.nl)
- Update all submodule URLs from gitea.centraal.wbd-rd.nl to gitea.wbd-rd.nl - Add settler as proper submodule in .gitmodules - Add agent skills, function anchors, decisions, and improvements - Add Docker configuration and scripts - Add manuals and third_party docs - Update .gitignore with secrets and build artifacts - Remove stale .tgz build artifact Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
znetsixe
96
AGENTS.md
96
AGENTS.md
@@ -9,6 +9,8 @@ EVOLV is a modular Node-RED package bundling multiple custom control/automation
|
||||
- `<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.
|
||||
|
||||
@@ -20,12 +22,68 @@ EVOLV is a modular Node-RED package bundling multiple custom control/automation
|
||||
## 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.
|
||||
|
||||
@@ -36,8 +94,16 @@ Use this table after orchestrator triage, or for approved single-domain direct c
|
||||
| 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
|
||||
@@ -58,14 +124,44 @@ Many `nodes/*` directories are git submodules.
|
||||
- `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`
|
||||
|
||||
Reference in New Issue
Block a user