Planning Scouts

/flow-next:plan does not start writing tasks from a blank page. It first dispatches read-only scouts that investigate in parallel and report structured findings back. The set follows the plan’s depth: SHORT (the default) runs three, STANDARD and DEEP add up to four more. 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. Four of them (docs-scout, practice-scout, docs-gap-scout, memory-scout) are also the read-first pass /flow-next:refine --scope=research runs; plan and refine share the ## Resolved via Research section they write, so the pass never runs twice.

The Tier column is platform-neutral. Every scout here is Reasoning, which maps to a concrete model per runtime (Sonnet on Claude; the Codex mirror’s INTELLIGENT model). See the model-tier note on the overview for the full mapping.

How they fan out

Plan launches the set for its depth in one parallel dispatch. flow-gap-analyst reasons over the repo-grounded findings, so on a host that does not block on dispatch it starts as soon as those return; every scout is joined before the plan is written. Memory is not a scout here: plan runs one flowctl memory search --rerank itself.

flowchart TB
  Plan["/flow-next:plan"] --> Mem["memory search (one call)"]
  Plan --> Short
  subgraph Short["Every depth"]
    Repo["repo-scout"]
    Spec["spec-scout"]
  end
  Plan --> Std
  subgraph Std["STANDARD and DEEP"]
    Docs["docs-scout"]
    Practice["practice-scout"]
    DocsGap["docs-gap-scout"]
    GH["github-scout (scouts.github)"]
  end
  Short --> Gap["flow-gap-analyst"]
  Std --> Tasks["Composed task plan"]
  Gap --> Tasks
  Mem --> Tasks

The codebase scouts

Scout	Tier	Job
repo-scout	Reasoning	Runs at every depth. Scans the repo for existing patterns, conventions, and related code paths so new work matches what is already there; at SHORT it also covers the docs-gap charter. Reads the optional clawpatch feature index when present, and degrades to grep/glob when it is not.
spec-scout	Reasoning	Runs at every depth. Reads open specs to surface dependencies and relationships, so a new plan slots into the existing graph instead of colliding with it.
memory-scout	Reasoning	Searches .flow/memory/ for prior learnings - bug fixes and curated knowledge - relevant to the task. Dispatched by /flow-next:refine --scope=research, not by plan. Plan and work read memory the same way with or without a key: one flowctl memory search --limit 15 --rerank when memory.enabled is set. With TYPESAFE_API_KEY set, Jev reorders the hits and drops none; without it they come back in BM25 order. See Optional Jev judgments.

The ecosystem scouts

Scout	Tier	Job
docs-scout	Reasoning	STANDARD and DEEP. Finds the exact framework and library documentation pages the implementation will need, version-aware - because docs change between versions.
practice-scout	Reasoning	STANDARD and DEEP. 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 at STANDARD and DEEP when scouts.github is enabled.

The rationale scout

Scout	Tier	Job
why-scout	Reasoning	Answers a why question about the code (“why was Y built this way”, “why does X guard against Z”) from a pointer: a file, a symbol, a line range, a commit, a PR number, or a spec id. It anchors on git blame and the PRs behind the commits, reads the tracker thread only through access the session already has, then the bug and decision memory tracks. Every finding carries a confidence tier (direct, supported, inferred, unknown) that the caller may not rewrite. Dispatched by /flow-next:flow on the investigation route, and by name when you ask a why question. Plan does not dispatch it.

The synthesis scouts

Scout	Tier	Job
flow-gap-analyst	Reasoning	Runs at every depth. 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	STANDARD and DEEP (repo-scout covers it at SHORT). Identifies which docs will need updating once the change lands, so documentation is planned in rather than bolted on. Shared with /flow-next:prime.

Note

Codebase research always goes through repo-scout - there is no second research mode to choose between, and no question about it at plan time. SHORT, the default, dispatches repo-scout, spec-scout, and flow-gap-analyst. STANDARD and DEEP add docs-scout, practice-scout, and docs-gap-scout, plus github-scout when scouts.github is on. The set follows depth and config, not a judgment about what seems relevant.