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

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.