Most agency engagements end the same way. The lead engineer schedules a "knowledge transfer" call. Slides are shown. A Confluence space is shared. There's a friendly farewell email. The receiving team thanks them, files the deck, and gets to work.
Three weeks later, the receiving team is in production debugging a failure mode that wasn't in the deck. The agency lead doesn't reply for two days, and when they do, they don't remember the decision that caused it.
That's not a handoff. That's a goodbye.
What actually gets lost
The artifact problem is the smallest part. Most decent agencies leave behind reasonable documentation: an architecture diagram, a README, a list of credentials.
The bigger problem is the story. Why this database, not that one. Why this library, before the team knew about the better one. Why this module is structured the way it is — a particular constraint from a stakeholder six months ago, since lifted, but the structure stayed. The decisions and their contexts live in the heads of the people who made them. When those people leave, the context evaporates.
What the receiving team inherits is an artifact without a story. They read the code, infer intent, and get it wrong half the time. The codebase starts to drift away from its design, because the design is no longer legible.
What real handoff looks like
Four things, in order of cost:
A 30-day overlap with the receiving team. Not a "we're available on Slack" overlap. A real one — joint stand-ups, paired code reviews, the agency's lead engineer still on-call for incidents that touch the system. The 30 days isn't to teach; it's to be present while the receiving team makes its first mistakes.
Architecture Decision Records (ADRs) for every non-obvious choice. A short markdown file in the repo, dated, with three sections: context, decision, consequences. One per non-trivial choice. Not after the fact — written during the engagement, then handed over as a directory. If the receiving team can read the ADRs in two hours and feel they know the codebase, the handoff is real.
Live walk-throughs of the failure modes. Not the happy paths — those are documented. The failure modes: what happens when the database goes down, what happens when the third-party API rate-limits, what happens when a deploy fails halfway. Each one, walked through with the receiving team driving. They run the recovery procedure; the agency watches.
On-call coverage for the first month of the next team's ownership. Pager handed over, but agency still backstops at tier-2. Calls usually peak in week two of the new team's ownership — that's when they hit something the deck didn't cover. Having the previous agency reachable cuts incident severity dramatically.
The contract part
If you wait until the engagement is ending to negotiate handoff terms, you've already lost leverage. The agency wants their team off your roster so they can staff the next engagement. You want a quality handoff. Those incentives are not aligned at month seventeen of an eighteen-month project.
Put it in the contract on day one. Specifically:
- Named successor: who takes over if the lead engineer leaves the agency mid-engagement. Not "we have other senior people" — a name, written in.
- Handoff scope, written: what the agency will deliver at engagement end. The 30-day overlap, the ADR commitment, the failure-mode walk-throughs.
- Handoff fee, baked in: handoff is real work. If it's not budgeted, it gets done badly. Budget it explicitly, not as a vague "transition" line item.
What to demand before signing
Three questions, asked of any agency before you sign:
- What does your last handoff look like? Ask for specifics. A vague answer ("we provide thorough documentation") is the answer.
- What's the longest engagement you've successfully transitioned out of, and to whom? References from receiving teams matter more than references from happy current clients.
- What happens if our team isn't ready when your engagement ends? The right answer is "we extend, at agreed rates". The wrong answer is "that's on you".
The competitive point
A clean handoff is a moat. Agencies that do it well get referrals from receiving teams, from in-house leads who watched the transition go well, from the clients themselves a year later. Agencies that don't get litigation.
If you're choosing an agency, the question isn't "are they good?" It's "what does it look like when they leave?" Because they always leave.