feat: Integrate ResponseEnhancer for ALL tools to provide contextual guidance and parallel execution instructions #49
Description
Problem Statement
The ResponseEnhancer class exists in the codebase but is NOT integrated into the response flow. This means that ALL MCP tools are missing valuable contextual guidance, next steps, and parallel execution instructions that would significantly improve the user experience and workflow completion rates.
Current Behavior
- ResponseEnhancer exists but is not wired up in
src/index.ts - No tools provide guidance despite the enhancer being fully implemented
- Parallel execution patterns are not communicated to users
- Workflow gaps exist between tool invocations
When ANY tool is called, users get raw responses without:
- Next step instructions
- Contextual reminders
- Actionable commands
- Parallel execution guidance
- Compliance tracking
Expected Behavior
ALL tools should return enhanced responses with contextual guidance:
Example: create_task Enhancement
{
"success": true,
"taskCreated": true,
"taskId": "2025-09-13T20-31-29-test-workflow",
"guidance": {
"next_steps": "Invoke the Task tool to execute this agent",
"actionable_command": "Task(description=\"Frontend Dashboard\", prompt=\"Check MCP task: 2025-09-13T20-31-29-test-workflow\", subagent_type=\"senior-frontend-engineer\")",
"contextual_reminder": "📋 2-Phase Delegation: ✅ Task Created → ❗ NEXT: Start Subagent",
"compliance_level": 0.85
}
}Example: check_tasks Enhancement
{
"tasks": [...],
"guidance": {
"next_steps": "Start working on pending tasks using get_task_context",
"contextual_reminder": "You have 3 pending tasks. Use TodoWrite to track progress",
"parallel_execution": {
"available": true,
"agents": ["frontend", "backend", "qa"],
"instruction": "Send single message with multiple Task invocations for parallel execution"
}
}
}Example: submit_plan Enhancement
{
"success": true,
"stepsIdentified": 11,
"guidance": {
"next_steps": "Begin implementation and sync with TodoWrite",
"contextual_reminder": "Use report_progress after each step completion",
"todo_sync_reminder": "Remember to sync TodoWrite updates with sync_todo_checkboxes"
}
}Example: mark_complete Enhancement
{
"success": true,
"status": "DONE",
"guidance": {
"next_steps": "Archive completed tasks and check for new assignments",
"contextual_reminder": "Task completed successfully. Consider archiving with archive_completed_tasks",
"parallel_tasks_available": ["task-123", "task-456"],
"delegation_complete": true
}
}Technical Discovery
The infrastructure is already built but not connected:
-
ResponseEnhancer class (
src/core/ResponseEnhancer.ts):- Lines 29-45: Default enhancers registered for key tools
- Lines 51-123: Main enhance() method with compliance tracking
- Lines 142-182: generateNextSteps() with tool-specific logic
- Lines 207-282: Tool-specific enhancement methods
-
DelegationTracker (
src/core/DelegationTracker.ts):- Tracks incomplete delegations
- Generates delegation reminders
- Provides Task tool invocation templates
-
ComplianceTracker (referenced but may need implementation):
- Tracks agent compliance levels
- Provides personalized guidance
Proposed Solution
1. Wire Up ResponseEnhancer in index.ts
// In tool handler
const rawResponse = await toolFunction(config, args);
const enhancedResponse = await responseEnhancer.enhance({
toolName,
toolResponse: rawResponse,
agent: extractAgent(args),
complianceTracker,
delegationTracker
});
return enhancedResponse;2. Enhance ALL Tools Systematically
- Task Management: create_task, check_tasks, get_task_context
- Workflow Tools: submit_plan, report_progress, mark_complete
- Archive Tools: archive_tasks, restore_tasks, archive_completed_tasks
- Diagnostic Tools: track_task_progress, get_full_lifecycle
- System Tools: list_agents, get_server_info, ping
- Sync Tools: sync_todo_checkboxes
3. Add Parallel Execution Detection
// In ResponseEnhancer
private async detectParallelOpportunities(agent: string): Promise<ParallelGuidance> {
const pendingTasks = await this.getPendingTasksAcrossAgents();
if (pendingTasks.length > 1) {
return {
available: true,
agents: pendingTasks.map(t => t.agent),
instruction: "Send single message with multiple Task invocations"
};
}
}4. Progressive Disclosure of Complexity
- Basic users: Simple next_steps guidance
- Intermediate users: Actionable commands and reminders
- Advanced users: Parallel execution patterns and optimization hints
Implementation Tasks
- Wire up ResponseEnhancer in src/index.ts for ALL tool responses
- Add response enhancement to all 17 MCP tools
- Implement parallel execution detection across agents
- Add ComplianceTracker if not already implemented
- Create comprehensive test suite for enhanced responses
- Update TypeScript types to include guidance fields
- Document enhancement patterns in PROTOCOL.md
- Add examples of enhanced responses to README.md
Benefits
- Workflow Completion: No gaps between tool invocations
- Parallel Execution: Clear instructions for running multiple agents
- Reduced Cognitive Load: Users don't need to remember next steps
- Better Compliance: Tracking and personalized guidance improves adherence
- Progressive Learning: Users learn the system through contextual hints
- Error Prevention: Proactive guidance prevents common mistakes
Test Cases
- All tools return guidance - Verify every tool includes guidance field
- Context-appropriate guidance - Each tool's guidance matches its purpose
- Parallel execution detection - Multiple pending tasks trigger parallel guidance
- Compliance tracking - Guidance adapts based on agent compliance history
- Delegation completion - Task tool invocation guidance after create_task
- Error scenarios - Even errors include helpful recovery guidance
- Performance - Enhancement doesn't significantly impact response time
Breaking Changes
None - The guidance field is additive and won't break existing integrations.
Performance Considerations
- Enhancement should add <10ms to response time
- Use caching for frequently accessed guidance
- Lazy load compliance data only when needed
References
- ResponseEnhancer:
src/core/ResponseEnhancer.ts(fully implemented, not integrated) - DelegationTracker:
src/core/DelegationTracker.ts - Guidance templates:
src/core/guidance-templates.ts - Delegation templates:
src/core/delegation-templates.ts
Priority
CRITICAL - The ResponseEnhancer is already built but sitting unused. This is like having a Ferrari in the garage with no keys. Integrating it would immediately improve the user experience for ALL tools with minimal implementation effort.
Estimated Effort
Small - Most of the work is already done. Just needs to be wired up in index.ts and tested.