What to Include in a Lovable Handoff to an Agency

At some point most Lovable founders reach the same wall. The app is live, real users are inside it, and the next feature is the one Lovable keeps fumbling. You have talked to an agency, they have quoted the work, and now they are asking for access. If you have never handed a vibe-coded project to developers before, the instinct is to share everything at once. A Slack channel gets created, the Lovable owner seat gets transferred, Supabase gets a new owner, .env files move as screenshots, and before any code is written the founder has lost custody of their own product.

This is the package we ask founders to send when they engage WitsCode or any other agency to pick up a Lovable project. When the engagement ends, you should walk away with a stable product, a clean credential surface, and an AI iteration loop that still works.

The Three-Tier Credential Model

Before any access is shared, decide who holds what kind of credential. Most founders treat handoffs as binary. Either the agency has the key or they do not. That model leaks. A better model has three tiers.

The founder tier is credentials only you ever hold. Root passwords for your domain registrar, your personal GitHub, your Lovable account, the email that receives Stripe payouts, the 2FA recovery codes for Supabase ownership. The agency never sees these, not because you distrust them, but because you should not be lockable out of your own company by anyone.

The agency tier is credentials created for the engagement, scoped to what the agency needs, and revoked the day the engagement ends. Supabase seats set to Developer instead of Owner, GitHub access as a collaborator, Stripe restricted keys with only the endpoints in play, a separate Vercel or Netlify team membership. Each can be killed with one click.

The production tier is the credentials your app actually uses to run. Supabase service role key, Stripe secret, OpenAI or Anthropic keys, Resend or Postmark keys, webhook signing secrets. The agency will see these because the app cannot run without them. Assume they are exposed the moment you share them, and schedule a rotation for the day the engagement closes.

Repository Access Without Giving Up Ownership

The GitHub invitation is where most founders over-grant. Lovable writes to a repo that you own. The agency needs enough access to read, branch, commit, and open pull requests, not enough to transfer the repo, delete history, or change branch protection rules.

Add the agency as a collaborator with Write, not Admin. Turn on branch protection for main so nothing lands without a pull request. If you are nervous, use a fork-and-PR model where they work on their fork and you merge into yours. Slower, but the agency cannot touch your main branch without your click.

Alongside the repo, share a map. A README addendum that says "src/components/ui is shadcn and should not be edited directly, src/pages maps to routes, src/integrations/supabase regenerates from the schema, and anything Lovable generated that still works should stay as it is" saves three days of the agency learning that by breaking things.

Finally, tell them which branches Lovable is writing to. If you are still prompting in Lovable in parallel, it will push to main and clobber their work. Either stop prompting for the engagement, or have the agency work on a handoff/ branch and merge when they are done. Put this in writing.

Supabase Credentials and the Developer Role

Supabase is usually the most dangerous piece of a Lovable handoff because it holds real customer data. Invite the agency to the Supabase organization as a Developer, not Owner or Administrator. Developer role can read and write schema, branch, and run migrations. It cannot delete the project, change billing, or transfer ownership. That is the fence you want.

If the agency needs production data, clone the database into a new Supabase project and share that. If they need the real production project, turn on point-in-time recovery before the engagement so you can roll back a destructive migration. If your app has regulated PII, redact the clone before sharing.

The Supabase service role key is the nuclear credential and should only be shared through a password manager, never in chat. Create a shared 1Password vault, put the key there, share the vault. When the engagement ends, revoke the vault access and rotate the key.

Here is the credential handoff snippet we share with founders as a template.

Shared vault: witscode-<project>-handoff
  - SUPABASE_SERVICE_ROLE_KEY (rotate on close)
  - STRIPE_SECRET_KEY (restricted key, scoped)
  - OPENAI_API_KEY (new key issued for engagement)
  - RESEND_API_KEY (restricted to transactional domain)
  - SENTRY_AUTH_TOKEN (project-scoped)

