Flow

Flow helps you turn a goal into a small approved plan, work through that plan step by step, and keep the whole session saved as you go.

It is built for repos where you want a clear workflow:

• define the goal
• review the proposed plan
• approve the work
• execute one feature at a time
• keep progress, blockers, and reviews visible

If you are just using Flow, you only need five commands: /flow-plan, /flow-run, /flow-auto, /flow-status, and /flow-reset.

When To Use It

Use Flow when you want:

• a clear plan before execution starts
• visible approval before work begins
• one active feature at a time instead of a blurry todo list
• saved session notes, docs, and review history
• an optional autonomous mode that still follows the same workflow

The Workflow

Flow is easiest to understand as a simple loop:

1. Run /flow-plan <goal>. Flow creates a draft plan for the work.
2. Review the draft. You look at the proposed features and decide whether to approve or reshape them.
3. Approve the plan. Once approved, the plan becomes the session you will execute.
4. Run /flow-run. Flow works through the approved features one at a time.
5. Use /flow-status whenever you want to see progress or the next recommended move.

The normal path is plan -> review -> approve -> run.

The 5 Commands

Command	Use it when you want to...
/flow-plan	create a plan or reshape the current plan
/flow-run	work through the approved plan one feature at a time
/flow-auto	let Flow drive planning and execution more autonomously
/flow-status	see where the current session stands and what to do next
/flow-reset	reopen one feature or archive the current session

Manual And Auto Modes

• /flow-plan + /flow-run is the normal manual path.
• /flow-auto follows the same overall workflow, but drives more of it for you.
• /flow-auto is not a separate system with different rules. It uses the same planning and execution model and stops when human input is the safer choice.
• To start a new autonomous run, give /flow-auto a goal: /flow-auto <goal>.
• Use bare /flow-auto only to resume an already-active autonomous session when one exists.
• If no autonomous session is resumable, bare /flow-auto tells you to rerun it with a goal.
• In interactive terminal runs, /flow-auto can pause after planning, show the draft plan inline, and let you either approve the full plan or choose a subset of features without leaving the command. Non-interactive runs keep the automatic plan-approval path.
• If you want /flow-auto to research and then implement in one run, make the goal execution-oriented in the same prompt by saying fix, implement, refactor, address, or similar. Review-only goals intentionally stop at findings.

Starting Auto Mode

Use /flow-auto <goal> when you want Flow to take a concrete objective and drive planning plus execution automatically.

Examples:

/flow-auto audit the chat architecture and propose refactors
/flow-auto implement the highest-priority AI runtime facade refactor
/flow-auto review the repo and fix the top two issues

Resume examples:

/flow-auto
/flow-auto resume

Install

From GitHub

droid plugin marketplace add https://github.com/ddv1982/flow-droid
droid plugin install flow@flow-droid

From a local checkout

droid plugin marketplace add /path/to/flow-droid
droid plugin install flow@flow-droid

Update

droid plugin update flow@flow-droid

Workflow

/flow-plan <goal>
/flow-plan   # review the draft features and approve the plan
/flow-run
/flow-auto <goal>
/flow-status

• /flow-plan starts a session or reshapes the current one.
• /flow-plan can optionally do bounded research before proposing the plan.
• After planning, you review the draft and approve it before execution starts.
• /flow-run works through the approved plan one feature at a time.
• /flow-auto <goal> starts a new autonomous run for that goal.
• Bare /flow-auto is for resuming active autonomy, not for starting a brand-new goal.
• /flow-auto uses the same planning and execution flow, but drives more of it for you automatically.
• /flow-status shows the current state and the next recommended move.
• /flow-reset lets you reopen a feature or archive the current session.

What To Expect

• Flow saves the session as it goes.
• Flow writes readable markdown summaries and review files for the session.
• Flow does not treat markdown as the source of truth. The saved session state is canonical.
• Flow is strict about feature completion: it does not complete a feature unless validation and required review gates pass.

What Gets Saved

Flow writes both machine-readable state and human-readable docs:

• the active session state
• a session overview
• per-feature docs
• decision notes
• review files

That means you can stop and resume without losing the thread of the work.

User Notes

• If /flow-plan is showing a draft review, the next step is choosing one of the offered review actions.
• Typed replies like approve and approve <ids> still work as fallback shortcuts.
• Feature trimming and research skipping exist, but they are advanced choices.

Droids

Flow uses two droids behind the scenes:

• flow-planner proposes the plan
• flow-worker completes one approved feature at a time

For Maintainers

The README is intentionally user-focused.

If you are maintaining Flow, use these docs instead:

• ARCHITECTURE.md
• CHANGELOG.md