Skip to content
Back to skills

Migration Upgrade

ASecurity

Upgrade a forge project to a newer forge binary version — version pinning in forge.yaml, the per-version migration skills, the supported upgrade window (N minors back), and the compatibility policy (semver at major 1; what a major owes you).

  • 10 stars
  • 0 votes
  • 0 copies
  • 1 view
  • Added November 13, 2026
developmentgoshellbashnodedockergitapifrontend

Works with

  • cli
  • api

Security analysis

A100/100

Scanned November 13, 2026

npx -y skills add reliant-labs/forge --skill migration-upgrade --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Migration Upgrade?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Migration Upgrade
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/reliant-labs-migration-upgrade/badge)](https://www.skillsdirectory.com/skills/reliant-labs-migration-upgrade)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: migration-upgrade
description: Upgrade a forge project to a newer forge binary version — version pinning in forge.yaml, the per-version migration skills, the supported upgrade window (N minors back), and the compatibility policy (semver at major 1; what a major owes you).
---

# Upgrading a forge project

Use this skill when the forge binary on your PATH is newer than the
`forge_version` recorded in `forge.yaml`, or when `forge generate` warns
about a version mismatch.

## How forge tracks versions

Every `forge.yaml` carries a `forge_version` field set at scaffold time
to the version of `forge project new` that produced the project.

For a project whose `go.mod` requires `github.com/reliant-labs/forge` (every
service project), the pin **follows go.mod**: bumping forge is

```bash
go get github.com/reliant-labs/forge@vX.Y.Z && go mod tidy
forge generate        # converges forge.yaml's forge_version to vX.Y.Z
```

`forge generate` rewrites that one scalar and says so (`📌 forge_version … →
vX.Y.Z`). It never writes the version of the forge binary running it — only
the version go.mod names, which every clone resolves identically. The one
exception is a hop `forge project upgrade` has to walk (a codemod, a
migration this project still needs, or more minors than the supported
window): generate leaves the pin, prints why, and names `forge project
upgrade`.

For a CLI or library whose go.mod does not require forge, `forge.yaml`'s
`forge_version` IS the pin (CI installs that version), and only `forge
project upgrade` moves it.

Legacy projects that predate the field are treated as `0.0.0`. They
get a one-time nudge from `forge generate` to run `forge project upgrade` so
the baseline can be pinned.

## The supported upgrade window

forge supports upgrading from at most **2 minor releases back** in a
single run (the Istio model). A project further back does a **staged
upgrade**: step to an intermediate release first, then continue.

```
v0.3  v0.4  v0.5  v0.6  v0.7        binary: v0.7
 │                 └──────┴─ project at v0.5: inside the window, one step
 └─ project at v0.3: 4 minors back — stage through v0.5 first
```

Attempting too large a jump is refused with the intermediate version
named:

```text
$ forge project upgrade --to v0.7.0
  v0.3.0 is 4 minor releases behind v0.7.0 — at most 2 minors back
  is supported in one step

  staged upgrade: run 'forge project upgrade --to v0.5' first, then
  re-run the original command
```

Why a window at all: each migration is written against the shapes of the
releases inside it. Migrations compose multiplicatively — N releases back
is N playbooks that must all still apply cleanly, in order, to a tree
none of their authors ever saw. Bounding N is what keeps the registry
small enough that every migration in it is still true.

## How to upgrade

```bash
# Inspect the current pin and the binary version.
grep forge_version forge.yaml
forge version

# A project whose go.mod requires forge: bump it there first.
go get github.com/reliant-labs/forge@vX.Y.Z && go mod tidy

# See which migrations this project actually needs.
forge project upgrade list

# Preview what the upgrade would change.
forge project upgrade --dry-run        # alias for --check

# Apply.
forge project upgrade                  # bumps to the binary's version
forge project upgrade --to v0.5.0      # bumps to a specific version

# Force-overwrite user-modified frozen files (rare; usually you want
# to inspect the diff first and reconcile manually).
forge project upgrade --force
```

`forge project upgrade` is one verb that applies every mechanical fix forge
knows for the range the pin crosses, in this order:

1. **modules** — `go get` / `go mod tidy` the forge requirement of every
   module that has one.
2. **codemods** — the `forge fix <name>` codemods keyed to the releases the
   range crosses (the ones marked to run on every crossing). A pin to a
   pre-release of a release (a Go pseudo-version of main) crosses that
   release's codemods too.
3. **templates** — frozen Tier-2 files diffed against the latest templates;
   unmodified files are auto-updated, modified ones are reported and kept
   (`--force` adopts them). A Tier-2 file the project does NOT have is added
   only when its template is new across the range (first shipped after the
   old pin) and nothing stands in for it. It is never added when the project
   deleted it (the scaffold ledger, `forge project disown --absent`, or git
   history says so) or has its own variant beside it (`eslint.config.js` for
   `eslint.config.mjs`, `compose.yaml` for `docker-compose.yml`). An older
   template the project never had is offered, not written:
   ``in templates since vX: <file> — `forge project rescaffold <file>` to add it``.
4. **pin** — `forge_version` in `forge.yaml` moves to the target.
5. **playbooks** — each crossed playbook's `automation:` steps (a playbook
   declares `fix:<codemod>` for the steps that are mechanical). A playbook
   whose detection still matches afterwards is left for a person.
