“Our current developer isn’t working out, but the project can’t stop.” This guide is for the planned switch: the outgoing team is still reachable, your operations depend on the software, and you want to change software development companies without a gap in the work, whether you’re replacing your software development agency, a freelancer or an offshore team. If your developer has already stopped responding, start with what to do when your developer disappears instead.
Here’s the order that keeps a project moving through a switch:
- Decide whether the problem is the team or the way the project is run.
- Get the code and every account into your company’s name.
- Give notice with a written handover request.
- Overlap the two teams for recorded walkthroughs.
- Have the new team run the software, document it and ship one small change.
- Pay the final invoice once the handover is complete.
Should you switch software developers, or fix the relationship?
A switch costs something even when it goes well: the new team has to learn your code and your business rules, and your staff will spend time answering questions. So separate the problems a frank conversation can fix from the ones it can’t.
If most of what you see matches the “try fixing it first” column, talk to the team first. Put what isn’t working, what has to change and by when in writing. If things improve, you’ve avoided a switch. If they don’t, you have a record of why you’re moving on, and time to get your accounts in order.
Want a structured second opinion? The software project health check scores 18 plain-language questions and lists the red flags, and our guide to the signs your software project is failing goes deeper.
Before you give notice: get access in your company’s name
Do this while the relationship is still cordial. Asking for an administrator login to systems your company pays for is routine housekeeping. Asking for it after you’ve given notice can turn into a negotiation.
For every system you want two things: the account belongs to your company (company email, company card), and someone on your staff has their own administrator login. A password the developer emailed you doesn’t count, because they can change it.
Two platform recommendations are worth following while you’re at it. GitHub warns that an organization with only one owner can lose access to its projects if that owner is unreachable, and recommends at least two owners per organization. AWS recommends that an account’s root user sign in with an email address your business manages that forwards to a group of people, so AWS can still reach someone after an individual leaves.
If the code lives in the developer’s own account or their agency’s organization, ask them to transfer it to yours. On GitHub, the transfer has to be started by someone with administrator access to the repository, and the issues, pull requests and commit history move with it. Ask for the full repository, not a zip of the current code; the history shows what changed, when and why.
Access isn’t the same as ownership
Logging into the repository doesn’t settle who owns the copyright in the code; that depends on your contract and the law that applies to you. Find the ownership or IP assignment clause and any terms that tie the transfer to payment, and take questions to your attorney (this isn’t legal advice). Our guide for when a developer disappears lists the clauses to look for.
Example (hypothetical, not client data)
A field-service company’s scheduling app sits in the agency’s GitHub organization, and its AWS account uses one developer’s personal email. Before giving notice, the operations director has the agency move the repository into a company organization with two company owners and switch the AWS sign-in to a company group address. Work never stops, and when notice goes out, nothing critical sits in someone else’s account.
What the outgoing team should hand over
Once the accounts are yours, give notice the way your contract requires, with a written handover request. Be specific: “send us everything” invites a folder of files and leaves out what the new team needs most.
- Code and history: the complete repository with every branch and its history, the build and deployment scripts, and any code changed on a server but never committed.
- Environments: production, staging and test, where each runs, the framework, database and operating system versions, and anything that runs on a schedule, such as nightly imports or reminder emails.
- Configuration and keys: a list of every setting, outside service and API key, and where each is stored. The values go into your password manager, not an email.
- Data: administrator database access, the latest backup, where backups are kept, when a restore was last tested, and where uploaded photos and documents are stored.
- Documentation: setup steps, a deployment runbook and an architecture overview. One page beats none.
- Work in progress: open bugs, half-finished features and their branches, anything promised to users, and the workarounds your staff rely on.
- Licenses and renewals: paid components, SSL certificates, domains and subscriptions, with renewal dates and whose card pays for each.
Ask the question nobody writes down
“What breaks if nobody touches this for a month?” The answer can surface a certificate renewal, a scheduled job or a manual step someone does every Monday that isn’t in any document.
The software handover checklist turns this list into a request you can send. Choose the situation where your developer is leaving and cooperating, mark what you already have, and it writes a numbered request with a reply-by date, plus a “find out” list for everything marked “don’t know.” Nothing you type is sent anywhere unless you choose to send it to us.
Running the handover: overlap, walkthroughs, recordings
Documents capture what the system does. The outgoing developers know why: why the invoice screen skips weekends, which customer has a special pricing rule, what happens if the import runs twice. An overlap, when both teams are engaged at once, is how the transition from your previous software vendor gets that knowledge out of their heads and into something your company keeps.
How long should it last? Long enough for recorded walkthroughs and for the new team to deploy to a staging copy from the repository on its own. Agree in writing on the overlap and what the outgoing team is paid for it. It’s real work, and worth paying for.
Walkthroughs worth recording
- Architecture tour: the main parts of the system, how they connect, where the data lives and every outside service it talks to.
- A live deployment: the outgoing team releases a change to staging while the new team asks why at each step.
- The business rules: the screens your staff use most and any special handling for particular customers, contractors, sites or products.
- The rough edges: known bugs, fragile areas and the workarounds around them.
- Questions from the new team, once it has read the code.
Record every session and keep the recordings with your documentation, where your company controls them. Have the new team ask questions in writing too, so the answers outlast the call. Bring your own staff to the business-rules session: they know which exceptions matter day to day.
Prove it before the overlap ends
- Someone on the new team has deployed to staging from the repository, following the written steps, without help from the old team.
- Your staff can sign in as administrators to every system with their own accounts.
- A backup has been restored somewhere it can be checked.
- Every “don’t know” on your list has an answer.
Then close the old team’s access: remove their accounts and server keys, and rotate the passwords and API keys they could see, putting each new key in place before revoking the old one so payments, emails and logins keep working. A repository transfer won’t do this for you; GitHub’s transfer documentation notes that the original owner is added as a collaborator and that secrets and deploy keys stay attached.
Lining up the team that takes it from here?
Your first call is with an engineer. Tell us where the handover stands, and we’ll tell you what we’d want to see before the outgoing team steps away. You talk directly to the U.S.-based engineers doing the work, and NDAs are welcome.
The new team’s first steps: run it, document it, ship one small change
Whoever takes over, the first job isn’t new features. It’s proving that people who didn’t write the software can run it, understand it and change it safely. Ask the new team to show you each step.
Run it from a fresh clone
Copy the repository to a clean machine and get the application running from the written steps alone. Every missing step or undocumented setting gets written down and fixed. Then compare the repository with production. Changes that exist only on the server get copied into the repository before anything else.
Document what they find
A short, plain-language write-up: how the system fits together, how to deploy it, which outside services it uses, where the risky areas are and what’s still unknown. It goes in your repository, not in the new team’s heads, or you’re rebuilding the dependence you’re trying to escape.
Ship one small change
Pick something low-risk that users will notice: a label, a report column, a minor bug your staff keep mentioning. The change barely matters. What matters is the new team taking it through code, review, staging and testing, so you know the path works.
Make the first production deploy
Release that change to production with the new team doing the work, at a quiet time, with a way to roll back. That proves the one capability everything else depends on.
Example (hypothetical, not client data)
A building-supply company switches teams on its customer ordering portal. The new team’s first production release changes the wording of one order-confirmation email. Getting there turns up a missing environment setting and a nightly job nobody had listed, and both are fixed before any feature work starts.
Only then should you hear a recommendation about larger changes, with reasons. Still choosing who takes over? Our guide on how to choose a software development company covers the questions that expose a bad fit.
Common mistakes when switching software vendors: paying the final invoice first, rewriting right away
Paying the final invoice before the handover is complete
Once the final payment clears, most of your leverage goes with it. Tie it to outcomes you can check: the repository in your company’s organization with full history, every account in your company’s name, recorded walkthroughs, and a staging deployment the new team ran from the written steps. Put those conditions in your notice. Your contract may set its own payment terms, so check with your attorney before you hold anything back.
Rewriting right away
A new team facing unfamiliar code may want to start over, and sometimes that’s the right call. But a rewrite throws away working features and the business rules inside them, while the old system still has to run your operations. A good team runs and documents what exists first. If it then recommends a rewrite, it explains in writing what’s wrong, why it can’t be fixed in place, what happens to your data and what gets released first.
If you’re weighing it, the rewrite-or-refactor scorecard scores your application on value, pressure, risk, data and readiness, and gives a recommended path with the reasons behind it.
Other mistakes worth avoiding
- Giving notice before you have administrator access. It only gets harder afterward.
- Switching in your busiest period. Walkthroughs and testing need your own staff’s time, and a peak season or product launch leaves none.
- Nobody on your side owning the switch. Name one person to keep the access list, chase open questions and sign off the handover.
- Treating early estimates as firm. Until the new team has run the code, any estimate for the remaining work is a guess.
If you want a team to pick up where the last one left off, see how we approach software project rescue and maintenance and support for software someone else built. More plain-language help is in our guides.