Skip to content
TakeoverWork
Guide for owners

How to hand over an unfinished software project (complete checklist)

7 min read

On this page
  1. What a good handover achieves
  2. Step 1: List every account the project depends on
  3. Step 2: Put the code and its history somewhere you own
  4. Step 3: Write down how to run it
  5. Step 4: Describe the current state honestly
  6. Step 5: Gather the supporting material
  7. Step 6: Plan access without handing out passwords
  8. Step 7: Agree what "done" means for the first milestone
  9. Step 8: Close the previous developer's access
  10. The complete handover checklist
  11. Common handover mistakes
  12. 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:

ServiceWhat it doesWhose name is it inWho has access nowRenewal or billing date
Domain registrarOwns 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_URL or STRIPE_SECRET_KEY, without their values. A file called .env.example with 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:

  1. What works. Features a real user can complete from start to finish today.
  2. What is broken or blocked. Include error messages, screenshots and the steps to reproduce each problem.
  3. 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.example or 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

Related problems