15 KiB

Raw Blame History

Context Synchronizer

The Context Synchronizer maintains shared awareness across all BMAD personas within Claude Code, ensuring consistent understanding of project state, decisions, and development progress.

Context Structure for Claude Code

Comprehensive Project Context

project_context:
  metadata:
    project_id: "{uuid}"
    project_name: "{descriptive-name}"
    project_type: "web-app|api-service|mobile-app|library|cli-tool"
    tech_stack: ["typescript", "react", "nodejs", "mongodb"]
    phase: "discovery|design|implementation|testing|deployment"
    created_timestamp: "{iso-8601}"
    last_updated: "{iso-8601}"
    
  claude_code_state:
    active_session: "{session-id}"
    workspace_path: "{absolute-path}"
    open_files: ["{file-paths}"]
    recent_tools_used: [
      {
        "tool": "Read",
        "target": "src/components/Auth.tsx",
        "timestamp": "{iso-8601}"
      }
    ]
    current_todos: [
      {
        "id": "todo-123",
        "content": "Implement user authentication",
        "status": "in_progress",
        "assigned_persona": "security"
      }
    ]
    git_context:
      current_branch: "feature/auth-implementation"
      uncommitted_changes: ["src/auth/", "tests/auth/"]
      last_commit: "abc123: Add user login component"
    
  decisions:
    - id: "{uuid}"
      timestamp: "{iso-8601}"
      decision: "Use JWT for authentication"
      made_by: "security"
      rationale: "Stateless, scalable, industry standard"
      impact: ["api-design", "frontend-auth", "security-model"]
      supporting_personas: ["architect", "dev"]
      
  artifacts:
    - id: "{uuid}"
      type: "architecture-document"
      path: "docs/system-architecture.md"
      version: "v1.2"
      last_modified_by: "architect"
      last_modified: "{iso-8601}"
      status: "approved"
      reviewers: ["security", "qa", "pm"]
      
  active_tasks:
    - id: "{uuid}"
      description: "Implement OAuth2 integration"
      assigned_to: ["security", "dev"]
      status: "in_progress"
      dependencies: ["user-model-design"]
      estimated_effort: "8 hours"
      actual_effort: "6 hours"
      blockers: []
      
  knowledge_state:
    learned_patterns: [
      {
        "pattern": "secure-api-authentication",
        "confidence": 0.95,
        "applications": 3,
        "success_rate": 1.0
      }
    ]
    avoided_anti_patterns: [
      {
        "anti_pattern": "password-in-url",
        "prevention_count": 2,
        "last_prevented": "{iso-8601}"
      }
    ]

Context Synchronization Protocol

Real-time Context Updates

async def synchronize_context_with_claude_code():
    """
    Maintain real-time synchronization between BMAD context and Claude Code state
    """
    # Monitor Claude Code tool usage
    tool_monitor = await start_tool_usage_monitor()
    
    # Monitor file system changes
    file_monitor = await start_file_system_monitor()
    
    # Monitor git state changes
    git_monitor = await start_git_state_monitor()
    
    # Monitor todo list changes
    todo_monitor = await start_todo_monitor()
    
    async def update_context_from_claude_code():
        while True:
            # Detect Claude Code state changes
            state_changes = await detect_claude_code_changes([
                tool_monitor,
                file_monitor, 
                git_monitor,
                todo_monitor
            ])
            
            if state_changes:
                # Update global context
                updated_context = await update_global_context(state_changes)
                
                # Broadcast updates to all personas
                await broadcast_context_update(updated_context, state_changes)
                
                # Store context snapshot for recovery
                await store_context_snapshot(updated_context)
            
            await asyncio.sleep(0.1)  # 100ms polling interval
    
    # Start continuous synchronization
    await update_context_from_claude_code()

