Skip to content

Upgrade an Onboarded Repo

In plain English

You onboarded a repo onto an older CortexBuild. A newer cortexbuild-core is now installed. This page is the one-command runbook to re-sync your repo's rendered agent files to the latest pack — safely, validated, and fully reversible — without losing the rules you curated, the agents you customised, or the learning your repo accumulated.

The whole upgrade is a single command with three modes:

cortexbuild upgrade              # 1. PREVIEW  (default — writes nothing)
cortexbuild upgrade --apply      # 2. APPLY    (snapshot → render → validate)
cortexbuild upgrade --rollback   # 3. ROLLBACK (byte-identical restore)

Do I need to re-render after every upgrade?

Don't decide by hand — run cortexbuild upgrade and let it decide. The answer is a command, not a judgement call, and the command is safe to run even when nothing substantive changed.

The deterministic procedure after installing a newer cortexbuild-core:

  1. cortexbuild upgrade (preview — writes nothing). It reports the framework version transition and whether a re-render would overwrite any file you hand-edited.
  2. If the preview is clean (no hand-edited owned files) → cortexbuild upgrade --apply. Apply is snapshot → render → validate, so it is always safe and fully reversible — even when the only real change is a cosmetic version stamp.
  3. If the preview flags hand-edited owned files → it is fail-closed; resolve per Step 3 — The hand-edited-agent case (below) before applying.

Don't try to read cortexbuild render --check drift as your signal

The framework version is stamped into every rendered file, so cortexbuild render --check reports drift after any version bump — even when no rule changed. That drift is expected and does not by itself mean a rule changed. Never try to classify "cosmetic version stamp vs real rule change" by eye. cortexbuild upgrade --apply re-stamps, re-renders, and re-validates in one safe, reversible step, so the distinction never has to be made by hand. render --check is a CI drift gate; upgrade is the post-upgrade decision-maker.

For an AI agent / automation — a runbook to follow verbatim

After any cortexbuild-core version change:

  1. Run cortexbuild upgrade --json (preview; writes nothing).
  2. If hand_edited_owned is empty and blocks_without_confirm is false → run cortexbuild upgrade --apply and confirm the result reports validated: true. Commit the regenerated surfaces as their own change.
  3. If hand_edited_owned is non-empty → STOP and surface the list to a human. Do not pass --confirm autonomously (that would overwrite hand-edits; a snapshot is taken, but a human should decide). Prefer moving the edits into source (repo-local overrides / custom agents) first.

The --json output (from_version, to_version, hand_edited_owned, blocks_without_confirm, validated) is the deterministic signal — no guessing, no eyeballing drift.

Why an upgrade needs more than render

A plain cortexbuild render re-renders the latest pack — but on a repo a customer has lived in, three things must be protected:

Customer asset Where it lives How the upgrade protects it
Curated / removed rules, repo-local overrides .cortexbuild/rules/ Preserved; counted in the preview
Custom agents (e.g. vision-ai-engineer) .github/agents/, .claude/agents/ Not CortexBuild-owned ⇒ never touched
Hand-authored prose outside managed regions in copilot-instructions.md / AGENTS.md / CLAUDE.md Managed-region write contract preserves it
Learning .cortexbuild/recurrence-ledger.yaml, adaptive selection, skills, eval trend Pure customer data — carried forward untouched
Hand-edits to generated files a CortexBuild-owned file the customer edited The one lossy case — the upgrade detects it and fails closed

The last row is the crux of the question "what about changes made to the agents during execution and learning?" — handled explicitly below.

Step 1 — Preview (writes nothing)

cortexbuild upgrade --repo-root .

The preview reports the framework version transition, the rules in the latest pack, the learning artefacts that are carried forward, and — most importantly — any CortexBuild-owned files you hand-edited that a re-render would overwrite. If that list is empty, the upgrade is a clean, safe re-render. If it is not, apply is fail-closed (see Step 3).

Step 2 — Apply (snapshot → render → validate)

cortexbuild upgrade --apply

