# What /flow is
Source: https://dorkos.ai/docs/guides/flow/what-flow-is
One command path from a raw idea to shipped code, run by hand or handed off to run on its own.
# What /flow is [#what-flow-is]
You used to run nine different commands (`/pm`, `/ideate`, `/spec:*`, `/linear:*`, and more) to move one idea from a raw thought to shipped code. `/flow` replaces all of them with a single path: one set of commands that takes a piece of work from "I had a thought" to "it's merged."
Throughout this guide, "you" and "the operator" mean the same person: whoever is driving the loop. That's you.
`/flow` also doesn't care which project-tracking tool you use (we call this **PM-agnostic**, short for "project management-agnostic"). It talks to your tracker through one narrow connector, so the same commands work no matter which tracker sits behind them. Today that tracker is Linear.
`/flow` is the single place that knows "where work is." Your tracker, your specs, and your labels
all reflect the stage `/flow` has work in, not the other way around. Move a piece of work forward
by advancing its stage, and everything else (labels, tracker status) follows automatically.
## A quick glossary [#a-quick-glossary]
The stages below use a few words worth pinning down:
* **Idea**: a raw thought, captured before anyone has decided if it's worth doing.
* **Work item**: anything `/flow` is tracking. An idea, a task, and a full spec are all work items at different stages of readiness.
* **Task**: a small, well-understood piece of work that can go straight to building, no design phase needed.
## The core promise [#the-core-promise]
`/flow` runs on its own by default, but it knows when to stop and ask you. Four things to know:
* **It keeps itself fed.** Finishing one stage produces exactly what the next stage needs, so there's always more ready work in the queue. If the queue does run dry while unshaped work is waiting, `/flow` says so out loud (`0 ready, 3 shapeable: run a triage pass?`) instead of quietly stalling. The engine doesn't just give up: it tells you.
* **It unblocks itself.** When `/flow` genuinely needs your input, it parks the question somewhere durable, pings you, and picks back up the moment you reply. You never have to babysit it, and it never asks the same question twice.
* **It doesn't wait for permission to start.** `/flow` can run the whole path on its own. No stage requires a human to kick it off.
* **It asks because it's unsure, not because of what stage it's in.** A human gets pulled in when the engine is genuinely uncertain (plus a small, fixed set of safety checks, more on those below), never just because the work reached a particular stage. That's why early brainstorming asks you lots of questions and late-stage building rarely does: it's one rule, not nine different policies per stage.
You're always in charge. Pause the loop, turn off any part of it, take back any item, or step into a session yourself, at any point.
## One path, start to finish [#one-path-start-to-finish]
Every piece of work travels the same nine stages. Simple work skips the middle ones (see below); complex work goes through all of them.
| Stage | What happens | Command |
| ------------- | -------------------------------------------------------------------------------------- | -------------------------- |
| **CAPTURE** | A raw thought gets written down as an idea. Nothing is judged or classified yet. | `/flow:capture` |
| **TRIAGE** | The idea gets sorted: is it a quick task or does it need real design work? | `/flow:triage` |
| **IDEATE** | A complex idea gets shaped into a written plan. | `/flow:ideate` |
| **SPECIFY** | The plan becomes a locked-down spec, ready to build from. | `/flow:specify` |
| **DECOMPOSE** | The spec gets broken into a checklist of tasks. | `/flow:decompose` |
| **EXECUTE** | The tasks get built, in an isolated copy of your project so nothing else is disturbed. | `/flow:execute` |
| **VERIFY** | The work gets tested, proof gets gathered, and a pull request opens. | `/flow:verify` |
| **REVIEW** | You look at the pull request and decide: ship it or send it back. | *(you review, no command)* |
| **DONE** | The item closes, follow-up work gets filed, and the temporary workspace is cleaned up. | `/flow:done` |
Small, well-understood changes skip straight from TRIAGE to EXECUTE as a task: no plan needed. Bigger or riskier work goes through IDEATE, SPECIFY, and DECOMPOSE first to get shaped properly.
Typing `/flow` with nothing after it acts as a router: tell it a stage, a piece of work, a project, or the word `auto`, and it sends you to the right place. Type nothing at all and it offers a menu: capture a new thought, work on a project, keep clearing the queue, or triage the backlog.
**Capture, then triage.** Your thought becomes an idea. `/flow:triage` decides whether to accept
it, then whether it's a quick task or something bigger. Accepted work gets marked ready, which
is what keeps the queue moving.
**Shape it (bigger work only).** `/flow:ideate`, then `/flow:specify`, then `/flow:decompose`
turn a rough idea into a locked spec and a checklist of tasks.
**Build and check it.** `/flow:execute` writes the code in its own isolated workspace.
`/flow:verify` tests it, collects proof it works, and opens a pull request.
**You review.** `/flow` stops here and hands you the pull request plus its evidence. This step
always requires you, no exceptions.
**Close it out.** Once you approve, `/flow:done` closes the item, files any follow-up work, and
cleans up. Then it looks for the next thing to do.
## Running it by hand or letting it run itself [#running-it-by-hand-or-letting-it-run-itself]
The stages above are the same either way. What changes is who presses the button for each step.
| | Running it by hand | Letting it run itself |
| ----------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **How you use it** | One stage at a time: `/flow:specify`, then `/flow:execute`, and so on. | Point it at the queue with `/flow auto`. It drains the ready work and stops at each gate. |
| **When it has a question** | Asked right in your current session. | Parked somewhere durable and sent to you; picks back up when you reply. |
| **Do you need the server running?** | No, it runs entirely from your terminal. | Draining the queue from your terminal doesn't need the server either. An always-on unattended runner does need it. |
| **Best for** | Learning how `/flow` works, or careful one-off changes. | Clearing a backlog of ready work while you do something else. |
### Which one should you use? [#which-one-should-you-use]
**Run it by hand when:**
* You're new to `/flow` and want to watch each stage happen before you trust it. Think of it as training wheels, not a downgrade.
* The work is sensitive, exploratory, or a one-off where you want to approve every step.
* You want any questions answered in the session you're already in.
**Hand it to autopilot when:**
* You've got a backlog of ready, well-understood work you want cleared in priority order.
* You'd rather get pinged when a decision is needed than sit and advance every stage yourself.
* You're comfortable reviewing at the final gate instead of at every step along the way.
Running it by hand and letting it run itself use the exact same code underneath. There's no
separate "autopilot version" to learn or worry about; it's the same nine stages either way.
## What always needs you [#what-always-needs-you]
Two things pull a human in, and neither can be turned off:
* **A safety floor.** No matter how confident `/flow` is, it stops before anything irreversible or destructive, anything that faces the outside world, anything touching secrets or spending money, or anything that changes the scope of the work. You can't disable this.
* **The review gate.** After VERIFY, every piece of work lands as a pull request with evidence, and waits for you. Nothing merges on its own.
There's also an optional gate after DECOMPOSE (approving the plan before any code gets written), but it's off by default: `/flow` goes straight from planning into building, and shows you its planning assumptions at the review gate instead.
Right now `/flow` parks at the review gate but can't yet tell when you've approved the pull
request. Merge it yourself, then run `/flow:done ` to close the item and clean up. Detecting
your approval and merging automatically is planned for a future release.
## What works today [#what-works-today]
`/flow` today is tested and reliable for the parts described above, run either by hand or as a one-time queue drain from your terminal. An always-on version that runs continuously and unattended, with no one starting each drain, is still being built. A few specific things aren't here yet:
* Running continuously, unattended, with nobody starting each pass.
* Handling more than one piece of work safely at the same time (v1 works through the queue one item at a time).
* Detecting your pull-request approval and merging automatically (today you merge, then run `/flow:done`).
* Receiving tracker updates the instant they happen, instead of checking periodically.
* A dedicated Linear identity built specifically for agents.
Being upfront about that line between what's built and what isn't is part of what makes `/flow` trustworthy.
## Next steps [#next-steps]
Run the path one stage at a time from the terminal, with every question answered right in front
of you.
Hand the engine a queue and let it feed, unblock, and resume itself.
Every setting that shapes the loop: gates, safety checks, ranking, and notifications.
A closer look under the hood, for the curious.