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.

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 pilot’s standard unknown-flag notice and the tick proceeds, with affected zero-task specs routing through plan, the safe default. 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 is agent-driven by /flow-next:ralph-init. Upgrading from 2.x with an existing Ralph setup means 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.