subagent-orchestrator

name	subagent-orchestrator
description	Delegate large work to subagents safely. Use for codebase mapping, bug tracing, security review, test gap analysis, performance review, and research. Trigger on /subagent-orchestrator, or when a task is too large for a single agent pass.
user-invocable	true
allowed-tools	Read, Grep, Glob, Bash, Edit

Subagent Orchestrator

Delegate large or parallel work to subagents while keeping the main agent in control.

When to Use Subagents

• Codebase map — exploring unfamiliar areas of a large codebase.
• Bug trace — tracing a code path across many files.
• Security review — scanning for vulnerabilities, credential leaks, injection risks.
• Test gap review — identifying untested code paths.
• Performance review — profiling, identifying bottlenecks.
• Documentation and research — gathering context from docs or external sources.

When NOT to Use Subagents

• Tiny single-file edits.
• Tasks that require consistent state across multiple file edits (risk of conflicts).
• Trivial lookups that can be done with Grep/Glob directly.

Subagent Prompt Template

Every subagent prompt must include:

Goal: <what to accomplish>
Context: <relevant background, file paths, domain knowledge>
Scope: <exact boundaries — what files, what aspects>
Forbidden: <what NOT to do — e.g. "do not edit files", "do not run destructive commands">
Tools: <allowed tools — default: Read, Grep, Glob, Bash>
Output: <expected deliverable format>
Validation: <how the main agent will verify the output>
Budget: <estimated complexity, time guidance>

Coordination Rules

• Subagents should not edit files unless explicitly scoped to do so.
• The main agent integrates all findings. Do not merge subagent output blindly.
• Do not spawn multiple subagents that edit overlapping files.
• If a subagent result conflicts with another, the main agent resolves the conflict.
• Track subagent tasks in a shared ledger to avoid redundant work.

Experience Log

This skill learns from experience. Mechanism:

• Read .claude/experience/subagent-orchestrator.md at skill start to benefit from past lessons.

• Write to .claude/experience/subagent-orchestrator.md after use if you learned something new.

• Format: YYYY-MM-DD: <lesson> — one line per entry.

• Evolve: If the same issue repeats 3+ times, update this SKILL.md itself.

This skill improves over time. After each use, append lessons learned.

Record format: YYYY-MM-DD: <lesson> Read this at skill start to apply past lessons.