Startup inherited from an agency: a mentor's checklist

Why these handoffs go wrong

Agency teams often move fast and keep moving. That works while the same people stay involved. Trouble starts when they leave with the unwritten knowledge.

A lot of the real context never reaches tickets or docs. One developer knows which server job fails twice a week. Another knows which setting breaks signups. Someone else knows that a 'temporary' script now runs a daily business task. When details live in people's heads, the new team starts with blind spots.

Control usually ends up split as well. Founders may have the domain login, a Git account, and one cloud bill. The agency may still control deploy pipelines, app store access, backups, error tracking, or the inbox that gets security alerts. Nobody plans to end up here, but it happens all the time.

New hires feel that risk right away. They inherit code they did not write, rules nobody explained, and a system map that does not exist. So they move slowly. They avoid touching fragile areas, even when the fix looks small. That caution makes sense, but it turns ordinary work into slow work.

The first serious problem usually exposes the gaps:

• nobody knows the rollback step
• only one old contractor can run a deploy
• production alerts still go to the wrong inbox
• the team can change code but cannot ship it

Most bad handoffs do not fail because the agency wrote bad code. They fail because ownership, access, and day to day knowledge sit in different places.

What to collect first

On day one, do not start fixing bugs. Collect every account, document, and agreement tied to the product. Inherited projects often have an access problem before they have a code problem.

Open one shared document and build a plain inventory. For each service, write down its name, who legally owns it, who pays for it, who can log in, and whether the company can change settings without the agency. That sounds basic, but it saves days of confusion later.

Start with the assets that can stop the business: source repositories, hosting, DNS, domain registrar access, company email accounts, CI/CD tools, app store accounts, analytics, billing systems, and error tracking. Keep the latest contract, statement of work, roadmap, open bugs, and customer reports in the same place.

The names matter as much as the passwords. Write down the legal owner, billing owner, and technical owner for each service. If the agency still pays for the cloud account or holds the only admin seat in an app store account, the company does not fully control that part of the product.

Ask for the latest contract and statement of work early. Those documents often explain what the agency agreed to build, what it never promised, and which handoff items you can still ask for. They also expose the gap between what the team assumes and what was actually delivered.

Keep the roadmap and bug list next to the account inventory. A small bug can become a release blocker if the only person with deploy access has already left.

Check code ownership first

If the code is not clearly yours, the rest of the handoff can fall apart quickly.

Start with the contract. It should say the company owns the source code, design files, custom scripts, and anything built for the product. If the wording is vague, fix that first. A friendly relationship with the agency is not the same as legal ownership.

Then move every repository under an organization the company controls. If the code still lives inside the agency's GitHub, GitLab, or Bitbucket space, you do not fully own the work yet.

A fast ownership review should cover:

• every repo and branch the product uses, including old private repos
• private packages, paid themes, plugins, fonts, and licensed assets
• signing keys, app certificates, and store publishing credentials
• scripts or tools the agency still hosts on its own servers or accounts

Each item is a real dependency until the team can replace it or bring it inside the company. If the agency still holds the mobile signing key, it still controls app updates. If a private package lives in the agency's registry, your next release can fail the day access changes.

Make a written list of everything that still depends on the agency. That might be a private npm package, a UI theme bought under their account, or a small internal tool that builds the app. It is all risk until the company can run without it.

Verify deploy access

Deploy access is where many takeovers stall. Everything can look fine until the first urgent fix lands and nobody can ship because one missing login blocks the release.

Map every step between a merged commit and a live product. Most teams need access to the code host, the CI/CD pipeline, a container or package registry, cloud servers, DNS, secrets storage, and any app store or email service tied to the release.

Then test the path yourself. Log in with a company account. Open the pipeline. Check whether it can still build, fetch secrets, and publish artifacts. Confirm who can approve a production release and who can fix it when it fails halfway through.

Do not trust screenshots or old credentials in a shared note. Open the dashboards. Inspect the latest successful deploy. Confirm that the billing owner, recovery email, and admin role all belong to the company.

Once the team has access, clean up the leftovers. Remove agency emails, shared passwords, and one off admin users. Rotate passwords, replace shared secrets, and revoke access that no longer makes sense.

Before you touch production, save a rollback path. Keep the current image tag or release artifact, note the exact deploy command, store a recent database backup, and write down which version is live now. If a small change goes wrong, you want a ten minute retreat, not a five hour scramble.

If one person can still deploy only from a private laptop and an agency email, the handoff is not done.

Make the architecture clear

Ask the agency to explain the live product on one page. If it takes a deck full of vague diagrams, you still do not have a useful map.

Use the real production setup, not the version people wish they had built. Put every moving part on the page and label it with the exact name the team will see in code, cloud dashboards, and invoices. Include each app or service in production, every database, cache, queue, worker, and cron job, the outside vendors for login, email, billing, storage, analytics, and alerts, and the place where secrets, user files, logs, and backups live.

Do not skip the unglamorous parts. Teams often know where the app runs, but they cannot say where uploads live, who can restore a backup, or which system stores API keys. Those missing details turn a small outage into a long one.

For each part of the system, add one blunt note: what breaks if it stops. Keep it simple. If the queue fails, background jobs pile up. If object storage fails, users cannot open files. If the billing job fails for three nights, invoices go out late and support gets flooded.

A one page map will not make the system better overnight. It will make the risks obvious, and that is the point.

Write the operating docs

Rough code rarely hurts as much as missing operating docs. A surprising number of inherited products keep working only because one person remembers the odd steps, hidden logins, and release habits.

