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.

Most users should start with /flow-next:setup. It is idempotent and wires the repo-local .flow/ state, review backend, local flowctl, and agent instructions.

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
copies flowctl to .flow/bin/
adds Flow-Next instructions to CLAUDE.md or AGENTS.md
writes .flow/usage.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 and hooks. The installer copies skills, agents, hooks, prompts, templates, and flowctl into ~/.codex/, then updates ~/.codex/config.toml.

Re-run the script after pulling a new Flow-Next release:

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

xAI Grok Build

Grok Build reads Claude Code plugins, skills, hooks, and MCP servers with zero configuration. If Flow-Next is already installed in Claude Code, Grok picks it up automatically — confirm with grok inspect. No marketplace entry, no extra setup.

This is verified working, multi-agent flows included — 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. You drive it with the same /flow-next:* commands as Claude Code.

Two caveats, both cosmetic — the commands still run:

The slash autocomplete under-lists Flow-Next. Grok’s menu only shows skills marked user-invocable; Flow-Next’s slash commands are command wrappers, so most don’t appear in the menu. Type the command in full — /flow-next:plan fn-1, /flow-next:work fn-1 — and it runs.
grok inspect doesn’t list Flow-Next’s agents. The 21 subagents don’t show in the inspect summary, but they dispatch correctly at runtime (verified above).

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 path above, or add gmickel/flow-next as a [[marketplace.sources]] entry in ~/.grok/config.toml.

Ralph autonomous mode on Grok is not yet validated; everything else in the workflow runs.

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 .cursor-plugin/plugin.json manifest plus a one-shot local installer for macOS / Linux and 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

The Windows installer is a robocopy-based sibling of the bash script — same destination, same excludes, same real-directory contract. (You can also run the bash script under Git Bash / WSL.)

Both copy the plugin into ~/.cursor/plugins/local/flow-next (%USERPROFILE%\.cursor\plugins\local\flow-next on Windows) as 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 — re-run after git pull to update. Then fully restart Cursor (Cmd-Q / Quit, reopen — a new local plugin needs a full restart) and run /flow-next:setup in your project.

This is verified working, multi-agent flows included — a full /flow-next:plan under Cursor fanned out the scout subagents in parallel (Opus 4.8) and drove flowctl to create the spec and tasks end-to-end. flowctl resolves via the project-local .flow/bin/flowctl after /flow-next:setup (Cursor exposes no plugin-root env var).

Two caveats are cosmetic — the commands still run:

No grouped “plugin” card. Cursor registers the individual skills / commands / agents (they appear in the / menu and the skill/command/subagent lists), but Flow-Next does not show as a single plugin in the marketplace UI.
The slash autocomplete under-lists Flow-Next for the same reason as Grok — the commands are wrappers. Type the command in full and it runs.

One hard limitation:

Ralph autonomous mode is NOT supported on Cursor. Cursor’s hook schema is afterFileEdit / beforeShellExecution; Flow-Next’s hooks use Claude Code’s PreToolUse / Stop + Bash|Execute matchers, which Cursor doesn’t recognize — so the Ralph guard never fires. The interactive plan / work / review / make-pr workflow is unaffected.

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 — the coding agent in the terminal / IDE / desktop app, not the Claude Desktop chat app (which does not load Claude Code plugins). Codex and Cursor use their own installers above.

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 — no /plugin marketplace add 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 — no admin rights, 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.

Claude Code and Factory Droid project setup writes .flow/bin/flowctl:

export PATH=".flow/bin:$PATH"
flowctl specs
flowctl tasks --spec fn-1
flowctl ready --spec fn-1
flowctl show fn-1.1

Codex also installs a global copy at ~/.codex/scripts/flowctl:

~/.codex/scripts/flowctl specs
~/.codex/scripts/flowctl tasks --spec fn-1

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

Updating

How you update depends on how Flow-Next is installed. Codex and Cursor install from a local snapshot of the repo — update the source first, or you reinstall the same version. After the install is current, re-run /flow-next:setup in each active repo to refresh .flow/bin/flowctl, templates, and agent instructions.

Claude Code / Factory Droid

Update the plugin from the marketplace, reload, then re-run setup:

/plugin            # update flow-next to the latest release
/reload-plugins
/flow-next:setup   # in each active repo

(Factory Droid: update via droid plugin.)

OpenAI Codex

Pull the repo and re-run the installer — this refreshes the global skills, agents, hooks, 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 re-run $flow-next-setup in each project and fully restart Codex so it reloads the refreshed install.

Cursor

Re-run the one-shot installer from Cursor above — it clones the latest release fresh each time — then fully restart Cursor (a reloaded local plugin needs a complete quit/reopen). Then re-run /flow-next:setup in each project.

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.