# Setup Source: https://flow-next.dev/skills/setup/ Optional local install of flowctl plus CLAUDE.md and AGENTS.md instructions. `/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. Setup offers to switch several optional subsystems on. [Running Lean](https://flow-next.dev/understand/what-each-layer-costs/) 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 `/SPEC.md` nor `/spec.md` exists. * Offers a `.flow/criteria.md` scaffold for [standing criteria](https://flow-next.dev/reference/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](https://flow-next.dev/integrations/tracker-sync/) - 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](https://flow-next.dev/understand/what-each-layer-costs/#turning-the-dial-none-and-host). ## 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. `/SPEC.md` 2. `/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](https://flow-next.dev/reference/standing-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](https://flow-next.dev/guides/model-routing/#the-routing-block) into your `CLAUDE.md`/`AGENTS.md`. What it writes is the same on every host: the four [tier](https://flow-next.dev/guides/model-routing/#tiers-what-kind-of-model-a-job-wants) 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 (``) 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](https://flow-next.dev/install/#cursor) and [Orchestration → Cursor host](https://flow-next.dev/guides/model-routing/#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](https://flow-next.dev/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 ```plaintext /flow-next:setup ``` ```text 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. * 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](https://flow-next.dev/reference/troubleshooting/#updated-the-plugin-do-i-re-run-setup). * 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](https://flow-next.dev/guides/cookbook/): * [Integration tricks](https://flow-next.dev/guides/cookbook/#integration-tricks) - the routing scaffold in your instruction file is what per-step model steering reads. * [Team patterns](https://flow-next.dev/guides/cookbook/#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 ```bash 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](https://flow-next.dev/integrations/tracker-sync/) - setup proposes exactly this when it finishes.