Skip to content

Regenerating from agentic.config.json to see what upstream changed

There is no sync service and no template remote. Regenerate a clean copy from your recorded selection, diff it against your repo, and take only the agent layer.

Next.js on Vercel5 min readships at docs/solutions/nextjs-vercel/regenerate-from-config-and-diff.md

Tags: generator · upgrades · diffing · agentic-config · maintenance

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

PathSafe to takeWhy
.agents/hooks/ scriptsYes, unless you edited a scriptSelf-contained; verify after
.agents/rules/New files yes; changed files read firstYou may have tightened one
.agents/agents/, .agents/skills/Yes for new, read for changedSame
Copies in agent folders (.claude/skills/, .claude/agents/, .codex/agents/, .cursor/agents/, .github/agents/ and the like)Same as the .agents/ file they copyKeep 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 handMerged files; you may have added to them
AGENTS.md, root and nestedNo: apply by handYour rules live there
docs/solutions/Yes, alwaysAdditive knowledge, no behaviour
src/**, except its AGENTS.md filesNoThis is your product now
package.json, tsconfig.jsonNo: read and apply by handMerged files; you have added to them
README.md, .env.exampleNo: apply by handSame

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.