6. **vendored-contracts** — see below.
7. **generate** — `forge generate`.
8. **locks** — a lockfile that disagrees with its `package.json` (generate
   edits dependency ranges) is refreshed by the package manager.
9. **lint** — `forge lint --json`. Errors are what is left for a person;
   findings of a rule still in its warn-first grace are listed as upcoming,
   with the release they gate from.

A codemod that replaces files you own (it cannot be reviewed except as a
`git diff`) only runs over a clean tree: upgrade leaves it and reports it under
"Still needs a person" rather than rewrite uncommitted work. `--allow-dirty`
runs it anyway. The pin files a bump itself edits (`go.mod`, `go.sum`,
`go.work`, `forge.yaml`) do not make a tree dirty.

`--check` (alias `--dry-run`) writes nothing and runs neither generate nor
lint; it still names each codemod rewrite and lockfile it would touch.
`--skip <phase>` (repeatable) omits `codemods`, `playbooks`, `vendored-contracts`,
`generate`, `locks` or `lint`; `modules`, `templates` and `pin` always run. It is how
a big rewrite goes into its own PR: `--skip playbooks` leaves the codemods a playbook
automates (`connect-errors`, `composition-graph`) for `forge fix <name>` on a branch
of their own, and `--skip codemods` does the same for the registry codemods the range
crosses. The pin moves in the same run, so a skipped codemod is not picked up by the
next upgrade: the skipped phase's `detail` in `--json` names each to run yourself.

### Exit codes and `--json` — the contract a pin bot calls

| Exit | Meaning | The caller |
| --- | --- | --- |
| `0` | Converged: every fix applied, nothing left for a person. | Merge candidate. |
| `1` | Failed: an error stopped the run (generate failed, a codemod errored, a bad flag, a staged-upgrade refusal). | Read `error`; do not retry blindly. |
| `2` | Could not determine: a package manager or registry could not be reached, or lint printed no readable verdict. | Retry. |
| `9` | Needs a person: everything mechanical is applied and `needs_human` is not empty. Re-running changes nothing. | Open the PR as a draft with `needs_human` in the body. |

`forge project upgrade --json` prints **one** document on stdout (human
progress goes to stderr), for a failing run too, so the caller can read what
was applied before the failure. Schema `forge-project-upgrade/v1`:

