-`.claude/skills/`: **EVOLV domain skills** — Claude-Code-native, auto-discovered, invokable via the `Skill` tool. Use for domain reasoning (rotating equipment, biology, telemetry, security, …).
-`.claude/agents/`: **Claude Code subagents** — auto-discovered, invokable via the `Agent` tool with `subagent_type:`. Use for spawnable independent work.
-`.agents/`: Holds this `AGENTS.md` routing table, function-anchors (per-node behavioural contracts in `.agents/function-anchors/`), and the improvements backlog (`.agents/improvements/`). **No skills live here** — the skill surface was migrated to `.claude/skills/` in 2026-05.
### Skills vs Subagents — when to use which
| Surface | Path | Loaded by | When to use |
|---|---|---|---|
| Claude Code skills | `.claude/skills/*/SKILL.md` | Auto-discovered; invokable via the `Skill` tool | Domain knowledge / workflow recipes the active agent should *read* before deciding |
| Claude Code subagents | `.claude/agents/*.md` | Auto-discovered; invokable via the `Agent` tool | Spawnable independent work (audits, parallel exploration, focused tasks) |
The orchestrator lives only as a subagent (`.claude/agents/evolv-orchestrator.md`); there is no orchestrator skill.
- For any change inside `nodes/*` that affects Node-RED runtime/editor behavior, always load `.claude/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.
- Decision logging: record load-bearing decisions in the commit message and PR description. Live open items belong in `.claude/refactor/OPEN_QUESTIONS.md`. Superseded plan artifacts live in `.agents/improvements/Archive/` and `.claude/refactor/Archive/`.
- 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.
- 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.
