Spawn Agent

Spawn Agent Skill

Purpose: Spawn PAI agents using MCP factory pattern Created: 2026-01-16 Trigger: /spawn-agent <agent_name> <mission> Model Tier: Sonnet (Execution)

Overview

This skill bridges MCP tools with Claude Code's Task() function for agent spawning.

The Pattern:

1. MCP spawn_agent_tool prepares context (identity, RAG, skills)
2. Claude Code executes via Task(prompt=spec.full_prompt, ...)
3. Spawned agent runs with full Claude Code capabilities

Why This Exists:

• No API keys needed in MCP server
• Spawned agents have Edit/Write/Bash/MCP tool access
• Governance (spawn chain, audit trail) enforced centrally

When to Use

Use This Skill When:

• Need to spawn a PAI agent for a specific mission
• Orchestrating multi-agent workflows
• Delegating domain-specific work to specialists
• Need RAG context injected into agent prompt

Do NOT Use When:

• Simple single-shot tasks (just do it directly)
• Research/exploration (use /search-party instead)
• Need to create a new agent (use /agent-factory instead)

Usage

Basic Syntax

/spawn-agent AGENT_NAME mission description here

Examples

/spawn-agent SCHEDULER Generate Block 10 schedule with ACGME compliance
/spawn-agent COMPLIANCE_AUDITOR Audit Block 10 for work hour violations
/spawn-agent G2_RECON Find all constraint implementations in the codebase
/spawn-agent COORD_ENGINE Optimize solver performance for schedule generation

With Parent Context (for spawn chain validation)

/spawn-agent SCHEDULER Generate Block 10 --parent COORD_ENGINE

Execution Protocol

When /spawn-agent is invoked, follow these steps:

Step 1: Load MCP Tool

# First, load the spawn_agent_tool
MCPSearch(query="select:mcp__residency-scheduler__spawn_agent_tool")

Step 2: Call spawn_agent_tool

spec = mcp__residency-scheduler__spawn_agent_tool(
    agent_name="AGENT_NAME",
    mission="The mission description",
    context={"relevant": "context"},  # Optional
    inject_rag=True,                   # Default: True
    inject_skills=None,                # Auto-match if None
    parent_agent="PARENT_NAME"         # Optional, for spawn chain
)

Step 3: Validate Response

Check the returned spec for:

• spawn_chain_valid: Must be True (or no parent specified)
• identity_found: Must be True
• tier and model: Determine execution parameters

If validation fails:

if not spec["spawn_chain_valid"]:
    # Escalate: parent cannot spawn this child
    raise SpawnChainViolation(spec["spawn_chain_error"])

if not spec["identity_found"]:
    # Escalate: need to create identity card first
    raise IdentityNotFound(f"Create identity: .claude/Identities/{agent_name}.identity.md")

Step 4: Execute via Task()

result = Task(
    prompt=spec["full_prompt"],
    subagent_type=spec["subagent_type"],  # "general-purpose"
    model=spec["model"],                   # haiku/sonnet/opus
    max_turns=spec["max_turns"],           # 5/20/50 based on tier
    description=f"{spec['agent_name']}: {mission[:30]}..."
)

Step 5: Handle Checkpoint (Optional)

If the agent needs to persist state:

# Agent writes checkpoint to spec["checkpoint_path"]
# Example: .claude/Scratchpad/AGENT_SCHEDULER_20260116_143022.md

# To resume later:
# Read checkpoint, include in next spawn's context

Tier-Based Execution

Rule: Match task complexity to tier. Don't spawn opus for simple validation.

Spawn Chain Validation

The MCP tool validates that parent agents can spawn children:

# From agents.yaml
COORD_ENGINE:
  can_spawn: [SCHEDULER, SWAP_MANAGER, OPTIMIZATION_SPECIALIST]

ARCHITECT:
  can_spawn: [COORD_PLATFORM, COORD_QUALITY, COORD_ENGINE, ...]

If spawn chain fails:

• Error message tells you who CAN spawn this agent
• Escalate to the correct parent or ORCHESTRATOR

Spawning Constraints (Session 138 Discovery)

Task() Availability by Spawner

Why This Matters

Subagents spawned via Task() do NOT have Task() available. They have all other tools (Bash, Edit, MCP, etc.) but cannot spawn further agents via Task().

Two working patterns:

Pattern A: Flat Parallelism (ORCHESTRATOR spawns all)

ORCHESTRATOR ──┬── Agent 1 (no Task(), works directly)
               ├── Agent 2 (no Task(), works directly)
               └── Agent N (no Task(), works directly)

Pattern B: CLI Spawning (for hierarchical)

ORCHESTRATOR ── Coordinator (via Task, no Task())
                     │
                     └── Bash: claude -p → Specialist (HAS Task())
                                               │
                                               └── Can spawn further agents

CLI Spawning Syntax

