Persona-Based Sub-Agent Orchestration

Orchestrate sub-agents with specialized personas to work on tasks in parallel: $ARGUMENTS

Parse arguments:

• Feature name or task file path
• --strategy=feature|security|performance|data|full (default: auto)
• --agents=auto|2-8 (default: auto-detect based on tasks)
• --personas=frontend,backend,security (override auto-selection)

Persona-Based Sub-Agent Orchestration

1. Load Available Personas

Read from: .claude/personas/agent-personas.json

Available personas:

• frontend: UI/UX specialist with design system expertise
• backend: Server architect with API and database skills
• security: Security analyst for compliance and protection
• qa: Quality engineer for comprehensive testing
• architect: System designer for architecture decisions
• performance: Optimization expert for speed improvements
• integrator: Integration specialist for connecting systems
• data: Database engineer for schema and migrations

2. Analyze Tasks and Match Personas

function matchPersonaToTask(task: Task): Persona {
  // Keywords to persona mapping
  const patterns = {
    frontend: /component|ui|form|button|layout|style|responsive/i,
    backend: /api|endpoint|database|server|auth|middleware/i,
    security: /encrypt|pii|audit|compliance|hipaa|gdpr/i,
    qa: /test|spec|e2e|unit|coverage|regression/i,
    data: /migration|schema|table|index|query/i,
    performance: /optimize|cache|speed|bundle|lazy/i,
    integrator: /webhook|external|third-party|sync/i,
    architect: /design|pattern|structure|architecture/i
  };
  
  // Match task description to best persona
  return findBestMatch(task.description, patterns);
}

3. Coordination Protocol

Handoff Points

• Backend completes API → Frontend can start integration
• Frontend completes form → Test agent can write tests
• All agents complete → Integration agent validates

Communication

• Shared checkpoint file for progress
• Clear interfaces between components
• Status updates after each task

4. Implementation

// .claude/orchestration/task-assignments.json
{
  "session_id": "orch_123456",
  "feature": "user-authentication",
  "agents": {
    "frontend": {
      "id": "agent_fe_001",
      "tasks": ["2.1", "2.2", "2.3"],
      "status": "working",
      "current_task": "2.1",
      "completed": [],
      "context": {
        "focus": "UI components",
        "dependencies": ["1.3", "1.4"],
        "output_contracts": {
          "LoginForm": "components/auth/LoginForm.tsx",
          "RegisterForm": "components/auth/RegisterForm.tsx"
        }
      }
    },
    "backend": {
      "id": "agent_be_001",
      "tasks": ["1.1", "1.2", "1.3", "1.4"],
      "status": "working",
      "current_task": "1.2",
      "completed": ["1.1"],
      "context": {
        "focus": "API and database",
        "dependencies": [],
        "output_contracts": {
          "auth_routes": "app/api/auth/*/route.ts",
          "user_schema": "lib/db/schemas/user.ts"
        }
      }
    }
  }
}

5. Sub-Agent Instructions

Each sub-agent receives:

## You are BACKEND_AGENT for feature: user-authentication

### Your Tasks:
1.1 [✓] Create user database schema
1.2 [ ] Set up auth API routes
1.3 [ ] Implement JWT tokens
1.4 [ ] Add rate limiting

### Your Context:
- Focus: API and database only
- Do NOT work on UI components
- Output locations:
  - API routes: app/api/auth/*/route.ts
  - Schemas: lib/db/schemas/*.ts
  - Utils: lib/auth/*.ts

### Dependencies:
- None (you're first in the chain)

### Handoff Contract:
When you complete tasks 1.3 and 1.4, notify FRONTEND_AGENT with:
- API endpoint URLs
- Request/response formats
- Auth header requirements

### Communication:
- Update .claude/orchestration/progress/backend.json after each task
- Check .claude/orchestration/messages.json for updates
- Signal completion with: /agent-complete backend

6. Progress Tracking

Real-time dashboard:

=== SUB-AGENT STATUS ===
Feature: user-authentication

BACKEND_AGENT    [██████░░░░] 60%  - Working on: JWT implementation
FRONTEND_AGENT   [██░░░░░░░░] 20%  - Waiting for: API endpoints
SECURITY_AGENT   [░░░░░░░░░░] 0%   - Waiting for: Components
TEST_AGENT       [░░░░░░░░░░] 0%   - Waiting for: All implementation

Messages:
- [BACKEND → FRONTEND]: Auth endpoints ready at /api/auth/login
- [FRONTEND → TEST]: LoginForm component ready for testing

Next Handoff: 1.3 completion unlocks frontend tasks

7. Conflict Prevention

Each agent has exclusive file ownership:

{
  "file_ownership": {
    "components/auth/*": "frontend",
    "app/api/auth/*": "backend",
    "lib/db/*": "backend",
    "lib/security/*": "security",
    "tests/*": "test"
  }
}

8. Smart Orchestration Mode

Automatically determines:

• Number of agents needed (2-5)
• Task dependencies and optimal order
• Handoff points between agents
• File ownership boundaries

9. Checkpoint Integration

Sub-agents automatically:

• Save progress every 2 tasks
• Create handoff documentation
• Update the main context file
• Leave breadcrumbs for debugging

10. Benefits

• 3-5x faster for multi-aspect features
• Better quality through specialization
• Clear boundaries prevent conflicts
• Natural documentation from handoffs
• Easy debugging with clear ownership

Example Usage:

# Start orchestration for a feature
/orchestrate auth --agents=3

# This creates:
# - 3 specialized sub-agents
# - Task assignments based on type
# - Coordination protocol
# - Progress tracking
# - Automatic handoffs

Sub-Agent Lifecycle:

1. Spawn: Main agent creates sub-agents with specific contexts
2. Assign: Tasks distributed based on expertise
3. Execute: Each agent works independently
4. Communicate: Updates via shared state
5. Handoff: Clear contracts between agents
6. Merge: Results combined by orchestrator
7. Complete: Main agent validates and closes