# Subagents Source: https://flow-next.dev/subagents/overview/ Every flow-next command is backed by a fleet of specialized subagents the skills dispatch for you - scouts that investigate, workers that build, auditors that check. When you run `/flow-next:plan`, or `/flow-next:work` on a spec with several tasks, the command fans out. (A single-task spec is built inline in the conversation, with no worker.) Each one is an **orchestrator** that dispatches a fleet of specialized **subagents** - each with its own fresh context, its own model tier, and its own narrow job. You never invoke these directly; they exist so the commands you *do* invoke stay fast, focused, and hard to derail. This section documents that machinery: **21 subagents** across three roles, including one rationale scout the [flow](https://flow-next.dev/skills/flow/) skill dispatches on a why question. ## The three layers ```mermaid flowchart LR You["You"] -->|"/flow-next:plan"| Plan["plan"] You -->|"/flow-next:prime"| Prime["prime"] You -->|"/flow-next:work"| Work["work"] You -->|"/flow-next:resolve-pr"| Resolve["resolve-pr"] Plan --> PS["9 planning scouts"] Prime --> RS["8 readiness scouts"] Work --> EX["worker · plan-sync · quality-auditor"] Resolve --> PR["pr-comment-resolver"] ``` * **You** type a slash command. * The **skill** orchestrates: it reads state, decides what to dispatch, and composes the results into one answer. * The **subagents** do the scoped work in isolated context and report structured findings back up. ## Why a fleet * **Fresh context per job.** A scout that reads twenty files returns a paragraph, not twenty files’ worth of tokens in your main conversation. * **Parallel fan-out.** `/flow-next:plan` dispatches up to eight scouts at once; `/flow-next:prime` runs eight. Coverage grows without growing wall-clock. * **Read-only by design.** Every scout disallows `Edit`, `Write`, and `Task` - it can investigate but cannot touch your code or spawn further agents. Only the builders (`worker`, `pr-comment-resolver`, `plan-sync`) edit files; `worker` and `pr-comment-resolver` may dispatch subagents of their own. The `Task` denial stays on every read-only agent for the reason it exists: one that can spawn a writing subagent has an escape hatch out of read-only. * **Right model for the job.** Each subagent is assigned a **tier**: every read-only agent (and `plan-sync`) sits in the reasoning tier, and the other two builders *inherit the caller’s model*. A fast tier exists for your own routing, but no bundled agent defaults to it. You never type these names - they are dispatched for you. The pages in this section exist to show what is happening under the hood, and how much ground each command actually covers. The **Tier** column below is platform-neutral on purpose. flow-next picks the concrete model for whatever runtime you are on, and the sync layer translates automatically - you never set a model name yourself: | Tier | Claude Code | Codex | Droid | Cursor | | ---------------------------------- | ---------------------------------------------------------- | -------------------------------- | -------------------------- | --------------------------- | | Reasoning | Sonnet for the scouts, Opus for the quality auditor | the mirror’s `INTELLIGENT` model | equivalent reasoning model | **inherit** (session model) | | Fast (no bundled agent by default) | whatever you name on the routing block’s `fast scout` line | the mirror’s `FAST` model | equivalent fast model | **inherit** (session model) | | Inherits | the caller’s model | the caller’s model | the caller’s model | the caller’s model | The Codex mirror’s concrete `INTELLIGENT` / `FAST` model ids are set by the sync layer and move with OpenAI’s lineup (overridable via `CODEX_MODEL_INTELLIGENT` / `CODEX_MODEL_FAST` when regenerating the mirror), so this page names the roles, not volatile ids. **Cursor host - agents-alias → inherit.** Canonical `agents/*.md` family aliases (`haiku` / `sonnet` / `opus`) are ignored on Cursor; every subagent inherits the session model. There is no alias-to-slug rewrite and none is planned (marketplace import consumes canonical files as-is). Caller-side in-prompt Cursor slugs are the escape hatch - ask `cursor-agent --list-models` for the current ids rather than copying one from a document. Read-only agents also carry Cursor-native `readonly: true` (Cursor does not enforce Claude’s `disallowedTools`). See [Orchestration → Cursor host](https://flow-next.dev/guides/model-routing/#cursor-host). On Claude the scouts pin `sonnet`, which follows the current Sonnet release, rather than inheriting the session model, so a session on a pricier model does not run every scout fan-out on it too. The quality auditor pins `opus`, because a bug it misses goes unnoticed. The `sonnet` alias means Sonnet 5.5 from Claude Code 2.1.284; an older Claude Code resolves it to Sonnet 5. To move the scouts to another model, name it on your routing block’s `fast scout` / `thinking scout` lines, which beat an agent’s own default. See [Model routing](https://flow-next.dev/guides/model-routing/#the-routing-block). ## Planning scouts → `/flow-next:plan` Research the codebase, the ecosystem, and the existing plan graph before any task is written. [Full detail →](https://flow-next.dev/subagents/planning-scouts/) | Subagent | Tier | What it surfaces | | ------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `repo-scout` | Reasoning | Existing patterns, conventions, and related code paths to match | | `spec-scout` | Reasoning | Dependencies and relationships against open specs | | `docs-scout` | Reasoning | The exact framework/library docs the implementation will need | | `practice-scout` | Reasoning | Current best practices, anti-patterns, and pitfalls | | `github-scout` | Reasoning | Reference implementations and known issues across GitHub | | `memory-scout` | Reasoning | Prior learnings in `.flow/memory/` relevant to the task. Plan no longer spawns it (it runs one memory search itself); refine’s research pass uses it | | `flow-gap-analyst` | Reasoning | Missing requirements, edge cases, and open questions | | `docs-gap-scout` | Reasoning | Which docs will need updating once the change lands | | `why-scout` | Reasoning | The rationale behind a change, from blame, PRs, the tracker thread, and memory, each finding tiered `direct`, `supported`, `inferred`, or `unknown`. Dispatched by [`/flow-next:flow`](https://flow-next.dev/skills/flow/) on a why question, never by plan | `docs-scout`, `practice-scout`, `docs-gap-scout`, and `memory-scout` also serve [`/flow-next:refine --scope=research`](https://flow-next.dev/skills/refine/), the read-first pass over a spec that names a library or API the repo does not already use. ## Readiness scouts → `/flow-next:prime` Assess whether the repository is ready for agents and production. Each scout owns one pillar. [Full detail →](https://flow-next.dev/subagents/readiness-scouts/) | Subagent | Tier | What it surfaces | | --------------------- | --------- | ---------------------------------------------------------------- | | `build-scout` | Reasoning | Build system, scripts, and CI - can an agent compile and run it? | | `testing-scout` | Reasoning | Test framework, coverage config, and how to run tests | | `tooling-scout` | Reasoning | Linting, formatting, type-checking, pre-commit | | `claude-md-scout` | Reasoning | Quality and completeness of `CLAUDE.md` / `AGENTS.md` | | `env-scout` | Reasoning | `.env` templates, Docker, devcontainers, system deps | | `security-scout` | Reasoning | Branch protection / rulesets, CODEOWNERS, dependency updates | | `observability-scout` | Reasoning | Logging, tracing, metrics, health endpoints | | `workflow-scout` | Reasoning | CI/CD pipelines, PR/issue templates, automation | `docs-gap-scout` is shared with planning above. ## Execution & review → `/flow-next:work`, `/flow-next:sync`, `/flow-next:resolve-pr` The agents that change code and guard quality. [Full detail →](https://flow-next.dev/subagents/execution/) | Subagent | Tier | What it does | | --------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `worker` | Inherits | Implements one task in fresh context when a spec has several tasks or a task goes to a chosen model - re-anchor, build, commit, mark done | | `plan-sync` | Reasoning | Proposes updates to downstream specs after implementation drift | | `quality-auditor` | Reasoning | Two-axis adversarial review of the diff - correctness (spec conformance, security, tests) and standards (simplicity, naming), dispatched in parallel | | `pr-comment-resolver` | Inherits | Resolves a single PR review thread and returns a structured verdict | Beyond these 21, `/flow-next:capture` and `/flow-next:audit` also dispatch the platform’s generic read-only `Explore` subagent for ad-hoc investigation. It is a host primitive rather than a flow-next-defined agent, so it has no page of its own.