Article
Every contract we sign says the client owns everything from the first commit. That sentence is easy to write. What makes it true is the last two weeks of the engagement, when the system goes from something we can run to something they can. Here is what that work consists of, because it is the part agencies most often skip and clients most often regret.
Reproduce the system from nothing
A new engineer with a fresh laptop and the README should have the system running locally in under an hour. We test this literally, with an engineer who was not on the project, and fix whatever they trip over. If the setup needs a secret, the README says where the secret lives. If it needs a service account, the account exists in the client's name.
Put every credential in the client's hands
Cloud accounts, domain registrar, DNS, the app stores, the payment provider, the error tracker, the email service. Each one in the client's name, with our access removed on the handover date and a list of what we removed. An engagement that ends with a critical login still belonging to the agency has not ended.
Write the runbook for three in the morning
Not architecture documentation, though that exists too. A runbook answers the questions that come up when something is wrong: how to see what is failing, how to roll back a deploy, how to restore a backup, what the alerts mean and what to do about each, who to call at the third-party services. We write it as a list of situations, each with steps, and we test the restore.
Record the decisions, not just the code
Why the database is structured the way it is. Why the third-party service was chosen over its competitor. Which corners were cut on purpose and what it would take to fix them. This is a short document, and it is the one a future engineer will thank you for, because code shows what was done and never why. We keep it as a decisions log through the project so it does not have to be reconstructed at the end.
Hand over live, not by email
Two sessions with the people who will run it: one walking through the system and the runbook, one where they deploy a small change themselves while we watch. The second session is the real test. If they cannot ship a change without us, we have not finished.
Leave the tests and the CI green
The tests that exist should describe intended behaviour and pass. The pipeline should run them on every change and deploy on merge. A team inheriting a green pipeline changes things with confidence; a team inheriting a red one stops running the tests within a month.
Say what happens next
A written note of what we would do next and in what order, what the known limits are, and how to reach us. Then a support window, in which anything we built that breaks is fixed at no charge, and after it, the choice of a retainer or nothing. Nothing is locked to us, which is the point of the whole exercise.
Why we do it this way
Because the alternative is a soft lock-in that nobody agreed to: a system that is technically yours and practically ours. Clients notice, and the ones who notice are the ones worth working with again. Every workflow ends with this handover, and the Legacy Modernization workflow, where the whole point is that the client's team takes over, is built around it.