Three months after generating your repo, the boilerplate upstream has improved. Two new guard hooks. A rule that catches a mistake your team made twice. Eight new solution docs for the batteries you selected. You would like those.
What you would not like is anything touching src/, which is now 40,000 lines
of your product and shares almost nothing with what was generated.
Every mechanism people reach for here makes that trade badly.
The wrong ways
Add the boilerplate as a git remote and merge. The generated repo was never a fork: it is the output of a program run with your selection. Your first commit is a squashed snapshot with no shared ancestry, so a merge is a several-hundred-file conflict in which every hunk is a manual decision.
Regenerate over the top of your repo. Some generators support this. It
overwrites package.json, AGENTS.md, .env.example and every merged file,
losing the dependencies you added and the rules you wrote. You find out which
ones tomorrow.
Copy files across by hand from memory. You get the three you remember and miss the two that mattered, and there is no record of what you skipped, so the next person starts from zero.
The right way: regenerate beside, diff, copy deliberately
agentic.config.json, committed at the root of your repo, records exactly what
was generated: the selection, the resolved plugin ids, the layer counts, and a
content hash.
{
"version": 1,
"selection": {
"projectName": "acme",
"stack": "nextjs-vercel",
"pm": "bun",
"batteries": ["better-auth", "neon", "prisma", "stripe"],
"design": "editorial",
"mode": "team",
"targets": ["claude", "codex", "cursor", "copilot"],
"admin": true
},
"plugins": ["nextjs-vercel", "neon", "prisma", "better-auth", "stripe", "editorial"],
"counts": { "agents": 6, "skills": 11, "rules": 14, "hooks": 8, "solutions": 27, "mcp": 3 },
"hash": "9f2c…"
}
targets lists the coding agents that get their own config files: any of
claude, codex, cursor, copilot, antigravity, gemini, opencode,
jetbrains, windsurf and kiro. AGENTS.md and .agents/ ship whatever it
says.
Because generation is deterministic (no timestamps, no random ids, sorted keys) the same config always produces byte-identical output. That is what makes a diff meaningful: every difference is either an upstream change or a change you made. Nothing is noise.
1. Regenerate into a sibling directory
Ask the builder for a fresh copy of your selection. POST the selection from
agentic.config.json to the plan API, and open the builderUrl it returns:
curl -s https://agenticboilerplate.com/api/v1/plan \
-H 'content-type: application/json' \
-d "$(jq '.selection' agentic.config.json)"
Sign in with the email you bought with, download the zip, and unzip it next to
your repo as ../acme-upstream. Rebuilding costs nothing extra: it is the same
selection, on the latest version.
Never into your repo. The point is to produce a clean reference copy to compare against.
2. Diff the agent layer only
diff -ru --new-file ./.agents ../acme-upstream/.agents | less
diff -ru --new-file ./docs/solutions ../acme-upstream/docs/solutions
# every AGENTS.md, root and nested
for f in $(cd ../acme-upstream && find . -name AGENTS.md -not -path '*/node_modules/*'); do
diff -u --new-file "$f" "../acme-upstream/$f"
done
.agents/ is the shared layer: rules, skills, subagents and guard hooks. Each
agent's own folder (.claude/, .codex/, .cursor/, .github/agents/ and
the rest) holds copies of it for agents that read only their own folder, plus
that agent's hook and MCP config. Diff the ones your repo has the same way.
Read it in three passes: files present upstream and absent locally (new rules, hooks, docs (usually pure gain); files present locally and absent upstream (yours, keep them); files present in both and different (the only ones needing thought) did you edit it, or did upstream?).
3. Copy what is safe
| Path | Safe to take | Why |
|---|---|---|
.agents/hooks/ scripts | Yes, unless you edited a script | Self-contained; verify after |
.agents/rules/ | New files yes; changed files read first | You may have tightened one |
.agents/agents/, .agents/skills/ | Yes for new, read for changed | Same |
Copies in agent folders (.claude/skills/, .claude/agents/, .codex/agents/, .cursor/agents/, .github/agents/ and the like) | Same as the .agents/ file they copy | Keep each copy identical to .agents/ |
Hook and MCP configs (.agents/hooks/guards.json, .claude/settings.json, .codex/hooks.json, .cursor/hooks.json, .mcp.json and the rest) | No: copy entries by hand | Merged files; you may have added to them |
AGENTS.md, root and nested | No: apply by hand | Your rules live there |
docs/solutions/ | Yes, always | Additive knowledge, no behaviour |
src/**, except its AGENTS.md files | No | This is your product now |
package.json, tsconfig.json | No: read and apply by hand | Merged files; you have added to them |
README.md, .env.example | No: apply by hand | Same |
A copy that is genuinely safe:
# new hooks and rules only: never overwrites a file you have edited
cp -rn ../acme-upstream/.agents/hooks/. ./.agents/hooks/
cp -rn ../acme-upstream/.agents/rules/. ./.agents/rules/
cp -rn ../acme-upstream/docs/solutions/. ./docs/solutions/
cp -n never overwrites. Anything it skipped is a file that exists in both and
needs a human decision: go back to the diff for those, one at a time.
Most agents only see a new rule through an AGENTS.md. Copy its section (or
its link line) from the upstream AGENTS.md that has it into yours, by hand,
plus any glob-scoped copy upstream made for it (.claude/rules/<id>.md,
.cursor/rules/<id>.mdc and the like).
4. Wire up and verify
A new hook script is inert until a hook config references it. Add its entry
to .agents/hooks/guards.json and to each agent's hook config your repo has
(.claude/settings.json, .codex/hooks.json, .cursor/hooks.json,
.github/hooks/agentic-guards.json, .gemini/settings.json,
.agents/hooks.json, .devin/hooks.v1.json). Copy each entry from the matching
upstream file by hand. Those files are merged, so never replace one wholesale.
Then:
bun run verify:hooks
bun run typecheck
bun run lint
bun run test
verify:hooks is the one that matters here: it attempts each blocked action and
confirms it was stopped, which is the only proof a newly copied guard is
actually wired in.
5. Commit it separately
git checkout -b chore/upstream-agentic-layer
git add .agents docs/solutions # plus each AGENTS.md and agent folder you changed
git commit -m "chore(agentic): pull upstream rules, hooks and solution docs"
One commit, nothing else in it. If a new guard turns out to be wrong for your repo, you revert one commit rather than untangling it from a feature.
Then delete ../acme-upstream. It is a scratch artefact: regenerating it again
costs seconds, and keeping it around invites someone to edit the wrong copy.
Checking whether anything changed at all
The hash in agentic.config.json is a sha256 over the sorted (path, content)
pairs of the generated output. Regenerate and compare:
Regenerate as in step 1, then:
diff <(grep '"hash"' agentic.config.json) <(grep '"hash"' ../acme-upstream/agentic.config.json) \
&& echo "identical: upstream has not changed for this selection"
Same hash, nothing to do. Worth running monthly; it takes a minute and answers the question honestly.
Two caveats
Changing the selection is not an upgrade. Adding a battery to
agentic.config.json and regenerating produces files for a battery your src/
has never integrated with. Add batteries deliberately, one at a time, reading
their onboarding steps, not through a diff.
Keep agentic.config.json committed and current. It is the only record of
what this repo was generated from. If someone deletes it, this entire workflow
stops being available, and reconstructing the selection from the file tree is
guesswork.
A one-step upgrade that does the compare-and-report for you is on the roadmap. Until then the commands above are the whole mechanism, and they work today.