Mixture of experts

Mixture of Experts (MoE)

Spawn multiple specialized experts in parallel, each analyzing from a unique angle. Aggregate their insights into a comprehensive, multi-dimensional answer.

Foundation: This skill builds on spawn-subagents for the underlying tmux/pi subagent mechanics. Read spawn-subagents for the core patterns before using MoE.

When to Use

• Architecture or design decisions
• Complex code reviews
• Security audits
• Performance optimization
• Debugging tricky issues
• Evaluating trade-offs

Expert Specializations

Core Experts

Expert	Focus	System Prompt
architect	Design patterns, coupling, cohesion, long-term maintainability	"You are a software architect. Focus on design patterns, separation of concerns, and long-term maintainability."
security	Vulnerabilities, injection risks, auth flaws, data exposure	"You are a security engineer. Focus on vulnerabilities, injection risks, authentication, and data exposure."
performance	Algorithmic complexity, resource usage, bottlenecks	"You are a performance engineer. Focus on time/space complexity, resource usage, and optimization opportunities."
maintainer	Readability, documentation, testing, onboarding cost	"You are a senior maintainer. Focus on code readability, documentation, testing coverage, and onboarding new developers."
minimalist	Simplicity, YAGNI, removing unnecessary complexity	"You are a minimalist engineer. Focus on simplifying, removing unnecessary code, and YAGNI violations."

Domain Experts

Expert	Focus
api-designer	REST/GraphQL conventions, versioning, backward compatibility
data-modeler	Schema design, normalization, query patterns, migrations
dx-specialist	Developer experience, tooling, error messages, debugging
ops-engineer	Deployment, monitoring, observability, rollback strategies

Scripts

This skill provides helper scripts in .agents/scripts/ for automating the MoE workflow:

Script	Purpose
moe-spawn.sh	Spawn expert agents in parallel
moe-wait.sh	Wait for all experts to complete
moe-aggregate.sh	Combine results and run aggregator
moe-cleanup.sh	Kill sessions and remove temp files
moe-code-review.sh	Complete code review workflow

Workflow

1. Define the Problem

Create a clear, specific prompt that all experts will analyze:

PROBLEM="Review the authentication flow in src/auth/ for issues and improvements"
TASK_ID=$(date +%s)

2. Spawn Experts in Parallel

Use moe-spawn.sh to spawn experts:

source .agents/scripts/moe-spawn.sh
spawn_moe_experts "architect security performance maintainer"

3. Wait for All Experts

Use moe-wait.sh to wait for completion:

source .agents/scripts/moe-wait.sh
wait_moe_experts "architect security performance maintainer"

4. Aggregate Results

Use moe-aggregate.sh to combine insights:

source .agents/scripts/moe-aggregate.sh
aggregate_moe_results "architect security performance maintainer"

5. Cleanup

Use moe-cleanup.sh to remove sessions and temp files:

source .agents/scripts/moe-cleanup.sh
cleanup_moe "architect security performance maintainer"

Complete Example: Code Review

Use the moe-code-review.sh script for a complete review workflow:

# Run MoE code review on a specific file
./.agents/scripts/moe-code-review.sh src/auth/login.ts

The script will:

1. Read the file content
2. Spawn architect, security, performance, and maintainer experts
3. Wait for all experts to complete
4. Synthesize results into actionable recommendations
5. Clean up sessions and temp files

Advanced: Weighted Aggregation

For weighted aggregation, modify the aggregator prompt in moe-aggregate.sh:

# Define weights
architect=3
security=3
performance=2
maintainer=2

# Build weighted prompt
WEIGHTED_PROMPT="Synthesize with these expert weights:\n"
for expert in $EXPERTS; do
  weight=$(eval echo \$$expert)
  WEIGHTED_PROMPT="$WEIGHTED_PROMPT\n- $expert (weight: $weight/10)"
done
WEIGHTED_PROMPT="$WEIGHTED_PROMPT\n\nHigher weight = more influence on final recommendation."

Best Practices

• Choose 3-5 experts — Too few misses angles, too many adds noise
• Make prompts specific — Generic prompts yield generic answers
• Include file content — Don't make experts hunt for context
• Define clear aggregation strategy — Consensus-based, weighted, or hierarchical
• Cache expert outputs — Save to files for inspection if aggregation fails
• Set timeouts — Kill hung experts after 5 minutes

Common Patterns

Scenario	Expert Mix
API Design	architect, api-designer, security, dx-specialist
Database Schema	data-modeler, performance, architect
Frontend Component	maintainer, minimalist, performance, dx-specialist
DevOps Pipeline	ops-engineer, security, maintainer
Full Feature	architect, security, performance, maintainer, minimalist

Limitations

• Expert outputs may conflict (aggregator must resolve)
• Token cost scales linearly with expert count
• No cross-expert communication during analysis
• Synthesis quality depends on aggregator prompt quality