Your First 30 Minutes

Take one small change from a description to a reviewed pull request. You will inspect the spec before implementation and the evidence before opening the PR. Allow about half an hour after installation; review rounds and your project’s tests determine the actual duration.

Use an existing repository with a small change ready, or the two-file Python example below. The example adds a --json flag to a text export command while keeping its existing output unchanged.

Minutes 0-5: install and setup

Install Flow-Next for your coding agent. You need Python 3.11+, your agent access, and a working project environment. Opening the final PR also needs an authenticated gh and a GitHub repository you can push to. Review setup covers the reviewer options; for this tutorial, ask setup to configure a reviewer from a different model family that your environment can reach.

Start with the example

Download export.py and test_export.py into a new directory, then run these commands in your terminal:

git init -b main
python3 -m unittest -v
python3 export.py
git add export.py test_export.py
git commit -m "chore: add text export example"

The baseline has one passing test and prints:

Ada: engineer
Lin: reviewer

Add your GitHub remote before the PR step. You can also complete the local spec, implementation, and review steps without a remote.

Set up your agent session

Open that directory in your coding agent. Invoke setup in the agent conversation:

Host	Invocation
Claude Code, Factory Droid, Grok Build	/flow-next:setup
Codex	$flow-next-setup
Cursor	/flow-next:setup or /flow-next-setup
OpenCode	/flow-next-setup

Setup creates project state and offers an instructions block. The plugin supplies the CLI; you do not need to copy it into the project. Choose the review setup described above, then ask the agent to show the empty task list.

Minutes 5-12: plan the change

Send this request to your agent:

Use Flow-Next to capture this change as a spec, show it to me, then plan it.

Add --json to export.py. With the flag, stdout must contain only a JSON
array with the same name and role fields as the current rows. Without the
flag, keep the existing text output exactly. Unknown flags must fail with
a nonzero exit and an error on stderr. Use Python's standard library.

The agent drafts the spec and shows it for your review. Check that it includes the JSON behavior, text compatibility, invalid flags, and dependency constraint. Correct a wrong requirement before approving it.

Acceptance criteria get identifiers such as R1 and R2. Tasks reference those identifiers so the final PR can explain which changes satisfy which requirements. Use the actual spec ID returned by your agent in subsequent steps; fn-1 below is an example.

The explicit invocations are capture, then plan <spec-id>, using your host’s prefix from the setup table. Choosing your route covers other starting points once you have tried this run.

Minutes 12-25: work it

Use Flow-Next to work fn-1 on a new branch. Use the configured cross-family
reviewer, fix the review findings, and show me the verification evidence.

Each task starts in a fresh worker context. The worker reads the spec and current code, establishes the test baseline, implements the change, and runs its checks. The review loop asks another model to examine the result and works through its findings.

At the end, inspect the changed code and run these commands in your terminal:

python3 -m unittest -v
python3 export.py
python3 export.py --json
python3 export.py --unknown

Check that the tests cover all three behaviors. The text output should match the baseline; the JSON output should parse as an array of the two row objects; the unknown flag should fail. The last command is deliberately an error case.

Ask the agent to show the task evidence and review receipt. Check the referenced commit and test commands, the review verdict, and any remaining findings. The wording of the transcript will vary with your agent; those artifacts are the result to inspect.

Minutes 25-30: open the PR

Once the GitHub remote and authentication are ready:

Use Flow-Next to open a draft PR for fn-1.

The explicit command is make-pr <spec-id>, with your host’s invocation prefix. It pushes the branch and opens the PR. Read the explanation of the change, acceptance coverage, verification, and files that need human attention. Merge when your normal review process is satisfied.

What you now have on disk

• A spec under .flow/specs/ recording the intended behavior and boundaries.
• Task records under .flow/tasks/ connecting implementation to acceptance criteria and evidence.
• A review receipt under .flow/review-receipts/ recording the verdict for the reviewed work.
• The implementation and tests in Git, with a PR explaining what to review.

One real change through review shows the same chain in Flow-Next’s own development, including the defect the review caught.

Where to go from here

• Compose the pipeline to shorten, extend, or chain your next run.
• What each layer costs to choose the work you want agents to do for you.
• For teams to share the spec and review responsibilities.
• Going autonomous to keep working between sessions.

Upgrading an older install? Remove obsolete copied files in the upgrade guide. A fresh install needs none of that cleanup.