Docs · Maintenance

Keeping your app up to date with the org build

How to pull the latest official LeadStack build into your own customised version of the app — without losing the changes you've made.

The easy way: ask Claude Code

If you set this app up with Claude Code, you don't need to run any of the git commands below by hand. Open Claude Code in your project folder and paste this:

Update my app to the latest official build from the upstream
template, keeping all of my customisations. Set up the upstream
remote and vendor branch if they aren't already there, merge in
the new release, and help me resolve any conflicts. Then run
pnpm install and tell me if there are any new environment
variables or Firestore rules/indexes I need to deploy.

This runs the exact same git steps described in the rest of this page — Claude just handles the fiddly vendor-branch and merge work for you, and walks you through any conflicts in plain English. For most people this is the smoother path; the manual steps below are here so you can understand what's happening (and for anyone who'd rather drive it themselves).

Whichever way you update, do the after-updating checklist when it finishes — the most important part is confirming your own changes are still there.

The mental model

Prefer to do it by hand, or want to understand what Claude Code is doing under the hood? Here's the whole picture. There are three things in play:

Name	What it is	Git term
Org repo	The official LeadStack build. A read-only snapshot you don't push to.	`upstream`
Your fork	Your personal copy on GitHub, where your work lives.	`origin`
Your customisations	The edits you make on your `main` branch.	your commits

The org repo is published as a single snapshot commit that gets replaced each release. It has no shared history with your fork, so you cannot just git pull from it. The steps below give git the shared reference point it needs to merge cleanly.

One-time setup (do this once per machine)

# 1. Add the org repo as a second remote called "upstream"
git remote add upstream https://github.com/Claude-Code-Pro-Camp/leadstack-agency.git

# 2. Fetch its current snapshot
git fetch upstream

# 3. Create a local "vendor" branch that mirrors the org snapshot.
#    This branch is the shared reference point for future merges.
git branch vendor upstream/main

You now have:

origin → your fork (where you push)
upstream → the org repo (read-only)
a vendor branch tracking the org snapshots

Each time you want the latest org build

Always start from a clean working tree — commit or stash your work first.

# 1. Get the newest org snapshot
git fetch upstream

# 2. Move the vendor branch up to the new snapshot's contents
git checkout vendor
git read-tree -u --reset upstream/main
git commit -m "vendor: latest org snapshot"

# 3. Merge it into your own branch (this preserves YOUR changes)
git checkout main
git merge vendor

# 4. Refresh dependencies in case they changed
pnpm install

That's it. Your customisations and the new org code are now combined.

If you see merge conflicts

A conflict only happens where you and the org edited the same lines. Git marks them like this:

<<<<<<< HEAD
your version
=======
org version
>>>>>>> vendor

To resolve:

Open each conflicted file and edit it to the version you want (delete the <<<<<<<, =======, >>>>>>> markers).
Then finish the merge:

git add -A
git commit

Tip: git status always lists which files still need attention.

After updating — don't forget

Confirm your own changes survived — run git log --oneline -15 and check you still see your commits mixed in with the new org ones. This is the one step that tells you the update merged your work rather than overwrote it.
pnpm install — pulls any new dependencies the update added.
Check .env.example — new features sometimes add new environment variables. Compare it against your real .env and fill in anything new.
Deploy Firestore rules + indexes if the release added a feature that needs them: firebase deploy --only firestore:rules,firestore:indexes. When in doubt, run it — it's harmless if nothing changed, but skipping it when a new feature needs an index makes that feature fail at runtime.
Test the app (pnpm dev) before pushing.
Push to your fork when happy: git push origin main
(This goes to YOUR repo, never the org repo.)

Quick reference

I want to…	Command
See my branches and where they point	`git branch -vv`
See which remotes I have	`git remote -v`
Check for uncommitted work	`git status`
Get the latest org build	the 4 steps above
Preview what a push would send	`git push --dry-run origin main`

Common questions

Can I just let Claude Code do the update instead of running these commands?

Yes — and for most people that's the recommended way. See The easy way above. It runs the identical git steps, just without you typing them. Afterwards, still run the after-updating checklist.

The manual git steps aren't working for me. Am I stuck?

No. The vendor-branch / read-tree steps trip a lot of people up, which is exactly why the Claude Code path exists — paste the prompt from The easy way and it'll set up whatever's missing and merge for you.

Does pushing send my code to the org repo?

No. git push goes to origin — your personal fork. The org repo is upstream and is read-only to you.

What if I haven't customised anything yet?

The merge still works; there just won't be any conflicts.

I messed up a merge — how do I bail out?

Before committing: git merge --abort returns you to where you started.