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. Running Lean prices each one - what it automates away, what it costs structurally, when it earns its keep, and the manual invocation if you would rather reach for it per change - and frames the two operating profiles that decide which set you want. Answering “no” to an offer is a first-class choice, not a deferred setup step.

What it does

• Copies nothing into your repo, on any host. 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.

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 full dial is priced in Running Lean.

SPEC.md cascade

When setup writes SPEC.md, it uses the three-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. 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: 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 and Cursor 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 / rp) remain selectable; the Cursor CLI option is labeled secondary/circular from inside Cursor.
• Ralph ceremony is skipped - Ralph is intentionally not built for Cursor; setup never offers or registers Ralph guards there.
• 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.
• Ralph ceremony is skipped - Ralph is intentionally not built for Grok (same posture as Cursor); setup never offers or registers Ralph guards there.
• 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.

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. 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.

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.