Claude-Code-Workflow/.claude/workflows/agent-orchestration-patterns.md

Agent Orchestration Patterns

Core Agent Coordination Features

• Gemini Context Analysis: MANDATORY context gathering before any agent execution
• Context-Driven Coordination: Agents work with comprehensive codebase understanding
• Dynamic Agent Selection: Choose agents based on discovered context and patterns
• Continuous Context Updates: Refine understanding throughout agent execution
• Cross-Agent Context Sharing: Maintain shared context state across all agents
• Pattern-Aware Execution: Leverage discovered patterns for optimal implementation
• Quality Gates: Each Agent validates input and ensures output standards
• Error Recovery: Graceful handling of Agent coordination failures

Workflow Implementation Patterns

Simple Workflow Pattern

Flow: Gemini Context Analysis → TodoWrite Creation → Context-Aware Implementation → Review

1. MANDATORY Gemini Context Analysis:
   - Analyze target files and immediate dependencies
   - Discover existing patterns and conventions
   - Identify utilities and libraries to use
   - Generate context package for agents

2. TodoWrite Creation (Context-informed):
   - "Execute Gemini context analysis"
   - "Implement solution following discovered patterns"
   - "Review against codebase standards" 
   - "Complete task with context validation"

3. Context-Aware Implementation:
   Task(code-developer): Implementation with Gemini context package
   Input: CONTEXT_PACKAGE, PATTERNS_DISCOVERED, CONVENTIONS_IDENTIFIED
   Output: SUMMARY, FILES_MODIFIED, TESTS, VERIFICATION
   
4. Context-Aware Review:
   Task(code-review-agent): Review with codebase standards context
   Input: CONTEXT_PACKAGE, IMPLEMENTATION_RESULTS
   Output: STATUS, SCORE, ISSUES, RECOMMENDATIONS

Resume Support: Load todos + full context state from checkpoint

Medium Workflow Pattern

Flow: Comprehensive Gemini Analysis → TodoWrite → Multi-Context Implementation → Review

1. MANDATORY Comprehensive Gemini Context Analysis:
   - Analyze feature area and related components
   - Discover cross-file patterns and architectural decisions
   - Identify integration points and dependencies
   - Generate comprehensive context packages for multiple agents

2. TodoWrite Creation (Context-driven, 5-7 todos):
   - "Execute comprehensive Gemini context analysis"
   - "Coordinate multi-agent implementation with shared context"
   - "Implement following discovered architectural patterns"
   - "Validate against existing system patterns", "Review", "Complete"

3. Multi-Context Implementation:
   Task(code-developer): Implementation with comprehensive context
   Input: CONTEXT_PACKAGES, ARCHITECTURAL_PATTERNS, INTEGRATION_POINTS
   Update context as new patterns discovered
   
4. Context-Aware Review:
   Task(code-review-agent): Comprehensive review with system context
   Input: FULL_CONTEXT_STATE, IMPLEMENTATION_RESULTS, PATTERN_COMPLIANCE
   Verify against discovered architectural patterns

Resume Support: Full context state + pattern discovery restoration

Complex Workflow Pattern

Flow: Deep Gemini Analysis → TodoWrite → Orchestrated Multi-Agent → Review → Iterate (max 2)

1. MANDATORY Deep Gemini Context Analysis:
   - System-wide architectural understanding
   - Deep pattern analysis across entire codebase
   - Integration complexity assessment
   - Multi-agent coordination requirements discovery
   - Risk pattern identification

2. TodoWrite Creation (Context-orchestrated, 7-10 todos):
   - "Execute deep system-wide Gemini analysis"
   - "Orchestrate multi-agent coordination with shared context"
   - "Implement with continuous context refinement"
   - "Validate against system architectural patterns", "Review", "Iterate", "Complete"

3. Orchestrated Multi-Agent Implementation:
   Multiple specialized agents with shared deep context
   Input: SYSTEM_CONTEXT, ARCHITECTURAL_PATTERNS, RISK_ASSESSMENT
   Continuous Gemini context updates throughout execution
   Cross-agent context synchronization
   
4. Deep Context Review & Iteration Loop (max 2 iterations):
   Task(code-review-agent): Production-ready review with full system context
   If CRITICAL_ISSUES found: Re-analyze context and coordinate fixes
   Continue until no critical issues or max iterations reached

Context Validation: Verify deep context analysis maintained throughout
Resume Support: Full context state + iteration tracking + cross-agent coordination

Workflow Characteristics by Pattern

Pattern	Context Analysis	Agent Coordination	Iteration Strategy
Complex	Deep system-wide Gemini analysis	Multi-agent orchestration with shared context	Multiple rounds with context refinement
Medium	Comprehensive multi-file analysis	Context-driven coordination	Single thorough pass with pattern validation
Simple	Focused file-level analysis	Direct context-aware execution	Quick context validation

Context-Driven Task Invocation Examples

# Gemini Context Analysis (Always First)
gemini "Analyze authentication patterns in codebase - identify existing implementations, 
        conventions, utilities, and integration patterns"

# Context-Aware Research Task  
Task(subagent_type="general-purpose", 
     prompt="Research authentication patterns in codebase",
     context="[GEMINI_CONTEXT_PACKAGE]")

# Context-Informed Implementation Task
Task(subagent_type="code-developer", 
     prompt="Implement email validation function following discovered patterns",
     context="PATTERNS: [pattern_list], UTILITIES: [util_list], CONVENTIONS: [conv_list]")

# Context-Driven Review Task
Task(subagent_type="code-review-agent",
     prompt="Review authentication service against codebase standards and patterns",
     context="STANDARDS: [discovered_standards], PATTERNS: [existing_patterns]")

# Cross-Agent Context Sharing
Task(subagent_type="code-developer",
     prompt="Coordinate with previous agent results using shared context",
     context="PREVIOUS_CONTEXT: [agent_context], SHARED_STATE: [context_state]")

Gemini Context Integration Points

Pre-Agent Context Gathering

# Always execute before agent coordination
gemini "Comprehensive analysis for [task] - discover patterns, conventions, and optimal approach"

During-Agent Context Updates

# Continuous context refinement
gemini "Update context understanding based on agent discoveries in [area]"

Cross-Agent Context Synchronization

# Ensure context consistency across agents
gemini "Synchronize context between [agent1] and [agent2] work on [feature]"