Flow is an IDE, so most of it is somewhere you look: a map of what your project does, the knowledge behind it, a board the work moves across, a workspace per conversation, and your own app running beside the code. Those surfaces come first below.
The work itself runs up a ladder of four stages — find out what you are building, plan it, run the plan, review what landed. Each stage writes a document into your repository, and each one has to leave proof behind before the next will run.
You can type the four commands yourself, or turn on autopilot and have the chain issue them for you. Either way the gate is the same one.
/discovery-plan "usage-based billing" # what are we building? /create-plan @flow/discovery/discovery_usage_billing_v1.md /execute-plan @flow/plans/plan_usage_billing_v1.md /review-code
Point Flow at a repository. The map derives itself on first open, and a structural pass runs on its own — always, and at no cost to you. A one-time sweep then learns the project into the documents the rest of the app reads, and from then on a module is re-learned when its code drifts away from what was written down.
Nothing needs configuring first. When you want to change how a run behaves — commits, pushes, pull requests, autopilot — that is /flow, and the settings are all optional.
The commands are how work moves through the project. These are the places you look at it.
The sheet Flow opens on: your project drawn as the things it does. Three statements, each enforced in code rather than maintained by hand.
Behind its own toggle sits the derived graph — the structure rather than the capabilities.
What your team knows about the code, written beside it as plain markdown and kept honest by content hashes — and, when you share it, learned once for everybody.
Todo, Doing, Blocked, Review and Done, opened as an editor tab. One rule shapes the whole model: Todo is a window, while Doing, Blocked and Done are records.
Every conversation that touches code gets its own git worktree, so nothing an agent does happens in the tree you are working in.
Parallel agents produce conflicts, so resolving them is a surface of its own rather than a shell-out.
Your app runs inside Flow, next to the code — and so do the terminals running it. Both halves are collected, so what your app did is something you hand over rather than something you describe.
Flow runs both halves of a web application — the app in its embedded browser, the backend in its terminals. A debug session is a window over both at once, on one clock.
Work that carries on between your sessions. Two engines: a producer that goes looking, and a consumer that picks things up.
Two ways in: one for when you know what you want, one for when you know what it says.
Which AI runs your work, and where Flow itself runs.
Work out what you are actually building
Reads every document you point at, finds the related code in your project, and asks you the questions that the request left open. It writes down requirements — functional, non-functional, constraints — and proposes a high-level approach.
It writes no code, and it does not plan. It ends by asking whether you want to continue to /create-plan, and waits.
/discovery-plan "User authentication with OAuth2" /discovery-plan @docs/feature-spec.md
Writes flow/discovery/discovery_<feature>_v<N>.md
Turn the discovery into phases you can approve
Extracts the requirements from the discovery document and lays them out as phases, each with a complexity score from 0 to 10 and its own tasks. A condensed Intent block records the goal, the constraints and what was ruled out, so the reasoning survives the plan.
It then walks you through a Change-Brief Review — the Today vs After shape of the system — before anything runs. The tests phase is always last.
/create-plan @flow/discovery/discovery_user_auth_v1.md /create-plan "Add dark mode toggle to settings"
Writes flow/plans/plan_<feature>_v<N>.md
Run the plan, phase by phase
Phases are analysed for dependencies and grouped into waves; independent phases in a wave run in parallel sub-agents. You approve each phase before its wave runs. Tasks carrying a <verify> tag are verified the moment they finish, and a failure is diagnosed and repaired in place — up to max_verify_retries attempts.
Build and tests run once, at the end. The finished plan and its discovery document are archived automatically. Database and ORM commands are never run for you: migrations are handed back for you to run yourself.
/execute-plan @flow/plans/plan_user_auth_v1.md
Writes code, commits, and an append-only record in flow/.rounds.jsonl
Review what actually landed
Reads the diff, loads your project’s own patterns, finds similar implementations already in the codebase, and files the findings as a document. Depth adapts to size: under 50 lines it looks only for security holes, logic bugs and breaking changes; 50–500 lines gets a full review; past 500 it goes multi-pass, grouped by severity, with a summary at the top.
Use /review-pr <url> instead when the changes are already on a pull request — GitHub or Azure DevOps.
/review-code /review-code --scope staged /review-code src/services/userService.ts
Writes flow/reviewed-code/review_<feature>.md
The command and the stage are spelled differently on purpose: /discovery-plan is what you type, discovery is the rung — the stage is named for what it produces.
A stage does not ask whether the previous one happened — it looks for what that stage inevitably leaves behind, scoped to the feature you are working on. Ask for /execute-plan with no readable plan for that feature and it refuses, and the refusal names the artifact it looked for.
Two of the four proofs are file presence and two read content, and the difference is reported rather than smoothed over:
Presence only — a discovery document has no grammar to check, so an empty file passes.
The content is read. A file that calls itself a plan and parses to zero phases proves nothing.
Written by the coordinator itself. Any status counts — a phase that ran and failed still ran.
Presence only, same as discovery. A review filed under a different name will be asked for again.
The ladder is ordered, not a set. If execution left a trace but no plan parses, the next stage is create-plan — the chain will not step over a missing rung because something further up happened to run.
With autopilot on, you describe the work once and the chain issues each stage from observable state. No command decides for itself whether to keep going, and every hand-off goes through the same gate — a refusal stops the chain rather than advancing past it.
/flow autopilot=true /flow add usage-based billing to the checkout # sets autopilot and starts discovery /flow autopilot=true commit=true push=true pr=true /flow -status # everything currently set
A chain pauses for exactly three things, and nothing else:
high risk assessment, before anything is publishedask on an irreversible action — when guarded_autopilot=trueOne thing to know if you name things yourself: the chain writes every document under one feature slug, and the proofs are scoped to it. A review filed under a different name — the scope rather than the feature — will not satisfy that rung, and the chain asks for the review again. A repeated review, never a skipped one.
Any command takes -help and prints its own usage without doing anything.
Free-form, one-question-at-a-time exploration for an idea too vague for discovery. Pure ideation, no project structure.
→ flow/brainstorms/brainstorm_<topic>_v<N>.md (optional)
Requirements and approach, with the open questions asked. Writes no code.
→ flow/discovery/discovery_<feature>_v<N>.md
Phases with complexity scores and tasks, an Intent block, and a Today vs After review.
→ flow/plans/plan_<feature>_v<N>.md
Runs the plan in dependency-ordered waves, verifies tagged tasks, archives the plan when done.
→ code, commits, flow/.rounds.jsonl
Reviews local uncommitted changes against your project’s patterns. Depth scales with the diff.
→ flow/reviewed-code/
Reviews a pull request on GitHub or Azure DevOps.
→ flow/reviewed-pr/
Writes and updates tests until the project reaches the coverage target you name.
→ test files
With no argument, extracts reusable patterns from the current session. With a topic, it teaches — researches, designs a curriculum, and walks you through it step by step.
→ flow/resources/ · ~/plan-flow/brain/learns/ (global) · flow/brain/learning/
Files a meeting note, an idea or an insight into the project brain by hand, cross-linked with [[wiki-links]].
→ flow/brain/
Builds an integration contract from a documentation URL or a repository, so discovery has something precise to read.
→ flow/contracts/<service>_contract.md
Reads flow/STATE.md and rebuilds full context after a compaction, a new session or a crash. Creates nothing.
→ a summary in the chat
Every runtime setting, persisted in flow/.flowconfig. Also /flow <prompt>, which turns autopilot on and starts discovery in one move.
→ flow/.flowconfig
Token usage and spend, by day, project or session.
→ a report in the chat
Everything is key=value through /flow, persisted per project in flow/.flowconfig. Settings are independent — commit=true works with autopilot off. /flow -unset <key> puts one back to its default; /flow -reset puts back all of them.
Chain the four stages instead of stopping between them.
Classify each dangerous seam of an autonomous run and pause to ask on irreversible actions.
Commit after each completed phase.
Push once every phase is done and build and tests pass.
Open a pull request after execution.
Open those PRs as drafts; /review-pr flips one to ready.
The base a workspace is cut from and a PR opens against.
The remote a thread binds its push and PR to.
Naming convention suggested for a thread’s remote branch, e.g. feature/{ticket}.
Give every thread its own workspace, so nothing runs in your tree.
Where a thread’s workspace starts when nobody names a start.
Bring the base up to date before cutting a workspace.
How long that refresh may take.
Group independent phases into waves and run each wave in parallel.
Run each phase in a fresh sub-agent with clean context. Turn off to debug inline.
Pick the model per phase from its complexity.
Repair attempts allowed per failed task verification.
Re-learn a module automatically when its code drifts.
Modules left out of learning, comma-separated.
The lint command the pipeline gates run.
Share this project’s knowledge with the team, or keep it to yourself.
All of it lives in your repository, as plain markdown. It commits, reviews and merges like code, and a teammate who pulls gets the same picture you have.
After a compaction, a new session or a crash, /resume-work reads flow/STATE.md, finds the work in flight, reads the plan or discovery behind it, and puts the context back. It creates nothing and changes nothing.
That is the point of writing each stage down as a document: the work survives the session it started in.