Plan

/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.

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 Ralph runs auto-proceed with one stderr line. Repos that never adopted readiness see nothing.

Research scouts in parallel

A planning pass runs several scouts at once so the spec is grounded before the first acceptance criterion is written:

• repo-scout — patterns and conventions already in the codebase.
• practice-scout — modern best practices for the change.
• docs-scout — relevant framework or library docs.
• memory-scout — prior decisions and pitfalls in .flow/memory/.
• spec-scout — dependencies and relationships with other specs.
• docs-gap-scout — documentation that will need updating.
• github-scout — optional; finds real-world implementations across repos.

All launched in one batch so the synthesis step has every signal at once.

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|none runs the Plan Review skill on the freshly-landed spec and task graph, then loops fix → review until SHIP. 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.

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.

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 interview 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: plan + work with no interview and no separate plan review.
• 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

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>