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 to create the repo’s .flow/ state, choose a review backend, and give every agent that reads CLAUDE.md / AGENTS.md the flow-next instructions.

Decide your layer set before you answer setup’s questions

Setup offers to switch several optional subsystems on. Each question names what the subsystem automates and what it adds to a run, and every one of them can also be run by hand per change. Answering “no” to an offer is a first-class choice, not a deferred setup step. The Configuration reference lists every key.

What it does

• Copies no tooling into your repo. The one exception is Codex, where setup copies the agent .toml files into .codex/agents/ because Codex reads agents only from the project. Every skill resolves flowctl from the plugin install itself, the agent guide is pulled live via flowctl usage, and the spec template resolves through the bundled cascade. Plugin updates land silently; you never re-run setup for an update.
• Runs flowctl init to create .flow/ (specs, tasks, memory, config) and walks the configuration ceremony.
• 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.
• Offers a .flow/criteria.md scaffold for standing criteria while that file is absent.
• Detects leftovers from the retired copy layout (.flow/bin/, .flow/templates/spec.md, .flow/usage.md) and offers to delete them - never silently, and never a customized .flow/templates/spec.md (a differing template is excluded with a copy-it-to-SPEC.md pointer).
• Proposes running /flow-next:tracker-sync as an optional next step when it finishes.
• Always recommends /flow-next:features to seed the feature map (or to maintain it when it is due), whatever the live-QA setting. It never runs the seed itself.

Tracker config is its own step

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 a repo-local .flow/ with your own config and review backend.
• 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.

The questions carry their price

Each opt-in question names what the feature buys and what it costs, so the choice is priced at the moment you make it. The review-backend question is the sharpest case: each review round is a serial pass the pipeline waits on, usually the largest wall-clock item in a run. Every host’s menu offers Host - the host-native reviewer that keeps every gate with no second CLI, pinned via one reviewer: line in the routing block - and None, which drops the review gates entirely (tests and the in-host quality audit still run, but nothing checks R-ID coverage at spec completion).

The answer is written to review.backend. A project whose review.backend still reads rp gets a one-line notice that RepoPrompt was removed in 8.0.0, and setup treats the key as unset, so it asks the review question again; see Review backends.

SPEC.md cascade

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

1. <repo_root>/SPEC.md
2. <repo_root>/spec.md
3. 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: standing-criteria scaffold

Setup asks once whether to write .flow/criteria.md, the project’s standing acceptance criteria. The question appears only while the file is absent: an existing file is user content, so it is never re-asked about and never touched, whether it was scaffolded, hand-written, or customized (a dangling symlink counts as existing, and surfaces as a validation error rather than a scaffold target).

Declining leaves no trace. The scaffold documents the G-ID grammar with its examples commented out, so a freshly written file parses to zero active criteria and changes nothing until you replace them with your own. Like the SPEC.md offer, it seeds a user-owned file - yours to edit, never refreshed behind your back.

Optional: live QA and the feature map

Setup asks the live-QA question once, on an unset pipeline.qa key: off, on, or auto, with off recommended when nothing runs in a browser yet. The setup summary prints Live QA: off, on, or auto. The values are on the QA page.

Setup then always prints one /flow-next:features line, whatever the live-QA answer, chosen by flowctl features status: a seed recommendation when .flow/features/ is absent, a maintain recommendation with its reasons when the map is due, or Feature map: current. The map lets QA, drive, and bug intake reuse how a user reaches each feature. Setup never seeds it itself, because seeding launches and drives the live app. See Keep the feature map current.

Optional: model-routing scaffold

Setup’s configuration ceremony includes one optional question (interactive runs only - headless and autonomous setups skip it silently): scaffold the routing block into your CLAUDE.md/AGENTS.md.

What it writes is the same on every host: the four tier lines - reviewer, implementer, fast scout, thinking scout - with their guidance, and every value commented out, so nothing routes until you fill one in. Setup asserts nothing about which models are installed: it never probes a CLI for model ids and never writes one. A model id is a property of your account, not of a project, and configuration that claimed what was installed became configuration that lied.

The block is shown in full before anything is written. Marker-fenced (<!-- flow-next:model-routing:start/end -->) so re-runs byte-compare (identical → silent no-op; edited → keep-mine/overwrite question) and /flow-next:uninstall removes exactly the block. A block a human has edited is never overwritten silently. Grok, Cursor and Muse Code read AGENTS.md, so the routing block lands there on those hosts.

Cursor-aware setup

