07f02e77db
New optional command between /ultraresearch-local and /ultraplan-local that matches brief+research against Claude Code features (hooks, subagents, skills, output-styles, MCP, plan-mode, worktrees, background-agents) and produces an architecture note with brief-anchored rationale plus explicit gaps. Added: - commands/ultra-cc-architect-local.md (--project, --fg, --quick, --no-gaps) - agents/architect-orchestrator.md (opus) — 6-phase background orchestrator - agents/feature-matcher.md (sonnet) — fallback-ranked feature proposals - agents/gap-identifier.md (sonnet) — 4 gap classes with issue-ready drafts - agents/architecture-critic.md (sonnet) — hallucination gate as BLOCKER - skills/cc-architect-catalog/ — SKILL.md + 10 seed entries (reference/pattern) Changed (non-breaking): - commands/ultraplan-local.md — auto-discovers architecture/overview.md - agents/planning-orchestrator.md — cross-references cc_features_proposed - plugin.json — 2.1.0 → 2.2.0, description, cc-architecture keyword - CHANGELOG, README, CLAUDE.md (plugin + marketplace root) Pipeline becomes brief → research → architect → plan → execute. Architect is optional; existing project dirs keep working unchanged. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
103 lines
3.8 KiB
Markdown
103 lines
3.8 KiB
Markdown
---
|
||
name: subagents-pattern
|
||
description: When subagents earn their cost and how to compose them — swarm, pipeline, and guard patterns.
|
||
layer: pattern
|
||
cc_feature: subagents
|
||
source: https://docs.claude.com/en/docs/claude-code/sub-agents
|
||
concept: subagent-composition
|
||
last_verified: 2026-04-18
|
||
ngram_overlap_score: null
|
||
review_status: 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.
|