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

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
/flow-next:setup

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

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, and RepoPrompt-oriented review workflows.
• Optional Ralph loop: repo-local automation for crisp specs that are already safe to execute.

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, with RepoPrompt-oriented review workflows and an OpenCode community port.

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.