Not in vault, founder holds only:
  - Domain registrar login
  - Lovable account login
  - Supabase org Owner seat
  - Stripe root account

That structure, copied into a document the agency receives on day one, removes ambiguity about who holds what.

Environment Variables and the .env.example File

Every Lovable project accumulates environment variables. Some are public and safe in the repo. Some are private and belong in the vault. Commit a complete .env.example with every key the app reads, plus a comment describing what each is for and where to get it. Actual values go in the vault.

A good .env.example for a Lovable project looks something like this.

# Public Supabase config (safe, already in client bundle)
VITE_SUPABASE_URL=
VITE_SUPABASE_ANON_KEY=

# Server-only Supabase
SUPABASE_SERVICE_ROLE_KEY=   # get from 1Password, rotate after handoff

# Stripe
VITE_STRIPE_PUBLISHABLE_KEY=
STRIPE_SECRET_KEY=            # restricted key for this engagement
STRIPE_WEBHOOK_SECRET=

# LLM
OPENAI_API_KEY=               # engagement-specific key

# Email
RESEND_API_KEY=

# App
APP_URL=http://localhost:5173

This file does two jobs. It tells the agency what the app needs, and it becomes the rotation checklist when the engagement ends.

Design Tokens and the Safe-to-Override List

The part of a Lovable handoff agencies get most wrong is design. A developer who has not worked in Lovable sees a tailwind config with custom colors, a globals.css with HSL variables, a shadcn components.json, and assumes they can move things around. Three days later your brand is gone, your buttons are off-brand blue, and the header spacing differs on every page.

Write down where every brand value lives, mark which ones are sacred and which are negotiable, and make the agency acknowledge both lists before they change a class.

The sacred list usually includes the primary brand color and its HSL triplet, the secondary accent, the logo path, the font family and weight scale, and the base spacing unit. Negotiable covers component border radii, shadow depths, transitions, and semantic colors like --destructive or --muted that can be tuned for accessibility. Add-freely is new semantic tokens for new features.

The template we share looks like this.

Design tokens, Lovable project <name>

Sacred, do not change without founder approval:
  tailwind.config.ts -> theme.extend.colors.brand
  src/index.css -> :root { --primary: 222 47% 11% }
  src/index.css -> :root { --background, --foreground }
  public/logo.svg
  Font stack: Inter, system-ui, sans-serif

Negotiable, flag before changing:
  --radius, component border radii
  Shadow depths in tailwind theme
  Transition durations
  --muted, --accent (accessibility-driven changes welcome)

Add as needed:
  New semantic variables for new features
  New component variants, as long as base variant is untouched

Do not introduce:
  New color systems (OKLCH, different scale)
  New spacing scales
  CSS-in-JS libraries (styled-components, emotion)
  Replacing shadcn components with a different library

This tells the agency, in one page, the difference between a change that is welcome and a change that will be rejected in code review. That alone saves hours of billed refactor.

The Known Issues and Do-Not-Fix Document

Every Lovable project has bugs the founder knows about. Some will be fixed, some will not. An agency that has not been told which bugs are intentional will find them, fix them, and invoice for work you did not want.

Organize in four categories. Known and will fix is the scope of the engagement, with tickets and repro steps. Known and do-not-fix is bugs you have left alone because the cost exceeds the value, the fix depends on an upstream change, or the behavior is intentional. Known and weird is code that works but looks strange, do not refactor without asking. Suspected and unconfirmed is flaky areas where the agency should log rather than fix on sight.

The template reads something like this.

Known issues, Lovable project <name>, updated <date>

Will fix (scope of engagement):
  BUG-01 Checkout fails on mobile Safari when coupon applied
  BUG-02 Dashboard chart re-renders on every keystroke
  BUG-03 Password reset email goes to spam

Do not fix:
  The /admin route renders twice on first load. Known, upstream
    Supabase auth race, patched by a reload. Leave it.
  Empty states show "Loading..." for 200ms before content. This is
    intentional to avoid layout shift.
  Some console warnings from shadcn dialog about nested buttons.
    Harmless, do not refactor the dialog tree.

