Introduction

Flow-Next is an agent-native workflow system for shipping higher-quality software with agents. It turns rough intent into durable specs, specs into context-sized task graphs, task graphs into re-anchored worker runs, and implementation into reviewed PRs with receipts.

The unit of work is the spec. Not the ticket, not the chat transcript, not the PR title. A spec lives in .flow/specs/<id>.md, carries numbered acceptance criteria, and stays durable across planning, execution, review, and handover.

The repeatability comes from the plan/work loop. /flow-next:plan decomposes the spec into dependency-ordered tasks sized for focused agent context windows. /flow-next:work gives each ready task a fresh worker context, rereads the spec, task, git state, and repo conventions, then records evidence as it moves. The agent is not carrying yesterday’s chat scrollback. It is executing the right slice of the right spec with the right context every time.

That loop is the whole product. Spec -> plan -> work is a complete way to use Flow-Next; everything else you will read about here - tracker sync, live QA, cross-model review backends, the autonomous loops - is a layer you switch on deliberately, with a cost worth knowing first. Running Lean prices each one and frames the two operating profiles that decide which set you want.

flowchart LR
  Intent["Rough intent"] --> Capture["/flow-next:capture or interview"]
  Intent -.->|"optional when unclear"| Chart["/flow-next:chart"]
  Chart -.-> Capture
  Capture --> Spec[".flow/specs/<id>.md"]
  Spec --> Plan["/flow-next:plan sizes work"]
  Plan --> Tasks["Context-fit dependency graph"]
  Tasks --> Work["/flow-next:work fresh worker"]
  Work --> Review["Adversarial review loop"]
  Review --> PR["PR + receipts + handover"]
  Review -.->|"opt-in: pipeline.qa (default off)"| QA["/flow-next:qa live-app pass"]
  QA -.-> PR
  PR --> Ship["Merge + release\n(or /flow-next:land)"]

That walk has a canonical page, The Pipeline, covering every stage, the autonomy loops that drive the same stages hands-free (pilot builds, land ships, Ralph hardens), and the optional HTML render lenses that attach at each human touchpoint: spec review, plan review, diff review. Optional chart is pre-capture discovery for one oversized unclear idea - not part of the first-run happy path; guide picks the smallest sufficient route when you are unsure.

What you get

Spec-driven development: rough intent becomes acceptance criteria, boundaries, constraints, and decision context that survive beyond one chat.
Context-fit planning: /flow-next:plan sizes tasks so agents work inside focused context windows instead of drowning in the whole repo.
Re-anchored execution: /flow-next:work runs focused workers that reread the spec, task, git state, and relevant code before editing.
Automated adversarial review: plan review, implementation review, and completion review loop until introduced issues are fixed.
Receipts and handovers: review verdicts, evidence, and next-step context live in the repo, so “done” means there is proof.
Drift prevention: plan-sync, docs discipline, spec completion review, and cognitive-aid PR bodies keep implementation, docs, and reviewer context aligned.
Multi-harness support: Claude Code, OpenAI Codex, Factory Droid, xAI Grok Build, Cursor, and RepoPrompt-oriented review workflows.
Autonomy suite: pilot builds (ready spec → draft PR, driven by your host’s /loop or /goal), land ships (CI kept green, reviews converged, gated merge + release), and Ralph is the hardened harness for unattended scale. All three are gated by the spec-level ready flag.
Optional render lenses (2.0.0+): opt-in self-contained HTML artifacts at the human touchpoints: a spec visualizer for business and plan review, a PR review instrument for diff review. Markdown stays the record.

Quick start

Pick the block for your agent harness. For the full install path and update notes, see Install.

Claude Code and Factory Droid

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

/reload-plugins loads the freshly installed plugin so its /flow-next:* commands become available without restarting Claude Code. (On Factory Droid, install via droid plugin marketplace add … && droid plugin install flow-next.)

Then run the workflow with slash commands:

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

OpenAI Codex

Clone and run the installer so bundled skills, agents, hooks, templates, and flowctl are wired into ~/.codex/config.toml:

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

Then run setup from your project using the Codex skill name:

$flow-next-setup

Use Codex skill names from the $ menu for the workflow:

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

xAI Grok Build