async def sync_decision_with_context(decision_data):
    """
    Synchronize persona decisions with global context
    """
    # Validate decision against current context
    validation_result = await validate_decision_against_context(
        decision_data,
        get_current_context()
    )
    
    if validation_result.conflicts:
        # Handle decision conflicts
        conflict_resolution = await resolve_decision_conflicts(
            decision_data,
            validation_result.conflicts
        )
        
        if conflict_resolution.requires_consultation:
            # Escalate to multi-persona consultation
            consultation_result = await initiate_consultation(
                conflict_resolution.stakeholders,
                decision_data
            )
            decision_data = consultation_result.resolved_decision
    
    # Update global context with validated decision
    updated_context = await add_decision_to_context(decision_data)
    
    # Notify affected personas
    affected_personas = identify_affected_personas(decision_data)
    await notify_personas_of_decision(affected_personas, decision_data)
    
    # Update Claude Code todos if decision creates new tasks
    if decision_data.creates_tasks:
        await update_claude_todos_from_decision(decision_data)
    
    return updated_context

Context Conflict Resolution

conflict_resolution:
  decision_conflicts:
    detection:
      - contradictory_decisions: "Two personas make opposing choices"
      - constraint_violations: "Decision violates established constraints"
      - dependency_conflicts: "Decision affects dependent components"
      
    resolution_strategies:
      - expertise_hierarchy: "Defer to domain expert"
      - stakeholder_consultation: "Get input from affected parties"
      - evidence_based_resolution: "Use data to resolve conflict"
      - compromise_solution: "Find middle ground approach"
      
  resource_conflicts:
    detection:
      - concurrent_file_edits: "Multiple personas editing same file"
      - tool_usage_conflicts: "Competing tool access needs"
      - timeline_conflicts: "Overlapping delivery schedules"
      
    resolution_mechanisms:
      - priority_based_scheduling: "High priority work gets precedence"
      - collaborative_editing: "Coordinate simultaneous work"
      - resource_pooling: "Share resources effectively"
      - sequential_processing: "Order conflicting operations"

Context-Aware Tool Enhancement

Smart Tool Selection Based on Context

async def enhance_claude_tools_with_context(tool_request, current_context):
    """
    Enhance Claude Code tool usage with BMAD context awareness
    """
    enhanced_request = {
        'original_request': tool_request,
        'context_enhancement': {},
        'recommendations': []
    }
    
    # Enhance Read operations with context
    if tool_request.tool == 'Read':
        file_context = await get_file_context(
            tool_request.target_file,
            current_context
        )
        
        enhanced_request['context_enhancement'] = {
            'file_history': file_context.modification_history,
            'related_decisions': file_context.related_decisions,
            'persona_annotations': file_context.persona_comments,
            'known_patterns': file_context.identified_patterns
        }
        
        enhanced_request['recommendations'] = [
            f"File last modified by {file_context.last_modifier}",
            f"Related to decisions: {file_context.related_decisions}",
            f"Known patterns: {file_context.identified_patterns}"
        ]
    
    # Enhance Write operations with context
    elif tool_request.tool == 'Write':
        write_context = await get_write_context(
            tool_request.target_file,
            current_context
        )
        
        enhanced_request['context_enhancement'] = {
            'affected_components': write_context.impact_analysis,
            'required_approvals': write_context.approval_requirements,
            'testing_implications': write_context.testing_needs,
            'documentation_updates': write_context.doc_updates_needed
        }
        
        # Automatically create todos for related tasks
        if write_context.creates_follow_up_tasks:
            follow_up_todos = await create_follow_up_todos(write_context)
            enhanced_request['auto_generated_todos'] = follow_up_todos
    
    # Enhance Grep operations with pattern intelligence
    elif tool_request.tool == 'Grep':
        pattern_context = await get_pattern_context(
            tool_request.search_pattern,
            current_context
        )
        
        enhanced_request['context_enhancement'] = {
            'related_patterns': pattern_context.similar_patterns,
            'anti_patterns': pattern_context.anti_patterns_to_avoid,
            'suggested_refinements': pattern_context.search_improvements
        }
    
    return enhanced_request

async def execute_context_aware_tool_operation(enhanced_request):
    """
    Execute tool operations with full context awareness
    """
    # Pre-execution context validation
    validation = await validate_operation_against_context(enhanced_request)
    
    if not validation.is_safe:
        return {
            'status': 'blocked',
            'reason': validation.blocking_issues,
            'suggestions': validation.alternative_approaches
        }
    
    # Execute with context monitoring
    execution_result = await execute_with_monitoring(enhanced_request)
    
    # Post-execution context update
    context_updates = await analyze_execution_impact(
        enhanced_request,
        execution_result
    )
    
    # Update global context
    await update_context_with_execution_results(context_updates)
    
    # Generate insights for future operations
    insights = await extract_insights_from_execution(
        enhanced_request,
        execution_result,
        context_updates
    )
    
    return {
        'execution_result': execution_result,
        'context_updates': context_updates,
        'learned_insights': insights,
        'status': 'completed'
    }

