Install

Flow-Next runs inside your agent harness. Install the plugin, run setup in the repo you want to work on, then use slash commands for the workflow.

What setup does. /flow-next:setup creates .flow/ in your repository, configures your review backend, and adds Flow-Next instructions to CLAUDE.md or AGENTS.md. It copies nothing - flowctl resolves from the plugin install itself. Everything it writes lands inside the repository.

How long it takes. Two commands to install the plugin, then one setup run that asks a short round of questions. Under five minutes on the first repo. Setup is idempotent, so running it again is safe.

How to undo it. rm -rf .flow/ removes Flow-Next from the repository. There is no account to close, no service to cancel, and no global state left behind.

Requirements and agent usage

Flow-Next is MIT-licensed. You supply a supported coding agent, access to its models, and the environment needed to build and test your project.

Requirement	Used for
Python 3.11+	The bundled pure-stdlib `flowctl` CLI
`jq` and `gh`	Review and pull-request plumbing; authenticate `gh` before opening a GitHub PR
Your coding-agent access	Planning, implementation, reviews, and other agent work
Project tools and tests	Building and verifying your actual change
A reachable reviewer	Cross-family review; use a host-native reviewer or a configured review CLI
A running app and supported driver	Live QA, when you set `pipeline.qa` to `on` or `auto` or invoke it by hand

There is no Flow-Next account or hosted service to run. Agent work uses your configured providers and their usage limits. Extra review rounds, additional workers, and live QA consume additional agent work. Each optional layer has its own switch on the configuration reference; review backends covers reviewer setup.

The commands below distinguish terminal installation from invocations in the agent conversation. After installing, follow Your First 30 Minutes for one reproducible change.

Claude Code and Factory Droid

Add the marketplace, install the plugin, and reload so its commands load:

/plugin marketplace add https://github.com/gmickel/flow-next
/plugin install flow-next
/reload-plugins

/reload-plugins makes the freshly installed /flow-next:* commands available without restarting Claude Code. (Factory Droid: droid plugin marketplace add … && droid plugin install flow-next.)

Then run setup inside the project repo:

/flow-next:setup

Setup is recommended because it:

configures your review backend (RepoPrompt and the review.backend setting are deprecated for 8.0.0)
creates .flow/ for your specs, tasks, memory, and config - and copies nothing else into the repo
adds Flow-Next instructions to CLAUDE.md or AGENTS.md
offers a repo-root SPEC.md template without clobbering existing customizations
recommends seeding the feature map with /flow-next:features (see First run)

Setup keeps the base install zero-dependency. It never configures the tracker bridge. If your team works out of Linear, GitHub Issues, GitLab, or Jira, run the separate, opt-in /flow-next:tracker-sync to wire it (setup proposes exactly this when it finishes). See Tracker Sync.

OpenAI Codex

Use the installer script for the full Codex experience:

git clone https://github.com/gmickel/flow-next.git
cd flow-next
./scripts/install-codex.sh flow-next

Then run the setup skill in your project:

$flow-next-setup

The script is required because Codex plugin manifests do not yet install Flow-Next’s bundled agents. The installer copies skills, agents, prompts, templates, and flowctl into your active Codex home, then updates that home’s config.toml. No hooks ship by default; upgrading also cleans stale flow-next entries out of a pre-3.0 ~/.codex/hooks.json while preserving any custom hooks alongside them.

More than one Codex home

If you run Codex from several homes - a work account, a client sandbox, a second instance - point CODEX_HOME at the one you want and run the installer once for it:

CODEX_HOME="$HOME/.codex-work" ./scripts/install-codex.sh flow-next

Any path works; quote it if it contains spaces. Each install resolves its own tools from its own home, so nothing leaks between them. With CODEX_HOME unset you get ~/.codex exactly as before.

Re-run the script after pulling a new Flow-Next release (once per home you use):

cd flow-next
git pull
./scripts/install-codex.sh flow-next

xAI Grok Build

First-class host. Grok Build reads the canonical Claude plugin format as-is (skills, agents, commands, MCP, instruction files). Setup detects Grok via a positive signal: GROK_AGENT=1 (set by grok in its agent shell). That is the only detection signal - ~/.grok/ on disk and ~/.grok/bin on PATH are not signals (they exist outside a grok session). Detection runs after Droid / Claude / Cursor and before the Codex fallback, so Grok never gets Codex-shaped $flow-next- snippets.

