Running Lean

Flow-Next runs fully as spec -> plan -> work. Everything else is a layer you can leave off and reach for when a piece of work warrants it.

This page names the two operating profiles those layers serve, prices each layer in structural terms, and gives the manual invocation for people who want the capability without the standing cost.

Adjacent, not the same

Menu, Not a Rail argues that the stages are skippable and reorderable - you do not have to walk capture, interview, plan, work in order. This page is about which layers you switch on at all, and what each one costs you to keep on. Read that one for the route; read this one for the load.

Two profiles

	Human-driven	Autonomous
Who is watching	You are, at the keyboard	Nobody, until morning
What the layers do	Give you a capability on demand	Stand in for the judgment you are not there to apply
Default posture	Run lean; add a layer when the work asks for it	Run gated; the gates are what make the run trustworthy
Typical shape	spec -> plan -> work, plus whatever the change needs	Pilot + Land under a host loop

Neither is the real mode. They are two answers to one question: who applies judgment at each handover?

When you are present, you are the reviewer, the tracker, and the QA. A review backend, a bidirectional tracker sync, and a live QA stage are then buying you convenience, not safety, and each one is worth switching on only where that convenience beats its cost. When nobody is present, those same layers stop being convenience: they are the only thing between an unattended loop and an unreviewed merge, and running without them is the actual risk.

The failure mode this page exists to prevent is paying autonomous-profile costs while sitting at the keyboard - a full tracker round-trip on every lifecycle event for a spec only you will ever read.

Profiles are per run, not per team and not per repo. The same repo can drain a backlog autonomously overnight and take a lean human-driven change the next morning.

The layers

Defaults below are read from the published config schema. Check your own with flowctl config get <key>.

Layer	Config key	Default	Lean invocation
Tracker sync	tracker.enabled	off	/flow-next:tracker-sync
Live QA stage	pipeline.qa	off	/flow-next:qa
Cross-model review backend	review.backend	unset	/flow-next:impl-review
HTML render lenses	artifacts.html.enabled	off	ask for a render in conversation
Plan-sync	planSync.enabled	on	/flow-next:sync
Memory	memory.enabled	on	/flow-next:audit
Pre-capture discovery	none	manual	/flow-next:chart, /flow-next:prospect
Autonomous loops	none	manual	/flow-next:pilot, /flow-next:land
Ralph	none	off, deprecated	see below
Implementation offload	none	no layer to enable	see below

Tracker sync

tracker.enabled - off by default. Full reference: Tracker Sync.

• Automates away: keeping a Linear, GitHub, GitLab, or Jira issue in step with the spec - body, status, and comments - so people who live in the tracker see current state without anyone retyping it.
• Costs: a bidirectional round-trip per lifecycle event you enable it for, a conflict policy you now have to hold an opinion about, and a second place where state can be wrong. Every tracker.perEvent.* key you switch on adds another synchronization point to every spec’s life.
• Earns its keep when: other people - PMs, stakeholders, teammates not in the repo - need to read or edit status where they already work, or when a tracker key is your distributed id allocator for parallel agents.
• Lean invocation: run /flow-next:tracker-sync on demand. Push a spec to the tracker at the moment you need someone else to see it, and leave the bridge off in between. Spec-only is a first-class mode, not a degraded one: the spec is the source of truth either way.

Live QA stage

pipeline.qa - off by default as a pilot stage; the skill is always available. Full reference: QA.

• Automates away: driving the running app like a real user against the spec’s acceptance criteria, and filing evidence-backed findings before a human opens the PR.
• Costs: a live-app drive pass per spec, a running deploy for the loop to point at, and a driver to configure and keep working. As a pilot stage it sits between all-tasks-done and make-pr, so every spec pays it.
• Earns its keep when: nobody will exercise the app before merge - the autonomous profile’s usual case - or when the change is UI or runtime shaped and tests cannot see the failure mode.
• Lean invocation: /flow-next:qa <spec> when a change deserves it. If the app is already up on your machine because you just built the feature, you are the live QA pass; the skill is for when you want findings written down as evidence instead of noticed and forgotten.

Cross-model review backend

review.backend - unset by default; reviews run in-host. Full reference: Orchestration.

• Automates away: getting a verdict from a model family that did not write the diff, so the reviewer’s blind spots are uncorrelated with the writer’s.
• Costs: an out-of-host review pass per review round, a second CLI installed and authenticated, and a fix-and-re-review loop that can run up to review.maxIterations rounds before escalating.
• Earns its keep when: the diff was written by an agent and will be merged without a human reading it line by line. That is the autonomous profile by definition; in the human-driven profile you are the cross-model reviewer.
• Lean invocation: /flow-next:impl-review or /flow-next:plan-review on the changes that warrant it, or a per-task review: pin, leaving the standing backend unset.

HTML render lenses

artifacts.html.enabled - off by default. Full reference: Visual Aids.

