What a proper project handover should include

Clients own all the code we write for them. That has been true since the first theme we sold, and it is a line in every contract. But ownership on paper is not the same as being able to use what you own. We regularly meet businesses who technically own an application built by a previous agency, yet cannot deploy it, do not know where it is hosted, have no idea which third-party accounts it depends on, and discover that the only person who understood it left two years ago. A handover is what turns ownership into control, and it deserves as much planning as the build itself.

Why handovers go wrong

Handovers fail for predictable reasons. They are scheduled for the last week of a project, when budgets are tight and attention has moved to the next engagement. They are treated as a documentation task rather than a transfer of capability. And they are measured by whether a document was delivered, not by whether the receiving team can actually do anything with it. We plan ours from the first week, and we measure success by a single test: can the client's team, or a new agency, deploy a change to production without calling us?

The handover package

Every build we finish comes with the same set of deliverables.

1. Code in your repository. The full history, not a zip file, in a repository owned by your organization account, with our access reduced to what any ongoing support agreement requires.
2. Infrastructure in your accounts. Hosting, DNS, CDN, email sending, error tracking and monitoring all registered to your organization, with billing in your name. Nothing important should live in an agency account.
3. A credentials inventory. A list of every external service, what it is used for, who the account owner is, and where the credentials are stored. The secrets themselves live in your password manager or secret store, never in a document.
4. A README that works. Step-by-step setup for a new developer, tested by someone who did not write it, on a clean machine.
5. Architecture notes. A short document with a diagram of the main components, how data flows between them, and the reasoning behind significant decisions.
6. Runbooks. How to deploy, roll back, restore from backup, rotate a credential, and respond to the three or four most likely incidents.
7. A known-issues list. Technical debt, deferred features and anything we would do differently with more time, stated plainly.

The best handover document is a README that a stranger can follow to a running system in under an hour.

Decision records

Architecture notes describe what the system looks like. Decision records explain why. We keep a short record for each significant choice during the build: the problem, the options considered, the choice made and its consequences. They take ten minutes to write at the time and save hours of confusion later, when a future developer wonders why the application uses a particular queue, or why a feature was built the long way round. Without them, successors either repeat old debates or undo decisions that had good reasons behind them.

docs/decisions/
  0001-use-postgres-row-level-security.md
  0002-queue-emails-via-redis.md
  0003-defer-multi-currency-to-phase-two.md

Knowledge transfer is a practice, not a meeting

Documents help, but capability transfers through doing. For clients with an in-house team, we run the last two to three weeks of a project as a guided handover:

• A walkthrough session per major area, recorded so new hires can watch later.
• The client's developers make real changes and deploy them with us reviewing, rather than watching us do it.
• They run at least one deployment rollback and one backup restore themselves.
• We pair on the first production incident, or on a simulated one if none occurs.

For clients without an in-house team, the audience is whoever will support the system next, whether that is a freelancer, another agency or our own care plan team. We have received plenty of handovers from other agencies, and we write ours to the standard we wish we received.

The first 30 days after launch

Every build includes 30 days of post-launch support, and we treat that period as part of the handover rather than a separate phase. Bugs found in real use get fixed, and each fix updates the documentation where it was missing something. At the end of the period we hold a short review: what questions came up that the documents did not answer, what the team still feels unsure about, and whether they want ongoing support. Some clients take the system fully in-house; others move onto one of our monthly care plans. Both are fine outcomes, and the handover should make either one straightforward.

What to ask any agency for

If you are commissioning software from anyone, ask before signing: whose accounts will the hosting and services live in, what documentation will be delivered, will your team deploy a change themselves before the project closes, and what does the known-issues list look like? Agencies confident in their work will answer those questions easily. If you have already received a system without these things, our legacy code modernization team often starts engagements by reconstructing the missing handover, and our custom web applications are delivered with the full package as standard.

Build something you can actually own

Whether you are planning a new build or trying to regain control of an existing one, we are glad to talk it through. Send us a few details and we will reply with a fixed-price quote within a day. Contact us to get started.