Skip to content
GitHub

Your First 30 Minutes

This is the run-through for your first half hour: one small, real change taken from idea to reviewed PR. Not a feature tour - a narrative of what you type and what you see. The example repo is a small web API and the change is deliberately modest: adding a --json flag to an existing CLI export command.

Minutes 0-5: install and setup

Section titled “Minutes 0-5: install and setup”

Install the plugin for your platform (per-platform steps), then initialize the repo you want to work in:

/flow-next:setup

On Claude Code, setup asks one question: is this repo Claude-Code-only? Say yes and you get plugin mode - nothing is copied, flowctl is already on the agent’s PATH, and you will never re-run setup for an update. Say no (teammates on Codex/Cursor, CI) and setup copies the flowctl CLI into .flow/bin/ and writes .flow/usage.md - copy mode, the default on every other host. Either way it offers a short instructions block for your CLAUDE.md/AGENTS.md, and all state lives repo-locally under .flow/ - no server, no account. Verify (plugin mode: just flowctl list):

Terminal window
.flow/bin/flowctl list
Flow Status: 0 specs, 0 tasks (0 done)

An empty factory. Good.

Minutes 5-12: plan the change

Section titled “Minutes 5-12: plan the change”

Describe the change to the planner:

/flow-next:plan add a --json flag to the export command so scripts can consume the output

The plan skill interviews the codebase (read-only scouts), writes a spec with numbered acceptance criteria, and breaks it into context-fit tasks. When it finishes:

Terminal window
.flow/bin/flowctl list
Flow Status: 1 spec, 2 tasks (0 done)


[open] fn-1-export-json-flag: Add --json flag to export command (0/2 done)
    [todo] fn-1-export-json-flag.1: Wire --json flag + JSON serializer
    [todo] fn-1-export-json-flag.2: Tests + docs for JSON output (deps: fn-1-export-json-flag.1)

Open the spec itself - this is the artifact everything else hangs off:

Terminal window
.flow/bin/flowctl cat fn-1-export-json-flag

You will find a goal, boundaries, and criteria like **R1:** \export —json` emits valid JSON to stdout - numbered, so tasks, commits, and the eventual PR can reference them precisely. If a criterion is wrong, edit it now; the spec is cheapest to fix before any code exists. When it reads right, this is also the moment to glance at the plan the way a reviewer would - or let a second model do it with [/flow-next:plan-review`](/skills/plan-review/) (optional for a change this small; habit-forming for bigger ones).

Minutes 12-25: work it

Section titled “Minutes 12-25: work it”
/flow-next:work fn-1-export-json-flag

Work dispatches a fresh-context worker per task. Each worker re-anchors first - rereads the spec, its task, and git state - then implements, commits, and records evidence. The transcript tail for a task looks like:

Task fn-1-export-json-flag.1: done
  Commit: a1b2c3d feat(export): --json flag + serializer (fn-1-export-json-flag.1)
  Tests: pytest tests/test_export.py -q (green)
  Summary: --json flag wired through the export command; serializer covers all row types.

That done was not self-declared prose: flowctl done refuses to complete a task without evidence JSON - commits, test commands, a summary. When both tasks finish, the implementation review gate runs (cross-model - a different model family reads the diff blind):

VERDICT: SHIP
Receipt: .flow/review-receipts/fn-1-export-json-flag.json

If the reviewer had found something, work would fix it and re-review until SHIP - that loop is the quality mechanism, not a failure mode.

Minutes 25-30: open the PR

Section titled “Minutes 25-30: open the PR”
/flow-next:make-pr fn-1-export-json-flag

The PR body is generated from flow state, not from vibes: a TL;DR, an R-ID coverage table mapping each acceptance criterion to the commits that satisfy it, critical changes, and a risk-bucketed review plan telling your reviewer what to actually read. Your reviewer gets an argument, not an archaeology dig.

What you now have on disk

Section titled “What you now have on disk”

Thirty minutes in, the point of the system is sitting in your repo:

  • .flow/specs/fn-1-export-json-flag.md - the spec, now immutable change history
  • .flow/review-receipts/fn-1-export-json-flag.json - the SHIP verdict, auditable forever
  • Evidence JSON on both tasks - commits + test commands, queryable via flowctl show <task> --json
  • A PR that proves the change instead of describing it

That inventory - not any single stage - is what Flow-Next is for: the verification spine.

Where to go from here

Section titled “Where to go from here”