How to hand over an unfinished software project (complete checklist)
7 min read
On this page
- What a good handover achieves
- Step 1: List every account the project depends on
- Step 2: Put the code and its history somewhere you own
- Step 3: Write down how to run it
- Step 4: Describe the current state honestly
- Step 5: Gather the supporting material
- Step 6: Plan access without handing out passwords
- Step 7: Agree what "done" means for the first milestone
- Step 8: Close the previous developer's access
- The complete handover checklist
- Common handover mistakes
- Next step
A handover is the moment a project either keeps its momentum or loses weeks to guesswork. The new developer needs to find the code, run it, understand what is half-done and deploy a change without chasing the previous person. This guide walks through what to gather, in the order that saves the most time, and ends with a checklist you can tick off.
What a good handover achieves
Think of the goal as three tests. Can the new developer run the project on their own machine? Can they change something and see the result? Can they deploy that change to the live site or app? If your handover lets them pass all three in their first few days, you have done the important part. Everything else is detail that speeds them up.
It also protects you. A written record of the project's condition on handover day stops later arguments about who broke what.
Step 1: List every account the project depends on
Most handover delays come from accounts nobody remembered. Open a spreadsheet and add one row per service:
| Service | What it does | Whose name is it in | Who has access now | Renewal or billing date |
|---|---|---|---|---|
| Domain registrar | Owns the web address | |||
| Hosting (Vercel, Netlify, a VPS...) | Serves the site | |||
| Database (Supabase, Firebase...) | Stores the data | |||
| Code host (GitHub, GitLab...) | Holds the source |
Keep going with email sending, payments, analytics, app store accounts, AI builder workspaces (Lovable, Bolt, Replit and similar), file storage and any paid APIs. Search your inbox for receipts and "welcome to" emails; they reveal services you forgot about.
The column that matters most is "whose name is it in". Anything registered to the previous developer's personal account is a risk, and moving it into your name is your first priority. The guide on securing your accounts after a developer disappears covers that in detail.
Step 2: Put the code and its history somewhere you own
The new developer needs the full source with its commit history, not a zip of the latest files. History shows why things changed and which parts were recently touched.
- If the code is on GitHub under the old developer's account, ask them to transfer the repository to you or to an organisation you own.
- If it lives inside an AI builder, use the builder's export or GitHub sync feature so the code exists outside that tool.
- If you only have a zip, create a new repository in your own account and commit it, noting that earlier history is missing.
Once the repository is in place, run the Repo Health Check if it is public. It shows recent activity, whether tests and a README exist, and whether files that look like secrets were committed. If anything was committed that should not have been, paste the suspicious file into the Secret Leak Scanner, which runs in your browser, before you share the repository more widely.
Step 3: Write down how to run it
A short setup note saves hours. It does not need to be technical prose; bullet points are fine. Cover:
- The commands used to install and start the project, if you know them (often in the README or
package.json). - The names of the environment variables the app needs, such as
SUPABASE_URLorSTRIPE_SECRET_KEY, without their values. A file called.env.examplewith names and blank values is the standard way to do this. - Which environments exist: local, staging, production. Say which database each one points at.
- How deploys happen today: automatic on push, a button in a dashboard, or files uploaded by hand.
If you are not sure about some of this, say so. "I think deploys happen automatically from the main branch, but I have not confirmed it" is more useful than silence.
Step 4: Describe the current state honestly
Write three short lists in plain language:
- What works. Features a real user can complete from start to finish today.
- What is broken or blocked. Include error messages, screenshots and the steps to reproduce each problem.
- What remains. Features that were planned but never built, in rough priority order.
Add a brief "as-found" statement: the date, the version or commit that was live, and a sentence saying the project is being handed over in its current condition. This protects both sides. The new developer is not blamed for problems that already existed, and you have a fair baseline for judging progress.
Describe problems, not people. "Payments stopped confirming in March" helps; "the last developer was careless" does not, and it may put off good candidates.
Step 5: Gather the supporting material
Collect anything that explains intent:
- Design files or links (Figma, screenshots of mock-ups, a style guide).
- Product notes, user stories or a feature list.
- Important decisions from old chat threads or emails, copied into one document.
- For AI-built apps, the prompts or chat history that shaped key features, if the tool lets you export them.
- A list of real users or test accounts the developer can use, without passwords. Test accounts can be created fresh.
Step 6: Plan access without handing out passwords
Decide which accounts the new developer needs on day one and which can wait. Usually that means the code repository, the hosting dashboard and the database, often with limited roles. Payments, app store and domain access can often come later or stay with you.
Use the team or collaborator features each service provides, so every person has their own login and can be removed cleanly. Our guide on giving a developer access without sharing passwords explains the options service by service. Never paste keys or passwords into chat or email, including messages on TakeoverWork.
Step 7: Agree what "done" means for the first milestone
Before work starts, write down a small, testable first goal. For example: "The app runs locally, the sign-up bug is fixed and deployed, and the developer has sent a short written review of the codebase." A first milestone like this tells you quickly whether the working relationship suits you. Price, timing and payment are agreed directly between you and the developer; TakeoverWork does not handle project money.
The Rescue Effort Estimator gives a rough effort band to sanity-check what you hear. It is a guide, not a quote.
Step 8: Close the previous developer's access
If the earlier developer or agency is no longer involved, remove their access once you have everything you need from them. Then rotate keys and secrets they could have seen, one at a time: create the new key, update it in the hosting dashboard, redeploy, confirm the app works, then revoke the old key. Doing it in that order avoids taking the live site down.
The complete handover checklist
- Account inventory created with owner, access and renewal date for each service
- Domain, hosting and database registered in your name or your company's name
- Code in a repository you own, with commit history where possible
- Repository checked for committed secrets
.env.exampleor a list of environment variable names (no values)- Notes on environments and how deploys happen
- What works, what is broken and what remains, written in plain language
- Error messages and screenshots for each known problem (no keys or customer data visible)
- As-found statement with date and live version
- Design files, product notes and key decisions collected in one place
- Day-one access list agreed, using invites and limited roles
- First milestone written down with clear acceptance criteria
- Previous developer's access removed and secrets rotated
To turn these steps into a document you can share, use the Project Handover Checklist Generator. It builds a handover document from a short form and lets you print or export it.
Common handover mistakes
- Handing over only the live site. A deployed web app is usually compiled code. Without the source repository, the new developer may be rebuilding rather than finishing.
- Mixing the old and new developer. Two people pushing to the same branch without talking causes conflicts. Agree a clean switch date.
- Skipping the known-issues list. The developer will find the bugs anyway, but slowly, and may quote higher to cover the unknowns.
- Leaving renewals unchecked. An expired domain or a lapsed hosting card can take the project offline in the middle of the handover.
Next step
If the previous person has already left mid-build, the finishing a half-built app page explains what usually needs doing first. When your notes are ready, post your takeover for free and paste in the works, broken and remaining lists you wrote in Step 4. Developers and agencies who take on unfinished projects can then read the details and get in touch.
Frequently asked questions
Do I need to understand the code to hand a project over?
No. Your job is to collect what exists and describe it honestly: which accounts you have, where the code lives, what works and what does not. The new developer reads the code. The clearer your notes on behaviour and goals, the faster they can do that.
Should I give the new developer the old .env file?
Not as a file in chat or email. Share the list of variable names so they know what is needed, then give access through the hosting or database dashboard, where values can be read by invited team members. Once the previous developer has left, plan to rotate the keys anyway.
What if the previous developer never gave me the code?
Start by securing what you do control, such as the domain and hosting, then ask for the repository in writing. If the code only exists on a live server, a developer may be able to recover a deployed copy, although built front-end code is harder to work with than the original source.
How long does a handover take to prepare?
For a small app, an owner can usually gather the accounts and write the notes in a focused day or two. It takes longer when accounts are in someone else's name or the code is spread across several places.
Is a handover document legally binding?
No. It is a working document that describes the project's condition. Price, scope, payment and ownership of work should be agreed separately in writing between you and the developer. TakeoverWork does not take part in that agreement or handle any payments.
Stuck with a half-built app?
Post your project free. Developers who finish and rescue projects can send you an interest note, and you decide who to talk to. You agree scope and payment directly with them.
Free tools that help
Related guides
How to give a developer access without sharing passwords
Use team invites and limited roles instead of shared passwords, service by service, and know exactly how to remove access and rotate keys when the work ends.
ReadDeveloper disappeared: secure your code, domain, hosting and accounts today
A calm, ordered plan for the day your developer goes silent: protect the domain and email first, then hosting, code, data and money accounts.
ReadHow to write a takeover listing that gets good responses
Developers decide quickly whether a takeover is worth a reply. Clear facts about the stack, the state of the code and your budget bring better, more specific responses.
ReadRelated problems
How to finish a half-built app without starting over by accident
A practical path for a stalled app: take stock of what works, decide fix or rebuild with clear reasons, define finished, prepare access and post a clear listing.
ReadDeveloper disappeared with the code? What to do, step by step
When a developer goes silent, secure your accounts first, then work on getting the code back. What you own depends on your agreement, so get local legal advice.
ReadAgency abandoned your project or closed mid-build? What to do next
When an agency stops work or closes, you need more than the code: accounts, designs, licences and project history. Here is how to collect them and plan the next step.
Read