-`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`.
- 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.
- 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.
- 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.
