cc-os/plugins/cc-architect/references/subagent-pattern.md

# Subagent Architecture Pattern

## Principle

Main thread orchestrates and communicates with user. Subagents handle detail work.

This keeps the main conversation focused. Context bloat in the main thread degrades response quality and loses important details.

## When to Dispatch Subagents

- Task involves reading/analyzing multiple files
- Work can be parallelized across independent concerns
- Detail work would bloat main thread context
- Task has clear, bounded scope a subagent can complete

## When NOT to Dispatch

- Simple, single-file operations
- Tasks requiring ongoing user dialogue
- Work that depends heavily on conversation context

## Model Selection

**Haiku:** Clear, mechanical, straightforward tasks
- File existence checks, YAML validation, pattern matching
- Tasks with unambiguous right/wrong answers
- Cleanup operations (removing temp files, archiving artifacts)

**Sonnet:** Moderate complexity, filtering, intermediate synthesis
- Filtering noise from Haiku research results
- Applying frameworks and patterns to gathered data
- Writing workflows, templates, documentation
- Intermediate decisions within established guidelines
- Pattern application (not pattern creation)

**Opus:** Judgment, analysis, higher-level thinking
- Quality assessments, trade-off evaluation
- Anything requiring interpretation of standards
- Pattern creation and architecture decisions
- Final synthesis and high-stakes decisions

**Default:** When uncertain, choose Opus
- Better to spend more on accuracy than fail cheaply

## Workflow Structure

**Maximum 2-3 subagents per workflow**
- More than 3 subagents indicates over-engineering
- Break complex work into phases, not more subagents
- Consider whether work truly needs delegation

## Phase Structure

Well-designed workflows follow a three-phase pattern:

**Phase 1: Setup + Research (Haiku)**
- Create necessary directories and scratch workspace
- Read files and gather data
- Pattern matching and data collection
- Output: Structured data files in scratch

**Phase 2: Processing (Sonnet)**
- Filter noise from Phase 1 results
- Apply frameworks and patterns to gathered data
- Make intermediate decisions within established guidelines
- Write drafts of workflows, templates, or documentation
- Output: Processed artifacts ready for review

**Phase 3: Synthesis + Cleanup (Opus + Haiku)**
- Opus: Final decisions, quality assessments, generate final output
- Haiku: Remove scratch files, archive temp artifacts
- Output: Final deliverables in correct locations

Not all workflows need all three phases. Simple workflows may only need Phase 1 + Phase 3.

## Single Responsibility

Each subagent should have one clear job:

| Good | Bad |
|------|-----|
| "Check frontmatter validity" | "Check frontmatter and also evaluate description quality and find patterns" |
| "Assess description trigger quality" | "Review the whole skill" |
| "Filter research findings to top 5 relevant items" | "Research everything and also decide what matters" |

## Cleanup Subagent Pattern

**When:** After workflow completion, when temp artifacts exist

**Model:** Haiku (mechanical operation)

**Tasks:**
- Remove scratch files and directories
- Archive temp artifacts if needed for audit trail
- Delete intermediate processing files
- Leave only final deliverables

**Example:**
```bash
# Haiku cleanup subagent prompt
rm -rf .claude/scratch/skill-audit-2025-02-09/
# OR if archiving needed
mv .claude/scratch/skill-audit-2025-02-09/ .claude/archive/
```

## Artifact Handoff

**Key principle:** Subagents write to files, not context.

Main thread should not read subagent outputs into context unless absolutely necessary for user communication. Instead:

1. Subagent writes findings to file in scratch workspace
2. Next subagent reads the file directly (file path passed in prompt)
3. Main thread only reads final deliverables for user summary

**Why:**
- Prevents context bloat in main thread
- Creates audit trail in scratch workspace
- Allows parallel subagent execution
- Enables cleanup without losing work

**Example flow:**
```
Main: Dispatch Haiku to gather data → writes scratch/data.json
Main: Dispatch Sonnet to filter → reads scratch/data.json, writes scratch/filtered.md
Main: Dispatch Opus to synthesize → reads scratch/filtered.md, writes final/output.md
Main: Read final/output.md to summarize for user
Main: Dispatch Haiku to cleanup → rm -rf scratch/
```

## Reporting Back

Subagents write findings to scratch workspace in structured format. Main thread assembles final output.

Example scratch structure:
```
scratch/
  structure-findings.md
  content-findings.md
  quality-findings.md
  patterns-findings.md
```

## Adoption for Other Plugins

**Migration steps for existing workflows:**

1. **Identify current subagent usage**
   - Count subagents per workflow
   - Classify by model tier
   - Map to phase structure

2. **Apply 2-3 subagent limit**
   - Consolidate over-dispatched workflows
   - Break complex workflows into phases
   - Consider whether delegation is needed

3. **Add Sonnet tier where appropriate**
   - Replace Opus for filtering/processing tasks
   - Use for documentation generation
   - Apply for pattern-following work

4. **Implement cleanup subagents**
   - Add Haiku cleanup at end of workflows
   - Remove scratch workspace after completion
   - Archive if audit trail needed

5. **Update artifact handoff**
   - Ensure subagents write to files
   - Pass file paths to next subagent
   - Keep main thread context minimal

6. **Document in workflow**
   - Mark phases clearly
   - Note model selection rationale
   - Include cleanup step