Custom connector work often gets treated like a narrow SDK exercise: wire up a factory, register a provider, ship an archive, move on. In practice, the hard part is not getting the first bundle to compile. The hard part is making the connector understandable enough that another engineer, another team, or a review gate can safely inherit it later.
That problem shows up repeatedly in enterprise integration environments. One engineer knows which descriptor fields are actually required. Someone else remembers the service registration hook. Packaging instructions live in an old chat thread or inside a local build script. The result is a starter that technically works but is fragile the moment ownership changes. We built ibm-custom-connector-starter to make that handoff surface explicit.
Existing examples usually miss the mark in one of two ways. Some are too minimal, which is useful for showing one SDK concept but not enough for real connector handoff. Others are too bundled, which hides the review story inside generated files and local conventions. Neither approach gives a platform or integration lead a fast, legible way to inspect descriptor posture, runtime registration, starter assets, and packaging steps together.
The design philosophy here is straightforward:
- keep the starter operator-readable
- keep the packaging trail explicit
- keep the descriptor and runtime hooks visible enough for review
That is why this repo exposes the same state through both HTML and JSON. The HTML routes make the starter easy to inspect visually. The JSON routes make it easy to test, automate, or wire into other review flows. The starter assets stay small and copyable on purpose; the value is not hiding complexity, it is making the baseline easy to reason about.
The IBM-inspired visual language is deliberate too. It helps the repo feel closer to the integration and platform environments it is meant to signal, without pretending to be an official IBM artifact. The goal is a starter that feels credible in that ecosystem while still reading like a Kinetic Gain-style productized reference build.
Next on the roadmap would be deeper packaging automation, descriptor validation, and contract-testing hooks for custom connector operations. The immediate win, though, is simpler: a connector starter that another engineer can extend without archaeology.