Plan

Direct execution through /flow-next:work <spec-id> --no-plan is the default for a ready spec. Plan is chosen only on a positive signal: you asked for a plan, separate human owners will implement, or delivery is staged across several PRs. Risk, size, and file count never trigger plan on their own. Design risk routes to plan-review, which reviews a spec with zero tasks; unresolved product or authority choices route to refine.

/flow-next:plan takes a feature request - text or an existing ready spec - and produces a structured plan: research findings, acceptance criteria with R-IDs, and tasks sized for one /flow-next:work iteration.

The output is a spec at .flow/specs/<id>.md plus task files under .flow/tasks/, ready for execution.

If direct work has already created a sole implicit owner, plan stops before changing the route or adding tasks. Decide how that owner’s scope and existing work should fit the requested breakdown first. A zero-task spec can switch directly to planning.

Chart is too late here: unshaped oversized freeform ideas are not plan input. Route those to optional /flow-next:chart first, then capture, then plan.

Readiness soft-check

When planning an existing spec in a repo where readiness is adopted (any spec marked ready, or tracker.readyState configured), plan checks the spec’s ready flag before spending research tokens on the scout fan-out. A not-ready spec gets one warn-not-block question, defaulting to proceed - planning is non-destructive and often part of getting a spec ready. With local readiness the options are proceed / mark-ready-then-proceed / abort; with tracker-authoritative readiness, mark-ready is never offered locally (the next sync would revert it) - instead: proceed / abort / move the issue on the board and re-run. Non-interactive and autonomous runs auto-proceed with one stderr line. Repos that never adopted readiness see nothing.

Research scouts in parallel

A planning pass runs its scouts at once so the spec is grounded before the first acceptance criterion is written. The set follows --depth (default short):

• repo-scout - patterns and conventions already in the codebase; always runs (at short it also covers docs that will need updating).
• spec-scout - dependencies and relationships with other specs; always runs.
• flow-gap-analyst - user flows, edge cases and missing requirements; always runs.
• practice-scout - modern best practices for the change; standard and deep.
• docs-scout - relevant framework or library docs; standard and deep.
• docs-gap-scout - documentation that will need updating; standard and deep.
• github-scout - real-world implementations across repos; standard and deep, when scouts.github is on.

Memory is not a scout: when memory is enabled, plan runs one flowctl memory search itself.

The set is launched in one batch so the synthesis step has every signal at once.

The research step shares one artifact with /flow-next:refine --scope=research: a ## Resolved via Research section on the spec. When the spec already carries that section, plan skips docs-scout, practice-scout and docs-gap-scout and says so (repo-scout, spec-scout, and flow-gap-analyst still run). When plan runs those research scouts itself, it writes the section, so the pass never runs twice.

Task sizing

Tasks are sized by observable metrics, not by time estimate:

Size	Files	Acceptance criteria	Pattern reuse
S	1-3	1-2	High
M	3-7	2-4	Mixed
L	8+	5+	Low - must split

M is the sweet spot for one /flow-next:work iteration (~100k tokens of context). L tasks must be split before planning is considered done. If a spec ends up with seven or more tasks, sequential S tasks get combined into M.

R-IDs are mandatory

Every acceptance criterion gets a stable identifier:

**R1:** Users can create a spec from conversation context.
**R2:** Each criterion is source-tagged.
**R3:** Read-back blocks before any file write.

R-IDs in ## Acceptance Criteria and ## Requirement coverage must match. Once a spec passes its first review, R-IDs are frozen - new criteria append at the end, removed criteria leave a gap.

No implementation code

The spec and tasks describe what must be true and how the work is decomposed - not the implementation itself. Signatures and architectural patterns are fine; complete function bodies are not. Implementation happens later in /flow-next:work with fresh context per task, so embedding code into the plan only invites stale bodies that the worker has to ignore or rewrite.

Optional review

Chain plan-review directly:

/flow-next:plan <request> --review=codex

--review=codex|rp|copilot|cursor|claude|host|none runs the Plan Review skill on the freshly-landed spec and task graph: one review, one fix pass on NEEDS_WORK, then one re-review whose verdict is final. Use it whenever the spec is large enough that fixing it post-implementation would mean throwing away worker output, or before handing the spec to autonomous work.

You can also invoke /flow-next:plan-review <spec-id> separately after the fact.

Plan asks no setup questions. Flags you pass win, depth defaults to short, and review uses the configured backend. With no backend configured, review is off and the handoff says so once (“no review backend set; run setup or set review.backend”).

Worked example

/flow-next:plan add per-key rate limits to the export API

Scouts dispatched (read-only): repo-scout, spec-scout...
Spec created: fn-14-rate-limits (5 acceptance criteria, R1-R5)
Tasks: .1 limiter middleware, .2 429 contract + headers (deps: .1), .3 tests + docs (deps: .2)
Each task sized to one fresh worker context. Ready for /flow-next:work fn-14-rate-limits.

Planning ends with an artifact you can review - and the spec review is the cheapest review you will ever do. Since 5.0.0 the task set is written once to a temporary file (${TMPDIR:-/tmp}/flow-plan-draft-<slug>-<suffix>.json) and the read-back is a compact summary (tasks, sizes, waves, R-ID coverage) with one ask: approve and write, open in editor, or abort. Edit cycles print only the diff.

Tips

• Edit the spec before working it: a wrong acceptance criterion costs seconds now and a review cycle later.
• Plan quality tracks input quality - a two-line request produces a guessy spec; a paragraph with constraints produces a sharp one (or run refine after).
• Tasks declare satisfies: [R-IDs], which is what makes the eventual PR coverage table possible - keep the mapping honest when you hand-edit tasks.

Dynamic usage

Recipes that compose with plan in the cookbook:

• Skip & lighten - small change, small ceremony: a small local change goes direct with no spec, and a ready spec goes straight to work with no plan.
• One-shot chains - “plan it, review the plan, then start work” in a single message.
• Prompt into a stage - “plan with max three tasks, no new dependencies” shapes the output without changing the contract.

Next step

The interactive next-steps menu leads with one Recommended next: line read from the shared routing reference the flow skill owns - plan-review versus straight to work, re-judged after every go-deeper round. Any remaining design risk recommends the review. Autonomous runs are unchanged.

For a risky spec, gate it through review before implementation:

/flow-next:plan-review <spec-id>

Otherwise hand the spec and its tasks straight to the work loop:

/flow-next:work <spec-id>