Sub Agent Invocation

4. Performance Directives (Demand Excellence)

• Always include: "Think hard and analyze deeply before proceeding"
• Specify thoroughness level: "comprehensive analysis" or "quick validation"

Invocation Template

"USER'S ORIGINAL REQUEST: [verbatim user prompt - MANDATORY]

[COMPREHENSIVE CONTEXT]
- Project: [overall goal and current state]
- Background: [why this matters, how it fits]
- Dependencies: [what this builds on or integrates with]

TASK ASSIGNMENT:
[Detailed, specific requirements with clear scope and boundaries]

CONTEXT REFERENCES:
- Session: [path and what to extract]
- Skills: [relevant skills to load]
- Examples: [similar existing implementations]

Think hard and provide [thoroughness level] analysis/implementation.

DELIVERABLES:
[Exact format, success criteria, validation requirements]"

Sub-Agent Context Principle: Sub-agents have temporary windows—maximize their context collection. Over-collection is safe; under-collection causes failures.

Common Invocation Failures

Routing Decision

/build vs /team-build Decision:

• /build: Tasks are independent, sub-agents don't need to communicate, cost-sensitive (1x tokens)
• /team-build: Agents need peer-to-peer coordination, cross-domain interfaces, contract-first spawning (2-4x tokens)

Auto-Invocation Protocol

Central AI auto-invokes /team-plan + /build (or /team-build) for complex work. This is the standard operating procedure for all non-trivial implementation.

Decision Criteria

Auto-invoke /team-plan immediately when:

• Request involves 5+ files or multiple domains
• Request is clearly multi-phase (e.g., "build feature with X, Y, Z")
• Request involves architectural or structural changes
• User explicitly asks for team coordination or a plan

Gather info first, then invoke when:

• Request is vague but potentially complex
• Request needs clarification about scope or approach
• Request touches unfamiliar areas of the codebase

Don't invoke (direct execution) when:

• Single file fix, typo, config change
• Clear, bounded task for a single specialist
• Research/exploration only (no implementation)

Invocation Syntax

Step 1 - Plan:

Skill({ skill: "team-plan", args: "<comprehensive prompt with all context>" })

Step 2 - Pause: Present the plan summary to the user. Wait for approval ("go", /build, /team-build, or feedback).

Step 3 - Execute (after user approval):

For isolated sub-agent execution (default):

Skill({ skill: "build", args: ".claude/tasks/<plan-file>.md" })

For collaborative Agent Teams execution (when agents need peer-to-peer coordination):

Skill({ skill: "team-build", args: ".claude/tasks/<plan-file>.md" })

Use /team-build when the plan involves cross-domain integration where agents need to share contracts (schemas, API specs, interfaces) and coordinate in real-time. Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.

Prompt Composition for Auto-Invocation

When composing the prompt for /team-plan, Central AI should include:

1. User's verbatim request - Always include the original words
2. Clarifications gathered - Any answers from AskUserQuestion
3. Codebase context - Relevant patterns, files, and architecture discovered
4. Constraints and preferences - User-expressed boundaries
5. Orchestration guidance (optional) - Hints for team composition or parallel/sequential structure

Example auto-invocation:

Skill({
  skill: "team-plan",
  args: "Build a new models section for the blog with 11 model profile pages. User wants: chronological model pages from Claude 3 through Opus 4.6, a models index page, and cross-links to existing posts. Existing blog structure is in apps/web/src/content/blog/blog-structure.ts. Content style should match existing guide posts. Use content-writer agents for parallel page creation."
})

Coordination Patterns

Parallel Execution

Invoke multiple agents using multiple Task tool calls in ONE message.

Use parallel dispatch when ALL conditions met:

• 3+ unrelated issues or independent domains
• No shared state between tasks
• Clear boundaries with no file overlap

Use serial dispatch when ANY condition present:

• Interconnected failures (one fix may resolve others)
• Shared state or same files (risk of merge conflicts)
• Sequential dependencies (B depends on A completing)
• Unclear scope (need to understand before fixing)

Parallel Agent Output Rule: When dispatching agents in parallel, instruct them to write their work to files (edits, creations) rather than returning lengthy responses in the terminal. All work is version controlled, so file-based output is preferred. This prevents context bloat from multiple agents returning verbose terminal output simultaneously.

Specialist + Quality Engineer Validation

The high-reliability pattern: specialist agents build, quality-engineer validates. Use when incorrect output has high cost.

Specialist agents serve as builders. Use the appropriate specialist for the domain: frontend-specialist, backend-engineer, supabase-specialist, security-auditor, performance-optimizer, or general-purpose for cross-domain work. Each specialist focuses on ONE task and reports completion via TaskUpdate.

Quality engineer serves as validator. When dispatched in validation mode, the quality-engineer inspects completed work without modifying files and produces a structured pass/fail report.

Validation prompt template:

"You are operating in VALIDATION MODE. Verify the completed work against acceptance criteria.

TASK TO VALIDATE: [task description and acceptance criteria]
SPECIALIST'S WORK: [files to inspect, expected changes]

WORKFLOW:
1. Read the task requirements and acceptance criteria
2. Inspect all files the specialist changed
3. Run validation commands (tests, type checks, compilation)
4. Report PASS or FAIL with specific evidence using the Validation Report format

CONSTRAINT: Do NOT modify any files. Inspect and report only. If issues are found, report them for the specialist to fix."

Dependency pattern for specialist/validation chains:

TaskCreate: "Build feature X"       -> Task #1 (assigned to specialist)
TaskCreate: "Validate feature X"    -> Task #2 (assigned to quality-engineer)
TaskUpdate: Task #2 addBlockedBy: ["1"]  // Validation waits for build

// Multiple specialists can run in parallel:
TaskCreate: "Build component A"     -> Task #1 (frontend-specialist)
TaskCreate: "Build component B"     -> Task #2 (backend-engineer)
TaskCreate: "Validate all"          -> Task #3 (quality-engineer), addBlockedBy: ["1", "2"]

Resume Pattern

Store agent IDs to continue work with preserved context:

// First deployment
Task({ prompt: "Build X...", subagent_type: "general-purpose" })
// Returns: agentId "abc123"

// Later - resume with full prior context
Task({ prompt: "Now add tests...", resume: "abc123" })

Use resume when: continuing related work, agent needs prior context. Use fresh when: unrelated task, clean slate preferred.

Sequential Dependencies

Agent Routing Reference