# Sub-Agent Architecture for Validation

This document describes the sub-agent architecture for music product validation.

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────┐
│                    Orchestrator                             │
│  (validate_subagents.py)                                  │
│                                                             │
│  • Reads product                                            │
│  • Determines which validators to run                       │
│  • Launches sub-agents IN PARALLEL                          │
│  • Merges results                                           │
│  • Generates final output                                   │
└─────────────────────────────────────────────────────────────┘
                         │
        ┌────────────────┼────────────────┐
        ▼                ▼                ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│   Release    │ │    Track     │ │  Classical   │
│  Validator   │ │  Validator   │ │  Validator   │
│              │ │              │ │              │
│ • Album      │ │ • Track      │ │ • Classical  │
│   metadata   │ │   metadata   │ │   rules      │
│ • Uses:      │ │ • Uses:      │ │ • Uses:      │
│   validate-  │ │   validate-  │ │   validate-  │
│   release-   │ │   track-     │ │   classical- │
│   metadata   │ │   metadata   │ │   metadata   │
│              │ │              │ │              │
│ Model: haiku │ │ Model: haiku │ │ Model: sonnet│
└──────────────┘ └──────────────┘ └──────────────┘
```

## Benefits

### 1. **Isolation**
- Each validator runs independently
- No cross-contamination between validation domains
- Clear responsibility boundaries

### 2. **Parallelization**
- All validators run simultaneously
- Faster total execution time
- Better resource utilization

### 3. **Cost Optimization**
- Use Haiku (cheaper) for straightforward validations
- Use Sonnet (more capable) only for complex classical rules
- Reduces overall API costs

### 4. **Scalability**
- Easy to add new validation domains
- Can adjust resources per validator
- Independent development and testing

### 5. **Clarity**
- Each sub-agent has a focused purpose
- Easier to debug specific validation issues
- Better separation of concerns

## File Structure

```
prompts/
├── orchestrator_prompt.md          # Main coordinator prompt
├── release_validator_prompt.md     # Album-level validation
├── track_validator_prompt.md       # Track-level validation
└── classical_validator_prompt.md   # Classical-specific validation

.claude/
├── skills/
│   ├── validate-release-metadata/  # Release validation skill
│   ├── validate-track-metadata/    # Track validation skill
│   └── validate-classical-metadata/# Classical validation skill
└── subagents.json                  # Sub-agent configuration

main_with_subagents.py              # Entry point using sub-agents
main.py                             # Original single-agent entry point
```

## Usage

### Run with Sub-Agent Architecture

```bash
python main_with_subagents.py
```

### Run with Original Architecture (Single Agent)

```bash
python main.py
```

## How It Works

### Step 1: Orchestrator Reads Product
The orchestrator reads `sample_product.json` and determines:
- Genre (to decide if classical validator is needed)
- Product structure

### Step 2: Launch Sub-Agents in Parallel
The orchestrator uses the Task tool to spawn sub-agents:

```python
# Pseudo-code for orchestrator
Task(
    description="Validate release metadata",
    prompt=read("prompts/release_validator_prompt.md"),
    subagent_type="general-purpose",
    run_in_background=True
)

Task(
    description="Validate track metadata",
    prompt=read("prompts/track_validator_prompt.md"),
    subagent_type="general-purpose",
    run_in_background=True
)

if genre == "Classical":
    Task(
        description="Validate classical rules",
        prompt=read("prompts/classical_validator_prompt.md"),
        subagent_type="general-purpose",
        run_in_background=True
    )
```

### Step 3: Sub-Agents Execute
Each sub-agent:
1. Reads the product file
2. Uses its designated skill
3. Returns validation results in structured JSON

### Step 4: Orchestrator Merges Results
The orchestrator:
1. Waits for all sub-agents to complete
2. Collects results from each
3. Merges into unified validation result
4. Calculates overall status and summary
5. Writes to `validation_results.json`

## Sub-Agent Configuration

Configuration is defined in `.claude/subagents.json`:

```json
{
  "subagents": {
    "release-validator": {
      "skills": ["validate-release-metadata"],
      "model": "haiku",
      "tools": ["Skill", "Read"]
    },
    "track-validator": {
      "skills": ["validate-track-metadata"],
      "model": "haiku",
      "tools": ["Skill", "Read"]
    },
    "classical-validator": {
      "skills": ["validate-classical-metadata"],
      "model": "sonnet",
      "tools": ["Skill", "Read"]
    }
  }
}
```

## Performance Comparison

### Original Architecture (Single Agent)
- **Execution**: Sequential
- **Time**: ~45-60 seconds
- **Model**: Sonnet for everything
- **Cost**: Higher (Sonnet for all tasks)

### Sub-Agent Architecture
- **Execution**: Parallel
- **Time**: ~20-30 seconds (fastest sub-agent determines total)
- **Model**: Haiku for simple tasks, Sonnet for complex
- **Cost**: Lower (optimized model selection)

## Debugging

### View Sub-Agent Logs
Sub-agents run as background tasks. You can view their progress in the orchestrator output.

### Test Individual Sub-Agents
You can test sub-agents individually:

```bash
# Test release validator
claude --prompt prompts/release_validator_prompt.md \
       --setting-sources user,project \
       --allowed-tools Skill,Read

# Test track validator
claude --prompt prompts/track_validator_prompt.md \
       --setting-sources user,project \
       --allowed-tools Skill,Read

# Test classical validator
claude --prompt prompts/classical_validator_prompt.md \
       --setting-sources user,project \
       --allowed-tools Skill,Read
```

## When to Use Which Architecture

### Use Sub-Agent Architecture When:
- Speed is important (parallel execution)
- Cost optimization matters
- You want clear separation of concerns
- You're validating multiple products in batch

### Use Single-Agent Architecture When:
- Simplicity is preferred
- You're doing one-off validations
- You need easier debugging of the full flow
- You don't need parallel execution

## Future Enhancements

1. **Caching**: Cache sub-agent results for incremental validation
2. **Streaming**: Stream sub-agent results as they complete
3. **Prioritization**: Run critical validators first
4. **Retry Logic**: Retry failed sub-agents automatically
5. **Metrics**: Track performance and cost per sub-agent