# Plan Source: https://flow-next.dev/skills/plan/ Research scouts in parallel; structured plan with R-ID coverage; tasks sized for one work-loop iteration. Direct execution through `/flow-next:work --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/.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`](https://flow-next.dev/skills/chart/) first, then capture, then plan. ## Readiness soft-check When planning an existing spec in a repo where [readiness](https://flow-next.dev/guides/writing-specs/#the-ready-flag) 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`](https://flow-next.dev/skills/refine/): 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: ```md **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: ```bash /flow-next:plan --review=codex ``` `--review=codex|rp|copilot|cursor|claude|host|none` runs the [Plan Review](https://flow-next.dev/skills/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 ` 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 ```plaintext /flow-next:plan add per-key rate limits to the export API ``` ```text 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--.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. * 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](https://flow-next.dev/skills/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](https://flow-next.dev/guides/cookbook/): * [Skip & lighten](https://flow-next.dev/guides/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](https://flow-next.dev/guides/cookbook/#one-shot-chains) - “plan it, review the plan, then start work” in a single message. * [Prompt into a stage](https://flow-next.dev/guides/cookbook/#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](https://flow-next.dev/skills/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: ```bash /flow-next:plan-review ``` Otherwise hand the spec and its tasks straight to the work loop: ```bash /flow-next:work ```