# Compatibility & migration Source: https://flow-next.dev/releases/compatibility/ What changed across major versions, what an upgrade requires, and the removals that need a hand-port. `spec` is the canonical vocabulary and repo-local `.flow/` state migrates forward without losing tracked work. This page records the changes that need something from you. ## What still holds * `spec` is the canonical term across the CLI, the skills, and these docs. * R-ID semantics are stable: ids never change, removed criteria leave gaps, new criteria append. * Spec and task ids never change. Linking a tracker adds an alias; it never renames. * Pure docs and agent-guidance changes do not require a plugin version bump. ## 8.0: RepoPrompt removed, every reviewer gets the same panel A major release. Nothing under `.flow/` migrates, `review.backend` keeps its meaning, and you don’t need to re-run setup. * **RepoPrompt is removed.** The `rp` review backend, the `flowctl rp` commands, `/flow-next:export-context` and plan review’s `--review=export` mode are gone. A project that still names `rp` or `export` (in `review.backend`, `FLOW_REVIEW_BACKEND`, a spec’s or task’s review setting, or `--review=`) gets a one-line notice and continues with no reviewer until you pick one: `flowctl config set review.backend codex` (or `host`, `claude`, `copilot`, `cursor`). Re-run the Codex, OpenCode or Cursor installer to drop the removed skill. * **`review.backend` stays.** 7.1.0 announced its removal for 8.0.0. That was reversed: the reviewer is still chosen with `review.backend`, a spec’s or task’s review setting, or `--review=`. * **`flowctl review-rounds record` needs `--backend`.** It no longer defaults to `rp`; host workflows pass `--backend host`. * **A plan review can read `stale`.** A spec rewritten after its plan-review SHIP reads `stale`. Anything that reads `plan_review_status` should treat it like `needs_work`. * **QA receipts record mode `receipt`** where a receipt-driven pass used to write `rp`. Receipts already on disk with `mode: "rp"` still read. Behaviour you will notice, with nothing to change on your side: * **The same review panel on every reviewer.** Claude, Copilot and Cursor reviews size the first round like Codex and host reviews: one reviewer for a small change in one area, three for anything larger, merged into one fix pass. * **A one-task spec has its standing criteria checked** by its implementation review. * **The stall check reviews your latest fix first.** It ends a loop only after three consecutive `not-fixed` rounds on the same finding. * **A usage or credit limit stops the review** with the CLI’s own message instead of a retry. * **Land reports `QUEUED`** when its merge call only added the pull request to a merge queue. ## 7.0: Ralph and the HTML lenses removed A major release. `/flow-next:flow --auto` (with `--until=merge` or `--tick`) is the one unattended mode. Nothing under `.flow/` migrates, and you don’t need to re-run setup. * **Ralph is removed.** `/flow-next:ralph-init`, the `scripts/ralph/` harness and `ralphctl`, the `ralph-guard` hooks, setup’s Ralph question, the `FLOW_RALPH`, `RALPH_ITERATION` and `FLOW_RALPH_NO_TRIAGE` variables, the Ralph-run probe in `flowctl status`, and the `flow-next-tui` run monitor are gone. To keep running Ralph, pin flow-next 6.7.x. Otherwise delete `scripts/ralph/` and any `ralph-guard` hook entries from your project settings, and use `/flow-next:flow --auto` for unattended runs ([Flow —auto](https://flow-next.dev/autonomy/pilot/)). * **The HTML render lenses are removed.** Capture, plan and make-pr no longer write HTML pages under `.flow/artifacts//`, and setup no longer asks about them. A config that still sets `artifacts.html.enabled` keeps working: flowctl ignores the key and prints a one-line note. `flowctl pr-cognitive-aid html-input` is gone. Old `spec.html` and `pr.html` files stay where they are; delete them, along with the `HTML render lens:` link line a lens added near the top of each spec. For a visual view of a spec, a plan or a diff, run [`/flow-next:visual`](https://flow-next.dev/skills/visual/), or ask the agent for an HTML page. * **The optional Jev judge no longer routes or gates QA.** `flowctl judge --preset route` is decided in code and sends no request, key or no key; the `qa-gate` preset and `judge --explain` are gone. Scripts that called them need updating. A run with a key and one without now take the same route. * **Unattended merges wait 10 minutes by default.** `land.patienceMinutes` defaults to 10 (was 30). Set the key if your review bots take longer to post. * **`pipeline.chainStages` is removed.** A config that still sets it keeps working: flowctl ignores the key and prints a one-line note. Under `flow --auto --tick`, make-pr runs on the next tick. Delete the key from `.flow/config.json`. * **The pilot and interview skill stubs are gone.** Use `/flow-next:flow --auto` and `/flow-next:refine`. * **The Copilot reviewer is read-only.** It runs without write and shell tools, like the Claude reviewer. Behaviour you will notice, with nothing to change on your side: * **Pull requests open ready for review** unless they carry open items; a human call that blocks nothing else becomes an open item on a draft PR. Unattended runs used to open a draft every time. * **Review goes by risk.** A change that touches persisted or shared state, concurrency, security or data layout, or a multi-file feature, is reviewed; a small local fix to output, wording or display is not, and the skip is recorded with its reason. * **Attended runs hand the result back first** and run the review in the background, then one scoped re-review of the fixes. * **Plan-review and completion review fix once and re-review once**, instead of looping to the round cap. * **Unattended runs loop fix and re-review until SHIP**, and write a Decisions list into the PR: each default chosen, finding declined and review skipped, with the evidence. ## 6.5: refine is one interview, two flowctl surfaces removed A minor release. Nothing under `.flow/` migrates, no config key changed, and setup does not need a re-run. The work is in scripts and in a copied spec template. * **`flowctl scope` is gone.** Its `resolve`, `bank` and `write-policy` subcommands served refine’s per-scope passes, which are now one interview. Scripts that called them need updating; `--scope`, `--biz` and `--tech` on `/flow-next:refine` still work as a lens. * **`flowctl done --resolved-feature` is gone.** Passing it fails as an unrecognized argument. QA receipts no longer carry `resolved_feature`; existing task evidence and QA payloads that carry it still load, and the key is ignored. * **A copied spec template keeps working.** A repo-root `SPEC.md` or `spec.md` copied from an older bundled template still resolves, and its `` comments are now ignored. Re-copy the bundled template and re-apply your edits to pick up the cleaner version. * **Refine no longer asks which interview to run.** Pass a lens (`--scope=`, `--biz`, `--tech`) or say which audience you want when you want one. ## 6.1: pilot and interview commands removed, agents invoke skills by id A minor release. Nothing under `.flow/` migrates, no config key changed, and setup does not need a re-run. The work is in loop recipes, prompts, and scripts that read flowctl JSON. * **`/flow-next:pilot` and `/flow-next:interview` are gone.** Replace them with `/flow-next:flow --auto --tick` and `/flow-next:refine`. Look in `/loop` and `/goal` prompts, Ralph recipes, scripts, and `CLAUDE.md` or `AGENTS.md` paragraphs. Pilot’s arguments map as shown on [Migrating from pilot](https://flow-next.dev/autonomy/pilot/#migrating-from-pilot). The hidden skill stubs behind them go in a later release. * **Agents invoke skills by id.** Every `/flow-next:*` command is now typed-only, so the skill listing shows each skill once. You type slash commands as before. A prompt or instruction file that tells an agent to run a skill should name it by id, for example `flow-next:flow-next-work`. * **`flowctl show --json` drops two ledgers.** Read review attempts with `flowctl review-rounds attempts --kind plan|impl --review-type plan|impl|completion` and the tracker link state with `flowctl sync get-state `. * **A tracker push can refuse.** A body-writing push on a linked spec whose tracker body changed since the last sync returns a `conflict` with subtype `tracker_diverged` and writes nothing. Reconcile to merge both sides, or rerun the push with `--overwrite-diverged` after a human confirms ([details](https://flow-next.dev/integrations/tracker-operations/#edits-made-on-the-tracker)). * **`flowctl done` checks evidence.** Evidence with none of `commits`, `tests`, or `prs` is refused; unknown keys print a warning. * **A malformed `.flow/config.json` is reported instead of reset.** Readers name the file (line and column for a syntax error), `config set` refuses to overwrite it, and `validate` reports a root error. Fix the file by hand. * **Not renamed.** `pilot.autonomy`, `pilot.gateClasses`, `pipeline.chainStages` (removed in 7.0), `tracker.perEvent.interview`, the `flowctl pilot` verbs, `.flow/pilot-runs/`, and the `PILOT_VERDICT` name keep their spelling. ## 6.0: land takes one named pull request, make-pr closes the spec A major release. Nothing under `.flow/` migrates, and existing config files load. The work is in your landing recipes and in anything that parses a pull request body. * **Land needs a pull request.** `/flow-next:land ` handles the one pull request you name. A bare or scheduled `/flow-next:land` finds nothing and stops `NEEDS_HUMAN`. Replace it with [the land loop](https://flow-next.dev/autonomy/land/#the-land-loop): list the pull requests, call land on each. * **Merging needs authorization from the current session.** An explicit request to land that pull request, or `flow --auto --until=merge`. Without it land repairs the pull request and stops at `AWAITING_REVIEW` with reason `merge-ready; authorization required`. A fresh headless session needs the instruction in its prompt. * **The default review gate changed.** Green checks, a nonblocking GitHub review decision and zero unresolved threads allow an authorized merge, even when nobody reviewed and no review is required. Bot comments no longer gate a merge. If you relied on `land.reviewSignal`, tighten the gate in your instruction file, with branch protection, or with `land.mergeVerdictCommand` ([the merge gate](https://flow-next.dev/autonomy/land/#the-merge-gate-precisely)). * **Eight `land.*` keys are retired**: `release`, `reviewSignal`, `automatedReviewers`, `reviewTrigger`, `ciFixBudget`, `cleanReviewCommentPattern`, `requestReviewers`, `patienceMinutesAfterReview`. They load with one notice and are ignored. `land.patienceMinutes` and `land.mergeVerdictCommand` remain. [Replacements](https://flow-next.dev/autonomy/land/#retired-keys). * **Land no longer releases, requests reviewers, or summons reviewer bots.** Run releases from your project’s release instructions after `LAND_VERDICT=MERGED`. `RELEASED` stays in the verdict vocabulary for parsers and is never emitted. * **No ledger, no labels, no tick claim.** Old land files under `.git/` are inert. The `flow-next:needs-human` label is no longer set or read. The `FLOW_PR_MERGE_CMD` override is gone; land uses the authenticated standard merge API. * **make-pr closes the finished spec on the branch**, as the last commit before the pull request opens, so the close reaches a protected base through the merge. Land writes nothing to the repository after the merge. Creating or starting a follow-up task reopens a closed spec. * **A conflicted chain child is a manual rebase.** Land never rebases, force-pushes or retargets. The steps are on [Troubleshooting](https://flow-next.dev/reference/troubleshooting/#land-on-a-chain-chain-broken-a-retarget-conflict-or-a-pending-merge-async). * **The pull request body has a new form.** One briefing for every diff size ([sections](https://flow-next.dev/skills/make-pr/#the-briefing-section-by-section)). The compact and full forms, the review-plan section and the generated-by footer are gone; artifact id, base and head ride in one HTML comment. Anything that parsed the old sections needs an update. The stored artifact keeps schema version 1. * **`--no-mermaid` is removed from make-pr.** Drop it from scripts; an unknown flag is refused. * **Aid artifacts stay local.** After `flowctl init` refreshes the managed ignore block, new generations are not staged. A repository that already tracks them can untrack them once with the command on the [make-pr page](https://flow-next.dev/skills/make-pr/#one-portable-artifact-three-render-surfaces). ## 5.1: pilot deprecated to a one-release alias One `/flow-next:flow --auto []` invocation now carries a ready spec to a draft PR, hop after hop, and `--tick` runs exactly one hop (what a pilot tick was). Nothing under `.flow/` migrates; the work is in your loop recipes. * **`/flow-next:pilot` is an alias for `/flow-next:flow --auto --tick` for this release only.** It prints `pilot is now flow --auto --tick; this alias is removed in the next release` to stderr, rewrites its arguments (`--spec ` becomes the positional id; `--backlog` and pilot’s old `--auto` backlog switch become `--backlog`; `--dry-run` becomes `--explain`; `--review`, `--research`, and `--depth` pass through), and behaves byte-for-byte as a pilot tick. The release after 5.1.0 removes the shim, the command entry, the Codex mirror, and the conduct page. * **Recipes to update now.** Replace `/loop 30m /flow-next:pilot` with `/loop 30m /flow-next:flow --auto --tick`, and a `/goal` objective that names pilot with one that names `flow --auto --tick` and the `PILOT_VERDICT` grammar. The default recipe needs no loop: one `/flow-next:flow --auto` invocation per item, run again for the next item. Land recipes changed in a later major; see the section above. * **`pipeline.chainStages` is deprecated (removed in 7.0).** `flow --auto --tick` (and the alias) still honours it as the `qa+make-pr` tick; a long-horizon run ignores it with one stderr notice, because its hop loop already runs `make-pr` as the hop after `qa`. * **`pipeline.qa=auto` now takes effect unattended.** `flow --auto` reads it through the same gate-selection reference attended flow reads. `on` and `off` are unchanged. * **Attended `flow` refuses under every autonomy marker** with `NEEDS_HUMAN: /flow-next:flow is attended - run /flow-next:flow --auto for unattended runs`; `--auto` refuses only under Ralph (`FLOW_RALPH`, `REVIEW_RECEIPT_PATH`). * **Not renamed.** `pilot.autonomy`, `pilot.gateClasses`, `pipeline.qa`, `pipeline.chainStages` (removed in 7.0), `flowctl pilot strikes list|clear`, `flowctl pilot-log`, the ledger path under the git common dir, `.flow/pilot-runs/`, and the `PILOT_VERDICT` name keep their spelling. A rename is a separate break for a later major. ## 5.0: guide removed, interview renamed to refine Two command names changed. Nothing under `.flow/` migrates; the work is in your prompts and docs. * **`/flow-next:guide` is gone, with no alias.** Replace it with `/flow-next:flow --explain ` where you wanted a recommendation, or plain `/flow-next:flow ` where you want the route run. Look in scripts, `/loop` and `/goal` prompts, `CLAUDE.md` or `AGENTS.md` policy paragraphs, and team docs. On this release a `/flow-next:guide` invocation is an unknown command on every host. * **`/flow-next:interview` is now `/flow-next:refine`.** Same scopes (`business`, `technical`, `both`), same flags, plus the new `--scope=research`. The old name keeps working for this release as a deprecated alias that prints one line (`Deprecated: /flow-next:interview is now /flow-next:refine`) and forwards your arguments unchanged. The alias is removed in the next release, so replace the name before then. The config key `tracker.perEvent.interview` keeps its name. * **`pipeline.qa` gains `auto`.** Existing `off` and `on` values behave as before. In 5.0 only the attended flow skill judged `auto`; since 5.1.0 `flow --auto` reads it too (see the 5.1 section above). * **Pilot and land invocations were unchanged in 5.0.** Since 5.1.0 `/flow-next:pilot` is the one-release alias for `flow --auto --tick`, so a `/loop 30m /flow-next:pilot` recipe now needs the edit named above. The routing rules behind capture’s, plan’s, and work’s recommendations now live in the [flow](https://flow-next.dev/skills/flow/) skill’s reference files; the recommendation you read and the route flow runs are the same rule. See the [changelog](https://flow-next.dev/releases/changelog/) for the full 5.0.0 story. ## 4.11: pilot’s `--no-plan` flag removed The no-plan decision moved onto the spec record. `/flow-next:pilot --no-plan` no longer exists; a stray flag gets the unknown-flag notice and the run proceeds. In 4.11 an affected zero-task spec routed through `plan`, the safe default then; since 5.1.0 `flow --auto` (which has no `--no-plan` flag either) applies the plan-versus-no-plan rule to a ready zero-task spec with no recorded route and records the result on the spec before any mint. Nothing breaks, but scripts or loop drivers passing the flag should migrate to marking the spec itself: ```bash flowctl spec set-no-plan fn-N # durable per-spec consent; refused once tasks exist flowctl spec clear-no-plan fn-N # undo /flow-next:capture ... --no-plan # record it at capture time ``` `/flow-next:work fn-N --no-plan` is unchanged; the direct flag stays for interactive use, and work now also honors the spec field. See [the no-plan route](https://flow-next.dev/choosing-your-route/#no-plan-route). ## 4.0: installs became copy-less Your repos need no `flowctl` copies. Every host resolves `flowctl` from the plugin install itself, so updating the plugin is the whole update. If an older install left `.flow/bin/`, `.flow/templates/spec.md`, or `.flow/usage.md` behind, delete them (`git rm` if tracked), or let [`/flow-next:setup`](https://flow-next.dev/skills/setup/) offer it. Nothing depends on them, and a stale copied `flowctl` can shadow the current one. Customized `.flow/templates/spec.md`? Copy it to a repo-root `SPEC.md` first, which is tier one of the [template cascade](https://flow-next.dev/guides/spec-scaffold/#template-discovery); setup’s offer detects a customized template and never deletes it. ## 4.0: packaged delegation and model config removed The `work.delegate*` subsystem and the `models.*` keys are gone. Leftover keys in `.flow/config.json` are inert. flowctl names them once in a non-blocking advisory and otherwise ignores them. The replacement is prose, not config. Name an `implementer` tier in your `CLAUDE.md` / `AGENTS.md` routing block and drive the other CLI through a headless bridge. Run [`/flow-next:setup`](https://flow-next.dev/skills/setup/), accept the routing-block scaffold, and use the bridge recipes in `flowctl usage`. Full model: [Model routing & steering](https://flow-next.dev/guides/model-routing/#implementation-offload-the-bridge-route). ## 3.0: `epic` aliases removed `epic` became `spec` in 1.0, with aliases that emitted deprecation warnings through 2.x: * `flowctl epic *` aliased `flowctl spec *` * `flowctl epics` aliased `flowctl specs` * `--epic` aliased `--spec` * `/flow-next:epic-review` aliased `/flow-next:spec-completion-review` All of them are **gone since 3.0**, leaving canonical `spec` forms only. External consumers reading legacy dual-emit JSON keys (`epics`, `epic_id`, and friends) or forwarding `--epic` flags must migrate before upgrading. **The on-disk `depends_on_epics` field is canonical schema, not an alias, and is unchanged.** It is the one place the older word survives on purpose, and it is easy to get wrong when grepping for leftovers. ## 3.0: migrate verbs removed The `migrate-rename` and `migrate-rollback` commands are gone. Port a pre-1.0 repo by hand in three steps, listed in `flowctl usage` under “Pre-1.0 layout porting”: rename `.flow/epics/` to `.flow/specs/`, rewrite the legacy keys, then run `flowctl validate --all`. The interactive path is: ```bash /flow-next:setup ``` ## 3.0: Ralph hooks became per-project The plugin ships **zero hooks**. Registration was agent-driven by `/flow-next:ralph-init` (removed in 7.0). Upgrading from 2.x with an existing Ralph setup meant re-running `ralph-init` once. The old plugin-level hooks are gone and the guard will not fire without re-registration. ## Where the release history lives Per-release detail, including everything that did not need a migration step, is in the [changelog](https://flow-next.dev/releases/changelog/).