Compatibility & migration

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).
The HTML render lenses are removed. Capture, plan and make-pr no longer write HTML pages under .flow/artifacts/<spec-id>/, 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, 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=<anything>, --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. 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 <spec> --json drops two ledgers. Read review attempts with flowctl review-rounds attempts <spec> --kind plan|impl --review-type plan|impl|completion and the tracker link state with flowctl sync get-state <spec>.
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).
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 <PR> 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: 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 <spec> --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).
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.
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.
The pull request body has a new form. One briefing for every diff size (sections). 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.

5.1: pilot deprecated to a one-release alias

One /flow-next:flow --auto [<spec-id>] 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 <id> 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 <the same words> where you wanted a recommendation, or plain /flow-next:flow <the same words> 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 skill’s reference files; the recommendation you read and the route flow runs are the same rule. See the 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:

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.

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 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; 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, accept the routing-block scaffold, and use the bridge recipes in flowctl usage. Full model: Model routing & steering.

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:

/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.