Setup

/flow-next:setup is the opt-in installer for flow-next at the project level.

It is fully optional. The plugin works without it. Run it when you want shell-level access to flowctl or when other AI agents (Codex, Cursor, Droid) need to read flow-next instructions from CLAUDE.md and AGENTS.md.

What it does

Copies flowctl and helper scripts to .flow/bin/ so they are reachable from the shell.
Appends flow-next instructions to CLAUDE.md and AGENTS.md, or creates them if they do not exist.
Offers a repo-root SPEC.md from the bundled template when neither <repo>/SPEC.md nor <repo>/spec.md exists.
Records setup_version in .flow/meta.json so other skills can warn when the local copy is stale.

When to use it

You want flowctl <command> to work from any terminal.
The repo is shared with non-Claude agents that need the same instructions.
You want a customizable repo-root SPEC.md template instead of the bundled scaffold.

If you only use Claude Code with the plugin installed, you do not need to run setup.

SPEC.md cascade

When setup writes SPEC.md, it uses the four-tier template resolution that /flow-next:capture, /flow-next:interview, and /flow-next:plan already use:

<repo_root>/SPEC.md
<repo_root>/spec.md
.flow/templates/spec.md
Bundled ${PLUGIN_ROOT}/templates/spec.md

Setup always writes uppercase SPEC.md. On re-setup, a byte-compare gate asks Keep mine / Overwrite with canonical / abort so customized templates are never silently clobbered.

Re-running

Setup is safe to re-run. It detects an existing install, compares versions, and offers to update only the scripts that drifted. Project-customized files are preserved.

Why scripts, not symlinks

The installer copies scripts rather than symlinking them. This keeps the install portable across environments — virtualization, containers, hand-off to a teammate — at the cost of needing a re-run after a plugin upgrade.

Next step

flowctl --version

If the command resolves, setup landed cleanly. Continue with /flow-next:strategy or /flow-next:capture.