gh-yaleh-meta-cc-claude/skills/subagent-prompt-construction/reference/patterns.md

Subagent Prompt Patterns

Core patterns for constructing Claude Code subagent prompts.

---

Pattern 1: Orchestration Agent

Use case: Coordinate multiple subagents for complex workflows

Structure:

orchestrate :: Task → Result
orchestrate(task) =
  plan = agent(planner, task.spec) →
  ∀stage ∈ plan.stages:
    result = agent(executor, stage) →
    validate(result) →
  aggregate(results)

Example: phase-planner-executor

• Coordinates project-planner and stage-executor
• Sequential stage execution with validation
• Error detection and recovery
• Progress tracking

When to use:

• Multi-step workflows requiring planning
• Need to coordinate 2+ specialized agents
• Sequential stages with dependencies
• Error handling between stages critical

Complexity: Moderate to Complex (60-150 lines)

---

Pattern 2: Analysis Agent

Use case: Analyze data via MCP tools and generate insights

Structure:

analyze :: Query → Report
analyze(query) =
  data = mcp::query_tool(query.params) →
  patterns = extract_patterns(data) →
  insights = generate_insights(patterns) →
  report(patterns, insights)

Example: error-analyzer (hypothetical)

• Query tool errors via MCP
• Categorize error patterns
• Suggest fixes
• Generate analysis report

When to use:

• Need to query session data
• Pattern extraction from data
• Insight generation from analysis
• Reporting on historical data

Complexity: Simple to Moderate (30-90 lines)

---

Pattern 3: Enhancement Agent

Use case: Apply skill guidelines to improve artifacts

Structure:

enhance :: Artifact → ImprovedArtifact
enhance(artifact) =
  guidelines = skill(domain-skill) →
  analysis = analyze(artifact, guidelines) →
  improvements = generate(analysis) →
  apply(improvements, artifact)

Example: code-refactorer (hypothetical)

• Load refactoring skill guidelines
• Analyze code against guidelines
• Generate improvement suggestions
• Apply or report improvements

When to use:

• Systematic artifact improvement
• Apply established skill patterns
• Need consistent quality standards
• Repeatable enhancement process

Complexity: Moderate (60-120 lines)

---

Pattern 4: Validation Agent

Use case: Validate artifacts against criteria

Structure:

validate :: Artifact → ValidationReport
validate(artifact) =
  criteria = load_criteria() →
  results = check_all(artifact, criteria) →
  report(passes, failures, warnings)

Example: quality-checker (hypothetical)

• Load quality criteria
• Check code standards, tests, coverage
• Generate pass/fail report
• Provide remediation suggestions

When to use:

• Pre-commit checks
• Quality gates
• Compliance validation
• Systematic artifact verification

Complexity: Simple to Moderate (30-90 lines)

---

Pattern Selection Guide

Need	Pattern	Complexity	Integration
Coordinate agents	Orchestration	High	2+ agents
Query & analyze data	Analysis	Medium	MCP tools
Improve artifacts	Enhancement	Medium	Skills
Check compliance	Validation	Low	Skills optional
Multi-step workflow	Orchestration	High	Agents + MCP
One-step analysis	Analysis	Low	MCP only

---

Common Anti-Patterns

❌ Flat Structure (No Decomposition)

# Bad - 100 lines of inline logic
λ(input) → output | step1 ∧ step2 ∧ ... ∧ step50

Fix: Decompose into 5-10 functions

❌ Verbose Natural Language

# Bad
"First, we need to validate the input. Then, we should..."

Fix: Use symbolic logic and function composition

❌ Missing Dependencies

# Bad - calls agents without declaring
agent(mystery-agent, ...) → result

Fix: Explicit dependencies section

❌ Unclear Constraints

# Bad - vague requirements
"Make sure code quality is good"

Fix: Explicit predicates (coverage ≥ 0.80)

---

Pattern Composition

Patterns can be composed for complex workflows:

Orchestration + Analysis:

orchestrate(task) =
  plan = agent(planner, task) →
  ∀stage ∈ plan.stages:
    result = agent(executor, stage) →
    if result.status == "error" then
      analysis = analyze_errors(result) → # Analysis pattern
      return (partial_results, analysis)
  aggregate(results)

Enhancement + Validation:

enhance(artifact) =
  improved = apply_skill(artifact) →
  validation = validate(improved) → # Validation pattern
  if validation.passes then improved else retry(validation.issues)

---

Quality Metrics

Compactness

• Simple: ≤60 lines (score ≥0.60)
• Moderate: ≤90 lines (score ≥0.40)
• Complex: ≤150 lines (score ≥0.00)

Formula: 1 - (lines / 150)

Integration

• High: 3+ features (score ≥0.75)
• Moderate: 2 features (score ≥0.50)
• Low: 1 feature (score ≥0.25)

Formula: features_used / applicable_features

Clarity

• Clear structure (0-1 subjective)
• Obvious flow (0-1 subjective)
• Self-documenting (0-1 subjective)

Target: All ≥0.80

---

Validation Checklist

Before using a pattern:

• Pattern matches use case
• Complexity appropriate (simple/moderate/complex)
• Dependencies identified
• Function count: 3-12
• Line count: ≤150
• Integration score: ≥0.50
• Constraints explicit
• Example reviewed

---

Related Resources

• Integration Patterns: integration-patterns.md (agent/MCP/skill syntax)
• Symbolic Language: symbolic-language.md (operators, quantifiers)
• Template: ../templates/subagent-template.md (reusable structure)
• Examples: ../examples/phase-planner-executor.md (orchestration)
• Case Studies: case-studies/phase-planner-executor-analysis.md (detailed)