Driving it manually
Run the /flow workflow by hand, one stage at a time, right from your terminal. No server needed.
Driving it manually
/flow is a workflow that carries a piece of work from a raw idea to a merged change. You can run it two ways: by hand, one command at a time, or on a schedule so it runs unattended. This guide covers driving it by hand. You type a command, answer any questions it asks, and decide when to move to the next step. Nothing runs until you say so.
Haven't installed /flow yet? It comes from the DorkOS Marketplace and needs
a one-time setup pass, /flow:init, before any of the commands below will work.
Manual mode needs nothing but your terminal: no server, no scheduler, nothing running in the background. Every command in this guide, plus the terminal drain /flow auto, works with DorkOS's server off. The only piece that needs a server is the always-on autonomous runner, covered in Turning on autonomy.
Here's the whole loop in three commands:
/flow:capture add keyboard shortcuts to the session list
/flow:triage DOR-201
/flow DOR-201 # repeat until it reaches REVIEW, then merge and run /flow:doneThat's the entire idea. The rest of this guide walks through each stage, then covers status, pause, and resume.
The stage spine
Work moves along one path from idea to done:
CAPTURE → TRIAGE → IDEATE → SPECIFY → DECOMPOSE → EXECUTE → VERIFY → ⟦REVIEW⟧ → DONEREVIEW is a human gate, not a command. The engine stops there and waits. You review the pull request (PR, the proposed code change waiting for your approval), and once you approve it, the work moves to DONE. Every other stage has a matching command.
The orchestrator: /flow
/flow with no stage name is the router. Tell it what you mean and it dispatches to the right command:
- A stage name (
/flow specify) routes to that stage's command. - A work item (
/flow DOR-157) advances that item one stage from wherever it sits. - A project (by name or spec slug) routes based on the project's state.
autodrains the whole ready queue from your terminal, carrying each item to its review gate.
Bare /flow, with nothing after it, does not guess. It asks you to pick from five options:
| Intent | What it does |
|---|---|
| Capture | Save a new thought as a low-commitment item. |
| Work on a project | Pick from your active projects and advance it. |
| Continue the queue | Claim the next item in line, carry it to its gate, then stop. One step of auto. |
| Triage the backlog | Run a triage pass over everything waiting to be classified. |
| Check loop status | See what's in flight and what's waiting on you (same as /flow:status). |
A specific item, a stage name, or auto are all reachable as free text too, alongside those five choices.
"Continue the queue" is exactly one step of auto: it picks the top item and carries it to
its review gate, then stops. It does not start a background loop and does not touch anything else.
It's the safest way to make one unit of progress without committing to draining everything.
How it works (for the curious)
The rest of this guide is everything you need to drive /flow by hand. This section explains why manual and automatic driving never drift apart. Skip it if you just want to run commands.
Each /flow:<stage> command is a thin trigger over a skill, a self-contained unit of instructions that does the actual work. The scheduled, unattended version of /flow (covered in Turning on autonomy) reaches that exact same skill through a different trigger: a transition in your tracker (the issue tracker /flow talks to, for example Linear) instead of you typing a command. There is no separate "manual version" of a stage to fall out of sync with the automatic one.
Whether you type /flow:specify or a scheduled tick advances an item into SPECIFY, the same skill
runs the same way. Drive a stage by hand today, hand it to the schedule tomorrow, and the behavior
does not change.
Command reference
| Command | Stage | What it does |
|---|---|---|
/flow | (router) | Route to a stage, a work item, a project, or auto. Bare call offers five options. |
/flow:capture | CAPTURE | Quick intake of a raw thought as an idea. No evaluation yet. |
/flow:triage | TRIAGE | Classify freeform input, or evaluate a captured item (accept, reject, needs research, needs refinement) and decide whether it's simple or complex. |
/flow:ideate | IDEATE | Shape a complex brief into a structured plan. |
/flow:specify | SPECIFY | Turn that plan into a frozen specification, plus draft ADRs (Architecture Decision Records, short docs that capture why a technical choice was made). |
/flow:decompose | DECOMPOSE | Break the spec into tasks, mirrored into your tracker as a checklist. |
/flow:execute | EXECUTE | Implement the tasks in an isolated worktree (a separate copy of your code, so nothing collides with other work in progress). |
/flow:verify | VERIFY | Test what changed, gather proof it works, open the PR, and hand off to review. |
/flow:done | DONE | Close the work, create any follow-ups, and remove the worktree. |
/flow:status | (observe) | Show every item in flight, every question waiting on you, and why each decision was made. |
/flow:pause | (control) | Stop every running mode at once. |
/flow:resume | (control) | Lift the pause and let work flow again. |
There is no /flow:review. REVIEW is the human gate: the engine stops and waits for you.
A worked walkthrough
This is one item moving from a raw thought to a merged change, driven entirely by hand. Each command advances one stage and stops. Questions arrive as you go, and you decide when to run the next command.
Capture the thought
/flow:capture add keyboard shortcuts to the session listThe thought lands in your tracker as an idea (small win, we know, the kind that never gets its own sprint but makes everyone's day a little better). No evaluation, no classification: capture is deliberately cheap so a thought survives instead of evaporating. You get back the item's identifier, for example DOR-201 - Add keyboard shortcuts to the session list.
Triage it
/flow:triage DOR-201Triage decides whether to accept, reject, or send the item back for more research or refinement, then makes the simple-versus-complex call. Simple work heads straight toward EXECUTE; complex work heads to IDEATE first. Either way, an accepted item is now ready for the next stage.
Ideate (complex work only)
/flow:ideate DOR-201For anything non-trivial, IDEATE shapes the brief into a structured plan. This stage asks questions freely: shaping is where the most is still unknown, so the engine pulls you in rather than guessing.
Specify
/flow:specify DOR-201SPECIFY turns the plan into a frozen specification and drafts the ADRs behind it. From here, the plan is settled and ready to be broken into tasks.
Decompose
/flow:decompose DOR-201DECOMPOSE breaks the spec into tasks, mirrored into your tracker as a checklist. A plan-approval pause can sit here, but it's off by default, so the work flows straight to EXECUTE.
Execute
/flow:execute DOR-201EXECUTE writes the code, in dependency-ordered batches, inside its own isolated worktree. This is where work isolation starts: everything before this stayed in your main checkout and only touched planning documents and the tracker. Code changes get their own checkout so nothing collides with other agents working at the same time.
Verify
/flow:verify DOR-201VERIFY runs the part of the app that changed, gathers proof it works, opens the pull request, and hands off to you for review.
Review (the human gate)
The engine stops here. There's no command: you review the pull request yourself, the one gate no robot gets to skip yet.
In this version, /flow doesn't detect your approval on its own. Once you approve the pull
request, you merge it yourself, then run the next command below.
You don't have to run every command in one sitting. The filesystem and tracker hold the true state, so you can stop after any stage, come back later, and pick up exactly where you left off.
Observing and controlling: status, pause, resume
Three commands sit outside the spine. They let you see what's happening and take control.
/flow:status
/flow:statusShows one screen with everything you'd otherwise have to dig for: every claimed or in-progress item (with its worktree, branch, and session), every question waiting on your reply, and the reasoning behind each automatic decision. Reach for it whenever you want to know where things stand.
A screenshot of real /flow:status output belongs here to show what this looks like in practice.
/flow:pause and /flow:resume
/flow:pause
# ... work on something else, or step in by hand ...
/flow:resume/flow:pause stops every mode from one place, manual and automatic alike. It exists for exactly one reason: handing work to a schedule should never mean losing the wheel. /flow:resume lifts the pause. To turn off or reprioritize one part of the automatic loop instead of stopping everything, edit the loops setting in config rather than pausing (see The dials).
Which command should I use?
Advance one stage, then stop
Use /flow:<stage> (or /flow <item>). One step, questions answered as you go, full control between steps. The default for hands-on work.
Not sure where work stands
Use bare /flow for the five-option menu, or /flow:status to see everything in flight and everything waiting on you.
Make one safe unit of progress
Pick Continue the queue from bare /flow. It claims the next item, carries it to its gate, and stops. No draining, no loop.
Drain the whole ready queue by hand
Use /flow auto. It works through the queue one item at a time from your terminal, no server needed, carrying each to its review gate.
Manual versus autonomous
Manual driving and the automatic, scheduled version are not different engines. They run the same underlying instructions, reached by different triggers, with a different amount of your hands on the wheel:
| Manual (this guide) | Autonomous (scheduled) | |
|---|---|---|
| Trigger | You type a command | A scheduled check claims an item |
| Scope per run | One stage, then stop | One item, carried to its gate |
| Questions | Arrive as you go | Posted as a comment, resumed on your reply |
| Server | Not required | Required (hosts the watcher and scheduler) |
| What runs | The stage skills | The same stage skills |
The terminal drain, /flow auto, sits between the two: automatic in spirit, since it carries items to their gates without asking you at every step, but server-free, since you're the one who started it and it runs in your terminal. A continuously running, unattended version of this is planned for a future release but isn't built yet.
When /flow auto empties the ready queue but other work is sitting behind it waiting to be
shaped, it doesn't stop silently. It tells you: "0 ready, N shapeable: run a triage pass?" so
you're never left wondering why nothing happened.
Next steps
What /flow is
Why one workflow spans everything from capture to done.
Turning on autonomy
Let the schedule claim and carry work unattended. Needs a running server.
The dials
Every setting: gates, work-in-progress limits, and the per-loop config.
How it works
The deeper mechanics, for readers who want to see under the hood.
What /flow is
One command path from a raw idea to shipped code, run by hand or handed off to run on its own.
Turning on the automatic loop
Three ways to let /flow carry work to your review gate on its own, from an attended terminal drain to a scheduled background loop. What works today, and what is still coming.