• Automates away: rendering a spec or a PR as a self-contained HTML page for people who will not read markdown in a terminal.
• Costs: an extra render step on capture, plan, and make-pr, and an artifact tree to decide whether to commit or ignore.
• Earns its keep when: you are handing a spec to a business reviewer, or a PR to someone reviewing decisions rather than diffs.
• Lean invocation: ask for the render in conversation when you need one. Markdown stays the source of truth in every case, so a lens is always regenerable and never has to exist in advance.

Plan-sync

planSync.enabled - on by default. Full reference: Sync.

• Automates away: updating downstream task specs after an implementation drifts from what the plan assumed, so later tasks re-anchor on what is true rather than what was planned.
• Costs: a reconciliation pass after each completed task.
• Earns its keep when: the spec has several dependent tasks - the usual case, which is why it ships on. On a single-task spec there is nothing downstream to reconcile and the pass is a no-op worth skipping.
• Lean invocation: flowctl config set planSync.enabled false, then /flow-next:sync when a task genuinely invalidates a downstream assumption.

Memory and the audit sweep

memory.enabled - on by default. Full reference: Self-Improving.

• Automates away: carrying learnings across context compaction and across sessions, so a bug class you already diagnosed does not get re-diagnosed from scratch.
• Costs: the tree itself is nearly free - entries are written as a side effect of work already happening and read by search, never loaded wholesale. The layer with a price is the audit sweep: a pass over every entry, judged against the current codebase.
• Earns its keep when: memory is on, always. The sweep earns its keep once entries have had time to go stale - after a refactor that invalidates prior art, or on a periodic cadence.
• Lean invocation: leave memory on; run /flow-next:audit deliberately rather than on a schedule.

Pre-capture discovery

No config key - these are skills you invoke or do not.

• Automates away: finding out what to build - a ranked backlog (prospect), a decision map for one oversized unclear idea (chart), or structured requirement extraction on an existing spec (interview).
• Costs: a discovery loop before any code exists. Chart in particular is an adaptive multi-invocation loop, one decision per tick.
• Earns its keep when: you cannot yet state the outcome in a sentence. When you can, capture directly; discovery on an idea you already understand is ceremony.
• Lean invocation: all three are already manual and none is ever a required stage. /flow-next:guide will tell you which, if any, your situation needs.

Autonomous loops

No config key to enable. Full reference: Going Autonomous.

• Automates away: the repetition - pilot advances one ready spec by one stage per tick, land babysits the resulting PRs to merged.
• Costs: this is the autonomous profile itself, so it inherits the profile’s gates. The layers above stop being optional in the way they are optional for you at a keyboard, because they are what replace you.
• Earns its keep when: there is a queue of blessed, fully specified work and nobody who wants to sit through it.
• Lean invocation: /flow-next:work is the human-driven equivalent and needs no loop primitive at all.

Ralph (deprecated)

Deprecated

A shell script that calls the orchestration primitives - /flow-next:pilot to build and /flow-next:land to ship, driven by a host loop or cron - does what the hardened harness does, without the scripts/ralph/ scaffold, the guard-hook registration, and the second receipt plumbing. Ralph predates those primitives.

Nothing is removed and nothing breaks. Existing installs keep working and the Ralph pages stay maintained as their reference. New adopters should start at pilot + land.

Implementation offload

No config key, and nothing to switch on. Full reference: Orchestration.

• Automates away: nothing by itself. Naming an implementer tier in your CLAUDE.md / AGENTS.md routing block sends the token-heavy code-writing to a second CLI agent over a headless bridge, so a long spec never eats the host’s context.
• Costs: a second CLI installed and authenticated, and prose you have to keep true. The bridged draft still gets every gate it would have got in-session, so the offload buys context and wall clock, never a shortcut.
• Earns its keep when: the specs are clear enough that a cheaper tier gets them right first time. A vague brief burns the saving on rework.
• Lean invocation: leave the tier unset. The session model implements, which is the shipped default - and you can still say “send this one out” in the moment without writing anything down.

The packaged work.delegate* subsystem was removed in 4.0.0

Leftover keys in .flow/config.json are inert - flowctl names them once in a non-blocking advisory and otherwise ignores them. Run /flow-next:setup, accept the routing-block scaffold, and use the bridge recipes in flowctl usage.

A lean run still leaves a record

Running lean does not mean running unaccountably. Every orchestrated stage records its outcome as ran, skipped(reason), or failed(reason) in the receipts it already writes - so a stage you deliberately left off is an explicit entry with your reason attached, not a silent absence:

flowctl usage --stages <spec-id>          # plain
flowctl usage --stages <spec-id> --json   # machine-readable

That is what makes a deliberate layer set auditable later. The difference between “QA was off because this is a CLI change with no live surface” and “QA never ran and nobody knows why” is visible in the receipt, not reconstructed from memory.

Where to go next

• Menu, Not a Rail - the same doctrine applied to stages: skip, reorder, prompt into, chain.
• Orchestration & Model Routing - the same doctrine applied to models: which model does what, and how to change it.
• Guide - the router that recommends the smallest sufficient workflow for one specific situation.
• First 30 Minutes - the getting-started walkthrough, if you have not run the base loop yet.