Context Persistence and Recovery

Context State Management

persistence_strategy:
  real_time_snapshots:
    frequency: "every_significant_change"
    triggers:
      - decision_made: "New decision recorded"
      - artifact_updated: "File modified or created"
      - task_status_change: "Todo status updated"
      - tool_usage: "Significant Claude Code tool operation"
      
  recovery_mechanisms:
    context_corruption:
      - rollback_to_snapshot: "Restore last known good state"
      - partial_reconstruction: "Rebuild from available data"
      - guided_recovery: "Ask user to confirm reconstructed state"
      
    session_interruption:
      - auto_save_state: "Continuous state preservation"
      - session_restoration: "Resume exactly where left off"
      - context_continuity: "Maintain persona awareness across sessions"

Cross-Session Context Continuity

async def restore_context_across_sessions(project_path):
    """
    Restore full context when returning to a project
    """
    # Load persisted context
    stored_context = await load_stored_context(project_path)
    
    # Analyze current state vs stored state
    current_state = await analyze_current_project_state(project_path)
    state_diff = await compare_states(stored_context, current_state)
    
    if state_diff.has_changes:
        # Context reconstruction needed
        reconstruction_plan = await create_reconstruction_plan(state_diff)
        
        # Apply automatic updates
        auto_updates = await apply_automatic_updates(reconstruction_plan)
        
        # Identify items needing manual review
        manual_review_items = reconstruction_plan.manual_review_needed
        
        if manual_review_items:
            # Present changes to user for confirmation
            user_confirmations = await request_user_confirmations(
                manual_review_items
            )
            await apply_user_confirmations(user_confirmations)
    
    # Restore persona states
    await restore_persona_states(stored_context.persona_states)
    
    # Re-establish tool monitoring
    await restart_context_synchronization()
    
    return {
        'context_restored': True,
        'automatic_updates': auto_updates,
        'manual_confirmations': len(manual_review_items) if manual_review_items else 0,
        'session_continuity': 'established'
    }

Context-Driven Recommendations

Intelligent Suggestions Based on Context

async def generate_context_driven_recommendations():
    """
    Generate intelligent recommendations based on current project context
    """
    current_context = await get_current_context()
    
    recommendations = {
        'immediate_actions': [],
        'optimization_opportunities': [],
        'risk_mitigations': [],
        'learning_applications': []
    }
    
    # Analyze for immediate action opportunities
    if current_context.has_pending_decisions:
        for decision in current_context.pending_decisions:
            recommendation = await generate_decision_recommendation(decision)
            recommendations['immediate_actions'].append(recommendation)
    
    # Identify optimization opportunities
    optimization_analysis = await analyze_optimization_opportunities(current_context)
    recommendations['optimization_opportunities'] = optimization_analysis
    
    # Assess risks and suggest mitigations
    risk_analysis = await assess_context_risks(current_context)
    recommendations['risk_mitigations'] = generate_risk_mitigations(risk_analysis)
    
    # Suggest applying learned patterns
    applicable_learning = await identify_applicable_learning(current_context)
    recommendations['learning_applications'] = applicable_learning
    
    return recommendations

Claude Code Integration Commands

# Context management commands
bmad context status --detailed
bmad context sync --force
bmad context restore --from-snapshot "2024-01-15T10:30:00Z"

# Context-aware operations
bmad context analyze --risks --opportunities
bmad context recommend --based-on "current-state"
bmad context validate --against-decisions

# Context sharing and collaboration
bmad context share --with-persona "architect" --scope "security-decisions"
bmad context merge --from-session "uuid" --resolve-conflicts
bmad context broadcast --update "new-security-requirements"

This Context Synchronizer transforms Claude Code into a context-aware development environment where every action is informed by the full project context, enabling more intelligent decision-making and seamless collaboration between AI personas.

15 KiB Raw Blame History