Skip to main content

Provider Redesign Program — Roadmap

This is the master index. It orders and connects the ten implementation plans in this directory. Each plan is independently executable (via superpowers:subagent-driven-development or superpowers:executing-plans) and produces working, testable software on its own — but the wave order below exists because later plans consume contracts earlier plans produce.

Program goal: Make NeuroLink's provider integration scale from 31 providers to 230+, by (a) fixing the bugs and installing a CI safety net first, (b) collapsing the 30+ hand-maintained provider lists and 5 metadata stores into single sources of truth, (c) extracting the machinery the expensive providers each hand-rolled (agentic loop, error classification, streaming primitives), and (d) turning "add a provider" into a config entry with a scaffold and a merge gate.

Spec: The Provider Atlas audit (published artifact: https://claude.ai/code/artifact/3083b1e5-9647-456a-8609-fa4cf4eb5c10) plus the 15 per-area audit reports it was synthesized from. Each plan's header lists the specific area reports it argues from.

The ten plans​

#PlanWhat it shipsDepends on
012026-08-15-01-tier-a-bug-fixes.mdThe nine reachable bug fixes (together-ai credential drop, setup command, public isValidProvider, HuggingFace sdk forwarding, llama.cpp health probe, image-dispatch matcher, export-default violations, replicate credential naming, wasted health probe)—
022026-08-15-02-ci-safety-net.mdFirst real merge gates: mocked-contract + structural suites wired into CI, fixed branch-protection contexts, pre-push hook, nightly live matrix, doc-truth fixes—
032026-08-15-03-dead-code-purge.mdDeletion of all grep-verified dead code (9 provider dirs' orphaned siblings, static barrel, Vertex diagnostics, universalProviderOptions, unused config factories, duplicate zod schemas, stale comments)—
042026-08-15-04-provider-descriptor.mdProviderDescriptor + PROVIDER_DESCRIPTORS pure-data module as the single source of truth; every hardcoded provider list (CLI choices, health switches, status arrays, env validation, credentialKeyMap, PROMPT_ONLY_TOOL_PROVIDERS) derived from it; completeness test suite03 (less surface to migrate)
052026-08-15-05-openai-compat-catalog.mdThe config-driven tier prototype: ConfiguredOpenAICompatProvider + OPENAI_COMPAT_CATALOG; the 7 zero-quirk providers ported with byte-parity mocked contract proofs; the adjustBodyAfter400 compose fix04, 07
062026-08-15-06-model-metadata-consolidation.mdOne per-provider model manifest replacing the 5 disagreeing stores (context windows, pricing, MODEL_REGISTRY, vision tables, PROVIDER_MAX_TOKENS); ClassifierRouter observability + ranking fix; fuzzy-match tightening03
072026-08-15-07-error-retry-unification.mdclassifyProviderError + per-provider rule tables replacing ~30 hand-rolled formatProviderError bodies; one retry primitive (down from 4); deduplicated error classes; streaming 429/5xx retry parity; structured-output policy consolidation—
082026-08-15-08-agentic-loop-engine.mdOne adapter-parameterized agentic loop engine replacing the 9 hand-rolled native loops (Anthropic, AI Studio ×2, Vertex ×4, Bedrock ×2); merged stream-channel primitive; shared native tool-format converter; SageMaker streaming recovery; SPI hardening against the dual-shape trap07
092026-08-15-09-media-registry-consolidation.mdGeneric HandlerRegistry<T> behind the six media processors; single registration path; one resolveRequestKind() dispatch decision; CLI media choices derived from data; result-type dedup04 (pattern), 01
102026-08-15-10-onboarding-playbook.mdThe 200-provider machine: four-tier onboarding guide with per-tier checklists, scaffold-provider tool, per-provider CI requirement, CLAUDE.md updates, ADRs02, 04, 05, 07

Execution waves​

Wave 1 (parallel, independent):        01  02  03
Wave 2 (parallel):                     04  07        ← the two contract-producing plans
Wave 3 (parallel):                     05  06  08  09
Wave 4:                                10
  • Wave 1 first, always. It installs the safety net (02) the later refactors rely on, removes the dead surface (03) the migrations would otherwise carry, and lands user-visible fixes (01) with zero architectural risk.
  • 04 and 07 are the keystone plans. They produce the shared contracts (ProviderDescriptor, classifyProviderError) that plans 05, 08, 09, and 10 consume. Do not start wave 3 before both land.
  • Within wave 3, plans are independent of each other (05 touches the compat family, 06 touches metadata, 08 touches native loops, 09 touches media) — they can run as parallel worktrees with low conflict risk. Two shared files to watch: providerRegistry.ts (05 rewrites 7 factory blocks; 09 rewires the media handler blocks) and baseProvider.ts (08's Task 8 SPI default executeStream vs 09's Tasks 14–16 dispatch/video edits — different methods, but rebase deliberately). Conflicts are mechanical in either order.
  • 10 is deliberately last: the playbook documents the end-state, not the transition.

Cross-plan contracts​

These names are fixed across all plans (each producing plan defines the full shape; consuming plans reference it in their Interfaces blocks):

  • Plan 04 produces ProviderDescriptor (type, src/lib/types/providers.ts), PROVIDER_DESCRIPTORS (src/lib/factories/providerDescriptors.ts, pure data, statically importable), ProviderFactory.getDescriptor() / getAllDescriptors().
  • Plan 07 produces ProviderErrorRule (type, src/lib/types/errors.ts; supports per-rule custom message), classifyProviderError(error, rules, provider: string, modelName?) — positional args, this is the canonical call shape — + DEFAULT_ERROR_RULES (src/lib/utils/errorClassifier.ts).
  • Plan 05 produces OpenAICompatCatalogEntry (type), ConfiguredOpenAICompatProvider (src/lib/providers/configuredOpenAICompat.ts), OPENAI_COMPAT_CATALOG (src/lib/providers/openaiCompatCatalog.ts).
  • Plan 08 produces runAgenticLoop + the loop adapter type (src/lib/core/loopEngine.ts), the merged stream channel (src/lib/core/streamChannel.ts), toNativeToolDeclarations (src/lib/core/nativeToolFormat.ts).

Program-level verification gates​

Run after every wave (all no-API unless noted):

pnpm run check                                   # typecheck clean
pnpm run lint                                    # all 14 repo rules + format
pnpm run build                                   # SDK + CLI build
npx tsx test/continuous-test-suite-providers-mocked.ts     # contract parity (wave 1+)
npx tsx test/continuous-test-suite-provider-structure.ts   # registry completeness (after plan 02)
npx tsx test/continuous-test-suite-provider-wiring.ts      # credential-key coverage (after plan 01)
npx tsx test/continuous-test-suite-provider-descriptors.ts # descriptor completeness (after plan 04)
npx tsx test/continuous-test-suite-model-manifests.ts      # metadata consistency (after plan 06)
pnpm test                                        # main continuous suite

Live verification (API keys required, run before declaring a wave done, never as a PR gate):

pnpm run test:matrix        # capability sweep across configured providers
pnpm run test:providers     # per-provider deep dives

What this program deliberately does not cover​

  • The proxy subsystem (src/lib/proxy/) — its Anthropic-only account pool and YAML routing are documented in the audit (chapter 13). Generalizing the account pool into a CredentialPool and deriving proxy /v1/models from the SDK registry are future work, unblocked (and made easier) by plan 04's descriptors.
  • neurolink.ts decomposition — the 17.7K-line orchestrator's generate/stream duplication (RAG injection, budget-compaction blocks, three fallback mechanisms) is a larger structural refactor. Plans 07/09 shave pieces off (retry, dispatch); a dedicated decomposition effort should follow the program once the provider surface is stable.
  • Onboarding the 200 providers themselves — that starts after wave 4, using plan 10's playbook and scaffold.