Subagents

When you run /flow-next:plan or /flow-next:work, you are not talking to one model doing everything in one context window. Each command 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.

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, not one agent

• 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 nine 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) write files, and even they cannot spawn subagents.
• Right model for the job. Each subagent is assigned a tier by how much reasoning its job needs — a reasoning tier for analysis and synthesis, a fast tier for mechanical scans, and inherit the caller’s model for the builders.

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
Reasoning	Opus	gpt-5.5	equivalent reasoning model
Fast	Sonnet	gpt-5.4-mini	equivalent fast model
Inherits	the caller’s model	the caller’s model	the caller’s model

A few scouts that make quality judgments (spec-scout, claude-md-scout, docs-gap-scout) sit in the reasoning tier even though Claude runs them on Sonnet for cost — the tier reflects intent, and Codex maps them to its reasoning model accordingly.

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
context-scout	Reasoning	Token-efficient deep exploration via RepoPrompt codemaps and slices
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	Fast	Prior learnings in .flow/memory/ relevant to the task
flow-gap-analyst	Reasoning	Missing requirements, edge cases, and open questions
docs-gap-scout	Reasoning	Which docs will need updating once the change lands

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	Fast	Build system, scripts, and CI — can an agent compile and run it?
testing-scout	Fast	Test framework, coverage config, and how to run tests
tooling-scout	Fast	Linting, formatting, type-checking, pre-commit
claude-md-scout	Reasoning	Quality and completeness of CLAUDE.md / AGENTS.md
env-scout	Fast	.env templates, Docker, devcontainers, system deps
security-scout	Fast	Branch protection / rulesets, CODEOWNERS, dependency updates
observability-scout	Fast	Logging, tracing, metrics, health endpoints
workflow-scout	Fast	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 — re-anchor, build, commit, mark done
plan-sync	Reasoning	Proposes updates to downstream specs after implementation drift
quality-auditor	Reasoning	Adversarial review of the diff: correctness, simplicity, security, tests
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.