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 and install the plugin:

/plugin marketplace add https://github.com/gmickel/flow-next
/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

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

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

After a plugin update, re-run setup in active repos:

/flow-next:setup

For Codex, also re-run ./scripts/install-codex.sh flow-next so global agents, hooks, and skills are refreshed.

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.