kiro-agent-team 1.0.0

package/.kiro/guides/agent-coordination.md

@@ -0,0 +1,434 @@
+# Agent Coordination
+
+## 🎭 **Mastering Multi-Agent Collaboration**
+
+Effective agent coordination is the key to systematic development success. This guide covers patterns, protocols, and best practices for orchestrating our 9-agent team to work together seamlessly.
+
+## 🎯 **Coordination Principles**
+
+### **1. Single Point of Coordination**
+**Project Manager** serves as the central coordinator for all multi-agent activities.
+
+**Why This Works:**
+- Eliminates conflicting instructions
+- Ensures consistent project vision
+- Provides clear escalation path
+- Maintains comprehensive project state
+
+### **2. Clear Handoff Protocols**
+Each agent has defined input/output specifications and handoff procedures.
+
+**Standard Handoff Pattern:**
+```
+Agent A completes task → Documents results → Notifies Project Manager → 
+Project Manager validates completion → Assigns next agent → Agent B begins
+```
+
+### **3. Shared Context Management**
+All agents work from the same project understanding established by `@prime`.
+
+### **4. Quality Gate Enforcement**
+No work proceeds to the next stage without passing defined quality checkpoints.
+
+## 🔄 **Coordination Patterns**
+
+### **Pattern 1: Sequential Handoff**
+
+**When to Use:**
+- Complex features with clear dependencies
+- When each stage builds on the previous
+- Quality-critical implementations
+
+**Example: Authentication System**
+```
+1. Project Manager: @plan-feature "Authentication"
+   ↓ (Plan complete, tasks assigned)
+   
+2. Database Specialist: @execute
+   ↓ (Schema ready, handoff to backend)
+   
+3. Backend Engineer: @execute  
+   ↓ (API ready, handoff to frontend)
+   
+4. Frontend Architect: @execute
+   ↓ (UI ready, handoff to testing)
+   
+5. Test Orchestrator: @code-review
+   ↓ (Quality approved, ready for deployment)
+```
+
+**Coordination Commands:**
+```bash
+# Project Manager initiates
+@prime
+@plan-feature "Authentication System"
+
+# Each agent executes in sequence
+# Database Specialist
+@execute
+# Notify: "Database schema complete, ready for backend integration"
+
+# Backend Engineer  
+@execute
+# Notify: "API endpoints complete, ready for frontend integration"
+
+# Frontend Architect
+@execute  
+# Notify: "UI components complete, ready for testing"
+
+# Test Orchestrator
+@code-review
+# Final validation and approval
+```
+
+### **Pattern 2: Parallel Development**
+
+**When to Use:**
+- Independent components that can be developed simultaneously
+- Time-critical projects requiring speed
+- When agents have different expertise areas that don't overlap
+
+**Example: Dashboard Feature**
+```
+Project Manager: @plan-feature "Analytics Dashboard"
+    ↓ (Parallel task assignment)
+    
+├── Backend Engineer: API endpoints
+├── Frontend Architect: UI components  
+├── Database Specialist: Analytics queries
+└── UI/UX Designer: Dashboard layout
+
+    ↓ (All complete, integration phase)
+    
+Test Orchestrator: @code-review (integrated system)
+```
+
+**Coordination Commands:**
+```bash
+# Project Manager initiates parallel work
+@prime
+@plan-feature "Analytics Dashboard"
+
+# Parallel execution (simultaneous)
+# Backend Engineer
+@execute
+# Frontend Architect  
+@execute
+# Database Specialist
+@execute
+# UI/UX Designer
+@execute
+
+# Integration checkpoint
+# Project Manager coordinates integration
+"All components ready, begin integration testing"
+
+# Final validation
+@code-review
+```
+
+### **Pattern 3: Iterative Collaboration**
+
+**When to Use:**
+- Experimental features requiring refinement
+- Complex problems needing multiple perspectives
+- When requirements evolve during development
+
+**Example: AI Feature Integration**
+```
+Iteration 1: Plan → Implement → Review → Refine Requirements
+Iteration 2: Adjust Plan → Re-implement → Review → Further Refinement  
+Iteration 3: Final Implementation → Comprehensive Review → Deploy
+```
+
+**Coordination Commands:**
+```bash
+# Iteration 1
+@prime
+@plan-feature "AI Integration (MVP)"
+@execute (assigned agents)
+@code-review
+@system-review [plan] [results]
+
+# Iteration 2 (based on learnings)
+@plan-feature "AI Integration (Enhanced)"
+@execute (refined implementation)
+@code-review
+
+# Iteration 3 (final)
+@execution-report
+@code-review-hackathon (comprehensive evaluation)
+```
+
+### **Pattern 4: Emergency Response Coordination**
+
+**When to Use:**
+- Critical production issues
+- Security incidents
+- Time-sensitive bug fixes
+
+**Example: Security Vulnerability Response**
+```
+1. Security Specialist: @rca [issue-id] (immediate analysis)
+2. Security Specialist: @implement-fix [issue-id] (rapid fix)
+3. Test Orchestrator: @code-review (emergency validation)
+4. DevOps Engineer: Deploy with monitoring
+5. Development Logger: @system-review (post-incident analysis)
+```
+
+**Coordination Commands:**
+```bash
+# Emergency response (Security Specialist leads)
+@rca [critical-issue-id]
+# Immediate analysis and containment
+
+@implement-fix [critical-issue-id]  
+# Systematic fix implementation
+
+# Emergency quality validation
+@code-review
+# Rapid but thorough validation
+
+# Post-incident learning
+@system-review [rca-doc] [fix-report]
+# Process improvement for prevention
+```
+
+## 🎯 **Agent-Specific Coordination Roles**
+
+### **Project Manager (Central Coordinator)**
+**Primary Responsibilities:**
+- Initiates all workflows with `@prime`
+- Creates comprehensive plans with `@plan-feature`
+- Assigns tasks to appropriate agents
+- Monitors progress and resolves conflicts
+- Maintains project state in Archon
+
+**Coordination Commands:**
+```bash
+@prime                    # Establish shared context
+@plan-feature [name]      # Create coordination plan
+@create-prd [feature]     # Document requirements
+```
+
+**Communication Patterns:**
+- "Task assigned to [Agent]: [specific requirements]"
+- "Milestone reached: [status update and next steps]"
+- "Coordination needed: [conflict resolution or clarification]"
+
+### **Test Orchestrator (Quality Coordinator)**
+**Primary Responsibilities:**
+- Validates all implementations with `@code-review`
+- Documents results with `@execution-report`
+- Evaluates projects with `@code-review-hackathon`
+- Ensures quality gates are met
+
+**Coordination Commands:**
+```bash
+@code-review             # Quality validation
+@execution-report        # Implementation documentation
+@code-review-hackathon   # Comprehensive evaluation
+```
+
+**Communication Patterns:**
+- "Quality gate: [PASS/FAIL] - [specific feedback]"
+- "Ready for deployment: [validation results]"
+- "Quality concerns: [issues requiring attention]"
+
+### **Development Logger (Process Coordinator)**
+**Primary Responsibilities:**
+- Analyzes process effectiveness with `@system-review`
+- Captures lessons learned and improvements
+- Optimizes agent coordination patterns
+- Maintains development insights
+
+**Coordination Commands:**
+```bash
+@system-review [plan] [report]  # Process analysis
+```
+
+**Communication Patterns:**
+- "Process improvement identified: [specific recommendation]"
+- "Coordination pattern working well: [successful approach]"
+- "Workflow optimization: [efficiency enhancement]"
+
+### **Security Specialist (Incident Coordinator)**
+**Primary Responsibilities:**
+- Leads security incident response with `@rca`
+- Implements systematic fixes with `@implement-fix`
+- Coordinates security reviews and audits
+- Manages vulnerability response
+
+**Coordination Commands:**
+```bash
+@rca [issue-id]          # Root cause analysis
+@implement-fix [issue-id] # Systematic fix implementation
+```
+
+**Communication Patterns:**
+- "Security incident: [severity and immediate actions]"
+- "Fix implemented: [solution details and validation]"
+- "Security review: [assessment and recommendations]"
+
+## 🔧 **Coordination Tools and Techniques**
+
+### **Archon Integration**
+**Project State Management:**
+- All projects and tasks managed in Archon
+- Real-time progress tracking
+- Agent workload balancing
+- Knowledge base integration
+
+**Usage Patterns:**
+```bash
+# Project Manager creates project structure
+"Create project [name] with task breakdown"
+
+# Agents update progress
+"Task [id] completed by [agent] - [results summary]"
+
+# Progress tracking
+"Project status: [milestone progress and next steps]"
+```
+
+### **Context Sharing Protocols**
+**Shared Understanding:**
+- All agents work from `@prime` context
+- Regular context updates for long projects
+- Clear documentation of assumptions and decisions
+
+**Context Update Triggers:**
+- Major architecture changes
+- New requirements or constraints
+- Team composition changes
+- Technology stack updates
+
+### **Conflict Resolution Procedures**
+**When Agents Disagree:**
+1. **Escalate to Project Manager** for coordination
+2. **Consult relevant documentation** and project constraints
+3. **Seek additional expertise** if needed
+4. **Document decision rationale** for future reference
+
+**Common Conflict Scenarios:**
+- Architecture approach disagreements
+- Priority conflicts between features
+- Resource allocation disputes
+- Quality standard interpretations
+
+## 📊 **Coordination Success Metrics**
+
+### **Efficiency Metrics**
+- **Handoff Time**: Average time between agent transitions
+- **Rework Rate**: Percentage of tasks requiring revision
+- **Conflict Resolution Time**: Speed of resolving coordination issues
+- **Context Alignment**: Consistency of agent understanding
+
+### **Quality Metrics**
+- **First-Pass Success**: Percentage of work passing quality gates initially
+- **Integration Success**: Smooth combination of parallel work streams
+- **Communication Clarity**: Reduction in clarification requests
+- **Process Adherence**: Compliance with coordination protocols
+
+### **Collaboration Metrics**
+- **Agent Utilization**: Balanced workload across team
+- **Knowledge Sharing**: Cross-agent learning and improvement
+- **Process Evolution**: Continuous improvement in coordination patterns
+- **Team Satisfaction**: Agent and user satisfaction with collaboration
+
+## 🚨 **Common Coordination Challenges**
+
+### **Challenge 1: Context Drift**
+**Problem**: Agents working from different understanding of project state
+**Solution**: 
+- Regular `@prime` context updates
+- Clear documentation of changes
+- Explicit context validation at handoffs
+
+### **Challenge 2: Dependency Bottlenecks**
+**Problem**: Sequential work creating delays
+**Solution**:
+- Identify parallelizable work streams
+- Create mock interfaces for parallel development
+- Implement incremental integration checkpoints
+
+### **Challenge 3: Quality Gate Bypassing**
+**Problem**: Pressure to skip quality validation
+**Solution**:
+- Enforce mandatory quality gates
+- Educate on long-term costs of quality shortcuts
+- Implement automated quality checks where possible
+
+### **Challenge 4: Communication Overhead**
+**Problem**: Too much coordination reducing productivity
+**Solution**:
+- Standardize communication patterns
+- Use asynchronous updates where possible
+- Focus on essential coordination points only
+
+## 🎯 **Advanced Coordination Techniques**
+
+### **Dynamic Agent Assignment**
+**Adaptive Coordination:**
+- Assign agents based on current workload and expertise
+- Reassign tasks when priorities change
+- Cross-train agents for flexibility
+
+**Implementation:**
+```bash
+# Project Manager assesses current capacity
+"Analyze agent availability and expertise for [feature]"
+
+# Dynamic assignment based on context
+"Assign [task] to [best-available-agent] with [specific-requirements]"
+```
+
+### **Coordination Automation**
+**Automated Handoffs:**
+- Trigger next agent when previous completes
+- Automatic quality gate enforcement
+- Progress notifications and updates
+
+**Hook-Based Coordination:**
+```yaml
+# Example coordination hook
+- trigger: "task_completed"
+  action: "notify_next_agent"
+  message: "Previous task complete, ready for your phase"
+```
+
+### **Cross-Agent Learning**
+**Knowledge Sharing:**
+- Agents learn from each other's approaches
+- Best practices propagation across team
+- Continuous improvement in coordination patterns
+
+**Learning Integration:**
+```bash
+# Regular process review
+@system-review [coordination-patterns] [outcomes]
+
+# Apply learnings to improve coordination
+"Update coordination protocols based on [specific-insights]"
+```
+
+## 🎓 **Coordination Mastery Path**
+
+### **Beginner Coordination**
+- [ ] Understand basic handoff patterns
+- [ ] Can execute sequential workflows
+- [ ] Follows quality gate protocols
+
+### **Intermediate Coordination**
+- [ ] Manages parallel development streams
+- [ ] Resolves basic coordination conflicts
+- [ ] Adapts patterns to project needs
+
+### **Advanced Coordination**
+- [ ] Designs custom coordination patterns
+- [ ] Optimizes team efficiency continuously
+- [ ] Mentors others in coordination best practices
+
+---
+
+**Ready to ensure quality at every step? Check out [Quality Assurance](quality-assurance.md) for comprehensive testing and validation processes!**