nexus-llm-adapters

name	nexus-llm-adapters
description	How to add or debug a Nexus LLM provider adapter — what every adapter must wire, how to verify it against a live provider, and the failure modes that produce a silently blank chat. Use when adding or changing a provider adapter, debugging streaming or reasoning display, working with local or CLI-backed models, or touching chat branch plumbing.

Nexus LLM adapters

Adapters live in src/services/llm/adapters/{provider}/ and extend BaseAdapter, which talks direct HTTP through ProviderHttpClient. There are no vendor LLM SDKs in this repo; adding one is a decision to raise, not to make.

This router points at the procedure. The detail loads when you take the path.

Workflow

1. Adding or changing an adapter — follow protocols/add-adapter.md. It is a wiring checklist; work it in order rather than pattern-matching an existing adapter, because the pieces that get forgotten are the ones no compiler checks.
2. Chat is blank, missing reasoning, looping, or doubling — follow protocols/debug-adapter.md. Start from the symptom, not the adapter source: these failures have known causes and reading code first wastes the trip.
3. Before calling any adapter change done — run protocols/verify-adapter.md. You MUST exercise the non-streaming path, the streaming path, and the streaming error path separately; they fail independently and unit tests prove none of them. You MUST also run scripts/check_stream_error_wiring.py on the adapter you touched and get a zero exit.
4. End of a session that used this skill — run protocols/self-refine.md.

Map

• protocols/ the procedures: add-adapter, debug-adapter, verify-adapter, self-refine.
• references/ mechanism and rationale, read on demand: symptoms.md (the symptom→cause lookup the debug protocol enters through), streaming-contract.md, reasoning-rendering.md, local-providers.md, cli-providers.md, chat-plumbing.md.
• scripts/check_stream_error_wiring.py — checks that an adapter parsing an SSE stream wires extractError. Run it, do not re-derive it by reading source.

Siblings — do not duplicate them here

• nexus-model-updates owns model metadata: ids, pricing, context windows, capability flags, provider defaults, and the live provider smoke test.
• nexus-model-eval and nexus-eval-harness own grading models on tool use.
• nexus-testing owns test lanes, what a mock can prove, and the in-app loop.
• nexus-mobile-compat owns Node imports, dependency vetting, and desktop-only gating — which every adapter that shells out or touches the filesystem needs.

Refine

At the end of a session that used this skill, run protocols/self-refine.md and append to refinement-log.md.