```json
{
  "ok": true, "exit_code": 0, "error": "",
  "schema": "forge-project-upgrade/v1",
  "mode": "apply",
  "from": "v0.1.45", "to": "v1.0.0",
  "converged": true,
  "phases": [{"name": "codemods", "status": "done", "detail": ""}],
  "codemods": [{"name": "operatorkit", "version": "v0.1.46", "source": "upgrade",
                "rewrites": ["internal/legacyops/ops.go: …"], "next": [], "blocked": []}],
  "locks": [{"path": "frontends/web/package-lock.json", "runner": "npm",
             "details": ["…"], "pending": false, "refreshed": true}],
  "playbooks": [{"id": "v1.0.0", "automation": ["fix:composition-graph"], "resolved": true}],
  "vendored_contracts": [{"name": "controlplane", "status": "lag", "revendored": true}],
  "needs_human": [{"kind": "lint-error", "rule": "forgeconv-…", "file": "internal/x.go",
                   "line": 7, "message": "…", "fix": "…"}],
  "upcoming": [{"rule": "forge-frontend-lock-drift", "count": 1, "introduced_in": "v1.0.0",
                "gates_from": "v1.0.1", "fix": "…", "examples": ["…"]}],
  "template_drift": ["Dockerfile"],
  "offers": [{"path": "docker-compose.yml", "since": "v0.0.2",
              "command": "forge project rescaffold docker-compose.yml"}]
}
```

- `ok` and `exit_code` are the process's own: `ok` is true exactly when the exit
  is 0. Every list is an array, never `null`.
- `converged` is `ok` with an empty `needs_human`.
- `phases[].status` is `done`, `skipped`, `planned` (`--check`) or `failed`.
- `needs_human[].kind` is `lint-error`, `playbook`, `codemod-blocked`,
  `codemod-skipped`, `lock-drift` or `vendored-contract`. Each carries `fix`:
  the command or skill that clears it. One lint finding is one item: the tool
  output under it (golangci-lint's source snippet, a formatter's diff) is its
  `context`, and the format lane's finding for a file golangci-lint's
  gofmt/goimports also flagged folds into that item.
- `upcoming` is informational and never changes the exit code.
- `offers` are scaffold-once files the project never had whose templates are
  not new across the range; upgrade did not add them, and `command` does. They
  never change the exit code.

### Re-vendoring a contract the project copies from another repository

forge does not know what a project vendors. The project declares it, and
upgrade runs the declared hook when the project's own check says the copy lags:

```yaml
# forge.yaml
upgrade:
  vendored_contracts:
    - name: controlplane
      report: tmp/ci/reliant-vendored-proto.json   # written by the project's own check
      schema: reliant-vendored-proto/v1            # a report claiming another is never acted on
      env_path: revendor.env                       # optional: an object in the report, exported to the commands
      commands:
        - [node, .github/scripts/sync-controlplane-proto.mjs]
        - [npm, run, "proto:generate:controlplane"]
```

The report is JSON with a top-level `schema` and a `status` of `in-sync` or
`lag`. `lag` runs `commands` in order from the project root, before generate;
`in-sync`, or no report yet, runs nothing; any other status or schema is
reported under `needs_human` as `vendored-contract`. The report format of
control-plane's `reliant-vendored-proto/v1` (`status`, `files[]`, `revendor.env`)
is one such producer.

## Reading per-version migration skills

A migration skill at `migrations/<version>` is the playbook for the
breaking changes one RELEASE introduced. Load it by the path
`forge project upgrade list` prints for it.

**Apply them in the order `forge project upgrade list` prints them —
oldest release first.** Each assumes the ones above it have already
landed; running a later release's playbook against a tree still in an
earlier shape is how a staged upgrade corrupts a project.

Every skill follows the same six-section shape:

1. **What changed.** A one-paragraph technical description.
2. **Detection.** How to identify whether your code has the old shape.
3. **Migration (deterministic part).** Commands that `forge project upgrade`
   already runs for you (regen, build).
4. **Migration (manual part).** What user-edited code might need to
   change. This is where the LLM does its real work.
5. **Verification.** `go build && go test && forge lint` plus any
   shape-specific checks.
6. **Rollback.** How to back out if something breaks.

forge does not automate the manual steps, because they touch hand-written
code that an LLM is better placed to reason about than a regex-based rewrite.
The steps that ARE mechanical are declared in the playbook's `automation:` and
run by `forge project upgrade` itself.

