ktg-plugin-marketplace/plugins/ultraplan-local/skills/cc-architect-catalog/subagents-pattern.md

name	description	layer	cc_feature	source	concept	last_verified	ngram_overlap_score	review_status
subagents-pattern	When subagents earn their cost and how to compose them — swarm, pipeline, and guard patterns.	pattern	subagents	https://docs.claude.com/en/docs/claude-code/sub-agents	subagent-composition	2026-04-18	null	approved

Subagents — Pattern

When to delegate

Delegation earns its cost when at least one of these holds:

• Context isolation — the subtask needs to read 50+ files or run many greps, and the parent conversation does not need the raw results. Summaries survive; raw output stays in the subagent.
• Parallelism — multiple independent subtasks can run at once, compressing wall-clock time.
• Specialization — the subagent has a tailored system prompt that changes its behavior meaningfully (e.g., adversarial reviewer).
• Tool scoping — the subtask should run with fewer tools than the parent (principle of least privilege).

If none of these apply, inline the work. A subagent call costs a full model turn; do not pay it for routine reads.

Common patterns

Pattern A: Exploration swarm

Parent launches 4-8 specialized subagents in parallel, each with a narrow brief (architecture, dependencies, risks, tests, ...). Each returns a summary. Parent synthesizes.

Used by: ultraplan-local Phase 2 exploration.

Cost shape: N × Sonnet call, wall-clock ≈ slowest subagent.

Pattern B: Adversarial review

Parent writes an artifact (plan, design note). Launches a reviewer subagent with a system prompt that demands problems, never praise. Reviewer returns findings. Parent revises.

Used by: plan-critic, scope-guardian, architecture-critic.

Cost shape: 1 × Sonnet call per review pass.

Pattern C: Background orchestrator

Parent kicks off a long-running orchestrator subagent with run_in_background: true, then continues. Orchestrator runs its own subagents, synthesizes, writes output to disk. Parent is notified on completion.

Used by: planning-orchestrator, research-orchestrator.

Cost shape: 1 × Opus orchestrator + N × Sonnet workers. Overlaps with other user work.

Pattern D: Guard subagent

A hook delegates an "is this safe?" question to a subagent when the answer needs judgment. The subagent returns a verdict; the hook enforces it.

Cost shape: 1 × Sonnet call per hook invocation. Use sparingly — adds seconds of latency per tool call.

Pitfalls

• Delegate-understanding anti-pattern — do not write "based on your findings, fix the bug" to a subagent. The subagent is not inside your head; it cannot see what you synthesized. Pass concrete context.
• Prompt-on-top-of-prompt drift — if the parent's prompt to a subagent contradicts the subagent's own system prompt, the subagent follows its system prompt. Do not try to re-style a reviewer into a cheerleader by prompting harder.
• Silent failure — a subagent that returns "done" without evidence may have done nothing. Trust but verify: check for the concrete artifacts the subagent was asked to produce.
• Orchestration explosion — a three-level-deep subagent tree costs exponentially. Flatten wherever the inner levels don't need their own context isolation.
• Token budget fights — parent and all active subagents share the harness's overall budget. Cap subagent output length ("report in under 200 words") when the summary is what matters.

Composition with other features

• Subagents + hooks: hooks fire during subagent tool calls too. A subagent with only Read tools is already constrained; hooks add defense in depth.
• Subagents + worktrees: an isolation: "worktree" subagent works in an isolated copy of the repo, so its writes never clash with the parent's writes.
• Subagents + background: run heavy exploration in background while the user continues other work.