When a subagent needs to spawn another agent:

claude -p "
You are SPECIALIST.

## Identity
[Include identity card content or key details]

## Mission
[Mission description with full context]

## Constraints
- Budget: Do not exceed this mission scope
- Report: Write findings to [path]
" --model haiku --max-budget-usd 1.00

Key points:

• CLI agents have full capabilities including Task()
• Context must be passed in prompt (same as Task() spawning)
• Use --max-budget-usd to prevent runaway costs
• Spawn chain validation is NOT enforced via CLI (governance by convention)

RAG Injection

By default, inject_rag=True queries relevant context:

# spawn_agent_tool internally does:
rag_results = rag_search(
    query=mission,
    doc_types=agent.relevant_doc_types,  # From agents.yaml
    top_k=5
)

To disable (faster, less context):

spec = spawn_agent_tool(..., inject_rag=False)

Checkpoint Protocol

Agents can persist state for resumption:

Writing Checkpoint (in spawned agent)

# .claude/Scratchpad/AGENT_SCHEDULER_20260116_143022.md

## Agent Checkpoint

**Agent:** SCHEDULER
**Mission:** Generate Block 10 schedule
**Status:** In Progress
**Timestamp:** 2026-01-16T14:30:22

### Progress
- [x] Loaded constraints
- [x] Ran solver (15 solutions found)
- [ ] Validation pending

### State
```json
{
  "block_number": 10,
  "solutions_found": 15,
  "best_objective": 0.87
}

Next Steps

1. Validate ACGME compliance on top 3 solutions
2. Select best based on fairness metric
3. Write to database

### Resuming from Checkpoint

```python
# Read checkpoint
checkpoint = Read(".claude/Scratchpad/AGENT_SCHEDULER_20260116_143022.md")

# Include in new spawn context
spec = spawn_agent_tool(
    agent_name="SCHEDULER",
    mission="RESUME: Complete Block 10 schedule generation",
    context={"checkpoint": checkpoint}
)

Audit Trail

Every spawn is logged to .claude/History/agent_invocations/:

{
  "invocation_id": "20260116_143022_SCHEDULER",
  "timestamp": "2026-01-16T14:30:22",
  "agent_name": "SCHEDULER",
  "tier": "Specialist",
  "model": "haiku",
  "mission": "Generate Block 10 schedule",
  "parent_agent": "COORD_ENGINE",
  "spawn_chain_valid": true,
  "rag_injected": true,
  "checkpoint_path": ".claude/Scratchpad/AGENT_SCHEDULER_20260116_143022.md"
}

Error Handling

Identity Not Found

Error: Identity card not found for agent: NEW_AGENT

Resolution:
1. Check if agent exists in .claude/agents.yaml
2. If not, use /agent-factory to create the agent
3. Create identity card at .claude/Identities/NEW_AGENT.identity.md

Spawn Chain Violation

Error: Spawn chain violation: SCHEDULER cannot spawn ARCHITECT

Resolution:
1. SCHEDULER can only spawn: [] (no children)
2. ARCHITECT should be spawned by: ORCHESTRATOR
3. Escalate to correct parent or invoke as ORCHESTRATOR

Registry Not Found

Error: Agent registry not found at .claude/agents.yaml

Resolution:
1. Verify .claude/agents.yaml exists
2. Check for YAML syntax errors
3. Regenerate from identity cards if needed

Integration Points

With ORCHESTRATOR Startup

/startupO and /startupO-lite can use this skill:

# In ORCHESTRATOR session
spec = spawn_agent_tool("G2_RECON", "Explore codebase for...")
Task(prompt=spec["full_prompt"], ...)

With Coordinator Skills

/coord-engine, /coord-platform, etc. spawn specialists:

# COORD_ENGINE spawning SCHEDULER
spec = spawn_agent_tool(
    "SCHEDULER",
    "Generate Block 10",
    parent_agent="COORD_ENGINE"  # Validates spawn chain
)

With Party Protocols

/search-party, /qa-party can spawn multiple agents in parallel:

# Spawn 10 G2_RECON probes
for i in range(10):
    specs.append(spawn_agent_tool("G2_RECON", f"Probe {i}: {target}"))

# Execute in parallel
for spec in specs:
    Task(prompt=spec["full_prompt"], ..., run_in_background=True)

Quick Reference

Agent Tiers

Common Spawns

# Scheduling
/spawn-agent SCHEDULER Generate Block X schedule

# Validation
/spawn-agent COMPLIANCE_AUDITOR Audit Block X for ACGME

# Research
/spawn-agent G2_RECON Find implementations of X

# Testing
/spawn-agent QA_TESTER Run test suite for X

# Documentation
/spawn-agent META_UPDATER Update docs for feature X

Aliases

• /spawn-agent (primary)
• /spawn (short form)
• /agent (alternative)

spawn-agent: The bridge between MCP governance and Claude Code execution.