Receive base updates

This page is about pulling a new base release onto your own copy. You need this flow when a new skill lands in the base, when an automation hook gets improved, or when the AI-facing domain rules (AI_AUTOMATION.md) get refreshed.

The reason to receive updates is one line. The base is the starting point your work piles on top of, but the base itself keeps improving — and if you do not pull those improvements, your copy gets frozen in time. You do not have to receive every update. Roughly once a month, or when the base side sends out a “new skill available” notice.

The flow is designed so a non-developer can run it. No git rebase to memorize. You just tell Claude Code or Codex “pull the base update,” and the tool walks the rest.

One-time — register the base remote

This registration is a one-off per machine. From then on, every update call rides on top of it.

Open a terminal, head into your SaaS folder, and run:

git remote add base https://github.com/ddakit/saas-base.git

The command prints nothing on success. That is fine. To confirm the register went through:

git remote -v

The healthy output looks like:

base    https://github.com/ddakit/saas-base.git (fetch)
base    https://github.com/ddakit/saas-base.git (push)
origin  ...your repo URL...

Four lines, two each for base and origin — that is the end of the step. If this is your first time, you can also type /update-from-base into Claude Code. On the very first call, if the base remote is not registered yet, the tool walks you through running the line above.

When something is off

fatal: remote base already exists means the register is already done. Move on to the next section.

Permission denied means your license has expired or you do not have access to the base repo. Contact the base maintainer.

Pull an update

Once the register is done, every subsequent run is one line. In the Claude Code or Codex chat, type one of:

/update-from-base

Or in plain words:

pull the base update

Both produce the same result.

Once invoked, the tool walks the following sequence. Each step lists what should show on screen when it is healthy, so you can follow along by line:

1. Check for unsaved changes

The tool first checks if there are uncommitted changes in your work. If there are:

You have unsaved changes. Commit them or stash them first to be safe.
Stash with git stash for now?

yes stashes them aside. After the update wraps, git stash pop brings them back. This is the safe path, and recommended.

2. Summarize what changed in the base

The tool fetches new commits from the base remote, then groups what touches your copy by area:

Base update summary (new changes since last sync)

Newly added skills (auto-applicable)
- 2

Updated base files (auto-applicable)
- .claude/skills/ (3 updated)
- .claude/hooks/ (1 updated)
- AI_AUTOMATION.md (✓ updated)

Needs manual confirm (may conflict with your edits)
- CLAUDE.md
- README.md

Proceed? (yes / no / show-diff)

yes applies every auto-applicable area in one pass. The base owns these seats as SSOT, so overwriting them does not erase your work.

show-diff shows which lines change. For the first one or two updates, run show-diff first to get a feel for the deltas, then yes on the next pass.

no exits without applying. The next call shows the same deltas again.

3. Files needing manual confirm — one of two

CLAUDE.md and README.md both can be edited by the base side and by you, so they do not get overwritten automatically. The tool asks per file:

CLAUDE.md — base updated and you may have edits, so it was not auto-applied.
Pick one of three:

1. Overwrite with the base version entirely (your edits go away)
2. Take only the base's changes (3-way merge — you resolve any conflicts)
3. Leave it for now (decide next time)

For a first time, option 1 is usually the answer. If you have not touched the file, the base version is the latest one. If you have, your edits are usually a short note or two — easy to write back.

Option 2 is when your edits are long and you want them preserved. The merge sometimes lands conflict markers (<<<<<<<, =======, >>>>>>>) in the file. When that happens, the tool tells you where, and you decide which version to keep. For a first time, this path is too much in one shot — option 1, then rewrite your note, is faster.

Option 3 is when you want to decide later. The next call asks the same question again.

README.md is the one phase 6 (/6-cleanup-residue) rewrites with your SaaS name and description, so an overwrite with the base version erases your SaaS name. This file usually goes “leave it for now” and you copy the base changes in by hand later.

4. Post-apply check

The tool sweeps the applied files once more. If hook (.sh) files updated, it reattaches execute permissions; it confirms settings.json did not break; if new skills came in, it lists the trigger keywords for each. The output ends like:

✓ Base update applied
2 new skills, 7 files updated
commit hash: a3f9c21

If you see this, the run is done.

5. Commit

The tool asks at the end:

Commit the changes?
Suggested message: "chore(base): sync to a3f9c21 (7 files)"

yes commits automatically. no lets you write the message by hand and commit yourself.

A pause before pulling

You do not have to pull every update. Two seats are worth pausing at.

If you have ever edited base code by hand, pause once. For example, if you modified a skill under .claude/skills/ directly, the auto-update overwrites that edit. The tool flags the file as mixed and asks again, but going in aware is safer. The recommended pattern is not to edit base skills directly — instead, create your own copy under your team’s directory (e.g. .claude/skills/my-team-{name}/) using the same trigger keyword.

If a piece of work is in flight and you mean to commit it within the hour, finish that commit first and then pull. Stashing also works, but if your stashed work touches the same lines as the base update, you hit a conflict on stash pop. That conflict is one of the hardest seats for a non-developer to resolve, so wait until work is at a stable seat to pull.

Right before a production deploy, pause once more. If the base update touched a security seat (webhook verification logic, an RLS policy skeleton), a production migration may be required. Apply to staging first, run a cycle, then ship to production.

When something broke

If a build breaks or a command stops working after the update, walk this order.

First, revisit the environment-setup section in 09-troubleshooting.md. The base may have started requiring Node 22 or a new version of a tool.

Next, revert the applied commit outright. The one line that reverts the latest update commit:

git revert HEAD

That creates a new commit reverting what the update brought in. Your own work stays untouched, and the base update can be re-pulled on the next call.

Rare situations like a force-push are caught by the tool, which stops and surfaces guidance. If that notice lands, do not push further — forward the message to the base maintainer as is.

Next

Once the update lands, confirm your SaaS still runs. Bring up pnpm dev, hit http://localhost:5173, run a quick lap — signup, login, the first screen of checkout (Stripe Checkout). If any step fails, compare against the healthy-shape descriptions in 03-first-run.md or 04-real-backend.md.

If your deployed SaaS receives an update, run a cycle on staging first, then run the 08-distribution.md flow again to apply to production. When the auto-update touched a security seat, staging validation comes before production rollout.