--apply performs, in order:

  1. Snapshot — an atomic, byte-exact copy of the reversible surface (.cortexbuild/ownership.json, .cortexbuild/rules/, and every render target: Copilot / Codex / Claude / Cursor) into .cortexbuild/upgrade-backups/.
  2. Render — the non-destructive managed re-render (user prose preserved, pruning scoped to CortexBuild-owned files only, custom agents untouched).
  3. Validate — a post-render drift check that must come back in sync. The result and a cortexbuild upgrade --rollback recipe are written to .cortexbuild/UPGRADE_REPORT.md. A failed validation exits non-zero.

Step 3 — The hand-edited-agent case (fail-closed)

If you edited a generated agent file directly (the only way an upgrade can lose work), the preview flags it and apply refuses:

✗ upgrade blocked: 2 CortexBuild-owned file(s) were hand-edited and would be
  overwritten by the re-render. Re-run with --confirm (a pre-upgrade snapshot is
  taken so the edits remain recoverable), or move those edits into source first.

You then have two correct paths:

  • Recommended — move the edit into source. Put the customisation where it survives every future upgrade: a repo-local rule override (.cortexbuild/rules/) or a custom agent file (a new *.agent.md that isn't a CortexBuild persona, so it is never owned/overwritten). Re-run the preview; it should now be clean.
  • Proceed under snapshot. cortexbuild upgrade --apply --confirm takes the pre-upgrade snapshot first, so even though the re-render overwrites the edit, cortexbuild upgrade --rollback restores it byte-for-byte.

The durable rule

Edit the source, never the rendered output — the same SSoT→render discipline the framework enforces on itself. Customers who maintain heavy agent customisation should keep it in repo-local overrides + custom agents, so upgrades are always conflict-free.

Step 4 — Rollback (byte-identical)

Any time after an apply:

cortexbuild upgrade --rollback                 # latest snapshot
cortexbuild upgrade --rollback --backup-id pre-upgrade-0001

Rollback restores the captured paths exactly and removes files the upgrade newly created — the repo returns to its precise pre-upgrade state.

Worked example — CortexVigil

CortexVigil onboarded onto an older CortexBuild and customised its agent surfaces (AGENTS.md, CLAUDE.md) with project-specific instructions, plus a custom vision-ai-engineer agent. The upgrade flow there:

cd /path/to/cortexvigil

# 1. Preview — surfaces the customised owned files instead of clobbering them.
cortexbuild upgrade
#   framework: 0.0.1 → 0.0.1   (re-sync to latest content)
#   recurrence ledger: preserved · repo-local rule overrides: preserved
#   ⚠ owned files hand-edited (would be overwritten): AGENTS.md, CLAUDE.md
#   → apply is fail-closed; use --apply --confirm (snapshot) or move edits to source

# 2. Prove reversibility end-to-end (safe even on a customised repo):
cortexbuild upgrade --apply --confirm     # snapshot + render + validate (PASS)
cortexbuild upgrade --rollback            # restore byte-identically
git status --porcelain                    # → empty: repo is exactly as before

The preview is the honest, non-destructive default: it caught CortexVigil's customisations rather than overwriting them. The apply→rollback round-trip proves the upgrade is fully reversible even when the customer has diverged — which is exactly the guarantee an enterprise upgrade needs.

What the upgrade never touches

  • .cortexbuild/recurrence-ledger.yaml and the eval/conformance trend — your accumulated learning.
  • Custom (non-CortexBuild) agent files and repo-local rule overrides.
  • Any byte outside a CortexBuild managed region in a shared file.
  • Connections / keychain references and the standards lock.

Rollback safety net at a glance

flowchart LR
  P[preview] -->|clean| A[apply: snapshot → render → validate]
  P -->|hand-edits| C{move to source?}
  C -->|yes| P
  C -->|no| AC[apply --confirm: snapshot first]
  A --> V{validated?}
  AC --> V
  V -->|yes| Done[in sync ✓]
  V -->|no| R[rollback → pre-upgrade state]