Role Routing Skill

Overview

This skill provides the Assistant Manager (EAMA) with decision logic for routing user requests to the appropriate specialist role:

Prerequisites

• •AI Maestro messaging system must be running
• •All specialist agents (EAA, EOA, EIA) must be registered
• •docs_dev/handoffs/ directory must exist and be writable
• •UUID generation capability required

Instructions

1. •Parse user message to identify primary intent
2. •Match intent to routing rule using the decision matrix
3. •If handling directly (status, approval, clarification), respond immediately
4. •If routing to specialist, create handoff document with UUID
5. •Save handoff to docs_dev/handoffs/
6. •Send via AI Maestro to target role
7. •Track handoff status and monitor for acknowledgment
8. •Report routing decision to user

• •EAA - Architect Agent
• •EOA - Orchestrator Agent
• •EIA - Integrator Agent

Output

Plugin Prefix Reference

Routing Decision Matrix

Detailed Routing Rules

Route to EAA (Architect) when:

1. •

   New project/feature design needed

   • •User says: "Design a...", "Plan how to...", "Create architecture for..."
   • •Action: Create handoff with requirements, route to eaa
2. •

   Requirements analysis required

   • •User says: "What do we need for...", "Analyze requirements for..."
   • •Action: Create handoff with context, route to eaa
3. •

   Technical specification needed

   • •User says: "Spec out...", "Document how...", "Define the API for..."
   • •Action: Create handoff, route to eaa
4. •

   Module planning required

   • •User says: "Break down...", "Modularize...", "Plan implementation of..."
   • •Action: Create handoff, route to eaa

Route to EOA (Orchestrator) when:

1. •

   Implementation ready to start

   • •Condition: Approved design/plan exists
   • •Action: Create handoff with design docs, route to eoa
2. •

   Task coordination needed

   • •User says: "Build...", "Implement...", "Start development..."
   • •Action: Create handoff with requirements, route to eoa
3. •

   Multi-agent work coordination

   • •Condition: Work requires multiple parallel agents
   • •Action: Create handoff with task breakdown, route to eoa
4. •

   Progress monitoring required

   • •Condition: Orchestration in progress, need intervention
   • •Action: Forward message to eoa

Route to EIA (Integrator) when:

1. •

   Work ready for integration

   • •Condition: Orchestrator signals completion
   • •Action: Create handoff with completion report, route to eia
2. •

   Code review requested

   • •User says: "Review...", "Check the PR...", "Evaluate changes..."
   • •Action: Create handoff with PR details, route to eia
3. •

   Quality gates needed

   • •User says: "Test...", "Validate...", "Run quality checks..."
   • •Action: Create handoff, route to eia
4. •

   Release preparation

   • •User says: "Prepare release...", "Merge...", "Deploy..."
   • •Action: Create handoff, route to eia

Route to ECOS (Chief of Staff) when:

1. •

   Agent lifecycle operations needed

   • •User says: "Spawn a new agent", "Create agent for...", "Start new session"
   • •Action: Create handoff with agent requirements, route to ecos
2. •

   Agent termination required

   • •User says: "Terminate agent", "Stop session", "Kill agent"
   • •Action: Create handoff with agent ID, route to ecos
3. •

   Session management needed

   • •User says: "Restart agent", "Check agent health", "Agent status"
   • •Action: Create handoff with session details, route to ecos
4. •

   Permission management required

   • •Condition: Sensitive operation requires elevated permissions
   • •Action: Create handoff with permission request, route to ecos
5. •

   Failure recovery needed

   • •Condition: Agent failure detected, escalation required
   • •Action: Create handoff with failure details, route to ecos
6. •

   Approval requests from ECOS

   • •Condition: ECOS requests user approval for agent operations
   • •Action: Present approval request to user, forward decision to ecos

Handle Directly (no routing):

1. •

   Status requests

   • •User says: "What's the status?", "How's progress?"
   • •Action: Query relevant role, compile report, present to user
2. •

   Approval decisions

   • •User says: "Yes, approve", "No, reject", "Proceed with..."
   • •Action: Record decision, forward to requesting role
3. •

   Clarification requests

   • •User says: "Explain...", "What does X mean?"
   • •Action: Answer directly or query relevant role
4. •

   Configuration/settings

   • •User says: "Set...", "Configure...", "Enable..."
   • •Action: Handle directly

Communication Hierarchy

USER <-> EAMA (Assistant Manager) <-> ECOS (Chief of Staff) <-> EAA (Architect)
                                                            <-> EOA (Orchestrator)
                                                            <-> EIA (Integrator)

CRITICAL:

• •EAMA is the ONLY role that communicates directly with the USER
• •ECOS manages agent lifecycle and sits between EAMA and specialist agents
• •EAA, EOA, and EIA do NOT communicate directly with each other or with EAMA
• •All specialist agent operations flow through ECOS

Handoff Protocol

Step 1: Identify Intent

Parse user message -> Identify primary intent -> Match to routing rule

Step 2: Validate Handoff (CRITICAL)

Before creating and sending any handoff, complete this validation checklist:

Handoff Validation Checklist

Before sending handoff to ECOS or specialists:

