Every agency says they leave you "handoff-ready." Almost none of them do. The phrase has been used so often, by so many vendors who had no intention of honoring it, that it now means roughly nothing. Let me put something sharper in its place.
Handoff-ready means: tomorrow morning, a competent developer you've never met could log in, read the docs, and pick up where we left off, without calling us.
That's the bar. Not "we'll send you the files." Not "we'll do a walkthrough on Zoom." A stranger, cold, at 9am, with only the artifacts we left behind. If that person gets stuck, we weren't handoff-ready. We were just friendly.
The one-day test
Here is the test I recommend running with any vendor (including me) before you sign. Put it in the statement of work. Give it a line item. It will change how the engagement is built.
On a date of your choosing, the vendor hands over a single folder (or repo, or shared drive). You do not call them. You do not email them. For the next eight hours, you, or a technical friend you trust, try to do these five things using only what's in that folder:
- Log in to every system the product depends on. Hosting, DNS, analytics, payment provider, email sender, any third-party APIs. All under accounts you own.
- Run the project locally, or at minimum understand how it runs in production, using the written instructions.
- Find and change one thing (a phone number in the footer, a price on a page) and deploy that change end-to-end.
- Answer the question "why is it built this way?" for at least three architectural decisions, using written docs (not tribal knowledge).
- Cancel or migrate any service without triggering an outage or losing data. Know exactly what each monthly bill is for.
If all five are possible in a day, you are handoff-ready. If even one requires a phone call to the original builder, you aren't; you have a dependency, and the vendor has leverage over you whether they want it or not.
Most agencies don't make their clients handoff-ready because being handoff-ready makes the client easier to lose. That's not malicious. It's just the shape of the incentive. Which is why you have to write the test into the contract.
What should be in the folder
The artifacts don't have to be elaborate. They have to be honest. In my engagements, the handoff folder contains:
The obvious
- Source code, in a repo you own
- A README that boots the project on a new machine
- Environment variable reference (names + what they do)
- Deployment instructions, written for a stranger
- List of all third-party services, with monthly cost
The things most vendors skip
- A written rationale for each major architectural choice
- A list of known trade-offs and where they'll bite
- Account-ownership map: who owns which login
- A "what to do when X breaks" runbook for the top 5 Xs
- A plain-English summary for the non-technical owner
That last row is the difference between a handoff and a shrug. Anybody can zip up a repo. Writing down why it's built this way, and what you'd do differently given another six months, takes an afternoon of honest work, and it is the single most valuable thing you leave behind.
Why this is a business question, not a technical one
Owner-operators sometimes think handoff is an engineering concern and defer it. It isn't. It's a risk concern.
A product that isn't handoff-ready is an asset with a single point of failure: your vendor. When that vendor raises rates, gets acquired, becomes unresponsive, or simply runs out of interest in your business, you have two bad options: pay whatever's asked, or rebuild from scratch. Both are expensive in ways that don't show up in the invoice.
A product that is handoff-ready is a normal operating asset. You can change vendors the way you change accountants: inconvenient, but survivable. That optionality is worth real money. It also, in my experience, makes the relationship with the current vendor healthier. Nobody negotiates well with a counterparty who has no exit.
The one question to ask
If you're mid-engagement right now and wondering where you stand, ask your vendor this:
"If you became unreachable tomorrow, what's the first thing my team would struggle with?"
A vendor who's serious about handoff will answer plainly, probably with a list, and probably with a plan to fix each one. A vendor who isn't will tell you not to worry about it. That's your answer.
Field notes
I publish the handoff folder on the day the work ships, not at some future offboarding. It's not a gesture. It's the contract. If you ever need to walk, you walk with everything. That's the job.
R.P.
