Your First 30 Minutes

Flow-Next runs inside your coding agent. One command, /flow-next:flow, reads whatever you hand it, decides what should happen next, and does it. Where it needs a pick from you, it asks inline and continues. It stops at the decision that ends the run: a finished change waiting for you to say “open the PR”, or a product choice only you can make. This page takes you from install to a pull request on one item of your own. Allow half an hour. The change itself comes back in about the time plain Claude Code, or your harness, takes, often less; the optional review and live QA stages add quality on top, and your project’s tests and those stages set the real duration.

Install and set up one project

Install Flow-Next for your coding agent. Then open any project you want to try it on and, in the agent conversation, run setup:

/flow-next:setup

On Codex the same command is $flow-next-setup, on OpenCode /flow-next-setup. The rest of this page writes the Claude Code form; the other two spellings apply throughout. Muse Code uses the Claude Code form, in a session started with muse --disable-sandbox (why). Setup creates a .flow/ directory in the project. That is where Flow-Next keeps its specs (the written intent and acceptance criteria for a change), its tasks (the implementation records behind a spec), and its receipts (the recorded result of each check and review). It also offers a short block for your instructions file and, if you want one, a seed file for project-wide acceptance criteria.

Setup also asks about an independent reviewer (a second model family that checks the work) and live QA (a driver that exercises the running app). For this run choose no reviewer and leave QA off. A tracker such as Linear or Jira is connected later through tracker sync. Each of these is a gate Flow runs when configured and records as skipped, with the reason, when not, so a run without them is still complete and inspectable. When you want them: review backends and live QA.

Setup ends by recommending one more step: /flow-next:features, which seeds a committed feature map at .flow/features/. If your project has a user surface that starts locally, run it once. It drives each main feature and records how a user reaches it, so QA, drive, and bug intake read the route instead of rediscovering it, in fewer turns. It is optional for this walkthrough, and work keeps the map current as later changes move routes (how).

The router hides the machinery

Flow-Next has a full pipeline underneath: capture, refine (interview), plan, plan-review, work, review, QA, make-pr, and more. You can invoke every stage by name, and the pipeline explains each one. This page uses none of them directly. /flow-next:flow picks the stage that fits the item and its current state, runs it, looks at the new state, and picks again. You see the choices as it makes them. When you want the controls yourself, the skills index lists every stage, and How Flow chooses shows how to read a route and override it.

Hand Flow something you actually have

In the agent conversation, type /flow-next:flow followed by the item. Any of these works:

/flow-next:flow WOR-17
/flow-next:flow https://linear.app/acme/issue/WOR-17
/flow-next:flow Add --json to the export command. With the flag, stdout is a JSON array with the same fields as the text rows. Without it, nothing changes.
/flow-next:flow <a pasted bug report or stack trace>
/flow-next:flow the /reports page takes 4 seconds, it should take under 1

Flow reads the content, not the form. A ticket key is read through whatever tracker access your session already has. A pasted stack trace, a sentence of intent, and a URL are each read for what they mean and for what already exists for them on disk. Then it matches that against the route matrix, which names the first step for every kind of starting point. How Flow chooses walks fifteen of them.

For a feature or a change you can state that is bigger than one local fix, that first step is capture. Capture turns the conversation into a spec: a title and a handful of acceptance criteria, each criterion tagged with where it came from, whether you said it, Flow paraphrased it, your project strategy supplied it, or Flow inferred it. It saves the spec and shows a compact summary. The summary has this shape:

Title: Quality gates for the export API
Criteria: 6
Source: [user] 4 · [paraphrase] 2 · [strategy] 0 · [inferred] 0
Recommended next: /flow-next:work <new spec> --no-plan - ready cohesive spec; no positive plan signal
Saved: .flow/specs/fn-1-quality-gates-export-api.md

Read the Source: line first. [inferred] 0 means Flow added nothing you did not say or clearly imply. Capture offers to open the saved file in your editor or continue. Type a correction and the agent edits that file, re-reads it, and validates the result. To see the full spec, open the Saved: path or ask for it. Saving alone does not authorize implementation; here, your request to build the feature lets Flow continue.