Grok is not a Codex host. Drive with /flow-next:* slash commands; type /flow-next: to discover them. flowctl resolves from the plugin install - nothing is copied into the repo.

Install (pick one)

Already in Claude Code? Grok auto-reads that install - confirm with grok inspect.
Marketplace source: add gmickel/flow-next as a [[marketplace.sources]] entry in ~/.grok/config.toml (or the TUI Marketplace tab via /plugins), then enable the flow-next plugin.
Local / dev: grok --plugin-dir /path/to/flow-next/plugins/flow-next.

Then run setup in the project:

/flow-next:setup

Grok exposes no plugin-root environment variable, so skills derive the plugin root from the absolute skill path Grok already hands the agent - no copies, no PATH setup. Setup writes lifecycle docs to CLAUDE.md by default (/flow-next: slash syntax - not Codex $flow-next-), and scaffolds model-routing into AGENTS.md. Grok loads both CLAUDE.md and AGENTS.md. A pre-existing wrong Codex $flow-next- marker block is consent-refreshed to the slash form (marker-scoped).

Don’t run grok plugin install https://github.com/gmickel/flow-next - that is Grok’s single-plugin installer, and the repo is a marketplace (the plugin is nested under plugins/flow-next/). Use the auto-read or marketplace path above.

What works (verified)

Skills, slash commands, multi-agent. A full /flow-next:plan under Grok fanned out all seven scout subagents in parallel and drove flowctl to create the spec, tasks, and validation end-to-end. Type /flow-next: to open command autocomplete; /flow-next- filters the separate hyphen-named skill surface.
review.backend host. Setup offers Host alongside bridge backends (codex / cursor / copilot / rp / none). Single-family fail-closed: Grok’s only native model family is grok-4.5, so native host review fails closed (interactive → ask; autonomous → NEEDS_HUMAN) unless the writer is non-Grok. Cross-family review on Grok comes through bridge backends, not a native multi-family subagent. See Review workflow.
flowctl resolves from the plugin install (derived from the skill file’s own absolute path), verified live in a repo with no .flow/bin/.

Caveats / intentional limits

Agent inspection is not the command menu. grok inspect may omit plugin agents even though subagents dispatch. Command autocomplete was live-verified on Grok 0.2.111: /flow-next: lists user-facing commands including plan/work. A separate command-free skill probe showed the skill name and description, then rendered its argument-hint after Tab selection.
Nested Droid → Grok is unsupported if DROID_PLUGIN_ROOT propagates into a grok child (higher-precedence detection wins). Claude/Cursor launched from a grok shell still classify correctly.

Cursor

Cursor has its own plugin system in the .cursor-plugin/ namespace and does not auto-read Claude Code’s .claude-plugin/ (unlike Grok). Flow-Next ships a root marketplace manifest, a per-plugin .cursor-plugin/plugin.json (explicit skills/agents/commands/rules paths so installs never discover codex/ or tests/), and a Cursor-native rules/flow-next.mdc guidance rail.

Recommended: team-marketplace repo import

For teams (and anyone on Cursor Teams / Enterprise), import the GitHub repo as a team marketplace. This is the recommended Cursor install. An admin connects the Cursor GitHub App, imports gmickel/flow-next, and chooses an install mode:

Mode	Meaning
Default Off	Plugin available; each engineer opts in
Default On	Installed for the team; engineers can disable
Required	Forced on for every team member

Cursor auto-refreshes the marketplace on push (GitHub App webhooks, ~10-minute batching). Engineers then run /flow-next:setup once per repo (creates .flow/, writes the AGENTS.md model-routing scaffold, etc. - no copies of the CLI). No per-developer git clone + re-run-after-pull cycle.

Public Cursor Marketplace submission is not the path here (publisher-terms decision); team-marketplace repo import delivers the same one-click / auto-update / org-enforceable value without those terms.

Admin runbook

Import the repo. In Cursor team settings → Marketplaces / Plugins, import https://github.com/gmickel/flow-next via the Cursor GitHub App (requires admin on the Cursor team + GitHub App install on the org/repo).
Choose install mode. Prefer Default On for voluntary adoption, Required when every engineer must run flow-next on day one.
Verify auto-refresh. After a push that changes plugin files, wait for Cursor’s refresh window (~10 min batching) and confirm team clients pick up the new surface (skills/commands/rules count or a known skill description change).
Per-repo setup. Each engineer (or the first clone of each project) runs /flow-next:setup. Cursor exposes no plugin-root environment variable, so skills derive the plugin root from the absolute skill path Cursor already hands the agent - nothing is copied into the repo. Setup leads the review-backend menu with host (recommended) and writes a fully commented model-routing block into AGENTS.md for the team to fill in - it never probes Cursor for model ids and never writes one.

