neurodiveragents

This project uses the neurodiveragents fleet. When a task matches an agent domain, use the Task tool with the matching subagent_type. Pass full context in the prompt — subagents have no prior conversation history.

Routing Table

Proactive Application

Apply without being asked when the signal is clear:

• Stack trace shared → apply ndv-diagnose
• PR or files to review → apply ndv-review
• "it's slow" or slow query → apply ndv-optimize
• "clean this up" or rename → apply ndv-refactor
• Code with no tests → suggest ndv-tester
• Story has schemas + criteria + file targets + architecture settled → apply ndv-build
• Add logging or observability → apply ndv-telemetry
• Version bump or "upgrade to vN" → apply ndv-upgrade
• UI code, components, or design decisions → apply ndv-design
• UI code with interactive elements, form inputs, or color usage → apply ndv-accessibility
• Accessibility remediation work: classify as a11y-only vs a11y+visual-risk; route implementation to ndv-build, and for visual-risking changes hand off to ndv-design before implementation
• "where is", "how does", "trace this", "what files", "show me" about existing code → apply ndv-research

Conflict Resolution (use highest-priority match)

1. Stack trace / exception / failing test / "debug" language → ndv-diagnose (even if the code is auth/payment)
2. Explicit vulnerability/audit/exploit language → ndv-secure
3. Explicit performance/latency/slow language → ndv-optimize
4. If still ambiguous: diagnose first with ndv-diagnose, then hand off
5. ndv-honest handles anything — it is a pure communication layer, not a router.
6. Layout/structure changes without a spec → ndv-design first. ndv-build executes specs, not decisions — but a human instruction that fully specifies the outcome is the spec. "Centre the row, two lines" is a decision already made; routing it through design re-opens a closed question. Route to design when the decision is open, not when the change is merely visual.

Example: "500 error + NullPointerException stack trace in login endpoint" → ndv-diagnose Example: "Should we switch to pnpm?" → ndv-honest

How to Apply

1. Use the Task tool with subagent_type: ndv-<specialist>
2. Pass full context in the prompt (task description, relevant files, error messages, goals) — subagents have no prior conversation history
3. For parallel work: spawn multiple Task calls in a single message

Parallelism Default

All agents default to parallel execution for 4-8 independent files/items.

Stack

• Runtime: Node.js ≥ 18, ESM ("type": "module")
• Test runner: node --test (built-in, no Jest/Vitest)
• Dependencies: @clack/prompts, picocolors — no build step for the fleet itself
• CSS build: Tailwind CLI (npm run css:build) — only needed for the website, not the fleet

Key directories

Validation

npm run validate

That is the whole merge gate, and the pre-commit hook and CI (.github/workflows/validate.yml) run exactly that command. It runs the full test suite (npm test, 14 files) and then the CSS staleness check. Authoring-guide checks are scoped to the agents changed on the branch: scripts/validate.sh compares against origin/main, or you can set CHANGED_AGENTS="ndv-foo,ndv-bar" yourself.

Narrower commands for iterating:

npm run validate:agents   # the 6 static agent/fixture checks — fast, no installs
npm run test:install      # install simulation only
npm run css:check         # CSS staleness only

Routing eval gate (local, before every release)

Run this before merging a release PR. It calls models, costs tokens, and is not part of validate:

npm run eval:gate

It re-scores each model recorded in test/fixtures/routing-baseline.json against test/fixtures/routing-cases.json:

Treat INCONCLUSIVE as "not checked", never as a pass.

Recording a baseline:

npm run eval:baseline                                             # 3 runs each: Opus 5, Sonnet 5, Haiku 4.5
npm run eval:baseline -- --models glm-5.3-flash                   # add a model (Ollama, needs OLLAMA_API_KEY)

• The floor is the worst result across the baseline runs. Misses are asked again (--retries 2, majority vote), so one unlucky answer doesn't fail a release.
• Editing the fixture makes the baseline stale. validate then fails until you re-run eval:baseline and commit the new baseline file.
• Models are reached through scripts/eval-providers/:
  • claude.sh (default for Claude models) runs the Claude CLI from an empty temp directory with no tools, no MCP servers, and a minimal system prompt. With ANTHROPIC_API_KEY set it also adds --bare, which skips hooks, plugins and your personal CLAUDE.md. Without it, your user-level CLAUDE.md still loads into every scoring call.
  • anthropic.mjs calls the Messages API directly: the clean-room number. Select it with --provider anthropic. Key from NDV_ANTHROPIC_API_KEY or ANTHROPIC_API_KEY; base URL from NDV_ANTHROPIC_BASE_URL to score through an Anthropic-compatible gateway. Some gateways resolve a bare alias such as claude-opus-5 to a different snapshot than Anthropic does; NDV_ANTHROPIC_MODEL_ALIASES=label=served-id,... maps the label to the id the gateway must receive, so the row measures the model its label names. Rate limits are retried with backoff; through a gateway pass --concurrency 2, since the default 4 trips a per-minute quota.
  • ollama.mjs calls Ollama's cloud API when OLLAMA_API_KEY is set, or a local Ollama server otherwise.