If you handed it something else

The matrix has a first step for each kind of item, and capture is only one of them:

• A small local change is changed directly, checked, and handed back. No spec, and no pull request unless you ask for one.
• A defect starts with a check for existing fixes, then a reproduction and a confirmed cause. The failing reproduction becomes the acceptance criterion, and the fix must turn it from failing on the base to passing on the head.
• A slow path is measured first on the real page, endpoint, or command. The baseline and the target become the criterion.
• A question about the code is answered with citations from the repo, its history, and memory. Nothing is written.
• A large, unclear idea goes to chart to find its boundaries before any spec exists.
• An existing spec, branch, or open PR resumes from wherever it is on disk.

How Flow chooses walks every row with a diagram.

The next step is always named

In the capture summary above, the Recommended next: line names what comes next: implement the spec directly, without splitting it into tasks, because the spec is cohesive and nothing asked for a plan. When you asked Flow to implement the change, it takes that step itself and keeps going, through the configured review, until the change is committed on a local branch. It stops earlier only when a decision is genuinely yours, such as a product choice the spec leaves open.

Two commands make the routing visible at any point:

• /flow-next:flow --explain fn-1 prints the decision and writes nothing. From the same real run:

  Route: /flow-next:work <spec-id> --no-plan (direct execution, the default)
  Signal: ready spec, zero tasks, no recorded route; six cohesive acceptance criteria (R1-R6) on one script that a single owner can implement end to end
  Skip/narrow: /flow-next:plan skipped; the read-first research pass skipped
  Skip kind: signal absent
  Why not the alternatives: none of the three plan signals is present (no plan requested, no separate owners, single PR); the spec is stdlib-only so no unfamiliar library triggers refine --scope=research; no design risk or open product choice for plan-review or refine

• /flow-next:flow with nothing after it takes the next step for the most recent item it can see, in this order: the spec, task, or PR this conversation last touched; the spec that matches your current branch; intent in the conversation that no spec captures yet, which it offers to capture; the next open spec in .flow/, with a pick when several are equally plausible. It asks what to work on only when none of those resolves. So if you stop a run, close the conversation, or come back tomorrow, the bare command picks up where things stand.

What you get at the stop

The run ends when the change is built and committed on a local branch, with one report. Nothing is pushed yet. The shape is fixed; the stages and times are yours:

Flow stopped at: change committed on a local branch; the pull request is your call
Route taken: capture -> work
stage: capture - ran [<start>..<end>]
stage: plan - skipped(policy: no positive plan signal; route recorded no_plan)
stage: work - ran [<start>..<end>]
stage: impl-review - skipped(config: review.backend=none)
stage: qa - skipped(config: pipeline.qa=off)
Next: Say 'open the PR' when you want it

Every stage Flow reached has one line, and every skip carries its reason. With a reviewer configured, the impl-review line reads ran and its verdict sits in a receipt under .flow/review-receipts/, except for a change so small that a recorded triage skip satisfies the gate, or a small local fix to output, wording or display, which is not reviewed and says why. When you are in the session, Flow hands the result back first and reports the review verdict, and any fix, when it lands in the background.

Read the diff on the branch. When you want the pull request, say “open the PR”. Flow runs make-pr, which pushes the branch and opens a pull request whose body gives the reading order, maps each acceptance criterion to the review step that covers it, ticks only the checks that passed, and lists anything that still needs a human. Flow does not ask whether to land a pull request it just opened. A later /flow-next:flow on the open PR offers landing and asks once unless you already authorized that item. Use /flow-next:flow fn-1 --until=merge to authorize continuation through land’s review-thread, CI, and merge gates.

From here

One command, or the same stages invoked by hand, takes an idea, a bug, a slow path, or a prototype to a finished pull request with the evidence attached. Where to go next:

• How Flow chooses to read any route and override it.
• The pipeline for what each stage does and what it leaves behind.
• One change through review for a real change and what its review caught.
• Going autonomous when you want the runs to continue without you at the keyboard.

Upgrading an older install? The upgrade guide covers files an older install may have left behind.