Once you've finished a migration's steps:

```bash
forge project upgrade apply <version>   # records it in .forge/migrations.json
```

## Which migrations ship

The registry is the binary's own, so this skill does not list it: a list here
goes stale the release after it is written. Ask the forge you are upgrading to:

```bash
forge project upgrade list                   # the ones THIS project still needs, in order
forge skill list --include-migrations        # every playbook this binary ships
```

An empty worklist is the normal steady state, not a gap. `forge project
upgrade list` says so directly:

```text
No migrations shipped by <this binary> — no release in the supported
upgrade window carries a breaking change.
```

<!-- @forge-only:start -->

## Authoring a migration skill (forge core authors)

Add a migration when a release changes the *shape* of a generated
artifact in a way user code or downstream tooling can observe. A new
annotation, a renamed helper, a changed file layout, a removed config
key — those need one. Pure internal refactors (swapping the regex engine
that parses proto annotations) do not.

### Where it goes and what it's called

One directory per RELEASE, named for that release:

```
internal/templates/project/skills/forge/migrations/v0.5.0/SKILL.md
```

The directory name IS the identifier: it's what `forge project upgrade
list` prints, what `forge project upgrade apply <id>` takes, and what
lands in `.forge/migrations.json`. One skill covers everything that
release broke — do not create a directory per individual change.

### A breaking change registers its codemod, and upgrade runs it

A PR that breaks a consumer (the API-diff gate names it with `API-BREAK:
codemod=<name>`) ships the `forge fix <name>` codemod in `internal/codemod`.
`forge project upgrade` then runs it when the range crosses the release, by
one of two declarations — the registration is incomplete without one, and
`TestEveryRegisteredCodemodIsReachableFromUpgrade` fails otherwise:

- `Upgrade: true` on the codemod, for a rewrite that keeps the program's
  meaning exactly (a rename, a moved symbol). It runs on every crossing of its
  `Version`, and decides from the tree, so it rewrites nothing where the old
  shape is absent.
- `automation: fix:<name>` in the release's playbook, for a codemod that
  replaces files wholesale or lists what it cannot decide. It runs only when
  the playbook's `detection` matches, only over a clean tree (or
  `--allow-dirty`), and a `Blocked` result lands in `needs_human`.

### Frontmatter contract

```yaml
---
name: v0.5.0
description: the deploy target moved from forge.yaml into KCL
relevance: migration
version: v0.5.0
detection: grep -q '^dev_target:' forge.yaml
---
```

| Field | Required | Meaning |
| --- | --- | --- |
| `name` | yes | Human-readable title. |
| `description` | yes | One line; this is what the worklist prints. |
| `relevance` | no | `migration` — defaulted from the directory, declare it anyway. |
| `version` | yes | The release that introduced the break. **Must equal the directory name** (a test pins this). |
| `automation` | no | Comma-separated mechanical steps `forge project upgrade` runs when the playbook applies. Each is `fix:<codemod>` (a registered `forge fix` name). A playbook that still matches its detection afterwards is reported as needing a person. |
| `detection` | yes | POSIX shell snippet, run in the project root by forge's in-process interpreter (identical on every OS, no `sh` needed). Exit 0 means the project still has the old shape. |

A migration applies when **both** hold: the project's pinned
`forge_version` is BELOW `version`, and `detection` exits 0.

### Writing detection: state, never version

Detection must test what the tree CONTAINS, never what version it claims
to be. The version half of the decision is already made by the `version`
field, and duplicating it there breaks the two cases that matter most:

- **Unpinned or dev-built projects.** A project bridged to a local forge
  checkout pins a pseudo-version; one predating `forge_version` has no
  pin at all. Neither has a usable position on the timeline, so forge
  falls back to detection ALONE. A version-based detection returns
  nothing useful here.
- **Multi-release jumps.** A project crossing four releases at once gets
  all four migrations. Each one must independently answer "does this tree
  still have my old shape?" — including after the previous three have
  already rewritten parts of it.

Good detection is a grep or a file test. Detection runs in-process, so
stick to shell builtins (`test`, `[`, `&&`, `||`, `!`) plus `grep` / `rg`,
which forge provides as portable built-ins supporting only `-q -i -F -E -r
-e` (`rg` is recursive by default). Any other external tool will not exist
on stock Windows. Three examples of the
`detection:` frontmatter value:

```text
test -f pkg/app/wire_gen.go
rg -q 'forge:server-set' internal/
grep -q '^dev_target:' forge.yaml
```

A migration with no detection applies to NOTHING — it cannot demonstrate
any project needs it, so it stays out of every worklist rather than
landing in all of them.

### The pruning rule

**When a release ages out of the supported window, DELETE its skill.**
Not archive, not mark retired — delete.

The window is `supportedUpgradeWindowMinors` in
`internal/cli/upgrade_migrations.go` (currently 2). A project older than
that cannot reach the migration anyway: it gets the staged-upgrade
refusal instead, which routes it through an intermediate release where
the migration was still in the window.

A skill nothing can reach is a skill nothing tests. Keeping it around
grows the registry without bound and leaves playbooks that quietly stop
being true. Deleting it is what makes the honest answer — "stage through
vX first" — the only answer that path can give.

<!-- @forge-only:end -->

## Compatibility policy

forge follows semver, and its major is 1. What that promises a project that
pins it:

- **Nothing public breaks within a major.** The public surfaces are CLI
  commands, flags, exit codes and `--json` document shapes (what a pin bot or
  script calls); the `pkg/` Go API; the `forge.yaml` and KCL schemas; the proto
  options under `proto/forge`; generated-code contracts; and the lint rules your
  gate runs. A new or stricter lint rule is not a break: it warns before it
  gates (`ci` skill).
- **Retiring something is a deprecation, not a removal.** The old command, flag,
  field, API or shape keeps working beside its replacement and warns, naming the
  replacement (a `Deprecated:` doc comment, `[deprecated = true]`, a hidden flag
  that prints a warning). It stays for at least 2 minor releases (the same 2 the
  upgrade window uses: a project inside the window is one whose shapes forge
  still supports) and is removed only in a major.
- **A major may break, and its contract is its upgrade instructions.** Only
  forge's owner cuts one. forge is upgraded by agents, so what a major owes you
  is not stability but a complete path: every break ships a migration playbook
  under `migrations/<version>` that `forge project upgrade list` surfaces, the
  mechanical part registered as a codemod or playbook `automation:` step that
  `forge project upgrade` applies itself, and the manual part written as steps
  an agent can follow. A break with no playbook is a forge bug: report it.
- **Behavioural fingerprints preserved across the cycle.** Mock
  not-set error strings, slog attribute keys, span names, and metric
  names are locked by fingerprint tests. A migration that breaks one
  of those gets called out explicitly in the skill's "What changed"
  section.

## See also

- `migration` — the top-level skill for porting a non-forge project
  *into* forge in the first place. This skill is for upgrading an
  already-forge project.

## Post-merge gotchas

Two things to know when `forge project upgrade` interacts with branches:

- **Recommended branch order: upgrade on `main` first, then merge into
  work branches.** The reverse (running `forge project upgrade` on a work
  branch and then merging `main` back in) produces ApplyDeps codemod
  conflicts that are painful to reconcile — the bootstrap/wire layer
  gets rewritten twice from different baselines, and the textual merge
  cannot tell which side owns which call. Treat `forge project upgrade` like a
  global codemod: land it on `main`, then rebase every open branch.
- **Generated-file merge conflicts: regenerate, don't hand-merge.**
  There is no global checksums manifest to reconcile anymore — each
  generated file carries its own `forge:hash` marker, so a textual
  merge of two pristine renders produces a file whose marker no longer
  verifies. Resolve by accepting either side and running
  `forge generate` (the writer heals pristine-but-stale vintages
  loudly); only a file BOTH branches hand-edited needs real conflict
  resolution, and the drift guard will name it.

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in development →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.