When setup detects a Cursor host (positive path: PLUGIN_ROOT under ~/.cursor/, not “Codex absence”):

• No copies - Cursor exposes no plugin-root environment variable, so skills derive the plugin root from the absolute skill path Cursor hands the agent when a skill loads.
• Review-backend menu leads with Host (Recommended) - host-native fresh-context subagent; pins in AGENTS.md. External CLIs (codex / copilot / cursor / claude) remain selectable; the Cursor CLI option is labeled secondary/circular from inside Cursor.
• Docs target defaults to AGENTS.md - Cursor reads it; slash-command syntax (/flow-next:plan), not the Codex $flow-next- form.

See Install → Cursor and Orchestration → Cursor host.

Grok-aware setup

When setup detects a Grok host (GROK_AGENT=1, ordered after Droid / Claude / Cursor and before the Codex fallback):

• No copies - Grok exposes no plugin-root environment variable either; skills derive the plugin root from the absolute skill path Grok hands the agent.
• Review menu includes Host with the single-family fail-closed caveat - Grok’s only native family is grok-4.5; native host review refuses same-family self-review unless the writer is non-Grok. Cross-family review comes via bridge backends (codex / cursor / copilot); when Codex is detected it is marked Recommended for a Grok writer.
• Docs target defaults to CLAUDE.md for the lifecycle snippet (/flow-next: slash syntax); model-routing still targets AGENTS.md. Grok loads both files. A pre-existing wrong Codex $flow-next- marker block is consent-refreshed to the slash form.

See Install → xAI Grok Build.

Muse-aware setup

When setup finds the marker file install-muse.sh writes at the bundle root (checked first, ahead of every environment variable, because Codex and Claude Code children of a Muse shell inherit Muse’s variables):

• No copies - Muse substitutes ${CLAUDE_PLUGIN_ROOT} in skill text, so flowctl resolves from the installed bundle.
• Review menu includes Host with the single-family fail-closed caveat, plus every CLI backend; when Codex is detected it is marked Recommended. The CLI backends need Muse started with --disable-sandbox.
• Docs target defaults to AGENTS.md with the /flow-next: slash syntax. Muse reads only the first of AGENTS.md and CLAUDE.md, AGENTS.md first, so a repo set up under Claude Code needs Both here or one setup run in Muse.

See Install → Muse Code.

Re-running

Setup is safe to re-run, but you rarely need to: plugin updates require no per-project step. Re-run it when setup says the docs-snippet schema bumped, when you want to change configuration, or to re-seed a user-owned file. Project-customized files are preserved. Since 6.1.0 setup remembers the optional questions you declined and reads its state in one flowctl setup-status call, so a steady re-run asks nothing you already answered. 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.

Coming from an older install

Repos set up before this layout carry .flow/bin/, .flow/templates/spec.md, and .flow/usage.md snapshots. Delete them (one exception: an edited .flow/templates/spec.md is your content - copy it to a repo-root SPEC.md first; the offer detects and skips a customized template). Nothing reads them, removing them changes nothing observable in any workflow, and keeping them is the riskier choice - a stale copied flowctl can shadow the current one (a flag that “should exist” erroring is the classic symptom). Setup detects the leftovers and offers to remove them, and /flow-next:plan prints a one-line nudge when it sees them. Nothing breaks while you wait: skills still fall back to .flow/bin/flowctl as a silent backstop.

Worked example

/flow-next:setup

Initialized: .flow/ (specs, tasks, memory, config)
Copied into the repo: nothing - flowctl resolves from the plugin install
CLAUDE.md: flow-next instructions block added (marker-fenced, uninstall-safe)
Model-routing block: written, every line commented out - edit it to name your models.
Leftovers from an older install: none found.
Recommended next step: run /flow-next:features to seed .flow/features/ - QA, drive and bug intake read it to reach each feature without rediscovering the route.

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

Tips

• Updating the plugin needs no per-project step. If something looks stale after an update, check for leftover copies from an older install. See Troubleshooting.
• The instruction blocks are marker-fenced, so your own CLAUDE.md/AGENTS.md content is never disturbed.
• The model-routing block is yours from the moment setup writes it - uncomment and edit the tier lines freely; setup never overwrites a block a human touched.

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 - the committed .flow/ state means a teammate’s clone picks up your specs, tasks, and config as soon as they install the plugin.

Next step

flowctl detect --json

If the command reports the repository’s Flow state, setup landed cleanly. flowctl usage proves the live bundled agent guide resolves with nothing copied into the repo. 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.