Changing development vendors is not a procurement exercise. It is a migration, and the thing being migrated is not code — it is context. The repositories transfer in an afternoon. The reasons behind the decisions in them do not transfer at all unless somebody deliberately moves them.
Most teams that have done this once describe the same failure. The handover happened, the new team had commit access on day one, and delivery still stopped for a quarter while people worked out what everything did. That gap is avoidable, but only if you plan the transition as a piece of engineering work rather than a contract end date.
What actually breaks
Three things go missing when a vendor leaves, and none of them are in the repository.
- Decision history — why the queue was chosen over a cron job, why that service was never split, which workaround is load-bearing. Without it the new team either re-litigates settled decisions or breaks something they assumed was accidental.
- Operational knowledge — what fails at month end, which alert is noise, what the manual step before the release actually does. This lives in people’s heads and expires the day their contract does.
- Access — the domain registrar, the payment provider dashboard, the DNS, the CI secrets, the one cloud account that was created on a personal address in year one. This is the part that turns a transition into a hostage negotiation.
Overlap the teams, and pay for it
The instinct is to end one contract and start the next on the following Monday. It is cheaper on paper and more expensive in practice. Plan an overlap where both teams are engaged at once, and treat that overlap as the deliverable rather than as dead time.
During the overlap the incoming team should be shipping, not reading. Small changes, real pull requests, reviewed by the outgoing team. You learn more about a codebase from having a change rejected than from any amount of documentation, and you find out immediately whether the outgoing vendor’s review standards were real.
What to demand from the outgoing vendor
Ask for these in writing, before the notice period starts, while there is still commercial leverage. A vendor who cannot produce them is telling you something useful about how the work was done.
- A complete access inventory — every account, provider and credential touching the system, with the owner named. Not a promise to hand things over; the list itself.
- A runbook for anything manual — deploys, migrations, month-end jobs, the steps nobody automated.
- The architecture as built, not as designed. Diagrams that match production, including the parts everyone is embarrassed about.
- A recorded walkthrough per major subsystem, from the engineer who wrote it. An hour of video outlasts any document because it captures the asides.
- An honest debt list — what they would fix first if they were staying. You will get a more candid answer on the way out than you ever got during the engagement.
Set the entry bar for the incoming team
The switch is your one moment of maximum leverage with the new vendor, and it is worth spending on structure rather than on rate. Insist on meeting the engineers who will do the work, not the account team — at Hazesoft clients interview the tech lead before anything is signed, and the person in that conversation is the person in your repositories. Insist that the arrangement you are signing can itself be exited: your repositories, your cloud accounts, documentation and handover drills treated as part of the definition of done rather than as a closing favour.
That last point matters more than it sounds. You are switching vendors precisely because leaving the last one was hard. Signing a replacement without fixing that condition means doing this again in three years with the same pain, and it is the single easiest thing to negotiate while you are still the one choosing.
The test for month one
A transition has gone well when the new team has merged production code inside the first month, can deploy without the outgoing vendor in the room, and can explain a decision they did not make. Anything less and you are still in handover, whatever the contract says. We set out how we run a takeover, step by step.
If you are mid-switch and want a second opinion on the transition plan, start with a technical call — an hour with an engineer on your architecture and constraints, not a sales call.