Versioning

Flow-Next 1.x stabilizes the spec vocabulary.

1.0 rename

epic became spec.

• flowctl epic * aliases flowctl spec *
• flowctl epics aliases flowctl specs
• --epic aliases --spec
• /flow-next:epic-review aliases /flow-next:spec-completion-review

Aliases emitted deprecation warnings through 2.x and were removed in 3.0 - canonical spec forms only. External consumers reading legacy dual-emit JSON keys (epics, epic_id, …) or forwarding --epic flags must migrate before upgrading. The on-disk depends_on_epics field is canonical schema, not an alias, and is unchanged.

Repo migration

The migrate-rename / migrate-rollback commands were removed in 3.0. Port a pre-1.0 repo by hand - three steps, listed in flowctl usage under “Pre-1.0 layout porting”: rename .flow/epics/ to .flow/specs/, rewrite the legacy keys, run flowctl validate --all.

Interactive path:

/flow-next:setup

Compatibility promise

Within 1.x:

• spec is the canonical term.
• Legacy epic aliases continue as warnings, not preferred docs language.
• R-ID semantics remain stable.
• Repo-local .flow/ state should migrate forward without losing tracked work.
• Pure docs and agent guidance changes do not require plugin version bumps.

Docs and changelog

Behavior changes should update:

• relevant docs page
• command reference if user-facing command behavior changes
• changelog entry
• examples or screenshots when UI/copy changes

This site should stay in sync with the Flow-Next plugin repo, including new docs such as teams, Ralph, and flowctl references.