Start with the path from commit to production. Write down which branch ships, who approves a release, what tests run, which environment variables matter, and how the team rolls back if the deploy fails. If nobody can explain rollback in one minute, the process still lives in someone's head.

Then document local setup and staging. A new engineer should be able to run the app, seed test data, and check a small change without asking three people for help. Note which services must run, where test accounts live, and how staging differs from production.

Every runbook should answer a few plain questions. How does code reach production? How does a developer run the product locally? Who handles bugs and incidents? Where do logs, alerts, and dashboards live? What happens before a hotfix ships?

Keep the hotfix routine short. Confirm severity. Check logs. Assign one person to patch the issue. Run a smoke test. Write down the rollback step. Post the change. Two clear pages beat ten pages nobody reads.

If a new engineer can deploy a small fix and respond to an alert without calling the agency, the docs are good enough for now.

A small example

On Monday, a SaaS startup asks for a small pricing update. The agency says it should take two hours. By Friday, nobody has shipped it.

The founder opens the codebase and finds three repos with similar names. One seems to control the marketing site. Another has billing code. A third looks newer, but nobody can say which repo runs checkout in production.

The team checks deploy access and finds another mess. Production runs in one cloud account, but DNS lives in a different account that the agency created under an old contractor email. The startup can edit code, but it cannot fully control traffic, secrets, or rollback.

Then mobile enters the picture. The app still shows the old pricing in a few places, and the company wants to update that too. The agency kept the mobile signing keys, so the team cannot publish a new build even after it changes the code.

A tiny request now stalls sales, support, and product work. The founders spend days asking for passwords, exports, and screenshots instead of fixing the feature. What looked like a pricing task turns into an ownership problem.

That is what these handoffs look like in real life. The software exists, but the company does not fully control it.

Review the first week

The first week should be short and strict. By the end of it, the team should know who controls the product, who can ship changes, and what might fail on an ordinary Tuesday.

Day 1 is inventory. Collect every repo, cloud account, domain login, app store account, analytics tool, payment dashboard, and signed contract. If any account still belongs to the agency, flag it immediately.

Day 2 is a staging deploy. Make one tiny change, push it, watch the build, and confirm that the team can roll it back without asking the agency for help.

Day 3 is a user journey test. Create an account, save a record, send an email, and check the database. This usually exposes hidden jobs, outside services, and manual fixes that nobody documented.

Day 4 is documentation. Write the missing runbook pages for deploy steps, rollback, secret storage, backup checks, and first response during common failures.

Day 5 is risk ranking. Sort problems by impact and by how hard they are to fix, then give each one an owner and a due date. If ownership stays vague, the work will stall.

A simple test helps here. If a password reset email fails, can the team tell whether the problem sits in the app, the queue, the mail provider, or DNS? If not, the handoff is still incomplete.

Mistakes that make the takeover harder

The fastest way to make a messy handoff worse is to start changing code on day one. Even a small fix can turn into a long night if nobody checked backups, restore steps, or the last rollback path.

Teams also get stuck when they trust one person to remember the whole setup. That person might be an agency lead, a freelancer, or your own first engineer. If they disappear, every missing detail turns into guesswork.

A better rule is simple: if it matters, write it down and verify it. Screenshots help. Exported configs help. A short note on where production runs, who can deploy, and where logs live helps even more.

Old agency accounts are another common problem. Shared logins, forgotten cloud users, and active API tokens can sit around for months. That is a security risk, but it also creates confusion when billing alerts, deploy notices, or error reports still go to the wrong inbox.

Skipping a test deploy is another mistake people regret. A dry run often exposes the real gaps: missing environment variables, expired secrets, broken build steps, or permissions that only the agency still has. You want that surprise in a safe test, not during a customer facing release.

Missing docs look harmless until something breaks. If nobody has written down cron jobs, DNS settings, release steps, restart commands, and outside services, a small outage can stretch for hours.

Treat missing docs as an operating risk, not paperwork.

Quick checks before touching production

Before any production release, stop and answer a few plain questions:

• Can the current team revoke the agency's production access and still run the system?
• Can one current team member deploy a safe change without help?
• Have you restored a recent backup and tested rollback for the last release?
• Can one person explain the system in plain English in about ten minutes?
• Do support staff know where logs, alerts, and error reports live?

That backup and rollback test matters more than most founders expect. Many teams learn too late that backups exist only on paper, or that rollback depends on one engineer remembering a manual step.

The ten minute explanation is a good stress test too. If nobody can describe the app, database, queue, outside services, and scheduled jobs without opening five tools, the system is still living in someone else's head.

Support access is the last quiet risk. When a customer reports a broken checkout or a failed sync, support should know where to look first. If they cannot find logs and alerts in under a minute, small incidents drag on and trust drops fast.

What to do next

Fix the gaps that can stop the business first. Messy code can wait. Broken deploys, lost domain access, and missing billing logins cannot.

Move control to the company. The founder or an internal lead should own every account, every secret, and every runbook. If the agency still holds the only admin login, the only production key, or the only copy of the setup notes, start there.

Then use a simple 30 day plan. Spend week one on access and secret rotation. Use week two for deploy steps and rollback checks. Use week three to document the system and clean up the runbooks. Use week four to tackle code hot spots, dead services, and costs that make no sense.

Do not wait for perfect docs. Write the missing parts while people still remember the details. Even a one page note for deploys or database restore is better than another month of guessing.

If the gaps are larger than your team can close alone, bring in a short outside review. Oleg Sotnikov at oleg.is helps founders sort architecture, infrastructure, and team process after messy agency handoffs. A focused fractional CTO review can turn a confusing takeover into a clear repair plan.