# Planning Scouts

Source: https://flow-next.dev/subagents/planning-scouts/

The read-only scouts /flow-next:plan and refine's research pass dispatch to research the codebase, the ecosystem, and the existing plan graph before a single task is written.

`/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`](https://flow-next.dev/skills/refine/) 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](https://flow-next.dev/subagents/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.

```mermaid
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](https://flow-next.dev/skills/map/) 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`](https://flow-next.dev/skills/refine/), 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](https://flow-next.dev/guides/jev-judge/). |

## 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`](https://flow-next.dev/skills/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`](https://flow-next.dev/subagents/readiness-scouts/). |

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.