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.

flowchart LR
  Intent["Rough intent"] --> Capture["/flow-next:capture or interview"]
  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.

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

Spec ids

fn-1 is the default Flow-Next id form, used throughout these docs. A spec linked to a tracker (Linear, GitHub, GitLab, or Jira) is referenced by its tracker key instead — /flow-next:work wor-17 works exactly the same way. Both forms resolve everywhere a spec id is accepted. See Spec & task ids.

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

If Flow-Next is already installed in Claude Code, Grok reads the plugin with zero config — confirm with grok inspect. Drive it with the same /flow-next:* commands as Claude Code (type them in full — the slash menu under-lists them, but they run when typed). Multi-agent flows are verified; Ralph is not yet validated. Don’t use grok plugin install <repo> (the repo is a marketplace).

Cursor

Cursor has its own plugin namespace and doesn’t read Claude Code plugins, so install via the 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

Then run /flow-next:setup in your project and drive with /flow-next:* (type in full). Skills, commands, and multi-agent flows are verified; Ralph is unsupported on Cursor (hook-schema mismatch).

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

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

Flow-Next is first-class on Claude Code, OpenAI Codex, and Factory Droid, also runs on xAI Grok Build and Cursor (local plugin), with RepoPrompt-oriented review workflows and an OpenCode community port. See the install matrix for per-harness setup + 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.