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>
98 lines
3.1 KiB
Markdown
98 lines
3.1 KiB
Markdown
---
|
||
name: subagents-reference
|
||
description: CC subagents — how the Task tool spawns isolated agent instances with scoped tools and context.
|
||
layer: reference
|
||
cc_feature: subagents
|
||
source: https://docs.claude.com/en/docs/claude-code/sub-agents
|
||
concept: task-tool-delegation
|
||
last_verified: 2026-04-18
|
||
ngram_overlap_score: null
|
||
review_status: approved
|
||
---
|
||
|
||
# Subagents — Reference
|
||
|
||
Subagents are fresh Claude instances spawned via the Task tool. Each
|
||
receives a task prompt, a tool subset, and no memory of the parent
|
||
conversation except what the parent explicitly passes. They return a
|
||
single final message to the parent.
|
||
|
||
## Anatomy
|
||
|
||
A subagent has:
|
||
|
||
- **A name** — either a built-in type (`general-purpose`, `Explore`,
|
||
`Plan`) or a plugin-defined type (`code-reviewer`, `test-runner`,
|
||
...).
|
||
- **A system prompt** — defined by the agent type. The parent cannot
|
||
override it.
|
||
- **A tool set** — subset of the parent's tools, as declared in the
|
||
agent definition's frontmatter `tools:` field.
|
||
- **A task prompt** — what the parent asks it to do. Self-contained;
|
||
the subagent has no access to prior messages.
|
||
- **A model** — either explicit in the agent definition (`model: opus |
|
||
sonnet | haiku`) or inherited from the parent.
|
||
|
||
## How to define a subagent
|
||
|
||
A plugin agent is a markdown file in `agents/` with frontmatter:
|
||
|
||
```yaml
|
||
---
|
||
name: code-reviewer
|
||
description: <when to invoke, include examples>
|
||
model: sonnet
|
||
tools: ["Read", "Grep", "Glob"]
|
||
---
|
||
|
||
<system prompt content>
|
||
```
|
||
|
||
The `description` field is how Claude decides when to spawn this
|
||
subagent. Include concrete trigger examples.
|
||
|
||
## How to invoke
|
||
|
||
Parent calls the `Task` / `Agent` tool with:
|
||
|
||
- `subagent_type` — the agent's name
|
||
- `description` — short label for logs
|
||
- `prompt` — the self-contained task
|
||
|
||
Optional:
|
||
|
||
- `run_in_background: true` — agent runs in the background; parent
|
||
is notified on completion.
|
||
- `isolation: "worktree"` — agent runs in a temporary git worktree
|
||
(isolated copy of the repo).
|
||
|
||
## Return protocol
|
||
|
||
- Foreground agent: parent blocks until the agent returns. Return value
|
||
is a single text message.
|
||
- Background agent: parent continues. On completion, the harness
|
||
injects a notification into the parent's next turn.
|
||
|
||
## Isolation guarantees
|
||
|
||
- No conversation history sharing. Each subagent starts cold.
|
||
- Separate context window. A subagent can read large files without
|
||
polluting the parent's context.
|
||
- Separate tool permissions. A subagent with only `Read` tools cannot
|
||
write files, even if the parent can.
|
||
|
||
## Cost and latency
|
||
|
||
- Every subagent call is a full model call with its own token budget.
|
||
- Model choice matters: Sonnet is ~5× cheaper than Opus; Haiku is
|
||
cheaper still but cannot be used (per project policy).
|
||
- Parallel subagents: the parent can launch multiple in one message;
|
||
the harness runs them concurrently. Total latency ≈ slowest agent.
|
||
|
||
## Failure modes
|
||
|
||
- Subagent hits context limit → partial or missing return.
|
||
- Subagent runs in background and the parent conversation ends → result
|
||
may be orphaned.
|
||
- Subagent's return message hallucinates file paths → caller must
|
||
verify.
|