Planning Scouts

/flow-next:plan does not start writing tasks from a blank page. It first dispatches a fleet of read-only scouts — up to nine — that investigate in parallel and report structured findings back. The plan is composed from what they find, so it is grounded in your actual codebase and the current state of the ecosystem rather than the model’s assumptions.

Every scout here disallows Edit, Write, and Task: it can read, search, and fetch, but it cannot change your code or spawn more agents.

The Tier column is platform-neutral — Reasoning and Fast map to a concrete model per runtime (Opus / Sonnet on Claude, gpt-5.5 / gpt-5.4-mini on Codex). See the model-tier note on the overview for the full mapping.

How they fan out

The research scouts run first and in parallel. flow-gap-analyst runs in a second wave because it reasons over the others’ findings.

flowchart TB
  Plan["/flow-next:plan"] --> Wave1
  subgraph Wave1["Wave 1 — research (parallel)"]
    Repo["repo-scout"]
    Ctx["context-scout"]
    Spec["spec-scout"]
    Docs["docs-scout"]
    Practice["practice-scout"]
    GH["github-scout"]
    Mem["memory-scout"]
  end
  Wave1 --> Gap["flow-gap-analyst"]
  Gap --> DocsGap["docs-gap-scout"]
  DocsGap --> Tasks["Composed task plan"]

The codebase scouts

Scout	Tier	Job
`repo-scout`	Reasoning	Scans the repo for existing patterns, conventions, and related code paths so new work matches what is already there. Reads the optional clawpatch feature index when present, and degrades to grep/glob when it is not.
`context-scout`	Reasoning	Token-efficient deep exploration via RepoPrompt codemaps and slices — comprehensive context without bloating the main conversation. The richer alternative to `repo-scout` when RepoPrompt is available.
`spec-scout`	Reasoning	Reads open specs to surface dependencies and relationships, so a new plan slots into the existing graph instead of colliding with it.
`memory-scout`	Fast	Searches `.flow/memory/` for prior learnings — both bug fixes and curated knowledge — relevant to the task, via the `flowctl memory` CLI. Runs when `memory.enabled` is set.

The ecosystem scouts

Scout	Tier	Job
`docs-scout`	Reasoning	Finds the exact framework and library documentation pages the implementation will need, version-aware — because docs change between versions.
`practice-scout`	Reasoning	Gathers current community best practices, anti-patterns, and pitfalls for the change (web search plus real-world GitHub examples).
`github-scout`	Reasoning	Searches public and authenticated-private GitHub for code patterns, reference implementations, and known issues. Runs when `scouts.github` is enabled.

The synthesis scouts

Scout	Tier	Job
`flow-gap-analyst`	Reasoning	Consumes the research findings and maps user flows, states, and edge cases to surface missing requirements and open questions before coding starts.
`docs-gap-scout`	Reasoning	Identifies which docs will need updating once the change lands, so documentation is planned in rather than bolted on. Shared with `/flow-next:prime`.

Next step

Once the scouts report, /flow-next:plan composes the task graph. From there:

/flow-next:work <spec-id>