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

• Asks the setup mode question once per repo (Claude Code only). Plugin mode: nothing is copied — bare flowctl rides the plugin’s PATH injection, the agent guide is pulled via flowctl usage, the spec template resolves from the bundled copy, and the only repo artifact is a slim versioned CLAUDE.md block. Plugin updates land silently; you never re-run setup for an update. Copy mode (every other host, and repos with plugin-less consumers): the snapshot behavior below.
• Copies flowctl and helper scripts to .flow/bin/ so they are reachable from the shell (copy mode).
• 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.
• Proposes running /flow-next:tracker-sync as an optional next step when it finishes.

Setup never touches tracker config

Setup wires the zero-dependency base install only. It never configures the tracker bridge — that keeps the base clean for the many users who run no project-management software. The bridge is a separate, opt-in step: run /flow-next:tracker-sync to start its discovery ceremony, which probes for a Linear MCP / LINEAR_API_KEY / GitHub auth / GitLab auth (glab / GITLAB_TOKEN / CI_JOB_TOKEN) / a Jira host (a configured *.atlassian.net or self-hosted base URL) and writes tracker.* config only on confirmation. Setup proposes it as an optional next step when it finishes, so it is discoverable without being imposed.

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:

1. <repo_root>/SPEC.md
2. <repo_root>/spec.md
3. .flow/templates/spec.md
4. 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.

Optional: model-routing scaffold

Setup’s configuration ceremony includes one optional question (interactive runs only — headless and autonomous setups skip it silently): scaffold an opinionated model-routing block into your CLAUDE.md/AGENTS.md. The block is a cost/intelligence/taste scores table plus routing rules wired to concrete flow-next surfaces (delegate:codex, review.backend, scouts, the thin-wrapper pattern). Routes to CLIs the command -v probes didn’t find are written commented-out with an install note; the composed block is shown in full before anything is written; the scores are starting opinions you’re invited to re-rank. Marker-fenced (<!-- flow-next:model-routing:start/end -->) so re-runs byte-compare (identical → silent no-op; edited or probe-drifted → keep-mine/overwrite question) and /flow-next:uninstall removes exactly the block. Opting into the delegation variant sets work.delegate codex but never pre-sets the consent gate — first use still asks.

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. The CLAUDE.md/AGENTS.md instruction block refreshes in place: setup records a per-target hash of the block it wrote (.flow/meta.json), so an unmodified block is silently updated to the current canonical while a customized one gets a Keep mine / Overwrite question - at most once, ever, for installs that predate the hash.

Why scripts, not symlinks

In copy mode 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. That is the one copy-mode rule to remember: after every Flow-Next update, re-run /flow-next:setup in each project so the bundled flowctl and .flow/usage.md snapshots match the new plugin (the skills nudge you on stderr when they drift). Plugin-mode repos have no snapshots and no rule — that is the point of plugin mode.

Worked example

/flow-next:setup

Copied: .flow/bin/flowctl, flowctl.cmd, flowctl.py (setup_version stamped)
Wrote: .flow/usage.md, .flow/templates/spec.md
CLAUDE.md: flow-next instructions block added (marker-fenced, uninstall-safe)
Optional model-routing scaffold: offered - accepted, table written.

Idempotent and non-destructive: specs, tasks, memory, and config are never touched by a re-run.

Tips

• Copy mode: re-run it in each project after every plugin update - the in-repo flowctl copy is a snapshot, and version-skew symptoms (missing flags, stale usage.md) all trace back here. Plugin mode has no snapshots, so this whole failure class does not exist there. See Troubleshooting.
• The instruction blocks are marker-fenced, so your own CLAUDE.md/AGENTS.md content is never disturbed.
• The model-routing scaffold is a starting opinion - edit the table freely; it is yours after setup writes it.

Dynamic usage

Recipes that compose with setup in the cookbook:

• Integration tricks - the routing scaffold in your instruction file is what per-step model steering reads.
• Team patterns - committed .flow/bin + usage.md means a teammate’s clone works without any global install.

Next step

flowctl --version

If the command resolves, setup landed cleanly. Continue with /flow-next:strategy or /flow-next:capture. If your team works out of Linear, GitHub Issues, GitLab, or Jira, run /flow-next:tracker-sync to wire the optional tracker bridge — setup proposes exactly this when it finishes.