Shrimp Task Manager

# MCP Task Manager Sub-Agents Implementation Specification ## Executive Summary This specification outlines the implementation of a **Sub-Agent System** for the MCP Task Manager, enabling intelligent task delegation to specialized agents based on task complexity, domain expertise, and workload distribution. The system leverages the existing architecture while adding orchestration capabilities for multi-agent collaboration. ## Table of Contents 1. [Current Architecture Analysis](#current-architecture-analysis) 2. [Sub-Agent System Design](#sub-agent-system-design) 3. [Implementation Phases](#implementation-phases) 4. [Technical Specifications](#technical-specifications) 5. [Integration Points](#integration-points) 6. [Security and Performance](#security-and-performance) 7. [Migration Strategy](#migration-strategy) --- ## 1. Current Architecture Analysis ### 1.1 Existing Strengths - **Modular Task Workflow**: Plan → Analyze → Reflect → Split → Execute → Verify - **Profile-based Multi-tenancy**: Each profile represents isolated task workspace - **Sophisticated Task Model**: Rich metadata with dependencies, complexity assessment, and execution context - **Template System**: Customizable prompts for different functions and languages - **History Management**: Complete audit trail with memory system - **Web-based Management**: React UI with real-time monitoring ### 1.2 Integration Points Identified - **Task Splitting (`splitTasks`)**: Natural delegation point based on complexity - **Profile System**: Can be extended to represent sub-agent capabilities - **Template Management**: Sub-agent specific prompt templates - **API Layer**: RESTful structure ready for sub-agent endpoints - **History System**: Can track sub-agent performance and handoffs --- ## 2. Sub-Agent System Design ### 2.1 Core Concepts #### Agent Types ```typescript interface SubAgent { id: string; // Unique identifier name: string; // Display name type: SubAgentType; // Specialization category capabilities: Capability[]; // What this agent can do status: AgentStatus; // IDLE | BUSY | OFFLINE | ERROR workload: number; // Current task count (0-100) performance: PerformanceMetrics; configuration: AgentConfig; } enum SubAgentType { FRONTEND = 'frontend', // React, UI/UX, styling BACKEND = 'backend', // APIs, databases, server logic DEVOPS = 'devops', // CI/CD, infrastructure, deployment FULLSTACK = 'fullstack', // General-purpose development RESEARCH = 'research', // Investigation, analysis, documentation TESTING = 'testing', // QA, testing strategies, automation ARCHITECTURE = 'architecture' // System design, patterns, optimization } interface Capability { domain: string; // e.g., 'react', 'nodejs', 'docker' proficiency: number; // 1-10 skill level lastUsed: Date; successRate: number; // Historical success percentage } ``` #### Task Delegation Rules ```typescript interface DelegationRule { id: string; name: string; condition: DelegationCondition; targetAgentType: SubAgentType; priority: number; // Higher number = higher priority enabled: boolean; } interface DelegationCondition { complexityThreshold?: TaskComplexityLevel; keywordMatches?: string[]; // Task description keywords fileTypePatterns?: string[]; // Related file extensions dependencyCount?: number; // Minimum dependencies estimatedHours?: number; // Time threshold } ``` ### 2.2 System Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ Master Coordinator │ │ - Task routing and delegation │ │ - Sub-agent lifecycle management │ │ - Load balancing and scheduling │ │ - Conflict resolution and coordination │ └─────────────────┬───────────────────────────────────────────┘ │ ┌─────────────┼─────────────┐ │ │ │ ┌───▼───┐ ┌───▼───┐ ┌───▼───┐ │Sub- │ │Sub- │ │Sub- │ │Agent │ │Agent │ │Agent │ │A │ │B │ │C │ └───────┘ └───────┘ └───────┘ ``` --- ## 3. Implementation Phases ### Phase 1: Foundation (4-6 weeks) **Objective**: Establish core sub-agent infrastructure #### 3.1 Sub-Agent Profile System **File**: `src/types/subagent.ts` ```typescript // New sub-agent type definitions interface SubAgentProfile extends Profile { agentType: SubAgentType; capabilities: Capability[]; delegationRules: DelegationRule[]; parentAgentId?: string; // For hierarchical agents maxConcurrentTasks: number; communicationProtocol: 'mcp' | 'http' | 'websocket'; healthCheckEndpoint?: string; } ``` #### 3.2 Master Coordinator Service **File**: `src/services/coordinator.ts` ```typescript class MasterCoordinator { private subAgents: Map<string, SubAgentProfile> = new Map(); private taskQueue: TaskQueue = new TaskQueue(); private delegationEngine: DelegationEngine; async registerSubAgent(agent: SubAgentProfile): Promise<void> async delegateTask(task: Task): Promise<DelegationResult> async monitorSubAgents(): Promise<AgentStatus[]> async handleTaskCompletion(taskId: string, result: TaskResult): Promise<void> async redistributeWorkload(): Promise<void> } ``` #### 3.3 Enhanced Task Model **File**: `src/types/task.ts` (extend existing) ```typescript interface Task { // ... existing fields assignedAgent?: string; // Sub-agent ID delegationHistory: DelegationEntry[]; subAgentMetadata?: { estimatedComplexity: number; requiredCapabilities: string[]; preferredAgentType: SubAgentType; escalationRules: EscalationRule[]; }; } interface DelegationEntry { timestamp: Date; fromAgent: string; toAgent: string; reason: string; status: 'PENDING' | 'ACCEPTED' | 'REJECTED' | 'COMPLETED'; } ``` ### Phase 2: Delegation Engine (3-4 weeks) **Objective**: Implement intelligent task routing #### 3.4 Delegation Algorithm **File**: `src/services/delegation-engine.ts` ```typescript class DelegationEngine { async evaluateTask(task: Task): Promise<DelegationRecommendation> { const complexity = await this.assessComplexity(task); const requiredCapabilities = await this.analyzeRequiredCapabilities(task); const availableAgents = await this.getAvailableAgents(); return this.selectOptimalAgent(complexity, requiredCapabilities, availableAgents); } private async assessComplexity(task: Task): Promise<ComplexityAssessment> { // Enhanced complexity analysis considering: // - File count and types in relatedFiles // - Dependency graph complexity // - Description length and technical keywords // - Historical completion times for similar tasks } private async analyzeRequiredCapabilities(task: Task): Promise<string[]> { // Extract capabilities from: // - File extensions (.jsx, .py, .dockerfile, etc.) // - Task description keywords // - Related project structure // - Template patterns used } } ``` #### 3.5 Sub-Agent Communication Protocol **File**: `src/protocols/subagent-protocol.ts` ```typescript interface SubAgentProtocol { // Task assignment assignTask(agentId: string, task: Task): Promise<TaskAssignmentResult>; // Status monitoring getAgentStatus(agentId: string): Promise<AgentStatus>; // Task updates onTaskProgress(callback: (update: TaskProgressUpdate) => void): void; // Health checks pingAgent(agentId: string): Promise<boolean>; } // MCP-based implementation class MCPSubAgentProtocol implements SubAgentProtocol { async assignTask(agentId: string, task: Task): Promise<TaskAssignmentResult> { // Use MCP tools to communicate with sub-agent return await this.mcpClient.callTool('execute_task', { taskId: task.id, agentId, context: this.buildExecutionContext(task) }); } } ``` ### Phase 3: UI Integration (2-3 weeks) **Objective**: Extend web interface for sub-agent management #### 3.6 Sub-Agent Dashboard **File**: `src/components/SubAgentDashboard.jsx` ```jsx function SubAgentDashboard() { const [subAgents, setSubAgents] = useState([]); const [taskAssignments, setTaskAssignments] = useState([]); return ( <div className="subagent-dashboard"> <SubAgentGrid agents={subAgents} /> <TaskDistributionChart assignments={taskAssignments} /> <PerformanceMetrics agents={subAgents} /> <DelegationRulesManager /> </div> ); } ``` #### 3.7 Enhanced Task View **File**: `src/components/TaskTable.jsx` (extend existing) ```jsx // Add columns: // - Assigned Agent // - Delegation Status // - Sub-Agent Performance // - Escalation Actions function TaskRow({ task }) { return ( <tr> {/* ... existing columns */} <td> <AgentAssignmentBadge agentId={task.assignedAgent} agentType={task.subAgentMetadata?.preferredAgentType} /> </td> <td> <DelegationStatusIndicator status={task.delegationHistory[0]?.status} /> </td> <td> <TaskActionsDropdown task={task} onReassign={() => handleReassignTask(task.id)} onEscalate={() => handleEscalateTask(task.id)} /> </td> </tr> ); } ``` ### Phase 4: Advanced Features (4-5 weeks) **Objective**: Add sophisticated orchestration capabilities #### 3.8 Workload Balancing **File**: `src/services/load-balancer.ts` ```typescript class LoadBalancer { async balanceWorkload(): Promise<void> { const agents = await this.coordinator.getActiveAgents(); const overloadedAgents = agents.filter(a => a.workload > 80); const underutilizedAgents = agents.filter(a => a.workload < 40); for (const overloaded of overloadedAgents) { const tasksToReassign = await this.selectTasksForReassignment(overloaded); for (const task of tasksToReassign) { const targetAgent = this.findOptimalTarget(task, underutilizedAgents); await this.coordinator.reassignTask(task.id, targetAgent.id); } } } } ``` #### 3.9 Performance Analytics **File**: `src/services/analytics.ts` ```typescript class SubAgentAnalytics { async generatePerformanceReport(timeframe: TimeRange): Promise<PerformanceReport> { return { agentUtilization: await this.calculateUtilization(timeframe), taskCompletionRates: await this.analyzeCompletionRates(timeframe), delegationEffectiveness: await this.assessDelegationSuccess(timeframe), bottleneckAnalysis: await this.identifyBottlenecks(timeframe), recommendations: await this.generateOptimizationRecommendations() }; } } ``` --- ## 4. Technical Specifications ### 4.1 Database Schema Extensions #### Sub-Agent Profiles Table ```sql CREATE TABLE sub_agent_profiles ( id VARCHAR(255) PRIMARY KEY, name VARCHAR(255) NOT NULL, agent_type ENUM('frontend', 'backend', 'devops', 'fullstack', 'research', 'testing', 'architecture'), capabilities JSON, status ENUM('IDLE', 'BUSY', 'OFFLINE', 'ERROR'), workload INT DEFAULT 0, max_concurrent_tasks INT DEFAULT 5, configuration JSON, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP ); ``` #### Task Assignments Table ```sql CREATE TABLE task_assignments ( id VARCHAR(255) PRIMARY KEY, task_id VARCHAR(255), assigned_agent_id VARCHAR(255), assigned_at TIMESTAMP, status ENUM('PENDING', 'ACTIVE', 'COMPLETED', 'FAILED', 'REASSIGNED'), delegation_reason TEXT, completion_time INT, -- milliseconds performance_score DECIMAL(3,2), FOREIGN KEY (assigned_agent_id) REFERENCES sub_agent_profiles(id) ); ``` ### 4.2 API Endpoints #### Sub-Agent Management ```typescript // GET /api/subagents // POST /api/subagents // PUT /api/subagents/:id // DELETE /api/subagents/:id // GET /api/subagents/:id/status // POST /api/subagents/:id/tasks/:taskId/assign // POST /api/subagents/:id/tasks/:taskId/reassign ``` #### Task Delegation ```typescript // POST /api/tasks/:id/delegate // GET /api/tasks/:id/delegation-history // POST /api/tasks/:id/escalate // GET /api/delegation/rules // POST /api/delegation/rules ``` #### Analytics and Monitoring ```typescript // GET /api/analytics/performance // GET /api/analytics/workload-distribution // GET /api/analytics/delegation-effectiveness // GET /api/monitoring/agent-health ``` ### 4.3 Configuration Schema #### Sub-Agent Configuration ```json { "subAgents": { "maxConcurrentAgents": 10, "defaultTaskTimeout": 3600000, "healthCheckInterval": 30000, "workloadRebalanceInterval": 300000, "escalationThresholds": { "taskAgeMinutes": 60, "failureCount": 3, "agentOfflineMinutes": 10 } }, "delegationRules": [ { "name": "Frontend Tasks", "condition": { "fileTypePatterns": ["*.jsx", "*.tsx", "*.css", "*.scss"], "keywordMatches": ["react", "component", "styling", "ui"] }, "targetAgentType": "frontend", "priority": 90 }, { "name": "Complex Backend Tasks", "condition": { "complexityThreshold": "HIGH", "fileTypePatterns": ["*.py", "*.js", "*.ts", "*.go"], "dependencyCount": 5 }, "targetAgentType": "backend", "priority": 85 } ] } ``` --- ## 5. Integration Points ### 5.1 Existing Function Modifications #### Enhanced `splitTasks` Function ```typescript // In src/tools/task/split-tasks.ts export async function splitTasks( globalAnalysisResult: string, tasksRaw: string, updateMode: UpdateMode = 'clearAllTasks' ): Promise<SplitTasksResult> { const tasks = await parseAndValidateTasks(tasksRaw); // NEW: Analyze delegation opportunities for (const task of tasks) { const delegationAnalysis = await analyzeDelegationPotential(task); task.subAgentMetadata = { estimatedComplexity: delegationAnalysis.complexity, requiredCapabilities: delegationAnalysis.capabilities, preferredAgentType: delegationAnalysis.recommendedAgentType, escalationRules: delegationAnalysis.escalationRules }; } // Rest of existing logic... } ``` #### Enhanced `executeTask` Function ```typescript // In src/tools/task/execute-task.ts export async function executeTask(taskId: string): Promise<ExecuteTaskResult> { const task = await getTaskById(taskId); // NEW: Check for sub-agent assignment if (task.subAgentMetadata?.preferredAgentType) { const coordinator = MasterCoordinator.getInstance(); const delegationResult = await coordinator.delegateTask(task); if (delegationResult.success) { return { message: `Task delegated to ${delegationResult.assignedAgent}`, delegated: true, assignedAgent: delegationResult.assignedAgent }; } // Fall back to local execution if delegation fails } // Existing execution logic... } ``` ### 5.2 Web UI Integration Points #### Profile Management Extension ```jsx // In src/App.jsx - extend profile creation function ProfileCreationDialog({ onSave }) { const [profileType, setProfileType] = useState('standard'); return ( <Modal> <ProfileTypeSelector value={profileType} onChange={setProfileType} options={[ { value: 'standard', label: 'Standard Profile' }, { value: 'subagent', label: 'Sub-Agent Profile' } ]} /> {profileType === 'subagent' && ( <SubAgentConfiguration onCapabilitiesChange={setCapabilities} onDelegationRulesChange={setDelegationRules} /> )} </Modal> ); } ``` #### Task Monitoring Enhancement ```jsx // In src/components/TaskTable.jsx function useTaskRealTimeUpdates(tasks) { useEffect(() => { const wsConnection = new WebSocket('ws://localhost:9998/ws/tasks'); wsConnection.onmessage = (event) => { const update = JSON.parse(event.data); if (update.type === 'TASK_DELEGATED') { updateTaskStatus(update.taskId, 'delegated', update.assignedAgent); } else if (update.type === 'AGENT_STATUS_CHANGED') { updateAgentStatus(update.agentId, update.status); } }; return () => wsConnection.close(); }, []); } ``` --- ## 6. Security and Performance ### 6.1 Security Considerations #### Authentication and Authorization ```typescript interface SubAgentAuthentication { apiKey: string; // Unique per sub-agent permissions: Permission[]; // Scoped capabilities ipWhitelist?: string[]; // Network restrictions rateLimits: RateLimit; // Request throttling } interface Permission { resource: string; // e.g., 'tasks', 'files', 'templates' actions: string[]; // e.g., ['read', 'write', 'execute'] conditions?: string[]; // Additional constraints } ``` #### Data Isolation - Sub-agents operate within sandboxed environments - Task data encrypted in transit using TLS 1.3 - Sensitive information (API keys, secrets) never shared with sub-agents - Audit logging for all sub-agent interactions ### 6.2 Performance Optimizations #### Caching Strategy ```typescript class SubAgentCache { private agentStatusCache = new Map<string, AgentStatus>(); private taskAssignmentCache = new Map<string, string>(); async getAgentStatus(agentId: string): Promise<AgentStatus> { const cached = this.agentStatusCache.get(agentId); if (cached && this.isCacheValid(cached.timestamp)) { return cached; } const fresh = await this.fetchAgentStatus(agentId); this.agentStatusCache.set(agentId, fresh); return fresh; } } ``` #### Connection Pooling ```typescript class SubAgentConnectionPool { private pools = new Map<string, ConnectionPool>(); async getConnection(agentId: string): Promise<Connection> { let pool = this.pools.get(agentId); if (!pool) { pool = new ConnectionPool({ maxConnections: 5, idleTimeout: 30000, healthCheckInterval: 10000 }); this.pools.set(agentId, pool); } return pool.acquire(); } } ``` --- ## 7. Migration Strategy ### 7.1 Backward Compatibility The sub-agent system is designed to be **completely backward compatible**: 1. **Existing Profiles**: Continue to work as single-agent profiles 2. **Task Format**: No breaking changes to existing task JSON structure 3. **API Endpoints**: All existing endpoints remain functional 4. **UI Components**: Existing views work with enhanced data ### 7.2 Phased Rollout #### Phase 1: Foundation (Weeks 1-6) - ✅ Sub-agent profile system - ✅ Basic delegation engine - ✅ Master coordinator service - ❌ No UI changes yet (runs in background) #### Phase 2: Core Features (Weeks 7-10) - ✅ Task delegation and routing - ✅ Sub-agent communication protocol - ✅ Basic monitoring dashboard - ⚠️ Opt-in beta testing with select users #### Phase 3: UI Integration (Weeks 11-13) - ✅ Full dashboard and management UI - ✅ Task assignment visualization - ✅ Performance analytics - ✅ Public beta release #### Phase 4: Advanced Features (Weeks 14-18) - ✅ Workload balancing - ✅ Advanced analytics - ✅ Auto-scaling capabilities - ✅ Production release ### 7.3 Testing Strategy #### Unit Testing ```typescript describe('DelegationEngine', () => { it('should select appropriate agent based on task complexity', async () => { const engine = new DelegationEngine(); const task = createMockTask({ complexity: 'HIGH', type: 'frontend' }); const recommendation = await engine.evaluateTask(task); expect(recommendation.agentType).toBe(SubAgentType.FRONTEND); expect(recommendation.confidence).toBeGreaterThan(0.8); }); }); ``` #### Integration Testing ```typescript describe('Sub-Agent Integration', () => { it('should handle complete task delegation workflow', async () => { const coordinator = new MasterCoordinator(); const task = await createTestTask(); const result = await coordinator.delegateTask(task); expect(result.success).toBe(true); // Verify task status updates const updatedTask = await getTaskById(task.id); expect(updatedTask.assignedAgent).toBeDefined(); expect(updatedTask.delegationHistory).toHaveLength(1); }); }); ``` #### Load Testing ```bash # Simulate 100 concurrent sub-agents with 1000 tasks npm run test:load -- --agents=100 --tasks=1000 --duration=300s ``` --- ## 8. Success Metrics ### 8.1 Key Performance Indicators 1. **Task Completion Time Reduction**: Target 40% improvement 2. **Agent Utilization**: Target 80% average utilization 3. **Delegation Accuracy**: Target 90% correct assignments 4. **System Reliability**: Target 99.9% uptime 5. **User Satisfaction**: Target 4.5/5 rating ### 8.2 Monitoring and Alerting ```typescript interface SystemMetrics { taskCompletionRate: number; // Tasks/hour averageDelegationTime: number; // Milliseconds agentHealthScore: number; // 0-100 errorRate: number; // Percentage resourceUtilization: number; // Percentage } // Alerting thresholds const ALERT_THRESHOLDS = { highErrorRate: 5, // > 5% errors lowUtilization: 30, // < 30% agent utilization slowDelegation: 5000, // > 5s delegation time agentOffline: 3 // > 3 agents offline }; ``` --- ## 9. Conclusion The Sub-Agent System represents a natural evolution of the MCP Task Manager, leveraging its existing strengths while adding sophisticated orchestration capabilities. The modular design ensures minimal disruption to existing workflows while providing powerful new capabilities for complex project management. ### 9.1 Benefits Summary - **Scalability**: Handle larger, more complex projects - **Specialization**: Leverage domain expertise for better results - **Efficiency**: Optimal resource utilization and workload distribution - **Reliability**: Fault tolerance through redundancy and failover - **Visibility**: Comprehensive monitoring and analytics ### 9.2 Implementation Readiness The MCP Task Manager's architecture is **exceptionally well-suited** for sub-agent integration: ✅ **Strong Foundation**: Modular workflow, rich task model, template system ✅ **Extensible Design**: Profile system, API structure, UI components ✅ **Proven Scalability**: File-based storage, memory management, real-time updates ✅ **Security Framework**: Authentication, validation, audit trails **Recommendation**: Proceed with implementation starting with Phase 1 (Foundation). The existing codebase provides excellent integration points and the architectural patterns support distributed agent coordination with minimal risk. --- *This specification serves as a comprehensive blueprint for implementing sub-agents in the MCP Task Manager. All proposed changes maintain backward compatibility while adding powerful new orchestration capabilities.*