Weird but works:
  src/lib/useSession.ts has two useEffects that look redundant.
    They are not. Both are needed, do not consolidate.
  The auth provider wraps routes twice. This fixes a Lovable
    regeneration quirk. Do not remove.

Tread carefully:
  The Stripe webhook handler has had flaky deploys. Test against
    the Stripe CLI locally before touching.
  RLS policies on the orders table are fragile, run the policy
    test suite after any schema change.

That document answers the question the agency will otherwise ask three weeks in, which is why nobody fixed the obvious thing. Writing it down once saves the conversation forever.

The Roadmap Priority List That Holds Scope

The only roadmap format that prevents scope creep is a three-column list of Now, Next, and Later. Without this, agencies cherry-pick the fun work or founders add scope mid-engagement and the timeline drifts.

Now is everything the agency is hired to ship in the first two weeks. Three to six items, each with a one-sentence acceptance criterion. Next is weeks three to six, the work that happens if the first phase goes well. Later is everything else, where good ideas wait their turn.

A clean roadmap document looks like this.

Roadmap, <project>, engagement starting <date>

Now (weeks 1-2, scope of this engagement):
  1. Ship multi-tenant workspaces. Accept = user can create a
     workspace, invite members, switch between them.
  2. Fix mobile checkout bug (BUG-01).
  3. Move transactional email from Lovable default to Resend.
  4. Add Sentry error tracking.

Next (weeks 3-6, separate engagement if agreed):
  1. Usage-based billing on Stripe.
  2. Public API with key management.
  3. Admin impersonation for support.

Later (backlog, not in scope):
  SSO and SAML, AI-generated reports, white-label,
  mobile app, integrations marketplace.

Anything outside the Now column is a change order, priced separately, scheduled separately. The agency knows this on day one. You know this on day one. The first time a new feature request comes up mid-engagement, you point at the document together and decide whether it is worth disrupting the plan.

The Rotation Nobody Warns You About

Here is the step most founders miss and most handoff checklists omit. The day the engagement ends, you rotate every credential the agency touched. Not the day after you get nervous. Not the day the last invoice clears. The day the work is done.

The reason is boring and unavoidable. Credentials leak. Not maliciously, usually. A .env file sits in a developer's home directory. A Slack message with a key in it is scrolled past and indexed. A screen share catches a terminal window with a token visible. A laptop gets sold. None of these are the agency doing anything wrong. They are just the statistical reality of any credential that has been touched by more than one person.

Schedule the rotation in your calendar on day one of the engagement, timed for the day the contract ends. The rotation list is the .env.example file you prepared at the start. You walk down it, rotate each private value in the relevant dashboard, update the vault, and redeploy. Supabase service role, Stripe secret, webhook signing secrets, LLM API keys, email API keys, Sentry tokens, anything the agency had visibility into. It takes an hour. It prevents a year of quiet risk.

Then you revoke the access. Remove the agency from the GitHub collaborator list, from the Supabase org, from the Vercel team, from the shared vault. Archive the Slack channel. Keep the Loom recordings and the documentation they produced. The relationship does not have to end, but the credential surface has to close.

The package we have described, repository access, Supabase seats, environment example file, design tokens document, known issues list, roadmap, credential vault, and rotation schedule, is what WitsCode asks every Lovable founder to assemble before we start work. Most founders do not have it when they reach out. We help them build it during the first week, which means the first week is mostly setup rather than shipping. That is fine. A Lovable handoff that starts with clear access and clear scope ships faster over a six-week engagement than one that starts with a shared .env in a Discord DM and hopes for the best.

If you are about to hand a Lovable project to a developer or an agency and you would like us to either do the work or audit the package you are about to send, book a call at witscode.com. We take the last mile from vibe code to maintainable product, and we do it without asking for your Lovable seat or your Supabase ownership. Start here >