feat: Universal orchestration guidance with parallel execution instructions #64
Description
Problem Statement
The Smart Response System fails to provide clear workflow guidance after task creation, causing Claude to:
- Not invoke agents after creating tasks
- Not understand parallel vs sequential execution
- Get confused by unnecessary task "type" distinctions
- Receive inconsistent guidance based on flawed pattern detection
Root Cause Analysis
- Missing Parallel Execution Instructions: Never explains that multiple Task() calls in ONE message execute in PARALLEL
- Vague Guidance: "Complete delegation" doesn't explain the workflow
- Type Confusion: taskType parameter adds complexity without value (unused in logic)
- Protocol Bloat: 160+ lines of PROTOCOL_CONTEXT embedded in every task (Issue feat: configurable protocol injection with independent task/plan templates #63)
- Pattern Detection Fallacy: Tries to be "smart" about batch detection when we should ALWAYS provide orchestration guidance
Proposed Solution: Universal Orchestration Template
Core Principle: EVERY create_task response gets the SAME comprehensive guidance that works for ALL patterns.
Universal Response After EVERY create_task:
{
"success": true,
"taskId": "task-id",
"guidance": {
"workflow": {
"step1": "✅ Task created and queued for processing",
"step2": "Continue creating any additional tasks needed",
"step3": "When done creating tasks, launch agent(s) to process all work"
},
"orchestration": {
"pattern": "Agents discover their own tasks via check_tasks()",
"single_agent": "Task(subagent_type=\"agent-name\", prompt=\"...\")",
"multiple_agents_parallel": "Put all Task() calls in ONE message for parallel execution",
"multiple_agents_sequential": "Use separate messages for sequential execution"
},
"example_invocations": {
"single": "Task(\n subagent_type=\"senior-backend-engineer\",\n prompt=\"You have MCP tasks assigned.\\nStart: mcp__agent_comm__check_tasks(agent=\\\"senior-backend-engineer\\\")\\nThis discovers ALL your tasks. For each task:\\n1. Get context 2. Submit plan 3. Execute 4. Report progress 5. Mark complete\"\n)",
"parallel": "// For parallel execution, put ALL in ONE message:\nTask(subagent_type=\"frontend-engineer\", prompt=\"Check your MCP tasks...\")\nTask(subagent_type=\"backend-engineer\", prompt=\"Check your MCP tasks...\")\nTask(subagent_type=\"qa-engineer\", prompt=\"Check your MCP tasks...\")"
},
"critical_note": "⚡ PARALLEL EXECUTION: Multiple Task() calls in SAME message run simultaneously"
}
}Implementation Changes
1. Remove Task Types Completely:
- Delete
taskTypefrom CreateTaskOptions interface - Remove all type-related logic from create-task.ts
- Simplify response generation
2. Update ResponseEnhancer.ts:
private async enhanceCreateTask(context: EnhancementContext): Promise<EnhancedResponse['guidance']> {
return {
workflow: generateWorkflowSteps(),
orchestration: generateOrchestrationGuidance(),
example_invocations: generateExampleInvocations(context.agent),
critical_note: "⚡ PARALLEL EXECUTION: Multiple Task() calls in SAME message run simultaneously"
};
}3. Clean Task Content (Integrate with #63):
- Remove PROTOCOL_CONTEXT injection
- Use configurable templates per Issue feat: configurable protocol injection with independent task/plan templates #63
- Tasks contain ONLY requirements
4. New Orchestration Templates:
// src/core/orchestration-templates.ts
export function generateUniversalGuidance(agent: string): OrchestrationGuidance {
return {
discovery_workflow: `mcp__agent_comm__check_tasks(agent="${agent}")`,
execution_pattern: "Agent discovers and processes ALL tasks",
parallel_instruction: "Multiple Task() in ONE message = parallel",
sequential_instruction: "Separate messages = sequential"
};
}Files to Modify
src/tools/create-task.ts- Remove types, clean contentsrc/core/ResponseEnhancer.ts- Universal orchestration guidancesrc/types.ts- Remove taskType enumsrc/core/orchestration-templates.ts(new) - Orchestration patterns- Tests - Update for new patterns
Success Criteria
- Claude successfully invokes agents after task creation
- Parallel execution instructions clear and prominent
- Works for all patterns (1 task/1 agent, N tasks/1 agent, N tasks/M agents)
- No taskType parameter or logic
- Clean task content without protocol injection
- Tests pass with 95%+ coverage
Benefits
- Universal: Works for ALL task/agent patterns without detection
- Clear: Explicit parallel execution instructions
- Simple: No types, no smart detection, just orchestration
- Consistent: Same guidance every time reduces confusion
- Scalable: Works for 1 or 100 tasks/agents identically
Related Issues
- Integrates with feat: configurable protocol injection with independent task/plan templates #63 (Protocol Injection Configuration)
- Addresses feedback from HOWTO-CREATE-ISSUE-PLAN.md patterns
- Solves orchestration confusion identified in production usage
This elegant solution provides Claude with everything needed to successfully orchestrate agents, regardless of the pattern.