Fallback: local install scripts (individuals)

For solo use, air-gapped machines, or before team-marketplace is configured, the local installers copy a snapshot into ~/.cursor/plugins/local/flow-next (%USERPROFILE%\.cursor\plugins\local\flow-next on Windows):

macOS / Linux:

git clone --depth 1 https://github.com/gmickel/flow-next.git /tmp/flow-next-install \
  && /tmp/flow-next-install/scripts/install-cursor.sh \
  && trash /tmp/flow-next-install

Windows (PowerShell):

git clone --depth 1 https://github.com/gmickel/flow-next.git $env:TEMP\flow-next-install; `
  powershell -ExecutionPolicy Bypass -File $env:TEMP\flow-next-install\scripts\install-cursor.ps1; `
  Remove-Item -Recurse -Force $env:TEMP\flow-next-install

Both write a real directory (NOT a symlink; Cursor’s plugin loader rejects a symlink whose realpath escapes ~/.cursor/), exclude the Codex mirror and tests, and are a snapshot, so re-run after git pull to update. Fully restart Cursor (Cmd-Q / Quit, reopen), then run /flow-next:setup in the project. The Windows installer is a robocopy sibling of the bash script (Git Bash / WSL work too).

What works (verified)

Skills, commands, and subagents register and run. Slash autocomplete lists flow-next commands (hyphenated form, e.g. /flow-next-plan); the colon form (/flow-next:plan) also works when typed. Natural-language skill triggering works.
Native structured asks (including multi-question batches; Skip / Other honored).
Multi-agent: a full /flow-next:plan fans out scout subagents in parallel and drives flowctl end-to-end. Explicit caller-side subagent model pins (Cursor slugs, asked from cursor-agent --list-models) are honored.
review.backend host: fresh-context subagent review pinned via AGENTS.md routing / caller-side slug pins to a family that did not write the diff (preferred from inside Cursor; existing codex / copilot / cursor / claude CLI / rp backends remain selectable). See Review workflow and Orchestration.
flowctl resolves from the plugin install (derived from the skill file’s own absolute path), verified live in the CLI and the desktop app with no .flow/bin/ present.

Caveats / intentional limits

Agents frontmatter aliases → inherit. On Cursor, agents/*.md family aliases (opus, sonnet, …) are ignored; subagents inherit the session model. Caller-side in-prompt slug pins are the escape hatch. There is no alias-to-slug rewrite pass (marketplace import consumes canonical files as-is).
In-IDE browser (drive/QA rung 4). No extra install. If the agent cannot attach, type @Browser (no space) or open the Browser pane until it shows connected, and confirm Settings → Tools & MCP → Browser Automation is Browser Tab. A mid-run “MCP server does not exist” after it was already driving is a Cursor flake - quit, wait, fresh chat; @Browser will not restore that session. See Flow-Next Drive.

OpenCode

First-class host, installer-delivered. OpenCode has no Claude-plugin format - its native surfaces are the Agent Skills standard, markdown subagents, and markdown slash commands, and its own “plugin” system is JS event hooks. So there is no mirror and no marketplace entry: an installer scatters the canonical files into OpenCode’s global config directory.

git clone --depth 1 https://github.com/gmickel/flow-next.git /tmp/flow-next-install \
  && /tmp/flow-next-install/scripts/install-opencode.sh \
  && rm -rf /tmp/flow-next-install

What lands under ~/.config/opencode/: canonical skills as-is (minus setup), the plugin-root support dirs at the config root so flowctl and the spec-template cascade resolve unchanged, generated agents with canonical tool denials translated to OpenCode’s permission: map, and flat /flow-next-<name> command stubs. A deterministic ownership manifest scopes every re-run and --uninstall to installed paths only - a colliding user directory aborts the install instead of being deleted.

Know before you drive:

The slash form is flat: /flow-next-plan, not /flow-next:plan. Every /flow-next:<name> in these docs maps to /flow-next-<name> on OpenCode.
Setup runs like every other host: /flow-next-setup (flat form). Detection is positive - the installer’s ownership manifest at the config root is the platform signal, so setup writes AGENTS.md instructions in the flat slash form, never Codex-shaped snippets.
If a Codex install co-exists, its ~/.codex/scripts/flowctl wins the resolution cascade’s first rung - keep both installs current.
Model tiers pin via agent definitions, not dispatches: OpenCode subagents inherit the session model unless their own 5-line agent file pins one - the recipe (and the fail-closed behavior without a pin) is in the repo’s docs/reach/opencode.md. Verified live: an agent-pinned host reviewer ran on the routing block’s model with an honest receipt.
Verified live against opencode 1.18.19: 29/29 skills and 20/20 subagents discovered with correct permission maps, a full plan scout fan-out, codex-backend review, and host-backend review driven end-to-end from an OpenCode session. The separate flow-next-opencode port repo is superseded and archived.

Team / org-wide deployment (Claude Code managed settings)

To put Flow-Next on every developer’s Claude Code without each person running the install commands, deploy it through Claude Code’s settings. This is a Claude Code capability, meaning the coding agent in the terminal / IDE / desktop app, not the Claude Desktop chat app (which does not load Claude Code plugins). Codex uses its installer above; Cursor teams should use the team-marketplace path instead of managed-settings.json.

Two approaches, depending on how hands-off you want it.

Org-wide via managed settings (admin / IT)

Deploy a managed-settings.json to the OS path below, via MDM (Jamf, Kandji), Group Policy, or your config-management tool. Managed settings take precedence over user and project settings and cannot be overridden.

OS	Path
macOS	`/Library/Application Support/ClaudeCode/managed-settings.json`
Linux / WSL	`/etc/claude-code/managed-settings.json`
Windows	`C:\Program Files\ClaudeCode\managed-settings.json`

{
  "extraKnownMarketplaces": {
    "flow-next": {
      "source": { "source": "github", "repo": "gmickel/flow-next" }
    }
  },
  "enabledPlugins": {
    "flow-next@flow-next": true
  }
}

extraKnownMarketplaces auto-registers the marketplace, so no /plugin marketplace add is needed.
enabledPlugins force-enables the plugin for everyone (the key is plugin@marketplace).
To restrict which marketplaces users may add, add strictKnownMarketplaces (an allowlist); add pluginTrustMessage to append an internal approval note to the trust prompt.

Per-repo, no admin (project settings)

Commit a .claude/settings.json to the repo. Anyone who opens the repo and trusts the folder is automatically prompted to install the marketplace and plugin, with no admin rights and scoped to that repo:

{
  "extraKnownMarketplaces": {
    "flow-next": {
      "source": { "source": "github", "repo": "gmickel/flow-next" }
    }
  },
  "enabledPlugins": {
    "flow-next@flow-next": true
  }
}

Two things hold either way:

A one-time trust prompt still appears by design. The settings pre-register and enable the plugin so there is nothing to type, but Claude Code still asks each user to trust the plugin on first use.
Each repo still needs /flow-next:setup. Managed and project settings install the plugin and its /flow-next:* commands; setup is what wires the repo-local .flow/ state, flowctl, review backend, and agent instructions. Deploying the plugin org-wide does not run setup for you.

Reference: Claude Code plugin marketplaces and settings.

claude.ai, Cowork and organization plugin sync

Since 7.1.0 these surfaces no longer refuse Flow-Next. They reject any plugin with a top-level bin/ directory, and Flow-Next no longer ships one: the launcher it held was a second copy of scripts/flowctl, which every skill already runs by path.

First run

Run setup once in the repository, then type flow with whatever you have, in your host’s spelling. Flow reads it, picks the route, runs it, and stops at the next decision that is yours. Your First 30 Minutes walks one change that way.

Host	Setup	First request
Claude Code, Factory Droid, Grok Build	`/flow-next:setup`	`/flow-next:flow <what you have>`
Codex	`$flow-next-setup`	`$flow-next-flow <what you have>`
Cursor	`/flow-next:setup` or `/flow-next-setup`	`/flow-next:flow <what you have>`
OpenCode	`/flow-next-setup`	`/flow-next-flow <what you have>`

These are messages to the coding agent, never shell commands. flow --explain <what you have> prints the route and writes nothing.

Optional: export TYPESAFE_API_KEY=<key> in the shell that runs your agent turns on the Jev judgments (a fork-kind hint, memory ordering and task tier); without the key the route and every gate stay the same.

Recommended: seed the feature map. Setup always ends by recommending /flow-next:features ($flow-next-features on Codex, /flow-next-features on OpenCode). On an app with a user surface, it drives each main feature once and records how a user reaches it in .flow/features/, which you commit. QA, drive, and bug intake then read the route instead of rediscovering it, which takes fewer turns on “where is this screen” work. Setup never runs it for you because it launches the app; run it when the app starts locally. The map then stays current as you work: Keep the feature map current.

Every stage Flow runs is also a skill you can invoke by name. The same change, stage by stage:

Claude Code and Factory Droid:

/flow-next:setup
/flow-next:capture
/flow-next:work fn-1 --no-plan
/flow-next:make-pr fn-1

OpenAI Codex:

$flow-next-setup
$flow-next-capture
$flow-next-work fn-1 --no-plan
$flow-next-make-pr fn-1

In Codex you can also type $ and choose the matching Flow skill from the menu. work --no-plan is the direct route for a ready spec and runs the configured review inside it; /flow-next:plan fn-1 first is the exception, on a positive signal listed on How Flow chooses.

Optional CLI access

Slash commands are the workflow. flowctl is the deterministic state layer those commands call.

After setup, you can inspect state directly.

Every skill resolves the plugin’s scripts/flowctl itself. A bare flowctl is not on PATH, in your shell or in an agent’s shell outside a skill: since 7.1.0 the plugin ships no top-level bin/ directory, so Claude Code no longer puts one there. Run it by its path, or put the plugin’s scripts/ directory on your PATH (flowctl usage prints the full guide):

# pick the line for your harness's install location:
export PATH="$HOME/.claude/plugins/marketplaces/flow-next/plugins/flow-next/scripts:$PATH"   # Claude Code
export PATH="$HOME/.cursor/plugins/local/flow-next/scripts:$PATH"                            # Cursor (local install)
export PATH="${CODEX_HOME:-$HOME/.codex}/scripts:$PATH"                                      # Codex
flowctl specs
flowctl tasks --spec fn-1
flowctl ready --spec fn-1
flowctl show fn-1.1

Codex also installs a global copy under your Codex home (~/.codex by default, or wherever CODEX_HOME points):

CODEX_BIN="${CODEX_HOME:-$HOME/.codex}/scripts"
"$CODEX_BIN/flowctl" specs
"$CODEX_BIN/flowctl" tasks --spec fn-1

Use flowctl for automation and debugging. Use slash commands for planning, work, review, and handoff.

Updating

Updating is one step on every host: update the plugin. Done. Nothing lives in your repo to go stale, so there is no per-project setup re-run and no version-skew failure mode. Re-run /flow-next:setup only when a release says the docs-snippet schema bumped, or when you want to change configuration.

How you update the plugin itself depends on how Flow-Next is installed. Codex installs from a local snapshot of the repo, so update the source first or you reinstall the same version. Cursor team-marketplace auto-refreshes on push; Cursor local-script installs are the same snapshot class as Codex.

Coming from an older install? If your repo still carries .flow/bin/, .flow/templates/spec.md, or .flow/usage.md, delete them - nothing reads them, and a stale copied flowctl can shadow the current one (an EDITED .flow/templates/spec.md is the one exception: copy it to a repo-root SPEC.md first; setup never deletes a customized template). /flow-next:setup offers to remove them for you, and /flow-next:plan prints a one-line nudge when it sees them.

Claude Code / Factory Droid

Update the plugin from the marketplace and reload. That is the whole update:

/plugin            # update flow-next to the latest release
/reload-plugins

(Factory Droid: update via droid plugin.)

OpenAI Codex

Pull the repo and re-run the installer. That refreshes the global skills, agents, and the ~/.codex/plugin.json version. Running /flow-next:setup alone does not update the global Codex install, and scripts/sync-codex.sh only rebuilds the in-repo mirror. Neither writes to ~/.codex. The installer is the updater:

cd flow-next
git pull
./scripts/install-codex.sh flow-next

Then fully restart Codex so it reloads the refreshed install. No per-project step.

Cursor

Team marketplace: auto-refreshes on push (~10 min batching). No per-developer reinstall, no per-project step. Re-run /flow-next:setup only when the instructions-snippet schema bumps or you change config - never for plugin updates.
Local script install: re-run the one-shot installer from Cursor above, which clones the latest release fresh each time, then fully restart Cursor (a reloaded local plugin needs a complete quit/reopen).

Uninstall

Flow-Next stores project state in the repo:

rm -rf .flow/

If you initialized Ralph on flow-next 6.7.x or earlier, remove its repo-local scripts and any ralph-guard hook entries from your project settings too:

rm -rf scripts/ralph/

Review the diff before deleting tracked .flow/ files in a team repo.