• Each baseline row records its provider, and eval:gate scores through the same one. Recording with --provider anthropic and gating through the CLI would compare two transports, not two releases.
• Keys and gateway settings live in .env at the repo root, gitignored. .env.example is the contract; copy it and fill it in. The eval scripts load it when present and shell variables take precedence. Never put a key or a gateway URL in a tracked file.

The eval measures the routing text that ships. The ndv:start/ndv:end block at the top of this file must be byte-identical to NDV_BLOCK in bin/ndv.js, and validate enforces that. Change the routing table in both places together, or the eval scores a table users never receive.

Ground truth: 56 cases covering all 19 agents, at least half of them conflict or residual cases. Each case has a basis:

• canonical (50): forced by an anchor, a verbatim phrase on a routing line that names the expected agent. scripts/routing-context.mjs supplies the same text to the validator and to the model. A canonical miss means the routing table needs fixing, or the model can't follow it.
• judgment (6, capped at 25%): the fixture author's own reading, with the contested alternative named. A judgment miss means review the case first.

To score a single model ad hoc, without the gate: NDV_EVAL_CMD='<command that reads stdin>' npm run eval:routing (supports --tag, --limit, --retries, --out).

Behavior eval (local, before a release that changes agent text)

The routing eval proves a task reaches the right agent. The behavior eval checks that the agent does the job once it's there. It also calls models, costs tokens, and is not part of validate:

npm run eval:behavior                                    # one run, Sonnet 5 via claude.sh
npm run eval:behavior -- --agent ndv-secure --kind lane  # narrow it while iterating
npm run eval:behavior:baseline                           # record floors: 3 runs each, same models as the routing gate
npm run eval:behavior:gate                               # PASS / DEGRADED / INCONCLUSIVE, same exit codes as eval:gate
npm run eval:behavior:compare -- --agent ndv-x --record  # agent file vs a plain model on the same cases

Each case in test/fixtures/behavior-cases.json runs with the agent's own model file as the system prompt, and has one of three kinds:

• finds: a defect planted inside the agent's domain. Pass means the output names it.
• lane: a defect planted outside the domain. Pass means the output hands it to the agent named in the case, which must be one the agent's Out of Scope declares.
• brief: a Flow brief with one Brief Contract field missing. Pass means BRIEF_REJECTED. Only Tier 1 and Tier 2 agents get one.

Scoring is deterministic: every check is a pattern on the output (scripts/behavior-checks.mjs, shared with the static test), with no model judge, so any score can be argued with line by line from the saved report (--out). The gate fails on a run below the baseline floor, and names each case that passed in every baseline run and now fails. Editing the fixture makes the baseline stale, and validate fails until it is re-recorded. Providers read the agent prompt from NDV_EVAL_SYSTEM_FILE; without it they keep the routing instruction.

Every new agent must beat the plain model. --compare runs each case twice: once with the agent file, once with a control prompt that knows the agent's lane, the routing table, the handoff format and BRIEF_REJECTED, but not the neurotype, primordial rule or domain protocols. The verdict per agent is EARNS (more checks passed than the control, and no fewer finds), NO GAIN or WORSE. --record writes it to test/fixtures/agent-evidence.json, pinned to the agent file and its cases. validate fails for any agent added after the original 18 without current EARNS evidence on at least two models (authoring guide, step 7).

Test files

Adding or changing an agent

1. Edit agents/ndv-[name].md (model file — source of truth)
2. Update routing in CLAUDE.md, agents/ndv-flow.md, bin/ndv.js (NDV_BLOCK + Copilot header), commands/opencode/ndv-help.md, humans/ndv-agents.md. The ndv block in CLAUDE.md and NDV_BLOCK must stay byte-identical.
3. Edit humans/ndv-[name].human.md (human file — written after model file is stable)
4. Run npm run validate. The pre-commit hook and CI (Node 20, ubuntu-latest) run the same command.
5. If routing changed, run npm run eval:gate before the next release.
6. For a new agent, or an edit to one added after the original 18: re-run npm run eval:behavior:compare -- --agent ndv-[name] --record on two models. It must say EARNS on both.

Pre-commit hook

Husky runs npm run validate on every commit. Fix failures before committing — do not skip the hook.

Running from a git worktree: husky's generated .husky/_ directory is untracked, so the hook doesn't fire there. Run npm run validate by hand before pushing.