Subagents

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 skill dispatches on a why question.

The three layers

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.

Note

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.

Tiers map to a model per platform

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.

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.

Planning scouts → /flow-next:plan

Research the codebase, the ecosystem, and the existing plan graph before any task is written. Full detail →

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 on a why question, never by plan

docs-scout, practice-scout, docs-gap-scout, and memory-scout also serve /flow-next:refine --scope=research, 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 →

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 →

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

Note

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.