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.

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

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. Since 3.0 no hooks ship by default (Ralph registers its own via /flow-next:ralph-init); 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.
Ralph autonomous mode is intentionally not built for Grok. Same posture as Cursor - not a schema gap and not “TBD validation.” Setup never offers Ralph on Grok, never registers guard hooks, and never runs ralph-init from the ceremony. Interactive plan / work / review is the supported surface.
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 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).
Ralph autonomous mode is intentionally not built for Cursor. Cursor has a full agent-hook set, but flow-next does not register Ralph guards on Cursor. Interactive plan / work / review is the supported surface. Scaffolding scripts/ralph/ does not enable the autonomous loop here.
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.

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.

First run

Start from a conversation or a clear request.

Claude Code and Factory Droid:

/flow-next:setup
/flow-next:capture
/flow-next:plan fn-1
/flow-next:work fn-1
/flow-next:impl-review fn-1
/flow-next:spec-completion-review fn-1
/flow-next:make-pr fn-1

OpenAI Codex:

$flow-next-setup
$flow-next-capture
$flow-next-plan fn-1
$flow-next-work fn-1
$flow-next-impl-review fn-1
$flow-next-spec-completion-review fn-1
$flow-next-make-pr fn-1

In Codex you can also type $ and choose the matching Flow skill from the menu.

Optional CLI access

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

After setup, you can inspect state directly.

Agents resolve flowctl from the plugin install themselves. For your own shell, put the plugin’s scripts/ directory on your PATH (Claude Code also injects bare flowctl for agent sessions, and 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, remove its repo-local scripts too:

rm -rf scripts/ralph/

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