First-class host. Setup detects Grok via GROK_AGENT=1 (not the Codex fallback). Grok reads the canonical Claude plugin as-is; if it is already installed in Claude Code, confirm with grok inspect. Type /flow-next: to open the command autocomplete; /flow-next- searches the separate hyphen-named skill surface. flowctl resolves from the plugin install (derived from the skill file’s absolute path - nothing is copied into the repo); lifecycle docs default to CLAUDE.md, model-routing to AGENTS.md (Grok loads both). review.backend host is available with single-family fail-closed (grok-4.5 only - cross-family via bridges). Multi-agent flows are verified; Ralph is intentionally not built (same posture as Cursor). Don’t use grok plugin install <repo> (the repo is a marketplace).

Cursor

Recommended (teams): import gmickel/flow-next as a Cursor team marketplace (admin runbook on Install → Cursor: Default On / Required, auto-refresh on push). Then /flow-next:setup once per repo.

Fallback (solo / air-gapped): local installer, then fully restart Cursor:

git clone https://github.com/gmickel/flow-next.git
cd flow-next
./scripts/install-cursor.sh        # Windows: install-cursor.ps1

Drive with /flow-next:* (autocomplete lists the hyphenated form, e.g. /flow-next-plan; colon form also works; natural-language skill triggering works). Multi-agent, native structured asks, and review.backend host are verified; Ralph is intentionally not built for Cursor.

Why plan and work matter

Most agent workflows fail because one giant prompt becomes the working memory, task tracker, product spec, and review plan. Flow-Next splits those responsibilities.

The planner turns a spec into a graph of executable slices. It identifies dependencies, parallelism, risk boundaries, and task size so the worker is not asked to solve the whole product change at once. Large work becomes a sequence of tasks that fit the context window on purpose.

The worker executes one ready slice at a time. It starts fresh, re-anchors on the spec and current repository state, uses subagents when focused investigation helps, updates Flow-Next state, and leaves receipts. That is the core quality advantage: less drift, less stale context, fewer hidden assumptions, and a repeatable path from intent to reviewed code.

flowchart TD
  Spec["Spec with acceptance criteria"] --> Planner["/flow-next:plan"]
  Planner --> A["Task slice A\nbounded context"]
  Planner --> B["Task slice B\nbounded context"]
  Planner --> C["Task slice C\nbounded context"]
  A --> WA["/flow-next:work\nfresh worker"]
  B --> WB["/flow-next:work\nfresh worker"]
  C --> WC["/flow-next:work\nfresh worker"]
  WA --> Review["review receipts"]
  WB --> Review
  WC --> Review
  Review --> Complete["spec completion review"]

Why it exists

Agentic engineering compresses implementation from weeks to hours. The standups, hallway clarification, and mid-flight course correction that used to finish vague requirements disappear. Flow-Next moves precision upstream and makes every handover reviewable.

The goal is not to make agents write more code. The goal is to make the work surface precise enough that agents can produce production-grade changes repeatedly and reviewers can verify them quickly.

Platforms

First-class on Claude Code, OpenAI Codex, Factory Droid, Cursor, and xAI Grok Build. Community port for OpenCode.

RepoPrompt-oriented review workflows run alongside all of them. See the install matrix for per-harness setup and caveats.

Solo path

Use the short path when one person owns product judgment, technical judgment, and final review:

/flow-next:capture
/flow-next:interview fn-1
/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

The important habit is re-anchoring. Before every work pass, the worker returns to the spec, the ready task, current git state, and relevant repo context. Flow-Next encodes that habit into the command workflow so solo work stays crisp even after context compaction, interruptions, or failed attempts.

Team path

Teams should treat the spec as the replacement for missing implementation touchpoints:

flowchart LR
  PO["PO or PM"] --> Business["Business spec pass"]
  Business --> Lead["Tech lead"]
  Lead --> Technical["Technical spec pass"]
  Technical --> Plan["Plan review"]
  Plan --> Agent["Agent implementation"]
  Agent --> Reviewer["Human review"]
  Reviewer --> Merge["Merge"]

Recommended command sequence:

/flow-next:interview fn-1 --scope=business
/flow-next:interview fn-1 --scope=technical --strategy --docs
/flow-next:plan-review fn-1
/flow-next:plan fn-1
/flow-next:work fn-1
/flow-next:impl-review fn-1
/flow-next:make-pr fn-1

The business pass answers what should exist and why. The technical pass answers how it must fit the repo. The plan and review gates keep those two layers from drifting apart.