• • All required fields present - Verify handoff contains: from, to, type, UUID, task description
• • UUID is unique - Check against existing handoffs in docs_dev/handoffs/ to prevent collisions
  bash

  # Verify UUID uniqueness
  ! grep -r "UUID: <new-uuid>" docs_dev/handoffs/ && echo "UUID is unique"
  

• • Target agent exists and is alive - Send health ping before handoff
  bash

  curl -s "$AIMAESTRO_API/api/messages?agent=<target-agent>&action=health"
  

• • File is valid markdown - No syntax errors, proper structure
• • File is readable by target agent - Verify file permissions and path accessibility
• • No [TBD] placeholders - All placeholder text must be replaced with actual values
  bash

  # Check for placeholder text
  ! grep -E "\[TBD\]|\[TODO\]|\[PLACEHOLDER\]|<fill-in>" handoff-file.md && echo "No placeholders found"
  

• • Task description is actionable - Contains clear success criteria
• • Dependencies documented - Any blocked-by or blocks relationships noted

Validation Failure Handling

If any validation check fails:

NEVER send an invalid handoff. An invalid handoff wastes agent resources and delays work.

Step 3: Create Handoff Document

Generate UUID -> Create handoff-{uuid}-eama-to-{role}.md -> Save to docs_dev/handoffs/

Step 4: Send via AI Maestro

Compose message -> Set appropriate priority -> Send to role session

Step 5: Track Handoff

Log handoff in state -> Set status to "pending" -> Monitor for acknowledgment

Step 6: Report to User

Confirm routing -> Provide tracking info -> Set expectation for response

File Naming Convention

handoff-{uuid}-{from}-to-{to}.md

Examples:
- handoff-a1b2c3d4-eama-to-eaa.md    # AM assigns to Architect
- handoff-e5f6g7h8-eaa-to-eama.md    # Architect reports to AM
- handoff-i9j0k1l2-eama-to-eoa.md    # AM assigns to Orchestrator
- handoff-m3n4o5p6-eoa-to-eama.md    # Orchestrator reports to AM
- handoff-q7r8s9t0-eama-to-eia.md    # AM assigns to Integrator

Storage Location

All handoff files are stored in: docs_dev/handoffs/

GitHub Operations Routing

Route to EIA (Integrator) for:

Route to EAA (Architect) for:

Route to EOA (Orchestrator) for:

Cross-reference: See the eama-github-routing SKILL for complete GitHub decision trees.

Design Document Routing

Handle Locally (EAMA):

Route to EAA (Architect) for:

Search Before Route Decision Tree

User mentions design/spec/architecture
          │
          ▼
    ┌─────────────────┐
    │ Does user give  │
    │ UUID or path?   │
    └────────┬────────┘
             │
     ┌───────┴───────┐
     │ YES           │ NO
     ▼               ▼
┌────────────┐  ┌─────────────────┐
│ Search by  │  │ Search by       │
│ UUID/path  │  │ keyword/context │
└─────┬──────┘  └────────┬────────┘
      │                  │
      ▼                  ▼
┌───────────────────────────────────┐
│   Design found?                   │
└────────────────┬──────────────────┘
         ┌───────┴───────┐
         │ YES           │ NO
         ▼               ▼
┌────────────────┐  ┌─────────────────┐
│ Include design │  │ Route to EAA to │
│ context in     │  │ create new      │
│ routing        │  │ design          │
└────────────────┘  └─────────────────┘

Module Orchestration Routing

Route to EOA (Orchestrator) for:

Orchestration Handoff Checklist

When routing to EOA, handoff MUST include:

1. •Design Reference: UUID of approved design
2. •Module List: Modules to implement (from design)
3. •Priority Order: Which modules first
4. •Dependencies: Inter-module dependencies
5. •Constraints: Time, resources, technical limits
6. •Success Criteria: What defines "done"

Checklist

Copy this checklist and track your progress:

• • Parse user message to identify primary intent
• • Match intent to routing rule using decision matrix
• • Determine if handling directly or routing to specialist
• • If routing: Generate UUID for handoff
• • If routing: Create handoff document with all required fields
• • If routing: Save handoff to docs_dev/handoffs/
• • If routing: Send AI Maestro message to target role
• • If routing: Track handoff status (set to "pending")
• • Report routing decision to user
• • Monitor for acknowledgment from target role
• • Update handoff status when acknowledged

Examples

Example 1: Routing a Design Request to EAA

# User says: "Design a user authentication system"

# EAMA identifies intent: "design" -> Route to EAA

# Creates handoff
## Handoff: handoff-a1b2c3d4-eama-to-eaa.md

**From**: EAMA (Assistant Manager)
**To**: EAA (Architect)
**Type**: task_assignment

### Request
Design a user authentication system

### Requirements
- Support OAuth2 and password-based auth
- Include role-based access control
- Must integrate with existing user database

### Expected Deliverable
- Design document in design/auth-system/DESIGN.md
- Module breakdown with dependencies

Example 2: Handling Status Request Directly

# User says: "What's the status of the project?"

# EAMA identifies intent: "status" -> Handle directly

# EAMA queries all roles, compiles report, presents to user
# No handoff created - direct response

Error Handling

Resources

• •Handoff Template in the shared folder
• •Message Templates in the shared folder
• •GitHub Routing SKILL (eama-github-routing)
• •Proactive Handoff Protocol in eama-shared skill references