496 lines
18 KiB
Markdown
496 lines
18 KiB
Markdown
# Collaboration Orchestrator
|
|
|
|
## Multi-Agent Task Coordination for Claude Code
|
|
|
|
The Collaboration Orchestrator enables sophisticated multi-persona workflows within Claude Code, allowing AI experts to work together seamlessly on complex development tasks.
|
|
|
|
### Collaboration Patterns for Claude Code
|
|
|
|
#### 1. Sequential Collaboration Pattern
|
|
```yaml
|
|
sequential_pattern:
|
|
description: "Personas work in sequence, each building on previous work"
|
|
use_cases:
|
|
- feature_development: "Analyst → PM → Architect → Developer → QA"
|
|
- security_review: "Security → Architect → Developer → QA"
|
|
- performance_optimization: "Architect → Developer → QA → Platform Engineer"
|
|
|
|
coordination_mechanism:
|
|
handoff_protocol:
|
|
- complete_current_work: "Finish assigned tasks"
|
|
- document_deliverables: "Create handoff documentation"
|
|
- notify_next_persona: "Send structured handoff message"
|
|
- validate_prerequisites: "Ensure next persona has what they need"
|
|
|
|
quality_gates:
|
|
- completion_criteria: "Clear definition of 'done'"
|
|
- validation_checks: "Automated and manual validations"
|
|
- approval_requirements: "Who needs to approve handoff"
|
|
- rollback_procedures: "What to do if issues found"
|
|
|
|
# Example: Sequential API Development
|
|
sequential_api_development:
|
|
phase_1_analysis:
|
|
persona: "analyst"
|
|
deliverables: ["requirements-analysis.md", "user-stories.md"]
|
|
claude_tools: ["WebSearch", "Read", "Write"]
|
|
completion_criteria:
|
|
- all_requirements_documented: true
|
|
- stakeholder_interviews_complete: true
|
|
- acceptance_criteria_defined: true
|
|
|
|
phase_2_design:
|
|
persona: "architect"
|
|
inputs: ["requirements-analysis.md", "user-stories.md"]
|
|
deliverables: ["api-design.md", "data-model.md", "integration-patterns.md"]
|
|
claude_tools: ["Read", "Write", "Edit", "MultiEdit"]
|
|
completion_criteria:
|
|
- api_endpoints_defined: true
|
|
- data_models_specified: true
|
|
- security_considerations_documented: true
|
|
|
|
phase_3_security_review:
|
|
persona: "security"
|
|
inputs: ["api-design.md", "data-model.md"]
|
|
deliverables: ["security-assessment.md", "threat-model.md"]
|
|
claude_tools: ["Read", "Grep", "WebFetch", "Write"]
|
|
completion_criteria:
|
|
- threat_model_complete: true
|
|
- security_controls_specified: true
|
|
- compliance_requirements_met: true
|
|
```
|
|
|
|
#### 2. Parallel Collaboration Pattern
|
|
```python
|
|
async def parallel_collaboration_pattern(task_definition):
|
|
"""
|
|
Coordinate multiple personas working simultaneously on related tasks
|
|
"""
|
|
# Define parallel work streams
|
|
work_streams = {
|
|
'frontend_development': {
|
|
'persona': 'frontend-dev',
|
|
'tasks': ['component-implementation', 'state-management', 'api-integration'],
|
|
'dependencies': ['api-spec', 'design-mockups'],
|
|
'deliverables': ['ui-components', 'integration-layer']
|
|
},
|
|
'backend_development': {
|
|
'persona': 'backend-dev',
|
|
'tasks': ['api-implementation', 'database-design', 'business-logic'],
|
|
'dependencies': ['api-spec', 'data-requirements'],
|
|
'deliverables': ['api-endpoints', 'data-access-layer']
|
|
},
|
|
'qa_preparation': {
|
|
'persona': 'qa',
|
|
'tasks': ['test-strategy', 'test-data-preparation', 'automation-setup'],
|
|
'dependencies': ['requirements', 'api-spec'],
|
|
'deliverables': ['test-plans', 'automated-tests']
|
|
},
|
|
'devops_setup': {
|
|
'persona': 'platform-engineer',
|
|
'tasks': ['ci-cd-pipeline', 'infrastructure-setup', 'monitoring'],
|
|
'dependencies': ['deployment-requirements'],
|
|
'deliverables': ['deployment-pipeline', 'infrastructure-code']
|
|
}
|
|
}
|
|
|
|
# Create shared workspace for coordination
|
|
shared_workspace = await create_shared_workspace(task_definition.project_id)
|
|
|
|
# Initialize parallel execution
|
|
parallel_tasks = []
|
|
for stream_id, stream_config in work_streams.items():
|
|
task = execute_work_stream(
|
|
stream_id,
|
|
stream_config,
|
|
shared_workspace,
|
|
task_definition.global_context
|
|
)
|
|
parallel_tasks.append(task)
|
|
|
|
# Monitor parallel execution with coordination
|
|
coordination_result = await coordinate_parallel_execution(
|
|
parallel_tasks,
|
|
shared_workspace
|
|
)
|
|
|
|
return coordination_result
|
|
|
|
async def coordinate_parallel_execution(parallel_tasks, shared_workspace):
|
|
"""
|
|
Coordinate parallel work streams with conflict resolution and synchronization
|
|
"""
|
|
coordination_state = {
|
|
'active_tasks': parallel_tasks,
|
|
'completed_tasks': [],
|
|
'blocked_tasks': [],
|
|
'conflicts': [],
|
|
'shared_resources': shared_workspace.resources
|
|
}
|
|
|
|
while coordination_state['active_tasks']:
|
|
# Check for task completions
|
|
completed = await check_task_completions(coordination_state['active_tasks'])
|
|
coordination_state['completed_tasks'].extend(completed)
|
|
coordination_state['active_tasks'] = [
|
|
task for task in coordination_state['active_tasks']
|
|
if task not in completed
|
|
]
|
|
|
|
# Detect and resolve conflicts
|
|
conflicts = await detect_resource_conflicts(coordination_state)
|
|
if conflicts:
|
|
resolution_results = await resolve_conflicts(conflicts, shared_workspace)
|
|
coordination_state['conflicts'].extend(resolution_results)
|
|
|
|
# Handle blocked tasks
|
|
blocked_tasks = await identify_blocked_tasks(coordination_state['active_tasks'])
|
|
if blocked_tasks:
|
|
unblock_results = await attempt_to_unblock_tasks(
|
|
blocked_tasks,
|
|
coordination_state
|
|
)
|
|
coordination_state['blocked_tasks'].extend(unblock_results)
|
|
|
|
# Synchronize shared state
|
|
await synchronize_shared_workspace(shared_workspace, coordination_state)
|
|
|
|
# Brief pause before next coordination cycle
|
|
await asyncio.sleep(1)
|
|
|
|
# Final integration of parallel work
|
|
integration_result = await integrate_parallel_outputs(
|
|
coordination_state['completed_tasks'],
|
|
shared_workspace
|
|
)
|
|
|
|
return {
|
|
'coordination_summary': coordination_state,
|
|
'integration_result': integration_result,
|
|
'final_deliverables': integration_result.consolidated_outputs
|
|
}
|
|
```
|
|
|
|
#### 3. Consultative Collaboration Pattern
|
|
```python
|
|
async def consultative_collaboration(primary_persona, consultation_needs):
|
|
"""
|
|
Enable primary persona to consult with experts as needed
|
|
"""
|
|
consultation_session = {
|
|
'session_id': generate_uuid(),
|
|
'primary_persona': primary_persona,
|
|
'consultation_requests': [],
|
|
'expert_responses': [],
|
|
'decisions_made': []
|
|
}
|
|
|
|
for consultation in consultation_needs:
|
|
# Prepare consultation request
|
|
consultation_request = {
|
|
'id': generate_uuid(),
|
|
'expert_needed': consultation['expert_domain'],
|
|
'question': consultation['question'],
|
|
'context': consultation['context'],
|
|
'urgency': consultation.get('urgency', 'normal'),
|
|
'claude_tools_available': consultation.get('tools', ['Read', 'Write', 'WebFetch'])
|
|
}
|
|
|
|
# Route to appropriate expert
|
|
expert_persona = select_expert_for_domain(consultation['expert_domain'])
|
|
|
|
# Execute consultation using Claude Code tools
|
|
expert_response = await execute_expert_consultation(
|
|
expert_persona,
|
|
consultation_request,
|
|
consultation_session
|
|
)
|
|
|
|
consultation_session['expert_responses'].append(expert_response)
|
|
|
|
# Apply expert recommendations
|
|
if expert_response.requires_action:
|
|
action_result = await apply_expert_recommendations(
|
|
expert_response,
|
|
primary_persona,
|
|
consultation_session
|
|
)
|
|
consultation_session['decisions_made'].append(action_result)
|
|
|
|
return consultation_session
|
|
|
|
async def execute_expert_consultation(expert_persona, consultation_request, session):
|
|
"""
|
|
Execute a single expert consultation using Claude Code capabilities
|
|
"""
|
|
# Prepare expert context
|
|
expert_context = await prepare_expert_context(
|
|
expert_persona,
|
|
consultation_request,
|
|
session['primary_persona']
|
|
)
|
|
|
|
# Execute consultation based on domain
|
|
if expert_persona == 'security':
|
|
consultation_result = await security_consultation(
|
|
consultation_request,
|
|
expert_context
|
|
)
|
|
elif expert_persona == 'architect':
|
|
consultation_result = await architecture_consultation(
|
|
consultation_request,
|
|
expert_context
|
|
)
|
|
elif expert_persona == 'qa':
|
|
consultation_result = await quality_consultation(
|
|
consultation_request,
|
|
expert_context
|
|
)
|
|
elif expert_persona == 'platform-engineer':
|
|
consultation_result = await infrastructure_consultation(
|
|
consultation_request,
|
|
expert_context
|
|
)
|
|
|
|
# Document consultation for future reference
|
|
await document_consultation(
|
|
consultation_request,
|
|
consultation_result,
|
|
session
|
|
)
|
|
|
|
return consultation_result
|
|
|
|
# Example: Security Consultation Implementation
|
|
async def security_consultation(consultation_request, expert_context):
|
|
"""
|
|
Security expert consultation using Claude Code tools
|
|
"""
|
|
# Analyze security implications using Grep and Read
|
|
if 'code_review' in consultation_request['context']:
|
|
code_files = consultation_request['context']['files']
|
|
|
|
# Use Grep to find security-relevant patterns
|
|
security_patterns = await grep_security_patterns(code_files)
|
|
|
|
# Use Read to analyze specific security concerns
|
|
detailed_analysis = await analyze_security_details(
|
|
code_files,
|
|
security_patterns
|
|
)
|
|
|
|
# Use WebFetch to check latest security advisories
|
|
latest_threats = await fetch_latest_security_advisories(
|
|
expert_context['technology_stack']
|
|
)
|
|
|
|
# Generate security recommendations
|
|
recommendations = generate_security_recommendations(
|
|
detailed_analysis,
|
|
latest_threats,
|
|
expert_context
|
|
)
|
|
|
|
# Create implementation guidance using Write tool
|
|
implementation_guide = await create_security_implementation_guide(
|
|
recommendations,
|
|
consultation_request['context']
|
|
)
|
|
|
|
return {
|
|
'expert': 'security',
|
|
'analysis': detailed_analysis,
|
|
'recommendations': recommendations,
|
|
'implementation_guide': implementation_guide,
|
|
'risk_assessment': assess_security_risks(detailed_analysis),
|
|
'requires_action': len(recommendations) > 0
|
|
}
|
|
```
|
|
|
|
### Collaboration Workspace Management
|
|
|
|
#### Shared Workspace for Claude Code
|
|
```yaml
|
|
shared_workspace:
|
|
workspace_structure:
|
|
shared_files:
|
|
- collaboration_notes.md: "Real-time collaboration notes"
|
|
- decision_log.md: "Decisions made during collaboration"
|
|
- artifact_registry.md: "Registry of all created artifacts"
|
|
- conflict_resolution_log.md: "Record of resolved conflicts"
|
|
|
|
persona_workspaces:
|
|
- architect/: "Architecture-specific working files"
|
|
- security/: "Security analysis and reports"
|
|
- qa/: "Test plans and quality assessments"
|
|
- dev/: "Implementation artifacts"
|
|
|
|
integration_area:
|
|
- final_deliverables/: "Consolidated outputs"
|
|
- review_materials/: "Items pending review"
|
|
- approved_artifacts/: "Finalized deliverables"
|
|
|
|
access_control:
|
|
read_permissions:
|
|
- all_personas: ["shared_files/*", "*/README.md"]
|
|
- persona_specific: ["own_workspace/*"]
|
|
- integration_access: ["integration_area/*"]
|
|
|
|
write_permissions:
|
|
- collaborative_files: ["collaboration_notes.md", "decision_log.md"]
|
|
- persona_workspaces: ["own_workspace/*"]
|
|
- controlled_integration: ["integration_area/*"] # requires approval
|
|
|
|
synchronization_rules:
|
|
real_time_sync:
|
|
- collaboration_notes.md: "immediate_sync"
|
|
- decision_log.md: "immediate_sync"
|
|
- conflict_resolution_log.md: "immediate_sync"
|
|
|
|
batch_sync:
|
|
- persona_workspaces: "every_5_minutes"
|
|
- integration_area: "on_explicit_request"
|
|
|
|
conflict_resolution:
|
|
- concurrent_edits: "merge_with_annotations"
|
|
- contradictory_decisions: "escalate_to_orchestrator"
|
|
- resource_conflicts: "priority_based_resolution"
|
|
```
|
|
|
|
### Conflict Detection and Resolution
|
|
|
|
#### Intelligent Conflict Management
|
|
```python
|
|
async def detect_and_resolve_collaboration_conflicts():
|
|
"""
|
|
Continuously monitor for collaboration conflicts and resolve them intelligently
|
|
"""
|
|
conflict_monitor = {
|
|
'file_conflicts': await monitor_concurrent_file_edits(),
|
|
'decision_conflicts': await monitor_contradictory_decisions(),
|
|
'resource_conflicts': await monitor_resource_contention(),
|
|
'timeline_conflicts': await monitor_schedule_conflicts()
|
|
}
|
|
|
|
detected_conflicts = []
|
|
|
|
# Check each conflict type
|
|
for conflict_type, monitor in conflict_monitor.items():
|
|
conflicts = await monitor.check_for_conflicts()
|
|
if conflicts:
|
|
detected_conflicts.extend([
|
|
{'type': conflict_type, 'details': conflict}
|
|
for conflict in conflicts
|
|
])
|
|
|
|
# Resolve conflicts using appropriate strategies
|
|
resolution_results = []
|
|
for conflict in detected_conflicts:
|
|
resolution_strategy = select_resolution_strategy(conflict)
|
|
resolution_result = await execute_resolution_strategy(
|
|
conflict,
|
|
resolution_strategy
|
|
)
|
|
resolution_results.append(resolution_result)
|
|
|
|
return {
|
|
'conflicts_detected': len(detected_conflicts),
|
|
'conflicts_resolved': len([r for r in resolution_results if r.success]),
|
|
'pending_conflicts': [r for r in resolution_results if not r.success],
|
|
'resolution_summary': resolution_results
|
|
}
|
|
|
|
async def execute_resolution_strategy(conflict, strategy):
|
|
"""
|
|
Execute specific conflict resolution strategy
|
|
"""
|
|
if strategy.type == 'expertise_hierarchy':
|
|
# Defer to domain expert
|
|
expert_decision = await consult_domain_expert(conflict, strategy.expert)
|
|
resolution = await apply_expert_decision(expert_decision, conflict)
|
|
|
|
elif strategy.type == 'collaborative_merge':
|
|
# Merge conflicting work collaboratively
|
|
merge_session = await initiate_collaborative_merge(conflict)
|
|
resolution = await execute_collaborative_merge(merge_session)
|
|
|
|
elif strategy.type == 'sequential_ordering':
|
|
# Order conflicting operations sequentially
|
|
operation_order = await determine_optimal_sequence(conflict)
|
|
resolution = await execute_sequential_operations(operation_order)
|
|
|
|
elif strategy.type == 'resource_sharing':
|
|
# Share contested resources
|
|
sharing_plan = await create_resource_sharing_plan(conflict)
|
|
resolution = await implement_resource_sharing(sharing_plan)
|
|
|
|
# Document resolution for learning
|
|
await document_conflict_resolution(conflict, strategy, resolution)
|
|
|
|
return resolution
|
|
```
|
|
|
|
### Performance Optimization for Collaboration
|
|
|
|
#### Efficient Multi-Persona Coordination
|
|
```yaml
|
|
performance_optimization:
|
|
parallel_processing:
|
|
independent_tasks:
|
|
- identify_dependencies: "Map task interdependencies"
|
|
- create_execution_graph: "Optimize execution order"
|
|
- maximize_parallelism: "Run independent tasks simultaneously"
|
|
|
|
resource_pooling:
|
|
- shared_tool_access: "Coordinate Claude Code tool usage"
|
|
- memory_sharing: "Share computed results between personas"
|
|
- cache_coordination: "Avoid duplicate computations"
|
|
|
|
communication_efficiency:
|
|
message_batching:
|
|
- group_related_messages: "Bundle related communications"
|
|
- compress_large_contexts: "Reduce context transfer overhead"
|
|
- prioritize_urgent_communications: "Fast-track critical messages"
|
|
|
|
smart_routing:
|
|
- direct_expertise_matching: "Route directly to best expert"
|
|
- avoid_unnecessary_routing: "Skip irrelevant personas"
|
|
- predictive_pre-positioning: "Anticipate consultation needs"
|
|
|
|
context_optimization:
|
|
incremental_updates:
|
|
- delta_synchronization: "Only sync changes, not full context"
|
|
- selective_distribution: "Send relevant context only"
|
|
- lazy_loading: "Load context on demand"
|
|
|
|
intelligent_caching:
|
|
- context_snapshots: "Cache frequently accessed contexts"
|
|
- prediction_caching: "Pre-cache likely needed contexts"
|
|
- adaptive_expiration: "Intelligent cache invalidation"
|
|
```
|
|
|
|
### Claude Code Integration Commands
|
|
|
|
```bash
|
|
# Collaboration initiation
|
|
bmad collaborate start --pattern "sequential" --participants "analyst,architect,dev"
|
|
bmad collaborate start --pattern "parallel" --workstreams "frontend,backend,qa"
|
|
bmad collaborate start --pattern "consultative" --primary "architect" --experts "security,qa"
|
|
|
|
# Workspace management
|
|
bmad workspace create --shared --participants "architect,security,qa"
|
|
bmad workspace sync --resolve-conflicts
|
|
bmad workspace status --show-conflicts
|
|
|
|
# Collaboration monitoring
|
|
bmad collaborate status --active-sessions
|
|
bmad collaborate conflicts --list --resolve
|
|
bmad collaborate handoff --from "architect" --to "dev" --validate
|
|
|
|
# Performance and optimization
|
|
bmad collaborate optimize --parallel-efficiency
|
|
bmad collaborate analyze --bottlenecks
|
|
bmad collaborate report --session "uuid" --detailed
|
|
```
|
|
|
|
This Collaboration Orchestrator transforms Claude Code into a sophisticated multi-agent workspace where AI personas can work together efficiently, handling complex development tasks that require multiple areas of expertise while maintaining coordination and resolving conflicts intelligently. |